YAML configuration reference¶

The schema generated by python -m phast schema is authoritative for accepted YAML types, defaults, enumerations, and ranges. Use python -m phast explain-config CONFIG to inspect a concrete file, and python -m phast run CONFIG --validate-only for schema/workflow preflight.

Top-level sections¶

Section	Role
`schema_version`	Configuration contract version; the general CLI YAML schema is version `1`.
`name`, `reference`	Human-readable run identification.
`geometry`	Built-in geometry or imported mesh definition.
`material`	Preset/inline constitutive and fracture properties.
`boundary_conditions`	Named supports and loads.
`loading`	Time, displacement, or step schedule controls.
`solver`	Analysis family, tolerances, iterations, backend, and preconditioner settings.
`output`	Result directory, trajectory, visualization, and logging options.
`device`	Requested device and optional compilation setting.
`initial_conditions`	Supported initial field values.

The repository contains two distinct configuration representations. Public example YAML files accepted by the general python -m phast run entry point use schema_version: 1. A separate version-2 authoring representation can be compiled into a ProblemSpec, but it executes only when a documented adapter supports the requested workflow. Do not change a version-1 example to version 2 unless its own documentation identifies that route. In either representation, passing structural validation does not establish runtime or scientific validity.

Frequently used fields¶

solver.solver_type selects the analysis family. solver.backend controls linear-solver backend dispatch where supported; solver.preconditioner selects a preconditioning choice where supported. solver.time_integrator accepts the implemented central-difference route and documented aliases; reserved routes remain bounded by their implementation.

output.trajectory: true enables snapshots, with output.trajectory_format: zarr preferred and h5 retained for legacy compatibility. output.plots, gif, vtu, and viz_format control visual products where the selected route supports them. These settings do not make a field reloadable unless the corresponding trajectory or stored field exists.

device.device can request cpu, cuda, or mps when supported. A material-aware or backend-aware fallback may change the runtime route; inspect the run metadata and manifest rather than inferring it from the request.

Precedence and units¶

The CLI overrides corresponding YAML values. The configuration loader accepts unit-bearing values for supported quantity fields; use one consistent unit system for all remaining geometry, material, load, and time data.

Authoritative lookup commands¶

python -m phast schema --output configs/phast.schema.json
python -m phast explain-config path/to/config.yaml
python -m phast run path/to/config.yaml --validate-only
python -m phast doctor

The schema and command help are the source of truth for a particular installed revision. This page intentionally summarizes routes rather than duplicating every generated property.