Getting started

Requirements

On Linux and macOS, booz_xform is distributed as pre-compiled binary wheels for CPython 3.10 and newer, so the only requirement for installing it is python3 itself. Everything the compiled code needs is included in the wheel.

Building booz_xform from source – which happens automatically if no wheel matches your platform, and which is what you do as a developer – additionally requires a C++ compiler, cmake, and the NetCDF library. The C++ or fortran interfaces to NetCDF are not required, only the standard C interface. The pybind11 package is also required, and is installed automatically by pip.

The python interface uses arrays from the numpy package, which pip installs automatically.

OpenMP is an optional dependency. If found, OpenMP is used to parallelize the calculation over magnetic surfaces. MPI is not used.

There are some additional python packages that are optional dependencies. The Plotting routines require the matplotlib package. The python unit tests require matplotlib as well as scipy. These packages are not needed for carrying out the coordinate transformation, so they are not automatically installed by pip, and you should install them separately if you want to use these features.

Installation

There are several ways you can install booz_xform, depending on whether you are a user or developer.

1. Installation from PyPI

If you do not plan to edit the source code, the recommended way to install booz_xform is to get the latest release from PyPI using pip:

pip install booz_xform

On Linux (x86-64 and aarch64) and macOS (Apple Silicon and Intel), this downloads a pre-compiled wheel. Nothing is compiled, and NetCDF does not need to be installed on your system.

If there is no wheel for your platform – Windows, Alpine Linux, PyPy, or a CPython version newer than the latest release – pip falls back to building from the source distribution. In that case you need a C++ compiler and NetCDF, so make sure NetCDF is available on your system first; on some HPC systems, this may require loading the relevant module. You can also force a source build with:

pip install -v --no-binary booz_xform booz_xform

(the duplication at the end is intended.) At the start of the compilation step, the cmake build system will search for the NetCDF header files and libraries. Any of the environment variables NETCDF_DIR, NETCDF_HOME, or NETCDFDIR can be set to guide cmake in this search, and it will also look in standard locations such as /opt/local/include. On Apple Silicon with Homebrew, cmake does not search /opt/homebrew on its own, so you may need to set NETCDF_DIR=/opt/homebrew.

The -v flag above (for verbose output) is optional, but it is useful since it allows you to see which compiler and NetCDF libraries were used. This information can be found in the lines similar to the following in the output:

...
-- The CXX compiler identification is AppleClang 11.0.0.11000033
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
CMAKE_MODULE_PATH=
CMAKE_CURRENT_SOURCE_DIR=/private/var/folders/_2/t14gsms50v1dmfz95bz32hk00000gn/T/pip-req-build-0fgxd2du
Hello world from FindNetCDF
-- Found NetCDF: /opt/local/lib/libnetcdf.dylib
NETCDF_INCLUDES=/opt/local/include
NETCDF_LIBRARIES=/opt/local/lib/libnetcdf.dylib
...

To change the compiler that is used to build the code, you can insert CXX= followed by the compiler name before pip. For example, to use the Intel compiler icpc, use

CXX=icpc pip install -v --no-binary booz_xform booz_xform

If the installation is successful, booz_xform will be added to your python environment. You should now be able to import the module from python:

>>> import booz_xform

On some systems, you may not have permission to install packages to the default location. In this case, add the --user flag to pip so the package can be installed for your user only:

pip install -v --user booz_xform

2. Installation from a local copy of the repository

If you prefer to see or edit the source code, you can first clone the repository using

git clone https://github.com/hiddenSymmetries/booz_xform.git

Then install the package to your local python environment with

cd booz_xform
pip install -v -e .

The -e flag is not mandatory but it can be helpful during development. This flag makes the installation editable, in that edits to the pure python source in src/booz_xform are immediately reflected in the package you import into python. Without this flag, you would need to re-install the package for changes to become active.

The pip install line can be preceded by CXX= to select a specific compiler, as in the PyPI method above.

Again, if you encounter a permissions error trying to install packages to the default location, add the --user flag:

pip install -v -e --user .

3. Building outside of the python package system

If you are actively developing the code, you may wish to compile the C++ source without going through the python package system. In this case, you should have a local copy of the repository, obtained with

git clone https://github.com/hiddenSymmetries/booz_xform.git

You must also have the pybind11 python package installed, as well as cmake. The code then can be built using the usual approach for a cmake project:

cd booz_xform/build
cmake ..
make -j

In this case, the python extension library _booz_xform (with a filename usually ending in .so), the standalone executable xbooz_xform, and the library libbooz_xform.a will all be created in the build directory. Note that in this approach, no python package is installed. You can import only the Booz_xform class with import _booz_xform, which loads the compiled extension without importing the pure python functions.

The xbooz_xform command

Any of the installation options above that install the python package also install a command-line driver named xbooz_xform, which takes the same input file as the fortran booz_xform code in Stellopt:

xbooz_xform in_booz

Run it with no arguments to see a description of the input file format. The command reads wout_<extension>.nc from the current working directory and writes boozmn_<extension>.nc there.

When installed by pip, this command is a small python wrapper (booz_xform/_cli.py) around the compiled extension, so that it also works for the pre-compiled wheels. Option 3 above instead produces an equivalent standalone C++ executable of the same name, which does not require python at run time.

Checking the version

The version of booz_xform that is installed can be displayed with:

>>> import booz_xform
>>> booz_xform.__version__

This is the same version number that appears on PyPI, in the GitHub release, and in the version attribute of the boozmn_*.nc files that booz_xform writes.