XMAP Documentation

Converting EFIT Data to spdata.dat

A clean installation and usage guide for XMAP, a tool that constructs a Boozer coordinate system from a G-EQDSK file. This page walks through environment setup, dependency installation, compilation, execution, and common troubleshooting steps.

Python virtual environment NumPy SciPy gfortran Matplotlib
Recommended setup: create an isolated Python environment first, install the Python dependencies there, make sure a Fortran compiler such as gfortran is available on your system, then clone, build, and run XMAP from inside that environment.

Overview

XMAP is used to construct a Boozer coordinate system from a G-EQDSK file and write the result to spdata.dat. The workflow is straightforward: prepare the environment, compile the Fortran module, and run the Python front end.

What you need

  • uv
  • Python 3.x
  • NumPy
  • SciPy
  • Matplotlib
  • Fortran compiler, such as gfortran

Detailed installation guide

1

Create and activate a virtual environment

Start by creating a dedicated environment with uv. This keeps the XMAP dependencies isolated from your system Python installation. Keep the environment active throughout the installation and

Environment setup
uv 
uv venv .venv
source .venv/bin/activate
2

Install the Python packages

Install the runtime Python libraries in the virtual environment.

Python dependencies
uv pip 
uv pip install numpy scipy matplotlib
3

Make sure a Fortran compiler is installed

XMAP builds a Fortran component, so the system must have a working Fortran compiler. gfortran is a common choice on Linux systems. You can look up how to install it on Windows or Mac online from here .

If the build step fails, the most common cause is a missing compiler or a missing development package required by the local Python/Fortran toolchain.
4

Clone the repository

Download the source code from GitHub and enter the project directory.

Get the source code
git 
git clone https://github.com/brokenhammer/xmap.git
cd xmap
5

Compile the Fortran module

Build the project with make. Run this command from inside the repository directory.

Compile
make 
make
6

Run the program

After the build completes successfully, activate the virtual environment if it is not already active, and start the driver script.

Execute XMAP
python 
python run.py

Example interactive run

When the script starts, it will prompt for the input G-file path and several mapping parameters. A typical run looks like this:

Sample session terminal 
python run.py
Please input path of gfile:
./g157102.02420
Please input npsi (=lsp in GTC and spdata), default: 91

Please input ntheta (=lst in GTC, =lst+1 in spdata), default: 122

Ratio of last mapping flux surface to LCFS: 0.995. Use --psimax=[value] to specify other value.
Please enter the output file path, default: './spdata.dat'

Reading gfile...
Begin mapping...
WARNING:root:Negative g detected. Enforce it to be positive...
Begin writing...
Finished writing to ./spdata.dat

You can keep the default values of npsi , ntheta and for the name of output file.

The warning shown above can be ignored in this workflow. Once the run finishes, spdata.dat will be created in the current folder.

Troubleshooting

  • Compilation fails immediately: verify that make is installed and that a Fortran compiler such as gfortran is available on your PATH.
  • Missing Python modules: reinstall the dependencies inside the active virtual environment using uv pip install ....
  • f2py not found: ensure NumPy is installed correctly, since f2py is typically provided with it.
  • Runtime file not found: confirm that the path to the G-file is correct before launching run.py.
XMAP Installation Guide · Converting EFIT Data to spdata.dat