Core Diagnostics

POLARIS can emit a set of “core diagnostic” files that describe how the simulation engine spent its time and memory. These are the primary tools for spotting performance problems such as thread starvation (see Threading Performance and agents_per_block) or unexpected memory growth (see Memory Usage).

The files

File	When it is written	Contents
core_diag.json	Always, at the end of every run (from World::Stop_Turning)	End-of-run summary: per-thread step/wait time, threading utilisation, and per-manager block/object hit-rates
core.memory.csv	Only with --dump_core_diagnostics N	Per-manager memory snapshot, appended every N iterations
core.timing.csv	Only with --dump_core_diagnostics N --dump_core_diagnostics_timing	Per-manager cumulative step timing, appended every N iterations

All files are written to the run’s output directory. The formatters live in libs/core/Core_Diagnostics.cpp.

core_diag.json is always produced

Unlike the CSVs, the end-of-run core_diag.json summary is written on every run and requires no flags. It is the quickest place to look for a threading bottleneck. A condensed one-line version is also written to the log at the end of the run, e.g.:

[NOTICE] Threading efficiency:  93.3% utilisation (6.7% wait) across 8 threads

The JSON itself carries the per-thread breakdown. step_ms is time spent doing useful work, wait_ms is time spent idle at the thread gates waiting for other threads, and wait_pct is the idle fraction. total_wait_pct aggregates across the pool:

{
    "num_threads": 8,
    "threads": [
        { "id": 0, "step_ms": 240.1, "wait_ms": 21.3, "wait_pct": 8.2 }
    ],
    "total_wait_pct": 8.1
}

Producing the per-iteration CSVs

The core.memory.csv and core.timing.csv files are opt-in because they are appended to throughout the run. Enable them from the command line:

# memory snapshot every 60 iterations
./Integrated_Model --dump_core_diagnostics 60

# also capture per-manager step timing
./Integrated_Model --dump_core_diagnostics 60 --dump_core_diagnostics_timing

N controls how often (in iterations) a row is appended; smaller values give finer resolution at the cost of larger files.

Analysing the output

For a worked example of loading these files (core.memory.csv, core.timing.csv, and core_diag.json) from Python, see the polaris-studio Examining Memory and Timing example. The Threading Performance and agents_per_block and Memory Usage sections walk through what the resulting plots tell you.