Operation Reference

June 23, 2026 · View on GitHub

This page is for host integrations and tooling that care about operation names, envelopes, error codes, artifact roots, and builtin names.

Envelopes

Successful operations return OperationEnvelope<T>:

Field	Meaning
`operation`	Stable operation name, such as `fea.run_modal`.
`op_version`	Versioned operation identifier, such as `fea.run_modal/v1`.
`trace_id`	Optional host trace id.
`request_id`	Optional host request id.
`data`	Typed operation payload.

Failures return OperationErrorEnvelope:

Field	Meaning
`error_code`	Stable machine-readable code.
`error_type`	`input`, `validation`, `capacity`, `backend`, `internal`, or `contract`.
`message`	Human-readable message.
`operation`, `op_version`	Operation identity that failed.
`retryable`	Whether retrying may be reasonable.
`severity`	`warning`, `error`, or `fatal`.
`context`	String key/value details for automation.
`trace_id`, `request_id`, `timestamp`	Correlation and timing metadata.

Error codes use RM.<DOMAIN>.<OPERATION>.<REASON>, for example RM.FEA.RUN_STUDY.INVALID_SPEC or RM.GEOMETRY.LOAD.UNSUPPORTED_FORMAT.

Geometry Operations

Operation version	Use
`geometry.inspect/v1`	Detect supported input format and byte count before loading.
`geometry.load/v1`	Import geometry bytes into a `GeometryAsset`.
`geometry.compute_stats/v1`	Return geometry statistics for an asset.
`geometry.list_regions/v1`	Return known geometry regions.
`geometry.query_entities/v1`	Return region, mesh, or entity references with a bounded query.
`geometry.capture_view/v1`	Capture a geometry view through the installed adapter.
`geometry.prep_for_analysis/v1`	Produce a prep artifact and `MeshingPrepResult`.
`geometry.prep_artifact_health/v1`	Report prep artifact counts, ages, metrics, and lifecycle data.

FEA Operations

Operation version	Use
`fea.create_model/v1`	Build an `AnalysisModel` from geometry and a model profile intent.
`fea.validate/v1`	Validate model units, frame, materials, loads, boundary conditions, domains, and geometry compatibility.
`fea.run_linear_static/v1`	Run the linear static structural path.
`fea.run_modal/v1`	Run modal analysis.
`fea.run_acoustic/v1`	Run acoustic harmonic analysis.
`fea.run_thermal/v1`	Run standalone thermal analysis.
`fea.run_transient/v1`	Run structural transient analysis.
`fea.run_nonlinear/v1`	Run nonlinear structural analysis.
`fea.run_electromagnetic/v1`	Run electromagnetic analysis.
`fea.run_cfd/v1`	Run finite-volume incompressible CFD analysis.
`fea.run_cht/v1`	Run coupled CFD plus thermal conjugate heat-transfer analysis.
`fea.run_fsi/v1`	Run partitioned fluid-structure interaction analysis.
`fea.results/v1`	Query fields, diagnostics, payload subsets, quality reasons, provenance, and summaries.
`fea.results_compare/v1`	Compare selected fields between two persisted runs.
`fea.trends/v1`	Summarize persisted runs by family.

Study Operations

Operation version	Use
`fea.validate_study/v1`	Validate one study and write a validation artifact.
`fea.plan_study/v1`	Produce operation sequence, run operation, fingerprint, and plan artifact.
`fea.run_study/v1`	Execute one study and write run evidence.
`fea.validate_study_sweep/v1`	Validate a sweep with aggregate and per-study issues.
`fea.plan_study_sweep/v1`	Plan a sweep with plan entries and failure entries.
`fea.run_study_sweep/v1`	Execute a deterministic sequential sweep.

RunMat Builtins

Builtin	Use
`geometry.inspect(path)`	Read a geometry file and return a `geometry.InspectResult` object.
`geometry.load(path)`	Read a geometry file and return a `geometry.Asset` object.
`geometry.listRegions(asset)`	Return imported regions from a `geometry.Asset`.
`geometry.meshes(asset)`	Return patch-ready surface mesh topology with vertices, faces/triangles, and region mappings.
`fea.load(path)`	Load a `.fea` study or sweep file and return `fea.Study` or `fea.Sweep`.
`fea.material(...)`, `fea.materialAssignment(...)`	Create typed material data and region assignments.
`fea.boundaryCondition(...)`, `fea.loadCase(...)`	Create typed constraints, loads, and sources.
`fea.step(...)`, `fea.domain(...)`, `fea.interface(...)`	Create typed analysis steps, physics domains, and interfaces.
`fea.runOptions(kind, Name, Value, ...)`	Create family-specific run options.
`fea.model(id, geometry, Name, Value, ...)`	Assemble an explicit model from geometry and typed components.
`fea.study(id, geometry, Name, Value, ...)`	Create a `fea.Study` from geometry, physics profile/model data, backend, and run options.
`fea.sweep(id, studies, Name, Value, ...)`	Create a deterministic sweep from `fea.Study` objects.
`fea.validate(study)`	Validate a `.fea` path, `fea.Study`, or `fea.Sweep`.
`fea.plan(study)`	Plan a `.fea` path, `fea.Study`, or `fea.Sweep`.
`fea.run(study)`	Run a `.fea` path, `fea.Study`, or `fea.Sweep`.
`fea.results(runOrId, Name, Value, ...)`	Load result data from a run result object or persisted run id.
`fea.field(resultsOrRun, fieldId)`	Extract one field from a result query.
`fea.plot(runOrResultsOrField, fieldId)`	Create a RunMat figure for a result field using the study geometry context.
`fea.compare(baselineRunId, candidateRunId, Name, Value, ...)`	Compare two persisted runs.
`fea.trends(Name, Value, ...)`	Summarize recent persisted runs.

