Elmer: native and Docker¶

Solving runs through the ExecutionBackend seam, and Elmer is the solver implemented today. femforge writes the solver input, runs Elmer's two programs, ElmerGrid and ElmerSolver, as separate processes, and reads the results. The backend decides where they run: NativeElmer runs an Elmer install on this machine, and DockerElmer runs each command in a container of the femforge Elmer image. The backend is a driver setting, never part of the config, so a run solved natively and the same run solved in Docker share one run id.

Pick a backend¶

Pick Docker for parallel solves and for the same Elmer on every machine. Pick native Elmer when you already run an Elmer install, or where Docker is unavailable.

import femforge as ff

native = ff.Driver(backend=ff.elmer.NativeElmer())
docker = ff.Driver(backend=ff.elmer.DockerElmer(), mpi_processes=4)

Without backend, the driver runs native Elmer for a serial solve when it is installed, and Docker for a parallel solve or when no native Elmer is found. Driver and runs lists every combination of docker, docker_image and mpi_processes.

Native Elmer¶

NativeElmer finds the tools on its first command and keeps them:

A missing required tool raises FileNotFoundError naming it. To run an install outside these places, put its bin directory on PATH, or pass the paths:

import femforge as ff
from femforge.elmer.runtime.tools import ElmerToolsLocations

tools = ElmerToolsLocations(
    ElmerGrid="/opt/elmer/bin/ElmerGrid",
    ElmerSolver="/opt/elmer/bin/ElmerSolver",
)
driver = ff.Driver(backend=ff.elmer.NativeElmer(tools))

A native backend runs serial solves only. Native Elmer builds lack MUMPS, the direct solver a partitioned solve needs, so NativeElmer reports itself as not partitioned and a driver with mpi_processes above 1 raises at construction. femforge still records ElmerSolver_mpi and mpiexec when it finds them, and femforge doctor reports whether the install has MPI.

Docker¶

DockerElmer() runs in ghcr.io/femforge-io/femforge-elmer:0.2.0: Ubuntu 24.04, pinned by digest, with headless Elmer, Open MPI and MUMPS from CSC's elmerfem-csc package. femforge.elmer.runtime.docker_image holds the recipe that generates its Dockerfile. Print it with femforge image dockerfile.

How femforge gets the image¶

Before its first command in a process, the backend makes sure Docker holds the image:

1. It reuses a local image with the tag when the image's femforge.recipe label, the SHA-256 of its Dockerfile, matches the current recipe.
2. Else it pulls the released image from GHCR, and keeps it when the label matches.
3. Else, when the pull fails or the pulled image came from another recipe, it logs a warning and builds the image from the recipe. The build takes a few minutes, once.

It checks each tag once per process, and concurrent solves in one process pull or build it once. Run femforge image pull or femforge image build to fetch it ahead of time.

Development images¶

When the recipe in your checkout differs from the released one, the backend uses a development image named femforge-elmer:<version>-dev.<hash8>, from the first 8 hex digits of the recipe's hash. A development image is never published, so the backend builds it locally on first use instead of pulling. femforge image bump raises the image version after a recipe change, and the release workflow refuses to publish a development tag.

Platform¶

The CSC package exists only for amd64, so femforge pulls, builds and runs the image with --platform linux/amd64 on every host. You do not need to set DOCKER_DEFAULT_PLATFORM. On an arm64 host, such as a Mac with Apple silicon, Docker runs the image under emulation and solves run slower; femforge doctor warns about it, and Docker Desktop's Rosetta emulation setting speeds them up.

Containers, mounts and users¶

Each ElmerGrid or ElmerSolver command runs in a fresh container, removed when it exits and named femforge_<hex>. The container binds the host directory it works on at /case: the mesh directory for ElmerGrid, the run directory for ElmerSolver.

On Linux with a rootful daemon, each container runs as your uid:gid, so the files it writes into the run directory stay yours. With a rootless daemon, and on Windows and macOS, it runs as the image's user.

Parallel solves¶

With mpi_processes above 1, ElmerGrid partitions the mesh in a container, then the solve runs as mpirun --oversubscribe -np <n> ElmerSolver_mpi. --oversubscribe lets the rank count exceed the host's physical cores, because it must match the partition count. Driver and runs covers what the driver changes in the solver stack before a parallel solve.

Timeouts¶

Every backend command takes timeout_s and a cancel token, and solve_case passes them through. A timed-out Docker command kills its container by name, since stopping the docker client alone leaves the container running. The image is fetched before the clock starts, so a build never counts against a timeout. A pull stops after 30 minutes and logs each finished layer and a heartbeat every 15 s. The driver sets no timeout, so its solves run until Elmer exits.

Another image¶

Pass a DockerImage to run Elmer in an image of your own:

import femforge as ff
from femforge.execution.docker.image import DockerImage

image = DockerImage("registry.example.com/elmer:9.0", platform="linux/amd64")
driver = ff.Driver(backend=ff.elmer.DockerElmer(image))

An image without a recipe is pulled when Docker lacks it and never built, so a failed pull raises DockerError. Without platform, Docker picks the host's. Driver(docker_image="registry.example.com/elmer:9.0") does the same with the host's platform.

The femforge image commands¶

Each command takes the image name as an optional argument, femforge-elmer by default. CLI lists every option.

Diagnose with femforge doctor¶

femforge doctor

The doctor prints one row per check with the fix for each problem, and exits with code 1 when a check fails. These checks concern Elmer:

Install lists the other checks.

Troubleshooting¶

Image licenses¶

The femforge-elmer image redistributes Elmer FEM and Ubuntu 24.04 packages, each under its own license. Elmer's ElmerSolver and ElmerGrid are GPL-2.0-or-later, and the ElmerSolver library is LGPL-2.1-or-later; the image's org.opencontainers.image.licenses label records GPL-2.0-or-later AND LGPL-2.1-or-later. femforge itself is Apache-2.0 and runs Elmer as a separate program.

The license texts ship inside the image. Each Ubuntu package keeps its own in /usr/share/doc/<package>/copyright. The elmerfem-csc package keeps Elmer's in /usr/share/elmersolver/license_texts/: LICENSES, GPL-2.txt, LGPL-2.1.txt, and fem/LICENSES for the libraries bundled into the solver. Print Elmer's notice with:

docker run --rm --platform linux/amd64 ghcr.io/femforge-io/femforge-elmer:0.2.0 cat /usr/share/elmersolver/license_texts/LICENSES

List every package's copyright file with:

docker run --rm --platform linux/amd64 ghcr.io/femforge-io/femforge-elmer:0.2.0 sh -c "ls /usr/share/doc/*/copyright"