pyResToolbox MCP Server

Instructions

{
    "flow_frac": [0.1, 0.2, 0.3, 0.4],
    "perm_frac": [0.05, 0.15, 0.25, 0.55]
}

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."""