Installation and Python environment
===================================

XGC-Analysis targets Python 3.10 or newer. During development, use an editable
install from a checkout so a local update does not require rebuilding a wheel::

   python3 -m venv .venv
   . .venv/bin/activate
   python -m pip install --upgrade pip
   python -m pip install -e .
   python -c "import xgc_analysis; print(xgc_analysis.__version__)"

Run these commands from the XGC-Analysis repository root. The core package
requires ADIOS2 Python bindings version 2.12.1 or newer, h5py, NumPy, SciPy,
and Matplotlib. The optional ``campaign`` extra adds HPC-Campaign version 0.7.1
or newer and PyYAML for campaign archives; the
``docs`` extra adds Sphinx and the Read the Docs theme, and ``dev`` adds pytest
and build tools. For example, with a pip-provided ADIOS2 build::

   python -m pip install -e '.[docs,dev]'

Add ``campaign`` to the extras when HPC-Campaign 0.7.1 or newer is available
on the configured package index. Public PyPI may lag the upstream source;
install a source checkout using the steps below when needed.

If the selected ADIOS2 bindings come from a custom build, follow the steps
below before installing XGC-Analysis. The pip ADIOS2 wheel is a serial build;
the features and MPI support of a custom build depend on its CMake options.
Use one ADIOS2 installation consistently for its Python bindings and command
line tools.

Compatibility and campaign archives
-----------------------------------

XGC-Analysis requires ADIOS2 2.12.1 or newer, with HPC-Campaign 0.7.1 or
newer for campaign-backed access. Package metadata encodes those minimums.
Remote archive and older-format conversion checks remain open. The on-disk
``.aca`` format is version-sensitive: verify an existing archive with the
installed HPC-Campaign tools before relying on it, and perform any upgrade
on a copy while retaining the original. Local campaign archives have been
checked with HPC-Campaign 0.7.1; remote access and older-format conversion
still require validation.

Build ADIOS2 Python bindings from source
----------------------------------------

Build with the **same Python executable** as the target virtual environment.
The following example installs outside the environment, then exposes the
installed Python package to that environment. Adapt the source checkout,
compiler/MPI configuration, and install prefix to the machine::

   python -m pip install numpy
   ADIOS_SOURCE=/path/to/ADIOS2
   ADIOS_PREFIX=/path/to/adios-install
   cmake -S "$ADIOS_SOURCE" -B "$ADIOS_SOURCE/_build_python" \
     -DCMAKE_BUILD_TYPE=Release \
     -DCMAKE_INSTALL_PREFIX="$ADIOS_PREFIX" \
     -DADIOS2_USE_Python=ON \
     -DADIOS2_USE_MPI=OFF \
     -DPython_EXECUTABLE="$(which python)"
   cmake --build "$ADIOS_SOURCE/_build_python" --parallel
   cmake --install "$ADIOS_SOURCE/_build_python"

Use ``-DADIOS2_USE_MPI=ON`` and the site's MPI/toolchain settings when MPI
bindings are required. The installed Python package is usually under
``$ADIOS_PREFIX/lib/pythonX.Y/site-packages``. Locate the actual directory
and add it to the virtual environment using a ``.pth`` file (or set
``PYTHONPATH`` for each session). For example::

   ADIOS_SITE="$ADIOS_PREFIX/lib/python$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')/site-packages"
   VENV_SITE="$(python -c 'import site; print(site.getsitepackages()[0])')"
   printf '%s\n' "$ADIOS_SITE" > "$VENV_SITE/adios2-custom.pth"
   python -c "import adios2; print(adios2.__version__, adios2.__file__)"
   "$ADIOS_PREFIX/bin/adios2-config" --version

Confirm that ``adios2.__file__`` resolves inside the selected build prefix,
and that ``adios2-config --version`` agrees. A distribution metadata version
alone does not prove which bindings Python imported. Install XGC-Analysis
without dependency resolution so pip does not replace those bindings::

   python -m pip install h5py numpy scipy matplotlib
   python -m pip install --no-deps -e .

For optional features, install ``hpc-campaign`` and ``PyYAML`` (campaign),
``sphinx`` and ``sphinx-rtd-theme`` (docs), or ``pytest`` and ``build`` (dev)
separately. Check the imported module path and ``adios2-config`` version after
installation. ``python -m pip check`` can report ``adios2`` as missing when a
custom CMake install is exposed only through ``.pth``: its Python module works,
but it has no pip distribution metadata. Build these docs with
``cd Docs && make html``.

If HPC-Campaign 0.7.1 or newer is supplied as a source checkout rather than
through the configured package index, install that checkout into the same
environment and verify the imported version before enabling campaign access::

   python -m pip install -e /path/to/hpc-campaign
   python -c "import hpc_campaign; print(hpc_campaign.__version__, hpc_campaign.__file__)"
   python -m pip install --no-deps -e .

Do not infer the ADIOS2 binding version from ``pip show`` alone. Check
``adios2.__version__`` and ``adios2.__file__`` as above, plus
``adios2-config --version`` from the intended prefix.