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: h5 as the default single-file format; zarr and both require explicit selection. 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.

output.result controls the result file result.vtkhdf. It is true by default and writes the file with the defaults of the solver type; false writes no file, and a mapping sets every, fields, derived_location, derived_every, size_limit_gb, layout and crack_tips. Only the two-dimensional phase-field routes of the YAML runner write the file; other routes, including the multi-material route, ignore the key. Result files explains each key and Result file layout specifies the file.

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.