OVFToolkit

OVFToolkit reads, writes, validates, converts, and processes OOMMF vector-field (OVF) files. Most users will want one of two things:

1. the ovftoolkit Python package for NumPy-based analysis; or
2. the ovf-convert and ovf-batchfft command-line tools.

The C++23 parser underneath them reads OVF 1.0 and 2.0 files, rectangular and irregular meshes, text and binary data, and multi-segment files. Segments are loaded lazily, so memory use follows the data currently being processed rather than the total file size.

OVFToolkit is available on PyPI:

python -m pip install ovftoolkit

To install the latest source checkout instead:

git clone --recurse-submodules https://github.com/Artemkth/OVFToolkit.git
cd OVFToolkit
python -m pip install .

Published ABI3 wheels require only Python 3.12 or newer and NumPy. Python 3.10 and 3.11 remain supported through source installation, which additionally needs a C++23 compiler, Boost headers, and Python development headers. Install those prerequisites with one of:

# Debian, Ubuntu, and derivatives
sudo apt update
sudo apt install build-essential libboost-dev python3-dev python3-venv

# Arch Linux and derivatives
sudo pacman -S --needed base-devel boost python

# Fedora
sudo dnf install gcc-c++ boost-devel python3-devel

The Python build frontend supplies nanobind and a sufficiently recent CMake in an isolated build environment.

Fields expose writable NumPy arrays. Files and their segments are lazy and can be iterated without loading the complete dataset:

import ovftoolkit as ovf

with ovf.reader("input.ovf") as source:
    for field in source:
        analyse(field.data)

Create a file by assigning a rectangular rank-4 or irregular rank-2 array. dummy_header fills the required rectangular-grid metadata from the array shape and cell size:

field = ovf.VField()
field.data = array
field.dummy_header((dx, dy, dz))
field.header[ovf.OVFParameter.Title] = "Example"

with ovf.writer("output.ovf") as destination:
    destination.write(field)

For rectangular fields with coordinate metadata, meshgrid() returns cell-center coordinate arrays aligned with the field data:

x, y, z = field.meshgrid()
assert x.shape == y.shape == z.shape == field.data.shape[:-1]

Copy metadata between fields without overwriting the destination data shape:

destination.header.copy_from(source.header)

Working programs live in examples/. In particular, create_ovf.py creates a normalized in-plane vortex and plot_ovf.py renders an OVF layer with NumPy and Matplotlib. More examples will be linked here as they are added.

For local notebook work:

python -m pip install jupyterlab matplotlib
jupyter lab

Detailed usage is documented in the ovf-convert and ovf-batchfft manuals.

When packaged builds are available, they are attached to the GitHub releases. Unpack the Windows archive and run the executables from its bin directory; the portable archive carries the runtime DLLs it needs. CUDA archives additionally require a compatible NVIDIA GPU and driver.

For a complete CPU build containing both tools:

# Debian, Ubuntu, and derivatives
sudo apt update
sudo apt install build-essential cmake ninja-build \
  libboost-program-options-dev libfftw3-dev libhdf5-dev libtbb-dev libvtk9-dev

# Arch Linux and derivatives
sudo pacman -S --needed base-devel cmake ninja boost boost-libs fftw hdf5 \
  onetbb vtk netcdf

# Fedora
sudo dnf install gcc-c++ cmake ninja-build boost-devel fftw-devel hdf5-devel \
  tbb-devel vtk-devel netcdf-devel

OVFToolkit requires CMake 3.30 or newer. Some long-term-support distributions ship an older CMake; in that case use a newer CMake package or a temporary Python environment:

python3 -m venv .venv-build
. .venv-build/bin/activate
python -m pip install "cmake>=3.30"

With the dependencies installed, the complete build is deliberately short:

git submodule update --init --recursive
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DOVFTOOLKIT_BUILD_TOOLS=ON -DOVFTOOLKIT_USE_CUFFT=OFF
cmake --build build
cmake --install build --prefix "$HOME/.local"

The tools are installed under $HOME/.local/bin. Add that directory to PATH if it is not already present. To run the test suite before installing:

ctest --test-dir build --output-on-failure

