Solver objects¶

Elmer is the solver backend femforge implements today. femforge models every block of Elmer's solver input file (the sif) as a typed pydantic model whose fields are its sif keywords. A preset builds one such stack per physics, the sif writer turns the stack and the mesh groups into a sif, and two parsers read ElmerSolver's output back into typed values. This page covers the model tree, the field-to-keyword mapping, the writer, the checks a solve runs before it writes, and the parsers.

The solver model tree¶

src/femforge/elmer/config groups the models by physics, and its __init__.py re-exports every public name, so callers import from femforge.elmer.config (src/femforge/elmer/config/__init__.py:5-32).

The hierarchy has one base and three mixins:

• SifKeywordModel: fields carry sif keywords, and to_elmer() reflects them out (src/femforge/elmer/config/common/keywords.py:15-41)
  • SolverBase: kind, equation, procedure, variable and the other keywords every solver block has (src/femforge/elmer/config/common/solver_base.py:172-191)
  • SimulationSettings and Constants: the Simulation and Constants blocks
• Mixins a concrete solver composes beside SolverBase:
  • LinearSystem: the Linear System * keywords (src/femforge/elmer/config/common/solver_base.py:138-152)
  • NonlinearSystem: the Nonlinear System * keywords (src/femforge/elmer/config/common/solver_base.py:155-163)
  • SteadyState: Steady State Convergence Tolerance (src/femforge/elmer/config/common/solver_base.py:166-169)

This table is generated from the classes at build time:

Two class variables carry the cross-object rules, and as class variables they never reach the sif. required_material_keys names the material keywords every body the solver acts on must supply (src/femforge/elmer/config/common/solver_base.py:178-179). It is typed as ElmerMaterialKeyword, the same enum a material's properties emit, so the requirement and the emission share one definition. conductor_only restricts the solver's equation to conductor bodies, because a conduction variable solved over dielectrics too puts about 21 decades of conductivity contrast into one matrix: singular for a direct factorization and a stall for preconditioned CG (src/femforge/elmer/config/common/solver_base.py:181-183).

The simulation, constants and operating-point blocks¶

CoordinateSystem.per_radian marks the two symmetric 2D systems, where Elmer integrates per radian and lumped outputs need a 2π factor (src/femforge/elmer/config/common/simulation.py:30-33).

PhysicsConfig and the presets¶

PhysicsConfig is the whole stack: the ordered solvers, the simulation block, the constants and the operating point (src/femforge/elmer/config/common/physics_config.py:47-62). solvers is a list of SolverUnion, a union discriminated on kind, so every concrete field survives a dump and a reload. A plain list[SolverBase] would drop them, and the stack could not ride inside SimulationConfig, the run identity or the manifest (src/femforge/elmer/config/common/physics_config.py:28-44). solver(kind) returns the live instance of one solver class for typed editing (src/femforge/elmer/config/common/physics_config.py:64-69).

physics_config builds the preset for one Physics with an exhaustive match, so a new physics is a type error until it has a preset (src/femforge/elmer/config/common/presets.py:34-139). The table lists each preset as physics_config builds it. magnetostatics_2d is the form magnetostatics solves as under Axisymmetric, never an authored choice, and solved_stack switches the thermal preset to Axi Symmetric under that frame (src/femforge/elmer/config/common/presets.py:24-31).

The comments in the presets record why each stack looks the way it does. Three matter most:

• COIL_MAGNETOSTATICS chains CoilSolver into WhitneyAV and drives the field solve from CoilSolver's elemental current, because a nodal current source dilutes the drive about twofold on thin conductors (src/femforge/elmer/config/common/presets.py:96-104).
• MAGNETOSTATICS_2D pins CalcFields' potential variable and keeps nodal fields on, because turning them off also suppresses the nodal force variable the force reduction reads (src/femforge/elmer/config/common/presets.py:45-55).
• LINEAR_ELASTICITY has a complete stack, but its per-body wiring in Sim is a stub (src/femforge/elmer/config/common/presets.py:132, src/femforge/elmer/sim.py:473-479).

Three functions adjust or read a whole stack:

Conditions and physics shows the user side of editing a stack.

Fields are sif keywords¶

