flow_fractions_from_lorenz
Generate idealized flow distribution curves from Lorenz coefficients to model reservoir heterogeneity for simulation, waterflood prediction, and sweep efficiency analysis.
Instructions
Generate flow fractions from Lorenz coefficient.
SYNTHETIC FLOW PROFILE - Creates idealized flow distribution matching a specified Lorenz coefficient. Generates a Lorenz curve (cumulative flow vs cumulative capacity) that honors the target heterogeneity level.
Parameters:
value (float, required): Target Lorenz coefficient (0-1). Must be 0 ≤ L ≤ 1. Typical: 0.2-0.7. Example: 0.5 for moderate heterogeneity.
Lorenz Curve Generation: Creates a curve showing:
X-axis: Cumulative storage capacity (kh fraction)
Y-axis: Cumulative flow capacity (flow fraction)
Curve shape: Determined by Lorenz coefficient
Points: 20 points along the curve for visualization
Curve Behavior:
L = 0: Straight diagonal line (perfect conformance)
L > 0: Curved line below diagonal (flow imbalance)
Higher L: More curvature, greater flow imbalance
Applications:
Reservoir Simulation: Generate layer properties for simulation models
Waterflood Prediction: Predict sweep efficiency from heterogeneity
Sweep Efficiency Estimation: Estimate vertical sweep from Lorenz
Sensitivity Analysis: Test impact of heterogeneity on performance
Conceptual Models: Create idealized reservoir models for studies
Visualization: Plot Lorenz curve to visualize heterogeneity
Returns: Dictionary with:
cumulative_flow_capacity (list): Y-axis values (cumulative flow fractions)
cumulative_storage_capacity (list): X-axis values (cumulative kh fractions)
lorenz_coefficient (float): Target Lorenz coefficient
method (str): "Generated Lorenz curve"
note (str): Visualization guidance
inputs (dict): Echo of input parameters
Common Mistakes:
Lorenz coefficient outside valid range (must be 0-1)
Confusing cumulative fractions with incremental fractions
Not understanding that curve represents idealized distribution
Using curve for non-log-normal distributions (may be inaccurate)
Example Usage:
Result: Lorenz curve with 20 points showing cumulative flow vs cumulative capacity. Curve is below diagonal, indicating flow imbalance (high-k layers produce more than their capacity fraction).
Note: This generates an idealized Lorenz curve. For actual reservoirs,
use lorenz_from_flow_fractions with measured production data. The curve
assumes log-normal permeability distribution. Plot cumulative flow vs
cumulative storage to visualize heterogeneity.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Implementation Reference
- The core handler function for the 'flow_fractions_from_lorenz' tool. It generates cumulative flow and storage capacity fractions based on the input Lorenz coefficient using the external layer.lorenz_2_flow_frac function.@mcp.tool() def flow_fractions_from_lorenz(request: LorenzRequest) -> dict: """Generate flow fractions from Lorenz coefficient. **SYNTHETIC FLOW PROFILE** - Creates idealized flow distribution matching a specified Lorenz coefficient. Generates a Lorenz curve (cumulative flow vs cumulative capacity) that honors the target heterogeneity level. **Parameters:** - **value** (float, required): Target Lorenz coefficient (0-1). Must be 0 ≤ L ≤ 1. Typical: 0.2-0.7. Example: 0.5 for moderate heterogeneity. **Lorenz Curve Generation:** Creates a curve showing: - X-axis: Cumulative storage capacity (kh fraction) - Y-axis: Cumulative flow capacity (flow fraction) - Curve shape: Determined by Lorenz coefficient - Points: 20 points along the curve for visualization **Curve Behavior:** - L = 0: Straight diagonal line (perfect conformance) - L > 0: Curved line below diagonal (flow imbalance) - Higher L: More curvature, greater flow imbalance **Applications:** - **Reservoir Simulation:** Generate layer properties for simulation models - **Waterflood Prediction:** Predict sweep efficiency from heterogeneity - **Sweep Efficiency Estimation:** Estimate vertical sweep from Lorenz - **Sensitivity Analysis:** Test impact of heterogeneity on performance - **Conceptual Models:** Create idealized reservoir models for studies - **Visualization:** Plot Lorenz curve to visualize heterogeneity **Returns:** Dictionary with: - **cumulative_flow_capacity** (list): Y-axis values (cumulative flow fractions) - **cumulative_storage_capacity** (list): X-axis values (cumulative kh fractions) - **lorenz_coefficient** (float): Target Lorenz coefficient - **method** (str): "Generated Lorenz curve" - **note** (str): Visualization guidance - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Lorenz coefficient outside valid range (must be 0-1) - Confusing cumulative fractions with incremental fractions - Not understanding that curve represents idealized distribution - Using curve for non-log-normal distributions (may be inaccurate) **Example Usage:** ```python { "value": 0.5 } ``` Result: Lorenz curve with 20 points showing cumulative flow vs cumulative capacity. Curve is below diagonal, indicating flow imbalance (high-k layers produce more than their capacity fraction). **Note:** This generates an idealized Lorenz curve. For actual reservoirs, use `lorenz_from_flow_fractions` with measured production data. The curve assumes log-normal permeability distribution. Plot cumulative flow vs cumulative storage to visualize heterogeneity. """ # lorenz_2_flow_frac returns a scalar flow fraction, not arrays # We need to generate a full curve, so we'll call it multiple times phih_values = np.linspace(0, 1, 20) flow_values = [layer.lorenz_2_flow_frac(lorenz=request.value, phih_frac=phi) for phi in phih_values] # Convert to lists flow_capacity = flow_values storage_capacity = phih_values.tolist() return { "cumulative_flow_capacity": flow_capacity, "cumulative_storage_capacity": storage_capacity, "lorenz_coefficient": request.value, "method": "Generated Lorenz curve", "note": "Plot cumulative flow vs storage to visualize heterogeneity", "inputs": request.model_dump(), }
- Pydantic model defining the input schema for the tool: a single 'value' field representing the Lorenz coefficient (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 the layer tools module, which includes the @mcp.tool() decorator application for flow_fractions_from_lorenz inside register_layer_tools(mcp). This is called during server initialization.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)