neuralqx.debug module

neuralQX debugging module.

Usage (decorate)

from neuralqx.debugging import trace, timeit, errors_only, io_trace

@trace(tag=”SAMPLER”) def sample(…): …

@timeit(tag=”LANCZOS”, warn_ms=250) def lanczos_step(…): …

@errors_only(tag=”IO”) def load_checkpoint(…): …

@io_trace(tag=”KERNEL”) def _get_conn_flattened_kernel(…): …

initialise(*, force=False)

Initialise neuralQX debugging for this process.

  • Creates per-session log file under cfg.get_static(“Leach Directory”) when enabled.

  • Installs exception / warning / faulthandler hooks (best-effort).

  • Safe to call multiple times.

Returns the logfile path if created, else None.

Return type:

Optional[Path]

refresh_settings(*, reinit=False)

Refresh settings from cfg. If reinit=True, rebuilds the log file/handlers.

Return type:

None

is_enabled()
Return type:

bool

get_logfile()
Return type:

Optional[Path]

trace(_fn=None, *, tag=None, log_args_at=50, log_return_at=10, warn_slow_ms=500.0, reraise=True)

Full-spectrum instrumentation.

Emission policy (when NQX_DEBUG=True): - INFO: entry log (function called, caller site, call id) - DEBUG: exit log (ok, duration, optional return summary) - WARNING: if warn_slow_ms is set, logs WARNING when duration exceeds threshold - ERROR: logs exception with traceback (always, regardless of configured verbosity filter) - CRITICAL: includes args/kwargs summary (bounded) and richer diagnostics

Return type:

Union[Callable[..., TypeVar(_T)], Callable[[Callable[..., TypeVar(_T)]], Callable[..., TypeVar(_T)]]]

The “tag” prefix is rendered as:

[TAG] :: message

timeit(_fn=None, *, tag=None, warn_ms=250.0, level=10)

Lightweight timing decorator. - logs one line with duration at level (default DEBUG) - logs WARNING if exceeds warn_ms (when warn_ms is not None)

Return type:

Union[Callable[..., TypeVar(_T)], Callable[[Callable[..., TypeVar(_T)]], Callable[..., TypeVar(_T)]]]

errors_only(_fn=None, *, tag=None, reraise=True)

Ultra-light decorator that only logs exceptions (plus traceback when verbosity allows).

Return type:

Union[Callable[..., TypeVar(_T)], Callable[[Callable[..., TypeVar(_T)]], Callable[..., TypeVar(_T)]]]

io_trace(_fn=None, *, tag=None, at_level=10)

IO-focused decorator: logs summarised input/output (shapes/dtypes for arrays) at at_level.

Typical use is for kernels / NetKet operator connections where we need shapes but not full tensors.

Return type:

Union[Callable[..., TypeVar(_T)], Callable[[Callable[..., TypeVar(_T)]], Callable[..., TypeVar(_T)]]]

event(msg, *, tag=None, level=20, **fields)

Structured-ish event log with key=value fields.

Return type:

None

log_once(level, key, msg, *, tag=None)

Log a message only once per process (per key).

Return type:

None

dump_recent_events(*, n=200, tag='DUMP')

Log the last N buffered events into the log (useful at high severity).

Return type:

None

dump_stacks(*, tag='STACKS')

Dump all thread stacks to the log.

Return type:

None

tagged(tag)

Temporarily set a default tag for warnings/context (does not override decorator tag).