Petropy

PetroPy - Petrophysical Analysis

Quick Reference

import petropy as pp

# Load and inspect
log = pp.Log('well.las')
print(log.keys())              # Available curves
depth, gr = log['DEPT'], log['GR']

# Calculate properties
log.shale_volume(gr_curve='GR', gr_clean=20, gr_shale=120)
log.formation_porosity(rhob_curve='RHOB', rhob_matrix=2.65, rhob_fluid=1.0)
log.water_saturation(method='archie', rt_curve='RT', porosity_curve='PHIT', rw=0.05)
log.permeability(method='timur', porosity_curve='PHIT', sw_curve='SW')

Key Classes

| Class | Purpose | |-------|---------| | Log | Main well log container, extends lasio.LASFile | | electrofacies | Facies classification utilities | | Formations | Zone/formation management |

Essential Operations

Shale Volume (Vsh)

log.shale_volume(
    gr_curve='GR',
    gr_clean=20,           # GR of clean sand (API)
    gr_shale=120,          # GR of shale (API)
    method='linear'        # or 'larionov_young', 'larionov_old', 'clavier'
)
vsh = log['VSH']

Porosity

# Density porosity with shale correction
log.formation_porosity(
    rhob_curve='RHOB',
    rhob_matrix=2.65,      # g/cc (sandstone)
    rhob_fluid=1.0,        # g/cc (water)
    rhob_shale=2.45,       # optional shale correction
    vsh_curve='VSH'        # requires VSH curve
)
phi = log['PHIT']

Water Saturation

log.water_saturation(
    method='archie',       # or 'simandoux', 'indonesia'
    rt_curve='RT',
    porosity_curve='PHIT',
    rw=0.05,               # Formation water resistivity (ohm-m)
    a=1.0, m=2.0, n=2.0    # Archie parameters
)
sw = log['SW']

Permeability

log.permeability(
    method='timur',        # or 'coates'
    porosity_curve='PHIT',
    sw_curve='SW'
)
perm = log['PERM']         # Result in mD

Pay Flag and Net Pay

import numpy as np
pay = (log['VSH']  0.08) & (log['SW'] < 0.6)
log['PAY'] = pay.astype(float)
net_pay = np.sum(pay) * log.step

Export Results

log.to_las('well_interpreted.las')

# Or to CSV
import pandas as pd
df = pd.DataFrame({'DEPT': log['DEPT'], 'VSH': log['VSH'], 'PHIT': log['PHIT'], 'SW': log['SW']})
df.to_csv('results.csv', index=False)

Archie Parameters

| Parameter | Symbol | Range | Description | |-----------|--------|-------|-------------| | Tortuosity | a | 0.6-1.0 | Formation factor coefficient | | Cementation | m | 1.8-2.2 | Pore geometry factor | | Saturation exp | n | 1.8-2.2 | Wettability factor |

Matrix Properties

| Lithology | rhob (g/cc) | nphi (v/v) | DT (us/ft) | |-----------|-------------|------------|------------| | Sandstone | 2.65 | -0.02 | 55.5 | | Limestone | 2.71 | 0.00 | 47.5 | | Dolomite | 2.87 | 0.02 | 43.5 | | Shale | 2.45 | 0.30-0.45 | 70-130 |

When to Use vs Alternatives

| Tool | Best For | |------|----------| | petropy | Automated formation evaluation, standard petrophysical workflows | | welly | Well data management, curve processing, multi-well projects | | custom calculations | Non-standard equations, full control over methodology |

Use petropy when you need a streamlined formation evaluation pipeline: Vsh, porosity, Sw, permeability, and pay flags with standard methods (Archie, Simandoux, Timur). It extends lasio so file I/O is built in.

Use welly instead when your focus is data management, curve QC, and multi-well projects rather than petrophysical calculations.

Use custom calculations instead when you need non-standard saturation models, proprietary equations, or more control over the computation steps than petropy's built-in methods provide.

Common Workflows

Complete formation evaluation from raw logs

- [ ] Load well with `pp.Log('well.las')`, verify required curves exist
- [ ] Pick clean sand and shale GR values from histogram or crossplot
- [ ] Compute shale volume: `log.shale_volume()`
- [ ] Compute porosity: `log.formation_porosity()` with matrix parameters
- [ ] Determine Rw from water zone or catalog; set Archie parameters
- [ ] Compute water saturation: `log.water_saturation()`
- [ ] Compute permeability: `log.permeability()`
- [ ] Apply pay flag cutoffs (Vsh, porosity, Sw) and calculate net pay
- [ ] Export interpreted log to LAS or CSV

References

• [Calculations](references/calculations.md) - Porosity, saturation, and permeability equations
• [Fluid Properties](references/fluid_properties.md) - Fluid property models and correlations

Scripts

• [scripts/formationevaluation.py](scripts/formationevaluation.py) - Complete formation evaluation workflow

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SteadfastAsArt
• Source: SteadfastAsArt/geoscience-skills
• License: MIT

Install and usage instructions live in the source repository linked above.