oil_rate_linear
Calculate oil production rates for horizontal wells and linear flow systems using Darcy's law. Automatically computes PVT properties for reservoir performance analysis and completion design.
Instructions
Calculate oil production rate for linear flow.
INFLOW PERFORMANCE TOOL - Computes oil production rate for horizontal wells or wells with linear flow geometry using Darcy's law. Automatically calculates PVT properties (Rs, Bo, μo) at average pressure. Essential for horizontal well performance analysis and completion design.
Parameters:
pi (float, required): Initial/reservoir pressure in psia. Must be > 0. Example: 4000.0.
pb (float, required): Bubble point pressure in psia. Must be ≥ 0. Example: 3500.0. If pi < pb, reservoir is saturated (gas cap present).
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.
sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.75.
psd (float or list, required): Sandface/draining pressure(s) in psia. Must be > 0 and < pi. Can be scalar or array. Example: 1500.0 or [1000, 1500, 2000].
h (float, required): Net pay thickness in feet. Must be > 0. Typical: 10-200 ft. Example: 50.0.
k (float, required): Permeability in millidarcies (mD). Must be > 0. Typical: 1-1000 mD. Example: 100.0.
area (float, required): Cross-sectional flow area in square feet. Must be > 0. Typical: 100-10000 ft². Example: 1000.0.
length (float, required): Flow length in feet. Must be > 0. Typical: 100-5000 ft. Example: 500.0.
rsb (float, required): Solution GOR at bubble point in scf/stb. Must be ≥ 0. Example: 800.0.
Flow Geometry: Linear flow occurs in:
Horizontal wells (early-time flow)
Hydraulically fractured vertical wells (fracture flow)
Channelized reservoirs
Edge water drive systems
Darcy's Law Formula (Linear): qo = (0.001127 × k × area × (pi - pwf)) / (μo × Bo × length)
Where PVT properties (μo, Bo) are calculated at average pressure (pi + pwf)/2.
Linear vs Radial Flow:
Linear: Flow perpendicular to wellbore (horizontal wells)
Radial: Flow converging to wellbore (vertical wells)
Linear flow typically has higher productivity than radial
Returns: Dictionary with:
value (float or list): Oil rate in STB/day (matches input psd shape)
method (str): "Darcy linear flow"
units (str): "STB/day"
inputs (dict): Echo of input parameters
Common Mistakes:
Using separator temperature instead of reservoir temperature
Pressure in barg/psig instead of psia (must be absolute)
Confusing flow area (perpendicular to flow) with wellbore area
Using wrong flow length (should be distance from boundary to well)
Not accounting for net pay thickness correctly
Confusing linear flow (horizontal wells) with radial flow (vertical wells)
Example Usage:
Result: Oil rate decreases as sandface pressure increases (typical IPR curve).
Note: This tool automatically calculates PVT properties. You don't need to provide Rs, Bo, or μo - they are computed internally at average pressure. Linear flow is characteristic of horizontal wells and hydraulically fractured wells.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Input Schema (JSON Schema)
Implementation Reference
- The @mcp.tool()-decorated handler function that implements the core logic for the 'oil_rate_linear' tool. It calculates PVT properties, invokes pyrestoolbox.oil.oil_rate_linear, and formats the response.@mcp.tool() def oil_rate_linear(request: OilRateLinearRequest) -> dict: """Calculate oil production rate for linear flow. **INFLOW PERFORMANCE TOOL** - Computes oil production rate for horizontal wells or wells with linear flow geometry using Darcy's law. Automatically calculates PVT properties (Rs, Bo, μo) at average pressure. Essential for horizontal well performance analysis and completion design. **Parameters:** - **pi** (float, required): Initial/reservoir pressure in psia. Must be > 0. Example: 4000.0. - **pb** (float, required): Bubble point pressure in psia. Must be ≥ 0. Example: 3500.0. If pi < pb, reservoir is saturated (gas cap present). - **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. - **sg_g** (float, required): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.75. - **psd** (float or list, required): Sandface/draining pressure(s) in psia. Must be > 0 and < pi. Can be scalar or array. Example: 1500.0 or [1000, 1500, 2000]. - **h** (float, required): Net pay thickness in feet. Must be > 0. Typical: 10-200 ft. Example: 50.0. - **k** (float, required): Permeability in millidarcies (mD). Must be > 0. Typical: 1-1000 mD. Example: 100.0. - **area** (float, required): Cross-sectional flow area in square feet. Must be > 0. Typical: 100-10000 ft². Example: 1000.0. - **length** (float, required): Flow length in feet. Must be > 0. Typical: 100-5000 ft. Example: 500.0. - **rsb** (float, required): Solution GOR at bubble point in scf/stb. Must be ≥ 0. Example: 800.0. **Flow Geometry:** Linear flow occurs in: - Horizontal wells (early-time flow) - Hydraulically fractured vertical wells (fracture flow) - Channelized reservoirs - Edge water drive systems **Darcy's Law Formula (Linear):** qo = (0.001127 × k × area × (pi - pwf)) / (μo × Bo × length) Where PVT properties (μo, Bo) are calculated at average pressure (pi + pwf)/2. **Linear vs Radial Flow:** - Linear: Flow perpendicular to wellbore (horizontal wells) - Radial: Flow converging to wellbore (vertical wells) - Linear flow typically has higher productivity than radial **Returns:** Dictionary with: - **value** (float or list): Oil rate in STB/day (matches input psd shape) - **method** (str): "Darcy linear flow" - **units** (str): "STB/day" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using separator temperature instead of reservoir temperature - Pressure in barg/psig instead of psia (must be absolute) - Confusing flow area (perpendicular to flow) with wellbore area - Using wrong flow length (should be distance from boundary to well) - Not accounting for net pay thickness correctly - Confusing linear flow (horizontal wells) with radial flow (vertical wells) **Example Usage:** ```python { "pi": 4000.0, "pb": 3500.0, "api": 35.0, "degf": 180.0, "sg_g": 0.75, "psd": [1500, 2000, 2500], "h": 50.0, "k": 100.0, "area": 1000.0, "length": 500.0, "rsb": 800.0 } ``` Result: Oil rate decreases as sandface pressure increases (typical IPR curve). **Note:** This tool automatically calculates PVT properties. You don't need to provide Rs, Bo, or μo - they are computed internally at average pressure. Linear flow is characteristic of horizontal wells and hydraulically fractured wells. """ # Convert psd to numpy array for processing psd_array = np.asarray(request.psd) is_scalar = psd_array.ndim == 0 if is_scalar: psd_array = np.array([psd_array]) # Calculate oil specific gravity from API sg_o = oil.oil_sg(api_value=request.api) # Calculate average pressures for PVT avg_pressures = (request.pi + psd_array) / 2.0 # Calculate Rs at average pressures rs_avg = oil.oil_rs( api=request.api, degf=request.degf, p=avg_pressures, sg_sp=request.sg_g, # Use sg_g as separator gas SG pb=request.pb, rsb=request.rsb, rsmethod=rs_method.VELAR, ) # Calculate Bo and uo at average pressures bo_values = oil.oil_bo( p=avg_pressures, pb=request.pb, degf=request.degf, rs=rs_avg, rsb=request.rsb, sg_o=sg_o, sg_g=request.sg_g, bomethod=bo_method.MCAIN, ) uo_values = oil.oil_viso( p=avg_pressures, api=request.api, degf=request.degf, pb=request.pb, rs=rs_avg, ) # Convert to scalars if needed if is_scalar: bo_values = float(bo_values[0]) if isinstance(bo_values, np.ndarray) else float(bo_values) uo_values = float(uo_values[0]) if isinstance(uo_values, np.ndarray) else float(uo_values) psd_array = psd_array[0] # Call oil_rate_linear with correct parameters qo = oil.oil_rate_linear( k=request.k, pr=request.pi, pwf=psd_array, area=request.area, length=request.length, uo=uo_values, bo=bo_values, vogel=False, pb=request.pb, ) # Convert numpy array to list for JSON serialization if isinstance(qo, np.ndarray): value = qo.tolist() else: value = float(qo) return { "value": value, "method": "Darcy linear flow", "units": "STB/day", "inputs": request.model_dump(), }
- Pydantic BaseModel defining the input schema and validation for the oil_rate_linear tool parameters.class OilRateLinearRequest(BaseModel): """Request model for linear oil inflow performance calculation.""" pi: float = Field(..., gt=0, description="Initial reservoir pressure (psia)") pb: float = Field(..., ge=0, description="Bubble point pressure (psia)") api: float = Field(..., gt=0, le=100, description="Oil API gravity (degrees)") degf: float = Field( ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)" ) sg_g: float = Field( ..., ge=0, le=3, description="Gas specific gravity (air=1, dimensionless)" ) psd: Union[float, List[float]] = Field( ..., description="Sandface pressure (psia) - scalar or array" ) h: float = Field(..., gt=0, description="Net pay thickness (ft)") k: float = Field(..., gt=0, description="Permeability (mD)") area: float = Field(..., gt=0, description="Drainage area (sq ft)") length: float = Field(..., gt=0, description="Well length (ft)") rsb: float = Field( 0.0, ge=0, description="Solution GOR at bubble point (scf/stb)" ) @field_validator("psd") @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 sandface pressure values must be positive") else: if v <= 0: raise ValueError("Sandface pressure must be positive") return v
- src/pyrestoolbox_mcp/server.py:18-30 (registration)The server.py file imports and calls register_inflow_tools(mcp) at line 26, which registers the oil_rate_linear tool (along with others) to the FastMCP server instance.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)
- src/pyrestoolbox_mcp/tools/inflow_tools.py:21-21 (registration)The register_inflow_tools function that defines and registers all inflow tools including oil_rate_linear using @mcp.tool() decorators.def register_inflow_tools(mcp: FastMCP) -> None:
- Export of OilRateLinearRequest model in the models package __init__.OilRateLinearRequest, GasRateRadialRequest, GasRateLinearRequest, ) __all__ = [ "MethodResponse", "ArrayInput", "BubblePointRequest", "SolutionGORRequest", "OilFVFRequest", "OilViscosityRequest", "OilDensityRequest", "OilCompressibilityRequest", "APIConversionRequest", "SGConversionRequest", "BlackOilTableRequest", "EvolvedGasSGRequest", "JacobyAromaticitySGRequest", "TwuPropertiesRequest", "WeightedAverageGasSGRequest", "StockTankGORRequest", "CheckGasSGsRequest", "ZFactorRequest", "GasFVFRequest", "GasViscosityRequest", "GasDensityRequest", "GasCompressibilityRequest", "CriticalPropertiesRequest", "GasPseudopressureRequest", "GasPressureFromPZRequest", "GasSGFromGradientRequest", "GasWaterContentRequest", "GasSGFromCompositionRequest", "RelPermTableRequest", "InfluenceTableRequest", "RachfordRiceRequest", "ExtractProblemCellsRequest", "ZipSimDeckRequest", "BrinePropertiesRequest", "CO2BrineMixtureRequest", "LorenzRequest", "FlowFractionRequest", "LayerDistributionRequest", "ComponentPropertiesRequest", "OilRateRadialRequest", "OilRateLinearRequest",