pyResToolbox MCP Server

Instructions

{
    "value": 0.5
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/layer_tools.py:17-98 (handler)

  Handler function for 'lorenz_to_beta' tool. Converts Lorenz coefficient to Dykstra-Parsons beta using pyrestoolbox.layer.lorenz2b. Includes comprehensive docstring with usage, parameters, and interpretation.

  @mcp.tool()
  def lorenz_to_beta(request: LorenzRequest) -> dict:
      """Convert Lorenz coefficient to Dykstra-Parsons beta parameter.
  
      **HETEROGENEITY QUANTIFICATION** - Converts between two common measures of
      reservoir heterogeneity. Essential for comparing reservoirs using different
      heterogeneity metrics and for literature data conversion.
  
      **Parameters:**
      - **value** (float, required): Lorenz coefficient (0-1). Must be 0 ≤ L ≤ 1.
        Typical: 0.2-0.7. Example: 0.5 for moderate heterogeneity.
  
      **Lorenz Coefficient (L):**
      - Ranges from 0 (homogeneous) to 1 (completely heterogeneous)
      - Based on cumulative flow capacity vs cumulative storage capacity
      - Geometric interpretation: area between Lorenz curve and 45° line
      - L = 2 × area between curve and diagonal
      - Directly measurable from production data (PLT, tracer tests)
  
      **Dykstra-Parsons Beta (β):**
      - Permeability variation coefficient (dimensionless, 0-1)
      - β = (k50 - k84.1) / k50
      - Based on log-normal permeability distribution
      - Requires permeability data (core, logs)
      - Common in literature and older studies
  
      **Conversion Relationship:**
      Beta and Lorenz are related through log-normal distribution statistics.
      Higher Lorenz = higher Beta (both indicate more heterogeneity).
  
      **Typical Ranges:**
      - L < 0.3 (homogeneous): β < 0.5
      - L = 0.3-0.6 (moderate): β = 0.5-0.7
      - L > 0.6 (heterogeneous): β > 0.7
  
      **Applications:**
      - **Waterflood Sweep Efficiency:** Predict vertical sweep from heterogeneity
      - **Vertical Conformance Analysis:** Evaluate production allocation
      - **Reservoir Characterization:** Compare reservoirs using different metrics
      - **Performance Prediction:** Use beta in Dykstra-Parsons calculations
      - **Literature Conversion:** Convert published beta values to Lorenz
  
      **Returns:**
      Dictionary with:
      - **beta** (float): Dykstra-Parsons beta coefficient (0-1)
      - **lorenz_coefficient** (float): Input Lorenz coefficient
      - **method** (str): "Lorenz to Dykstra-Parsons conversion"
      - **interpretation** (dict): Heterogeneity level guidance
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Lorenz coefficient outside valid range (must be 0-1)
      - Confusing Lorenz with other heterogeneity measures
      - Using beta from wrong distribution (must be log-normal)
      - Not understanding that conversion is approximate (depends on distribution)
  
      **Example Usage:**
      ```python
      {
          "value": 0.5
      }
      ```
      Result: β ≈ 0.6-0.7 (moderate to high heterogeneity).
  
      **Note:** Conversion assumes log-normal permeability distribution. For
      non-log-normal distributions, conversion may be less accurate. Always
      validate against actual permeability data when possible.
      """
      beta = layer.lorenz2b(lorenz=request.value)
  
      return {
          "beta": float(beta),
          "lorenz_coefficient": request.value,
          "method": "Lorenz to Dykstra-Parsons conversion",
          "interpretation": {
              "lorenz_0": "Homogeneous reservoir",
              "lorenz_1": "Completely heterogeneous",
              "beta_low": "Low variation (<0.5)",
              "beta_high": "High variation (>0.7)",
          },
          "inputs": request.model_dump(),
      }

• src/pyrestoolbox_mcp/models/layer_models.py:7-11 (schema)

  Pydantic input schema LorenzRequest used by lorenz_to_beta and related tools. Defines 'value' as float between 0 and 1.

  class LorenzRequest(BaseModel):
      """Request model for Lorenz coefficient calculation."""
  
      value: float = Field(..., ge=0, le=1, description="Lorenz or beta value")

• src/pyrestoolbox_mcp/server.py:21-29 (registration)

  Registration of layer tools in the main MCP server. Imports and calls register_layer_tools(mcp), which defines and registers lorenz_to_beta among 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)

  Function that defines and registers all layer tools, including the lorenz_to_beta handler using @mcp.tool() decorator.

  def register_layer_tools(mcp: FastMCP) -> None:
      """Register all layer/heterogeneity tools with the MCP server."""