gas_compressibility
Calculate gas compressibility coefficient for material balance calculations and pressure transient analysis using reservoir temperature, pressure, and gas composition.
Instructions
Calculate gas compressibility (Cg).
CRITICAL GAS PVT PROPERTY - Computes gas compressibility coefficient, which measures how much gas volume changes with pressure. Essential for material balance calculations, pressure transient analysis, and reserve estimation. Gas compressibility is much higher than oil compressibility (typically 100-1000 × 10⁻⁶ 1/psi vs 5-50 × 10⁻⁶).
Parameters:
sg (float, required): Gas specific gravity (air=1.0). Valid: 0.55-3.0. Typical: 0.6-1.2. Example: 0.7.
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.
co2 (float, optional, default=0.0): CO2 mole fraction (0-1). Typical: 0-0.20. Example: 0.05.
n2 (float, optional, default=0.0): N2 mole fraction (0-1). Typical: 0-0.10. Example: 0.01.
zmethod (str, optional, default="DAK"): Z-factor method for compressibility. Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
Compressibility Behavior:
Decreases with increasing pressure (gas becomes less compressible)
Typical range: 50-500 × 10⁻⁶ 1/psi at reservoir conditions
At low pressure: Cg ≈ 1/P (ideal gas behavior)
At high pressure: Cg decreases significantly
Formula: Cg = (1/Z) × (∂Z/∂P) - (1/P)
Where Z-factor and its pressure derivative are calculated using specified method.
Returns: Dictionary with:
value (float or list): Compressibility in 1/psi (matches input p shape)
method (str): Z-factor method used
units (str): "1/psi"
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
Confusing gas compressibility (high, 100-1000 × 10⁻⁶) with oil compressibility (low, 5-50 × 10⁻⁶)
Using ideal gas approximation (Cg = 1/P) instead of real gas
Example Usage:
Result: Cg decreases from ~1000 × 10⁻⁶ 1/psi at 1000 psia to ~250 × 10⁻⁶ 1/psi at 4000 psia.
Note: Gas compressibility is critical for material balance calculations. Always use reservoir conditions. Account for all non-hydrocarbon components. Cg values are small (micro-1/psi), so results are typically in scientific notation.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Input Schema (JSON Schema)
Implementation Reference
- The handler function decorated with @mcp.tool() that executes the gas_compressibility tool logic using pyrestoolbox.gas.gas_cg.@mcp.tool() def gas_compressibility(request: GasCompressibilityRequest) -> dict: """Calculate gas compressibility (Cg). **CRITICAL GAS PVT PROPERTY** - Computes gas compressibility coefficient, which measures how much gas volume changes with pressure. Essential for material balance calculations, pressure transient analysis, and reserve estimation. Gas compressibility is much higher than oil compressibility (typically 100-1000 × 10⁻⁶ 1/psi vs 5-50 × 10⁻⁶). **Parameters:** - **sg** (float, required): Gas specific gravity (air=1.0). Valid: 0.55-3.0. Typical: 0.6-1.2. Example: 0.7. - **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. - **co2** (float, optional, default=0.0): CO2 mole fraction (0-1). Typical: 0-0.20. Example: 0.05. - **n2** (float, optional, default=0.0): N2 mole fraction (0-1). Typical: 0-0.10. Example: 0.01. - **zmethod** (str, optional, default="DAK"): Z-factor method for compressibility. Options: "DAK", "HY", "WYW", "BUR". DAK recommended. **Compressibility Behavior:** - Decreases with increasing pressure (gas becomes less compressible) - Typical range: 50-500 × 10⁻⁶ 1/psi at reservoir conditions - At low pressure: Cg ≈ 1/P (ideal gas behavior) - At high pressure: Cg decreases significantly **Formula:** Cg = (1/Z) × (∂Z/∂P) - (1/P) Where Z-factor and its pressure derivative are calculated using specified method. **Returns:** Dictionary with: - **value** (float or list): Compressibility in 1/psi (matches input p shape) - **method** (str): Z-factor method used - **units** (str): "1/psi" - **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 - Confusing gas compressibility (high, 100-1000 × 10⁻⁶) with oil compressibility (low, 5-50 × 10⁻⁶) - Using ideal gas approximation (Cg = 1/P) instead of real gas **Example Usage:** ```python { "sg": 0.7, "degf": 180.0, "p": [1000, 2000, 3000, 4000], "h2s": 0.0, "co2": 0.05, "n2": 0.01, "zmethod": "DAK" } ``` Result: Cg decreases from ~1000 × 10⁻⁶ 1/psi at 1000 psia to ~250 × 10⁻⁶ 1/psi at 4000 psia. **Note:** Gas compressibility is critical for material balance calculations. Always use reservoir conditions. Account for all non-hydrocarbon components. Cg values are small (micro-1/psi), so results are typically in scientific notation. """ method_enum = getattr(z_method, request.zmethod) cg = gas.gas_cg( 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(cg, np.ndarray): value = cg.tolist() else: value = float(cg) return { "value": value, "method": request.zmethod, "units": "1/psi", "inputs": request.model_dump(), }
- Pydantic BaseModel defining the input parameters and validation for the gas_compressibility tool.class GasCompressibilityRequest(BaseModel): """Request model for gas compressibility 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)" ) zmethod: Literal["DAK", "HY", "WYW", "BUR"] = Field( "DAK", description="Z-factor calculation method" ) @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-25 (registration)Registration of gas tools (including gas_compressibility) by calling register_gas_tools(mcp) in the main MCP server setup.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)
- src/pyrestoolbox_mcp/tools/gas_tools.py:26-30 (registration)The register_gas_tools function that defines and registers all gas tools, including gas_compressibility with @mcp.tool() decorator.def register_gas_tools(mcp: FastMCP) -> None: """Register all gas-related tools with the MCP server.""" @mcp.tool() def gas_z_factor(request: ZFactorRequest) -> dict: