Skip to content

PUBLIC_API.md

Latest commit

 

History

History
289 lines (232 loc) · 14.2 KB

PUBLIC_API.md

File metadata and controls

289 lines (232 loc) · 14.2 KB
Raw

ILLIAD Public API

This document defines the public interface of ILLIAD version 1.0.0. Interfaces not listed here are implementation details even when they are importable from a source checkout.

ILLIAD is research software for a staged field-line, flux-surface, SOL, and impurity-ion transport workflow. Its primary interface is the installed command set and JSON configuration files; selected analysis classes are also available for programmatic use.

Versioning Policy

ILLIAD follows Semantic Versioning 2.0.0. The installed version is available as:

from illiad import __version__

For the 1.x series, incompatible changes to active command names, documented JSON keys, or stable Python utilities require a major release. Minor releases may add backward-compatible commands, keys, and functionality; patch releases contain backward-compatible fixes and documentation changes. Interfaces explicitly labeled provisional are excluded from these stability guarantees.

Numerical results also depend on scientific inputs, dependency versions, stochastic sampling, and hardware; the version contract does not promise bitwise-identical output.

Installed Commands

Command Status Purpose Configuration
illiad-fieldsolver Active Generate Cartesian magnetic-field arrays from coil geometry. input_files/fieldsolver_inputs.example.json
illiad-poincare Active Trace field lines and reconstruct Poincare surfaces. input_files/poincare_inputs.example.json
illiad-flux-calc Active Integrate toroidal flux and diagnose island chains. input_files/flux_calc_inputs.example.json
illiad-flux-grad Active Interpolate a scalar profile and/or generate its Cartesian electric field. input_files/flux_grad_inputs.example.json
illiad-sol-trace Active Trace open SOL field lines with the PyTorch solver. input_files/sol_trace_inputs.example.json
illiad-sol-density Placeholder Reserve the command name for a future density analysis class. None
illiad-sol-potential Placeholder Reserve the command name for a future potential analysis class. None
illiad-boris Active Run full-orbit lithium-ion transport. input_files/boris_inputs.example.json

The six active commands accept:

--inputs PATH

PATH is a UTF-8 JSON file whose top-level value is an object. Supplied values override built-in defaults. Omitting --inputs uses those defaults. The same path may instead be supplied as the optional positional INPUTS argument. Supplying both forms is an input error; neither form takes precedence. Relative input paths and output/ are resolved from the process working directory.

The two placeholder commands accept only standard -h/--help. Invoking one without --help exits unsuccessfully with a not-implemented message. They do not import, install, or dispatch to misc_scripts, and they do not yet define JSON contracts.

Root run*.py launchers mirror the command modules for source-checkout use. Installed commands are canonical; illiad.cli, launcher modules, and their main() functions are not public Python API.

Large generated scientific inputs and outputs are not bundled. See Release Contents.

JSON Configuration Interface

