| oil_bubble_point | Calculate oil bubble point pressure (Pb). CRITICAL PVT PROPERTY - The bubble point is the pressure at which gas first
begins to evolve from solution in oil. Essential for all oil reservoir calculations. Parameters: api (float, required): Oil API gravity in degrees. Valid range: 0-100.
Typical values: 20-50. Example: 35.0 for medium gravity crude. degf (float, required): Reservoir temperature in degrees Fahrenheit.
Valid range: -460 to 1000. Typical: 100-300°F. Example: 180.0. rsb (float, required): Solution gas-oil ratio at bubble point in scf/stb.
Must be ≥ 0. Typical: 100-3000 scf/stb. Example: 800.0. sg_g (float, optional, default=0.0): Gas specific gravity (air=1.0).
Valid range: 0-3. Typical: 0.6-1.2. Example: 0.75 for associated gas. method (str, optional, default="VALMC"): Correlation method.
Options: "STAN", "VALMC", "VELAR". VALMC recommended for wider applicability.
Method Selection: VALMC (Valko-McCain 2003): Recommended. Best for wide range of conditions.
Use for: Most applications, high GOR oils, wide temperature ranges. STAN (Standing 1947): Classic correlation. Use for: Standard conditions,
quick estimates, compatibility with older methods. VELAR (Velarde 1997): Alternative method. Use for: Specific regional
correlations, comparison studies.
Returns:
Dictionary with: value (float): Bubble point pressure in psia method (str): Method used units (str): "psia" inputs (dict): Echo of input parameters
Common Mistakes: Using separator temperature instead of reservoir temperature Confusing rsb (solution GOR at bubble point) with separator GOR Using gas gravity from wrong separator stage Temperature in Celsius instead of Fahrenheit
Example Usage: {
"api": 35.0,
"degf": 180.0,
"rsb": 800.0,
"sg_g": 0.75,
"method": "VALMC"
} Expected result: Pb ≈ 3000-4000 psia for typical oil. Note: If Pb > reservoir pressure, reservoir is undersaturated (no free gas).
If Pb < reservoir pressure, reservoir is saturated (gas cap present). |
| oil_solution_gor | Calculate solution gas-oil ratio (Rs) at specified pressure. CRITICAL PVT PROPERTY - Computes volume of gas dissolved in oil at given
pressure and temperature. Rs increases with pressure up to bubble point, then
remains constant (equal to rsb) above bubble point. Parameters: api (float, required): Oil API gravity in degrees. Valid: 0-100.
Example: 35.0. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. p (float or list, required): Pressure(s) in psia. Must be > 0.
Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000]. sg_g (float, optional, default=0.0): Separator gas specific gravity (air=1).
Valid: 0-3. Typical: 0.6-1.2. Example: 0.75. pb (float, optional, default=0.0): Bubble point pressure in psia.
If 0, will be calculated. Must be ≥ 0. Example: 3500.0. rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb.
If 0 and pb provided, will be calculated. Must be ≥ 0. Example: 800.0. method (str, optional, default="VELAR"): Correlation method.
Options: "VELAR", "STAN", "VALMC".
Pressure Behavior: p < pb: Rs calculated from correlation (increases with pressure) p ≥ pb: Rs = rsb (constant, no additional gas dissolves)
Method Selection: VELAR (Velarde 1997): Default, good accuracy. Use for most cases. STAN (Standing 1947): Classic, widely used. Use for compatibility. VALMC (Valko-McCain 2003): Alternative method.
Returns:
Dictionary with: value (float or list): Rs in scf/stb (matches input p shape) method (str): Method used units (str): "scf/stb" inputs (dict): Echo of input parameters
Common Mistakes: Using separator gas gravity instead of separator gas gravity (sg_g parameter) Not providing pb when p > pb (will calculate incorrectly) Pressure in barg/psig instead of psia (must be absolute) Confusing rsb (at bubble point) with separator GOR
Example Usage: {
"api": 35.0,
"degf": 180.0,
"p": [2000, 3000, 4000],
"sg_g": 0.75,
"pb": 3500.0,
"rsb": 800.0,
"method": "VELAR"
} Result: Rs increases from ~400 scf/stb at 2000 psia to 800 scf/stb at 3500 psia,
then remains 800 scf/stb at 4000 psia (above bubble point). Note: Always provide pb and rsb when available for accurate results.
If unknown, set pb=0 and rsb=0 to auto-calculate, but accuracy may be reduced. |
| oil_formation_volume_factor | Calculate oil formation volume factor (Bo). CRITICAL PVT PROPERTY - Computes ratio of oil volume at reservoir conditions
to volume at standard conditions. Bo > 1.0 because oil expands due to dissolved gas
and thermal expansion. Essential for material balance, reserve calculations, and
production forecasting. Parameters: api (float, required): Oil API gravity in degrees. Valid: 0-100. Example: 35.0. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. p (float or list, required): Pressure(s) in psia. Must be > 0.
Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000]. sg_g (float, optional, default=0.0): Gas specific gravity (air=1).
Valid: 0-3. Typical: 0.6-1.2. Example: 0.75. pb (float, optional, default=0.0): Bubble point pressure in psia.
Required for accurate calculation. Example: 3500.0. rs (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb.
If 0, will be calculated from p. Must match p shape. Example: 600.0 or [400, 600, 800]. rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb.
Required if pb provided. Example: 800.0. method (str, optional, default="MCAIN"): Correlation method.
Options: "MCAIN", "STAN". MCAIN recommended.
Pressure Behavior: p < pb: Bo increases with pressure (more gas dissolves) p = pb: Bo reaches maximum (Bob, typically 1.2-2.0 rb/stb) p > pb: Bo decreases with pressure (oil compressibility dominates)
Method Selection: MCAIN (McCain et al. 1988): Recommended. More accurate, wider range. STAN (Standing 1947): Classic method. Use for compatibility.
Returns:
Dictionary with: value (float or list): Bo in rb/stb (matches input p shape) method (str): Method used units (str): "rb/stb" inputs (dict): Echo of input parameters
Common Mistakes: Not providing rs when p < pb (will calculate incorrectly) Using separator GOR instead of solution GOR at reservoir pressure Pressure in barg/psig instead of psia Confusing Bo (reservoir volume) with Bg (gas FVF)
Example Usage: {
"api": 35.0,
"degf": 180.0,
"p": [2000, 3000, 4000],
"sg_g": 0.75,
"pb": 3500.0,
"rs": [400, 600, 800],
"rsb": 800.0,
"method": "MCAIN"
} Result: Bo increases from ~1.15 rb/stb at 2000 psia to ~1.35 rb/stb at 3500 psia,
then decreases to ~1.33 rb/stb at 4000 psia (above bubble point). Note: Always provide rs for pressures below bubble point. If rs=0, tool will
calculate it, but providing it explicitly improves accuracy. |
| oil_viscosity | Calculate oil viscosity (μo). CRITICAL PVT PROPERTY - Computes oil viscosity at reservoir conditions.
Viscosity affects flow rates, pressure drops, and recovery efficiency.
Uses Beggs-Robinson (1975) correlation, industry standard for oil viscosity. Parameters: api (float, required): Oil API gravity in degrees. Valid: 0-100.
Example: 35.0. Higher API = lighter oil = lower viscosity. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. Higher temperature = lower viscosity. p (float or list, required): Pressure(s) in psia. Must be > 0.
Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000]. pb (float, optional, default=0.0): Bubble point pressure in psia.
Required for accurate calculation. Example: 3500.0. rs (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb.
If 0, will be calculated. Must match p shape. Example: 600.0. rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb.
Required if pb provided. Example: 800.0. method (str, optional, default="BR"): Correlation method. Only "BR" available.
Viscosity Behavior: p < pb: Viscosity decreases with pressure (more gas dissolves, oil thins) p = pb: Viscosity reaches minimum (μob, typically 0.5-5 cP) p > pb: Viscosity increases with pressure (oil compression)
Typical Ranges: Light oils (API > 35): 0.5-2 cP at bubble point Medium oils (API 25-35): 1-10 cP at bubble point Heavy oils (API < 25): 10-1000+ cP at bubble point
Returns:
Dictionary with: value (float or list): Viscosity in cP (matches input p shape) method (str): "BR" (Beggs-Robinson) units (str): "cP" inputs (dict): Echo of input parameters
Common Mistakes: Not providing rs when p < pb (will calculate incorrectly) Using dead oil viscosity instead of live oil viscosity Temperature in Celsius instead of Fahrenheit Pressure in barg/psig instead of psia
Example Usage: {
"api": 35.0,
"degf": 180.0,
"p": [2000, 3000, 4000],
"pb": 3500.0,
"rs": [400, 600, 800],
"rsb": 800.0,
"method": "BR"
} Result: Viscosity decreases from ~1.2 cP at 2000 psia to ~0.8 cP at 3500 psia,
then increases to ~0.85 cP at 4000 psia (above bubble point). Note: Viscosity is highly sensitive to temperature and dissolved gas content.
Always use reservoir temperature, not separator temperature. |
| oil_density | Calculate oil density (ρo) at reservoir conditions. CRITICAL PVT PROPERTY - Computes oil density from PVT properties using
mass balance approach. Essential for gradient calculations, well pressure analysis,
and material balance calculations. Parameters: p (float or list, required): Pressure(s) in psia. Must be > 0.
Can be scalar or array. Example: 3000.0. api (float, required): Oil API gravity in degrees. Valid: 0-100.
Example: 35.0. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. rs (float or list, required): Solution GOR at pressure p in scf/stb.
Must match p shape. Example: 600.0 or [400, 600, 800]. sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3.
Typical: 0.6-1.2. Example: 0.75. bo (float or list, required): Oil formation volume factor at pressure p in rb/stb.
Must match p shape. Calculate using oil_formation_volume_factor tool first.
Example: 1.25 or [1.15, 1.25, 1.30].
Calculation Method:
Density = (Stock tank oil mass + Dissolved gas mass) / Reservoir volume
ρo = (sg_o × 62.372 + 0.01357 × Rs × sg_g) / Bo Where: sg_o = oil specific gravity (calculated from API) 62.372 = water density at standard conditions (lb/cuft) 0.01357 = gas density conversion factor
Typical Ranges: Light oils: 40-50 lb/cuft Medium oils: 50-55 lb/cuft Heavy oils: 55-65 lb/cuft
Returns:
Dictionary with: Common Mistakes: Using stock tank density instead of reservoir density Not providing matching rs and bo arrays Using wrong bo value (must be at same pressure as p) Confusing density (mass/volume) with specific gravity (dimensionless)
Example Usage: {
"p": 3000.0,
"api": 35.0,
"degf": 180.0,
"rs": 600.0,
"sg_g": 0.75,
"bo": 1.25
} Result: Density ≈ 48-52 lb/cuft for typical medium gravity oil. Note: Always calculate Bo first using oil_formation_volume_factor tool,
then use matching rs and bo values for accurate density calculation. |
| oil_compressibility | Calculate oil compressibility (Co). CRITICAL PVT PROPERTY - Computes oil compressibility coefficient, which measures
how much oil volume changes with pressure. Essential for material balance calculations,
pressure transient analysis, and reserve estimation. Co is typically 5-50 × 10⁻⁶ 1/psi. Parameters: p (float or list, required): Pressure(s) in psia. Must be > 0.
Can be scalar or array. Example: 3000.0 or [2000, 3000, 4000]. api (float, required): Oil API gravity in degrees. Valid: 0-100.
Example: 35.0. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. pb (float, required): Bubble point pressure in psia. Must be ≥ 0.
Example: 3500.0. sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3.
Typical: 0.6-1.2. Example: 0.75. rs (float or list, optional, default=0.0): Solution GOR at pressure p in scf/stb.
If 0, will be calculated. Must match p shape. Example: 600.0. rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb.
Required if pb provided. Example: 800.0.
Compressibility Behavior: p < pb: Co is relatively constant (oil + dissolved gas compressibility) p = pb: Co increases sharply (gas evolution begins) p > pb: Co decreases with pressure (gas compressibility dominates)
Typical Ranges: Undersaturated oil: 5-20 × 10⁻⁶ 1/psi At bubble point: 20-50 × 10⁻⁶ 1/psi Above bubble point: 10-30 × 10⁻⁶ 1/psi
Returns:
Dictionary with: Common Mistakes: Not providing pb (required for accurate calculation) Using wrong pressure (must be reservoir pressure, not separator) Confusing oil compressibility with gas compressibility Not accounting for dissolved gas effects
Example Usage: {
"p": [2000, 3000, 4000],
"api": 35.0,
"degf": 180.0,
"pb": 3500.0,
"sg_g": 0.75,
"rs": [400, 600, 800],
"rsb": 800.0
} Result: Co ≈ 10-15 × 10⁻⁶ 1/psi below bubble point, increases near pb. Note: Compressibility is critical for material balance calculations.
Always provide pb for accurate results. Co values are small (micro-1/psi),
so results are typically in scientific notation. |
| oil_api_from_sg | Convert oil specific gravity to API gravity. UNIT CONVERSION TOOL - Converts oil specific gravity (dimensionless, water=1.0)
to API gravity (degrees). API gravity is an inverse measure of density - higher API
means lighter oil. Essential for standardizing oil property reporting. Parameters: sg (float or list, required): Oil specific gravity (water=1.0).
Valid range: 0.1-1.5. Typical: 0.8-1.0. Example: 0.85 or [0.80, 0.85, 0.90].
Can be scalar or array.
Conversion Formula:
API = (141.5 / SG) - 131.5 API Gravity Ranges: Heavy oil: API < 22° (SG > 0.922) Medium oil: API 22-35° (SG 0.922-0.850) Light oil: API > 35° (SG < 0.850) Water: API = 10° (SG = 1.0)
Returns:
Dictionary with: value (float or list): API gravity in degrees (matches input sg shape) method (str): "Standard conversion" units (str): "degrees API" inputs (dict): Echo of input parameters
Common Mistakes: Using gas specific gravity instead of oil specific gravity Confusing API gravity with specific gravity (inverse relationship) Using density (lb/cuft) instead of specific gravity Not understanding that higher API = lighter oil
Example Usage: Result: API = (141.5 / 0.85) - 131.5 ≈ 35.0° (medium gravity oil) Note: API gravity is the industry standard for oil classification.
Use this conversion when you have specific gravity but need API gravity
for correlations or reporting. |
| oil_sg_from_api | Convert API gravity to oil specific gravity. UNIT CONVERSION TOOL - Converts API gravity (degrees) to specific gravity
(dimensionless, water=1.0). Specific gravity is the ratio of oil density to water
density at standard conditions. Essential for calculations requiring specific gravity. Parameters: api (float or list, required): Oil API gravity in degrees.
Valid range: 0-100. Typical: 20-50. Example: 35.0 or [30, 35, 40].
Can be scalar or array.
Conversion Formula:
SG = 141.5 / (API + 131.5) Specific Gravity Ranges: Heavy oil: SG > 0.922 (API < 22°) Medium oil: SG 0.850-0.922 (API 22-35°) Light oil: SG < 0.850 (API > 35°) Water: SG = 1.0 (API = 10°)
Returns:
Dictionary with: value (float or list): Specific gravity (dimensionless, matches input api shape) method (str): "Standard conversion" units (str): "dimensionless (water=1)" inputs (dict): Echo of input parameters
Common Mistakes: Using gas API gravity instead of oil API gravity Confusing API gravity with specific gravity (inverse relationship) Not understanding that lower SG = lighter oil (higher API) Using wrong conversion formula
Example Usage: Result: SG = 141.5 / (35.0 + 131.5) ≈ 0.850 (medium gravity oil) Note: Most PVT correlations use API gravity directly, but some require
specific gravity. Use this conversion when needed. Remember: API and SG are
inversely related - higher API means lower SG (lighter oil). |
| generate_black_oil_table | Generate comprehensive black oil PVT table. COMPREHENSIVE PVT TABLE GENERATOR - Creates complete black oil PVT table with
all properties (Rs, Bo, μo, ρo, Co) at pressures from 14.7 psia to specified maximum.
This is the most comprehensive PVT tool, generating complete tables for reservoir
simulation input or analysis. Optionally exports ECLIPSE-compatible keywords. Parameters: pi (float, required): Initial reservoir pressure in psia. Must be > 0.
Example: 4000.0. Table starts from 14.7 psia and goes up to pmax. api (float, required): Oil API gravity in degrees. Valid: 0-100.
Example: 38.0. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 175.0. sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3.
Typical: 0.6-1.2. Example: 0.68. pmax (float, optional, default=0.0): Maximum pressure for table in psia.
If 0, auto-calculates as pi × 1.5. Must be > pi. Example: 5000.0. pb (float, optional, default=0.0): Bubble point pressure in psia.
If 0, will be calculated. Example: 3900.0. rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb.
If 0, will be calculated. Example: 2300.0. nrows (int, optional, default=50): Number of table rows. Valid: 1-200.
More rows = finer resolution. Typical: 20-100. Example: 50. export (bool, optional, default=False): Export ECLIPSE-compatible files.
If True, creates PVTO.INC, PVDO.INC, DENSITY.INC files. Example: False. pb_method (str, optional, default="VALMC"): Bubble point method.
Options: "STAN", "VALMC", "VELAR". VALMC recommended. rs_method (str, optional, default="VELAR"): Solution GOR method.
Options: "VELAR", "STAN", "VALMC". VELAR recommended. bo_method (str, optional, default="MCAIN"): Oil FVF method.
Options: "MCAIN", "STAN". MCAIN recommended. uo_method (str, optional, default="BR"): Oil viscosity method.
Only "BR" available.
Generated Properties: Rs: Solution gas-oil ratio (scf/stb) - increases with pressure up to pb Bo: Formation volume factor (rb/stb) - peaks at bubble point μo: Oil viscosity (cP) - minimum at bubble point ρo: Oil density (lb/cuft) - calculated from mass balance Co: Oil compressibility (1/psi) - increases near bubble point
Table Structure:
Pressure values are logarithmically spaced from 14.7 psia to pmax, with
finer spacing near bubble point for accuracy. ECLIPSE Export:
When export=True, generates: PVTO.INC: Pressure-dependent oil properties (for undersaturated oil) PVDO.INC: Dead oil properties (for heavy oils) DENSITY.INC: Oil density table
Returns:
Dictionary with: table (list of dicts): PVT table data, each dict contains pressure and all properties summary (dict): Key values (bubble point, rsb, Bob, μob, etc.) columns (list): Column names in table methods (dict): Methods used for each property export_files (dict, optional): File names if export=True inputs (dict): Echo of input parameters
Common Mistakes: Setting pmax too low (should be > pi for complete table) Not providing pb and rsb when known (reduces accuracy) Using wrong correlation methods (use recommended defaults) Too few rows (nrows < 20) causing poor resolution Not understanding table format for simulation input
Example Usage: {
"pi": 4000.0,
"api": 38.0,
"degf": 175.0,
"sg_g": 0.68,
"pmax": 5000.0,
"pb": 3900.0,
"rsb": 2300.0,
"nrows": 50,
"export": False,
"pb_method": "VALMC",
"rs_method": "VELAR",
"bo_method": "MCAIN",
"uo_method": "BR"
} Result: Complete PVT table with 50 rows covering 14.7-5000 psia with all properties. Note: This is the most comprehensive PVT tool. Use for complete reservoir
analysis or simulation input preparation. Always provide pb and rsb when available
for best accuracy. For simulation, set export=True to generate ECLIPSE keywords. |
| oil_rs_at_bubble_point | Calculate solution GOR at bubble point using Standing correlation. Computes Rs specifically at the bubble point pressure based on
reservoir fluid properties. Uses Standing (1947) correlation. This is useful when you know the bubble point pressure and need
to calculate the corresponding solution GOR. Returns Rs in scf/stb. Args:
request: Bubble point parameters (API, temperature, bubble point, gas gravity) Returns:
Dictionary with Rs at bubble point, method, units, and inputs |
| evolved_gas_sg | Calculate evolved gas specific gravity. Computes the specific gravity of gas evolved from oil as pressure
decreases below bubble point. This is important for: The evolved gas composition changes with pressure, and this function
accounts for that variation. Returns dimensionless specific gravity (air = 1.0). Args:
request: Evolved gas parameters including oil properties, pressure(s),
and separator conditions Returns:
Dictionary with evolved gas SG value(s), units, and inputs |
| stock_tank_gas_sg | Calculate stock tank gas specific gravity. Computes the specific gravity of gas liberated at stock tank conditions.
This is the gas that comes out of solution when oil reaches atmospheric
pressure and temperature. Stock tank gas properties are needed for: Returns dimensionless specific gravity (air = 1.0). Args:
request: Stock tank gas parameters including oil properties and
separator conditions Returns:
Dictionary with stock tank gas SG value(s), units, and inputs |
| oil_sg_from_jacoby | Calculate oil specific gravity from molecular weight and Jacoby aromaticity. HYDROCARBON CHARACTERIZATION TOOL - Estimates specific gravity
for undefined petroleum fractions using molecular weight and aromaticity. Jacoby Aromaticity Factor (JA): Applications: Plus fraction (C7+) characterization Undefined heavy end lumping EOS fluid modeling Pseudo-component generation
Returns specific gravity (dimensionless, water=1). Args:
request: Molecular weight and Jacoby aromaticity factor Returns:
Dictionary with specific gravity, method, and inputs |
| oil_twu_critical_properties | Calculate critical properties using Twu (1984) correlation. CRITICAL PROPERTIES ESTIMATION - Most widely used method for
estimating Tc, Pc, Vc for petroleum fractions and plus fractions. Twu Method: More accurate than older correlations (Riazi-Daubert, Kesler-Lee) Uses molecular weight and specific gravity Optional boiling point for improved accuracy Damping factor for heavy ends
Returns: Tc: Critical temperature (°R) Pc: Critical pressure (psia) Vc: Critical volume (cuft/lbmol) Also returns: SG, Tb (if not provided)
Critical for: Args:
request: Molecular weight, specific gravity, optional boiling point, damping Returns:
Dictionary with all critical properties |
| weighted_average_gas_sg | Calculate weighted average gas specific gravity from separator stages. SURFACE FACILITIES CALCULATION - Combines gas gravities from
separator and stock tank weighted by GORs. Use Cases: Formula:
sg_avg = (sg_sp * rsp + sg_st * rst) / (rsp + rst) Returns weighted average gas SG (dimensionless, air=1). Args:
request: Separator and stock tank gas properties Returns:
Dictionary with weighted average SG and breakdown |
| stock_tank_incremental_gor | Calculate incremental GOR from separator to stock tank. SEPARATOR DESIGN TOOL - Estimates gas evolved between
separator and stock tank conditions. Physics:
As oil flows from separator (higher P, T) to stock tank (14.7 psia, ~60°F),
additional gas comes out of solution. Applications: Returns stock tank incremental GOR in scf/stb. Args:
request: Separator pressure, temperature, and oil API Returns:
Dictionary with incremental GOR and guidance |
| validate_gas_gravities | Validate and impute missing gas gravities. DATA VALIDATION TOOL - Checks consistency of gas gravities
and calculates missing values when one is unknown. Logic: If sg_g provided: Calculate sg_sp from sg_g If sg_sp provided: Calculate sg_g from sg_sp If both provided: Validate consistency
Use Cases: QC PVT data before analysis Fill gaps in incomplete data Validate separator gas measurements
Returns tuple of (sg_g, sg_sp) with calculated/validated values. Args:
request: Available gas gravities and GORs Returns:
Dictionary with validated/calculated gas gravities |
| gas_z_factor | 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: {
"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. |
| gas_critical_properties | Calculate gas pseudo-critical properties (Tc and Pc). CRITICAL GAS PROPERTY CALCULATION - Computes pseudo-critical temperature and
pressure for real gas mixtures. Required for Z-factor calculations and all gas
property correlations. Pseudo-critical properties are weighted averages of pure
component critical properties, adjusted for non-hydrocarbon components. 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. h2s (float, optional, default=0.0): H2S mole fraction (0-1).
Typical: 0-0.05. Example: 0.02 for 2% H2S. High H2S significantly affects Tc/Pc. 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="PMC"): Correlation method.
Options: "PMC", "SUT", "BUR". PMC recommended.
Pseudo-Critical Properties: Tc (Pseudo-critical Temperature): Temperature above which gas cannot be
liquefied regardless of pressure. Typical: 300-500°R for natural gas. Pc (Pseudo-critical Pressure): Pressure at critical temperature.
Typical: 600-800 psia for natural gas.
Method Selection: PMC (Piper, McCain & Corredor 1993): RECOMMENDED. Most accurate for
wide range of gas compositions. Accounts for non-hydrocarbon effects. SUT (Sutton 1985): Classic method. Use for compatibility with older methods. BUR (Burrows 1981): Alternative method. Use for specific applications.
Non-Hydrocarbon Effects: H2S: Increases both Tc and Pc significantly CO2: Increases Tc, decreases Pc slightly N2: Increases Pc, decreases Tc slightly Always account for non-hydrocarbons for accurate Z-factor calculations
Returns:
Dictionary with: value (dict): Contains "tc" (degR) and "pc" (psia) method (str): Method used units (dict): {"tc": "degR", "pc": "psia"} inputs (dict): Echo of input parameters
Common Mistakes: Not accounting for non-hydrocarbon fractions (H2S, CO2, N2) Using wrong gas gravity (must be separator gas, not sales gas) Confusing pseudo-critical with true critical properties Using critical properties for pure components instead of mixtures
Example Usage: {
"sg": 0.7,
"h2s": 0.0,
"co2": 0.05,
"n2": 0.01,
"method": "PMC"
} Result: Tc ≈ 380-420°R, Pc ≈ 650-750 psia for typical natural gas. Note: Critical properties are used internally by gas_z_factor and other
gas property tools. Always use PMC method unless specific compatibility required.
Account for all non-hydrocarbon components - even small amounts affect results. |
| gas_formation_volume_factor | Calculate gas formation volume factor (Bg). CRITICAL GAS PVT PROPERTY - Computes ratio of gas volume at reservoir conditions
to volume at standard conditions. Bg << 1.0 because gas compresses significantly
at reservoir pressure. Essential for material balance, reserve calculations, and
production forecasting. 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 Bg calculation.
Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
Bg Behavior: Bg decreases with increasing pressure (gas compresses) Bg increases with increasing temperature (gas expands) Typical range: 0.001-0.01 rcf/scf at reservoir conditions At standard conditions (14.7 psia, 60°F): Bg = 1.0 rcf/scf
Formula:
Bg = (Z × T × Psc) / (P × Tsc) = 0.02827 × Z × T / P (field units) Where: Z = gas compressibility factor (from gas_z_factor tool) T = reservoir temperature (°R) P = reservoir pressure (psia) Psc = 14.7 psia, Tsc = 520°R (standard conditions)
Returns:
Dictionary with: value (float or list): Bg in rcf/scf (matches input p shape) method (str): Z-factor method used units (str): "rcf/scf" 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 Bg (gas FVF) with Bo (oil FVF) Temperature in Celsius instead of Fahrenheit
Example Usage: {
"sg": 0.7,
"degf": 180.0,
"p": [1000, 2000, 3000, 4000],
"h2s": 0.0,
"co2": 0.05,
"n2": 0.01,
"zmethod": "DAK"
} Result: Bg decreases from ~0.005 rcf/scf at 1000 psia to ~0.002 rcf/scf at 4000 psia. Note: Bg is inversely proportional to pressure. Always use reservoir conditions,
not separator conditions. Account for all non-hydrocarbon components for accuracy. |
| gas_viscosity | Calculate gas viscosity (μg). CRITICAL GAS PVT PROPERTY - Computes gas viscosity at reservoir conditions
using Lee, Gonzalez & Eakin (1966) correlation, industry standard for natural gas.
Viscosity affects flow rates, pressure drops, and well performance. Gas viscosity
increases with pressure and temperature, opposite to liquid behavior. 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 viscosity calculation.
Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
Viscosity Behavior: Increases with pressure (gas molecules closer together) Increases with temperature (molecular motion increases) Typical range: 0.01-0.05 cP at reservoir conditions At standard conditions: ~0.01 cP
Lee-Gonzalez-Eakin Correlation:
Uses Z-factor internally to account for real gas behavior. More accurate than
ideal gas assumptions, especially at high pressures. Returns:
Dictionary with: value (float or list): Viscosity in cP (matches input p shape) method (str): "Lee-Gonzalez-Eakin" units (str): "cP" 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 viscosity (increases with P) with oil viscosity (decreases with P) Temperature in Celsius instead of Fahrenheit
Example Usage: {
"sg": 0.7,
"degf": 180.0,
"p": [1000, 2000, 3000, 4000],
"h2s": 0.0,
"co2": 0.05,
"n2": 0.01,
"zmethod": "DAK"
} Result: Viscosity increases from ~0.012 cP at 1000 psia to ~0.025 cP at 4000 psia. Note: Gas viscosity is much lower than oil viscosity (typically 0.01-0.05 cP
vs 0.5-10 cP). Always use reservoir conditions, not separator conditions.
Account for all non-hydrocarbon components for accuracy. |
| gas_density | Calculate gas density (ρg) at reservoir conditions. CRITICAL GAS PVT PROPERTY - Computes gas density from real gas equation of state.
Essential for gradient calculations, well pressure analysis, and material balance.
Gas density increases significantly with pressure due to compressibility. 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 density calculation.
Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
Density Formula:
ρg = (P × MW) / (Z × R × T) Where: P = pressure (psia) MW = molecular weight = sg × 28.97 lb/lbmol Z = gas compressibility factor R = gas constant = 10.732 psia·ft³/(lbmol·°R) T = temperature (°R = °F + 460)
Density Behavior: Increases with pressure (gas compresses) Decreases with temperature (gas expands) Typical range: 5-20 lb/cuft at reservoir conditions At standard conditions: ~0.05-0.1 lb/cuft
Returns:
Dictionary with: value (float or list): Density in lb/cuft (matches input p shape) method (str): Z-factor method used units (str): "lb/cuft" 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 Using ideal gas law (Z=1) instead of real gas (Z<1) Temperature in Celsius instead of Fahrenheit
Example Usage: {
"sg": 0.7,
"degf": 180.0,
"p": [1000, 2000, 3000, 4000],
"h2s": 0.0,
"co2": 0.05,
"n2": 0.01,
"zmethod": "DAK"
} Result: Density increases from ~8 lb/cuft at 1000 psia to ~18 lb/cuft at 4000 psia. Note: Gas density is much lower than oil density (typically 5-20 lb/cuft
vs 40-60 lb/cuft). Always use reservoir conditions. Account for all non-hydrocarbon
components - they significantly affect molecular weight and density. |
| gas_compressibility | 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: {
"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. |
| gas_pseudopressure | Calculate gas pseudopressure difference (m(p)). CRITICAL GAS ANALYSIS TOOL - Computes pseudopressure difference, a pressure
transformation that linearizes the gas diffusivity equation. This makes gas flow
analysis mathematically similar to liquid flow, enabling use of liquid flow solutions
for gas systems. Essential for accurate gas well performance analysis. 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. p1 (float, required): Initial pressure in psia. Must be > 0.
Typically reservoir pressure. Example: 1000.0. p2 (float, required): Final pressure in psia. Must be > 0.
Typically sandface pressure. Example: 3500.0. h2s (float, optional, default=0.0): H2S mole fraction (0-1).
Typical: 0-0.05. Example: 0.0. co2 (float, optional, default=0.0): CO2 mole fraction (0-1).
Typical: 0-0.20. Example: 0.0. n2 (float, optional, default=0.0): N2 mole fraction (0-1).
Typical: 0-0.10. Example: 0.0. zmethod (str, optional, default="DAK"): Z-factor method for integration.
Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
Pseudopressure Formula:
m(p) = 2∫(p/(μZ))dp from p1 to p2 Where: Why Pseudopressure:
Gas properties (Z, μ) vary significantly with pressure, making gas flow non-linear.
Pseudopressure transformation accounts for these variations, enabling: Use of liquid flow solutions for gas Linear pressure analysis Accurate well test interpretation Material balance calculations
Applications: Gas Well Testing: Pressure transient analysis, rate transient analysis Material Balance: P/Z vs cumulative production plots Reservoir Simulation: Input for gas flow calculations IPR Curves: Inflow performance relationship generation
Returns:
Dictionary with: value (float): Pseudopressure difference in psia²/cP method (str): Integration method with Z-factor method used units (str): "psia²/cP" 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 pseudopressure with actual pressure Using wrong pressure order (p1 should be lower than p2 typically) Temperature in Celsius instead of Fahrenheit
Example Usage: {
"sg": 0.7,
"degf": 180.0,
"p1": 1000.0,
"p2": 3500.0,
"h2s": 0.0,
"co2": 0.0,
"n2": 0.0,
"zmethod": "DAK"
} Result: Pseudopressure difference ≈ 1-5 × 10⁶ psia²/cP (typical range). Note: Pseudopressure is essential for accurate gas flow calculations.
Always use reservoir conditions. Account for all non-hydrocarbon components.
The integration is performed numerically, so results are approximate but highly accurate. |
| gas_pressure_from_pz | Calculate pressure from P/Z value. MATERIAL BALANCE TOOL - Solves for pressure given a P/Z (pressure/Z-factor) value.
Essential for gas material balance analysis where P/Z vs cumulative production is plotted.
Uses iterative solution to find pressure that yields the specified P/Z value. Parameters: pz (float or list, required): P/Z value(s) in psia. Must be > 0.
Can be scalar or array. Example: 5000.0 or [4000, 5000, 6000]. 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. h2s (float, optional, default=0.0): H2S mole fraction (0-1).
Typical: 0-0.05. Example: 0.0. co2 (float, optional, default=0.0): CO2 mole fraction (0-1).
Typical: 0-0.20. Example: 0.0. n2 (float, optional, default=0.0): N2 mole fraction (0-1).
Typical: 0-0.10. Example: 0.0. zmethod (str, optional, default="DAK"): Z-factor method for calculation.
Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
P/Z Method Applications: Volumetric Gas Reserves: P/Z vs Gp plot gives GIIP (Gas Initially In Place) Aquifer Influx Detection: Deviation from straight line indicates water drive Drive Mechanism Identification: Volumetric vs water drive vs gas cap Production Forecasting: Extrapolate P/Z to abandonment pressure
Material Balance Principle:
For volumetric gas reservoirs: P/Z = (Pi/Zi) × (1 - Gp/G)
Where Gp = cumulative production, G = GIIP A straight line on P/Z vs Gp indicates volumetric depletion.
Deviation suggests water influx, changing pore volume, or gas cap expansion. Solution Method:
Iterative Newton-Raphson method to solve: P/Z - pz_target = 0
Converges rapidly for well-posed problems. Returns:
Dictionary with: value (float or list): Pressure in psia (matches input pz shape) method (str): Iterative solution method with Z-factor method units (str): "psia" inputs (dict): Echo of input parameters
Common Mistakes: Using separator temperature instead of reservoir temperature Not accounting for non-hydrocarbon fractions Confusing P/Z (pressure/Z-factor) with pressure Using wrong Z-factor method (must match method used in material balance) Temperature in Celsius instead of Fahrenheit
Example Usage: {
"pz": 5000.0,
"sg": 0.7,
"degf": 180.0,
"h2s": 0.0,
"co2": 0.0,
"n2": 0.0,
"zmethod": "DAK"
} Result: Pressure ≈ 4500-5500 psia (depends on Z-factor at that pressure). Note: P/Z method is fundamental to gas material balance. Always use the same
Z-factor method throughout your analysis for consistency. Account for all
non-hydrocarbon components as they affect Z-factor and thus P/Z values. |
| gas_sg_from_gradient | Calculate gas specific gravity from pressure gradient. DIAGNOSTIC TOOL - Determines gas specific gravity from measured pressure gradient
in a gas column. Uses standalone Newton-Raphson solver (fixed implementation) to
solve the inverse problem. Essential for formation fluid identification and gas
property verification when only gradient data is available. Parameters: gradient (float, required): Pressure gradient in psi/ft. Must be > 0.
Typical: 0.05-0.15 psi/ft. Example: 0.1 psi/ft. degf (float, required): Temperature in °F at measurement depth.
Valid: -460 to 1000. Typical: 100-400°F. Example: 180.0. p (float, required): Pressure in psia at measurement depth. Must be > 0.
Example: 3500.0. method (str, optional, default="DAK"): Z-factor method for calculation.
Options: "DAK", "HY", "WYW", "BUR". DAK recommended.
Gradient Principle:
Gas gradient = dP/dh = (ρg × g) / 144 = (P × MW) / (Z × R × T × 144) Where: ρg = gas density (lb/cuft) MW = molecular weight = sg × 28.97 lb/lbmol Z = gas compressibility factor R = gas constant = 10.732 psia·ft³/(lbmol·°R) T = temperature (°R = °F + 460)
Applications: Formation Fluid ID: Identify gas vs oil vs water from gradient Gas Density Verification: Check measured gas gravity against gradient Completion Fluid Design: Design mud weight based on gas gradient Wellbore Pressure Modeling: Calculate pressure profiles in gas columns
Typical Gradients: Dry gas (sg=0.6): ~0.08 psi/ft Associated gas (sg=0.8): ~0.11 psi/ft Heavy gas (sg=1.0): ~0.14 psi/ft
Solution Method:
Uses Newton-Raphson iterative solver to find sg that yields the specified gradient.
This is a standalone fixed implementation that avoids upstream library bugs. Returns:
Dictionary with: value (float): Gas specific gravity (dimensionless, air=1) method (str): "Gradient correlation (Newton-Raphson)" units (str): "dimensionless (air=1)" 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 (affects MW and Z) Using wrong gradient units (must be psi/ft, not psi/100ft) Temperature in Celsius instead of Fahrenheit
Example Usage: {
"gradient": 0.1,
"degf": 180.0,
"p": 3500.0,
"method": "DAK"
} Result: Gas SG ≈ 0.7-0.8 for typical natural gas gradient. Note: This tool uses a standalone fixed implementation to avoid upstream bugs.
Always use reservoir conditions (pressure and temperature at measurement depth).
Gradient is sensitive to temperature - use correct temperature for accurate results. |
| gas_water_content | Calculate water content of natural gas. CRITICAL GAS PROCESSING TOOL - Computes the amount of water vapor that natural
gas can hold at given pressure and temperature conditions. Essential for hydrate
prevention, dehydration unit design, and pipeline operation. Water content decreases
with increasing pressure and decreasing temperature. 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): Temperature in °F. Valid: -460 to 1000.
Typical: 40-200°F. Example: 100.0. p (float or list, required): Pressure(s) in psia. Must be > 0.
Can be scalar or array. Example: 1000.0 or [500, 1000, 2000].
Water Content Behavior: Decreases with increasing pressure (less water can dissolve) Decreases with decreasing temperature (less water vapor) Typical range: 5-200 lb/MMSCF at pipeline conditions At high pressure/low temperature: <10 lb/MMSCF
Hydrate Formation:
Gas-water systems form solid hydrates (ice-like structures) at certain P-T conditions.
Hydrates can block pipelines and equipment. Gas must be dehydrated below: Hydrate formation temperature at operating pressure Typical target: <7 lb/MMSCF for pipeline operation Typical target: <0.1 lb/MMSCF for LNG/cryogenic processes
Correlation:
Uses McCain correlation (1990) based on experimental data for sweet natural gas.
Valid for typical pipeline and processing conditions. Applications: Hydrate Prevention: Determine minimum dehydration requirement Dehydration Unit Design: Size glycol contactors and regenerators Pipeline Corrosion: Assess water-related corrosion risk Gas Processing: Design dehydration systems for sales gas Sales Gas Specs: Ensure compliance with water content limits
Returns:
Dictionary with: value (float or list): Water content in lb/MMSCF (matches input p shape) method (str): "McCain (1990) correlation" units (str): "lb/MMSCF" inputs (dict): Echo of input parameters note (str): Hydrate prevention guidance
Common Mistakes: Using separator temperature instead of pipeline/processing temperature Pressure in barg/psig instead of psia (must be absolute) Not understanding hydrate formation conditions Confusing water content (lb/MMSCF) with water dew point (°F) Temperature in Celsius instead of Fahrenheit
Example Usage: {
"sg": 0.7,
"degf": 100.0,
"p": [500, 1000, 2000]
} Result: Water content decreases from ~50 lb/MMSCF at 500 psia to ~20 lb/MMSCF at 2000 psia. Note: Water content is critical for pipeline operation. Always check against
hydrate formation curve. For hydrate prevention, compare to hydrate formation
temperature at operating pressure. Typical pipeline requirement: <7 lb/MMSCF. |
| gas_sg_from_composition | Calculate gas specific gravity from composition. COMPOSITIONAL GAS CHARACTERIZATION - Computes gas specific gravity from
hydrocarbon molecular weight and non-hydrocarbon mole fractions. Uses molecular
weight weighted average method. Essential when gas composition is known but SG
measurement is unavailable or unreliable. Parameters: hc_mw (float, required): Hydrocarbon molecular weight in lb/lbmol.
Valid: 10-200. Typical: 16-50. Example: 18.5 for typical natural gas. co2 (float, optional, default=0.0): CO2 mole fraction (0-1).
Typical: 0-0.20. Example: 0.05 for 5% CO2. h2s (float, optional, default=0.0): H2S mole fraction (0-1).
Typical: 0-0.05. Example: 0.02 for 2% H2S (sour gas). n2 (float, optional, default=0.0): N2 mole fraction (0-1).
Typical: 0-0.10. Example: 0.01 for 1% N2. h2 (float, optional, default=0.0): H2 mole fraction (0-1).
Typical: 0-0.01. Example: 0.0 (rare in natural gas).
Calculation Method:
Weighted average based on molecular weights: Formula: MW_avg = hc_fraction × hc_mw + co2 × 44.01 + h2s × 34.08 + n2 × 28.01 + h2 × 2.02
SG = MW_avg / 28.97 Typical Hydrocarbon MW: Applications: Compositional Simulation: Convert composition to SG for black oil models Gas Plant Feed: Characterize feed gas from composition analysis Sales Gas Specs: Calculate SG for pipeline specifications Contaminated Gas: Analyze gas with high non-hydrocarbon content Laboratory Data: Convert GC analysis to SG
Non-Hydrocarbon Effects: CO2 increases SG (MW=44.01 > air MW=28.97) H2S increases SG (MW=34.08 > air MW=28.97) N2 slightly decreases SG (MW=28.01 ≈ air MW=28.97) H2 significantly decreases SG (MW=2.02 << air MW=28.97)
Returns:
Dictionary with: gas_specific_gravity (float): Gas SG (dimensionless, air=1) composition (dict): Detailed composition breakdown hydrocarbon_fraction: Mole fraction of hydrocarbons hydrocarbon_mw: Provided hydrocarbon MW co2_fraction: CO2 mole fraction h2s_fraction: H2S mole fraction n2_fraction: N2 mole fraction h2_fraction: H2 mole fraction
method (str): "Molecular weight weighted average" units (str): "dimensionless (air=1)" inputs (dict): Echo of input parameters
Common Mistakes: Using weight fraction instead of mole fraction Incorrect hydrocarbon MW (must be average MW of HC fraction) Mole fractions don't sum to 1.0 (should sum to 1.0) Using component MW instead of mixture MW for hydrocarbons Not accounting for all non-hydrocarbon components
Example Usage: {
"hc_mw": 18.5,
"co2": 0.05,
"h2s": 0.0,
"n2": 0.01,
"h2": 0.0
} Result: SG ≈ 0.65-0.70 (typical natural gas with 5% CO2, 1% N2). Note: Mole fractions must sum to 1.0. If only HC fraction is provided,
ensure hc_fraction = 1.0 - (co2 + h2s + n2 + h2). Hydrocarbon MW should be
the average MW of the hydrocarbon fraction, not individual component MW. |
| oil_rate_radial | Calculate oil production rate for radial flow (vertical well). INFLOW PERFORMANCE TOOL - Computes oil production rate for vertical wells
with radial flow geometry using Darcy's law. Automatically calculates PVT properties
(Rs, Bo, μo) at average pressure. Optionally applies Vogel IPR model for
two-phase flow below bubble point. Parameters: pi (float, required): Initial/reservoir pressure in psia. Must be > 0.
Example: 4000.0. pb (float, required): Bubble point pressure in psia. Must be ≥ 0.
Example: 3500.0. If pi < pb, reservoir is saturated (gas cap present). api (float, required): Oil API gravity in degrees. Valid: 0-100.
Example: 35.0. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3.
Typical: 0.6-1.2. Example: 0.75. psd (float or list, required): Sandface/draining pressure(s) in psia.
Must be > 0 and < pi. Can be scalar or array. Example: 1500.0 or [1000, 1500, 2000]. h (float, required): Net pay thickness in feet. Must be > 0.
Typical: 10-200 ft. Example: 50.0. k (float, required): Permeability in millidarcies (mD). Must be > 0.
Typical: 1-1000 mD. Example: 100.0. s (float, optional, default=0.0): Skin factor (dimensionless).
Negative = stimulation, positive = damage. Typical: -5 to +20.
Example: 0.0 for undamaged well. re (float, required): Drainage radius in feet. Must be > rw.
Typical: 500-5000 ft. Example: 1000.0. rw (float, required): Wellbore radius in feet. Must be > 0.
Typical: 0.25-0.5 ft. Example: 0.5. rsb (float, required): Solution GOR at bubble point in scf/stb.
Must be ≥ 0. Example: 800.0. vogel (bool, optional, default=False): Apply Vogel IPR model.
Set True when pi < pb (saturated reservoir). Example: False.
Flow Regime: Undersaturated (pi > pb): Single-phase oil flow, Darcy's law applies Saturated (pi < pb): Two-phase flow, use Vogel=True for accurate IPR
Darcy's Law Formula:
qo = (0.00708 × k × h × (pi - pwf)) / (μo × Bo × (ln(re/rw) + S)) Where PVT properties (μo, Bo) are calculated at average pressure (pi + pwf)/2. Returns:
Dictionary with: value (float or list): Oil rate in STB/day (matches input psd shape) method (str): "Darcy radial flow" or "Vogel IPR" units (str): "STB/day" 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 setting vogel=True when pi < pb (underestimates rate) Using wrong drainage radius (re) - should be well spacing/2 Confusing net pay (h) with gross thickness Not accounting for skin factor (s)
Example Usage: {
"pi": 4000.0,
"pb": 3500.0,
"api": 35.0,
"degf": 180.0,
"sg_g": 0.75,
"psd": [1500, 2000, 2500],
"h": 50.0,
"k": 100.0,
"s": 0.0,
"re": 1000.0,
"rw": 0.5,
"rsb": 800.0,
"vogel": False
} Result: Oil rate decreases as sandface pressure increases (typical IPR curve). Note: This tool automatically calculates PVT properties. You don't need to
provide Rs, Bo, or μo - they are computed internally at average pressure.
For saturated reservoirs (pi < pb), set vogel=True for accurate two-phase flow. |
| oil_rate_linear | Calculate oil production rate for linear flow. INFLOW PERFORMANCE TOOL - Computes oil production rate for horizontal wells
or wells with linear flow geometry using Darcy's law. Automatically calculates PVT
properties (Rs, Bo, μo) at average pressure. Essential for horizontal well
performance analysis and completion design. Parameters: pi (float, required): Initial/reservoir pressure in psia. Must be > 0.
Example: 4000.0. pb (float, required): Bubble point pressure in psia. Must be ≥ 0.
Example: 3500.0. If pi < pb, reservoir is saturated (gas cap present). api (float, required): Oil API gravity in degrees. Valid: 0-100.
Example: 35.0. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3.
Typical: 0.6-1.2. Example: 0.75. psd (float or list, required): Sandface/draining pressure(s) in psia.
Must be > 0 and < pi. Can be scalar or array. Example: 1500.0 or [1000, 1500, 2000]. h (float, required): Net pay thickness in feet. Must be > 0.
Typical: 10-200 ft. Example: 50.0. k (float, required): Permeability in millidarcies (mD). Must be > 0.
Typical: 1-1000 mD. Example: 100.0. area (float, required): Cross-sectional flow area in square feet.
Must be > 0. Typical: 100-10000 ft². Example: 1000.0. length (float, required): Flow length in feet. Must be > 0.
Typical: 100-5000 ft. Example: 500.0. rsb (float, required): Solution GOR at bubble point in scf/stb.
Must be ≥ 0. Example: 800.0.
Flow Geometry:
Linear flow occurs in: Darcy's Law Formula (Linear):
qo = (0.001127 × k × area × (pi - pwf)) / (μo × Bo × length) Where PVT properties (μo, Bo) are calculated at average pressure (pi + pwf)/2. Linear vs Radial Flow: Linear: Flow perpendicular to wellbore (horizontal wells) Radial: Flow converging to wellbore (vertical wells) Linear flow typically has higher productivity than radial
Returns:
Dictionary with: value (float or list): Oil rate in STB/day (matches input psd shape) method (str): "Darcy linear flow" units (str): "STB/day" 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) Confusing flow area (perpendicular to flow) with wellbore area Using wrong flow length (should be distance from boundary to well) Not accounting for net pay thickness correctly Confusing linear flow (horizontal wells) with radial flow (vertical wells)
Example Usage: {
"pi": 4000.0,
"pb": 3500.0,
"api": 35.0,
"degf": 180.0,
"sg_g": 0.75,
"psd": [1500, 2000, 2500],
"h": 50.0,
"k": 100.0,
"area": 1000.0,
"length": 500.0,
"rsb": 800.0
} Result: Oil rate decreases as sandface pressure increases (typical IPR curve). Note: This tool automatically calculates PVT properties. You don't need to
provide Rs, Bo, or μo - they are computed internally at average pressure.
Linear flow is characteristic of horizontal wells and hydraulically fractured wells. |
| gas_rate_radial | Calculate gas production rate for radial flow (vertical well). INFLOW PERFORMANCE TOOL - Computes gas production rate for vertical wells
with radial flow geometry using real gas pseudopressure formulation. This accounts
for pressure-dependent gas properties (Z-factor, viscosity) which are significant
for gas systems. More accurate than simplified Darcy's law for gas. Parameters: pi (float, required): Initial/reservoir pressure in psia. Must be > 0.
Example: 5000.0. sg (float, required): Gas specific gravity (air=1). Valid: 0.55-3.0.
Typical: 0.6-1.2. Example: 0.7. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. psd (float or list, required): Sandface/draining pressure(s) in psia.
Must be > 0 and < pi. Can be scalar or array. Example: 2000.0 or [1000, 2000, 3000]. h (float, required): Net pay thickness in feet. Must be > 0.
Typical: 10-200 ft. Example: 50.0. k (float, required): Permeability in millidarcies (mD). Must be > 0.
Typical: 1-1000 mD. Example: 100.0. s (float, optional, default=0.0): Skin factor (dimensionless).
Negative = stimulation, positive = damage. Typical: -5 to +20.
Example: 0.0 for undamaged well. re (float, required): Drainage radius in feet. Must be > rw.
Typical: 500-5000 ft. Example: 1000.0. rw (float, required): Wellbore radius in feet. Must be > 0.
Typical: 0.25-0.5 ft. Example: 0.5. h2s (float, optional, default=0.0): H2S mole fraction (0-1).
Typical: 0-0.05. Example: 0.0. co2 (float, optional, default=0.0): CO2 mole fraction (0-1).
Typical: 0-0.20. Example: 0.0. n2 (float, optional, default=0.0): N2 mole fraction (0-1).
Typical: 0-0.10. Example: 0.0.
Pseudopressure Method:
Uses real gas pseudopressure (m(p)) which linearizes the gas diffusivity equation:
m(p) = 2∫(p/(μZ))dp from pb to p This accounts for: Z-factor variation with pressure Gas viscosity variation with pressure Non-linear pressure behavior
Flow Formula:
qg = (kh × (m(pi) - m(pwf))) / (1422 × T × (ln(re/rw) + S)) Where PVT properties are integrated over pressure range. Returns:
Dictionary with: value (float or list): Gas rate in MSCF/day (matches input psd shape) method (str): "Pseudopressure radial flow" units (str): "MSCF/day" 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 drainage radius (re) - should be well spacing/2 Confusing net pay (h) with gross thickness Not accounting for skin factor (s)
Example Usage: {
"pi": 5000.0,
"sg": 0.7,
"degf": 180.0,
"psd": [2000, 3000, 4000],
"h": 50.0,
"k": 100.0,
"s": 0.0,
"re": 1000.0,
"rw": 0.5,
"h2s": 0.0,
"co2": 0.0,
"n2": 0.0
} Result: Gas rate decreases as sandface pressure increases (typical IPR curve). Note: This tool uses pseudopressure method which is more accurate than
simplified Darcy's law for gas. Always account for non-hydrocarbon components
(H2S, CO2, N2) as they affect Z-factor and flow calculations significantly. |
| gas_rate_linear | Calculate gas production rate for linear flow. INFLOW PERFORMANCE TOOL - Computes gas production rate for horizontal wells
or wells with linear flow geometry using real gas pseudopressure formulation.
This accounts for pressure-dependent gas properties (Z-factor, viscosity) which
are significant for gas systems. More accurate than simplified Darcy's law for gas. Parameters: pi (float, required): Initial/reservoir pressure in psia. Must be > 0.
Example: 5000.0. sg (float, required): Gas specific gravity (air=1). Valid: 0.55-3.0.
Typical: 0.6-1.2. Example: 0.7. degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000.
Example: 180.0. psd (float or list, required): Sandface/draining pressure(s) in psia.
Must be > 0 and < pi. Can be scalar or array. Example: 2000.0 or [1000, 2000, 3000]. h (float, required): Net pay thickness in feet. Must be > 0.
Typical: 10-200 ft. Example: 50.0. k (float, required): Permeability in millidarcies (mD). Must be > 0.
Typical: 1-1000 mD. Example: 100.0. area (float, required): Cross-sectional flow area in square feet.
Must be > 0. Typical: 100-10000 ft². Example: 1000.0. length (float, required): Flow length in feet. Must be > 0.
Typical: 100-5000 ft. Example: 500.0. h2s (float, optional, default=0.0): H2S mole fraction (0-1).
Typical: 0-0.05. Example: 0.0. co2 (float, optional, default=0.0): CO2 mole fraction (0-1).
Typical: 0-0.20. Example: 0.0. n2 (float, optional, default=0.0): N2 mole fraction (0-1).
Typical: 0-0.10. Example: 0.0.
Flow Geometry:
Linear flow occurs in: Horizontal wells (early-time flow) Hydraulically fractured vertical wells (fracture flow) Channelized gas reservoirs Edge water drive systems
Pseudopressure Method:
Uses real gas pseudopressure (m(p)) which linearizes the gas diffusivity equation:
m(p) = 2∫(p/(μZ))dp from pb to p This accounts for: Z-factor variation with pressure Gas viscosity variation with pressure Non-linear pressure behavior
Flow Formula (Linear):
qg = (k × area × (m(pi) - m(pwf))) / (1422 × T × length) Where PVT properties are integrated over pressure range. Linear vs Radial Flow: Linear: Flow perpendicular to wellbore (horizontal wells) Radial: Flow converging to wellbore (vertical wells) Linear flow typically has higher productivity than radial
Returns:
Dictionary with: value (float or list): Gas rate in MSCF/day (matches input psd shape) method (str): "Pseudopressure linear flow" units (str): "MSCF/day" 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) Confusing flow area (perpendicular to flow) with wellbore area Using wrong flow length (should be distance from boundary to well) Confusing linear flow (horizontal wells) with radial flow (vertical wells) Not accounting for net pay thickness correctly
Example Usage: {
"pi": 5000.0,
"sg": 0.7,
"degf": 180.0,
"psd": [2000, 3000, 4000],
"h": 50.0,
"k": 100.0,
"area": 1000.0,
"length": 500.0,
"h2s": 0.0,
"co2": 0.0,
"n2": 0.0
} Result: Gas rate decreases as sandface pressure increases (typical IPR curve). Note: This tool uses pseudopressure method which is more accurate than
simplified Darcy's law for gas. Always account for non-hydrocarbon components
(H2S, CO2, N2) as they affect Z-factor and flow calculations significantly.
Linear flow is characteristic of horizontal wells and hydraulically fractured wells. |
| generate_rel_perm_table | Generate relative permeability table for reservoir simulation. CRITICAL SIMULATION TOOL - Creates saturation-dependent relative permeability
curves for ECLIPSE, Intersect, CMG, or other simulators. Relative permeability
is essential for multiphase flow simulation and determines fluid mobility. Parameters: rows (int, required): Number of saturation points in table. Must be > 0.
Typical: 20-50. Example: 25. More rows = smoother curves but larger files. krtable (str, required): Table type. Options: "SWOF", "SGOF", "SGWFN".
Example: "SWOF" for water-oil systems. krfamily (str, required): Correlation family. Options: "COR" (Corey), "LET".
Example: "COR" for simple power-law, "LET" for flexible fitting. kromax (float, required): Maximum oil relative permeability (0-1).
Typical: 0.5-1.0. Example: 1.0. swc (float, required): Connate water saturation (0-1). Must be < 1.
Typical: 0.1-0.3. Example: 0.15. krwmax (float, optional): Maximum water rel perm for SWOF (0-1).
Typical: 0.1-0.5. Example: 0.25. krgmax (float, optional): Maximum gas rel perm for SGOF/SGWFN (0-1).
Typical: 0.5-1.0. Example: 1.0. sorw (float, optional): Residual oil saturation to water (0-1).
Typical: 0.1-0.3. Example: 0.15. sorg (float, optional): Residual oil saturation to gas (0-1).
Typical: 0.05-0.2. Example: 0.1. sgc (float, optional): Critical gas saturation (0-1).
Typical: 0.05-0.15. Example: 0.1. swcr (float, optional): Critical water saturation for Corey (0-1).
Typical: 0.15-0.25. Example: 0.2. no (float, optional): Corey exponent for oil (Corey only). Must be > 0.
Typical: 2.0-4.0. Example: 2.5. Higher = more curved. nw (float, optional): Corey exponent for water (Corey only). Must be > 0.
Typical: 1.5-3.0. Example: 1.5. ng (float, optional): Corey exponent for gas (Corey only). Must be > 0.
Typical: 2.0-3.5. Example: 2.0. Lo, Eo, To (float, optional): LET parameters for oil (LET only).
Typical: Lo=1-3, Eo=1-2, To=1-3. Example: Lo=2.5, Eo=1.25, To=1.75. Lw, Ew, Tw (float, optional): LET parameters for water (LET only).
Typical: Lw=1-3, Ew=1-2, Tw=1-3. Example: Lw=1.5, Ew=1.0, Tw=2.0. Lg, Eg, Tg (float, optional): LET parameters for gas (LET only).
Typical: Lg=1-3, Eg=1-2, Tg=1-3. Example: Lg=1.2, Eg=1.5, Tg=2.0.
Correlation Families: Corey (1954): Simple power-law model, fast, widely used.
Formula: Kr = krmax * ((S - Sc) / (1 - Swc - Sor))^n
Use for: Quick estimates, standard cases, compatibility. LET (2005): Flexible 3-parameter model, better curve fitting.
Formula: Kr = krmax * (S^L) / (S^L + E * (1-S)^T)
Use for: History matching, complex curves, accuracy.
Table Types: SWOF: Water-Oil (waterflood, aquifer influx). Columns: Sw, Krw, Kro, Pcow. SGOF: Gas-Oil (gas cap expansion, gas injection). Columns: Sg, Krg, Krog, Pcog. SGWFN: Three-phase gas-water (gas cycling, WAG). Columns: Sg, Krg, Krw, Pcog, Pcow.
Saturation Endpoints: Swc: Connate water (immobile water) Sorw: Residual oil to water (trapped oil after waterflood) Sorg: Residual oil to gas (trapped oil after gas injection) Sgc: Critical gas (minimum gas saturation for flow)
Workflow: Choose correlation family (Corey or LET) Select table type (SWOF, SGOF, SGWFN) Specify saturation endpoints (Swc, Sor, Sgc) Set maximum rel perms (kromax, krwmax, krgmax) Define correlation parameters (Corey exponents or LET params) Generate table with specified number of rows
Returns:
Dictionary with: table (list): List of dicts with saturation and rel perm values columns (list): Column names (e.g., ["Sw", "Krw", "Kro", "Pcow"]) rows (int): Number of rows in table table_type (str): Table type (SWOF, SGOF, SGWFN) correlation (str): Correlation family (COR, LET) note (str): Usage guidance inputs (dict): Echo of input parameters
Common Mistakes: Saturation endpoints don't sum correctly (Swc + Sor < 1.0) Using wrong table type for simulation (check simulator requirements) Corey exponents too high (>5) causing unrealistic curves Not specifying required parameters for chosen table type Too few rows (<10) causing poor curve resolution Maximum rel perms > 1.0 (must be dimensionless 0-1)
Example Usage (Corey SWOF): {
"rows": 25,
"krtable": "SWOF",
"krfamily": "COR",
"kromax": 1.0,
"krwmax": 0.25,
"swc": 0.15,
"swcr": 0.2,
"sorw": 0.15,
"no": 2.5,
"nw": 1.5
} Example Usage (LET SGOF): {
"rows": 25,
"krtable": "SGOF",
"krfamily": "LET",
"kromax": 1.0,
"krgmax": 1.0,
"swc": 0.2,
"sorg": 0.15,
"sgc": 0.1,
"Lo": 2.5,
"Eo": 1.25,
"To": 1.75,
"Lg": 1.2,
"Eg": 1.5,
"Tg": 2.0
} Note: Relative permeability tables are critical for accurate simulation.
Always validate endpoints against core data or literature. Use LET for
history matching when Corey doesn't fit data well. Table format is
ECLIPSE-compatible and ready for direct inclusion in simulation decks. |
| generate_aquifer_influence | Generate Van Everdingen & Hurst aquifer influence functions. CRITICAL AQUIFER MODELING TOOL - Creates dimensionless aquifer influence
functions for AQUTAB keyword in ECLIPSE/Intersect. These functions quantify
water influx from surrounding aquifers into hydrocarbon reservoirs. Parameters: res (float or list, required): Dimensionless aquifer radius (ReD).
Must be > 1.0. Can be scalar or list. Typical: 5-100. Example: 10.0.
ReD = re/rw where re = aquifer outer radius, rw = reservoir radius. start (float, required): Minimum dimensionless time (tD_min).
Must be > 0. Typical: 0.01-1.0. Example: 0.1. end (float, required): Maximum dimensionless time (tD_max).
Must be > start. Typical: 10-1000. Example: 100.0. rows (int, required): Number of time points in table. Must be > 0.
Typical: 20-100. Example: 50. More rows = smoother curves.
Background:
Van Everdingen & Hurst (1949) developed analytical solutions for aquifer influx
using diffusivity equation. These functions relate: Dimensionless time (tD) = (k × t) / (φ × μ × ct × rw²) Dimensionless pressure (pD) = aquifer response function Dimensionless radius (ReD) = aquifer geometry
Influence Function:
The influence function pD(tD, ReD) represents the dimensionless pressure response
at the reservoir-aquifer boundary. It depends on: Aquifer geometry (radial vs linear, finite vs infinite) Boundary conditions (constant rate vs constant pressure) Aquifer properties (permeability, porosity, compressibility)
Applications: Material Balance: Quantify aquifer support in material balance analysis Pressure Maintenance: Evaluate aquifer pressure support Water Influx: Calculate cumulative water influx over time History Matching: Match production history with aquifer model Production Forecasting: Predict future aquifer influx
Integration Method:
Uses numerical integration (Gaussian quadrature) of diffusivity equation with
high-resolution integration (M=8) for accuracy. The solution is computed at
specified dimensionless time points. Returns:
Dictionary with: dimensionless_time (list): Dimensionless time values (tD) dimensionless_pressures (list): List of pD arrays (one per ReD) rows (int): Number of time points dimensionless_radii (list): ReD values used time_range (dict): Start and end dimensionless times note (str): Usage guidance for ECLIPSE inputs (dict): Echo of input parameters
Common Mistakes: ReD < 1.0 (aquifer radius must be > reservoir radius) tD_max < tD_min (end must be > start) Too few rows (<10) causing poor resolution Wrong dimensionless radius (must match aquifer geometry) Confusing dimensionless time with actual time Not accounting for aquifer compressibility
Example Usage: {
"res": 10.0,
"start": 0.1,
"end": 100.0,
"rows": 50
} Result: Table with 50 time points from tD=0.1 to tD=100.0 for ReD=10.0. Note: AQUTAB keyword is ready for direct inclusion in ECLIPSE DATA file.
The influence functions are dimensionless and must be scaled using reservoir
and aquifer properties. For multiple aquifers, generate separate tables for
each aquifer with different ReD values. |
| rachford_rice_flash | 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: {
"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. |
| extract_eclipse_problem_cells | Extract convergence problem cells from ECLIPSE/Intersect PRT file. SIMULATION DIAGNOSTICS TOOL - Parse ECLIPSE/Intersect PRT output
files to extract cells with convergence failures, material balance
errors, or other simulation problems. What It Does: Scans ECLIPSE .PRT files for error/warning messages Identifies problem cells by (I, J, K) grid coordinates Extracts timestep and iteration information Reports error types and severity
Applications: Convergence Debugging: Find cells causing timestep cuts Model QC: Identify grid initialization issues Performance Tuning: Locate problematic regions Numerical Stability: Track material balance errors
Common Problems Detected: Material balance errors Negative saturations Pressure/temperature out of range Flash calculation failures Linear solver issues Severe saturation changes
Workflow: Run ECLIPSE/Intersect simulation Locate the .PRT output file Use this tool to extract problem cell locations Investigate problematic cells in pre-processor Refine initialization or grid properties
Output Format: List of problem cells with timestep, iteration,
cell coordinates (I,J,K), error type, and severity. Args:
request: Path to PRT file and output options Returns:
Dictionary with list of problem cells and summary statistics |
| validate_simulation_deck | Validate and process ECLIPSE simulation deck with INCLUDE files. DECK MANAGEMENT TOOL - Recursively process ECLIPSE/Intersect
simulation decks to find all INCLUDE files, validate references,
and optionally create a complete archive. What It Does: Parses main DATA file for INCLUDE keywords Recursively follows INCLUDE chains Validates all referenced files exist Identifies missing or broken references Optionally creates zip archive with all files
Applications: Deck Validation: Ensure all files present before submission Deck Transfer: Create complete archive for sharing Version Control: Bundle all files for archiving QC Check: Verify deck completeness before cluster runs
Workflow: Specify main DATA file(s) to check Tool recursively finds all INCLUDE files Validates each file exists Reports missing files or broken paths Optionally creates zip with all referenced files
INCLUDE File Support: Absolute paths: /full/path/to/file.inc Relative paths: ../INCLUDE/GRID.GRDECL Same directory: SCHEDULE.INC Nested INCLUDE chains: INCLUDE files that reference other INCLUDE files
Output Formats: Summary of all files found List of missing/broken references Optional: ZIP archive with complete deck
Args:
request: List of DATA files, zip option, console output preference Returns:
Dictionary with file inventory, validation results, and optional zip path |
| calculate_brine_properties | Calculate properties of CH4 or CO2 saturated brine. BRINE PVT TOOL - Computes comprehensive brine properties including density,
viscosity, compressibility, and formation volume factor. Essential for aquifer
analysis, water injection, and CO2 sequestration studies. Parameters: p (float or list, required): Pressure(s) in psia. Must be > 0.
Can be scalar or array. Example: 3000.0 or [1000, 2000, 3000]. degf (float, required): Temperature in °F. Valid: -460 to 1000.
Typical: 100-400°F. Example: 180.0. wt (float, required): Salinity in weight percent NaCl (0-30).
Typical: 0-20 wt%. Example: 5.0 for 5% NaCl brine. ch4 (float, optional, default=0.0): CH4 saturation fraction (0-1).
Typical: 0-0.1. Example: 0.05 for 5% CH4 saturation. co2 (float, optional, default=0.0): CO2 saturation fraction (0-1).
Typical: 0-0.1. Example: 0.03 for 3% CO2 saturation.
Properties Calculated: Density (ρw): Brine density in lb/cuft. Increases with salinity, pressure.
Typical: 60-70 lb/cuft. Viscosity (μw): Brine viscosity in cP. Decreases with temperature, increases with salinity.
Typical: 0.3-1.5 cP. Compressibility (cw): Brine compressibility in 1/psi. Critical for aquifer influx.
Typical: 2e-6 to 5e-6 1/psi. Formation Volume Factor (Bw): Volume ratio rb/stb. Slightly > 1.0.
Typical: 1.01-1.05 rb/stb. Solution GOR (Rw): Gas dissolved in brine in scf/stb. Increases with pressure.
Typical: 0-20 scf/stb.
Dissolved Gas Effects: CH4-saturated: Methane dissolved in formation water (typical in aquifers) CO2-saturated: CO2 dissolution (sequestration, EOR, geothermal) Mixed systems supported (CH4 + CO2) Dissolved gas reduces density and increases compressibility
Salinity Range: 0-30 wt% NaCl (fresh water to highly saline) Correlations:
Uses industry-standard correlations accounting for: Pressure effects on density and viscosity Temperature effects (viscosity decreases with T) Salinity variations (density and viscosity increase with salinity) Dissolved gas concentrations (reduces density)
Applications: Aquifer Influx: Calculate water influx rates and volumes Water Injection: Design injection projects and pressure maintenance CO2 Sequestration: Evaluate CO2 storage capacity and brine properties Geothermal Reservoirs: Analyze geothermal brine properties Pressure Maintenance: Evaluate aquifer pressure support Material Balance: Include water drive in material balance calculations
Returns:
Dictionary with: formation_volume_factor_rb_stb (float or list): Bw (matches input p shape) density_lb_cuft (float or list): Brine density (matches input p shape) viscosity_cp (float or list): Brine viscosity (matches input p shape) compressibility_1_psi (float or list): Brine compressibility (matches input p shape) solution_gor_scf_stb (float or list): Gas dissolved in brine (matches input p shape) method (str): "Industry standard correlations" salinity_wt_percent (float): Input salinity dissolved_gas_saturation (float): Combined CH4+CO2 saturation note (str): Usage guidance 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) Salinity in ppm instead of wt% (must convert: wt% = ppm/10000) Not accounting for dissolved gas (affects density and compressibility) Temperature in Celsius instead of Fahrenheit Confusing CH4 and CO2 saturation fractions
Example Usage: {
"p": [1000, 2000, 3000],
"degf": 180.0,
"wt": 5.0,
"ch4": 0.05,
"co2": 0.0
} Result: Brine density increases with pressure, viscosity decreases with temperature.
Dissolved CH4 reduces density compared to pure brine. Note: Brine properties are critical for accurate aquifer modeling. Always
account for dissolved gas (CH4 or CO2) as it significantly affects density and
compressibility. Salinity has major impact on density and viscosity - use correct
formation water salinity. |
| co2_brine_mutual_solubility | Calculate CO2-brine mutual solubilities and properties. CRITICAL CO2-BRINE SYSTEM TOOL - Computes comprehensive properties for CO2-saturated
brine systems using the Duan & Sun (2003) model. Essential for CO2 sequestration,
CO2-EOR, and geothermal applications. Accounts for mutual solubility (CO2 in brine,
H2O in CO2-rich phase). Parameters: pres (float, required): Pressure in psia (field) or bar (metric). Must be > 0.
Typical: 1000-5000 psia. Example: 3000.0 psia. temp (float, required): Temperature in °F (field) or °C (metric).
Typical: 100-400°F. Example: 180.0°F. ppm (float, required): Salinity in parts per million (ppm) NaCl.
Typical: 0-200000 ppm. Example: 50000 ppm (5 wt%). metric (bool, optional, default=False): Unit system flag.
False = field units (psia, °F), True = metric (bar, °C). cw_sat (bool, optional, default=True): Compressibility calculation flag.
True = saturated compressibility, False = undersaturated.
Properties Calculated: Mutual Solubility:
CO2-brine systems exhibit mutual solubility: CO2 dissolves in brine (increases with pressure, decreases with salinity) H2O dissolves in CO2-rich phase (increases with temperature) Both solubilities depend on pressure, temperature, and salinity
Physics:
Uses Duan & Sun (2003) model for CO2-H2O-NaCl systems accounting for: Pressure effects on solubility (higher P = more CO2 dissolved) Temperature effects (higher T = less CO2 dissolved, more H2O in vapor) Salinity effects (higher salinity = less CO2 dissolved) Mutual solubility (both phases contain both components)
Applications: CO2 Sequestration: CCS project design, storage capacity evaluation CO2-EOR: Enhanced oil recovery with CO2 injection, miscibility studies Geothermal: CO2-based geothermal systems, supercritical CO2 Aquifer Storage: Underground CO2 storage capacity, leakage assessment Material Balance: CO2-brine material balance calculations
Salinity Conversion: 1 wt% = 10,000 ppm Seawater ≈ 35,000 ppm (3.5 wt%) Formation brine: 50,000-200,000 ppm (5-20 wt%)
Returns:
Dictionary with: phase_equilibrium (dict): Mole fractions in aqueous and vapor phases densities (dict): All density values (CO2-rich, saturated, pure, fresh) viscosities (dict): All viscosity values (saturated, pure, fresh) formation_volume_factors (dict): Bw values (saturated, pure, fresh) compressibility (dict): Undersaturated and saturated compressibility solution_gor_co2 (float): CO2 dissolved in brine viscosibility_per_bar_or_psi (float): Viscosibility coefficient method (str): "Duan & Sun (2003) CO2-H2O-NaCl model" units (str): "metric" or "field" note (str): Usage guidance inputs (dict): Echo of input parameters
Common Mistakes: Using wrong unit system (check metric flag) Salinity in wt% instead of ppm (must convert: ppm = wt% × 10000) Pressure in barg/psig instead of psia (must be absolute) Temperature in wrong units (check metric flag) Not accounting for mutual solubility (both phases contain both components) Using wrong compressibility (saturated vs undersaturated)
Example Usage (Field Units): {
"pres": 3000.0,
"temp": 180.0,
"ppm": 50000,
"metric": False,
"cw_sat": True
} Result: CO2 solubility in brine ≈ 20-40 scf/stb, H2O in CO2-rich phase ≈ 0.1-1 mol%. Note: CO2-brine mutual solubility is critical for CCS and CO2-EOR projects.
Always use correct unit system (field vs metric). The model accounts for mutual
solubility which is significant at high pressures and temperatures. Salinity
significantly reduces CO2 solubility - use correct formation water salinity. |
| lorenz_to_beta | Convert Lorenz coefficient to Dykstra-Parsons beta parameter. HETEROGENEITY QUANTIFICATION - Converts between two common measures of
reservoir heterogeneity. Essential for comparing reservoirs using different
heterogeneity metrics and for literature data conversion. Parameters: Lorenz Coefficient (L): Ranges from 0 (homogeneous) to 1 (completely heterogeneous) Based on cumulative flow capacity vs cumulative storage capacity Geometric interpretation: area between Lorenz curve and 45° line L = 2 × area between curve and diagonal Directly measurable from production data (PLT, tracer tests)
Dykstra-Parsons Beta (β): Permeability variation coefficient (dimensionless, 0-1) β = (k50 - k84.1) / k50 Based on log-normal permeability distribution Requires permeability data (core, logs) Common in literature and older studies
Conversion Relationship:
Beta and Lorenz are related through log-normal distribution statistics.
Higher Lorenz = higher Beta (both indicate more heterogeneity). Typical Ranges: L < 0.3 (homogeneous): β < 0.5 L = 0.3-0.6 (moderate): β = 0.5-0.7 L > 0.6 (heterogeneous): β > 0.7
Applications: Waterflood Sweep Efficiency: Predict vertical sweep from heterogeneity Vertical Conformance Analysis: Evaluate production allocation Reservoir Characterization: Compare reservoirs using different metrics Performance Prediction: Use beta in Dykstra-Parsons calculations Literature Conversion: Convert published beta values to Lorenz
Returns:
Dictionary with: beta (float): Dykstra-Parsons beta coefficient (0-1) lorenz_coefficient (float): Input Lorenz coefficient method (str): "Lorenz to Dykstra-Parsons conversion" interpretation (dict): Heterogeneity level guidance inputs (dict): Echo of input parameters
Common Mistakes: Lorenz coefficient outside valid range (must be 0-1) Confusing Lorenz with other heterogeneity measures Using beta from wrong distribution (must be log-normal) Not understanding that conversion is approximate (depends on distribution)
Example Usage: Result: β ≈ 0.6-0.7 (moderate to high heterogeneity). Note: Conversion assumes log-normal permeability distribution. For
non-log-normal distributions, conversion may be less accurate. Always
validate against actual permeability data when possible. |
| beta_to_lorenz | Convert Dykstra-Parsons beta to Lorenz coefficient. HETEROGENEITY CONVERSION - Converts beta parameter to Lorenz coefficient.
Essential for converting literature data and comparing reservoirs using
different heterogeneity metrics. Parameters: Dykstra-Parsons Beta (β): Permeability variation coefficient (dimensionless, 0-1) β = (k50 - k84.1) / k50 Based on log-normal permeability distribution Requires permeability data (core, logs) Common in literature and older studies
Lorenz Coefficient (L): Ranges from 0 (homogeneous) to 1 (completely heterogeneous) Based on cumulative flow capacity vs cumulative storage capacity Directly measurable from production data More intuitive for production analysis
Typical Ranges: β < 0.5: Low heterogeneity (L ~ 0.2-0.3) β = 0.5-0.7: Moderate (L ~ 0.3-0.5) β > 0.7: High heterogeneity (L > 0.5)
Use Cases: Literature Conversion: Convert published beta values to Lorenz Reservoir Comparison: Compare reservoirs using different metrics Simulation Input: Convert beta to Lorenz for simulation models Reservoir Analog Studies: Use analog beta values with Lorenz-based tools Historical Data: Convert old Dykstra-Parsons studies to modern metrics
Returns:
Dictionary with: lorenz_coefficient (float): Lorenz coefficient (0-1) beta (float): Input beta coefficient method (str): "Dykstra-Parsons to Lorenz conversion" inputs (dict): Echo of input parameters
Common Mistakes: Beta coefficient outside valid range (must be 0-1) Confusing beta with other variation coefficients Using beta from wrong distribution (must be log-normal) Not understanding that conversion is approximate (depends on distribution)
Example Usage: Result: L ≈ 0.4-0.5 (moderate heterogeneity). Note: Conversion assumes log-normal permeability distribution. For
non-log-normal distributions, conversion may be less accurate. Always
validate against actual production data when possible. |
| lorenz_from_flow_fractions | Calculate Lorenz coefficient from flow and permeability fractions. LORENZ FROM PRODUCTION DATA - Computes Lorenz coefficient from layer-by-layer
flow and permeability data. Essential for analyzing actual production data and
quantifying vertical conformance from measured production allocation. Parameters: flow_frac (list, required): Flow fractions from each layer (0-1).
Must sum to 1.0. Length must match perm_frac. Example: [0.1, 0.2, 0.3, 0.4]. perm_frac (list, required): Permeability-thickness fractions (kh fractions)
for each layer (0-1). Must sum to 1.0. Length must match flow_frac.
Example: [0.05, 0.15, 0.25, 0.55].
Input Data Sources: PLT (Production Logging Tool): Flow rate per layer from production logs Tracer Tests: Flow allocation from tracer response Production Allocation: Flow rates from well test analysis Core Data: Permeability and thickness from core analysis Log Data: Permeability from well logs, thickness from formation tops
Lorenz Coefficient Calculation:
Constructs Lorenz curve from data: Sort layers by kh fraction (ascending) Calculate cumulative kh fraction (x-axis) Calculate cumulative flow fraction (y-axis) Calculate area between curve and diagonal (45° line) L = 2 × area (normalized to 0-1)
Interpretation: L < 0.3: High conformance (flow matches capacity) L = 0.3-0.6: Moderate conformance (some flow imbalance) L ≥ 0.6: Poor conformance (severe flow imbalance)
Applications: Production Allocation Analysis: Quantify vertical conformance from PLT data PLT Interpretation: Convert PLT flow rates to heterogeneity measure Tracer Test Analysis: Evaluate sweep efficiency from tracer response Vertical Conformance Evaluation: Assess waterflood performance History Matching: Match simulation to measured production allocation Performance Diagnosis: Identify layers with poor conformance
Returns:
Dictionary with: lorenz_coefficient (float): Lorenz coefficient (0-1) number_of_layers (int): Number of layers analyzed method (str): "Lorenz from flow and permeability fractions" interpretation (str): Conformance level guidance inputs (dict): Echo of input parameters
Common Mistakes: Flow fractions don't sum to 1.0 (must normalize) Perm fractions don't sum to 1.0 (must normalize) Length mismatch between flow_frac and perm_frac Using weight fractions instead of flow fractions Not sorting layers correctly (must sort by kh) Using wrong kh calculation (must be k × h, not just k)
Example Usage: {
"flow_frac": [0.1, 0.2, 0.3, 0.4],
"perm_frac": [0.05, 0.15, 0.25, 0.55]
} Result: L ≈ 0.4-0.5 (moderate conformance - high-k layers produce more than
their capacity fraction, low-k layers produce less). Note: This is the most direct way to calculate Lorenz from actual production
data. Always ensure fractions sum to 1.0 and layers are correctly matched.
High L indicates poor vertical conformance (flow imbalance). |
| flow_fractions_from_lorenz | 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: 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. |
| generate_layer_distribution | 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: {
"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: {
"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. |
| get_component_properties | Get critical properties for hydrocarbon components from database. COMPONENT DATABASE - Access to comprehensive database of critical properties
for standard hydrocarbon components and common non-hydrocarbons. Essential for
compositional analysis, EOS calculations, and phase behavior modeling. Parameters: component (str, required): Component name. Case-insensitive.
Examples: "methane", "C1", "ethane", "C2", "propane", "C3", "n-butane", "nC4",
"i-butane", "iC4", "benzene", "toluene", "N2", "CO2", "H2S", "H2O". eos (str, optional, default="PR79"): Equation of State model.
Options: "PR79", "PR77", "SRK", "RK". PR79 recommended.
Available Components: Light Ends: Methane (C1), Ethane (C2), Propane (C3), Butane (C4), Pentane (C5) Normal Paraffins: n-C4 through n-C45 (n-butane to n-pentatetracontane) Branched Alkanes: iC4 (isobutane), iC5 (isopentane), neoC5 (neopentane) Aromatics: Benzene (C6H6), Toluene (C7H8), Xylenes (C8H10) Naphthenes: Cyclopentane, Cyclohexane Non-Hydrocarbons: N2 (nitrogen), CO2 (carbon dioxide), H2S (hydrogen sulfide), H2O (water)
Properties Returned: MW: Molecular weight in lb/lbmol. Example: 16.04 for methane. Tc: Critical temperature in °R. Example: 343.0 for methane. Pc: Critical pressure in psia. Example: 667.8 for methane. Zc: Critical compressibility factor (dimensionless). Example: 0.286 for methane. Omega: Acentric factor ω (dimensionless). Example: 0.011 for methane. Vcritical: Critical volume in cuft/lbmol. Example: 1.59 for methane. Tb: Normal boiling point in °R. Example: 201.6 for methane. SG: Specific gravity (dimensionless, relative to water). Example: 0.554 for methane.
EOS Models: PR79 (Peng-Robinson 1979): RECOMMENDED. Most widely used, best accuracy.
Use for: Most applications, hydrocarbon systems, gas processing. PR77 (Peng-Robinson 1977): Original version. Use for: Compatibility, older models. SRK (Soave-Redlich-Kwong 1972): Alternative EOS. Use for: Specific applications, comparison. RK (Redlich-Kwong 1949): Older EOS. Use for: Historical compatibility, simple systems.
Critical Properties Usage:
Critical properties are essential for: EOS phase behavior calculations (PR, SRK, RK) Flash calculations (bubble point, dew point) Phase envelope generation Compressibility factor calculations Vapor-liquid equilibrium
Applications: Compositional Simulation: Input component properties for compositional models EOS Phase Behavior: Calculate phase envelopes and phase boundaries Flash Calculations: Solve vapor-liquid equilibrium problems PVT Modeling: Build compositional PVT models Gas Processing Design: Design separation and processing facilities Material Balance: Compositional material balance calculations
Source:
Industry-standard component database with properties from: NIST (National Institute of Standards and Technology) API (American Petroleum Institute) data EOS calibrations and literature values
Returns:
Dictionary with: component (str): Component name eos_model (str): EOS model used properties (dict): All critical properties (MW, Tc, Pc, Zc, Omega, Vcritical, Tb, SG) method (str): "Component database lookup" note (str): Usage guidance inputs (dict): Echo of input parameters
Common Mistakes: Component name misspelled (check spelling, try common aliases like "C1" for methane) Wrong EOS model (use PR79 unless specific requirement) Case sensitivity (component names are case-insensitive, but use standard capitalization) Component not in database (check available components list) Using properties from wrong EOS (properties are EOS-specific)
Example Usage: {
"component": "methane",
"eos": "PR79"
} Result: Returns all critical properties for methane calibrated for PR79 EOS. Note: Component properties are EOS-specific. Always use properties from the
same EOS model throughout your calculations. PR79 is recommended for most applications.
For components not in database, use external sources or estimate from correlations. |