A field names its sif keyword with Map metadata on its Annotated type, as in max_output_level: Annotated[int, Map("Max Output Level")] (src/femforge/elmer/config/common/simulation.py:65). mapped_items reflects the (keyword, value) pairs back out and skips every field whose value is None (src/femforge/common/pydantic.py:34-45). No table beside the models lists the keywords, so a keyword cannot drift from its field.

SifKeywordModel.to_elmer() builds the keyword dict on demand and never stores it (src/femforge/elmer/config/common/keywords.py:27-41):

• A field left at None stays out of the sif, so Elmer keeps its own default for that keyword.
• A list expands to a numbered keyword family, such as Vector Field 1 to Vector Field n.
• extra_keywords merges last and wins, so any Elmer keyword the typed fields lack stays authorable without a subclass (src/femforge/elmer/config/common/keywords.py:23-25).
• Fixed vocabularies are StrEnums whose values are the exact sif strings, so the value written is the enum member itself (src/femforge/elmer/config/common/solver_base.py:15-96).

from femforge.elmer.config import MagnetoDynamicsSolver, physics_config
from femforge.elmer.physics import Physics

stack = physics_config(Physics.MAGNETOSTATICS)
solver = stack.solver(MagnetoDynamicsSolver)
solver.linear_system_max_iterations = 2000
solver.extra_keywords["Linear System GCR Restart"] = 50

block = solver.to_elmer()
assert block["Linear System Max Iterations"] == 2000
assert "Variable" not in block

A keyword several solvers share is declared once as a module-level Annotated alias, such as LinearMaxIterationsField, and every solver that overrides its default reuses the alias (src/femforge/elmer/config/common/solver_base.py:99-135). The alias also carries the field description, because a concrete override would reset a description that came from a docstring (src/femforge/elmer/config/common/solver_base.py:143). kind has no Map: it names the solver in the SolverUnion and doubles as the sif Solver block's label (src/femforge/elmer/sim.py:229-234).

The mesh side follows the same rule: GmshOptions.apply reflects the same Map tags into gmsh option setters (src/femforge/meshing/gmsh_options.py:114-133).

Keyword tables¶

The tables below are generated from the models at build time. Rows follow the field order of the model, which is also the order to_elmer writes the keywords in. "unset" means the field defaults to None and the keyword stays out of the sif. A preset can override a default: the thermal stack, for instance, builds its own SaveScalars reductions.

Simulation and constants¶

SimulationSettings

Constants

Electromagnetism¶

MagnetoDynamicsSolver

MagnetoDynamics2DSolver

MagnetoDynamicsCalcFieldsSolver

CoilCurrentSolver

StatCurrentSolver

ElectrostaticsSolver

Thermal¶

HeatSolver

Mechanics¶

StressSolver

Output¶

ResultOutputSolver

SaveScalarsSolver

Generic¶

GenericSolver is the escape hatch for a solver the hierarchy does not model: set equation and procedure, and author the rest through extra_keywords and the shared typed knobs (src/femforge/elmer/config/common/generic.py:10-17).

GenericSolver

The sif writer¶

src/femforge/elmer/sif.py follows pyelmer's public API shape as an independent implementation (NOTICE:6-7). It writes the same text pyelmer writes, always with LF line endings (src/femforge/elmer/sif.py:1). tests/elmer/test_sif_writer.py compares its output with golden files pyelmer wrote, and checks the LF endings and the registry semantics below (tests/elmer/test_sif_writer.py:1).

Sim and generate()¶

Sim turns the mesh groups and a solver stack into a sif in two phases (src/femforge/elmer/sim.py:59-63):

1. The constructor is cheap. It maps the physics through the frame, takes the given stack or the preset, and checks the stack and every group's conditions against the frame. It builds no sif objects (src/femforge/elmer/sim.py:65-104).
2. generate() builds the sif graph from the possibly edited stack: the simulation and constants blocks, then solvers, equations, materials, bodies and boundaries in dependency order, then validate() (src/femforge/elmer/sim.py:108-129).
3. write(dir) writes the start-info file, the sif and the two id maps, and requires generate() first (src/femforge/elmer/sim.py:483-500).

The driver's build_sim stage constructs Sim from the resolved stack and applies prepare_for_mpi for a partitioned solve; write_sif calls generate().write() (src/femforge/run/driver.py:636-662). Sim takes no config object: its bodies come from the mesh groups, and it owns only its solver stack.

