Array PVT Correlations¶

Overview¶

The bores.correlations.arrays module contains vectorized versions of every scalar PVT correlation from bores.correlations.core. Where the scalar module operates on single float values, the array module operates on NumPy arrays of any shape and dimension. These are the functions the simulator calls internally to compute fluid properties across the entire reservoir grid in a single pass, and you can use them for post-processing, custom property computations, or building property grids from scratch.

Every function in this module accepts NDimensionalGrid arrays (typed NumPy arrays parameterized by dimension) and returns arrays of the same shape. The functions use the same correlations, formulas, and valid ranges as their scalar counterparts. Many are compiled with Numba's @numba.njit decorator for performance-critical inner loops, while CoolProp-based functions iterate over array elements internally.

All units are the same as the scalar module: pressure in psi, temperature in degrees Fahrenheit, density in lbm/ft³, viscosity in cP, and formation volume factors in bbl/STB or ft³/SCF.

from bores.correlations.arrays import (
    compute_oil_formation_volume_factor,
    compute_gas_compressibility_factor,
    compute_oil_viscosity,
)

How Array Functions Differ from Scalar¶

The key differences between the array and scalar modules are:

Input types. Scalar functions accept float parameters. Array functions accept NDimensionalGrid[NDimension] parameters, which are NumPy arrays of shape (nx,), (nx, ny), or (nx, ny, nz) depending on the simulation dimensionality.

Broadcasting. Array functions follow NumPy broadcasting rules. You can pass a scalar value for a parameter that is uniform across the grid (like gas gravity) and it will be broadcast against the grid-shaped parameters (like pressure). Some parameters explicitly accept FloatOrArray types for this purpose.

Validation. Scalar functions raise ValidationError immediately when a single invalid value is detected. Array functions use min_() and max_() helpers to check the entire grid at once, raising an error if any element violates the constraint.

Precision. Array functions respect the global precision setting (use_32bit_precision() / use_64bit_precision()). Results are cast to the same dtype as the input arrays using the get_dtype() helper.

Numba compilation. Many array functions are decorated with @numba.njit(cache=True) for JIT compilation. The first call triggers compilation (typically 1-5 seconds), and subsequent calls use the cached machine code. CoolProp-based functions cannot be Numba-compiled and iterate over array elements with a Python loop instead.

Quick Example¶

import numpy as np
from bores.correlations.arrays import (
    compute_oil_formation_volume_factor,
    compute_gas_compressibility_factor,
    compute_oil_viscosity,
)

# Grid-shaped pressure and temperature arrays
grid_shape = (10, 10, 3)
pressure = np.full(grid_shape, 3000.0, dtype=np.float32)
temperature = np.full(grid_shape, 200.0, dtype=np.float32)
bubble_point = np.full(grid_shape, 2500.0, dtype=np.float32)
oil_sg = np.full(grid_shape, 0.85, dtype=np.float32)
gas_gravity = np.full(grid_shape, 0.70, dtype=np.float32)
gor = np.full(grid_shape, 500.0, dtype=np.float32)
oil_comp = np.full(grid_shape, 1e-5, dtype=np.float32)

# Compute Bo for every cell at once
Bo_grid = compute_oil_formation_volume_factor(
    pressure=pressure,
    temperature=temperature,
    bubble_point_pressure=bubble_point,
    oil_specific_gravity=oil_sg,
    gas_gravity=gas_gravity,
    gas_to_oil_ratio=gor,
    oil_compressibility=oil_comp,
)
print(f"Bo range: {Bo_grid.min():.4f} to {Bo_grid.max():.4f} bbl/STB")

Function Reference¶

The table below lists every public function in the array module. Each function has the same name, the same parameters, and uses the same correlation as its scalar counterpart. Click through to the Scalar Correlations page for detailed descriptions of formulas, valid ranges, and physical interpretation.

Generic Fluid Properties (CoolProp)¶

These functions iterate over each element of the input arrays and call CoolProp for each cell individually. They are slower than the correlation-based functions below but work for any fluid supported by CoolProp (CO2, N2, Methane, n-Octane, etc.).

Gas Gravity¶

Oil Properties¶

Gas Properties¶

Water Properties¶

Bubble Point and GOR¶

Multi-Phase and Volumetrics¶

Miscible Flooding (Todd-Longstaff)¶

Performance Notes¶

The array functions are designed for grid-level computation and are significantly faster than calling the scalar versions in a Python loop over cells. For a 100x100x20 grid (200,000 cells):

• Numba-compiled functions (most correlations): Run at near-C speed after the first compilation. Typical computation times are 1-10 ms per grid evaluation.
• CoolProp-based functions (compute_fluid_density, compute_fluid_viscosity, etc.): Iterate over elements in Python calling CoolProp for each cell. These are 10-100x slower than correlation-based functions but provide equation-of-state accuracy for non-standard fluids.

If you need CoolProp-level accuracy for standard reservoir fluids, consider computing properties once and storing them in a PVT table using bores.PVTTables, then using table lookup during simulation instead of repeated CoolProp calls.