Skip to content

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:

Package Purpose
numpy Array operations and linear algebra
scipy Sparse matrix solvers and numerical methods
numba JIT compilation for performance-critical functions
attrs / cattrs Data models and serialization
h5py / zarr / orjson HDF5, Zarr, and JSON storage backends
plotly Visualization (series, maps, 3D volumes)

Install BORES

uv is a fast Python package manager that handles dependency resolution efficiently. If you do not have uv installed yet, you can install it with:

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

Then install BORES:

uv add bores-framework

If you are working from a cloned copy of the BORES repository, you can install it in development mode:

uv sync

This reads the pyproject.toml and installs all dependencies, including optional dev tools.

You can install BORES with standard pip:

pip install bores-framework

Or to ensure that pip uses an index for MKL-optimized numpy/scipy for x86_64 Linux/Windows:

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

For development mode from a local clone:

pip install -e ".[dev]"

Virtual Environments

Always install BORES inside a virtual environment to avoid conflicts with other packages. With uv, virtual environments are managed automatically. With pip, create one using python -m venv .venv and activate it before installing.

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.

First-run latency

The first time you import BORES or run a simulation, Numba compiles several cached functions. This may take 10-30 seconds. Subsequent runs will be much faster because compiled code is cached to disk.

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

macOS ships with the Accelerate framework, which provides BLAS/LAPACK. No additional installation is needed.

The numpy and scipy wheels on PyPI bundle their own BLAS/LAPACK (OpenBLAS). No additional installation is typically required. If you installed via uv on x86_64, MKL-optimized versions are used automatically.

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

Pre-built wheels for h5py are available on PyPI and should install without issues. If you encounter problems, try upgrading pip: pip install --upgrade pip.

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.

MKL Optimization

On x86_64 Linux and Windows, BORES is configured to use Intel MKL-optimized versions of numpy and scipy when installed via uv. This provides significant performance improvements for linear algebra operations, which are central to reservoir simulation. macOS and non-x86 architectures use standard OpenBLAS builds.

Next Steps

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