Get Started
===========

Heliokit targets a controlled 64-bit CPython 3.10 environment. The current
packages are pinned to Python 3.10 because the desktop repository contains
compiled extensions and native scientific dependencies built for that runtime.

Choose a Python 3.10 environment
---------------------------------

There are two supported installation paths. The Conda path is recommended: it
keeps Heliokit and its native scientific dependencies isolated from other Python
projects.

1. Use an existing Python 3.10 environment

   Use a managed 64-bit CPython 3.10 installation that already has the required
   runtime dependencies. Confirm the interpreter before installing:

   .. code-block:: powershell

      python --version
      python -c "import struct; print(struct.calcsize('P') * 8)"

   The commands must report Python ``3.10.x`` and ``64`` respectively.

2. Create a Conda Python 3.10 environment (recommended)

   Create and activate a dedicated environment, then update pip inside that
   environment:

   .. code-block:: powershell

      conda create --name heliokit python=3.10 --yes
      conda activate heliokit
      python -m pip install --upgrade pip

   Run all later ``python`` and ``pip`` commands from this activated
   environment. A different environment name is fine, provided it is a 64-bit
   Python 3.10 environment.

Install the host package
------------------------

Install the host package from PyPI:

.. code-block:: powershell

   python -m pip install heliokit

The host package and individual components install their own lightweight Python
dependencies. They do not require the full desktop scientific stack unless a
specific component needs it at runtime.

Install the component packages you need. For example:

.. code-block:: powershell

   python -m pip install heliokit-data-vti heliokit-data-cdf
   python -m pip install heliokit-filter-data-calculator heliokit-viz2d-histogram2d

You can also ask the host package to install components from PyPI:

.. code-block:: powershell

   heliokit components install --online heliokit-data-vti heliokit-viz3d-volume

Inspect components
------------------

.. code-block:: powershell

   heliokit components list
   heliokit components list --kind data

Run a component
---------------

.. code-block:: powershell

   heliokit data read vti D:\data\volume.vti

   heliokit run model kp --mode predict --results-dir D:\runs\kp

   heliokit run pipeline geomag --output D:\runs\geomag\summary.json

Use activated shortcuts
-----------------------

In PowerShell, activate short component commands in the current terminal:

.. code-block:: powershell

   heliokit activate --no-prompt | Invoke-Expression
   vti D:\data\volume.vti
   histogram2d --help

Use ``heliokit activate`` without ``--no-prompt`` when you also want the prompt
to show ``(heliokit)``.