Components
==========

Heliokit packages are intentionally named by capability. The host package is
``heliokit``. Shared component abstractions live in ``heliokit-base``. First-party
capabilities are published as separate packages such as ``heliokit-data-vti`` or
``heliokit-model-kp``.

Before running a component, consult :doc:`reference`. It is the authoritative
command reference for argument names, required values, accepted formats,
defaults, and cross-parameter validation.

Package groups
--------------

.. list-table::
   :header-rows: 1
   :widths: 24 32 44

   * - Group
     - Entry point
     - Examples
   * - Data
     - ``heliokit.data``
     - ``heliokit-data-fits``, ``heliokit-data-vti``, ``heliokit-data-cdf``, ``heliokit-data-swv``
   * - Filters
     - ``heliokit.filters``
     - ``heliokit-filter-mag-chb``, ``heliokit-filter-scattertovtk``, ``heliokit-filter-data-calculator``
   * - Models
     - ``heliokit.models``
     - ``heliokit-model-dst``, ``heliokit-model-kp``, ``heliokit-model-sep``
   * - Tools
     - ``heliokit.tools``
     - ``heliokit-tool-chd-acwe``, ``heliokit-tool-chd-catch``, ``heliokit-tool-data-download-aia``
   * - Pipelines
     - ``heliokit.pipelines``
     - ``heliokit-pipeline-geomag``
   * - 3D visualization
     - ``heliokit.viz3d``
     - ``heliokit-viz3d-volume``, ``heliokit-viz3d-slice``, ``heliokit-viz3d-animation``
   * - 2D visualization
     - ``heliokit.viz2d``
     - ``heliokit-viz2d-xy-line``, ``heliokit-viz2d-histogram``, ``heliokit-viz2d-euv``

Data readers
------------

.. code-block:: powershell

   heliokit data read fits D:\data\aia193.fits
   heliokit data read nc D:\data\sample.nc
   heliokit data read vti D:\data\volume.vti
   heliokit data fetch ace --output D:\data\ace_recent.csv

Filters
-------

.. code-block:: powershell

   heliokit run filter mag_chb `
     --rad "D:\data\field.h5::RAD" `
     --theta "D:\data\field.h5::THE" `
     --phi "D:\data\field.h5::PHI" `
     --a1 "D:\data\field.h5::BR" `
     --a2 "D:\data\field.h5::BT" `
     --a3 "D:\data\field.h5::BF" `
     --attribute-cs scs `
     --start-r 1.05 --des-r 2.5 --in-r 1.0 --out-r 3.0 `
     --chb-tindex 20 --chb-findex 40 `
     --output D:\data\mag_chb.h5

   heliokit run filter data_calculator `
     --var "bx=D:\data\field.h5::Bx" `
     --var "by=D:\data\field.h5::By" `
     --expression "sqrt(bx**2 + by**2)" `
     --name bxy --output D:\data\bxy.h5

Models and pipelines
--------------------

.. code-block:: powershell

   heliokit run model dst --mode predict --results-dir D:\runs\dst
   heliokit run model kp --mode train --train-file D:\data\kp_train.csv --results-dir D:\runs\kp_train --epochs 5
   heliokit run pipeline geomag --output D:\runs\geomag\summary.json

Dataset selector syntax
-----------------------

Some components accept selectors that combine a file path and an internal
dataset name:

.. code-block:: text

   PATH::DATASET
   NAME=PATH::DATASET
   NAME=PATH::DATASET,PATH::DATASET,PATH::DATASET

Examples:

.. code-block:: text

   D:\data\cube.h5::Bx
   density=D:\data\cube.h5::rho
   B=D:\data\cube.h5::Bx,D:\data\cube.h5::By,D:\data\cube.h5::Bz