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.