oil_compressibility
Calculate oil compressibility coefficient to measure volume changes with pressure for material balance calculations, pressure transient analysis, and reserve estimation in petroleum engineering.
Instructions
Calculate oil compressibility (Co).
CRITICAL PVT PROPERTY - Computes oil compressibility coefficient, which measures how much oil volume changes with pressure. Essential for material balance calculations, pressure transient analysis, and reserve estimation. Co is typically 5-50 × 10⁻⁶ 1/psi.
Parameters:
p (float or list, required): Pressure(s) in psia. Must be > 0. Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000].
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.
pb (float, required): Bubble point pressure in psia. Must be ≥ 0. Example: 3500.0.
sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.75.
rs (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb. If 0, will be calculated. Must match p shape. Example: 600.0.
rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. Required if pb provided. Example: 800.0.
Compressibility Behavior:
p < pb: Co is relatively constant (oil + dissolved gas compressibility)
p = pb: Co increases sharply (gas evolution begins)
p > pb: Co decreases with pressure (gas compressibility dominates)
Typical Ranges:
Undersaturated oil: 5-20 × 10⁻⁶ 1/psi
At bubble point: 20-50 × 10⁻⁶ 1/psi
Above bubble point: 10-30 × 10⁻⁶ 1/psi
Returns: Dictionary with:
value (float or list): Compressibility in 1/psi (matches input p shape)
method (str): "McCain"
units (str): "1/psi"
inputs (dict): Echo of input parameters
Common Mistakes:
Not providing pb (required for accurate calculation)
Using wrong pressure (must be reservoir pressure, not separator)
Confusing oil compressibility with gas compressibility
Not accounting for dissolved gas effects
Example Usage:
Result: Co ≈ 10-15 × 10⁻⁶ 1/psi below bubble point, increases near pb.
Note: Compressibility is critical for material balance calculations. Always provide pb for accurate results. Co values are small (micro-1/psi), so results are typically in scientific notation.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Implementation Reference
- The @mcp.tool()-decorated handler function that executes the oil compressibility calculation using pyrestoolbox.oil.oil_co().@mcp.tool() def oil_compressibility(request: OilCompressibilityRequest) -> dict: """Calculate oil compressibility (Co). **CRITICAL PVT PROPERTY** - Computes oil compressibility coefficient, which measures how much oil volume changes with pressure. Essential for material balance calculations, pressure transient analysis, and reserve estimation. Co is typically 5-50 × 10⁻⁶ 1/psi. **Parameters:** - **p** (float or list, required): Pressure(s) in psia. Must be > 0. Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000]. - **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. - **pb** (float, required): Bubble point pressure in psia. Must be ≥ 0. Example: 3500.0. - **sg_g** (float, required): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.75. - **rs** (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb. If 0, will be calculated. Must match p shape. Example: 600.0. - **rsb** (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. Required if pb provided. Example: 800.0. **Compressibility Behavior:** - **p < pb**: Co is relatively constant (oil + dissolved gas compressibility) - **p = pb**: Co increases sharply (gas evolution begins) - **p > pb**: Co decreases with pressure (gas compressibility dominates) **Typical Ranges:** - Undersaturated oil: 5-20 × 10⁻⁶ 1/psi - At bubble point: 20-50 × 10⁻⁶ 1/psi - Above bubble point: 10-30 × 10⁻⁶ 1/psi **Returns:** Dictionary with: - **value** (float or list): Compressibility in 1/psi (matches input p shape) - **method** (str): "McCain" - **units** (str): "1/psi" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Not providing pb (required for accurate calculation) - Using wrong pressure (must be reservoir pressure, not separator) - Confusing oil compressibility with gas compressibility - Not accounting for dissolved gas effects **Example Usage:** ```python { "p": [2000, 3000, 4000], "api": 35.0, "degf": 180.0, "pb": 3500.0, "sg_g": 0.75, "rs": [400, 600, 800], "rsb": 800.0 } ``` Result: Co ≈ 10-15 × 10⁻⁶ 1/psi below bubble point, increases near pb. **Note:** Compressibility is critical for material balance calculations. Always provide pb for accurate results. Co values are small (micro-1/psi), so results are typically in scientific notation. """ co = oil.oil_co( p=request.p, api=request.api, degf=request.degf, pb=request.pb, sg_g=request.sg_g, rsb=request.rsb, ) # Convert numpy array to list for JSON serialization if isinstance(co, np.ndarray): value = co.tolist() else: value = float(co) return { "value": value, "method": "McCain", "units": "1/psi", "inputs": request.model_dump(), }
- Pydantic model defining the input parameters and validation rules for the oil_compressibility tool.class OilCompressibilityRequest(BaseModel): """Request model for oil compressibility calculation.""" p: Union[float, List[float]] = Field( ..., description="Pressure (psia) - scalar or array" ) api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)") degf: float = Field( ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)" ) pb: float = Field(..., ge=0, description="Bubble point pressure (psia)") sg_g: float = Field( ..., ge=0, le=3, description="Gas specific gravity (air=1, dimensionless)" ) rs: Union[float, List[float]] = Field( ..., description="Solution GOR (scf/stb) - scalar or array" ) rsb: float = Field( 0.0, ge=0, description="Solution GOR at bubble point (scf/stb)" ) @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 positive") else: if v <= 0: raise ValueError("Value must be positive") return v
- src/pyrestoolbox_mcp/server.py:16-30 (registration)Registration of oil tools (including oil_compressibility) 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) register_gas_tools(mcp) register_inflow_tools(mcp) register_simtools_tools(mcp) register_brine_tools(mcp) register_layer_tools(mcp) register_library_tools(mcp)