pyResToolbox MCP Server

Instructions

{
    "lorenz": 0.6,
    "nlay": 10,
    "k_avg": 100.0,
    "h": 100.0
}

{
    "lorenz": 0.6,
    "nlay": 10,
    "k_avg": 100.0,
    "h": 100.0
}

Implementation Reference

• src/pyrestoolbox_mcp/tools/layer_tools.py:343-484 (handler)

  The core handler function for the 'generate_layer_distribution' tool. It uses pyrestoolbox.layer.lorenz_2_layers to generate a log-normal permeability distribution across the specified number of layers matching the input Lorenz coefficient, computes layer properties (thickness, perm, fractions), statistics, and returns structured output.

  @mcp.tool()
  def generate_layer_distribution(request: LayerDistributionRequest) -> dict:
      """Generate layered permeability distribution from Lorenz coefficient.
  
      **LAYER PROPERTY GENERATION** - Creates detailed layer-by-layer permeability
      and thickness distribution matching specified heterogeneity. Essential for
      building reservoir simulation models and predicting waterflood performance.
  
      **Parameters:**
      - **lorenz** (float, required): Lorenz coefficient (0-1). Must be 0 ≤ L ≤ 1.
        Typical: 0.2-0.7. Example: 0.6 for moderate heterogeneity.
      - **nlay** (int, required): Number of layers to generate. Must be > 0.
        Typical: 5-50. Example: 10 for 10-layer model.
      - **k_avg** (float, required): Average permeability in mD. Must be > 0.
        Typical: 10-1000 mD. Example: 100.0 mD.
      - **h** (float, optional, default=100.0): Total thickness in feet.
        Must be > 0. Typical: 50-500 ft. Example: 100.0 ft.
  
      **Method:**
      Uses Dykstra-Parsons log-normal permeability distribution with correlation
      to Lorenz coefficient to generate realistic layer properties:
      1. Convert Lorenz to beta parameter
      2. Generate log-normal permeability distribution
      3. Sort layers by permeability (ascending)
      4. Assign equal thickness to each layer
      5. Calculate layer statistics
  
      **Output Properties:**
      For each layer:
      - **Thickness (ft):** Layer thickness (equal for all layers)
      - **Permeability (mD):** Layer permeability (log-normal distribution)
      - **Thickness Fraction:** Fraction of total thickness
      - **kh Fraction:** Fraction of total flow capacity (k × h)
  
      **Statistics Calculated:**
      - k_min, k_max: Minimum and maximum permeability
      - k_avg, k_median: Average and median permeability
      - k_std: Standard deviation
      - Heterogeneity ratio: k_max / k_min
  
      **Critical for:**
      - **Reservoir Simulation:** Generate layer properties for simulation models
      - **Waterflood Prediction:** Predict sweep efficiency and recovery
      - **Vertical Sweep Efficiency:** Analyze vertical conformance
      - **Conformance Studies:** Evaluate production allocation
      - **Upscaling:** Create coarse-scale models from fine-scale data
      - **Sensitivity Analysis:** Test impact of heterogeneity on performance
  
      **Usage Example:**
      For 10-layer simulation model with Lorenz=0.6:
      ```python
      {
          "lorenz": 0.6,
          "nlay": 10,
          "k_avg": 100.0,
          "h": 100.0
      }
      ```
      Result: 10 layers with permeabilities ranging from ~20 mD (low-k) to ~500 mD
      (high-k), each with 10 ft thickness. High-k layers have higher kh fractions.
  
      **Returns:**
      Dictionary with:
      - **layers** (list): List of dicts with layer properties (thickness, permeability, fractions)
      - **statistics** (dict): Permeability statistics (min, max, avg, median, std, ratio)
      - **total_thickness_ft** (float): Total thickness
      - **average_permeability_md** (float): Average permeability
      - **lorenz_coefficient** (float): Input Lorenz coefficient
      - **number_of_layers** (int): Number of layers
      - **method** (str): "Dykstra-Parsons log-normal distribution"
      - **note** (str): Usage guidance
      - **inputs** (dict): Echo of input parameters
  
      **Common Mistakes:**
      - Lorenz coefficient outside valid range (must be 0-1)
      - Too few layers (<5) causing poor resolution
      - Too many layers (>50) causing unnecessary complexity
      - Wrong average permeability (must match reservoir average)
      - Not understanding that layers are sorted by permeability
      - Confusing thickness fraction with absolute thickness
  
      **Example Usage:**
      ```python
      {
          "lorenz": 0.6,
          "nlay": 10,
          "k_avg": 100.0,
          "h": 100.0
      }
      ```
      Result: 10 layers with log-normal permeability distribution, each 10 ft thick.
      Permeability ranges from ~20 mD to ~500 mD, matching Lorenz=0.6 heterogeneity.
  
      **Note:** This generates idealized layer properties assuming log-normal
      permeability distribution and equal layer thickness. For actual reservoirs,
      use measured core or log data when available. Layer properties are ready
      for direct use in reservoir simulation models.
      """
      # lorenz_2_layers returns np.ndarray of permeabilities, assuming equal thickness
      k_values = layer.lorenz_2_layers(
          lorenz=request.lorenz,
          nlayers=request.nlay,
          k_avg=request.k_avg,
      )
      
      # Assume equal thickness layers
      h_values = np.ones(request.nlay) * request.h / request.nlay
      
      layer_data = []
      for i in range(request.nlay):
          layer_data.append({
              "layer": i + 1,
              "thickness_ft": float(h_values[i]),
              "permeability_md": float(k_values[i]),
              "thickness_fraction": float(h_values[i] / np.sum(h_values)),
              "kh_fraction": float(
                  k_values[i] * h_values[i] / np.sum(k_values * h_values)
              ),
          })
  
      # Calculate statistics
      statistics = {
          "k_min_md": float(np.min(k_values)),
          "k_max_md": float(np.max(k_values)),
          "k_avg_md": float(np.mean(k_values)),
          "k_median_md": float(np.median(k_values)),
          "k_std_md": float(np.std(k_values)),
          "heterogeneity_ratio": float(np.max(k_values) / np.min(k_values)),
      }
  
      return {
          "layers": layer_data,
          "statistics": statistics,
          "total_thickness_ft": float(np.sum(h_values)),
          "average_permeability_md": request.k_avg,
          "lorenz_coefficient": request.lorenz,
          "number_of_layers": request.nlay,
          "method": "Dykstra-Parsons log-normal distribution",
          "inputs": request.model_dump(),
          "note": "Use layer properties directly in reservoir simulation models",
      }

