Module diagnostics

Expand description

Diagnostic-dump infrastructure shared by the solver and the CLI.

§Why this exists

Debugging a stalled solve or a perf regression usually means capturing the inner state of the IPM at specific iterations: the augmented-system KKT matrix, the iterate, the search step, the line-search trace. Historically this lived as a scatter of POUNCE_DBG_* env-vars across the codebase, each with bespoke semantics. This module centralizes the surface so the CLI (--dump kkt:5-10) and the dump sites (deep in the linear solver) speak the same vocabulary.

§Lifecycle

The CLI parses --dump <cat>[:<spec>] flags into a DiagnosticsConfig and constructs a DiagnosticsState.
The application installs the state via IpoptApplication::set_diagnostics, then propagates an Rc<DiagnosticsState> through the solve in the same way crate::timing::TimingStatistics is propagated.
At the top of each outer iteration, the IPM calls DiagnosticsState::bump_iter to advance the current-iter counter and reset the per-iter solve index.
Every dump site (KKT solver, line search, μ oracle, …) calls DiagnosticsState::want to gate the dump, then DiagnosticsState::open_writer to obtain a file handle in the right iter_NNN/ sub-directory.

§File layout

<dump_dir>/
  manifest.json
  iter_005/
    kkt_solve_001.jsonl
    iterate.json
  iter_006/...
  resto/
    parent_iter_007/
      iter_000/kkt_solve_001.jsonl
  timing.json

The solve_NNN suffix disambiguates the multi-solve-per-iter case (second-order corrections and perturbation re-solves issue extra factorizations inside one outer iteration). The resto/parent_iter_NNN/ hierarchy keeps the restoration sub-IPM trace separate from the main solve trace.

Structs§

DiagnosticsConfig: Static configuration: where to dump, in what format, with what per-category iter filters. Constructed by the CLI, held by the application, frozen for the duration of a solve.
DiagnosticsState: Live state threaded through the solve via Rc. The IPM mutates current_iter and solves_this_iter; the dump sites read them. All fields use atomics so the type is Send + Sync even though the solver itself is single-threaded — keeps the door open for future parallel inner solvers without an ABI rewrite.

Enums§

DiagCategory: Single diagnostic category the user can request.
DumpFormat
IterSpec: Iteration filter attached to a category. None endpoints denote open-ended ranges (N- is Range(Some(N), None)).
IterateVariant: Payload-detail variant for the iterate dump category.
KktVariant: Payload-detail variant for the kkt dump category.

Functions§

parse_iterate_spec: Parse the iterate: spec grammar — [<iter-filter>[:<variant>]].
parse_kkt_spec: Parse the kkt: spec grammar — [<iter-filter>][+L][+Lvals].