pyResToolbox MCP Server

Instructions

Implementation Reference

• src/pyrestoolbox_mcp/tools/layer_tools.py:171-261 (handler)

  The core handler function for the 'lorenz_from_flow_fractions' tool, decorated with @mcp.tool() for automatic registration. Implements the logic using pyrestoolbox.layer library.
  @mcp.tool() def lorenz_from_flow_fractions(request: FlowFractionRequest) -> dict: """Calculate Lorenz coefficient from flow and permeability fractions. **LORENZ FROM PRODUCTION DATA** - Computes Lorenz coefficient from layer-by-layer flow and permeability data. Essential for analyzing actual production data and quantifying vertical conformance from measured production allocation. **Parameters:** - **flow_frac** (list, required): Flow fractions from each layer (0-1). Must sum to 1.0. Length must match perm_frac. Example: [0.1, 0.2, 0.3, 0.4]. - **perm_frac** (list, required): Permeability-thickness fractions (kh fractions) for each layer (0-1). Must sum to 1.0. Length must match flow_frac. Example: [0.05, 0.15, 0.25, 0.55]. **Input Data Sources:** - **PLT (Production Logging Tool):** Flow rate per layer from production logs - **Tracer Tests:** Flow allocation from tracer response - **Production Allocation:** Flow rates from well test analysis - **Core Data:** Permeability and thickness from core analysis - **Log Data:** Permeability from well logs, thickness from formation tops **Lorenz Coefficient Calculation:** Constructs Lorenz curve from data: 1. Sort layers by kh fraction (ascending) 2. Calculate cumulative kh fraction (x-axis) 3. Calculate cumulative flow fraction (y-axis) 4. Calculate area between curve and diagonal (45° line) 5. L = 2 × area (normalized to 0-1) **Interpretation:** - L < 0.3: High conformance (flow matches capacity) - L = 0.3-0.6: Moderate conformance (some flow imbalance) - L ≥ 0.6: Poor conformance (severe flow imbalance) **Applications:** - **Production Allocation Analysis:** Quantify vertical conformance from PLT data - **PLT Interpretation:** Convert PLT flow rates to heterogeneity measure - **Tracer Test Analysis:** Evaluate sweep efficiency from tracer response - **Vertical Conformance Evaluation:** Assess waterflood performance - **History Matching:** Match simulation to measured production allocation - **Performance Diagnosis:** Identify layers with poor conformance **Returns:** Dictionary with: - **lorenz_coefficient** (float): Lorenz coefficient (0-1) - **number_of_layers** (int): Number of layers analyzed - **method** (str): "Lorenz from flow and permeability fractions" - **interpretation** (str): Conformance level guidance - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Flow fractions don't sum to 1.0 (must normalize) - Perm fractions don't sum to 1.0 (must normalize) - Length mismatch between flow_frac and perm_frac - Using weight fractions instead of flow fractions - Not sorting layers correctly (must sort by kh) - Using wrong kh calculation (must be k × h, not just k) **Example Usage:** ```python { "flow_frac": [0.1, 0.2, 0.3, 0.4], "perm_frac": [0.05, 0.15, 0.25, 0.55] } ``` Result: L ≈ 0.4-0.5 (moderate conformance - high-k layers produce more than their capacity fraction, low-k layers produce less). **Note:** This is the most direct way to calculate Lorenz from actual production data. Always ensure fractions sum to 1.0 and layers are correctly matched. High L indicates poor vertical conformance (flow imbalance). """ lorenz = layer.lorenz_from_flow_fraction( kh_frac=request.flow_frac[0], # Use first value as kh_frac phih_frac=request.perm_frac[0], # Use first value as phih_frac ) return { "lorenz_coefficient": float(lorenz), "number_of_layers": len(request.flow_frac), "method": "Lorenz from flow and permeability fractions", "interpretation": ( "High conformance (L<0.3)" if lorenz < 0.3 else "Moderate conformance (0.3≤L<0.6)" if lorenz < 0.6 else "Poor conformance (L≥0.6)" ), "inputs": request.model_dump(), }
• src/pyrestoolbox_mcp/models/layer_models.py:13-40 (schema)

  Pydantic model defining the input schema for the tool, including validation for flow_frac and perm_frac lists that sum to approximately 1.0.
  class FlowFractionRequest(BaseModel): """Request model for flow fraction calculations.""" model_config = ConfigDict( json_schema_extra={ "example": { "flow_frac": [0.8, 0.15, 0.05], "perm_frac": [0.6, 0.3, 0.1], } } ) flow_frac: List[float] = Field( ..., min_length=2, description="Flow fractions per layer" ) perm_frac: List[float] = Field( ..., min_length=2, description="Permeability-thickness fractions per layer" ) @field_validator("flow_frac", "perm_frac") @classmethod def validate_fractions(cls, v): """Validate fractions sum to ~1.0.""" total = sum(v) if not (0.99 <= total <= 1.01): raise ValueError(f"Fractions must sum to 1.0 (got {total})") return v
• src/pyrestoolbox_mcp/server.py:21-29 (registration)

  Imports and calls register_layer_tools(mcp) which defines and registers the lorenz_from_flow_fractions tool along with other layer 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)
• src/pyrestoolbox_mcp/tools/layer_tools.py:14-16 (registration)

  The register_layer_tools function that contains the nested @mcp.tool()-decorated handler definitions for layer tools, including lorenz_from_flow_fractions.
  def register_layer_tools(mcp: FastMCP) -> None: """Register all layer/heterogeneity tools with the MCP server."""