• src/pyrestoolbox_mcp/models/layer_models.py:42-66 (schema)

  Pydantic BaseModel defining the input schema (LayerDistributionRequest) with validation for lorenz (0-1), nlay (1-100), h (>0), k_avg (>0), normalize (bool). Includes example in json_schema_extra.

  class LayerDistributionRequest(BaseModel):
      """Request model for layer distribution generation."""
  
      model_config = ConfigDict(
          json_schema_extra={
              "example": {
                  "lorenz": 0.7,
                  "nlay": 10,
                  "normalize": True,
              }
          }
      )
  
      lorenz: float = Field(
          ..., ge=0, le=1, description="Lorenz coefficient (0=homogeneous, 1=heterogeneous)"
      )
      nlay: int = Field(..., gt=0, le=100, description="Number of layers")
      h: float = Field(1.0, gt=0, description="Total thickness (ft, default=1 for normalized)")
      k_avg: float = Field(
          1.0, gt=0, description="Average permeability (mD, default=1 for normalized)"
      )
      normalize: bool = Field(
          True, description="Normalize output (h and k fractions vs absolute)"
      )

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

  Explicit registration of all layer tools (including generate_layer_distribution) by calling register_layer_tools(mcp) in the main server setup.

  register_layer_tools(mcp)

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

  Import of the register_layer_tools function used to register the layer tools module.

  from .tools.layer_tools import register_layer_tools