generate_layer_distribution
Generate permeability and thickness distributions for reservoir simulation layers using Lorenz coefficient to model heterogeneity for waterflood performance prediction.
Instructions
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:
Convert Lorenz to beta parameter
Generate log-normal permeability distribution
Sort layers by permeability (ascending)
Assign equal thickness to each layer
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:
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:
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Implementation Reference
- 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", }
- 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