This branch contains 38 notebooks. The page inventories every one of them; the output cards below are published separately and are described under Verified notebook outputs.
The notebooks are at two different levels of maturity, and it saves a lot of time to know which is which before you open one:
Design shells are marked (design shell) below.
The figures below were exported on 2026-08-21 with MPLBACKEND=Agg and VAFT_DOCS_READ_ONLY=1, from a commit and a branch that no longer exist, by an exporter that has since been removed from the repository. Every image still matches its recorded checksum, but none of them can be tied to the notebook that produced it, because the notebooks have moved on. They are kept as legacy artifacts and are labelled as such in _data/notebook_outputs.yml; regenerating them is tracked in issue #156. Treat them as illustrative, not as current output.
notebooks/database_initialization_and_load.ipynbf7c97ecf5f92a355e870cc0d77b0006cf4fa437f5e49e638db856dd5be53df3f9301167e833591d9591c6463b60269be75f22c0e1e8d47008d9f167216cd828eOpen TXT artifact — Lazy-ODS metadata returned by a live read-only HSDS request.
notebooks/database_initialization_and_load.ipynbf7c97ecf5f92a355e870cc0d77b0006cf4fa437f5e49e638db856dd5be53df3fb638972489ba5c784ec52851a624be8d9f6d09706cb91d93b2a9d94cb72f65a6Open TXT artifact — Root-IDS comparison before and after a local compressed-JSON round trip.
notebooks/read_and_convert_data_structure.ipynbab0bdecbfe70ed117ccac0611f8dcd994d1feaee889645f0236365c3fd5a95bc5e0522ddb6c3c459d38c96a5261350b45ca84fa58d61f69c9094609c4f1505b2
notebooks/fluctuation_diagnostics_analysis.ipynba41968189104e0047c9867e1e0b772ca2f1519da270bd384cdf1fd89ea11e21a17c631ea70e35f0383f66c53b6adec638df27f7cedee9edd4c302fb22ec899f1
notebooks/kinetic_efit_end_to_end.ipynb789fdf1591de3f8d87777e9bcb6f8c549a6f43f0bcf535900735782c2f3915f2a90e3861a2c18382e478a24526b8a5354d769266e679744d56362215028a7453
Open TXT artifact — Prepared-file and executable-readiness report.
notebooks/equilibrium_refinement_using_chease.ipynb9e2b221eab484bbba055e0aed1a9690c831233c4f4a7df2bf5fc05f26ff0de8c680abc32c64b5e9ba8b296cec3468e1e128a9fef2d35b3c9de094fa4ed28e0c714b3d14bb3ab6776adb80e7e4078499a9211d4bff0f3de9907055e112882f3bcOpen TXT artifact — Optional external-code configuration status without credential or secret values.
notebooks/initialize_external_fusion_codes.ipynba7169d5ceb351ee781d059ba8189e46b7ab696e67a39723484cac25d29ebbdaf5412b49b5173c00f81d994d25e585d0b2e0c28cfef8df5cb1ccbb34b7b665708
Open TXT artifact — Row count and mean confinement metrics.
notebooks/confinement_time_scaling.ipynb02f602010db261dd6eb71cbba5334ad2854e325c14907bfb325c56d85979f812d589ce0aa5c2a8669532a7832f1a7464854d204da5b11d479bef4bd81ebb705d0e0a93ed6eb137150fe0a0991db52306bd14fb5caffd8386789bd02c2d04c393
Open TXT artifact — Machine-readable workflow stage and output summary.
notebooks/automated_pipeline_overview.ipynba04dd9ff3b1c8b9a6a4b888374977a041b1236e7644a1d8ae71d99904657250f8c78973028a647a5a398cfb816ebdc9c040ee621d5f8ff04921550eeee778165193e1ba7806cc3ebb3d41f53391264780a48cf0197d03cd55c9bb2e3a83b06ad| Notebook | Purpose |
|---|---|
database_initialization_and_load.ipynb |
Install VAFT, verify the HSDS connection, list public shots, and load a shot into an ODS. |
vest_experimental_data_list.ipynb |
Tour of IMAS/OMAS concepts and of which VEST diagnostics are mapped into the database today. |
vest_raw_signal_sql_database.ipynb |
Reach the legacy SQL DAQ store: field codes, slow vs fast channels, and raw waveform retrieval. |
verify_exist_shot_and_load.ipynb |
Inspect published-shot status and verify selected read paths without changing the remote namespace. |
Start here. This is the shortest path from a fresh install to a shot in memory.
import vaft
# Is the HSDS backend reachable?
print(vaft.database.is_connect())
# Which shots are published?
shots = vaft.database.exist_shot("public")
# Load one shot as an OMAS ODS
ods = vaft.database.load(39915, directory="public")
vaft.database.load is the canonical entry point: it returns an OMAS ODS, and it also accepts an explicit ids_name= keyword when you want a native IMAS IDS instead. See Database for the full surface.
If you have no network access, every example below can also be driven from the packaged sample data described in the next section.
| Notebook | Purpose |
|---|---|
read_and_convert_data_structure.ipynb |
Walk an equilibrium ODS key by key — equilibrium.time_slice, profiles_1d, and the rest of the hierarchy. |
imas_omas_data_conversion.ipynb |
Bridge OMAS ODS objects and native IMAS AL5 HDF5 storage, in both directions. |
The packaged samples are the fastest way to get a realistic ODS without touching the network:
import vaft
ods = vaft.omas.sample_ods() # one shot
odc = vaft.omas.sample_odc() # a collection of three shots
list(ods.keys())
print(ods["equilibrium.time"])
print(list(ods["equilibrium.time_slice.0"].keys()))
To reach a packaged file by name rather than through the sample helpers, use the resource accessor — it resolves paths inside the installed package:
from vaft.data.resources import data_path
sample_path = data_path("omas/39915.json")
For the IMAS round trip:
from vaft.imas import save_omas_imas, load_omas_imas
save_omas_imas(ods, user="test_user", machine="VEST", pulse=39915, run=0)
ods_back = load_omas_imas(user="test_user", machine="VEST", pulse=39915, run=0)
Related reading: Data structures and Machine mapping.
| Notebook | Purpose |
|---|---|
magnetic_diagnostics_processing.ipynb |
(design shell) Planned preprocessing, filtering, calibration, and sign conventions for ip, flux loops, and poloidal probes. |
soft_x_ray_signal_analysis.ipynb |
Map digitizer CSVs into a soft X-ray ODS, then plot lines of sight, signals, and spectrograms. |
fluctuation_diagnostics_analysis.ipynb |
Mirnov coil fluctuation work: spectrograms, toroidal mode spectra, and mode-number fits. |
fast_camera_video_analysis.ipynb |
(design shell) Planned camera image and video loading, plasma-behavior observation, and synchronization. |
The soft X-ray notebook is a good template for “raw file to ODS to plot” in one pass:
from vaft.machine_mapping.soft_x_rays import soft_x_rays_from_digitizer_csv
from vaft.plot import plot_soft_x_ray_los, plot_soft_x_ray_signal, plot_soft_x_ray_spectrogram
ods = soft_x_rays_from_digitizer_csv(shot, daq_label, digitizer_file=plasma_file)
plot_soft_x_ray_los(ods, arrays=["lowermid", "bottom"])
plot_soft_x_ray_signal(ods)
plot_soft_x_ray_spectrogram(ods)
See Magnetics and Processing.
| Notebook | Purpose |
|---|---|
equilibrium_refinement_using_chease.ipynb |
Refine a GEQDSK with CHEASE: build EXPEQ and the namelist, resolve the binary, run, collect outputs. |
forward_equilibrium_using_TES.ipynb |
Forward (Grad-Shafranov) equilibrium solve with TES, driven straight from an ODS. |
forward_equilibrium_using_TokaMaker.ipynb |
Forward free-boundary equilibrium with TokaMaker (Open FUSION Toolkit), driven by measured PF coil currents. |
time_dependent_equilibrium_using_TokaMaker.ipynb |
Vessel eddy currents, wall eigenmodes, quasi-static shot evolution, and vertical-stability growth rates with TokaMaker. |
free_boundary_pf_coil_scan.ipynb |
Free-boundary PF-coil-current scans: commanded against materialized currents, per-case topology classification, and resumable continuation. |
analytic_solovev_equilibrium.ipynb |
Constant-source analytic Solov’ev construction, verified against the gridded field. |
local_miller_equilibrium_fitting.ipynb |
Local Miller fitting, its reconstruction errors, and where it stops working near the separatrix. |
parametric_equilibrium_descriptors.ipynb |
Convention-aware global descriptors, and GEQDSK against ODS parity. |
edge_and_boundary_representation.ipynb |
Limiter and diverted topology, X-points, gaps, and separatrix balance. |
initialize_external_fusion_codes.ipynb |
Read-only readiness checks for the GPECHOME, CHEASEHOME, EFITHOME, and TESHOME conventions. |
electromagnetic_response_modeling_with_efund.ipynb |
(design shell) Planned EFUND response modeling over wall geometry, PF active and PF passive structures. |
eddy_current_calculation_and_startup_analysis.ipynb |
(design shell) Planned PF-passive eddy-current ODE solve and tokamak startup / null analysis. |
magnetic_equilibrium_reconstruction_with_efit.ipynb |
(design shell) Planned EFIT reconstruction from magnetics, eddy currents, and PF coil information. |
mhd_equilibrium_analysis.ipynb |
(design shell) Planned equilibrium loading, representative quantities, and coordinate transformations. |
linear_ideal_stability_analysis_with_dcon.ipynb |
(design shell) Planned ideal MHD stability (delta-W) with DCON from the GPEC package. |
linear_resistive_stability_analysis_with_rdcon.ipynb |
(design shell) Planned resistive stability (Delta-prime) with RDCON. |
perturbed_equilibrium_and_3d_response_with_gpec.ipynb |
(design shell) Planned perturbed equilibrium and non-axisymmetric 3D response with GPEC. |
CHEASE is the most complete code-coupling example in the repository. The prepare_* / run_* / collect_* triple is the pattern every code wrapper in vaft.code follows:
from vaft.data import read_geqdsk
from vaft.data.resources import data_path
from vaft.code.chease import CHEASEConfig, prepare_chease_inputs, find_chease_executable
initial = read_geqdsk(data_path("efit/g039915.00319"))
ods = initial.to_omas()
config = CHEASEConfig(workdir=workdir)
inputs = prepare_chease_inputs(initial, config) # writes EXPEQ + chease_namelist
executable = find_chease_executable(config) # None if CHEASE is not installed
TES shows the same idea starting from a database shot rather than a file:
import vaft
from vaft.code import tes
ods = vaft.database.load(39915)
cfg = tes.TESConfig(
executable=RTES,
workdir=WORKDIR,
shot=39915,
time=0.325,
bt0=0.15, # fix the toroidal field; omit to read it from the tf IDS
eddy=True, # treat pf_passive as eddy coils
)
inputs = tes.prepare_tes_inputs(ods, cfg)
Both binaries are optional: the notebooks degrade to input generation when the executable is absent. See Equilibrium and Stability.
| Notebook | Purpose |
|---|---|
profile_fitting_using_equilibrium_and_kinetic_diagnostics.ipynb |
Map Thomson scattering onto equilibrium flux surfaces to fit core Te and ne profiles. |
kinetic_efit_end_to_end.ipynb |
Build electron and ion profiles from the paired shot 48224 repository inputs at 300 ms. |
confinement_time_scaling.ipynb |
Single-shot workflow test, then a dataset-wide confinement-time scaling and regression study. |
tokamak_power_balance.ipynb |
Ohmic input against radiated and conducted losses, with an Aurora-based impurity treatment. |
The profile notebook is the largest runnable example that stays inside pure VAFT:
import vaft
ods = vaft.database.load(40330, directory="public")
vaft.plot.plot_thomson_radial_position(ods)
vaft.plot.plot_thomson_time_series(ods)
vaft.plot.plot_electron_profile_with_thomson(ods)
| Notebook | Purpose |
|---|---|
plotting_sample_using_vaft_plot_module.ipynb |
The plot module tour: naming conventions, ODS vs ODC input, and time-convention shifts. |
publication_figures.ipynb |
Reproduce publication-quality composite figures at print DPI. |
verification_and_validation.ipynb |
Cross-check volume-averaged parameters across shots and export a V&V spreadsheet. |
multiple_tokamak_comparison.ipynb |
(design shell) Planned cross-device comparison of geometry, equilibrium, and diagnostic signals. |
The plot module names functions as {ids}_{coordinate}_{quantity} — for example time_magnetics_ip. Any plot function accepts a single ODS, an ODC, or a list of ODS objects, which is what makes shot overlays trivial:
import vaft
ods = vaft.omas.sample_ods()
odc = vaft.omas.sample_odc()
vaft.plot.time_magnetics_ip(ods)
vaft.plot.time_magnetics_ip(odc) # overlays every shot in the collection
# Re-zero the time axis on breakdown, then replot
vaft.omas.change_time_convention(ods, convention="breakdown")
vaft.plot.time_magnetics_ip(ods)
Composite figures are single calls:
import vaft
ods = vaft.omas.sample_ods()
vaft.plot.overlay_all_with_vacuum_psi_contour(ods)
See Plotting for the full catalogue.
| Notebook | Purpose |
|---|---|
vest_daily_monitoring.ipynb |
Day-to-day shot health check: load the day’s shots into an ODC and compare key signals. |
shot_characteristics_classification.ipynb |
(design shell) Planned representative-signal extraction, shot classification, and summary sheets. |
automated_pipeline_overview.ipynb |
Deterministic stage and product summary for routine, corrective, and history-table Snakemake paths. |
These pair with the automated Snakemake stages described in Pipelines.
The nine documentation-allowlisted notebooks are repaired on the companion branch. Some other runnable notebooks retained from the develop baseline still demonstrate older discovery or file-loading APIs; the working forms below are the migration path.
1. vaft.database.exist_ts_file() does not exist. It is called by tokamak_power_balance.ipynb and verification_and_validation.ipynb to discover processed shots. There is no replacement helper in the package; supply the shot list directly, as profile_fitting_using_equilibrium_and_kinetic_diagnostics.ipynb now does:
import pandas as pd
core_profile_shots = [40330]
df = pd.DataFrame({"Shot Number": core_profile_shots, "Status": ["core_profile"]})
2. vaft.omas.load_omas_json() does not exist, and the packaged data moved. Sample JSON files are no longer flat under vaft/data/; they live under vaft/data/omas/. Notebooks that still build a path like os.path.join(os.path.dirname(vaft.__file__), "data", "39915.json") — including vest_daily_monitoring.ipynb and parts of read_and_convert_data_structure.ipynb — will fail. Use the sample helpers or the resource accessor instead:
import vaft
from vaft.data.resources import data_path
ods = vaft.omas.sample_ods() # preferred
sample_path = data_path("omas/39915.json") # or resolve the file explicitly
Note that load_omas_json does exist in the upstream omas package (from omas import load_omas_json); only the vaft.omas alias was removed.
A newcomer should work through the runnable notebooks in this order:
database_initialization_and_load.ipynb — install, connect, load your first shot.read_and_convert_data_structure.ipynb — learn the ODS hierarchy before you plot anything.plotting_sample_using_vaft_plot_module.ipynb — the plot naming convention pays for itself immediately.vest_experimental_data_list.ipynb — find out which diagnostics are actually mapped.profile_fitting_using_equilibrium_and_kinetic_diagnostics.ipynb — the first real physics workflow.equilibrium_refinement_using_chease.ipynb — how VAFT wraps an external code.confinement_time_scaling.ipynb — scale up from one shot to the whole dataset.Then branch by interest: imas_omas_data_conversion.ipynb for interoperability, soft_x_ray_signal_analysis.ipynb and fluctuation_diagnostics_analysis.ipynb for diagnostics, forward_equilibrium_using_TES.ipynb for forward modeling, and publication_figures.ipynb when it is time to write the paper.
If you have not installed VAFT yet, start at Installation and the Quick start guide. The complete function list is in the API reference.