GUIBRUSHR.Retrieval.debug_log module

Shared JSONL debug logger for the Retrieval pipeline.

Used by both ExofastMCMC.exofast_demc (parent MCMC driver) and ModelCalculation.ModelData.parallel_chain (parallel workers) so that high-level events (setup, convergence, finalization) and low-level events (per-core proposal / accept / chain_end) land in a single chronologically ordered file suitable for offline analysis.

Concurrency

Multiprocessing workers append independently. Under POSIX a single write() call whose buffer is smaller than PIPE_BUF (4096 B on Linux) is atomic — so by keeping each JSON line under ~3800 bytes we avoid interleaved writes without any lock.

Robustness

emit_event never raises: a broken logger must never kill the MCMC.

GUIBRUSHR.Retrieval.debug_log.get_log_path(model_obj)

Return the JSONL debug file path for this retrieval, or None.

Parameters:

model_obj – any object exposing retrieval_data.path_results.

Returns:

pathlib.Path or None.

GUIBRUSHR.Retrieval.debug_log.init_log(path, header)

Create the parent dir, truncate the file, write a header line.

GUIBRUSHR.Retrieval.debug_log.emit_event(path, record)

Append one JSON line to path atomically (POSIX, <3800 B).

Parameters:

• path – str/Path of the JSONL log file, or None to disable.

• record – dict to serialize. ‘ts’ and ‘pid’ auto-filled if missing.

class GUIBRUSHR.Retrieval.debug_log.BufferedLogger

Bases: object

In-memory batch of JSON events, flushed on demand.

Use this to decouple emit frequency from disk I/O: the parent MCMC driver accumulates events during a burnin block and flushes once at the distribution-save checkpoint (every 10 outer_steps). Workers use a short-lived instance and flush once before exiting their outer_step.

Thread/process safety

Not shared across processes. Each process owns its own buffer. The single flush call is one write() per line under open(..., "a"), so the POSIX <PIPE_BUF atomicity guarantee still holds line-by-line — workers flushing concurrently with the parent do not interleave within a line.

__init__()

emit(record)

Append a record to the in-memory buffer. Never raises.

flush(path)

Write all buffered lines to path (append mode) and clear.

If path is None or the write fails, the buffer is cleared anyway to prevent unbounded memory growth on long runs.