fea.Study and fea.Sweep objects expose validate, plan, and run methods through the class system. fea.RunResult exposes results, field, and plot; fea.Results exposes field and plot; fea.Field exposes plot.

`.fea` Document Fields

Top-level study fields:

Field	Required	Meaning
`version`	Yes	Document version. Current value is `1`.
`kind`	Yes	`study`.
`id`	Yes	Stable study id.
`geometry`	Yes	Geometry file path, units, and import options.
`model`	Yes	Model id, profile, defaults mode, and frame.
`run`	Yes	Run family, backend, and family-specific options.
`regions`	No	Named aliases for geometry region selectors.
`materials`	No	Material definitions keyed by material id.
`material_assignments`	No	Region-to-material assignments.
`boundary_conditions`	No	Constraints and boundary data.
`loads`	No	Forces, moments/torques, pressures, body forces, current densities, or coil currents.
`steps`	No	Analysis steps.
`domains`	No	Thermo-mechanical, electro-thermal, electromagnetic, or CFD domain data.
`interfaces`	No	Contact or coupling interfaces.

Top-level sweep fields:

Field	Required	Meaning
`version`	Yes	Document version. Current value is `1`.
`kind`	Yes	`sweep`.
`id`	Yes	Stable sweep id.
`fail_fast`	No	Defaults to `true`.
`studies`	Yes	List of nested study documents. Nested studies omit `kind`.

Load documents use type or kind. Structural moment loads use type: moment with vector: [mx, my, mz] in N*m. type: torque is accepted as an alias and resolves to the canonical moment load. Direct moment loads are valid only for structural regions whose elements provide rotational DOFs; non-structural run families and solid-only displacement regions reject them during validation or assembly.

Rotational structural runs may return structural.rotation and structural.reaction_moment fields. Beam-specific moment resultants use structural.beam_torsion_moment and structural.beam_bending_moment; shell-specific resultants use structural.shell_bending_moment.

Runtime Config

Use [runtime.fea]:

Key	Purpose
`artifact_store`	`in_memory` or `filesystem` run artifact store. Defaults to `filesystem` when omitted by the CLI/runtime bootstrap.
`artifact_root`	Filesystem root for persisted run artifacts. Defaults to `artifacts`.
`artifact_max_runs`	Optional global retained run limit.
`artifact_max_runs_per_kind`	Optional retained run limit per family.
`study_artifact_root`	Study validate, plan, run, and sweep artifact root.
`geometry_prep_artifact_root`	Geometry prep artifact root.
`geometry_prep_max_artifacts`	Optional global prep artifact retention limit.
`geometry_prep_max_artifacts_per_geometry`	Optional per-geometry prep artifact retention limit.
`geometry_prep_max_age_seconds`	Optional prep artifact age retention limit.
`geometry_prep_require_latest_revision`	Whether prep-aware runs reject stale geometry revisions.
`thermo_field_artifact_root`	Thermo-field artifact root for coupled thermal paths.

Preferred environment variables:

Environment variable	Purpose
`RUNMAT_FEA_ARTIFACT_STORE`	`in_memory` or `filesystem` run artifact store fallback.
`RUNMAT_FEA_ARTIFACT_ROOT`	Run artifact root.
`RUNMAT_FEA_ARTIFACT_MAX_RUNS`	Optional global retained run limit.
`RUNMAT_FEA_ARTIFACT_MAX_RUNS_PER_KIND`	Optional retained run limit per family.
`RUNMAT_FEA_STUDY_ARTIFACT_ROOT`	Study validate, plan, run, and sweep artifact root.
`RUNMAT_GEOMETRY_PREP_ARTIFACT_ROOT`	Geometry prep artifact root.
`RUNMAT_GEOMETRY_PREP_MAX_ARTIFACTS`	Optional global prep artifact retention limit.
`RUNMAT_GEOMETRY_PREP_MAX_ARTIFACTS_PER_GEOMETRY`	Optional per-geometry prep artifact retention limit.
`RUNMAT_GEOMETRY_PREP_MAX_AGE_SECONDS`	Optional prep artifact age retention limit.
`RUNMAT_GEOMETRY_PREP_REQUIRE_LATEST_REVISION`	Whether prep-aware runs reject stale revisions.
`RUNMAT_THERMO_FIELD_ARTIFACT_ROOT`	Thermo-field artifact root.

Legacy RUNMAT_ANALYSIS_* variables remain compatibility fallbacks where supported.

Evolution Rules

Add fields instead of changing field meaning.
Preserve stable error codes and quality reason codes.
Keep operation-specific validation failures typed as operation errors.
Persist enough provenance to explain backend and solver policy choices.
Update status, V&V docs, and tests when a family changes support level.
Version-bump an operation if a payload or semantic break is unavoidable.