BZX - Boozer to GKV Coordinate Transformations

BZX is a Python package that transforms BOOZ_XFORM Boozer coordinate metrics into GKV field-aligned coordinates, enabling gyrokinetic analysis of VMEC equilibria.

Installation

To install from PyPI:

pip install bzx

Or install the latest development version from GitHub:

pip install git+https://github.com/GKV-developers/bzx.git

If your environment has any problems with installation, you can copy the single source script file bzx.py from the src/bzx/ directory and use it.

Usage

(i) Basic usage: Convert to GKV input file using BZX

Prepare VMEC equilibrium output (e.g. wout.nc) and its BOOZ_XFORM output (e.g. boozmn.nc).

from bzx import bzx

# Define transformation parameters
Ntheta_gkv = 1   # N_theta value in GKV
nrho = 11        # Radial grid points
ntht = 64        # Poloidal grid points
nzeta = 0        # Toroidal grid points (nzeta=0 corresponds to output GKV field-aligned coordinates)
alpha_fix = 0.0  # Field-line label: alpha = zeta - q*theta (not used for nzeta > 0)

# Run BZX transformation
bzx(Ntheta_gkv, nrho, ntht, nzeta, alpha_fix, 
    fname_boozmn="boozmn.nc", fname_wout="wout.nc", 
    output_file="./metric_boozer.bin.dat")

• Reads VMEC output file (wout.nc) and BOOZ_XFORM output file (boozmn.nc). NetCDF format is recommended, but Binary format is also acceptable.
• Converts them into field-aligned data and saves the result as GKV input binary file (metric_boozer.bin.dat).
• Note: some BOOZ_XFORM versions (e.g. the Python package booz_xform==0.0.9) write phi_b = 0 into boozmn.nc. BZX detects this automatically and recovers the edge toroidal flux from the phi variable of wout.nc (a NetCDF wout is required in this case), printing a warning to stdout and log_BZX.dat.

(ii) Example of workflow: From VMEC to GKV via BOOZ_XFORM and BZX

The script examples/run_vmecpp_boozxform_bzx.ipynb demonstrats how to use BZX, starting from generating an equilibrium.

• Step 1: Compute a MHD equilibrium using VMEC++

  • About VMEC++ :
    • Proxima Fusion - VMEC++
    • GitHub - vmecpp

• Step 2: Convert the VMEC output to Boozer coordinates using BOOZ_XFORM

  • About BOOZ_XFORM :
    • BOOZ_XFORM Documentation
    • GitHub - BOOZ_XFORM
    • BOOZ_XFORM - STELLOPT

• Step 3: Convert the BOOZ_XFORM output to GKV coordinates using BZX

  • This project.

(iii) As a command line tool

After installation, you can use BZX directly as a CLI tool in a terminal, e.g.,

python -m bzx --Ntheta_gkv 1 --nrho 11 --ntht 64 \
              --nzeta 0 --alpha_fix 0.0 \
              --fname_boozmn "boozmn.nc" --fname_wout "wout.nc" \
              --output_file "./metric_boozer.bin.dat"

All arguments of bzx function is specified by keyword arguments. See also help.

python -m bzx --help

Dependencies

BZX requires the following Python packages:

• numpy, scipy, xarray
• (Optional) matplotlib for visualization in examples/
• (Optional) booz_xform for examples/run_vmecpp_boozxform_bzx.py
• (Optional) vmecpp for examples/run_vmecpp_boozxform_bzx.py

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Developed by Shinya Maeyama (maeyama.shinya@nifs.ac.jp)