Metadata-Version: 2.4
Name: eqdsk-from-cdf
Version: 0.1.1
Summary: Write G-EQDSK files directly from a single TRANSP CDF file.
Author: Antti Salmi
License-Expression: MIT
License-File: LICENSE
Keywords: cdf,eqdsk,fusion,geqdsk,plasma,transp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Requires-Dist: contourpy>=1.2
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```bash
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:

```bash
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.

## Quick Start

Convert one TRANSP CDF time slice:

```bash
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:

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

Check the install with the public bundled sample:

```bash
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:

```bash
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:

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

Higher resolution square grid:

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

Rectangular grid:

```bash
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:

```bash
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:

```bash
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:

```bash
eqdsk-from-cdf sample-path --kind cdf
```

Print the installed sample GEQ reference path:

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

Convert the bundled public sample manually:

```bash
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:

```bash
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:

```bash
./install.sh
```

Validate an existing command on `PATH` from a checkout:

```bash
./install.sh --check
```

Run checks before committing:

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

Test the built wheel like a fresh user before publishing:

```bash
uv run --isolated --with dist/eqdsk_from_cdf-0.1.1-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:

```bash
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.1"
git tag v0.1.1
git push
git push origin v0.1.1
uv publish
```

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

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

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

```bash
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.