Bodies, boundaries and components¶

A component groups bodies by condition identity, so one CoilDrive authored on a phase's tag reaches every body of that phase as one Component.

Checks before the solve¶

validate() runs at the end of generate() and covers what pydantic cannot see across objects (src/femforge/elmer/sim.py:133-225). It collects every error into one ValueError and issues each smell as a SolverConfigWarning (src/femforge/elmer/sim.py:46-47).

The constructor raises earlier for an unknown physics and for a stack or condition that cannot solve the frame (src/femforge/elmer/sim.py:86-102). Before a partitioned solve, the driver also warns when a coil stack computes nodal forces, because the halo elements it then partitions with corrupt the Component force lumping (src/femforge/run/driver.py:671-680).

The solver-log parser¶

SolverLogParser.feed turns one ElmerSolver output line into a typed event, or None (src/femforge/elmer/solver_log.py:156-188):

The convergence line's solver tag is the sif Equation name lowercased, and some Elmer builds omit it (src/femforge/elmer/solver_log.py:15-16), so both sides normalize names with normalize_solver_key (src/femforge/elmer/solver_log.py:100-102).

solve_case runs ElmerSolver through a backend and feeds every streamed line to the parser (src/femforge/elmer/runtime/solve.py:30-108). It writes each convergence sample to convergence.jsonl as one flushed line, logs it through a ConvergenceRenderer against the stack's targets, and logs each warning and error at its own level. It builds one renderer per solve, so one solve's progress baseline never leaks into the next (src/femforge/elmer/runtime/solve.py:57-94). The driver writes the same targets to convergence_targets.json immediately before the solve (src/femforge/run/driver.py:682-692); Telemetry covers how that file is read back.

After the solve, parse_result reads the finished bundle into a Result (src/femforge/run/parse.py:177-232):

• Status comes from elmersolver.log: error when the log is missing, any line holds ERROR or the run never printed ALL DONE; diverged on a non-convergence marker or a NaN; ok otherwise (src/femforge/run/parse.py:126-174).
• Scalars come from each .dat and its .dat.names sidecar, reading the last row, because a sweep or a transient run appends rows (src/femforge/run/parse.py:43-70).
• A partitioned solve takes rank 0. It writes per-rank .dat.<rank> files, and the exported values are already globally reduced, so rank 0 stands in for the whole and the parser never sums. Disagreeing ranks log a warning, because they mean a reduction without a global operator (src/femforge/run/parse.py:90-123).
• Forces read only the global CalcFields sums, so per-Component triples never fold into the total. The per-Component values join components.yml, and an Axisymmetric frame revolves every force and torque to the full revolution (src/femforge/run/parse.py:186-217).

Results covers the user side.

The electrical flux mapping¶

A current-conduction run measures each phase's terminal current with Elmer's own flux integral, and src/femforge/run/electrical.py maps the result back to names:

1. FixedPotential emits Save Scalars = Logical True beside its potential, which marks the electrode for boundary integration (src/femforge/physical/conditions.py:292-297).
2. SaveScalars' default first reduction is the diffusive flux of Potential weighted by Electric Conductivity, which integrates σ ∂φ/∂n over each marked boundary to a current (src/femforge/elmer/config/output/save_scalars.py:34-41). Its second reduction integrates the Joule loss density to a power P, a cross-check through R = ΔV²/P (src/femforge/elmer/config/output/save_scalars.py:43-47).
3. Elmer names each flux column by its boundary index, as in diffusive flux: potential over bc 3; boundary_fluxes reads the index out of the column name (src/femforge/run/electrical.py:10-21).
4. read_boundary_names reads the index-to-name map Sim wrote as boundaries.yml (src/femforge/run/electrical.py:24-31). The file is flat int: name YAML, and the reader splits each line at its first colon.
5. electrode_currents joins the two into a current per named boundary block (src/femforge/run/electrical.py:34-36).
6. phase_currents keeps, per PHASE<n> index in the names, the current of largest magnitude, because Elmer integrates an internal electrode's flux from one side, and the pad side can read about zero (src/femforge/run/electrical.py:43-54).
7. resistance divides ΔV by that current and raises on a zero current (src/femforge/run/electrical.py:57-61).

Run.electrode_currents and Run.phase_currents read a bundle through these functions (src/femforge/run/inspect.py:184-189).