pyResToolbox MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/pyrestoolbox_mcp/tools/simtools_tools.py:338-430 (handler)

  The @mcp.tool()-decorated handler function implementing rachford_rice_flash tool. Calls simtools.rr_solver to compute vapor fraction beta, liquid xi and vapor yi compositions from overall zis and K-values Kis.
  @mcp.tool() def rachford_rice_flash(request: RachfordRiceRequest) -> dict: """Solve Rachford-Rice equation for vapor-liquid equilibrium. **PHASE BEHAVIOR TOOL** - Calculates vapor fraction (beta) and phase compositions for two-phase flash at specified pressure and temperature. Essential for compositional analysis, separator design, and phase behavior calculations. **Parameters:** - **zis** (list, required): Overall mole fractions of components (0-1). Must sum to 1.0. Length must match Kis. Example: [0.5, 0.3, 0.2] for 3 components. - **Kis** (list, required): Equilibrium ratios (K-values) for components. Ki = yi/xi where yi = vapor mole fraction, xi = liquid mole fraction. Length must match zis. Example: [2.5, 1.8, 0.6]. K > 1 = light component. **Rachford-Rice Equation:** Σ[zi(Ki - 1) / (1 + β(Ki - 1))] = 0 Where: - zi = overall mole fraction of component i - Ki = equilibrium ratio (yi/xi) for component i - β = vapor mole fraction (0 to 1) **Phase Behavior:** - β = 0: All liquid (subcooled) - 0 < β < 1: Two-phase (vapor + liquid) - β = 1: All vapor (superheated) **K-Value Behavior:** - K > 1: Component prefers vapor phase (light components) - K = 1: Component equally distributed (critical component) - K < 1: Component prefers liquid phase (heavy components) - K-values depend on pressure, temperature, and composition **Solution Method:** Iterative Newton-Raphson method with bounds checking (0 ≤ β ≤ 1). Converges rapidly for well-posed problems. Typically converges in 3-10 iterations. **Applications:** - **Gas-Oil Separator Design:** Determine separator conditions for phase split - **Phase Envelope:** Calculate bubble/dew points and phase boundaries - **Compositional Simulation:** Flash calculations in compositional models - **EOS Flash:** Solve equation of state flash calculations - **Surface Facility Design:** Design separation trains and processing units - **Material Balance:** Phase split in material balance calculations **Returns:** Dictionary with: - **vapor_fraction** (float): Vapor mole fraction β (0-1) - **liquid_composition** (list): Liquid phase mole fractions xi - **vapor_composition** (list): Vapor phase mole fractions yi - **method** (str): "Rachford-Rice (Newton-Raphson)" - **note** (str): Interpretation guidance - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Mole fractions don't sum to 1.0 (must normalize) - K-values don't match components (length mismatch) - K-values at wrong P-T conditions (must match flash conditions) - Using weight fractions instead of mole fractions - Not accounting for non-hydrocarbon components - K-values from wrong correlation/EOS **Example Usage:** ```python { "zis": [0.5, 0.3, 0.2], "Kis": [2.5, 1.8, 0.6] } ``` Result: β ≈ 0.3-0.5 (two-phase), with light components enriched in vapor, heavy components enriched in liquid. **Note:** Rachford-Rice equation assumes ideal mixing. For real systems, K-values must account for non-ideality (activity coefficients, fugacity). K-values are typically obtained from EOS (Peng-Robinson, Soave-Redlich-Kwong) or correlations (Wilson, Standing). Always ensure K-values match flash conditions. """ # Solve Rachford-Rice iteration, xi, yi, beta, err = simtools.rr_solver( zi=request.zis, ki=request.Kis, ) return { "vapor_fraction": float(beta), "liquid_composition": [float(x) for x in xi], "vapor_composition": [float(y) for y in yi], "method": "Rachford-Rice (Newton-Raphson)", "inputs": request.model_dump(), "note": "Vapor fraction (beta) ranges from 0 (all liquid) to 1 (all vapor)", }
• src/pyrestoolbox_mcp/models/simtools_models.py:98-129 (schema)

  Pydantic input schema for rachford_rice_flash tool defining zis (overall mole fractions, sum~1.0) and Kis (equilibrium ratios), with validation for non-negativity and length >=2.
  class RachfordRiceRequest(BaseModel): """Request model for Rachford-Rice flash calculation.""" model_config = ConfigDict( json_schema_extra={ "example": { "zis": [0.5, 0.3, 0.2], "Kis": [1.5, 0.9, 0.3], } } ) zis: List[float] = Field(..., min_length=2, description="Overall mole fractions") Kis: List[float] = Field(..., min_length=2, description="K-values (yi/xi)") @field_validator("zis", "Kis") @classmethod def validate_composition(cls, v): """Validate composition arrays.""" if not all(val >= 0 for val in v): raise ValueError("All values must be non-negative") return v @field_validator("zis") @classmethod def validate_sum(cls, v): """Validate sum of mole fractions.""" total = sum(v) if not (0.99 <= total <= 1.01): raise ValueError(f"Mole fractions must sum to 1.0 (got {total})") return v
• src/pyrestoolbox_mcp/server.py:19-30 (registration)

  Main server file imports register_simtools_tools and invokes it on the FastMCP instance, which registers the rachford_rice_flash handler.
  from .tools.simtools_tools import register_simtools_tools from .tools.brine_tools import register_brine_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) register_library_tools(mcp)