Installation

Z-mag is distributed from the IBM GitHub repository https://github.com/IBM/Z-mag under the MIT License. Releases are identified by git tags following Semantic Versioning (v1.0.0, v1.1.0, …). The import name Zmag_bins is unchanged across releases; selecting a tag fixes the software version of a given installation.

The procedure below installs from a clone of the repository. To pin a specific release, check out the corresponding git tag listed in Release history before creating the conda environment.

Release history

The following table records what is in this tree. After checking out a tag, proceed with Install from that checkout.

Tag	Status	Summary
v1.0.0	First public release	Stereographic dynamic demag / nodemag solvers; hybrid FEM–BEM magnetostatics; Sphinx manual; example drivers (Standard Problem 3, precession–damping, checkpoint / restart). Requires DOLFINx / FEniCSx 0.11 (see environment.yml).
main	Development tip	Matches v1.0.0 until the next tagged release.

Subsequent releases will be recorded here as new tags are published. Detailed release notes are maintained in CHANGELOG.md at the repository root.

Install

Prerequisites

• Miniconda or Miniforge

• Git

• A C++17 compiler, CMake 3.15 or newer, and pybind11 (required to compile the BEM bindings)

1. Clone the repository

git clone https://github.com/IBM/Z-mag.git
cd Z-mag

To install a tagged release instead of main, run git fetch --tags and git checkout vX.Y.Z (see Release history).

2. Create the zmag environment

From the repository root, create and activate the conda environment named zmag:

conda env create -n zmag -f environment.yml
conda activate zmag
pip install "git+https://github.com/jorgensd/adios4dolfinx.git"

The file environment.yml specifies the FEniCSx / DOLFINx stack and companion packages (MPI, PETSc, Gmsh, meshio, ADIOS2, and related dependencies) for the checked-out release. Package pins may differ between tags; the environment.yml shipped with the selected tag must be used.

If import adios4dolfinx raises No module named 'adios2', install the MPI ADIOS2 binding:

conda activate zmag
conda install -y -c conda-forge "adios2=*=mpi_openmpi*"

3. Build the BEM bindings

Compile the C++ BEM accelerator provided in bem_assembler/cpp/. This step is required for a complete installation and is not limited to demag simulations:

cd bem_assembler/cpp
./install_python_bindings.sh --clean

If the bindings are not discovered automatically, prepend the build directory to PYTHONPATH:

export PYTHONPATH=/path/to/bem/build:${PYTHONPATH}

Confirm that the module loads:

import bem_cpp
print(bem_cpp.__version__)

4. Configure the Python path

Add the repository root to PYTHONPATH:

export PYTHONPATH="$(pwd):${PYTHONPATH}"

The factory API can then be imported as:

from Zmag_bins import create_stereo_solver

solver = create_stereo_solver(model="demag")    # or model="nodemag"

Verification

After installation, activate the environment and confirm that the principal modules import successfully:

conda activate zmag

import dolfinx
from Zmag_bins import create_stereo_solver
import bem_cpp

print(dolfinx.__version__)
print(bem_cpp.__version__)

An end-to-end check of the full stack can be performed from the repository root by running one of the included example drivers, for example:

mpirun -n 4 python test_dynamic_checkpoints.py

Build the manual

To rebuild this documentation from a source checkout:

cd Zmag_bins/docs
pip install -r requirements.txt
make html

The generated HTML is written to Zmag_bins/docs/build/html/.