petropy

name	petropy
description	Petrophysical analysis and formation evaluation from well logs. Calculate porosity, water saturation, permeability, and lithology. Use when Claude needs to: (1) Calculate shale volume from gamma ray, (2) Compute porosity from density/neutron/sonic logs, (3) Estimate water saturation using Archie or Simandoux, (4) Calculate permeability from porosity and saturation, (5) Perform pay zone identification, (6) Conduct multi-mineral analysis, (7) Generate petrophysical summation plots.
version	1.0.0
author	Geoscience Skills
license	MIT
tags	["Petrophysics","Formation Evaluation","Water Saturation","Porosity","PetroPy","Well Logs","Permeability","Archie"]
dependencies	["petropy>=0.1.6","lasio","numpy"]
complements	["lasio","welly","striplog"]
workflow_role	analysis

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.4) & (log['PHIT'] > 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 - Porosity, saturation, and permeability equations
• Fluid Properties - Fluid property models and correlations

Scripts

• scripts/formation_evaluation.py - Complete formation evaluation workflow