oil_solution_gor
Calculate solution gas-oil ratio at specified pressure to determine dissolved gas volume in oil reservoirs using industry-standard correlations.
Instructions
Calculate solution gas-oil ratio (Rs) at specified pressure.
CRITICAL PVT PROPERTY - Computes volume of gas dissolved in oil at given pressure and temperature. Rs increases with pressure up to bubble point, then remains constant (equal to rsb) above bubble point.
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): Separator 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. If 0, will be calculated. Must be ≥ 0. Example: 3500.0.
rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. If 0 and pb provided, will be calculated. Must be ≥ 0. Example: 800.0.
method (str, optional, default="VELAR"): Correlation method. Options: "VELAR", "STAN", "VALMC".
Pressure Behavior:
p < pb: Rs calculated from correlation (increases with pressure)
p ≥ pb: Rs = rsb (constant, no additional gas dissolves)
Method Selection:
VELAR (Velarde 1997): Default, good accuracy. Use for most cases.
STAN (Standing 1947): Classic, widely used. Use for compatibility.
VALMC (Valko-McCain 2003): Alternative method.
Returns: Dictionary with:
value (float or list): Rs in scf/stb (matches input p shape)
method (str): Method used
units (str): "scf/stb"
inputs (dict): Echo of input parameters
Common Mistakes:
Using separator gas gravity instead of separator gas gravity (sg_g parameter)
Not providing pb when p > pb (will calculate incorrectly)
Pressure in barg/psig instead of psia (must be absolute)
Confusing rsb (at bubble point) with separator GOR
Example Usage:
Result: Rs increases from ~400 scf/stb at 2000 psia to 800 scf/stb at 3500 psia, then remains 800 scf/stb at 4000 psia (above bubble point).
Note: Always provide pb and rsb when available for accurate results. If unknown, set pb=0 and rsb=0 to auto-calculate, but accuracy may be reduced.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Input Schema (JSON Schema)
Implementation Reference
- Handler function that executes the oil_solution_gor tool logic. Uses pyrestoolbox.oil.oil_rs to compute solution GOR (Rs) based on input parameters, handles scalar/array inputs, and returns formatted result with units.@mcp.tool() def oil_solution_gor(request: SolutionGORRequest) -> dict: """Calculate solution gas-oil ratio (Rs) at specified pressure. **CRITICAL PVT PROPERTY** - Computes volume of gas dissolved in oil at given pressure and temperature. Rs increases with pressure up to bubble point, then remains constant (equal to rsb) above bubble point. **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): Separator 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. If 0, will be calculated. Must be ≥ 0. Example: 3500.0. - **rsb** (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. If 0 and pb provided, will be calculated. Must be ≥ 0. Example: 800.0. - **method** (str, optional, default="VELAR"): Correlation method. Options: "VELAR", "STAN", "VALMC". **Pressure Behavior:** - **p < pb**: Rs calculated from correlation (increases with pressure) - **p ≥ pb**: Rs = rsb (constant, no additional gas dissolves) **Method Selection:** - **VELAR** (Velarde 1997): Default, good accuracy. Use for most cases. - **STAN** (Standing 1947): Classic, widely used. Use for compatibility. - **VALMC** (Valko-McCain 2003): Alternative method. **Returns:** Dictionary with: - **value** (float or list): Rs in scf/stb (matches input p shape) - **method** (str): Method used - **units** (str): "scf/stb" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using separator gas gravity instead of separator gas gravity (sg_g parameter) - Not providing pb when p > pb (will calculate incorrectly) - Pressure in barg/psig instead of psia (must be absolute) - Confusing rsb (at bubble point) with separator GOR **Example Usage:** ```python { "api": 35.0, "degf": 180.0, "p": [2000, 3000, 4000], "sg_g": 0.75, "pb": 3500.0, "rsb": 800.0, "method": "VELAR" } ``` Result: Rs increases from ~400 scf/stb at 2000 psia to 800 scf/stb at 3500 psia, then remains 800 scf/stb at 4000 psia (above bubble point). **Note:** Always provide pb and rsb when available for accurate results. If unknown, set pb=0 and rsb=0 to auto-calculate, but accuracy may be reduced. """ method_enum = getattr(rs_method, request.method) rs = oil.oil_rs( api=request.api, degf=request.degf, p=request.p, sg_sp=request.sg_g, # oil_rs uses sg_sp not sg_g pb=request.pb, rsb=request.rsb, rsmethod=method_enum, ) # Convert numpy array to list for JSON serialization if isinstance(rs, np.ndarray): value = rs.tolist() else: value = float(rs) return { "value": value, "method": request.method, "units": "scf/stb", "inputs": request.model_dump(), }
- Pydantic BaseModel defining the input schema for the tool, with validation for fields like API gravity, temperature, pressure (scalar or list), gas gravity, bubble point pressure, Rsb, and method selection.class SolutionGORRequest(BaseModel): """Request model for solution gas-oil ratio 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)") rsb: float = Field( 0.0, ge=0, description="Solution GOR at bubble point (scf/stb)" ) method: Literal["VELAR", "STAN", "VALMC"] = Field( "VELAR", description="Calculation method" ) @field_validator("p") @classmethod def validate_pressure(cls, v): """Validate pressure values.""" if isinstance(v, list): if not all(p > 0 for p in v): raise ValueError("All pressure values must be positive") else: if v <= 0: raise ValueError("Pressure must be positive") return v
- src/pyrestoolbox_mcp/server.py:16-24 (registration)Registration of oil tools including oil_solution_gor by calling register_oil_tools(mcp) in the main MCP 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)