Installation¶
Install the Python package, activate OpenFOAM, then build the integration for that OpenFOAM environment. Finish with foamnordic doctor before running a case.
Before starting¶
Use CPython 3.11 or 3.12 on Linux (x86_64 or aarch64) or Apple Silicon. The commands below use a bash or zsh terminal. OpenFOAM must already be installed with its compiler and MPI environment; installing FoamNordic does not install OpenFOAM.
Linux with OpenFOAM.com v2512 is the primary HPC target. On Apple Silicon, use OpenFOAM.app and its openfoam launcher. On a cluster, obtain the OpenFOAM module name from the local installation instructions; openfoam/2512 below is an example.
1. Install the Python package¶
Install the PyPI release with either pip or uv in the Python environment used for the project. uv requires a virtual environment; an existing one is sufficient.
pip install foamnordic
uv pip install foamnordic
Create a virtual environment if needed
Use an existing Python 3.11 or 3.12 environment, or create and activate one before installing.
python3.12 -m venv .venv
source .venv/bin/activate
uv venv --python 3.12
source .venv/bin/activate
For uv setup, see the uv installation guide.
Check that the package and terminal use the intended environment:
python -c "import sys, foamnordic; print(sys.executable); print(foamnordic.__file__)"
foamnordic --version
The plain package supports ordinary OpenFOAM runs, mathematical functions and existing model artefacts. Add model-training dependencies only when needed.
2. Activate OpenFOAM and build¶
Wheels include the Python API and native control runtime. The integration build supplies the libraries and runtime executables for the active OpenFOAM compiler/ABI combination. It downloads ONNX Runtime by default and requires network access unless an archive is supplied locally.
Use the same Python environment as in step 1 and load the site's OpenFOAM module:
module load openfoam/2512
command -v wmake
foamnordic build
foamnordic doctor
For a standalone OpenFOAM installation, source its etc/bashrc instead of loading a module. Follow the installation's compiler and MPI setup instructions.
Enter the OpenFOAM.app environment, then build and check FoamNordic:
openfoam
foamnordic build
foamnordic doctor
Use the Python environment containing FoamNordic inside this shell. If foamnordic is unavailable, activate that environment before building. foamnordic build calls wmake internally; no separate wmake command is required. Use exit to leave the OpenFOAM shell.
Run a command without entering the shell
The launcher also accepts a command. Resolve the executable in the current Python environment to preserve its selection:
openfoam "$(command -v foamnordic)" build
openfoam "$(command -v foamnordic)" doctor
The runtime is installed below ~/.local/share/foamnordic/runtime/<platform>/<openfoam-abi>/. Repeat the build when selecting a different OpenFOAM compiler/ABI; separate runtimes coexist. See the command-line reference for build directories, prefixes and other options.
3. Check the environment and run a case¶
foamnordic doctor checks the environment without starting a solver. Resolve FAIL entries first. Solver runs require OpenFOAM, runtime profile, Longship and adapter checks to pass; parallel runs also need MPI. ModelHost or ONNX warnings can be expected from a build without ONNX.
Continue with the first OpenFOAM run. Set Case.of_cmd to the same OpenFOAM activation used for the build: "module load openfoam/2512" with shell="bash" on the example cluster, or "openfoam" with shell="zsh" on macOS. Supply an existing case directory containing the solver dictionaries and fields.
For notebooks, select a kernel from the Python environment containing FoamNordic. Importing the package in the terminal does not establish that a different notebook kernel can import it.
After the first run, follow the local cavity example to inspect fields and run results. The tutorials introduce field exchange and closures on Slurm.
Optional model-training dependencies¶
The ml extra adds scikit-learn, ONNX, Equinox, Optax and CPU JAX. Use ml-cuda12 for training on a compatible Linux CUDA 12 system. These Python extras do not replace the OpenFOAM integration build.
pip install "foamnordic[ml]"
For Linux CUDA 12, replace ml with ml-cuda12.
uv pip install "foamnordic[ml]"
For Linux CUDA 12, replace ml with ml-cuda12.
If installation stops¶
| Symptom | Next step |
|---|---|
| Python version rejected | Select Python 3.11 or 3.12, then recreate the virtual environment with that interpreter. |
foamnordic: command not found |
Activate the environment used for installation. Inside the OpenFOAM shell, activate the same Python environment. |
wmake is unavailable |
Activate OpenFOAM with its compiler environment before building. |
| Runtime profile or adapter missing | Run foamnordic build in the OpenFOAM environment selected for the case, then run doctor there. |
| ONNX Runtime download fails | Supply an unpacked ONNX Runtime 1.28.0 archive through FOAMNORDIC_ONNX_RUNTIME_ROOT, or use build --without-onnx for workloads without native ONNX. |
| Import works in the terminal but fails in a notebook | Select the matching Python kernel and restart it after changing the environment. |
For an unresolved failure, retain the build error and doctor output, including the Python path and OpenFOAM version. See the command-line reference for diagnostic commands.
Install from main¶
The PyPI release is sufficient for normal use. To install the current main branch instead, repository access is required while FoamNordic remains private.
pip install "git+https://github.com/PentagonToy/FoamNordic.git@main#subdirectory=packages/foamnordic"
uv pip install "git+https://github.com/PentagonToy/FoamNordic.git@main#subdirectory=packages/foamnordic"
For reproducible work, replace main with a tag or commit. Then repeat the OpenFOAM integration build and environment check above.
Editable installation¶
Use an editable installation when modifying the Python source. Clone the repository, then install the library from the checkout:
git clone https://github.com/PentagonToy/FoamNordic.git
cd FoamNordic
pip install -e ./packages/foamnordic
uv pip install -e ./packages/foamnordic
Build the OpenFOAM integration and check the environment after installation. Editable installs reflect Python changes; native C++ changes require a rebuild. See development and verification.