Constants¶

Overview¶

BORES uses a system of physical constants and unit conversion factors throughout its calculations. These constants cover standard conditions (pressure, temperature), fluid densities, molecular weights, conversion factors between SI and imperial units, and numerical thresholds that control simulation behavior. Rather than scattering magic numbers throughout the code, all constants are centralized in a Constants class that you can inspect, modify, and even temporarily override during a simulation.

The constants system is designed around the reservoir engineering convention of using imperial (oilfield) units internally: pressures in psi, temperatures in Fahrenheit, permeabilities in millidarcies, viscosities in centipoise, and volumes in barrels and cubic feet. Conversion factors to SI units are provided for every quantity so you can work in whichever system you prefer for input and output.

Understanding the constants is important for two reasons. First, if your reservoir uses non-standard conditions (for example, a different standard temperature or salinity), you can adjust the constants to match. Second, when debugging unexpected results, checking whether the correct constants are being used can quickly identify unit conversion errors.

The Global Constants Proxy¶

BORES provides a global constants proxy c that gives direct access to all default constant values. You can import and use it anywhere:

from bores.constants import c

# Access constant values with dot notation
print(c.STANDARD_PRESSURE_IMPERIAL)       # 14.696
print(c.STANDARD_TEMPERATURE_IMPERIAL)    # 60.0
print(c.MOLECULAR_WEIGHT_CO2)             # 44.01
print(c.BARRELS_TO_CUBIC_FEET)            # 5.614583

The proxy automatically returns the unwrapped value of each constant. If you need the full Constant object (with description and unit metadata), use bracket notation:

from bores.constants import c

const = c["STANDARD_PRESSURE_IMPERIAL"]
print(const.value)        # 14.696
print(const.description)  # "Standard atmospheric pressure (Imperial units)"
print(const.unit)         # "psi"

You can also use get_constant() for safe access with a default:

from bores.constants import get_constant

const = get_constant("STANDARD_PRESSURE_IMPERIAL")
if const is not None:
    print(f"{const.description}: {const.value} {const.unit}")

Available Constants¶

Standard Conditions¶

Standard Densities¶

Molecular Weights¶

Thermal and Compressibility Properties¶

Gas Constant¶

Pressure Conversions¶

Temperature Conversions¶

Viscosity Conversions¶

Permeability Conversions¶

Volume Conversions¶

Length Conversions¶

Time Conversions¶

Flow Rate Conversions¶

Transmissibility Conversions¶

Gravity¶

Numerical Thresholds¶

Reservoir Fluid Defaults¶

Valid Ranges¶

The Constants Class¶

The Constants class is a dictionary-like container that stores all constants as Constant objects. Each Constant wraps a value with optional description and unit metadata.

from bores.constants import Constants, Constant

# Create with default constants
constants = Constants()

# Access a value
print(constants.STANDARD_PRESSURE_IMPERIAL)  # 14.696

# Access the full Constant object
const = constants["STANDARD_PRESSURE_IMPERIAL"]
print(const)  # Constant(value=14.696, description='...', unit='psi')

Modifying Constants¶

You can modify constants at runtime using dot notation or bracket notation:

from bores.constants import Constants, Constant

constants = Constants()

# Set a raw value (auto-wrapped in Constant)
constants.DEFAULT_WATER_SALINITY_PPM = 50000

# Set with full metadata
constants["MY_CUSTOM_VALUE"] = Constant(
    value=42.0,
    description="Custom parameter for my model",
    unit="psi",
)

Using Custom Constants in a Simulation¶

The Config accepts a Constants instance, allowing you to customize constants for a specific simulation:

from bores.constants import Constants

# Create custom constants
custom = Constants()
custom.DEFAULT_WATER_SALINITY_PPM = 100000  # Very saline formation water

config = bores.Config(
    timer=timer,
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
    constants=custom,
)

Temporary Constants Override¶

For temporary overrides, use the Constants instance as a context manager. Within the context, the global proxy c points to your custom constants. Outside, the defaults are restored:

from bores.constants import Constants, c

# Create custom constants
custom = Constants()
custom.STANDARD_TEMPERATURE_IMPERIAL = 70.0  # Different standard temp

# Temporarily override global constants
with custom():
    print(c.STANDARD_TEMPERATURE_IMPERIAL)  # 70.0
    # All BORES functions called here use 70 F as standard temperature

# Outside the context, original defaults are restored
print(c.STANDARD_TEMPERATURE_IMPERIAL)  # 60.0

This mechanism uses Python's ContextVar system and is thread-safe. Each thread maintains its own constants context, so overrides in one thread do not affect other threads.

Iterating Over Constants¶

The Constants class supports iteration, length, and containment checks:

from bores.constants import Constants

constants = Constants()

# Count all constants
print(len(constants))  # Number of defined constants

# Check if a constant exists
if "MOLECULAR_WEIGHT_CO2" in constants:
    print("CO2 molecular weight is defined")

# Iterate over all constant names
for name in constants:
    print(name)

# Iterate over name-value pairs
for name, const in constants.items():
    print(f"{name}: {const.value} {const.unit or ''}")

Creating Custom Constants¶

You can define your own Constant objects for project-specific parameters:

from bores.constants import Constant, Constants

# Create a Constants instance with custom values
project_constants = Constants()
project_constants["FORMATION_WATER_VISCOSITY"] = Constant(
    value=0.7,
    description="Measured formation water viscosity at reservoir conditions",
    unit="cP",
)
project_constants["INJECTION_WATER_VISCOSITY"] = Constant(
    value=0.5,
    description="Treated injection water viscosity",
    unit="cP",
)

Custom constants coexist with the default constants. You can use them to store project-specific parameters alongside the standard physical constants, keeping all numerical values in one inspectable location.