Driver and runs¶

The Driver turns a SimulationConfig into a Result. It derives the run identity from the config and returns a finished run with that identity when one exists. Otherwise it meshes with the mesh backend, gmsh today, writes the sif and solves with the solver backend, Elmer today. It then parses the output and records the run in its own bundle directory. Where each step executes is a driver setting, never part of the config, so the same config names the same run on every machine and every backend.

Evaluate a config¶

import femforge as ff

config = ff.SimulationConfig(
    mesh=ff.MeshConfig(step="models/actuator.step", global_mesh_size=0.002),
    domain=ff.DomainConfig(
        materials=[ff.materials.Air(), ff.materials.N52()],
        tags=[
            ff.EntityTag(
                selector={ff.TagKey.MAGNETIZATION: "N"},
                conditions=[ff.Magnetization(direction=ff.Direction(0, 0, 1))],
            ),
            ff.EntityTag(selector={ff.TagKey.NAME: "mover"}, conditions=[ff.ForceComponent(label="mover")]),
        ],
    ),
    meta=ff.RunMeta(description="Baseline gap", tags={"study": "gap"}),
)

driver = ff.Driver(runs_dir="runs", backend=ff.elmer.DockerElmer(), mesher=ff.WorkerMesher())
result = driver.evaluate(config)

print(result.run_id, result.status)
print(result.axial_force("mover", ff.Axis.Z))

Run it twice: the second call finds the finished bundle and returns its result without solving.

Construction¶

Every parameter is keyword-only.

Artifacts and retention covers retention, artifacts and bundle_policy; Telemetry covers telemetry.

Execution backends¶

Solving runs through the ExecutionBackend seam, and Elmer is the solver implemented today:

DockerElmer reuses a matching local image, else pulls the released one, else builds it from its recipe. When the recipe in your checkout differs from the released one, it builds a local development image instead. Pass DockerElmer(DockerImage(tag)) or Driver(docker_image=tag) to run another image. Elmer native and Docker covers the image and the native install.

Without backend, the driver picks one:

docker=False with a docker_image raises.

Parallel solves¶

Set mpi_processes above 1 to solve on several ranks. The driver checks at construction that the backend is partitioned, so NativeElmer raises there. Before the solve it:

• switches CoilSolver's direct solve to MUMPS and raises for any other direct solve in the stack;
• partitions the Elmer mesh with ElmerGrid into partitioning.<n>/, adding halo elements only when the stack needs them for coil electrodes;
• warns when a partitioned coil solve also computes nodal forces, because halo elements corrupt the Component force lumping.

Results explains how femforge reads the per-rank scalar files.

Meshers¶

Meshing runs through the MeshBackend seam, and gmsh is the mesher implemented today:

The mesher never enters the run identity. Mesh covers the mesh settings themselves.

evaluate() and the stages¶

Driver.evaluate takes the config and an optional retention that overrides the driver's policy for one call. It then:

1. Computes the identity: cache_key(config), the run id derived from it, and the bundle directory runs_dir/<run_id>.
2. Returns a reusable bundle, local or from the artifact cache.
3. Claims the run directory, so a second process asking for the same run waits.
4. Writes the manifest with status running and runs the stages below.
5. Parses the result and writes the bundle.
6. Publishes the bundle to the artifact cache, when one is configured and the run did not end in error.
7. Applies the retention policy.

Subclass the driver and override a stage method or a hook to change the pipeline. configure_sim runs after the identity is computed, so an edit there does not change the run id; author config.physics.overrides instead when the change should. Each stage emits a StageEvent at its start and its finish through on_stage_event, which records the timeline on the manifest:

import femforge as ff
from femforge.run import StageEvent


class TimedDriver(ff.Driver):
    """A driver that prints each stage's duration."""

    def on_stage_event(self, event: StageEvent) -> None:
        super().on_stage_event(event)
        if event.finished_at is not None:
            print(event.stage, event.finished_at - event.started_at)

A stage that raises sets the manifest status to error, applies the retention policy and re-raises. An interrupt leaves the bundle as it is.

The run bundle¶

Each run writes one directory under runs_dir, named by its run id:

runs/
├── calm-avocet-3f9a1c07/
│   ├── manifest.json              provenance: config, keys, status, stage timeline
│   ├── result.json                the typed Result
│   ├── geometry.step              the STEP the run meshed
│   ├── geometry.msh               the gmsh mesh, absent when the mesh came from a store
│   ├── mesh.header                ElmerGrid's mesh, with mesh.nodes, mesh.elements, mesh.boundary
│   ├── mesh.names                 ElmerGrid's ids by group name
│   ├── groups.json                the mesh groups a cached mesh is rebound from
│   ├── entities.json              named bodies and boundaries by mesh id
│   ├── boundaries.yml             boundary ids by name
│   ├── components.yml             sif Component ids by name
│   ├── case.sif                   the solver input, with ELMERSOLVER_STARTINFO
│   ├── scalars.dat                SaveScalars output, with scalars.dat.names
│   ├── case_t0001.vtu             the field output
│   ├── elmergrid.log              with elmersolver.log, convergence.jsonl, convergence_targets.json, run.log
│   └── partitioning.4/            the partitioned mesh of a 4-rank solve
└── calm-avocet-3f9a1c07.lock/     the claim, while a driver solves the run

The RunManifest in manifest.json describes the run:

Run ids and the cache key¶

The run id has the form <adjective>-<noun>-<hash8> and is a pure function of the cache_key. Identical inputs map to the same directory, and a second machine computes the same id.

Editing config.meta relabels a run without solving it again. Overrides identical to the preset leave the key unchanged. When two keys share a name, which is astronomically unlikely, the driver raises so that two runs never mix in one directory.

Claims and reuse¶

With reuse=True, evaluate() returns the local bundle when its manifest has the same cache_key, its status is ok or diverged, it holds result.json, and, unless bundle_policy is CORE, retention has not purged its field output. Otherwise, with an artifact cache, it fetches the published bundle into the run directory. A run that ended in error solves again; divergence is a physics outcome and is reused. reuse=False always solves.

One process produces each bundle. The driver claims runs_dir/<run_id>.lock/ and refreshes the claim every 10 s while it solves. Another process asking for the same run checks every 2 s and reuses the bundle once the first one finishes with a reusable status. A claim silent for 120 s is stale, and the next claimant breaks it.

Reaping stale runs¶

A process that dies mid-solve leaves its bundle at running and its claim behind. reap_runs settles them: it marks each bundle left running with no live claim as abandoned and breaks every silent claim. A claim is silent when its directory is gone, its heartbeat is stale, or it was taken on this host by a process that no longer exists.

femforge runs reap --runs-dir runs

The command also re-indexes the runs it changed in the telemetry store. See CLI for its options.

Finding runs again¶

Run opens a bundle for reading: its result, manifest, named bodies, components and field output. Run.from_result(result) opens the bundle a result came from, and Run.latest(runs_dir) the newest one. find_runs filters a runs directory by config.meta, newest first:

import femforge as ff

for run in ff.find_runs("runs", tags={"study": "gap"}, text="baseline"):
    print(run.path.name, run.meta.description, run.result.status)

tags matches by subset, and text searches the run id, the description and the notes, ignoring case. find_runs reads every manifest; over thousands of bundles, query the RunIndex instead.