Installation¶

Requirements¶

Nmag currently targets Linux and Python 3.10 or newer. A normal installation needs:

Python, venv, and pip; and
a C compiler for dependencies without a wheel for your platform.

Git is only required if you choose the source checkout setup. The published package is the simplest option when you want to run Nmag without cloning the repository.

On Ubuntu or Debian:

sudo apt update
sudo apt install python3 python3-venv python3-pip build-essential

Install from PyPI¶

Create a virtual environment and install the published package:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install nmag-python-3

This installation is sufficient for normal simulations and uses the standard Python/Numba execution path. The optional native Rust accelerator is available when installing from a source checkout.

Run a simulation with:

.venv/bin/python simulation.py

Install from a source checkout¶

Clone the repository and use its setup script:

git clone https://github.com/TriMagnetix/nmag-python-3.git
cd nmag-python-3
./scripts/setup.sh

The script creates or reuses .venv, installs Nmag in editable mode, offers to build the optional Rust accelerator, and runs the standard checks. It invokes the virtual environment explicitly, so activation is not required.

Run a simulation with:

.venv/bin/python simulation.py

You may activate the environment if that is more convenient:

source .venv/bin/activate
python simulation.py

Manual source setup¶

For CI or an existing environment:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .

Normal simulations do not require Rust. To build the optional accelerator, install Rust with rustup, install the rust extra, and run the build script:

.venv/bin/python -m pip install -e '.[rust]'
./scripts/build-accelerator.sh --release

Python 3.12 accelerator builds on Ubuntu or Debian also need libpython3.12-dev. Substitute the development package matching your Python version.

Verify the installation¶

.venv/bin/python -c "import nmag; print(nmag.SI(1, 'A/m'))"

The published package exposes reusable mesh and VTK helpers directly:

from nmag import export_vtk
from nmesh import read_netgen_neutral

Then run the quickstart. If the optional accelerator was built, nmag.parallel_runtime_info() reports its effective thread configuration.

Building this documentation¶

Documentation tools are isolated in a separate extra:

.venv/bin/python -m pip install -e '.[docs]'
.venv/bin/mkdocs serve

Use mkdocs build --strict before submitting documentation changes.