Procedures
An analysis step is an analysis <name> { … } block in a study. It holds exactly one procedure block, <family> <procedure> { <fields> }, plus optional retain, accuracy, load_cases and initial_conditions members. Steps run in dependency order; after analysis.<step> orders a step after another, and a state binding (basis = analysis.modes.state.basis) makes one step consume another's result.
analysis modes {
structural modal { modes = 12 }
retain basis
}
analysis response after analysis.modes {
structural modal_harmonic {
basis = analysis.modes.state.basis
frequencies = [50 Hz, 100 Hz, 150 Hz]
}
}Families and procedures
The table below is generated from the capability ledger, the same source as the compiler's table of family and procedure pairs. runmat check applies that table, so a combination the family does not run is reported at its line before anything is meshed.
| Family | Runs in this release | Planned |
|---|---|---|
| Structural mechanics | static, modal, prestressed modal, buckling, transient, harmonic, prestressed harmonic, nonlinear, transient (modal superposition), harmonic (modal superposition), prestressed harmonic (modal superposition), response spectrum (modal superposition), random response (modal superposition) | none |
| Heat transfer | static, transient | none |
| Electromagnetics | static, harmonic, line parameters | transient, nonlinear |
| Acoustics | harmonic, modal, transient | static, nonlinear |
| Fluid flow | static, transient | harmonic, nonlinear |
| Thermomechanical | static, nonlinear | transient, harmonic |
| Electrothermal | static, transient | harmonic, nonlinear |
| Conjugate heat transfer | static, transient | harmonic, nonlinear |
| Fluid–structure interaction | static, transient | harmonic, nonlinear |
Modal superposition reuses a retained modal basis; every other entry solves the full system directly.
What each procedure solves
With , and the assembled stiffness, mass and damping matrices and the load vector:
| Procedure | Equation | Independent domain |
|---|---|---|
static (steady) | none | |
modal | , for the lowest modes pairs | mode count |
transient | (first order, , for heat transfer) | time |
harmonic | frequency list | |
buckling | , with the geometric stiffness of a preload | mode count |
nonlinear | , solved by Newton iteration over the load factor | load factor |
| modal-reduced forms | the same equations projected onto a retained modal basis, | as above |
Each family's physics reference states its weak form, element matrices, solver and recovery.
Structural procedures
| Procedure block | Fields | Publishes |
|---|---|---|
structural static | none | primary (displacement state) |
structural preload | none; the step's loads are the preload | geometric_stiffness |
structural modal | modes (positive integer); optional residual_vectors (one to three global directions, [[0, 0, 1]]); optional solver = auto (default), factorization or iterative | modal_basis |
structural transient | start_time, end_time, time_step | primary |
structural modal_transient | basis, start_time, end_time, time_step | primary |
structural harmonic | frequencies | primary |
structural modal_harmonic | basis, frequencies; optional static_correction = applied_loads or none (default) | primary |
structural prestressed_modal | prestress, modes; optional residual_vectors and solver | modal_basis |
structural buckling | prestress, modes | buckling modes |
structural prestressed_harmonic | prestress, frequencies; optional basis (modal reduction instead of a direct solve) and, with basis, static_correction | primary |
structural modal_response_spectrum | basis, spectra = [model.response_spectrum.<name>, …] | primary |
structural random_response | basis, excitation = model.random_excitation.<name>, modal_damping_ratio (number), minimum_cumulative_mass_ratio (number) | primary |
structural nonlinear | start_load_factor, end_load_factor; optional kinematics = small_strain (default) or large_deformation | primary |
Modal eigensolver
solver chooses how a modal extraction computes its modes:
auto(the default): the resource plan uses shift-invert block Lanczos on a sparse factorization when that plan fits the memory the run is admitted to use, and otherwise block LOBPCG with a multigrid preconditioner when that plan fits.factorization: shift-invert block Lanczos only.iterative: block LOBPCG only. It holds no factorization, so it fits models whose factor does not.
Both methods prove that no mode below the highest reported one was missed (a Sturm inertia count) and qualify each mode on the same accuracy criterion. When the plan for a required method does not fit the admitted memory, the run is refused before solving, and the error names the bytes the study needs and the bytes the budget offers. RunMat does not switch to the other method.
analysis modes {
structural modal {
modes = 6
solver = iterative
}
}Modal truncation and residual vectors
A modal-reduced step solves in the space its basis spans: the retained modes, then any residual vectors, then any static correction. RunMat accepts the step when the reduced equations meet the step's relative accuracy tolerance. It then evaluates the full-order equilibrium of the expanded response and publishes the largest relative imbalance as the modal truncation measure (modal_truncation_balance_error in fea.results, with the frequency where it occurs). That measure reports how much response the reduced space leaves out. It is published for every modal-reduced sweep and is not compared with the algebraic tolerance. A direct solve is accepted on its full-order balance and reports it as max_frequency_balance_error.
Two enrichments shrink the truncation measure:
residual_vectors = [[0, 0, 1], …]onstructural modalorstructural prestressed_modaladds, for each global direction, the static response to a unit acceleration in that direction with the retained modes removed. Use it for base excitation and inertia loading.static_correction = applied_loadson a modal-reduced frequency step adds the static response to the step's applied load (real and imaginary parts at the sweep's reference frequency), with the retained shapes removed. The reduced space then contains the exact quasi-static response, so the truncation measure falls sharply below the first retained mode. Use it for concentrated or surface loads.
analysis modes {
structural modal { modes = 8 }
retain basis
}
analysis response after analysis.modes {
structural modal_harmonic {
basis = analysis.modes.state.basis
frequencies = [20, 40, 60] Hz
static_correction = applied_loads
}
}structural nonlinear runs as a study's single step, and inside a procedure graph (after a preload, before a modal step) Not yet releasedStatus.
Thermal procedures
| Procedure block | Fields | Publishes |
|---|---|---|
thermal steady | optional heat_source = analysis.<em-step>.state.<s> | primary (temperature state) |
thermal transient | start_time, end_time, time_step; optional heat_source | primary |
heat_source heats the thermal step with the Joule loss density of an upstream electromagnetic harmonic step (induction heating).
Electromagnetic procedures
| Procedure block | Fields |
|---|---|
electromagnetic static | none; the model's electromagnetic { equation = … } selects electrostatics, DC conduction or magnetostatics |
electromagnetic harmonic | frequencies |
electromagnetic transient Not yet releasedStatus | start_time, end_time, time_step |
electromagnetic nonlinear Not yet releasedStatus | start_load_factor, end_load_factor |
electromagnetic line_parameters | none; the cross_section geometry carries the stackup and traces (trace impedance) |
Acoustic procedures
| Procedure block | Fields |
|---|---|
acoustic harmonic | frequencies |
acoustic modal | modes |
acoustic transient | start_time, end_time, time_step |
acoustic static Not yet releasedStatus | none |
acoustic nonlinear Not yet releasedStatus | start_load_factor, end_load_factor |
Fluid procedures
| Procedure block | Fields |
|---|---|
fluid steady | none |
fluid transient | start_time, end_time, time_step |
fluid harmonic Not yet releasedStatus | frequencies |
fluid nonlinear Not yet releasedStatus | start_load_factor, end_load_factor |
Coupled procedures
| Procedure block | Fields |
|---|---|
thermomechanical preload | temperature = analysis.<thermal-step>.state.<s>; publishes geometric_stiffness for prestressed modal, buckling and harmonic steps |
thermomechanical steady | none |
thermomechanical nonlinear | start_load_factor, end_load_factor |
thermomechanical transient Not yet releasedStatus | start_time, end_time, time_step |
thermomechanical harmonic Not yet releasedStatus | frequencies |
electrothermal steady, electrothermal transient | none; time fields for transient |
electrothermal harmonic Not yet releasedStatus | frequencies |
electrothermal nonlinear Not yet releasedStatus | start_load_factor, end_load_factor |
conjugate_heat_transfer steady, conjugate_heat_transfer transient | none; time fields for transient |
conjugate_heat_transfer harmonic Not yet releasedStatus | frequencies |
conjugate_heat_transfer nonlinear Not yet releasedStatus | start_load_factor, end_load_factor |
fluid_structure_interaction steady, fluid_structure_interaction transient | none; time fields for transient |
fluid_structure_interaction harmonic Not yet releasedStatus | frequencies |
fluid_structure_interaction nonlinear Not yet releasedStatus | start_load_factor, end_load_factor |
static and steady are the same procedure; use whichever reads naturally for the family.
Domains
No procedure infers its domain from a signal, an output or another step; each states it:
| Field | Type | Rule |
|---|---|---|
start_time, end_time | time | . |
time_step | time | Positive, and divides exactly. |
frequencies | list of frequencies | Finite, nonnegative, nonempty and strictly increasing, such as [10 Hz, 20 Hz, 50 Hz]. |
modes | positive integer | Number of eigenpairs, from the lowest. |
start_load_factor, end_load_factor | numbers | Finite and increasing; the load is scaled by the factor. |
State flow
Each step publishes typed states: a displacement or temperature state (primary), a modal basis (modal_basis), a preload's geometric stiffness (geometric_stiffness). retain <name> publishes a step's state under a chosen name, so retain basis after structural modal publishes analysis.<step>.state.basis.
A consuming step names the state it needs:
analysis preload { structural preload {} }
analysis modes after analysis.preload {
structural prestressed_modal {
prestress = analysis.preload.state.geometric_stiffness
modes = 6
}
retain basis
}
analysis response after analysis.modes {
structural prestressed_harmonic {
prestress = analysis.preload.state.geometric_stiffness
basis = analysis.modes.state.basis
frequencies = [60 Hz]
}
}The checker verifies each binding: the producer exists, the state kind matches, the producer runs on the same mesh and solution space, and the state is complete and persisted. after orders steps; it does not replace a state binding. Every state binding adds its own dependency, so a step that consumes two producers waits for both.
Members of every analysis step
| Member | Form | Meaning |
|---|---|---|
retain <name> | statement | Publishes the step's state under <name>. |
load_cases = [load_case.<a>, …] | list | The load cases this step applies. [] applies none; omitting it applies the model's load cases. Supports and prescribed values always apply. |
initial_conditions = [model.initial.<a>, …] | list | Initial state for a step that starts from one, such as a transient step. See initial conditions. |
accuracy { algebraic_measure = <measure>; algebraic_relative_tolerance = <number> } | block | The step's mandatory algebraic accuracy check. Both members are optional, and at least one is required. algebraic_relative_tolerance is strictly between 0 and 1. It sets solver stopping and the check on the computed solution; it does not bound discretization error. See algebraic accuracy. |
analysis heat_up {
thermal transient {
start_time = 0 s
end_time = 60 s
time_step = 0.5 s
}
load_cases = [load_case.heater_on]
initial_conditions = [model.initial.ambient]
accuracy { algebraic_relative_tolerance = 1e-8 }
}Algebraic accuracy
Every analysis step checks that its computed solution satisfies the assembled equations. algebraic_measure selects the measure the check uses:
backward_error: the normwise backward error in the ∞-norm. For a linear system it is ‖b − A x‖ / (‖A‖ ‖x‖ + ‖b‖). For a mode with eigenvalue λ and shape x it is ‖K x − λ M x‖ / ((‖K‖ + |λ| ‖M‖) ‖x‖). It is the smallest relative change to the operators (and load) for which the computed answer is exact. It does not grow with mesh refinement or conditioning, so one tolerance means the same thing on a coarse and a fine model. The default tolerance is 1e-12. Double-precision direct solvers and converged iterative solvers reach about 1e-16 in this measure, and evaluatingA xitself is uncertain by up to a few 1e-14 for quadratic solid elements.relative_residual: the Euclidean residual relative to the terms that form it, ‖b − A x‖ / ‖b‖, or ‖K x − λ M x‖ / (‖K x‖ + |λ| ‖M x‖) for a mode. The default tolerance is 1e-8. In double precision this measure cannot go below about 1e-16 × the condition number, so on a fine mesh it can reject a correct solution.
Structural modal and prestressed modal steps use backward_error by default. Every mode publishes both numbers: modal.backward_error and modal.residual_norm (the relative residual). The step's measure decides which one is checked. The other procedures check relative_residual in this release, and setting algebraic_measure = backward_error on them is an error.
| Procedure | Algebraic check in this release | Published |
|---|---|---|
structural modal, structural prestressed_modal | backward error of each mode, 1e-12 | modal.backward_error and modal.residual_norm per mode; diagnostics FEA_MODAL_ACCURACY and FEA_MODAL_CONVERGENCE |
structural static, structural harmonic, structural transient, structural prestressed_harmonic | relative residual of the solved equations, 1e-8 | structural.residual_norm |
structural nonlinear | relative residual of every Newton correction solve, 1e-8 | the largest correction residual in the numerical receipt |
thermal steady, transient and nonlinear steps | relative residual of every accepted linear solve, 1e-8 | the largest linear residual in the numerical receipt |
electrical static steps | relative residual of the lifted linear system, 1e-8 | linear_relative_residual in the numerical receipt |
magnetic static steps | relative physical and gauge residuals, 1e-8 | the numerical receipt |
structural buckling | relative residual of each mode | the buckling modes' backward errors are computed but not checked |
The engineering checks are separate from this table and keep their own criteria: mesh convergence, modal mass capture, energy balance, Newton force balance and the fluid scaled residuals.
The backward-error check for every algebraic solve is Not yet releasedStatus. Static, thermal, electrostatic, magnetostatic and harmonic solves, each transient step and each Newton linearization will check η = ‖b − A x‖ / (‖A‖ ‖x‖ + ‖b‖) at 1e-12 by default and publish it beside the relative residual. algebraic_measure = relative_residual will keep the current check.
Setting algebraic_measure resets the tolerance to that measure's default, and algebraic_relative_tolerance then replaces it:
analysis modes {
structural modal { modes = 6 }
accuracy {
algebraic_measure = relative_residual
algebraic_relative_tolerance = 1e-6
}
}Response spectrum and random response
analysis modes {
structural modal { modes = 30 }
retain basis
}
analysis response_spectrum after analysis.modes {
structural modal_response_spectrum {
basis = analysis.modes.state.basis
spectra = [model.response_spectrum.qualification_x]
}
}The spectrum is a model declaration (response_spectrum <name> { … }), and a random excitation a random_excitation <name> { … } power spectral density; both are referenced from the step. The full studies are modal-response-spectrum.fea and modal-random-response.fea.