oil_formation_volume_factor
Calculate oil formation volume factor (Bo) to convert reservoir oil volume to standard conditions for material balance, reserve estimation, and production forecasting.
Instructions
Calculate oil formation volume factor (Bo).
CRITICAL PVT PROPERTY - Computes ratio of oil volume at reservoir conditions to volume at standard conditions. Bo > 1.0 because oil expands due to dissolved gas and thermal expansion. Essential for material balance, reserve calculations, and production forecasting.
Parameters:
api (float, required): Oil API gravity in degrees. Valid: 0-100. Example: 35.0.
degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000. Example: 180.0.
p (float or list, required): Pressure(s) in psia. Must be > 0. Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000].
sg_g (float, optional, default=0.0): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.75.
pb (float, optional, default=0.0): Bubble point pressure in psia. Required for accurate calculation. Example: 3500.0.
rs (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb. If 0, will be calculated from p. Must match p shape. Example: 600.0 or [400, 600, 800].
rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. Required if pb provided. Example: 800.0.
method (str, optional, default="MCAIN"): Correlation method. Options: "MCAIN", "STAN". MCAIN recommended.
Pressure Behavior:
p < pb: Bo increases with pressure (more gas dissolves)
p = pb: Bo reaches maximum (Bob, typically 1.2-2.0 rb/stb)
p > pb: Bo decreases with pressure (oil compressibility dominates)
Method Selection:
MCAIN (McCain et al. 1988): Recommended. More accurate, wider range.
STAN (Standing 1947): Classic method. Use for compatibility.
Returns: Dictionary with:
value (float or list): Bo in rb/stb (matches input p shape)
method (str): Method used
units (str): "rb/stb"
inputs (dict): Echo of input parameters
Common Mistakes:
Not providing rs when p < pb (will calculate incorrectly)
Using separator GOR instead of solution GOR at reservoir pressure
Pressure in barg/psig instead of psia
Confusing Bo (reservoir volume) with Bg (gas FVF)
Example Usage:
Result: Bo increases from ~1.15 rb/stb at 2000 psia to ~1.35 rb/stb at 3500 psia, then decreases to ~1.33 rb/stb at 4000 psia (above bubble point).
Note: Always provide rs for pressures below bubble point. If rs=0, tool will calculate it, but providing it explicitly improves accuracy.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Implementation Reference
- The handler function decorated with @mcp.tool() that implements the core logic for calculating the oil formation volume factor (Bo) using pyrestoolbox.oil.oil_bo with methods MCAIN or STAN.@mcp.tool() def oil_formation_volume_factor(request: OilFVFRequest) -> dict: """Calculate oil formation volume factor (Bo). **CRITICAL PVT PROPERTY** - Computes ratio of oil volume at reservoir conditions to volume at standard conditions. Bo > 1.0 because oil expands due to dissolved gas and thermal expansion. Essential for material balance, reserve calculations, and production forecasting. **Parameters:** - **api** (float, required): Oil API gravity in degrees. Valid: 0-100. Example: 35.0. - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000. Example: 180.0. - **p** (float or list, required): Pressure(s) in psia. Must be > 0. Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000]. - **sg_g** (float, optional, default=0.0): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.75. - **pb** (float, optional, default=0.0): Bubble point pressure in psia. Required for accurate calculation. Example: 3500.0. - **rs** (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb. If 0, will be calculated from p. Must match p shape. Example: 600.0 or [400, 600, 800]. - **rsb** (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. Required if pb provided. Example: 800.0. - **method** (str, optional, default="MCAIN"): Correlation method. Options: "MCAIN", "STAN". MCAIN recommended. **Pressure Behavior:** - **p < pb**: Bo increases with pressure (more gas dissolves) - **p = pb**: Bo reaches maximum (Bob, typically 1.2-2.0 rb/stb) - **p > pb**: Bo decreases with pressure (oil compressibility dominates) **Method Selection:** - **MCAIN** (McCain et al. 1988): Recommended. More accurate, wider range. - **STAN** (Standing 1947): Classic method. Use for compatibility. **Returns:** Dictionary with: - **value** (float or list): Bo in rb/stb (matches input p shape) - **method** (str): Method used - **units** (str): "rb/stb" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Not providing rs when p < pb (will calculate incorrectly) - Using separator GOR instead of solution GOR at reservoir pressure - Pressure in barg/psig instead of psia - Confusing Bo (reservoir volume) with Bg (gas FVF) **Example Usage:** ```python { "api": 35.0, "degf": 180.0, "p": [2000, 3000, 4000], "sg_g": 0.75, "pb": 3500.0, "rs": [400, 600, 800], "rsb": 800.0, "method": "MCAIN" } ``` Result: Bo increases from ~1.15 rb/stb at 2000 psia to ~1.35 rb/stb at 3500 psia, then decreases to ~1.33 rb/stb at 4000 psia (above bubble point). **Note:** Always provide rs for pressures below bubble point. If rs=0, tool will calculate it, but providing it explicitly improves accuracy. """ method_enum = getattr(bo_method, request.method) # Calculate sg_o from API sg_o = oil.oil_sg(api_value=request.api) bo = oil.oil_bo( p=request.p, pb=request.pb, degf=request.degf, rs=request.rs, rsb=request.rsb, sg_o=sg_o, sg_g=request.sg_g, bomethod=method_enum, ) # Convert numpy array to list for JSON serialization if isinstance(bo, np.ndarray): value = bo.tolist() else: value = float(bo) return { "value": value, "method": request.method, "units": "rb/stb", "inputs": request.model_dump(), }
- Pydantic BaseModel defining the input schema (parameters and validation) for the oil_formation_volume_factor tool.class OilFVFRequest(BaseModel): """Request model for oil formation volume factor calculation.""" api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)") degf: float = Field( ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)" ) p: Union[float, List[float]] = Field( ..., description="Pressure (psia) - scalar or array" ) sg_g: float = Field( 0.0, ge=0, le=3, description="Gas specific gravity (air=1, dimensionless)" ) pb: float = Field(0.0, ge=0, description="Bubble point pressure (psia)") rs: Union[float, List[float]] = Field( 0.0, description="Solution GOR (scf/stb) - scalar or array" ) rsb: float = Field( 0.0, ge=0, description="Solution GOR at bubble point (scf/stb)" ) method: Literal["MCAIN", "STAN"] = Field( "MCAIN", description="Calculation method (MCAIN recommended)" ) @field_validator("p", "rs") @classmethod def validate_arrays(cls, v): """Validate array inputs.""" if isinstance(v, list): if not all(val >= 0 for val in v): raise ValueError("All values must be non-negative") else: if v < 0: raise ValueError("Value must be non-negative") return v
- src/pyrestoolbox_mcp/server.py:16-24 (registration)The registration of all oil tools (including oil_formation_volume_factor) by calling register_oil_tools(mcp) in the main FastMCP server initialization.from .tools.oil_tools import register_oil_tools from .tools.gas_tools import register_gas_tools from .tools.inflow_tools import register_inflow_tools from .tools.simtools_tools import register_simtools_tools from .tools.brine_tools import register_brine_tools from .tools.layer_tools import register_layer_tools from .tools.library_tools import register_library_tools register_oil_tools(mcp)