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)