Full API Reference¶

Overview¶

This page lists every class, function, constant, and type exported from the bores package. Everything listed here is importable directly from bores (for example, from bores import Config or import bores; bores.Config). The API is organized by functional area to help you find what you need quickly.

The bores package uses wildcard re-exports from its internal modules. This means you never need to import from internal paths like bores.wells.controls or bores.solvers.base. Everything public is available at the top level. The only exception is the array PVT correlations, which must be imported from bores.correlations.arrays explicitly, and the visualization submodules (bores.visualization.plotly1d, bores.visualization.plotly2d, bores.visualization.plotly3d) which you can import by name for direct renderer access.

For detailed documentation of individual items, see the relevant sections in the User Guide and Tutorials. For PVT correlation functions specifically, see the Scalar Correlations and Array Correlations pages.

Model Construction¶

These are the main entry points for building reservoir models and wells. The factory functions handle PVT correlation computation, grid validation, and internal object construction for you.

Factory Functions¶

import bores
import numpy as np

# Build input grids (10x10x3 reservoir)
shape = (10, 10, 3)
thickness = bores.build_uniform_grid(shape, 20.0)
pressure = bores.build_uniform_grid(shape, 3000.0)
porosity = bores.build_uniform_grid(shape, 0.20)
temperature = bores.build_uniform_grid(shape, 200.0)
oil_viscosity = bores.build_uniform_grid(shape, 1.5)
bubble_point = bores.build_uniform_grid(shape, 2500.0)

model = bores.reservoir_model(
    grid_shape=shape,
    cell_dimension=(100.0, 100.0),
    thickness_grid=thickness,
    pressure_grid=pressure,
    rock_compressibility=3e-6,
    absolute_permeability=bores.RockPermeability(
        kx=bores.build_uniform_grid(shape, 100.0),
        ky=bores.build_uniform_grid(shape, 100.0),
        kz=bores.build_uniform_grid(shape, 10.0),
    ),
    porosity_grid=porosity,
    temperature_grid=temperature,
    water_saturation_grid=Sw,
    oil_saturation_grid=So,
    gas_saturation_grid=Sg,
    oil_viscosity_grid=oil_viscosity,
    oil_bubble_point_pressure_grid=bubble_point,
    residual_oil_saturation_water_grid=bores.build_uniform_grid(shape, 0.20),
    residual_oil_saturation_gas_grid=bores.build_uniform_grid(shape, 0.10),
    residual_gas_saturation_grid=bores.build_uniform_grid(shape, 0.05),
    irreducible_water_saturation_grid=bores.build_uniform_grid(shape, 0.20),
    connate_water_saturation_grid=bores.build_uniform_grid(shape, 0.20),
)

Core Data Models¶

All data model classes are frozen attrs classes. You modify them using attrs.evolve() to create new instances with changed fields.

Simulation¶

These classes and functions control how simulations are configured and executed.

Configuration and Execution¶

config = bores.Config(
    timer=bores.Timer(
        simulation_time=bores.Time(days=365),
        initial_step_size=bores.Time(days=1),
        maximum_step_size=bores.Time(days=30),
        minimum_step_size=bores.Time(days=0.01),
    ),
    wells=wells,
    scheme="impes",
)

simulation = bores.run(model=model, config=config)
for step in simulation:
    print(f"Day {step.time:.1f}, Pressure: {step.model.pressure_grid.mean():.1f} psi")

Time Management¶

Model State¶

Wells¶

Well types, fluid definitions, controls, and scheduling are all available at the top level.

Well Types¶

Well Fluids¶

Well Rate Computation¶

Well Controls¶

Rate Clamping¶

Well Scheduling¶

Grid Construction¶

Functions for building the spatial grids that represent reservoir geometry and initial conditions.

Grid Builders¶

Grid Aliases¶

These are aliases that call the same underlying functions. Prefer the build_* versions.

