Installation¶

Install StackNordic from PyPI, check the Python environment, then choose a stored-data or OpenFOAM workflow. StackNordic works independently of FoamNordic and requires no FoamNordic integration build.

Before starting¶

Use Python 3.11 or 3.12 on Linux or macOS. The package installs NumPy, SciPy, h5py, Cantera and Hedgehogs as dependencies. The commands below use a bash or zsh terminal.

StackNordic is under active development. The site records its source revision; a PyPI release can differ from the current repository API. Use a matching release or pinned source revision for reproducible work.

1. Install the Python package¶

Choose pip or uv in the Python environment used for the project. uv requires a virtual environment; an existing one is sufficient.

pipuv

pip install stacknordic

uv pip install stacknordic

Create a virtual environment if needed

Skip this step if a Python 3.11 or 3.12 environment is already active. Otherwise, create and activate one before installing StackNordic.

pipuv

python3.12 -m venv .venv
source .venv/bin/activate

uv venv --python 3.12
source .venv/bin/activate

See the uv installation guide if uv is unavailable.

2. Check the installation¶

stacknordic --version
stacknordic --help
python -c "import sys, stacknordic; print(sys.executable); print(stacknordic.__file__)"

The commands should report the installed version, available commands and package location. For notebooks, select a kernel from the same Python environment.

3. Choose a workflow¶

Read stored data¶

Case inspection, direct reads of stored fields and operations on exported datasets do not require an active OpenFOAM runtime. Inspect an existing case without launching a solver:

import stacknordic as sno

case = sno.OpenFOAM.case(case_dir="cases/cavity")
print(case.reconstructed_times)
print(case.decomposed_times)

Replace the path with a case containing system/controlDict and constant/. Continue with dataset export and storage or filtering. Export requests that invoke OpenFOAM, such as reconstruction or runtime-derived gradients, need the runtime below.

Run OpenFOAM utilities¶

Reconstruction and OpenFOAM-backed post-processing require an installed OpenFOAM runtime. Installing StackNordic does not install OpenFOAM. Select a runtime compatible with the case.

Linux / HPCApple Silicon

Load the site's OpenFOAM module; the module name below is an example:

module load openfoam/2512
reconstructPar -help

For a standalone installation, source its etc/bashrc instead, following its compiler and MPI setup instructions.

Use OpenFOAM.app and its openfoam launcher:

openfoam reconstructPar -help

Run StackNordic through the same launcher to preserve the selected Python executable:

openfoam "$(command -v stacknordic)" reconstruct --case-dir cases/cavity --n-jobs 1 --progress

Continue with the reconstruction example. In Python, declare the environment through sno.OpenFOAM.case(of_cmd=..., shell=...): use the local module command with shell="bash", or of_cmd="openfoam" with shell="zsh" on macOS.

If installation stops¶

Symptom	Next step
Python version rejected	Select Python 3.11 or 3.12.
`stacknordic: command not found`	Activate the installation environment and check its executable path.
Missing case entries	Check the case path and its `system/controlDict` and `constant/` entries.
`reconstructPar` unavailable	Activate a compatible OpenFOAM runtime before reconstruction.
Import fails only in a notebook	Select the matching Python kernel and restart it.
Documented API absent	Compare the installed release with the site's source revision.

For an unresolved failure, retain the command, error output, installed version and Python path. Include the OpenFOAM version when a utility was involved.

Install from main¶

To use the current repository version ahead of a release:

pipuv

pip install "git+https://github.com/PentagonToy/StackNordic.git@main"

uv pip install "git+https://github.com/PentagonToy/StackNordic.git@main"

Replace main with a tag or commit for reproducible work.

Editable installation¶

Use an editable installation when modifying the source:

git clone https://github.com/PentagonToy/StackNordic.git
cd StackNordic

pipuv

pip install -e .

uv pip install -e .

Follow the development instructions and verification guide for contributor checks.