Installation¶

This page covers how to install BORES, verify your setup, and troubleshoot common issues. BORES supports Python 3.10 and above on Linux, macOS, and Windows.

Prerequisites¶

Before installing BORES, make sure you have the following:

• Python 3.10 or later - BORES uses modern typing features and requires Python 3.10 as a minimum. You can check your version with python --version.
• A C compiler - Numba (used for JIT-compiled numerical kernels) occasionally needs to compile extensions. On Linux, gcc is typically available by default. On macOS, install Xcode command line tools with xcode-select --install. On Windows, the Microsoft Visual C++ Build Tools are sufficient.
• A working internet connection - Required to download BORES and its dependencies from PyPI.

BORES depends on several scientific Python packages that will be installed automatically:

Install BORES¶

curl -LsSf https://astral.sh/uv/install.sh | sh

uv add bores-framework

uv sync

pip install bores-framework

pip install bores-framework --extra-index-url https://urob.github.io/numpy-mkl

pip install -e ".[dev]"

Verify Your Installation¶

Run the following script to confirm that BORES is installed correctly and its core dependencies are available:

import bores
print(f"BORES version: {bores.__version__}")
print(f"Default precision: {bores.get_dtype()}")

Expected output:

BORES version: 0.1.0
Default precision: <class 'numpy.float32'>

If you see an ImportError, double-check that you installed BORES in the correct Python environment and that all dependencies resolved successfully.

Optional Dependencies¶

BORES includes several optional packages that extend its capabilities. These are installed by default with the standard installation, but are worth knowing about if you are working in a minimal environment.

Thermodynamics - CoolProp and thermo¶

BORES uses CoolProp and thermo for advanced fluid property calculations, particularly when computing gas properties from first principles. These packages enable accurate PVT calculations for non-standard gases like CO2 or nitrogen.

pip install coolprop thermo

Visualization - Plotly and Trame¶

The visualization module relies on Plotly for generating charts and 3D renders, along with Kaleido for static image export and Trame for interactive 3D volume visualization in web browsers.

pip install plotly kaleido trame

Storage - HDF5 and Zarr¶

BORES supports multiple storage backends for saving and loading simulation results. h5py provides HDF5 support, while zarr enables chunked, compressed array storage suitable for large simulations.

pip install h5py zarr

Troubleshooting¶

Numba compilation errors¶

Numba compiles Python functions to machine code on first use. If you encounter compilation errors, try the following:

1. Update Numba: Ensure you have numba >= 0.63.0 installed.
2. Clear the cache: Delete Numba's cache directory, typically found at __pycache__ folders containing .nbi and .nbc files.
3. Check your compiler: Run numba -s to print system information and verify that a compatible C compiler is detected.

Missing BLAS/LAPACK libraries¶

scipy and numpy depend on optimized linear algebra libraries. On Linux, if you see errors about missing BLAS or LAPACK:

sudo apt-get install libopenblas-dev liblapack-dev

sudo dnf install openblas-devel lapack-devel

HDF5 build failures¶

If h5py fails to install, it may be because the HDF5 C library is not available on your system:

sudo apt-get install libhdf5-dev

brew install hdf5

Numba Threading Layer (Optional Performance Tuning)¶

BORES uses Numba for JIT-compiled numerical kernels. By default, Numba uses multiple threads for parallelization across your CPU cores. The threading backend can be configured for optimal performance.

Threading Backends¶

Numba supports three threading layers in order of preference:

1. TBB (Intel Threading Building Blocks) - Best performance, cross-platform support
2. OMP (OpenMP) - Good performance, widely available
3. Workqueue - Fallback, available on all platforms

Important: BORES does not require TBB and will work correctly with any available threading layer. By default, Numba automatically selects the best available option: tbb → omp → workqueue.

Check Your Current Threading Layer¶

To see which threading layer Numba is currently using, run:

import numba

def get_threading_backend():
    try:
        return numba.threading_layer()
    except Exception:
        return "unknown"

print(f"Numba threading layer: {get_threading_backend()}")

Expected output (one of):

Numba threading layer: tbb
Numba threading layer: omp
Numba threading layer: workqueue

export NUMBA_NUM_THREADS=4

import numba
numba.set_num_threads(4)

Optional: Install TBB for Better Performance¶

If you want to ensure TBB (the fastest threading layer) is used, install it on your platform:

sudo apt-get install libtbb-dev

pip install tbb tbb4py
uv add tbb tbb4py  # or with uv

import numba
print(numba.threading_layer())  # Should print: tbb

brew install tbb

pip install tbb tbb4py
uv add tbb tbb4py  # or with uv

import numba
print(numba.threading_layer())  # Should print: tbb

pip install tbb tbb4py
uv add tbb tbb4py  # or with uv

import numba
print(numba.threading_layer())  # Should print: tbb

Graceful Fallback Behavior¶

BORES is designed to work reliably with any threading layer. If you want to explicitly ensure safe fallback behavior at startup:

import os
import numba

# Ensure safe fallback: tbb → omp → workqueue
os.environ.setdefault("NUMBA_THREADING_LAYER", "default")

# Print what's available
print(f"Numba threading layer: {numba.threading_layer()}")

import bores  # Now import BORES

Platform Notes¶

Linux¶

Linux is the primary development and testing platform for BORES. All features, including MKL-optimized linear algebra on x86_64, work out of the box with the standard installation.

macOS¶

BORES works on both Intel and Apple Silicon Macs. On Apple Silicon (M1/M2/M3/M4), Numba uses the ARM64 backend, which is fully supported. The Accelerate framework provides optimized BLAS/LAPACK.

Windows¶

BORES is supported on Windows 10 and later. If you are using Windows Subsystem for Linux (WSL), the Linux installation instructions apply. Native Windows installation works with both uv and pip.

Next Steps¶

With BORES installed, head to the Quickstart to build and run your first simulation.