neuralqx.utils.io.loggers.logger module

escape_html(text)

Helper to escape HTML characters.

Return type:

Any

format_value(value)

Format the value, escaping special characters.

Return type:

Any

dict_to_html(data_dict, *, meta=None)

Return type:

str

class Logger(random_seed, solver_seed)

Bases: AbstractLogger

Structured logger for neuraLQX solver executions.

This class collects, organizes, and manages simulation metadata, configuration parameters, and numerical results produced during solver runs. Logged data is stored in a hierarchical dictionary structure with predefined categories that can be extended dynamically at runtime.

The logger supports:

• Incremental logging of scalar and structured values

• Runtime extension of log fields

• Recursive sanitisation of unset entries

• Human-readable display using Rich panels

• Persistent export to a signed HTML file

The logger is distributed-aware: all logging, display, and file output operations are performed exclusively on process 0 to avoid duplicated output.

add_field(parent_key, new_field_key)

Add a new logging field under an existing parent log category.

This method allows the log schema to be extended dynamically at runtime by inserting a new field initialised with a null value. The field becomes available for subsequent logging operations.

Parameters:

• parent_key (str) – The name of the parent log category to extend.

• new_field_key (str) – The name of the new field to add under the parent category.

Raises:

KeyError – If the specified parent category does not exist in the log.

Return type:

None

log(field_key, value)

Record one or more values in the log.

This method assigns values to existing log fields. It supports both single key-value logging and batch logging by providing lists of field keys and corresponding values.

Parameters:

• field_key (str | list[str]) – The field name(s) to which values should be logged.

• value (Any | list[Any]) – The value(s) to associate with the specified field(s).

Raises:

• KeyError – If a specified field does not exist in the log.

• ValueError – If lists are provided with mismatched lengths or incompatible types.

Return type:

None

get_log()

Retrieve the complete structured log.

Return type:

dict

Returns:

The full hierarchical log dictionary, including all parent categories and their associated fields.

get_value_of(key)

Retrieve the value associated with a given log key.

If the key corresponds to a parent category, the entire sub-dictionary is returned. If the key corresponds to a leaf field, only its value is returned.

Parameters:

key (str) – The name of a log field or parent category.

Return type:

Any

Returns:

The requested value or sub-log.

Raises:

KeyError – If the key does not exist anywhere in the log.

write_log_to_file(path)

Export the current log to a signed HTML file on disk.

The log is sanitized before export, rendered into a human-readable HTML document, cryptographically signed, and written to the specified directory. The output file name includes the random seed and a timestamp.

This operation is performed only on the global master process.

Parameters:

path (str) – Directory where the HTML log file should be written.

Return type:

None

display_log()

Display the current log in a formatted Rich panel.

The log is sanitized prior to display and rendered as a nested table structure for interactive inspection in the console.

This operation is performed only on the global master process.

Return type:

None

sanitize(log_dict)

Recursively remove unset entries from a log dictionary.

This method traverses the provided dictionary and removes any key-value pairs where the value is None. Nested dictionaries are cleaned recursively and removed entirely if empty.

Parameters:

log_dict (dict) – A log dictionary to sanitize.

Return type:

dict

Returns:

A cleaned version of the input dictionary containing only populated entries.

erase_parent_content(parent)

Clear all logged values under a specified parent category.

Fields that were part of the original log schema are reset to None, while fields added dynamically at runtime are removed entirely.

Parameters:

parent (str) – The name of the parent log category to clear.

Raises:

KeyError – If the specified parent category does not exist.

Return type:

None