Tracked input_files/*.example.json files are complete templates for their commands. Copy a template to a filename ending in .json before customizing it; ordinary JSON files are ignored so run-specific inputs are not committed accidentally. Values use JSON types, array-like values use arrays, and optional values use null.

fieldsolver_inputs.example.json

Key Meaning
OUTPUT_NAME Basename for the generated magnetic-field array.
MESH_SIZE Three integer mesh dimensions.
I_TORO, I_HELI, I_VERT Toroidal, helical, and vertical coil currents in amperes.
COILFILE Coil-geometry input file.
RMAJOR, RMINOR Major and minor radii in meters.
MESH_PERIODICITY Three-element mesh periodicity descriptor.

poincare_inputs.example.json

Group Keys
Magnetic configuration CURRENT_TOR, CURRENT_HEL, CONFIG_TOR, CONFIG_HEL, ENABLE_ERRFIELD
Initial field lines IC_PHI_DEG, IC_THETA_DEG, START_RADIUS, END_RADIUS, NLINES
Trace and solver controls SPINS, NPLANES, SOLVER, RTOL, ATOL, NTHREADS, DOUBLE_LINE
Output OUTPUT_DIR

Currents are in kiloamperes, radii in meters, and angles in degrees.

flux_calc_inputs.example.json

Group Keys
Input/output location ANLYS_DIR, ANLYS_SUBDIR, FIELD_FILE_TOR, FIELD_FILE_HEL
Magnetic configuration CURRENT_TOR, CURRENT_HEL, CONFIG_TOR, CONFIG_HEL, ENABLE_ERRFIELD
Surface sampling LCFS_INDEX, NPHI, NTHETA, optional PHI_GENs
Flux integration MAX_SUBSETS, SMOOTH_FCTR, INTEGRATE_EPSABS, INTEGRATE_EPSREL
Retained legacy inputs ISLAND_ALGORITHM, HIST_BINS
Diagnostics PLOT_ALL, BIG_MESH

When PHI_GENs is absent or null, positive NPHI produces numpy.linspace(360.0 / NPHI, 360.0, NPHI) in degrees. Explicit values are normalized to a floating-point NumPy array.

The active island detector measures rotational transform from each ordered Poincare surface, matches low-order rationals with denominators no greater than MAX_SUBSETS, and splits matched chains by striding the crossing array. This permits distinct island-chain subset counts in one run. ISLAND_ALGORITHM and HIST_BINS remain accepted and logged for existing inputs but do not control the active detector.

flux_grad_inputs.example.json

Group Keys
Shared analysis and magnetic inputs ANLYS_DIR, ANLYS_SUBDIR, CURRENT_TOR, CURRENT_HEL, CONFIG_TOR, CONFIG_HEL, ENABLE_ERRFIELD, LCFS_INDEX, NPHI, NTHETA, optional PHI_GENs
Prior flux selection SMALLEST_ISLAND_INDEX, MAX_SUBSETS
Interpolation control RUN_INTERPOLATOR, INPUT_FIELD_NAME, ALPHA, DEBUG, INV_SURF_INDICES, GUESS_PHI_INDEX, OUTPUT_FILE_NAME, FLUX_INTERPOLATION_MODE
RBF interpolation RBF_KERNEL, RBF_NEIGHBORS, RBF_SMOOTHING, RBF_EPSILON
Periodic 3-D interpolation RBF_PHI_HALF_WINDOW, RBF_PHI_SCALE, RBF_POINTS_PER_SURFACE_PER_PHI
Gradient construction LEGACY_FILTER_GRADIENTS_OUTSIDE_LCFS, GRADIENT_FILTER_BUFFER

With RUN_INTERPOLATOR set to true, FLUX_INTERPOLATION_MODE accepts exactly 2d or 3d:

  • 2d fits each output plane from that plane's Poincare samples.
  • 3d fits from a periodically wrapped local toroidal window. RBF_PHI_HALF_WINDOW selects adjacent source planes, RBF_PHI_SCALE supplies the angular length scale, and RBF_POINTS_PER_SURFACE_PER_PHI limits each surface's contribution.

Both modes retain float64 source, query, interpolated, and saved arrays. Source labels run from 1 at the magnetic axis to 0 at the LCFS, and rho=0 is filled from the poloidal average of the innermost repaired radial shell.

With RUN_INTERPOLATOR set to false, interpolation is skipped and INPUT_FIELD_NAME names an existing scalar array relative to output/<ANLYS_DIR>/data/. The gradient stage still writes Efield_<OUTPUT_FILE_NAME>.npy and its plots.

Gradients use radian angular coordinates and periodic centered differences in toroidal and poloidal directions. LEGACY_FILTER_GRADIENTS_OUTSIDE_LCFS enables the historical exterior mask; GRADIENT_FILTER_BUFFER is its nonnegative radial buffer in meters.

sol_trace_inputs.example.json

Group Keys
Output location ANLYS_DIR, ANLYS_SUBDIR
Magnetic configuration CURRENT_TOR, CURRENT_HEL, CONFIG_TOR, CONFIG_HEL, ENABLE_ERRFIELD, MAJOR_RADIUS_M, VESSEL_RADIUS_M
LCFS and seeds LCFS_INDEX, N_PLANES, N_SEED_PLANES, SEED_PHI_DEG, N_RHO, N_THETA, RHO_MIN, RHO_MAX, LCFS_CLEARANCE_M, LCFS_SPLINE_SMOOTHING, LCFS_BOUNDARY_POINTS
Trace length SPINS
Device and integration DEVICE, INTEGRATOR, STEP_SIZE_M, BATCH_SIZE, CROSSING_BUFFER_SIZE, STEP_CHUNK_SIZE, COMPILE_STEP_CHUNKS, WALL_BISECTION_STEPS, MIN_FIELD_MAGNITUDE
Progress PROGRESS_INTERVAL_STEPS, PROGRESS_REFRESH_STEPS, SHOW_PROGRESS
Plots GENERATE_PLOTS, COLOR_SCALE, COLORMAP, N_LEVELS, VMIN, VMAX, DPI, PLOT_MAX_SAMPLES, PLOT_SAMPLE_SEED, PHYSICAL_PHI_OFFSET_DEG

DEVICE accepts auto, cpu, cuda, or an explicit CUDA device. INTEGRATOR accepts euler, midpoint, or rk4. Tracing uses float64 values, integrates both directions from each valid exterior seed, and terminates each solve at the wall or numerical length limit 2*pi*MAJOR_RADIUS_M*SPINS.

Compact raw output is sorted by toroidal plane. plane_offsets.npy indexes each plane's slice in raw_points_rtp.npy; raw_fieldline_id.npy maps each crossing to fieldline_connection_length_m.npy; and raw_source_direction.npy distinguishes forward, reverse, and inserted seed samples. Directional lengths, wall intersections, masks, seed coordinates, and plane coordinates are saved alongside them.

boris_inputs.example.json

Group Keys
Magnetic configuration CONFIG_TOR, CONFIG_HEL, ENABLE_ERRFIELD, TOROIDAL_CURRENT, HELICAL_CURRENT
Upstream fields FIELD_FILE_DENSITY, FIELD_FILE_ELECTRIC
Collision selection ION_NEUTRAL_COLLISIONS, ION_ION_COLLISIONS
Background plasma ELECTRON_TEMP_EV, BACKGROUND_GAS_SPECIES, NEUTRAL_GAS_TEMP_EV, NEUTRAL_GAS_DENSITY, PLASMA_DENSITY, ION_ELECTRON_SAT_CURRENT_RATIO
Ion properties ION_MASS, ION_TEMP, CHARGE_NUM
Plasma potential Optional PLASMA_POTENTIAL; otherwise derived from background inputs.
Particle initialization LCFS_INDEX, DELTRS, NPHI, NTHETA, NPARTICLES_PER_EMITTER
Time integration DT, TMAX
Trace selection TRACK_NPHI, TRACK_NTHETA, TRACK_NPARTICLES_PER_EMITTER, STRIDE
Output OUTPUT_DIRECTORY_NAME, TAG

ION_NEUTRAL_COLLISIONS accepts viscous_drag, langevin, or null. ION_ION_COLLISIONS accepts linear_fp, fokker_planck, or null. Enabled models are applied as half-steps before and after each Boris push.

Particle initialization uses an emitter-major layout. Initial speeds follow the configured Maxwellian, and launch directions are cosine-weighted over a hemisphere about the normalized local electric field, with the outward geometric LCFS normal as fallback. Every run writes E0_Dist.png and the four-panel V0_Dist.png. STRIDE must be a positive integer.

Unknown configuration keys are not part of the API. Current runners do not validate every key up front, so begin with the supplied example.

Python API

The preferred import root is illiad. Former classes.*, utility.*, and plot_funcs.* packages have been removed.

Stable Utilities

from illiad import __version__
from illiad.utilities.run_config import (
    load_inputs_json,
    merge_input_params,
    normalize_phi_gens,
)
Import Contract
__version__ Installed version string.
load_inputs_json(path, label="Inputs") Load a top-level JSON object or exit with a readable input error.
merge_input_params(defaults, overrides=None) Return a shallow defaults copy updated by supplied overrides.
normalize_phi_gens(input_params) Mutate and return the mapping after deriving or normalizing PHI_GENs.

Provisional Research Interfaces

The following analysis objects and helper functions are documented for programmatic research use, but their constructors, methods, and detailed return formats are not part of the stable 1.x compatibility contract. The installed commands and JSON interfaces above are the stable workflow surface.

from illiad.io import IOHandler
from illiad.mesh import Mesh, TorchMesh
from illiad.particle import Particle, FieldLine, Ion
from illiad.poincare import Poincare
from illiad.flux import FluxCalculator, FluxInterpolator, FluxGradientor
from illiad.sol import SOLTracer
from illiad.boris import Boris
from illiad.collisions import Collisions
from illiad.utilities.coordtrans import RTP_to_XYZ, XYZ_to_RTP
from illiad.utilities.point_generators import (
    generateSeedShells,
    generate_MB_velocities,
    ionInitializer,
)
from illiad import plotting
Object Constructor and documented methods
IOHandler IOHandler(run_name); logging, subdirectory, NumPy, CSV, figure, and input-boilerplate methods
Mesh Mesh(R0=0.72, a=0.19); field/scalar loading, perturbation, rotation, and interpolation methods
TorchMesh TorchMesh(R0=0.0, a=0.0); torch field/scalar loading, interpolation, weight, and return methods
Poincare Poincare(...); condition, solver, LCFS, output, and run methods
FluxCalculator FluxCalculator(io_handler, field, input_params); run
FluxInterpolator FluxInterpolator(io_handler, field, input_params); run
FluxGradientor FluxGradientor(io_handler, field, input_params); run
SOLTracer SOLTracer(io_handler, magnetic_field, input_params); build_initial_conditions, log_inputs, trace, plot, run
Boris Boris(io_handler, anlys_name="Boris", tag=None); condition, solver, output, diagnostic, and run methods
Collisions Collision-model resolution and ion-neutral and ion-ion numerical operators

illiad.sol also exports build_torch_magnetic_field, load_lcfs_boundary, load_poincare_settings, minimum_boundary_distance, and resolve_device. No density or potential analysis class is currently public.

Output and Data Compatibility

The directory convention output/<run>/logs, output/<run>/data, and output/<run>/plots is supported. Stage outputs are contracts between stages of the same ILLIAD release, not yet stable cross-version interchange formats.

Explicitly Non-Public Interfaces

  • Modules under illiad.cli, root launchers, and their globals.
  • misc_scripts, including the current density and potential prototypes.
  • fastplotlib_tests, notebooks, scratch scripts, and unpublished helpers.
  • Generated arrays not explicitly documented above and local output trees.

An internal Python interface becomes public only when it is listed here and exported through an illiad namespace.