libneo

Common code for plasma codes of ITPcp, in particular for different NEO-2 versions.

Getting started

Prerequisites

libneo requires CMake, Ninja, GCC+GFortran, OpenMPI, a BLAS/LAPACK (OpenBLAS or MKL) and FFTW, NetCDF+NetCDF-Fortran and HDF5 including development headers.

For your own Debian or Ubuntu system, run setup/debian.sh. For usage on common computing clusters, load the modules in setup/<machine>.sh.

Build

For convenience, the build process can be automatically started by running

make

directly in the libneo directory. This will create a build subdirectory and run cmake with ninja internally.

Install Python interface

The Python interface is located in the python subdirectory. This interface is only built if python, numpy and f90wrap are available. Please activate a suitable venv first, and then run

pip install -e .

in the libneo directory for an editable build.

doc

Documentation, this includes user documentation and interface documentation. The latter is generated via doxygen.

matlab

Matlab library that contains various functions, classes and code interfaces for general and specific uses.

EFIT

A class to read/write/modify equilibrium g-files (commonly wrongly called efit files).

GPEC_interface

A minimalist interface to run the code GPEC together with DCON.

InputFile

A class that can be used to read/create/modify inputfiles that contain Fortran Namelists.

KIN

A class that can write .kin files (kinetic profiles saved column wise)

KiLCA_interface

Interface to prepare/run/postprocess the code KiLCA. A compiled version of KiLCA is needed (see here)

Shared

Shared classes and functions of the Matlab library.

Utility

Classes and functions that have a general use for many application.

python

Python interface package and scripts/functions.

Chartmap generators

Generate *.chartmap.nc volumes compatible with libneo_coordinates.

For map2disc-generated chartmaps, zeta is the cylindrical toroidal angle (zeta_convention=cyl) and rho is a geometric disk radius (rho_convention=unknown).

VMEC angle conventions (phi, zeta, nfp)

VMEC documentation commonly writes Fourier factors as exp(i*(m*theta - n*zeta)). In VMEC wout_*.nc files:

• xm stores poloidal mode numbers m.
• xn stores signed toroidal mode numbers including field periods: xn = n*nfp.
• zeta/varphi is the geometric toroidal angle in radians (often atan2(y,x)); some tools reduce it modulo one field period (2*pi/nfp), but this does not change the Fourier phase because xn already contains nfp.

So the consistent real-space evaluation with wout coefficients is:

• cos(m*theta - xn*zeta) and sin(m*theta - xn*zeta) (i.e. keep the minus inside).

For the magnetic axis, VMEC stores zaxis_cs but uses the same phase convention, so:

• Z_axis(zeta) = sum_n zaxis_cs(n) * sin(-n*nfp*zeta) (using sin(-x) = -sin(x)).

Install dependencies:

pip install -e ".[chartmap]"

Python API:

from libneo.chartmap import write_chartmap_from_vmec_boundary
write_chartmap_from_vmec_boundary("wout.nc", "wout.chartmap.nc", nrho=33, ntheta=65, nzeta=33)

CLI:

libneo-write-chartmap from-vmec wout.nc wout.chartmap.nc --nrho 33 --ntheta 65 --nzeta 33

VMEC with cubic Hermite extension beyond LCFS (no map2disc dependency, C1 continuous):

libneo-write-chartmap from-vmec-extended wout.nc wout.chartmap.nc \
    --nrho-vmec 25 --boundary-offset 0.15

This mode uses exact VMEC coordinates inside the LCFS and extends beyond using cubic Hermite interpolation along coordinate line tangents, providing C1 continuity at the boundary suitable for symplectic integrators.

VMEC extended to STL wall boundary (no map2disc dependency, C1 continuous):

libneo-write-chartmap from-vmec-to-wall wout.nc wall.stl wout.chartmap.nc \
    --rho-lcfs 0.8 --nrho 33 --ntheta 65 --nzeta 33

STL unit handling:

• STL has no unit metadata; libneo assumes meters by default.
• For engineer CAD STLs in mm, pass --stl-units mm (or --stl-scale 1e-3).

This mode combines VMEC coordinates inside the LCFS with linear interpolation to a wall boundary extracted from an STL file. The radial coordinate rho ranges from 0 to 1, where rho <= rho_lcfs corresponds to VMEC surfaces (with s = (rho/rho_lcfs)^2) and rho = 1 lies exactly on the wall boundary. Poloidal points are matched between the LCFS and wall by aligning both curves to start at their outboard midplane and interpolating by fractional position along the curve.

Coils format converter

Convert STELLOPT coils format to simple biotsavart format:

python -m libneo.convert_coils_to_simple input.coils output.simple

The simple format is compatible with libneo's neo_biotsavart module and SIMPLE code.

src

Fortran source files for the library. Subfolders contain source for additional tools, also compiled into libneo.

hdf5_tools

Interface to hdf5, to simplify calls.

magfie

MC

contrib

MyMPILib

Interface to MPI, so no actual mpi routines need to be called in programs.

poincare

Poincare plot generation for magnetic field lines. Computes field line trajectories and their intersections with toroidal cross-sections to visualize magnetic islands, chaos regions, and flux surface structure.

tests

Contains resources for tests of the library.