ptyrad.runtime.logging

PtyRAD logging and diagnostic report function.

This module provides a robust logging architecture designed to handle both interactive notebook environments and distributed, multi-GPU training jobs. It features a buffering system to capture early logs before the output directory is known, a rank-zero filter to prevent duplicated logs in distributed runs, and a foolproof report function to guarantee critical diagnostics are always visible to the user even a logger is not initialized.

Functions

get_logging_manager()	Retrieves the currently active logging manager instance.
report(message[, verbosity])	Dual-purpose logging and printing function for critical diagnostics.

Classes

LoggingManager([log_file, log_dir, ...])	Configures and manages the central PtyRAD logging hierarchy.
RankZeroFilter([name])	A logging filter that restricts output to the primary distributed process.

ptyrad.runtime.logging.report(message, verbosity='INFO')

Dual-purpose logging and printing function for critical diagnostics.

This function attempts to emit the message through the standard PtyRAD logging hierarchy. However, if the logger has not been initialized (no handlers exist) or if the user has set the global logging level higher than the message’s severity, it falls back to a standard Python print(). This ensures vital system information (like GPU errors or missing dependencies) always reaches the user.

Parameters:

• message (str) – The diagnostic message to output.

• verbosity (Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'], optional) – The logging severity level. Defaults to ‘INFO’.

ptyrad.runtime.logging.get_logging_manager()

Retrieves the currently active logging manager instance.

Returns:

The globally active LoggingManager instance, or None if logging has not yet been initialized.

Return type:

LoggingManager or None

class ptyrad.runtime.logging.RankZeroFilter(name='')

Bases: Filter

A logging filter that restricts output to the primary distributed process.

In a multi-GPU environment (e.g., via PyTorch DistributedDataParallel), multiple processes run the same script. This filter prevents duplicated console output and file writes by ensuring only the rank 0 process is allowed to emit log records.

filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

class ptyrad.runtime.logging.LoggingManager(log_file='ptyrad_log.txt', log_dir='auto', prefix_time='datetime', prefix_date=None, prefix_jobid=0, append_to_file=True, show_timestamp=True, show_config=True, verbosity='DEBUG', **kwargs)

Bases: object

Configures and manages the central PtyRAD logging hierarchy.

This manager initializes console and in-memory buffered handlers upon creation. The buffer captures all logs generated during early initialization and parameter loading. Once the final output directory is determined by the reconstruction loop, flush_to_file is called to dump the buffer to disk and seamlessly transition to standard file-based logging.

Parameters:

verbosity (Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'])

flush_to_file(log_dir=None, append_to_file=None)

Flushes buffered logs to a file based on user-defined file mode (append or write)

close()

Closes the file handler if it exists.