Installation#

Note

These instructions have last been updated on 2025-02-04 and tested with ubuntu/raven/cobra/macOS.

Prerequisites#

GVEC requires a C and a Fortran 2003 compliant compiler. Compilers tested with GVEC include:

  • GNU Compiler Collection 9 or newer

  • Intel C/Fortran Compiler 17 or newer (recommended)

  • CMake 3.5+ as a build system

The python bindings require Python 3.10 or newer.

Additionally GVEC requires:

  • git

  • cmake

  • pkg-config

  • libc6

  • zlib

  • BLAS/LAPACK (or compatible, e.g. ATLAS, MKL)

  • netcdf library (Fortran & serial!)

On MPCDF clusters (raven, viper) we can use the module system to manage dependencies. There are prepared scripts in CI_setup that need to be sourced to load the modules, depending on the machine and the compiler. For example on raven with the latest intel compiler, use

. CI_setup/raven_setup_ifx-2025

or on viper with the latest gfortran compiler, use

. CI_setup/viper_setup_gfortran-13

Install the following packages using apt:

  • git

  • make andcmake (optionally cmake-curses-gui)

  • g++ and gfortran

  • pkg-config

  • liblapack3 and liblapack-dev

  • zlib1g-dev

  • libnetcdf-dev and libnetcdff-dev

  • python3, python3-pip, python3-dev and python3-venv (3.10 or newer)

Full command:

apt-get install git make cmake g++ gfortran pkg-config liblapack3 liblapack-dev zlib1g-dev libnetcdf-dev libnetcdff-dev python3 python3-pip python3-dev python3-venv

Tested on Ubuntu 22.04.

Install the following packages using homebrew (brew install)

  • cmake

  • netcdf-fortran

  • pkgconf

  • gcc (possibly no need to install explicitly)

  • lapack (possibly no need to install explicitly)

  • python@3.10 (or newer)

Install GVEC with pip#

The latest release of GVEC is available on PyPI and can be installed with:

pip install gvec

Currently GVEC is only available as an sdist (source-distribution) and not as a wheel (pre-compiled). This means pip will download GVEC and compile it with CMake. To see more details of the compilation process you can specify the --verbose flag. For the compilation to work properly you need to have the prerequisite system packages installed/loaded.

Installing GVEC with pip will also install the python bindings and a number of scripts, see:

pygvec --help

Installing pre-releases#

You can also tell pip to install directly from the repository:

pip install git+https://gitlab.mpcdf.mpg.de/gvec-group/gvec.git

And even specify a different branch, using @branch_name, e.g.:

pip install git+https://gitlab.mpcdf.mpg.de/gvec-group/gvec.git@main

Troubleshooting#

  • no such option --config-settings during installation

    • upgrade pip with pip install pip --upgrade

  • Cannot open include file 'netcdf.inc' during installation

    • gvec/src/vmec/vmec_readin.f90(494): error #5102: Cannot open include file 'netcdf.inc'

    • gvec cannot find netCDF

  • INTEL_MKL_ERROR when trying to use pyGVEC

    • INTEL MKL ERROR: /usr/lib/x86_64-linux-gnu/libmkl_avx2.so: undefined symbol: mkl_sparse_optimize_bsr_trsm_i8.

    • Intel MKL FATAL ERROR: Cannot load libmkl_avx2.so or libmkl_def.so.

    • you can try export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libmkl_def.so:/usr/lib/x86_64-linux-gnu/libmkl_avx2.so:/usr/lib/x86_64-linux-gnu/libmkl_core.so:/usr/lib/x86_64-linux-gnu/libmkl_intel_lp64.so:/usr/lib/x86_64-linux-gnu/libmkl_intel_thread.so:/usr/lib/x86_64-linux-gnu/libiomp5.so

  • undefined reference to EVP_KDF_CTX when trying to import gvec and using conda

    • /lib64/libk5crypto.so.3: undefined reference to EVP_KDF_CTX_new_id@OPENSSL_1_1_1b

    • this can be caused by the conda environment conflicting with system libraries. You can try: export LD_PRELOAD="/usr/lib64/libcrypto.so /usr/lib64/libssl.so"

  • on Fedora linux, it seems that the gfortran compiler needs an additional flag, in CMakeList.txt:

     set(CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} -I/usr/lib64/gfortran/modules")

Getting GVEC with git#

  1. Clone the repository to a local directory:

    Either you use the https address to clone, which always requests username and password when connecting to the mpcdf gitlab:

    git clone https://gitlab.mpcdf.mpg.de/gvec-group/gvec.git

    Or you use the git@ address to clone, in which case you have to copy your public ssh key of your machine to your profile on gitlab.mpcdf.mpg.de (typically its a .pub file in ~/.ssh, generated by ssh-keygen). Then you do not have to specify any username or password.

    git clone git@gitlab.mpcdf.mpg.de:gvec-group/gvec.git

  2. Now enter the created folder of the clone ( cd gvec )

  3. To change to the latest release, simply checkout main branch:

    git checkout main

    A list of branches on the remote is shown with git branch -r. You can change to a different branch of the GVEC repository (for a specific feature not yet available in the release) with:

    git checkout NAME_OF_BRANCH

Installing the python bindings manually#

You can install the gvec python package manually, from a cloned repository. We strongly recommend to always use a clean virtual environment for the installation, e.g.

cd gvec
python3 -m venv .venv
source .venv/bin/activate

Then you can install the gvec python package manually with

pip install .[dev,examples] -v