Simulation core

The core packages group objects by what they own. Simulation composes them; each object can also be imported and used by a script without the GUI.

  • xgc_analysis.mesh owns Mesh, Plane, MeshData, PlaneData, sparse geometry helpers, and both existing field-line mapping routines. Mesh reads wedge spacing and constructs one stored Plane for axisymmetric geometry or one per toroidal mesh plane otherwise. MeshData can hold a separate data slice for every toroidal plane even when all slices share the same stored poloidal geometry.

  • xgc_analysis.magnetic_equilibrium owns MagneticField. It reads xgc.equil.bp and xgc.bfield.bp and interpolates the background field using the supplied poloidal Plane. There is no separate equilibrium object in this stage.

  • xgc_analysis.simulation owns Simulation and VelocityGrid. Simulation selects a catalog, shares static-product values, reads the input namelist, and constructs the core objects and species. VelocityGrid describes the cylindrical (v_perp, v_parallel) grid from xgc.f0.mesh.bp.

  • xgc_analysis.species owns Species, the periodic-table helper, input-defined radial profiles, and heat/torque deposition shapes. Species.initial_profiles retains the earlier file-only interface; Species.prescribed_profiles includes analytic and file shapes.

Coordinates and indexing

Plane.rz uses cylindrical (R, Z) coordinates in metres and shape (n_node, 2). Mesh.delta_phi and Mesh.wedge_angle are toroidal angles in radians. Mesh.nphi counts the toroidal data planes per wedge, while Mesh.planes contains just one geometry object when is_axisymmetric is true. PlaneData holds one plane’s vertex values; MeshData.get_data() stacks them with toroidal plane as axis 0. These Python arrays use zero-based indices. BP connectivity can be one-based; the routines that consume it perform their existing conversion locally.

The two field-line mapping modules both trace mesh vertices in toroidal angle with RK4 and return triangle indices and barycentric weights for each step. Mesh.setup_fieldline_mapping uses xgc_analysis.mesh.fieldline_mapping. The other implementation, fieldline_mapping2, is retained separately for later numerical review; its axisymmetric plane_index currently selects data plane 0 at every step. No mapping algorithm was consolidated during this package relocation.

Construction and resource use

The core constructors read static values through the catalog. Create a directory or campaign catalog first, then pass it to Simulation or an individual core object. Simulation(initialize=False) stores catalog and directory state without reading the core static products. A fully initialized simulation requires the mesh, equilibrium, magnetic-field products, and the input text artifact. Catalog-backed campaign reads may keep an ADIOS reader open; close the catalog when the caller is finished with it.

Typical imports:

from xgc_analysis.data_access.catalog import open_catalog
from xgc_analysis.simulation import Simulation
from xgc_analysis.mesh import MeshData, PlaneData
from xgc_analysis.magnetic_equilibrium import MagneticField

catalog = open_catalog("/path/to/xgc/output")
simulation = Simulation(catalog=catalog)