VAFT - Versatile Analysis Framework for Tokamak

English | 한국어

PyPI Python License

VAFT is an open-source Python library that functions both as a dedicated data platform for the VEST (Versatile Experiment Spherical Torus) tokamak at Seoul National University and as a machine- and code-generic data analysis framework built upon the IMAS data model, providing an IMAS-compliant data interface built on the OMAS interface library and an HSDS remote HDF5 database.

Hong-Sik Yun, Sunjae Lee et al 2025 Plasma Phys. Control. Fusion 67 115021 (doi:10.1088/1361-6587/ae1b6a)

Key Features

Architecture

VEST Data Analysis Platform
├── Automated Pipeline (Snakemake)     ── experiment → postprocessing → simulation
├── Database (IMAS-HSDS)                ── per-shot HDF5 storage via REST API
└── Interface (VAFT)                    ── data access, mapping, processing, visualization

Available IMAS IDSs in the VEST Database

Experimental: dataset_description · magnetics · tf · pf_active · barometry · spectrometer_uv · thomson_scattering · charge_exchange

Modelling: wall · em_coupling · pf_passive · equilibrium (EFIT/CHEASE) · core_profiles · mhd_linear (DCON/RDCON)

Quick Start

Installation

Install from source (recommended):

git clone https://github.com/VEST-Tokamak/vaft.git
cd vaft
python -m pip install -e .

# Development tooling
python -m pip install -e ".[dev]"

Legacy NumPy 1 installation

Use this only for an external package that still requires NumPy 1. Because h5pyd==0.20.0 declares a NumPy 2 requirement, install it with --no-deps after replacing NumPy:

python -m pip install -e .
python -m pip install --force-reinstall --no-deps "numpy>=1.26.4,<2"
python -m pip install --force-reinstall --no-deps h5pyd==0.20.0

This is a legacy compatibility option; pip check may report the intentionally bypassed NumPy requirement.

Install from PyPI (obsolete):

pip install vaft

Supported Python: 3.10 -- 3.13 Numerical stack default: NumPy 2.x (numpy>=2.0.0,<3)

Connect to the VEST Database

If you will use the remote VEST HSDS database, configure your HSDS credentials:

hsconfigure

Enter the following when prompted:

A connection ok message confirms you are connected. See the detailed guide for more information.

Basic Usage

import vaft

# Load a shot from the remote database
ods = vaft.database.load(39915)

# Access IMAS-structured data directly
time = ods['magnetics.time']
ip = ods['magnetics.ip.0.data']

load is the eager path for complete ODS exports and workflows that need a local IMAS staging set. Without paths it stages the complete shot; with paths=["equilibrium"] it stages only that IDS plus dataset_description and uses a validated local domain cache by default. For exploratory access to selected leaves, use the direct lazy path, which opens only the requested IDS domain and transfers only the dataset selections that are read:

When byte-exact per-IDS images are available, eager loads use them by default to avoid the many requests made by hsget. Use transport="canonical" to bypass derived images or transport="h5image" to require them. Direct lazy open() always keeps canonical selection-based access.

with vaft.database.open(39915, source="public", paths="equilibrium") as ods:
    psi = ods["equilibrium.time_slice.0.profiles_2d.0.psi"]

The lazy API supports occurrence 0 in this first version. Native IDS use the explicit remote representation:

equilibrium = vaft.database.load(
    39915, source="public", representation="imas", paths="equilibrium"
)

Remote saves keep canonical IMAS images authoritative and can publish derived caches alongside them. derived_cache="auto" creates per-IDS images; the historical full-ODS cache remains readable but is only created explicitly. The choices are "none", "imas-images", "omas", and "both".

For experimental native lazy access without a local staging directory, open an IMAS handle. It returns a read-only, lazy IDSToplevel; each requested leaf is read directly from the corresponding HSDS IDS domain. This first version supports occurrence 0 and an exact stored IMAS DD version.

with vaft.database.open(
    39915, source="public", representation="imas", paths="equilibrium"
) as handle:
    psi = handle.get().time_slice[0].profiles_2d[0].psi

Local artifacts are deliberately separate from the HSDS API. They are content-detected rather than selected by a format flag:

ods = vaft.omas.load("./shot/master.h5")
with vaft.imas.load("./equilibrium.nc") as entry:
    equilibrium = entry.get("equilibrium")

See the HSDS lazy and per-IDS h5image report for the architecture, cache policy, and shot 39915 benchmark results.

Profile Fitting

# Map Thomson scattering data onto equilibrium flux coordinates, then fit profiles
mapped_rho = vaft.process.equilibrium_mapping_thomson_scattering(ods, geq)
vaft.process.profile_fitting_thomson_scattering(
    ods, time_ms, mapped_rho, fitting_function_te='gp', fitting_function_ne='gp'
)

IMAS Conversion

# Write an OMAS ODS as an IMAS HDF5 image set or a native IMAS NetCDF file
vaft.imas.save(ods, "./shot")
vaft.imas.save(ods, "./shot.nc")

Library Modules

vaft/
├── database/          # Remote database access (HSDS, raw SQL)
├── machine_mapping/   # Native-to-IDS diagnostic conversion (70+ functions)
├── formula/           # Physics formulas (equilibrium, stability, Green's functions)
├── process/           # Signal processing, EM modeling, profile fitting
├── plot/              # Visualization (time, 1D, 2D, top-view, analysis)
├── omas/              # ODS utilities (shot metadata, sample data)
├── imas/              # IMAS-Python (AL5) interoperability
├── code/              # Code interfaces (EFIT, CHEASE, GPEC, Snakemake)
└── data/              # Sample data, geometry assets, calibration tables

Example Notebooks

Related Resources

• Documentation: vest-tokamak.github.io/vaft
• Paper: H.-S. Yun, S. Lee et al, "Developing an IMAS-compatible platform for the university-scale tokamak VEST and its application to operating characteristics analysis", Plasma Phys. Control. Fusion 67 115021 (2025). doi:10.1088/1361-6587/ae1b6a
• OMAS: gafusion.github.io/omas — Python API for IMAS data structures
• OMFIT: omfit.io — Integrated modeling and experimental data analysis framework for tokamak research
• HSDS: github.com/HDFGroup/hsds — HDF5 REST-based data service
• IMAS: github.com/iterorganization/IMAS-Data-Dictionary — ITER Integrated Modelling & Analysis Suite

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

For database write access, contact peppertonic18@snu.ac.kr, satelite2517@snu.ac.kr.

Acknowledgements

The authors would like to thank O Meneghini and J McClenaghan at General Atomics for their technical advice. Some parts of the data processing were performed using the code API in the OMFIT integrated modeling framework [1]. This research was supported by the National Research Foundation of Korea (NRF) grant funded by the Korean Government (MSIT) (RS-2021-NR057187, RS-2023-00281276, RS-2024-00409564, and RS-2025-02304810).

Third-party Notices

OPEN-ADAS atomic routines

Parts of VAFT's OPEN-ADAS ADF11 parsing, interpolation, default-file selection, and ionization-equilibrium logic are adapted from software distributed under the following license.

MIT License

Copyright (c) 2021 Francesco Sciortino

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

OMFIT classes compatibility port

VAFT's native EQDSK compatibility and interoperability paths include behavior ported or adapted from omfit_classes. VAFT also provides compatibility shims for the corresponding legacy NumPy, SciPy, and xarray interfaces. The original OMFIT classes software is distributed under the following license.

Copyright 2013-2021 the OMFIT contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.