Installation

Last changes: Documentation changelog

FullMag separates the Python authoring layer from the solver runtime. The Python package defines the fm.study(...) and fm.connect() workflows and lowers models to the canonical ProblemIR; a container-backed or compiled backend executes the solve. This page installs the published Python package from PyPI (or from source) and sets up the daily Docker Compose DEV workspace.

Requirements

  • Python 3.10 or newer.

  • pip or uv to install fullmag and its Python dependencies.

  • Git and Docker (Docker Desktop Linux engine on Windows PowerShell, or Linux/WSL2 Docker integration) for running the solver runtime and Control Room. just is recommended for the repository recipes (just docker-dev, just docker-dev-toolchain).

  • Host Cargo/Rust and CMake are not required: the backend container builds Rust and native FEM/FDM solvers inside Docker using isolated named volumes.

  • Finite-element geometry and meshing require the optional meshing extra (gmsh, manifold3d, meshio, scipy, trimesh).

Install the Python DSL

From PyPI

The public Python authoring package and live HTTP/WebSocket client are published on PyPI (fullmag):

pip install fullmag

With uv:

uv add fullmag            # in a uv project
uv pip install fullmag    # in an existing environment

Optional extras install additional authoring and interactive capabilities:

Extra

Included dependencies

Intended workflow

meshing

gmsh, manifold3d, meshio, scipy, trimesh

FEM geometry and conformal domain meshing

figures

Pillow

Image-based material and texture authoring

jupyter

ipython, matplotlib

Interactive notebooks and fullmag.live.jupyter.monitor()

Combine extras as needed, for example:

pip install "fullmag[meshing,figures,jupyter]"

The PyPI distribution is pure Python. It provides model authoring, ProblemIR serialization, and the live API client (fm.connect()), which drives a running FullMag Docker DEV group over HTTP and WebSocket. It does not bundle the native FDM/FEM solver libraries: without a connected server session or repository runtime, fm.relax() and fm.run() return a Result with status="not-executable".

From a source checkout

To install the editable or development Python package straight from a repository checkout:

git clone https://github.com/MateuszZelent/fullmag
cd fullmag
python -m pip install ./packages/fullmag-py

Install optional extras in the same way when authoring FEM meshes or Jupyter notebooks:

python -m pip install "./packages/fullmag-py[meshing,jupyter]"

Verify that the module imports:

python -c "import fullmag; print(fullmag.__file__)"

Prepare the Docker Compose DEV runtime

Daily FullMag development runs inside a per-checkout Docker Compose group (fullmag-master for the main checkout, or fullmag-worktree-<worktree_id> for a registered Git worktree). Each group contains two permanent services: backend (which compiles changed Rust/C++ targets incrementally and serves the API + native FDM/FEM runtime) and frontend (Next.js Control Room dev server with HMR).

2. Configure host storage once

Before starting any build, configure FULLMAG_PROJECT_STORAGE_ROOT in the main checkout’s local .env (worktrees inherit it automatically from the main checkout via Git):

python -B scripts/setup_docker.py
python -B scripts/setup_docker.py --check

Use python3 in Linux/WSL shells. This wizard writes only the storage root, checkout selection, and default frontend port into .env and never starts or deletes containers. User sessions, Zarr results, projects, and settings stay in the configured host storage; build caches, Cargo/pnpm packages, and compilation artifacts live in Docker named volumes and BuildKit (with ADR 0076 defining the single group-private named volume architecture splitting private/backend, private/frontend, and private/ledger alongside shared fullmag-shared-* caches).

3. Build the toolchain and start services

Run from the root of the main checkout or registered worktree you want to work in:

just docker-dev-toolchain
just docker-dev "$PWD"
  • just docker-dev-toolchain builds the pinned container dependency image (docker/fem-gpu/Dockerfile, including CMake, MFEM, hypre, libCEED, and CUDA headers). This step is only slow on the first host setup.

  • just docker-dev "$PWD" validates mounts and storage, builds the backend inside the permanent backend container, and starts both the API runtime and Control Room on http://127.0.0.1:3197 (or the next free port printed by the launcher).

  • To run a single checkout script non-interactively once the group is running with an empty workspace, call just docker-dev-script examples/fdm_cpu_relax_smoke.py; to ensure services are up and execute a script in one step, run just fullmag-dev-container examples/fdm_cpu_relax_smoke.py.

Do not invoke plain docker compose up, host cargo/cmake, or retired host-runner commands: the managed launcher records source, package, storage, and startup provenance before starting any service.

Both FDM CUDA and FEM GPU lanes run inside the container runtime when NVIDIA GPU access is enabled (--gpu-access auto or explicit GPU selection). Executed GPU evidence still requires the resolved device identity to be recorded in the simulation provenance; host build completion alone does not qualify GPU parity.

Checking the installation

Bare imports verify the Python layer only. Confirm end-to-end execution by running one of the tracked stage-first smoke scripts through your DEV group, or by connecting a live session with fm.connect() and running the first FDM simulation or first FEM simulation tutorials.

Control Room crosswalk

Use the authoring path stated in this guide, normally Model Explorer -> Objects followed by the relevant Geometry, Material, Physics, Mesh, or Stage panel. Any parameter shown in Python but not shown in that path is TODO: frontend support; do not describe it as configurable in the UI. See Control Room capability register.

Python/API crosswalk

The runnable Python example and exact argument contract are authoritative. If this guide is conceptual or does not contain a runnable example, it explicitly defers to the linked Python API page rather than duplicating an unverified signature.

Physics, limitations, and bibliography

Use the linked physics or numerical-methods page for governing equations and assumptions. This onboarding page does not add a new physical model. Bibliography: see the linked terminal API or physics page; no additional source is claimed here.

Source-code index

  • packages/fullmag-py/pyproject.toml — [project], [project.optional-dependencies]: Python requirement and [meshing], [figures], [jupyter] extras.

  • justfile — docker-dev-toolchain, docker-dev, docker-dev-script, fullmag-dev-container: managed Docker Compose DEV launcher recipes.

  • scripts/setup_docker.py — interactive/check setup wizard for .env storage and port bindings.

  • scripts/docker_dev.py and scripts/bootstrap_docker_toolchain.py — Docker Compose group bootstrap, mount/storage preflight, backend build/start, and script execution.

  • scripts/fullmag_storage.py — resolve_layout: project/worktree/storage identity and path validation.