VMEC++

VMEC++ is a Python-friendly, from-scratch reimplementation in C++ of the Variational Moments Equilibrium Code (VMEC), a free-boundary ideal-MHD equilibrium solver for stellarators and tokamaks.

The original version was written by Steven P. Hirshman and colleagues in the 1980s and 1990s. The latest version of the original code is called PARVMEC and is available here.

Compared to its Fortran predecessors, VMEC++:

has a zero-crash policy and reports issues via standard Python exceptions
allows hot-restarting a run from a previous converged state (see Hot restart)
supports inputs in the classic INDATA format as well as simpler-to-parse JSON files; it is also simple to construct input objects programmatically in Python
typically runs just as fast or faster
comes with substantial documentation of its internal numerics

VMEC++ can run on a laptop, but it is a suitable component for large-scale stellarator optimization pipelines.

On the other hand, some features of the original Fortran VMEC are not available in VMEC++. See below for more details.

Usage
Installation
Hot restart
Differences with respect to PARVMEC/VMEC2000
Roadmap
Related repositories
License

Usage

This is a quick overview of the three main ways in which you can use VMEC++. See examples/ for some actual example scripts. Suitable input files are found in examples/data. If unsure where to start, we suggest to give the w7x case a try, which is a five-field-period stellarator case for the Wendelstein 7-X stellarator.

For example examples/force_residual_convergence.py runs fixed-boundary VMEC++ on the W7-X case and plots the convergence of the force residuals.

W7-X force residual convergence

As a Python package

VMEC++ offers a simple Python API:

import vmecpp

# Construct a VmecInput object, e.g. from a classic Fortran input file
vmec_input = vmecpp.VmecInput.from_file("input.w7x")  # or VMEC++'s w7x.json format
# This is a normal Python object: it can be constructed and modified programmatically
vmec_input.rbc[0, 0] *= 1.1

# Run VMEC++
vmec_output = vmecpp.run(vmec_input)

# Inspect the results programmatically or save them as a classic wout file
print(vmec_output.mercier.iota)
vmec_output.wout.save("wout_w7x.nc")

All other output files are accessible via members of the output object called threed1_volumetrics, jxbout and mercier.

With SIMSOPT

SIMSOPT is a popular stellarator optimization framework. VMEC++ implements a SIMSOPT-friendly wrapper that makes it easy to use it with SIMSOPT.

import vmecpp.simsopt_compat

vmec = vmecpp.simsopt_compat.Vmec("input.w7x")
print(f"Computed plasma volume: {vmec.volume()}")

As a command line tool

You can use VMEC++ directly as a CLI tool. In a terminal in which Python has access to the VMEC++ package:

# run on a given input file -> produce corresponding wout_w7x.nc
# vmecpp is a python module and can be either run with `python -m` or directly as a script
vmecpp examples/data/input.w7x

# check all options
vmecpp --help

As a Docker image

A pre-built Docker image is available at https://github.com/proximafusion/vmecpp/pkgs/container/vmecpp. Note that at present it is only updated occasionally.

See docker/README.md for more information and instructions on how to build a new image.

Installation

The easiest method for installing vmecpp is using pip:

pip install vmecpp

For usage as part of MPI-parallelized SIMSOPT applications, you might want to also install MPI on your machine and pip install mpi4py.

Alternatively you can build the latest vmecpp directly from source according to the appropriate instructions below.

Ubuntu/Debian

Ubuntu 22.04 and 24.04, as well as Debian 12 are officially supported.

Install required system packages:

sudo apt-get install -y build-essential cmake libnetcdf-dev liblapack-dev libomp-dev libhdf5-dev python3-dev

Install VMEC++ as a Python package (possibly after creating a dedicated virtual environment):

pip install git+https://github.com/proximafusion/vmecpp

The procedure will take a few minutes as it will build VMEC++ and some dependencies from source.

A common issue on Ubuntu is a build failure due to no python executable being available in PATH, since on Ubuntu the executable is called python3. When installing in a virtual environment (which is always a good idea anyways) python will be present. Otherwise the Ubuntu package python-is-python3 provides the python alias.

Arch Linux

Install required system packages:

pacman -Sy --noconfirm python-pip gcc gcc-fortran openmp hdf5 netcdf lapack

Install VMEC++ as a Python package (possibly after creating a virtual environment):

python -m pip install git+https://github.com/proximafusion/vmecpp

Fedora

Fedora 41 is officially supported.

Install required system packages:

dnf install -y python3.10-devel cmake g++ gfortran libomp-devel hdf5-devel netcdf-devel lapack-devel

Install VMEC++ as a Python package (possibly after creating a virtual environment):

# If you are installing with MPI support, remember to source the mpi compiler first
. /etc/profile.d/modules.sh
python3.10 -m pip install git+https://github.com/proximafusion/vmecpp

MacOS

Install dependencies via Homebrew:

brew install python@3.10 ninja libomp netcdf-cxx git
# And if they aren't pre-installed already:
brew install gcc cmake

Install VMEC++ as a Python package (possibly after creating a virtual environment):

# tell cmake where to find gfortran and gcc as they have non-standard names
export FC=$(which gfortran-14)
# OpenMP headers live under a different path newer OS-X versions, so CMake can't find them
export OpenMP_ROOT=$(brew --prefix)/opt/libomp
export HDF5_ROOT=$(brew --prefix hdf5)
python3.10 -m pip install git+https://github.com/proximafusion/vmecpp

As part of a conda environment

VMEC++ is currently not packaged for conda, but all its dependencies are and VMEC++ can be installed inside a conda environment. An example environment.yml file is provided here that can be used, after cloning the vmecpp repository, as:

git clone https://github.com/proximafusion/vmecpp.git
cd vmecpp
# this creates a "vmecpp" conda environment
conda env create --file environment.yml
# use the environment as usual
conda activate vmecpp

C++ build from source

After having installed the build dependencies as shown above, you can compile the C++ core of VMEC++ via CMake or Bazel. E.g. with CMake:

git clone https://github.com/proximafu

Vmecpp

Install / Use

README