Install¶

femforge is a Python package plus a solver that runs beside it. It meshes through the mesh backend, gmsh today, which installs with the package. It solves through the solver backend, Elmer today, which runs from a native install or inside the femforge Docker image. This page installs both and checks the result with femforge doctor.

Requirements¶

• Python 3.12, 3.13 or 3.14.
• Docker, or a native Elmer install.
• About 5 GB of free disk space. femforge doctor warns below 5 GB and fails below 2 GB.

Install the package¶

With pip, pip install "femforge[workbench]" or pip install femforge. The workbench extra installs femforge-workbench at the same version, which brings the viz extra, trame and plotly. The viz extra alone adds pyvista, vtk, matplotlib, meshio and magpylib for field rendering (femforge.viz) and the analytic cross-check (femforge.validation) without the browser workbench, which costs only 20 MB more.

The femforge-workbench package has extras of its own:

Linux system libraries¶

The gmsh wheel loads OpenGL and X11 libraries that a minimal Linux install lacks. On Debian or Ubuntu, install them with:

sudo apt-get install -y --no-install-recommends libgl1 libglu1-mesa libxrender1 libxcursor1 libxft2 libxinerama1

femforge doctor names this command when the gmsh check fails on a missing library.

Choose how Elmer runs¶

Pass the backend to the driver:

import femforge as ff

docker_driver = ff.Driver(backend=ff.elmer.DockerElmer())
native_driver = ff.Driver(backend=ff.elmer.NativeElmer())

Without a backend, the driver runs native Elmer when ElmerSolver and ElmerGrid are installed and the solve is serial, else Docker.

Before its first command, the Docker backend checks for the image. It reuses a local image built from the current recipe, else pulls the released image from GHCR. When the pull fails, or the pulled image was built from a different recipe, it builds the image locally from the recipe in femforge.elmer.runtime.docker_image. The build takes a few minutes, once. To fetch the image ahead of time, run:

femforge image pull

femforge also records ElmerSolver_mpi and an MPI launcher such as MS-MPI's mpiexec when a native install has them. A native build lacks MUMPS, so partitioned solves run only in Docker. Elmer: native and Docker covers both backends in depth.

Check the install¶

femforge doctor

The doctor prints one row per check and the fix for each failure. It exits with code 1 when a check fails. Pass --json for a machine-readable report and --runs-dir to check the disk of a runs directory other than runs.

First-run cost¶

The first run downloads about 1.2 GB of packages and, without a native Elmer, pulls a 1.3 GB image. Later runs reuse both.