Grid Operations¶

Grid Data Containers¶

Rock-Fluid Properties¶

Models for relative permeability and capillary pressure.

Relative Permeability Models¶

Relative Permeability Table Registry¶

Three-Phase Mixing Rules¶

These functions compute oil relative permeability in three-phase flow from two-phase (oil-water and gas-oil) curves.

Capillary Pressure Models¶

PVT Tables¶

Tabular property lookup as an alternative to correlations.

Boundary Conditions¶

Types for specifying reservoir boundary behavior.

Boundary Classes¶

Boundary Types¶

Aquifer Support¶

Faults and Fractures¶

Solvers and Preconditioners¶

Linear solver and preconditioner infrastructure for the pressure equation.

Solvers¶

Preconditioners¶

Evolution Internals¶

Analysis¶

See the Model Analysis page for detailed usage.

Data Streaming and Storage¶

Streaming¶

Storage Backends¶

Serialization¶

The serialization system provides dictionary-based round-tripping for all BORES objects.

Visualization¶

The visualization system provides Plotly-based plotting for 1D time series, 2D maps, and 3D volume rendering.

Core Visualization¶

1D Plotting¶

For direct renderer access, import from bores.visualization.plotly1d:

2D Plotting¶

Import from bores.visualization.plotly2d:

3D Plotting¶

Import from bores.visualization.plotly3d:

PyVista 3D Plotting¶

Import from bores.visualization.pyvista3d:

from bores.visualization.pyvista3d import DataVisualizer, PlotConfig, PlotType

viz = DataVisualizer(config=PlotConfig(
    width=1200,
    height=960,
    plot_type=PlotType.CELL_BLOCKS,
    smooth_shading=True,
    enable_picking=True,
))

# Single plot from a model state
plotter = viz.make_plot(state, property="pressure", title="Reservoir Pressure")
plotter.show()

# Animation from simulation states
plotters = viz.animate(
    states,
    property="oil_saturation",
    step_size=5,
    save=bores.GifExporter("saturation.gif"),
)

Precision Control¶

Functions for controlling the floating-point precision used throughout the simulator.

import bores

# Default is 32-bit
bores.use_64bit_precision()

# Or temporarily
with bores.with_precision("float64"):
    model = bores.reservoir_model(...)

Types and Enums¶

Type aliases and enumerations used throughout the API.

Enums¶

Dimension Types¶

Grid Types¶

Function Types¶

Property Types¶

Constants¶

The constants system provides named, documented physical constants with unit information.

import bores

print(bores.c.STANDARD_PRESSURE)      # 14.696 psi
print(bores.c.STANDARD_TEMPERATURE)   # 60.0 F
print(bores.c.GAS_CONSTANT)           # 10.7316 psi*ft³/(lbmol*R)

Errors¶

All BORES exceptions inherit from BORESError. You can catch BORESError to handle any BORES-specific error, or catch specific subclasses for targeted handling.

import bores

try:
    model = bores.reservoir_model(porosity=-0.1, ...)
except bores.ValidationError as exc:
    print(f"Invalid model: {exc}")

try:
    for step in bores.run(model=model, config=config):
        pass
except bores.SolverError as exc:
    print(f"Solver failed: {exc}")
except bores.SimulationError as exc:
    print(f"Simulation error: {exc}")

Utility Functions¶

Low-level array utility functions. These are primarily used internally but are available if you need them for custom computations.

PVT Correlations¶

Scalar and array PVT correlation functions are documented separately due to their size:

• Scalar Correlations: 60+ single-value functions for point PVT calculations. Use these for quick checks, building custom tables, or validating against lab data.
• Array Correlations: Vectorized equivalents that operate on entire grids in a single call. The simulator uses these internally, and you can use them for post-processing or custom property computations.

Both modules share the same function names and parameters. The only difference is that scalar functions accept float inputs and array functions accept NDimensionalGrid inputs.