Installation¶

Requirements¶

• Python 3.10 or newer.

• pip with network access to install runtime wheels and the Python dependencies.

• A Cargo/Rust toolchain is not required for Python authoring alone, but the repository build tooling uses it to produce the native FDM/FEM solver bundle.

• Finite-element meshing with the geometry workflow additionally needs the optional meshing extras (gmsh, manifold3d, meshio, scipy, trimesh).

Install the Python DSL¶

Clone the repository and install the embedded Python package:

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

Install the optional meshing dependencies when you author FEM geometry:

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

Verify that the module imports:

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

Prepare a solver runtime¶

The fm.study(...) API is solver-agnostic, but execution needs a compiled backend. The repository owns a justfile that wraps the container and host build paths. The default local runtime is built with:

just build fullmag

This stages the launcher and the finite-difference library under .fullmag/local. The easiest headless run is then:

just run-headless examples/fdm_cpu_relax_smoke.py

For a first interactive launch, just fullmag build=True fdm cpu <script> builds on first use and then runs the script with the Control Room.

The finite-element runtime uses MFEM, hypre, libCEED and (on GPU) CUDA. It is built and executed through the repository’s managed container recipes rather than ad-hoc host commands:

just ensure-managed-fem-runtime

FDM CUDA and FEM GPU paths additionally require a managed CUDA runtime. GPU execution must be qualified with device identity recorded in the result; compiling on a host is not proof that GPU code executed.

Checking the installation¶

Bare imports validate the Python layer only. A complete check is to run one of the repository’s small stage-first smoke scripts headlessly and confirm that a result artifact is produced. The first FDM simulation and first FEM simulation pages use the same workflow.

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 {doc}``/python-api/index 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¶

• No new implementation symbol is introduced by this guide. The exact Python source symbol is owned by the linked terminal API page and the runnable example.