{"id":28834570,"url":"https://github.com/proximafusion/vmecpp","last_synced_at":"2026-02-13T16:52:50.855Z","repository":{"id":275103248,"uuid":"887571250","full_name":"proximafusion/vmecpp","owner":"proximafusion","description":" From-scratch C++ and Python reimplementation of the Variational Moments Equilibrium Code (VMEC).","archived":false,"fork":false,"pushed_at":"2026-02-11T01:31:22.000Z","size":8141,"stargazers_count":206,"open_issues_count":27,"forks_count":30,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-11T02:12:30.654Z","etag":null,"topics":["fusion","mhd-simulation","plasma","stellarator","stellarators"],"latest_commit_sha":null,"homepage":"https://proximafusion.github.io/vmecpp/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proximafusion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-11-12T22:51:16.000Z","updated_at":"2026-02-11T00:49:02.000Z","dependencies_parsed_at":"2025-03-24T08:27:13.740Z","dependency_job_id":"027ef4c5-c8f7-409c-9a35-74ec79775dc9","html_url":"https://github.com/proximafusion/vmecpp","commit_stats":null,"previous_names":["proximafusion/vmecpp"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/proximafusion/vmecpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proximafusion%2Fvmecpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proximafusion%2Fvmecpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proximafusion%2Fvmecpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proximafusion%2Fvmecpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proximafusion","download_url":"https://codeload.github.com/proximafusion/vmecpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proximafusion%2Fvmecpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29412668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T06:24:03.484Z","status":"ssl_error","status_checked_at":"2026-02-13T06:23:12.830Z","response_time":78,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fusion","mhd-simulation","plasma","stellarator","stellarators"],"created_at":"2025-06-19T09:33:45.316Z","updated_at":"2026-02-13T16:52:50.848Z","avatar_url":"https://github.com/proximafusion.png","language":"C++","funding_links":[],"categories":["Tools"],"sub_categories":["Simulation and Modeling Frameworks"],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/user-attachments/assets/978b76bc-cd9b-4af8-b1f3-18efde7c079f\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/user-attachments/assets/ec4e391a-9044-44ae-93f0-9dd8bed70001\"\u003e\n  \u003cimg alt=\"A dark Proxima logo in light color mode and a light one in dark color mode.\" src=\"https://github.com/user-attachments/assets/ec4e391a-9044-44ae-93f0-9dd8bed70001\" width=400px\u003e\n\u003c/picture\u003e\n\n# VMEC++\n\n\u003c!--\n[![PyPI - Version](https://img.shields.io/pypi/v/vmecpp.svg)](https://pypi.org/project/vmecpp)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vmecpp.svg)](https://pypi.org/project/vmecpp)\n--\u003e\n\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![MIT license](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)\n![Python version](https://img.shields.io/badge/python-3.10-blue)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14800158.svg)](https://doi.org/10.5281/zenodo.14800158)\n\n[![CI](https://github.com/proximafusion/vmecpp/actions/workflows/tests.yaml/badge.svg)](https://github.com/proximafusion/vmecpp/actions/workflows/tests.yaml)\n[![C++ core tests](https://github.com/proximafusion/vmecpp/actions/workflows/test_bazel.yaml/badge.svg)](https://github.com/proximafusion/vmecpp/actions/workflows/test_bazel.yaml)\n[![Publish wheels to PyPI](https://github.com/proximafusion/vmecpp/actions/workflows/pypi_publish.yml/badge.svg)](https://github.com/proximafusion/vmecpp/actions/workflows/pypi_publish.yml)\n\nVMEC++ is a Python-friendly, from-scratch reimplementation in C++ of the Variational Moments Equilibrium Code (VMEC),\na free-boundary ideal-MHD equilibrium solver for stellarators and tokamaks.\n\nThe original version was written by Steven P. Hirshman and colleagues in the 1980s and 1990s.\nThe latest version of the original code is called `PARVMEC` and is available [here](https://github.com/ORNL-Fusion/PARVMEC).\n\nCompared to its Fortran predecessors, VMEC++:\n- has a zero-crash policy and reports issues via standard Python exceptions\n- allows hot-restarting a run from a previous converged state (see [Hot restart](#hot-restart))\n- 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\n- typically runs just as fast or faster\n- comes with [substantial documentation of its internal numerics](https://github.com/proximafusion/vmecpp/blob/main/docs/the_numerics_of_vmecpp.pdf)\n\nVMEC++ can run on a laptop, but it is a suitable component for large-scale stellarator optimization pipelines.\n\nOn the other hand, some features of the original Fortran VMEC are not available in VMEC++.\nSee [below](#differences-with-respect-to-parvmecvmec2000) for more details.\n\n\u003c!-- NOTE: if you change the intro above, remember to also adapt docs/index.md! --\u003e\n\n-----\n\n## Table of Contents\n\n- [Usage](#usage)\n  - [As a Python package](#as-a-python-package)\n  - [With SIMSOPT](#with-simsopt)\n  - [As a command line tool](#as-a-command-line-tool)\n  - [As a Docker image](#as-a-docker-image)\n- [Installation](#installation)\n  - [Ubuntu](#ubuntudebian)\n  - [Arch](#arch-linux)\n  - [Fedora](#fedora)\n  - [MacOS](#macos)\n  - [As part of a conda environment](#as-part-of-a-conda-environment)\n  - [C++ build from source](#c-build-from-source)\n- [Hot restart](#hot-restart)\n- [Differences with respect to PARVMEC/VMEC2000](#differences-with-respect-to-parvmecvmec2000)\n- [Roadmap](#roadmap)\n- [Related repositories](#related-repositories)\n- [License](#license)\n\n\u003c!-- SPHINX-START1 --\u003e\n\n## Usage\n\nThis is a quick overview of the three main ways in which you can use VMEC++.\nSee [examples/](https://github.com/proximafusion/vmecpp/blob/main/examples/) for some actual example scripts.\nSuitable input files are found in [`examples/data`](https://github.com/proximafusion/vmecpp/blob/main/examples/data).\nIf unsure where to start, we suggest to give the [`w7x`](https://github.com/proximafusion/vmecpp/blob/main/examples/data/w7x.json) case a try, which is a five-field-period stellarator case for the [Wendelstein 7-X](https://www.ipp.mpg.de/w7x) stellarator.\n\nFor example [`examples/force_residual_convergence.py`](https://github.com/proximafusion/vmecpp/blob/main/examples/force_residual_convergence.py) runs fixed-boundary VMEC++ on the W7-X case and plots the convergence of the force residuals.\n\u003c!-- SPHINX-END1 --\u003e\n![W7-X force residual convergence](docs/w7x_force_convergence.png)\n\u003c!-- SPHINX-START2 --\u003e\n\n### As a Python package\n\nVMEC++ offers a simple Python API:\n\n```python\nimport vmecpp\n\n# Construct a VmecInput object, e.g. from a classic Fortran input file\nvmec_input = vmecpp.VmecInput.from_file(\"input.w7x\")  # or VMEC++'s w7x.json format\n# This is a normal Python object: it can be constructed and modified programmatically\nvmec_input.rbc[0, 0] *= 1.1\n\n# Run VMEC++\nvmec_output = vmecpp.run(vmec_input)\n\n# Inspect the results programmatically or save them as a classic wout file\nprint(vmec_output.mercier.iota)\nvmec_output.wout.save(\"wout_w7x.nc\")\n```\n\nAll other output files are accessible via members of the `output` object called `threed1_volumetrics`, `jxbout` and `mercier`.\n\n### With SIMSOPT\n\n[SIMSOPT](https://simsopt.readthedocs.io) is a popular stellarator optimization framework.\nVMEC++ implements a SIMSOPT-friendly wrapper that makes it easy to use it with SIMSOPT.\n\n```python\nimport vmecpp.simsopt_compat\n\nvmec = vmecpp.simsopt_compat.Vmec(\"input.w7x\")\nprint(f\"Computed plasma volume: {vmec.volume()}\")\n```\n\n### As a command line tool\n\nYou can use VMEC++ directly as a CLI tool.\nIn a terminal in which Python has access to the VMEC++ package:\n\n```console\n# run on a given input file -\u003e produce corresponding wout_w7x.nc\n# vmecpp is a python module and can be either run with `python -m` or directly as a script\nvmecpp examples/data/input.w7x\n\n# check all options\nvmecpp --help\n```\n\n### As a Docker image\n\nA pre-built Docker image is available at https://github.com/proximafusion/vmecpp/pkgs/container/vmecpp.\nNote that at present it is only updated occasionally.\n\nSee [docker/README.md](https://github.com/proximafusion/vmecpp/blob/main/docker/README.md) for\nmore information and instructions on how to build a new image.\n\n## Installation\n\nThe easiest method for installing `vmecpp` is using pip:\n```shell\npip install vmecpp\n```\n\nFor usage as part of MPI-parallelized SIMSOPT applications, you might want to also install MPI on your machine and `pip install mpi4py`.\n\nAlternatively you can build the latest `vmecpp` directly from source according to the appropriate instructions below.\n\n### Ubuntu/Debian\n\nUbuntu 22.04 and 24.04, as well as Debian 12 are officially supported.\n\n1. Install required system packages:\n```shell\nsudo apt-get install -y build-essential cmake libnetcdf-dev liblapack-dev libomp-dev libhdf5-dev python3-dev\n```\n\n2. Install VMEC++ as a Python package (possibly after creating a dedicated virtual environment):\n\n```shell\npip install git+https://github.com/proximafusion/vmecpp\n```\n\nThe procedure will take a few minutes as it will build VMEC++ and some dependencies from source.\n\nA 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`.\nWhen installing in a virtual environment (which is always a good idea anyways) `python` will be present.\nOtherwise the Ubuntu package `python-is-python3` provides the `python` alias.\n\n### Arch Linux\n\n1. Install required system packages:\n\n```shell\npacman -Sy --noconfirm python-pip gcc gcc-fortran openmp hdf5 netcdf lapack\n```\n\n2. Install VMEC++ as a Python package (possibly after creating a virtual environment):\n\n```shell\npython -m pip install git+https://github.com/proximafusion/vmecpp\n```\n\n### Fedora\n\n[Fedora 41](https://docs.fedoraproject.org/en-US/fedora/f41/release-notes/) is officially supported.\n\n1. Install required system packages:\n\n```shell\ndnf install -y python3.10-devel cmake g++ gfortran libomp-devel hdf5-devel netcdf-devel lapack-devel\n```\n\n2. Install VMEC++ as a Python package (possibly after creating a virtual environment):\n\n```shell\n# If you are installing with MPI support, remember to source the mpi compiler first\n. /etc/profile.d/modules.sh\npython3.10 -m pip install git+https://github.com/proximafusion/vmecpp\n```\n\n\n### MacOS\n\n1. Install dependencies via [Homebrew](https://brew.sh/):\n\n```shell\nbrew install python@3.10 ninja libomp netcdf-cxx git\n# And if they aren't pre-installed already:\nbrew install gcc cmake\n```\n\n2. Install VMEC++ as a Python package (possibly after creating a virtual environment):\n\n```shell\n# tell cmake where to find gfortran and gcc as they have non-standard names\nexport FC=$(which gfortran-14)\n# OpenMP headers live under a different path newer OS-X versions, so CMake can't find them\nexport OpenMP_ROOT=$(brew --prefix)/opt/libomp\nexport HDF5_ROOT=$(brew --prefix hdf5)\npython3.10 -m pip install git+https://github.com/proximafusion/vmecpp\n```\n\n### As part of a conda environment\n\nVMEC++ is currently not packaged for conda, but all its dependencies are and VMEC++\ncan be installed inside a conda environment. An example `environment.yml` file is\nprovided [here](https://github.com/proximafusion/vmecpp/blob/main/environment.yml) that\ncan be used, after cloning the `vmecpp` repository, as:\n\n```shell\ngit clone https://github.com/proximafusion/vmecpp.git\ncd vmecpp\n# this creates a \"vmecpp\" conda environment\nconda env create --file environment.yml\n# use the environment as usual\nconda activate vmecpp\n```\n\n### C++ build from source\n\nAfter having installed the build dependencies as shown above, you can compile\nthe C++ core of VMEC++ via CMake or Bazel. E.g. with CMake:\n\n```shell\ngit clone https://github.com/proximafusion/vmecpp.git\ncd vmecpp\ncmake -B build  # create and configure build directory\ncmake --build build --parallel  # build VMEC++\n# you can now use the vmec_standalone C++ executable to run VMEC on a VMEC++ input JSON file, e.g.\n./build/vmec_standalone ./examples/data/solovev.json\n```\n\nThe main C++ source code tree is located at [`src/vmecpp/cpp/vmecpp`](https://github.com/proximafusion/vmecpp/blob/main/src/vmecpp/cpp/vmecpp).\n\n## Hot restart\n\nBy passing the output of a VMEC++ run as initial state for a subsequent one,\nVMEC++ is initialized using the previously converged equilibrium.\nThis can dramatically decrease the number of iterations to convergence when running\nVMEC++ on a configuration that is very similar to the converged equilibrium.\n\n### Example\n\n```python\nimport vmecpp\n\ninput = vmecpp.VmecInput.from_file(\"w7x.json\")\n\n# Base run\noutput = vmecpp.run(input)\n\n# Now let's perturb the plasma boundary a little bit...\ninput.rbc[0, 0] *= 0.8\ninput.rbc[1, 0] *= 1.2\n# ...and fix up the multigrid steps: hot-restarted runs only allow a single step\ninput.ns_array = input.ns_array[-1:]\ninput.ftol_array = input.ftol_array[-1:]\ninput.niter_array = input.niter_array[-1:]\n\n# We can now run with hot restart:\n# passing the previously obtained output ensures that\n# the run starts already close to the equilibrium, so it will take\n# very few iterations to converge this time!\nhot_restarted_output = vmecpp.run(input, restart_from=output)\n```\n\n## Full tests and validation against the reference Fortran VMEC v8.52\n\nWhen developing the C++ core, it's advisable to locally run the full C++ tests for debugging or to validate changes before submitting them.\nThe full tests are not stored in the sources of this repo, but in a separate repo: https://github.com/proximafusion/vmecpp_large_cpp_tests .\nSee the instructions there for how to run those tests locally. The CI of this repo includes those tests too.\n\nThe single-thread runtimes as well as the contents of the \"wout\" file produced by VMEC++ can be compared with those of Fortran VMEC v8.52.\nThe full validation test can be found at https://github.com/proximafusion/vmecpp-validation, including a set of sensible input configurations,\nparameter scan values and tolerances that make the comparison pass. See that repo for more information.\n\n## Differences with respect to PARVMEC/VMEC2000\n\nVMEC++:\n- reports issues via standard Python exceptions and has a zero crash policy\n- allows hot-restarting a run from a previous converged state (see [Hot restart](#hot-restart))\n- 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\n- employs the same parallelization strategy as Fortran VMEC, but VMEC++ leverages OpenMP for a multi-thread implementation rather than Fortran VMEC's MPI parallelization: as a consequence it cannot parallelize over multiple nodes\n- implements the iteration algorithm of Fortran VMEC 8.52, which sometimes has different convergence behavior from (PAR)VMEC 9.0: some configurations might converge with VMEC++ and not with (PAR)VMEC 9.0, and vice versa\n\n### Limitations with respect to the Fortran implementations\n- non-stellarator-symmetric terms (`lasym == true`) are not supported yet\n- free-boundary works only for `ntor \u003e 0` - axisymmetric (`ntor = 0`) free-boundary runs don't work yet\n- `lgiveup`/`fgiveup` logic for early termination of a multi-grid sequence is not implemented yet\n- `lbsubs` logic in computing outputs is not implemented yet\n- `lforbal` logic for non-variational forces near the magnetic axis is not implemented yet\n- `lrfp` flag is available for wout compatibility, but RFP-specific physics is not implemented yet - only stellarators/Tokamaks for now\n- several profile parameterizations are not fully implemented yet:\n   * `gauss_trunc`\n   * `two_power_gs`\n   * `akima_spline`\n   * `akima_spline_i`\n   * `akima_spline_ip`\n   * `cubic_spline`\n   * `cubic_spline_i`\n   * `cubic_spline_ip`\n   * `pedestal`\n   * `rational`\n   * `nice_quadratic`\n   * `sum_cossq_s`\n   * `sum_cossq_sqrts`\n   * `sum_cossq_s_free`\n- some (rarely used) free-boundary-related output quantities are not implemented yet:\n   * `curlabel` - declared but not populated yet\n   * `potvac` - declared but not populated yet\n   * `xmpot` - not declared yet\n   * `xnpot` - not declared yet\n- 2D preconditioning using block-tridiagonal solver ([`BCYCLIC`](https://www.sciencedirect.com/science/article/abs/pii/S0021999110002536)) is not implemented;\n  neither are the associated input fields `precon_type` and `prec2d_threshold`\n- VMEC++ only computes the output quantities if the run converged\n- The Fortran version falls back to fixed-boundary computation if the `mgrid` file cannot be found; VMEC++ (gracefully) errors out instead.\n- The Fortran version accepts both the full path or filename of the input file as well as the \"extension\", i.e., the part after `input.`; VMEC++ only supports a valid filename or full path to an existing input file.\n\n## Roadmap\n\nSome of the things we are planning for VMEC++'s future:\n- [x] free-boundary hot-restart in Python\n- [X] open-sourcing the full VMEC++ test suite (including the Verification\u0026Validation part that compares `wout` contents)\n- [x] open-sourcing the source code to reproduce VMEC++'s performance benchmarks\n- [ ] VMEC++ usable as a C++ bazel module\n\nSome items we do not plan to work on, but where community ownership is welcome:\n- [ ] packaging VMEC++ for platforms or package managers other than pip (e.g. conda, homebrew, ...)\n- [ ] native Windows support\n- [ ] ARM support\n- [ ] 2D preconditioner using [`bcyclic_plus_plus`](https://code.ornl.gov/m4c/bcyclic_plus_plus)\n\n## Related repositories\n\n* [`proximafusion/vmecpp-validation`](https://github.com/proximafusion/vmecpp-validation) - Validation tests for VMEC++\n* [`proximafusion/vmecpp_large_cpp_tests`](https://github.com/proximafusion/vmecpp_large_cpp_tests) - Large C++ tests for VMEC++\n* [`proximafusion/the_numerics_of_vmecpp`](https://github.com/proximafusion/the_numerics_of_vmecpp) - Documentation of the numerical details of VMEC++\n* [`proximafusion/vmecpp-benchmarks`](https://github.com/proximafusion/vmecpp-benchmarks) - Performance benchmarks comparing VMEC++ and VMEC2000\n\n## License\n\n`vmecpp` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproximafusion%2Fvmecpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproximafusion%2Fvmecpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproximafusion%2Fvmecpp/lists"}