Spectral `App` configuration reference (JSON / TOML)¶

This page lists the JSON / TOML surface consumed by the default CPU spectral stack (SimulationSession<SpectralCPUStack> / ETD sessions) for shipped apps (apps/tungsten, apps/aluminumNew). Apps may add keys or nest objects; treat shipped inputs as ground truth when in doubt.

Pipeline order: app_pipeline.md. Mental model: configuration.md.

Domain (grid)¶

Parsed by from_json<Domain>(settings) from the "domain" object. The domain is the box itself:

Key	Type	Meaning
`size`	3 positive integers	Grid points per axis
`lower`	3 finite numbers	Lower limit of the box; index `(0,0,0)` sits here
`upper`	3 finite numbers	Upper limit of the box, above `lower` on every axis

"domain": {"size": [256, 256, 256],
           "lower": [-142.2, -142.2, -142.2],
           "upper": [142.2, 142.2, 142.2]}

Every axis is periodic, so the spacing is (upper - lower) / size and upper is the periodic image of lower, not a stored point. Index i sits at lower + i * spacing. Place a seed in the middle of the box by making the box symmetric and putting the seed at (0, 0, 0).

The earlier keys Lx/Ly/Lz, dx/dy/dz and origin/origo were removed; an input that uses them fails with the equivalent block in the message. scripts/migrate_domain_block.py FILE... rewrites JSON and TOML inputs in place and keeps the grid bit for bit.

Time stepping¶

Parsed by from_json<Time>(settings) — supports flat keys or nested under "timestepping".

Key	Type	Meaning
`t0`, `t1`	number	Integration window
`dt`	number	Step size
`saveat`	number	Output cadence (also gates binary writers in JSON wiring; `≤ 0` disables periodic result writes in the default helper)
`timestepping.integrator.method`	string	Optional. `euler`, `rk2_midpoint`, `rk2_heun`, `rk4_classical`, `bogacki_shampine32`, `imex_euler`, `etd1`. Defaults to `euler`. IMEX/ETD tokens are identity on `Time` (no RK tableau).

FFT (`plan_options`)¶

Object key "plan_options" (JSON) or [plan_options] (TOML). Passed to HeFFTe plan construction on the CPU spectral path (SpectralCPUStack) and on GPU spectral sessions (GPUSpectralStack via create_cuda / create_hip). backend: "cuda" is rejected for SpectralCPUStack / CPUFFT — use CPU fftw there, or a GPU session (tungsten_cuda, aluminum_etd_cuda, session-matrix GPU JSON). GPU overlays start from cuFFT / rocFFT defaults and apply the same reshape / pencil / GPU-aware keys.

Annotated reference file: examples/fft_backend_selection.toml. Tutorial: tutorials/fft_heffte_plan_options.md.

Model¶

Key	Type	Meaning
`model.name`	string	Conventionally matches the app’s model registration
`model.params`	object	Model-specific; optional `from_json` into your C++ params type

Validation is model-dependent (see parameter_validation.md).

Tungsten (apps/tungsten) accepts optional thermal-drive keys on model.params. Omitting them is the isothermal 0.2.0 case (CPU goldens unchanged):

Key	Type	Meaning
`G_grid`	number	Thermal gradient along x. Default `0` (no T_var).
`V_grid`	number	Frame velocity in `T_var(x,t) = G (x' - x_initial - V t)`. Default `0`.
`x_initial`	number	Initial front position used to unwrap x. Default `0`.

The linear ETD symbol still uses the JSON reference T. Only the real-space mean-field cubic (q3) sees the local temperature. CPU, CUDA, and HIP share TungstenPointwise. See apps/tungsten/README.md.

Result writers¶

When saveat > 0 and fields is present, parse_result_writers_from_json constructs a catalog writer per entry (default "binary" → BinaryWriter):

Key	Type	Meaning
`fields[].name`	string	Field identifier known to the simulator / model
`fields[].data`	string	Filename template. `$NAME` / `${NAME}` environment references are expanded first (unset or empty is a hard error). If the expanded string contains `%`, `printf`-style formatting with the simulator’s output increment is applied (see `binary_field_io_spec.md`)
`fields[].writer`	string	Catalog key: `"binary"` (default), `"vtk"`, or `"hdf5"` when built with `OpenPFC_ENABLE_HDF5`. Unknown keys are a hard error. `"hdf5"` writes `/field` plus a `.xdmf` sidecar (parallel HDF5 MPI-IO, or gather-to-rank-0 when HDF5 is serial).

Initial / boundary conditions¶

Key	Type	Meaning
`initial_conditions`	array	Objects with `type`, optional `target`, type-specific fields
`boundary_conditions`	array	Same pattern

Modifier types must be registered in main before App runs (register_field_modifier<…>). See app_pipeline.md and examples/initialization/catalog/model.cpp.

Optional sections¶

Key	Handled by	Notes
`simulator`	`apply_simulator_section_from_json`	Gen-1 overlay: `result_counter`, `increment`, optional `integrator.method` (same tokens as `timestepping.integrator.method`). Cannot be combined with `restart_from`.
`checkpoint.every`	`CheckpointService`	Save accepted state every N increments (`0` disables). Bundles go to `checkpoint.directory/step_<increment>/`.
`checkpoint.directory`	`CheckpointService`	Parent directory for published checkpoint bundles.
`restart_from`	`CheckpointService::restore_from_config`	Path to a published bundle (`…/step_N`). Restores fields, `Time` increment/time, result counter, method identity, and session BC state. Grid, method, or BC configuration mismatch is a hard error. Moving boundaries require saved front state; see the tungsten restart workflow.
`profiling`	`AppProfilingController`	`performance_profiling.md`

TOML vs JSON¶

Same logical keys; TOML uses tables such as [domain], [timestepping], [plan_options], [model], [model.params].