Install Visual Studio 2022 with the C++ workload, CMake 3.30 or newer, Git, and vcpkg. Set VCPKG_ROOT to your vcpkg directory. Forward slashes are used below so paths such as C:\Users\... are never interpreted by CMake as escape sequences.

VTK warning: the default Windows build includes ovf-convert, so vcpkg builds VTK and its large dependency tree. A clean build can take a long time and many gigabytes. If you only need ovf-batchfft, use one of the no-VTK configurations below.

Build both CPU tools, including VTK/HDF5 conversion and FFTW analysis:

$toolchain = "$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake".Replace('\', '/')
cmake -S . -B build -A x64 `
  "-DCMAKE_TOOLCHAIN_FILE=$toolchain" `
  -DOVFTOOLKIT_BUILD_TOOLS=ON `
  -DOVFTOOLKIT_USE_CUFFT=OFF
cmake --build build --config Release --parallel
cmake --install build --config Release --prefix build/stage

Build only the FFTW-based ovf-batchfft, without downloading or building VTK:

$toolchain = "$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake".Replace('\', '/')
cmake -S . -B build-fftw -A x64 `
  "-DCMAKE_TOOLCHAIN_FILE=$toolchain" `
  -DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON `
  -DVCPKG_MANIFEST_FEATURES=fftw `
  -DOVFTOOLKIT_BUILD_TOOLS=ON `
  -DOVFTOOLKIT_USE_FFTW=ON `
  -DOVFTOOLKIT_USE_CUFFT=OFF
cmake --build build-fftw --config Release --parallel
cmake --install build-fftw --config Release --prefix build-fftw/stage

Or build only the CUDA/cuFFT version without VTK or FFTW:

$toolchain = "$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake".Replace('\', '/')
cmake -S . -B build-cuda -A x64 -T cuda=12.9 `
  "-DCMAKE_TOOLCHAIN_FILE=$toolchain" `
  -DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON `
  -DOVFTOOLKIT_BUILD_TOOLS=ON `
  -DOVFTOOLKIT_USE_FFTW=OFF `
  -DOVFTOOLKIT_USE_CUFFT=ON
cmake --build build-cuda --config Release --parallel
cmake --install build-cuda --config Release --prefix build-cuda/stage

The staged executables and any required dynamic-library dependencies are placed together in the stage bin directory. Change cuda=12.9 to the installed CUDA toolset version.

The vcpkg manifest has two default features:

• convert supplies the VTK/HDF5 stack for ovf-convert;
• fftw supplies the CPU backend for ovf-batchfft.

VCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON is therefore the switch that avoids the large conversion stack. Enabling fftw explicitly adds FFTW back without adding VTK.

Optional project components use the same three-state convention:

The main settings are OVFTOOLKIT_BUILD_TOOLS, OVFTOOLKIT_BUILD_PYTHON_BINDING, OVFTOOLKIT_BUILD_WOLFRAM_BINDING, OVFTOOLKIT_BUILD_MUMAX_RUNNER, and OVFTOOLKIT_BUILD_DOCS. FFT backends are selected independently with OVFTOOLKIT_USE_FFTW and OVFTOOLKIT_USE_CUFFT.

The separately licensed mumax controller is packaged from tools/mumax-runner as ovftoolkit-mumax-runner; it does not bundle CUDA, mumax3, or mumax-slave.

The ovfparser C++23 library is always built. Its public interface uses std::span, std::mdspan, std::expected, concepts, and RAII ownership. A bundled Kokkos mdspan implementation is used when the standard library does not yet provide a sufficiently recent std::mdspan.

When Doxygen is available, build the API documentation with:

cmake --build build --target ovftoolkit-docs

Most original OVFToolkit source is distributed under the MIT License. The exception is tools/mumax-runner/, which is a separate GPL-3.0-or-later distribution because its Go executable incorporates mumax3. Third-party source and libraries retain their own licenses.

The license requirements of a binary depend on the components linked into it:

See LICENSING.md for the release checklist and precise scope, and THIRD_PARTY_NOTICES.md for the dependency inventory. Packaged artifacts must carry the verbatim notices for the exact direct and transitive libraries they contain; for vcpkg builds these are under vcpkg_installed/<triplet>/share/<port>/copyright.