gas_z_factor
Calculate gas compressibility factor (Z-factor) to correct ideal gas law for real gas behavior in reservoir engineering applications including material balance and flow calculations.
Instructions
Calculate gas compressibility factor (Z-factor).
CRITICAL GAS PVT PROPERTY - The Z-factor corrects the ideal gas law (PV=nRT) for real gas behavior. Z = 1.0 for ideal gas, Z < 1.0 for most real gases at reservoir conditions. Essential for all gas reservoir calculations including material balance, reserve estimation, and flow calculations.
Parameters:
sg (float, required): Gas specific gravity (air=1.0). Valid: 0.55-3.0. Typical: 0.6-1.2. Example: 0.7 for dry gas, 0.85 for associated gas.
degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000. Typical: 100-400°F. Example: 180.0.
p (float or list, required): Pressure(s) in psia. Must be > 0. Can be scalar or array. Example: 3500.0 or [1000, 2000, 3000, 4000].
h2s (float, optional, default=0.0): H2S mole fraction (0-1). Typical: 0-0.05. Example: 0.02 for 2% H2S. High H2S requires special handling.
co2 (float, optional, default=0.0): CO2 mole fraction (0-1). Typical: 0-0.20. Example: 0.05 for 5% CO2.
n2 (float, optional, default=0.0): N2 mole fraction (0-1). Typical: 0-0.10. Example: 0.01 for 1% N2.
method (str, optional, default="DAK"): Correlation method. Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
Z-Factor Behavior:
Low pressure: Z ≈ 1.0 (ideal gas behavior)
Medium pressure: Z < 1.0 (attractive forces dominate)
High pressure: Z > 1.0 (repulsive forces dominate)
Typical range: 0.7-1.2 for reservoir conditions
Method Selection:
DAK (Dranchuk & Abou-Kassem 1975): RECOMMENDED. Most accurate, widely validated. Use for: All applications, high accuracy requirements.
HY (Hall & Yarborough 1973): Classic method, fast. Use for: Quick estimates, compatibility with older methods.
WYW (Wang, Ye & Wu 2021): Newer correlation. Use for: Comparison studies, modern applications.
BUR (Burrows 1981): Alternative method. Use for: Specific regional correlations.
Non-Hydrocarbon Effects:
H2S and CO2 increase Z-factor (reduce compressibility)
N2 has minimal effect
For sour gas (H2S > 5%), use Wichert-Aziz correction (not included here)
Returns: Dictionary with:
value (float or list): Z-factor (dimensionless, matches input p shape)
method (str): Method used
units (str): "dimensionless"
inputs (dict): Echo of input parameters
Common Mistakes:
Using separator temperature instead of reservoir temperature
Pressure in barg/psig instead of psia (must be absolute)
Not accounting for non-hydrocarbon fractions (H2S, CO2, N2)
Using wrong gas gravity (must be separator gas gravity, not sales gas)
Temperature in Celsius instead of Fahrenheit
Example Usage:
Result: Z decreases from ~0.95 at 1000 psia to ~0.85 at 3000 psia, then increases to ~0.90 at 4000 psia (typical behavior).
Note: Z-factor is critical for accurate gas calculations. Always use DAK method unless specific compatibility requirements exist. Account for all non-hydrocarbon components for accurate results.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Input Schema (JSON Schema)
Implementation Reference
- The main handler function for the 'gas_z_factor' tool. It takes ZFactorRequest input, computes Z-factor using pyrestoolbox.gas.gas_z with specified method, handles array/scalar output, and returns formatted dict.@mcp.tool() def gas_z_factor(request: ZFactorRequest) -> dict: """Calculate gas compressibility factor (Z-factor). **CRITICAL GAS PVT PROPERTY** - The Z-factor corrects the ideal gas law (PV=nRT) for real gas behavior. Z = 1.0 for ideal gas, Z < 1.0 for most real gases at reservoir conditions. Essential for all gas reservoir calculations including material balance, reserve estimation, and flow calculations. **Parameters:** - **sg** (float, required): Gas specific gravity (air=1.0). Valid: 0.55-3.0. Typical: 0.6-1.2. Example: 0.7 for dry gas, 0.85 for associated gas. - **degf** (float, required): Reservoir temperature in °F. Valid: -460 to 1000. Typical: 100-400°F. Example: 180.0. - **p** (float or list, required): Pressure(s) in psia. Must be > 0. Can be scalar or array. Example: 3500.0 or [1000, 2000, 3000, 4000]. - **h2s** (float, optional, default=0.0): H2S mole fraction (0-1). Typical: 0-0.05. Example: 0.02 for 2% H2S. High H2S requires special handling. - **co2** (float, optional, default=0.0): CO2 mole fraction (0-1). Typical: 0-0.20. Example: 0.05 for 5% CO2. - **n2** (float, optional, default=0.0): N2 mole fraction (0-1). Typical: 0-0.10. Example: 0.01 for 1% N2. - **method** (str, optional, default="DAK"): Correlation method. Options: "DAK", "HY", "WYW", "BUR". DAK recommended. **Z-Factor Behavior:** - Low pressure: Z ≈ 1.0 (ideal gas behavior) - Medium pressure: Z < 1.0 (attractive forces dominate) - High pressure: Z > 1.0 (repulsive forces dominate) - Typical range: 0.7-1.2 for reservoir conditions **Method Selection:** - **DAK** (Dranchuk & Abou-Kassem 1975): **RECOMMENDED**. Most accurate, widely validated. Use for: All applications, high accuracy requirements. - **HY** (Hall & Yarborough 1973): Classic method, fast. Use for: Quick estimates, compatibility with older methods. - **WYW** (Wang, Ye & Wu 2021): Newer correlation. Use for: Comparison studies, modern applications. - **BUR** (Burrows 1981): Alternative method. Use for: Specific regional correlations. **Non-Hydrocarbon Effects:** - H2S and CO2 increase Z-factor (reduce compressibility) - N2 has minimal effect - For sour gas (H2S > 5%), use Wichert-Aziz correction (not included here) **Returns:** Dictionary with: - **value** (float or list): Z-factor (dimensionless, matches input p shape) - **method** (str): Method used - **units** (str): "dimensionless" - **inputs** (dict): Echo of input parameters **Common Mistakes:** - Using separator temperature instead of reservoir temperature - Pressure in barg/psig instead of psia (must be absolute) - Not accounting for non-hydrocarbon fractions (H2S, CO2, N2) - Using wrong gas gravity (must be separator gas gravity, not sales gas) - Temperature in Celsius instead of Fahrenheit **Example Usage:** ```python { "sg": 0.7, "degf": 180.0, "p": [1000, 2000, 3000, 4000], "h2s": 0.0, "co2": 0.05, "n2": 0.01, "method": "DAK" } ``` Result: Z decreases from ~0.95 at 1000 psia to ~0.85 at 3000 psia, then increases to ~0.90 at 4000 psia (typical behavior). **Note:** Z-factor is critical for accurate gas calculations. Always use DAK method unless specific compatibility requirements exist. Account for all non-hydrocarbon components for accurate results. """ method_enum = getattr(z_method, request.method) z = gas.gas_z( sg=request.sg, degf=request.degf, p=request.p, h2s=request.h2s, co2=request.co2, n2=request.n2, zmethod=method_enum, ) # Convert numpy array to list for JSON serialization if isinstance(z, np.ndarray): value = z.tolist() else: value = float(z) return { "value": value, "method": request.method, "units": "dimensionless", "inputs": request.model_dump(), }
- Pydantic BaseModel defining the input schema and validation for the gas_z_factor tool parameters including sg, degf, p, h2s, co2, n2, method with field validators.class ZFactorRequest(BaseModel): """Request model for gas Z-factor calculation.""" sg: float = Field( ..., ge=0.5, le=2.0, description="Gas specific gravity (air=1, dimensionless)" ) degf: float = Field( ..., gt=-460, lt=1000, description="Temperature (degrees Fahrenheit)" ) p: Union[float, List[float]] = Field( ..., description="Pressure (psia) - scalar or array" ) h2s: float = Field( 0.0, ge=0.0, le=1.0, description="H2S mole fraction (dimensionless)" ) co2: float = Field( 0.0, ge=0.0, le=1.0, description="CO2 mole fraction (dimensionless)" ) n2: float = Field( 0.0, ge=0.0, le=1.0, description="N2 mole fraction (dimensionless)" ) method: Literal["DAK", "HY", "WYW", "BUR"] = Field( "DAK", description="Calculation method (DAK recommended)" ) @field_validator("p") @classmethod def validate_pressure(cls, v): """Validate pressure values.""" if isinstance(v, list): if not all(p > 0 for p in v): raise ValueError("All pressure values must be positive") else: if v <= 0: raise ValueError("Pressure must be positive") return v
- src/pyrestoolbox_mcp/server.py:17-30 (registration)Imports register_gas_tools from gas_tools.py and calls it with the MCP instance to register all gas tools including gas_z_factor.from .tools.gas_tools import register_gas_tools from .tools.inflow_tools import register_inflow_tools 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)
- src/pyrestoolbox_mcp/tools/gas_tools.py:26-26 (registration)The register_gas_tools function defines and registers the gas_z_factor tool (and others) using @mcp.tool() decorator within the MCP instance scope.def register_gas_tools(mcp: FastMCP) -> None:
- Documentation listing gas_z_factor as one of the available Gas PVT Tools in the server overview resource.### Gas PVT Tools - gas_z_factor: Calculate gas Z-factor (compressibility factor)