CAS3D#

Warning

This feature is experimental and likely does not yet produce the expected results.

This is the interface to the MHD stability code CAS3D [1]. It can be used to convert a GVEC equilibrium (parameterfile & statefile) into specialized netCDF file that can be read by CAS3D.

The interface is installed automatically with pyGVEC and available with pygvec to-cas3d.

Usage#

Install GVEC with python bindings as normal. The pygvec executable with the pygvec to-cas3d subcommand will be added to the binary folder (e.g. venv/bin/, which is also added to $PATH). Then you should simply be able to execute:

pygvec to-cas3d parameter.ini GVEC_State_0000_00000100.dat GVEC_BoozFT-CAS3D.nc --ns 3 --MN_out 10 10 --stellsym

which will produce the GVEC_BoozFT-CAS3D.nc netCDF file to be used with CAS3D.

The other options for pygvec to-cas3d are:

$ pygvec to-cas3d --help
usage: pygvec to-cas3d [-h] --ns NS --MN_out MN_OUT MN_OUT [--MN_booz MN_BOOZ MN_BOOZ] [--sampling SAMPLING] [--stellsym] [--pointwise POINTWISE] parameterfile statefile outputfile

Convert a GVEC equilibrium to be used in CAS3D

positional arguments:
  parameterfile         input GVEC parameter-file
  statefile             input GVEC state-file
  outputfile            output netCDF file

options:
  -h, --help            show this help message and exit
  --ns NS               number of flux surfaces (equally spaced in s=rho^2) (required)
  --MN_out MN_OUT MN_OUT
                        maximum fourier modes in the output (M, N) (required)
  --MN_booz MN_BOOZ MN_BOOZ
                        maximum fourier modes for the boozer transform (M, N)
  --sampling SAMPLING   sampling factor for the fourier transform and surface reparametrization
  --stellsym            filter the output for stellarator symmetry
  --pointwise POINTWISE
                        output pointwise data to a separate file

Note that per default pygvec to-cas3d will be parallelized with OpenMP and you can set the number of threads (for example 20) before running the converter as an environment variable, with

export OMP_NUM_THREADS=20

Note

The Boozer Transform is limiting both the performance and memory usage of the converter. A higher resolution (e.g. --MN_out 16 32 --sampling 4) can require significant amounts of RAM (e…g more than 32GiB).

Interface#

The netCDF export for CAS3D contains a number of flux surfaces, equidistantly spaced in the normalized toroidal flux. On each surface the magnetic field, metric tensor and second fundamental form is described using fourier coefficients. The specific quantities and their definitions are found below.

Coordinates#

CAS3D uses a flux aligned coordinate system with a radial coordinate $s\in[0,1]$, proportional to the normalized toroidal flux, and two angular coordinates $\vartheta,\zeta\in[0,1]$. Note that the first radial position in the output is not the $s=0$ surface, but $s=10^{-8}$ to avoid the singularity at the axis. The two angles are Boozer-straight-fieldline-angles, that is the components of the magnetic field $B_\vartheta(s),B_\zeta(s),\mathcal{J}B^\vartheta(s),\mathcal{J}B^\zeta(s)$ are constant on each fluxsurface. The $\vartheta=0$ surface is on the outward side of the device and $\vartheta,\zeta$ both increase in the counter-clockwise direction when viewed from the front or above respectively. This makes the $(s,\vartheta,\zeta)$ coordinate system left-handed ($\mathcal{J} < 0$) (and is similar to a COCOS[2] number of 3/5/13/15).

Warning

The placement of the $\vartheta=0$ contour is not guaranteed by the converter right now. The expected position of that contour for a generalized axis-following frame is however not clearly defined.

Warning

ToDo: this derivation assumes that $\zeta=[0,1]$ on the whole device for CAS3D, that is that $\zeta=[0,\frac{1}{N_{FP}}]$ on one field period.

In terms of the GVEC Boozer-coordinates $(\rho,\vartheta_B,\zeta_B)$, the CAS3D flux coordinates are:

\[ s = \rho^2, \qquad \vartheta = -\sigma\frac{1}{2\pi} \vartheta_B, \qquad \zeta = \sigma\frac{1}{2\pi} \zeta_B, \]

where $\sigma=1$ if the GVEC reference frame ($h$-map) is defined with counter-clockwise $\zeta$ direction and $\sigma=-1$ otherwise. The derivatives are then:

\[ \frac{ds}{d\rho} = 2\rho, \qquad \frac{d\vartheta}{d\vartheta_B} = -\sigma\frac{1}{2\pi}, \qquad \frac{d\zeta}{d\zeta_B} = \sigma\frac{1}{2\pi}.\]

The derived quantities are then transformed as shown here

field-periodic representation#

If the number of field periods is >1, the flux surface positions $x,y,z$ in cartesian coordinates are not periodic on one field-period. A transformation to field-periodic variables $\hat{x},\hat{y},\hat{z}$ is possible, using the toroidal parameterization $\zeta\in[0,2\pi]$, see Guiliani et. al. [3]. The transform forflux surface with $\vartheta$ poloidal and $\zeta$ toroidal parameterization is then defined as:

\[\begin{split} \begin{align} \hat{x}(\vartheta,\zeta) &:=\quad x(\vartheta,\zeta)\cos(2\pi\zeta)+y(\vartheta,\zeta)\sin(2\pi\zeta), \\ \hat{y}(\vartheta,\zeta) &:=-x(\vartheta,\zeta)\cos(2\pi\zeta)+y(\vartheta,\zeta)\cos(2\pi\zeta), \\ \hat{z}(\vartheta,\zeta) &:=\quad z(\vartheta,\zeta) \end{align} \end{split}\]

and its inverse

\[\begin{split} \begin{align} x(\vartheta,\zeta) &:= \hat{x}(\vartheta,\zeta)\cos(2\pi\zeta) - \hat{y}(\vartheta,\zeta)\sin(2\pi\zeta), \\ y(\vartheta,\zeta) &:= \hat{x}(\vartheta,\zeta)\cos(2\pi\zeta) + \hat{y}(\vartheta,\zeta)\cos(2\pi\zeta), \\ z(\vartheta,\zeta) &:= \hat{z}(\vartheta,\zeta), \end{align} \end{split}\]

With stellarator-symmetry, $\hat{x}$ is an even periodic function on a field period and $\hat{y},\hat{z}$ are odd periodic functions on a field period.