Configuration¶

Overview¶

The Config class holds every parameter that controls how a BORES simulation runs. It specifies the timer (time stepping behavior), the rock-fluid tables (relative permeability and capillary pressure models), the wells, the numerical scheme, the solvers, the preconditioners, the convergence tolerances, and all the physical constraints that keep the simulation stable and accurate.

Config is a frozen (immutable) attrs class. Once you create a Config, its fields cannot be changed in place. To modify a configuration, you create a new one using the copy() or with_updates() methods. This immutability prevents accidental modification of simulation parameters during a run and makes configurations safe to pass between functions without defensive copying.

Every simulation in BORES requires a Config. You pass it (along with a reservoir model) to bores.run() to start the simulation. The Config is the single point of control for all numerical behavior. If two simulations use different schemes, solvers, or convergence criteria, those differences are captured entirely in their respective Config objects.

Creating a Config¶

At minimum, a Config requires a Timer and a RockFluidTables:

import bores

rock_fluid_tables = bores.RockFluidTables(
    relative_permeability_table=bores.BrooksCoreyThreePhaseRelPermModel(
        irreducible_water_saturation=0.25,
        residual_oil_saturation_water=0.30,
        residual_oil_saturation_gas=0.15,
        residual_gas_saturation=0.05,
        water_exponent=2.5,
        oil_exponent=2.0,
        gas_exponent=2.0,
    ),
    capillary_pressure_table=bores.BrooksCoreyCapillaryPressureModel(
        irreducible_water_saturation=0.25,
        residual_oil_saturation_water=0.30,
        residual_oil_saturation_gas=0.15,
        residual_gas_saturation=0.05,
    ),
)

config = bores.Config(
    timer=bores.Timer(
        initial_step_size=bores.Time(days=1),
        max_step_size=bores.Time(days=10),
        min_step_size=bores.Time(hours=1),
        simulation_time=bores.Time(years=3),
    ),
    rock_fluid_tables=rock_fluid_tables,
)

This creates a valid configuration with all defaults. The IMPES scheme, BiCGSTAB solver with ILU preconditioning, and standard convergence tolerances are used automatically.

Adding Wells¶

Most simulations include wells. Pass them through the wells parameter:

wells = bores.wells_(injectors=[injector], producers=[producer])

config = bores.Config(
    timer=bores.Timer(
        initial_step_size=bores.Time(days=1),
        max_step_size=bores.Time(days=10),
        min_step_size=bores.Time(hours=1),
        simulation_time=bores.Time(years=3),
    ),
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
)

Adding Well Schedules¶

For simulations with time-varying well controls, use well_schedules:

config = bores.Config(
    timer=timer,
    rock_fluid_tables=rock_fluid_tables,
    well_schedules=schedules,
)

When well_schedules is provided, the simulator automatically switches well controls at the scheduled times. See the Well Scheduling page for details.

Adding Boundary Conditions¶

Boundary conditions (aquifer support, constant pressure boundaries, etc.) are specified through the boundary_conditions parameter:

config = bores.Config(
    timer=timer,
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
    boundary_conditions=boundary_conditions,
)

All Config Parameters¶

Required Parameters¶

Optional Model Parameters¶

Numerical Scheme¶

See Schemes for detailed information on each evolution scheme.

Solver Configuration¶

See Solvers and Preconditioners for details.

Time Step Controls¶

See Time Step Control for guidance on adjusting these.

Physical Controls¶

Fluid Mobility¶

The default relative mobility ranges are:

• Oil: \(10^{-12}\) to \(10^{6}\)
• Water: \(10^{-12}\) to \(10^{6}\)
• Gas: \(10^{-12}\) to \(10^{6}\)

These ranges prevent division by zero and numerical overflow in mobility calculations. You rarely need to change them.

Hysteresis¶

Output and Logging¶

Modifying a Config¶

Since Config is immutable, you cannot modify fields directly. Use copy() or with_updates() to create modified versions:

copy()¶

# Create a new config with a different scheme
implicit_config = config.copy(scheme="implicit")

# Multiple changes at once
tuned_config = config.copy(
    scheme="implicit",
    pressure_solver="gmres",
    pressure_preconditioner="amg",
    max_iterations=400,
)

with_updates()¶

with_updates() works the same way as copy() but validates that all provided keys are valid Config attributes:

# This works
updated = config.with_updates(scheme="implicit")

# This raises AttributeError because "schemee" is not a valid field
updated = config.with_updates(schemee="implicit")  # AttributeError

Use with_updates() when you want protection against typos in parameter names. Use copy() when you prefer the shorter name and are confident in the parameter names.

Freeze Saturation Pressure¶

The freeze_saturation_pressure flag controls whether the oil bubble point pressure (Pb) is recomputed at each time step or held constant at its initial value.

# Keep Pb constant (standard black-oil assumption)
config = bores.Config(
    timer=timer,
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
    freeze_saturation_pressure=True,
)

When freeze_saturation_pressure=True, the following properties are computed using the initial bubble point pressure rather than a dynamically updated value:

• Bubble point pressure (Pb) itself
• Solution gas-oil ratio (Rs)
• Oil formation volume factor (Bo)
• Oil compressibility (Co)
• Oil viscosity (indirectly through Rs)
• Oil density (indirectly through Rs and Bo)

This is appropriate for natural depletion and waterflooding where oil composition remains constant. Set it to False (the default) for miscible injection or any process where dissolved gas content changes significantly during the simulation.

Capillary Strength Factor¶

The capillary_strength_factor scales capillary pressure effects without changing the capillary pressure model itself. It ranges from 0.0 (no capillary effects) to 1.0 (full capillary effects).

# Reduce capillary effects by 50% for numerical stability
config = bores.Config(
    timer=timer,
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
    capillary_strength_factor=0.5,
)

Capillary gradients can become numerically dominant in fine meshes or at sharp saturation fronts, causing oscillations or overshoot. Reducing the capillary strength factor damps these effects without removing them entirely. This is a common technique for improving convergence in difficult models while preserving the qualitative influence of capillary pressure on fluid distribution.

Setting disable_capillary_effects=True is equivalent to capillary_strength_factor=0.0 but is more explicit in intent.

Example Configurations¶

Simple Depletion Study¶

config = bores.Config(
    timer=bores.Timer(
        initial_step_size=bores.Time(days=2),
        max_step_size=bores.Time(days=30),
        min_step_size=bores.Time(days=1),
        simulation_time=bores.Time(years=10),
    ),
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
    freeze_saturation_pressure=True,
)

High-Resolution Waterflood¶

config = bores.Config(
    timer=bores.Timer(
        initial_step_size=bores.Time(days=0.5),
        max_step_size=bores.Time(days=5),
        min_step_size=bores.Time(hours=1),
        simulation_time=bores.Time(years=5),
    ),
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
    pressure_solver="gmres",
    pressure_preconditioner="amg",
    max_water_saturation_change=0.15,
    max_pressure_change=50.0,
)

Miscible Gas Injection¶

config = bores.Config(
    timer=bores.Timer(
        initial_step_size=bores.Time(hours=6),
        max_step_size=bores.Time(days=3),
        min_step_size=bores.Time(minutes=30),
        simulation_time=bores.Time(years=3),
    ),
    rock_fluid_tables=rock_fluid_tables,
    wells=wells,
    miscibility_model="todd_longstaff",
    freeze_saturation_pressure=False,
    max_pressure_change=75.0,
)