Performance and Profiling Configuration

Runtime

YAML path	Type	Default	Allowed values	Meaning
`runtime.print_thread_config`	Bool	`true`	`true`, `false`	Print Julia/BLAS thread summary at startup (now including a `parallel: enabled=... max_tasks=...` line).
`runtime.julia_threads`	String	`keep`	`keep`, `default`, `off`, `auto`, or integer-like string	Julia thread policy for runner setup. Requires process startup (`--threads`) or script re-exec.
`runtime.blas_threads`	String	`keep`	`keep`, `default`, `off`, `auto`, or integer-like string	BLAS thread policy for runner setup and can be applied at runtime.
`runtime.parallel.enabled`	Bool	`true`	`true`, `false`	Master switch for in-process parallel execution of independent work items (island solves, short-circuit sweeps, contingency batches). `false` forces every parallel site onto the serial path (the same functions, not copies).
`runtime.parallel.max_tasks`	String	`auto`	`auto` or positive integer string	Task cap for parallel sites. `auto` resolves to `Threads.nthreads()`; the cap is applied via chunking, so it also bounds `@threads` sites.
`runtime.parallel.min_work_items`	Int	`4`	integer >= 1	Work lists shorter than this run serially (avoids task overhead on tiny cases).

With runtime.parallel.enabled: true and a single-threaded Julia process the parallel sites still run serially; the startup summary prints a once-per-process hint to start with julia --threads=auto.

Timing semantics under parallel execution: the per-phase timings in the performance profile (and performance.log) are CPU-time SUMS across all islands/workers, exactly as the serial loop accumulated them, so phase names and their meaning do not change between serial and parallel runs. The elapsed real time of a parallel fan-out is accounted separately under parallel_wall_time; on a parallel run it is smaller than the sum of the per-island phase times, and the ratio is the achieved speedup.

For examples/powerflow/matpower_import.jl, Julia thread priority is:

CLI override: --julia-threads=<N|auto|keep>
Environment override: SPARLECTRA_JULIA_THREADS
YAML runtime.julia_threads
keep current process setting

Example startup commands:

julia --threads=8 --project=. examples/powerflow/matpower_import.jl
julia --project=. examples/powerflow/matpower_import.jl --julia-threads=8

$env:JULIA_NUM_THREADS = "8"
julia --project=. examples/powerflow/matpower_import.jl

Output configuration

YAML path	Type	Default	Allowed values	Meaning
`output.console_summary`	Bool	`true`	`true`, `false`	Print compact run summary to console.
`output.console_auto_profile`	Symbol/String	`compact`	`off`, `compact`, `full`	MATPOWER auto-profile console detail.
`output.console_diagnostics`	Symbol/String	`compact`	`off`, `compact`, `summary`, `full`	Diagnostic detail on console.
`output.console_q_limit_events`	Symbol/String	`summary`	`off`, `summary`, `full`	Q-limit/PV→PQ event console detail.
`output.console_max_rows`	Int	`100`	non-negative integer	Max rows in compact console tables.
`output.logfile_results`	Symbol/String	`off`	`off`, `compact`, `classic`, `full`	Solved result table detail in logfile.
`output.detailed_result_csv_write_mode`	Symbol/String	`auto`	`auto`, `buffered`, `streaming`	Detailed CSV artifact write strategy; `auto` streams very large outputs.
`output.detailed_result_csv_exporter`	Symbol/String	`auto`	`auto`, `report`, `direct`	Detailed CSV row-generation path; `auto` uses the direct streaming exporter for large bus counts.
`output.detailed_result_csv_direct_threshold_buses`	Int	`10000`	positive integer	Bus-count threshold where `auto` switches detailed CSV export from report generation to direct streaming.
`output.detailed_result_csv_buffer_initial_bytes`	Int	`8388608`	non-negative integer	Initial size hint for buffered detailed CSV artifact writing.
`output.detailed_result_csv_buffer_max_bytes`	Int	`67108864`	positive integer	Cheap estimated-size limit above which `auto` prefers streaming.
`output.detailed_result_csv_streaming_threshold_rows`	Int	`100000`	positive integer	Row-count threshold above which `auto` prefers streaming.
`output.logfile_diagnostics`	Symbol/String	`compact`	`off`, `compact`, `full`	Diagnostic logfile detail.
`output.logfile_performance`	Symbol/String	`compact`	`off`, `compact`, `full`	Performance profile logfile detail.
`output.logfile_warnings`	Symbol/String	`table`	`off`, `summary`, `table`, `full`	Warning representation in logfile.

The Jacobian cond. line (estimate plus verdict) is always part of the classic result output since 0.9.7; the former output.condition_number option no longer exists, and a leftover condition_number key in an existing YAML file is ignored. See Solver.

