This document defines the public interface of ILLIAD version 0.1.0. It is the compatibility contract used for versioning and releases. 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, and impurity-ion transport workflow. Its primary public interface is therefore the command-line workflow and its JSON configuration files. The Python interfaces are provided for programmatic use of the same components.
ILLIAD follows Semantic Versioning 2.0.0. The installed package version is available as:
from illiad import __version__Until 1.0.0, ILLIAD is in an initial public-release phase:
- Patch releases (
0.1.x) will not intentionally break the supported command interface, documented JSON keys, or stable Python interfaces below. - A minor pre-1.0 release may make a breaking change. It will be called out in the release notes and this document before or with the release.
- At 1.0.0 and later, removal or incompatible change to a public interface requires a major-version increment, except where a documented deprecation period says otherwise.
Numerical results depend on model inputs, data files, platform, dependency versions, stochastic sampling, and hardware. Semantic versioning applies to the software interface, not to bitwise-identical scientific output.
The following commands are installed by the illiad-fieldlines distribution:
| Command | Purpose | Configuration file |
|---|---|---|
illiad-fieldsolver |
Generate Cartesian magnetic-field arrays from coil geometry. | fieldsolver_inputs.json |
illiad-poincare |
Trace field lines and reconstruct Poincare surfaces. | poincare_inputs.json |
illiad-flux-calc |
Integrate toroidal flux across reconstructed surfaces. | flux_calc_inputs.json |
illiad-flux-grad |
Interpolate the flux profile and generate a Cartesian electric field. | flux_grad_inputs.json |
illiad-boris |
Run full-orbit lithium-ion transport with the Boris solver. | boris_inputs.json |
Every command accepts:
--inputs-json PATH
PATH names a UTF-8 JSON file whose top-level value is an object. Paths in the
JSON file are resolved relative to the process working directory. Every
workflow command merges supplied values over its built-in defaults. When
--inputs-json is omitted, the command uses those built-in defaults.
Use the installed commands rather than invoking run*.py files directly. The
illiad.cli modules, root launchers, and their main() functions are not
public Python API.
The commands require their upstream data products. In particular, the usual
workflow uses prepared magnetic-field arrays under input_files/, Poincare
outputs for the flux stages, and generated density/electric-field arrays for
the Boris stage. ILLIAD does not bundle large scientific arrays in package
artifacts. See Release Contents for the data policy.
The repository-root JSON files are complete, supported examples. Keys listed below are the public configuration schema for their command. Values must use JSON types; array-like values are JSON arrays.
illiad-fieldsolver accepts:
| 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. |
illiad-poincare accepts:
| 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 expressed in kiloamperes; radii are expressed in meters; angles
are expressed in degrees. OUTPUT_DIR identifies the run directory below
output/.
illiad-flux-calc accepts:
| 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, PHI_GENs |
| Flux integration | MAX_SUBSETS, SMOOTH_FCTR, INTEGRATE_EPSABS, INTEGRATE_EPSREL, ISLAND_ALGORITHM, HIST_BINS |
| Diagnostics | PLOT_ALL, BIG_MESH |
PHI_GENs is optional. When it is absent or null, ILLIAD derives it from
NPHI as numpy.linspace(360 // NPHI, 360, NPHI) in degrees. Use an NPHI
that divides 360, or provide PHI_GENs explicitly for a different sampling
scheme.
illiad-flux-grad accepts the shared location, magnetic-configuration, and
surface-sampling keys from flux_calc_inputs.json, plus:
| Group | Keys |
|---|---|
| Prior flux selection | SMALLEST_ISLAND_INDEX |
| Interpolation and electric field | ALPHA, DEBUG, INV_SURF_INDICES, GUESS_PHI_INDEX, OUTPUT_FILE_NAME |
| RBF interpolation | RBF_KERNEL, RBF_NEIGHBORS, RBF_SMOOTHING, RBF_EPSILON |
INV_SURF_INDICES is a JSON array of surface indices. OUTPUT_FILE_NAME is
the electric-field output basename, without a required .npy suffix.
illiad-boris accepts:
| Group | Keys |
|---|---|
| Magnetic configuration | CONFIG_TOR, CONFIG_HEL, ENABLE_ERRFIELD, TOROIDAL_CURRENT, HELICAL_CURRENT |
| Upstream fields | FIELD_FILE_DENSITY, FIELD_FILE_ELECTRIC |
| Collision controls | ION_NEUTRAL_COLLISIONS, ION_ION_COLLISIONS, NEUTRAL_GAS_DENSITY, PLASMA_DENSITY |
| Background plasma | ELECTRON_TEMP_EV, BACKGROUND_GAS_SPECIES, NEUTRAL_GAS_TEMP_EV, BACKGROUND_ION_TEMP_EV, ION_ELECTRON_SAT_CURRENT_RATIO |
| Ion properties | ION_MASS, ION_TEMP, CHARGE_NUM |
| Plasma potential | Optional PLASMA_POTENTIAL; when omitted, derived from the background-plasma 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 |
STRIDE is a positive integer controlling trace sampling.
Unknown configuration keys are not part of the API. Current runners do not provide schema validation for every key, so a misspelled key can be ignored or fail later in a workflow. Start from the supplied example files for each release.
The preferred import root is illiad. Shared utilities are organized under
illiad.utilities, and active plotting helpers live in illiad.plotting.
The former classes.*, utility.*, and plot_funcs.* packages have been
removed.
The following interfaces are the stable programmatic surface for the 0.1 series:
from illiad import __version__
from illiad.utilities.run_config import load_inputs_json, merge_input_params, normalize_phi_gens| Import | Contract |
|---|---|
__version__ |
Installed ILLIAD version string. |
load_inputs_json(path, label="Inputs") |
Load and return a top-level JSON object, exiting with a readable error for unreadable or invalid input. |
merge_input_params(defaults, overrides=None) |
Return a shallow copy of defaults, updated by overrides when supplied. |
normalize_phi_gens(input_params) |
Mutate and return the mapping, deriving or normalizing PHI_GENs from NPHI. |
The following imports are public in the sense that they are documented and supported for exploratory programmatic use. Their object models and method signatures are still being consolidated from research code. They may change in a minor pre-1.0 release; such changes will be documented in release notes.
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.boris import Boris
from illiad.collisions import Collisions
from illiad.flux import FluxCalculator, FluxInterpolator, FluxGradientor
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 plottingThe current documented members of these objects are:
| Object | Constructor and methods |
|---|---|
IOHandler |
IOHandler(run_name); startLog, createSubDir, setActiveSubDir, saveNumpyData, loadNumpyData, saveFig, loadPorts_fromCSV, loadCSV, saveCSV, inputsBoilerplate, borisBoilerplate |
Mesh |
Mesh(R0=0.72, a=0.19); loadCartesianField, addFieldPerturbation, setErrorField, set_nonPer_errField, rot_vecXYZ_byPHI, interpField, loadScalarField, interpScalarField |
TorchMesh |
TorchMesh(R0=0.0, a=0.0); loadCartesianField, addFieldPerturbation, loadScalarField, setErrorField, rot_vecXYZ_byPHI, get_weights, return_vecs, return_scalars, interpField, interpScalarField |
Particle |
Particle(type) |
FieldLine |
FieldLine(init_XYZ, maxlength, direction=1.0); pushXYZ, storePath |
Ion |
Ion(init_XYZ, mass_amu, charge_z, maxlife=0.0); initVelocity, initOutput, setPosition, setVelocity |
Poincare |
Poincare(io_handler, solvr="LSODA", r_tol=1e-6, a_tol=1e-16, workers=-1, double_line=False, anlys_name="Poincare"); set_conditions, parallel_solver, single_solver, post_solver, identifyLCFS, save_output, run |
Boris |
Boris(io_handler, anlys_name="Boris", tag=None); setConditions, parallel_solver, post_solver, save_output, run |
Collisions |
viscous_drag_hstep, langevin_in_hstep, linearFP_ii_hstep, chandrasekhar_psi, chandrasekhar_psi_prime, coulomb_fp_rates_li_he, fokker_planck_ii_hstep |
FluxCalculator |
FluxCalculator(io_handler, field, input_params); run |
FluxInterpolator |
FluxInterpolator(io_handler, field, input_params); run |
FluxGradientor |
FluxGradientor(io_handler, field, input_params); run |
illiad.collisions also exports the physical constants kg_per_amu,
kboltz, eps0, sqrt_pi, Li_mass, and He_mass.
The coordinate module exports RTP_to_XYZ, XYZ_to_RTP, XYZ_to_RTP2,
RTP_to_XYZ_many, XYZ_to_RTP_many, rot_vecXYZ_byPHI, RTP_XYZ_JAC,
RTP_XYZ_JAC2, axisShift, and align_z_to_vector.
illiad.utilities.point_generators exports generateSeedShells,
generate_MB_velocities, and ionInitializer. illiad.plotting provides the
plotting helpers used by the Boris and Poincare workflows. Their detailed
return shapes and plot formats are provisional.
The directory convention output/<run>/logs, output/<run>/data, and
output/<run>/plots is supported. Stage commands produce files consumed by
later stages in the same ILLIAD release.
Raw NumPy array layouts, output basenames beyond the workflow examples, log
text, plot appearance, and files below fastplotlib_tests/ are not stable
public data formats yet. Pin the ILLIAD version and retain the source JSON
configuration with a scientific result. A documented interchange format or
data-schema version will be required before these files are treated as
cross-version public API.
The following are outside the public compatibility contract:
- Modules under
illiad.cli, rootrun*.pylaunchers, and their globals. fastplotlib_tests/,misc_scripts/, notebooks, scratch scripts, and unpublished analysis helpers.- Generated input/output arrays, local output directories, and files not documented in this file.
When an internal interface is promoted, it will first be added here and exposed
through the illiad namespace.