torchref.refinement.logger module

Refinement Logger - Separate logging concerns from refinement logic.

Provides verbosity-aware statistics recording and comparison for refinement workflows. Integrates with LossState to capture and display refinement progress.

class torchref.refinement.logger.Logger(state, verbose=1, pattern='.*', _records=<factory>, _labels=<factory>)

Bases: object

Refinement logging with verbosity-aware stat reporting.

Integrates with LossState to record, compare, and display refinement stats. Supports regex-based filtering of target names.

Parameters:

• state (LossState) – The loss state to monitor.

• verbose (int) – Verbosity level (0=essential, 1=standard, 2=detailed, 3=debug).

• pattern (str) – Regex pattern for filtering target names. Default “.*” matches all. Examples: “xray.*” for X-ray targets only, “geometry/bond” for specific target.

Examples

Basic usage:

from torchref.refinement import LossState, Logger

state = LossState(device=device)
state.register_target("xray/work", xray_target)
state.register_target("geometry/bond", bond_target)

logger = Logger(state, verbose=1)

# Record before refinement
logger.record(label="before_xyz")

# ... run refinement ...

# Record after and compare
logger.record(label="after_xyz")
logger.compare(title="XYZ Refinement")

Filtering by pattern:

# Show only X-ray targets
logger.current(pattern="xray.*")

# Create a logger that only tracks geometry
geom_logger = Logger(state, pattern="geometry.*")

state: LossState

verbose: int = 1

pattern: str = '.*'

record(label=None)

Record current refinement state.

Gathers stats from all targets in LossState, stores in history. Uses the instance’s pattern filter.

Parameters:

label (str, optional) – Label for this record (e.g., “before_xyz”, “after_xyz”).

Returns:

The recorded stats dictionary.

Return type:

dict

compare(label_before=None, label_after=None, pattern=None, title='Refinement Comparison')

Print comparison between two recorded states.

If labels not provided, compares last two records.

Parameters:

• label_before (str, optional) – Label of “before” state. Default: second-to-last record.

• label_after (str, optional) – Label of “after” state. Default: last record.

• pattern (str, optional) – Regex to filter which targets to display. Default: use instance pattern.

• title (str, optional) – Title for the comparison output. Default: “Refinement Comparison”.

current(pattern=None, title='Current State')

Print the current refinement state.

Uses latest recorded state, or records new one if none exist.

Parameters:

• pattern (str, optional) – Regex to filter which targets to display. Default: use instance pattern.

• title (str, optional) – Title for the output. Default: “Current State”.

get_record(label)

Get a specific recorded state by label.

Parameters:

label (str) – The label to look up.

Returns:

The recorded stats dictionary, or None if label not found.

Return type:

dict or None

clear()

Clear all recorded history.

property history: List[Dict[str, Any]]

Access full recording history.

__init__(state, verbose=1, pattern='.*', _records=<factory>, _labels=<factory>)