eqdsk-from-cdf 0.1.2

Write G-EQDSK files directly from a single TRANSP CDF file.

eqdsk-from-cdf

Convert a single TRANSP CDF equilibrium slice into a G-EQDSK file from the command line.

The package is intended for quick local conversion workflows: install the command, point it at a TRANSP CDF file, choose the target time and sign convention explicitly, and write a GEQDSK file that can be checked with the bundled validation sample.

Install

Install from PyPI:

python -m pip install eqdsk-from-cdf

For command-line-only use, pipx is also a good option because it keeps the application and its dependencies isolated:

pipx install eqdsk-from-cdf

If eqdsk-from-cdf is not found after install, make sure ~/.local/bin is on your PATH.

The package requires Python 3.9 or newer.

Cluster Or HPC Environments

On shared systems, preloaded modules, PYTHONPATH, or user-site packages can make pip mix packages from different Python versions. If installation behaves strangely, create a clean environment first:

deactivate 2>/dev/null || true
unset PYTHONPATH PYTHONHOME
python3.9 -m venv --clear ~/venvs/eqdsk39
source ~/venvs/eqdsk39/bin/activate
python -m pip install --upgrade pip
python -m pip install --upgrade --no-cache-dir eqdsk-from-cdf
eqdsk-from-cdf validate

If your cluster uses environment modules, also unload unrelated Python/scientific modules before creating the venv. The key point is to avoid mixing a Python 3.9 venv with packages from older system Python paths.

Quick Start

Convert one TRANSP CDF time slice:

eqdsk-from-cdf run.CDF --time 17.5 --bt-sign 1 --ip-sign 1 --out out.geq

If --out is omitted, the output is written next to the input with a .geq suffix:

eqdsk-from-cdf run.CDF --time 17.5 --bt-sign 1 --ip-sign 1

Check the install with the public bundled sample:

eqdsk-from-cdf validate

validate regenerates a GEQDSK from the bundled sample CDF and compares it against the bundled sample GEQ reference. It does not depend on private reference files.

Main Options

CDF_PATH is the input TRANSP CDF file.

--time SECONDS selects the requested TRANSP time slice in seconds.

--bt-sign {-1,1} sets the toroidal magnetic field sign.

--ip-sign {-1,1} sets the plasma current sign.

--out PATH sets the output GEQDSK path. Without it, run.CDF becomes run.geq.

--nr N and --nz N set the output GEQDSK R and Z grid sizes. The defaults are 129 and 129. Larger grids preserve more spatial detail but produce larger files and take longer to generate. Common choices are 129x129, 257x257, or rectangular grids such as 128x192.

--plot PATH saves a conversion diagnostic plot.

--show displays the diagnostic plot interactively.

Run the built-in help for the full command reference:

eqdsk-from-cdf --help

Sign Convention

Viewed from above the machine, looking along +Z, +1 means counter-clockwise and -1 means clockwise.

Both --bt-sign and --ip-sign are required. This is intentional: the converter does not guess sign conventions silently.

Resolution Examples

Default grid:

eqdsk-from-cdf run.CDF --time 17.5 --bt-sign 1 --ip-sign 1 --out out.geq

Higher resolution square grid:

eqdsk-from-cdf run.CDF --time 17.5 --bt-sign 1 --ip-sign 1 --nr 257 --nz 257 --out out_257.geq

Rectangular grid:

eqdsk-from-cdf run.CDF --time 17.5 --bt-sign 1 --ip-sign 1 --nr 128 --nz 192 --out out_128x192.geq

Diagnostic Plots

Save a plot while converting:

eqdsk-from-cdf run.CDF --time 17.5 --bt-sign 1 --ip-sign 1 --out out.geq --plot conversion.png

Show the same plot interactively:

eqdsk-from-cdf run.CDF --time 17.5 --bt-sign 1 --ip-sign 1 --show

The plot overlays reconstructed moment surfaces, generated Psi(R,Z) contours, boundary, limiter, magnetic axis, and profile curves.

Bundled Sample

Print the installed sample CDF path:

eqdsk-from-cdf sample-path --kind cdf

Print the installed sample GEQ reference path:

eqdsk-from-cdf sample-path --kind geq

Convert the bundled public sample manually:

sample="$(eqdsk-from-cdf sample-path --kind cdf)"
eqdsk-from-cdf "$sample" --time 17.50435 --bt-sign 1 --ip-sign 1 --out sample.geq

Compare GEQDSK Files

Print scalar/profile differences and save a visual comparison:

reference="$(eqdsk-from-cdf sample-path --kind geq)"
eqdsk-from-cdf compare sample.geq "$reference" --output compare.png

If --output is omitted, the comparison plot is shown interactively.

Contour Extraction

Computational contour extraction uses contourpy directly. Matplotlib contour calls are used only for diagnostic plotting.

Development

Install from a local checkout:

./install.sh

Validate an existing command on PATH from a checkout:

./install.sh --check

Run checks before committing:

uv run --extra dev ruff check .
uv run pytest -q
uv build

Test the built wheel like a fresh user before publishing:

uv run --isolated --with dist/eqdsk_from_cdf-0.1.2-py3-none-any.whl eqdsk-from-cdf validate

Release Notes For Maintainers

Work from pypi-main; it is the clean public-history branch. Use feature branches from pypi-main for larger changes.

Before releasing, bump version in pyproject.toml, run the checks above, commit, tag, push, and publish:

git switch pypi-main
uv run --extra dev ruff check .
uv run pytest -q
uv build
git add -A
git commit -m "Release 0.1.2"
git tag v0.1.2
git push
git push origin v0.1.2
uv publish

uv publish needs PyPI credentials. One option is to export a PyPI API token as UV_PUBLISH_TOKEN before publishing:

export UV_PUBLISH_TOKEN="pypi-..."
uv publish

For interactive use, avoid leaving the token in shell history:

read -s UV_PUBLISH_TOKEN
export UV_PUBLISH_TOKEN
uv publish

For long-term use, store the token in a password manager or another secure secret store. If a token is exposed accidentally, revoke it on PyPI and create a new one.

Each PyPI release should have an immutable Git tag, for example v0.1.0, v0.1.1, or v0.2.0.

The public package carries only the bundled sample CDF and bundled sample GEQ used by eqdsk-from-cdf validate. Private reference checks, portability scripts, and scratch generated files should stay local or ignored.