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),
        maximum_step_size=bores.Time(days=10),
        minimum_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),
        maximum_step_size=bores.Time(days=10),
        minimum_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.

Explicit Scheme Controls¶

Time Step Saturation Controls¶

Time Step Pressure 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.

Implicit Solver Configuration¶

These parameters control Newton-Raphson solvers in implicit and sequential-implicit schemes.

Sequential Implicit Outer Iteration Configuration¶

These parameters control outer loop convergence for the sequential-implicit scheme.

Additional Numerical Controls¶

Hysteresis¶

Output and Logging¶

Parallel Assembly with Task Pools¶

During each timestep, the pressure and saturation solvers assemble coefficient matrices from fluid properties, transmissibilities, and well contributions. In the IMPES scheme, the pressure solver has three independent assembly stages (accumulation terms, face transmissibilities, and well contributions) and the saturation solver has two independent stages (flux contributions and well rate grids). By default, these stages run sequentially on the calling thread. For larger grids, you can run them concurrently using a thread pool.

The task_pool parameter accepts a ThreadPoolExecutor that BORES uses to submit independent assembly stages in parallel. The calling thread blocks until all submitted stages complete, so the effective assembly time approaches the duration of the slowest stage rather than their sum. This can reduce assembly time by 30 to 50% for grids with 50,000 or more cells.

BORES provides the new_task_pool() context manager as the standard way to create and manage a pool. It creates the pool, yields it for use, and shuts it down cleanly when the block exits, whether normally or due to an exception.

import bores

with bores.new_task_pool(concurrency=3) as pool:
    config = bores.Config(
        timer=timer,
        rock_fluid_tables=rock_fluid_tables,
        wells=wells,
        task_pool=pool,
    )

    run = bores.Run(model=model, config=config)
    with bores.StateStream(run, store=store) as stream:
        for state in stream:
            process(state)
# Pool shuts down cleanly here

When to Use a Task Pool¶

The break-even point depends on grid size. Below about 10,000 cells, the overhead of thread synchronisation and future creation exceeds the time saved by concurrent execution. The benefit becomes noticeable around 50,000 cells and clearly measurable above 200,000 cells.

Concurrency Settings¶

Pass concurrency=3 for IMPES simulations. The pressure solver submits at most 3 tasks per call and the saturation solver submits at most 2, so 3 workers covers both without waste. If your machine has only 2 physical cores, use concurrency=2. Higher values provide no additional benefit because the current assembly design never submits more than 3 tasks per solver call.

Conditional Pool Based on Grid Size¶

If you want your code to work efficiently across different model sizes, you can conditionally create a pool:

import bores
from contextlib import nullcontext

nx, ny, nz = 50, 50, 20
cell_count = nx * ny * nz  # 50,000

if cell_count > 10_000:
    pool_context = bores.new_task_pool(concurrency=3)
else:
    pool_context = nullcontext(None)

with pool_context as pool:
    config = bores.Config(
        timer=timer,
        rock_fluid_tables=rock_fluid_tables,
        task_pool=pool,  # None for small grids, `ThreadPoolExecutor` for large
    )
    # ... run simulation

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="full-sequential-implicit")

# Multiple changes at once
tuned_config = config.copy(
    scheme="full-sequential-implicit",
    pressure_solver="gmres",
    pressure_preconditioner="amg",
    maximum_newton_iterations=20,
)

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="full-sequential-implicit")

# This raises AttributeError because "schemee" is not a valid field
updated = config.with_updates(schemee="full-sequential-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),
        maximum_step_size=bores.Time(days=30),
        minimum_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),
        maximum_step_size=bores.Time(days=5),
        minimum_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",
    maximum_water_saturation_change=0.15,
    maximum_pressure_change=50.0,
)

Miscible Gas Injection¶

config = bores.Config(
    timer=bores.Timer(
        initial_step_size=bores.Time(hours=6),
        maximum_step_size=bores.Time(days=3),
        minimum_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,
    maximum_pressure_change=75.0,
)