vibeqc.ProgressLogger

class vibeqc.ProgressLogger(stream=None, log_path=None, verbose=4, use_logging=False)

Bases: object

Per-stage progress emitter for long-running calculations.

Writes plain-ASCII, line-flushed output to stream (default sys.stdout) and, optionally, to log_path (truncated on construction, appended-and-flushed thereafter). Every write goes through flush() immediately so tail -f against a redirected stdout shows the run unfolding in real time.

Parameters:

• stream (Optional[IO[str]]) – Where to write live progress. Default sys.stdout. Ignored when use_logging=True.

• log_path (Optional[Union[str, os.PathLike]]) – Optional path. Truncated on construction; appended-to with a flush after each write. Useful when callers want both an interactive stdout view and a persistent on-disk record. Honored regardless of use_logging.

• verbose (Union[int, bool, None]) – Integer verbosity level (0..9, default 4). Higher values add more detail; level 0 makes every method a no-op. The level table is in the module docstring. True / False are accepted for back-compat (True → 4, False → 0).

• use_logging (bool) – If True, route emits through logging.getLogger( "vibeqc.run_job") instead of the stream. Composes with stdlib handlers (rotating files, syslog, dictConfig) — no special integration required. The log_path tee still applies if set.

Notes

The current implementation deliberately stays plain ASCII — the goal is the nohup + tail -f workflow, where color codes would only inject control bytes that no log viewer asked for. TTY detection is exposed via is_tty for downstream tooling that wants to layer color or progress bars on top.

__init__(stream=None, log_path=None, verbose=4, use_logging=False)

Parameters:

• stream (IO[str] | None)

• log_path (str | PathLike | None)

• verbose (int | bool | None)

• use_logging (bool)

Return type:

None

Methods

__init__([stream, log_path, verbose, ...])
banner(title)	Section banner: blank line + indented title + dashed rule.
converged(*, n_iter, energy, converged)	Final SCF status line; called once after the iteration loop.
debug(message)	Phase-level wall-clock breakdown / debug detail.
info(message)	Emit a one-line informational message, indented.
iteration(n, **fields)	One SCF iteration line.
memory(label, rss_mib)	Inline RSS-memory snapshot.
stage(name, *[, detail])	Context manager: emit [name] on enter, [name] done (X.XXs) on exit — regardless of which branch ran inside.
warn(message)	Emit a one-line warning, prefixed with WARN:.
write_raw(text)	Write text exactly as given (newlines preserved), with a single flush.

Attributes

enabled	True iff level is non-zero (i.e. anything emits).
is_tty	Whether the underlying stream is a TTY.
level	The integer verbosity level this logger was constructed with (0..9).
stream
use_logging	Whether emits route through logging (True) or the raw stream (False).

info(message)

Emit a one-line informational message, indented.

Visible at verbose level 2 and above.

Parameters:

message (str)

Return type:

None

warn(message)

Emit a one-line warning, prefixed with WARN:.

Visible at verbose level 1 and above (warnings should not be hidden by quiet runs short of full silence).

Parameters:

message (str)

Return type:

None

banner(title)

Section banner: blank line + indented title + dashed rule.

Visible at verbose level 1 and above. Under use_logging the three lines emit as three INFO records.

Parameters:

title (str)

Return type:

None

write_raw(text)

Write text exactly as given (newlines preserved), with a single flush. Used by callers that want to splice in a pre-formatted block (e.g. the geometry table from vibeqc.scf_log).

Visible at verbose level 2 and above.

Parameters:

text (str)

Return type:

None

stage(name, *, detail=None)

Context manager: emit [name] on enter, [name] done (X.XXs) on exit — regardless of which branch ran inside.

The start line emits at verbose level 2; the timing done line emits at level 3 (so verbose=2 shows which stages ran but suppresses per-stage wall-time noise, and verbose>=3 adds the timing detail).

Parameters:

• name (str) – Short stage identifier (printed in brackets).

• detail (str | None) – Optional one-line addendum appended to the start line (e.g. "4x4x4 -> 8 IBZ k-points").

Return type:

Iterator[None]

iteration(n, **fields)

One SCF iteration line.

Recognized fields: energy (Ha), dE (Ha), grad (||[F,DS]||), diis (subspace dim). Any other key/value pair is appended at the end. Wall time since logger construction is appended automatically.

At n == 1, dE is rendered as a placeholder -- so the column layout matches vibeqc.scf_log.format_scf_trace().

Visible at verbose level 4 and above. Under use_logging emits at DEBUG (per-iter detail belongs below INFO so logging.basicConfig(level=INFO) keeps a quiet stream while level=DEBUG exposes the trace).

Parameters:

• n (int)

• fields (Any)

Return type:

None

converged(*, n_iter, energy, converged)

Final SCF status line; called once after the iteration loop.

Visible at verbose level 1 and above (the final summary is almost always wanted — only a fully silent verbose=0 suppresses it).

Parameters:

• n_iter (int)

• energy (float)

• converged (bool)

Return type:

None

memory(label, rss_mib)

Inline RSS-memory snapshot.

Visible at verbose level 5 and above. Pairs with the post-mortem .perf log’s Memory snapshots section — same data, but live.

Parameters:

• label (str)

• rss_mib (float)

Return type:

None

debug(message)

Phase-level wall-clock breakdown / debug detail.

Visible at verbose level 6 and above. Overlaps the post-mortem .perf log on purpose — the perf log shows the same numbers when the run is over; verbose>=6 streams them live for users debugging an in-flight job. Under use_logging emits at DEBUG so a stdlib RotatingFileHandler set to DEBUG captures the trace without lifting the bar for INFO-only handlers.

Parameters:

message (str)

Return type:

None

property enabled: bool

True iff level is non-zero (i.e. anything emits). Kept as the legacy alias for verbose=True/False callers that predate the integer level.

property level: int

The integer verbosity level this logger was constructed with (0..9).

property use_logging: bool

Whether emits route through logging (True) or the raw stream (False).

property stream: IO[str]

property is_tty: bool

Whether the underlying stream is a TTY. Useful for callers that want to layer color / spinners over the plain output.