For API and Web UI runs, classic writes the standard result output and a compact timing/status summary. full additionally writes a Full run details section with effective typed configuration, selected artifact options, and available status diagnostics. The summary reports solver_time, representative_time, iterations, final mismatch, and final outcome where available; benchmark median and samples appear only when benchmark mode is enabled.

Diagnostics configuration

YAML path	Type	Default	Allowed values	Meaning	Cost notes
`diagnostics.log_effective_config`	Bool	`false`	`true`, `false`	Log merged effective configuration.	true: low
`diagnostics.console_summary`	Bool	`true`	`true`, `false`	Emit compact run summary to console.	true: low
`diagnostics.console_auto_profile`	Symbol/String	`compact`	`off`, `compact`, `full`	Auto-profile detail on console.	`full`: medium
`diagnostics.console_diagnostics`	Symbol/String	`compact`	`off`, `compact`, `summary`, `full`	Solver diagnostics detail on console.	`full`: medium/high
`diagnostics.console_q_limit_events`	Symbol/String	`summary`	`off`, `summary`, `full`	PV→PQ event verbosity on console.	`full`: medium
`diagnostics.console_max_rows`	Int	`100`	non-negative integer	Row cap for console diagnostics tables.	low
`diagnostics.logfile_diagnostics`	Symbol/String	`compact`	`off`, `compact`, `full`	Diagnostic logfile detail level.	`full`: medium/high

Performance configuration

YAML path	Type	Default	Allowed values	Meaning
`performance.enabled`	Bool	`true`	`true`, `false`	Enable performance instrumentation.
`performance.level`	Symbol/String	`iteration`	`off`, `summary`, `iteration`, `full`	Instrumentation detail level.
`performance.print_to_console`	Bool	`true`	`true`, `false`	Emit performance output to console.
`performance.write_to_logfile`	Bool	`true`	`true`, `false`	Emit performance output to logfile.
`performance.show_allocations`	Bool	`false`	`true`, `false`	Include allocation stats.
`performance.show_iteration_table`	Bool	`true`	`true`, `false`	Show iteration-level timing table.
`performance.compact_logging`	Bool	`true`	`true`, `false`	Compact performance logging format.
`performance.skip_reference_comparison`	Bool	`false`	`true`, `false`	Skip voltage/reference comparisons for speed.
`performance.skip_expensive_diagnostics`	Bool	`true`	`true`, `false`	Skip high-cost diagnostics.
`performance.skip_branch_neighborhood_report`	Bool	`true`	`true`, `false`	Skip branch neighborhood report.
`performance.max_diagnostic_rows`	Int	`25`	non-negative integer	Row cap for diagnostics tables.

Benchmark configuration

The Web UI's performance_timing=off|compact|full option is separate from the benchmark configuration. It writes performance.log for phases of one service/API request, such as request parsing, case resolution, configuration, case loading/network construction/solve, postprocessing, artifact writing, and total time. full includes available internal profile entries. In contrast, benchmark.enabled performs repeated solves and reports representative and median timing. Tests assert phase names and artifact presence, not fragile time thresholds.

YAML path	Type	Default	Allowed values	Meaning
`benchmark.enabled`	Bool	`true`	`true`, `false`	Enable benchmark mode.
`benchmark.methods`	Vector{Symbol/String}	`[rectangular]`	`rectangular` (current PF core)	Methods benchmarked.
`benchmark.seconds`	Float64	`2.0`	positive real	Benchmark max. time budget. This is not a minimum runtime, solver timeout, or iteration limit; a running sample is not interrupted.
`benchmark.samples`	Int	`50`	positive integer	Max benchmark samples per method. The benchmark may finish earlier when this count is reached before the time budget, or collect fewer samples when the time budget is reached first.
`benchmark.show_once`	Bool	`false`	`true`, `false`	Run one full visible solve before timing loop.
`benchmark.show_once_output`	Symbol/String	`classic`	`classic`, `dataframe`, `compact`	Output format for `show_once`.
`benchmark.show_once_max_nodes`	Int	`0`	non-negative integer	Row cap for one-shot output.

Solver workspace and warmup keys

Performance-relevant keys that live outside the performance.* section proper:

Key	Default	Meaning
`power_flow.rectangular_workspace_reuse`	`true`	Reuse the rectangular solver's workspace between solves of one session instead of reallocating.
`power_flow.rectangular_preallocate_workspace`	`auto`	Preallocate the workspace up front (`off`, `on`, `auto`; `auto` decides by case size).
`power_flow.rectangular_workspace_min_buses`	`1000`	Case size from which `auto` preallocates.
`performance.representative_warmup_runs`	`0`	Untimed warmup solves before a timed representative run.
`performance.compare_cold_warm`	`false`	Report the cold (first) and warm (subsequent) timings side by side.