Metadata-Version: 2.4
Name: petropt
Version: 0.3.4
Summary: Open-source Python library for petroleum & reservoir engineering — PVT, IPR, decline, multiphase flow, material balance, petrophysics (Archie/Simandoux/Timur), rate transient analysis (Blasingame / Agarwal-Gardner / NPI), drilling (API 5C3 collapse, Barlow burst), production (Turner/Coleman/Katz/Gilbert), economics, well log I/O. MIT licensed.
Project-URL: Homepage, https://petropt.com
Project-URL: Repository, https://github.com/petropt/petropt
Project-URL: Documentation, https://tools.petropt.com/docs/
Project-URL: Online Tools, https://tools.petropt.com
Project-URL: Issues, https://github.com/petropt/petropt/issues
Author: Mehrdad G. Shirangi
Author-email: Groundwork Analytics LLC <info@petropt.com>
License-Expression: MIT
License-File: LICENSE
Keywords: API-5C3,API-RP-14E,Agarwal-Gardner,Archie,Arps,Barlow,Beggs-Brill,Blasingame,Coates,Coleman,Darcy-Weisbach,ECD,Fetkovich,Gilbert,Hammerschmidt,IPR,Indonesian,Katz,LAS,Larionov,MAASP,NPI,NPV,PVT,RTA,STOIIP,Simandoux,Standing,Timur,Turner,Vogel,Vshale,Z-factor,burst-pressure,collapse-pressure,decline-curve,drilling,economics,erosional-velocity,flowing-material-balance,hydrate,kill-mud,linear-flow,material-balance,net-pay,oil-gas,open-source,petroleum-engineering,petrophysics,production,production-data,relative-permeability,reservoir-engineering,well-logs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: lasio>=0.31
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Provides-Extra: all
Requires-Dist: dlisio>=0.3; extra == 'all'
Requires-Dist: jupyter; extra == 'all'
Requires-Dist: matplotlib; extra == 'all'
Provides-Extra: dlis
Requires-Dist: dlisio>=0.3; extra == 'dlis'
Provides-Extra: notebooks
Requires-Dist: jupyter; extra == 'notebooks'
Requires-Dist: matplotlib; extra == 'notebooks'
Description-Content-Type: text/markdown

# petropt — The Python Library for Petroleum Engineering

[![PyPI](https://img.shields.io/pypi/v/petropt)](https://pypi.org/project/petropt/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://github.com/petropt/petropt/actions/workflows/test.yml/badge.svg)](https://github.com/petropt/petropt/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/petropt/)

> Free, open-source petroleum engineering tools for Python. MIT licensed — use anywhere, no restrictions.

**[Online Calculators](https://tools.petropt.com)** · **[Documentation](https://tools.petropt.com/docs/)**

## Install

```bash
pip install petropt
```

## Quick Start

```python
import petropt

# Load a production dataset
df = petropt.datasets.load_sample_production()

# PVT: Standing bubble point pressure
pb = petropt.correlations.standing_bubble_point(api=35, gas_sg=0.65, temp=200)

# Decline: Arps hyperbolic forecast
import numpy as np
t = np.arange(0, 60)
q = petropt.correlations.arps_decline(qi=1000, di=0.05, b=0.5, t=t)

# IPR: Vogel inflow performance
ipr = petropt.correlations.vogel_ipr(qmax=1500, pr=3500, num_points=50)

# Petrophysics: water saturation from resistivity
sw = petropt.petrophysics.archie_sw(rt=20.0, phi=0.20, rw=0.05)

# RTA: Blasingame variables for type-curve matching
bg = petropt.rta.blasingame_variables(t, q, cum, pwf, pi=3000)

# Economics: NPV of a well
npv = petropt.economics.npv(cash_flows=[-500000, 80000, 70000, 60000], discount_rate=0.10, periods_per_year=1)
```

## What's Inside

### Correlations (50+ functions)
- **PVT** — Standing bubble point/Rs/Bo, Beggs-Robinson viscosity, Sutton & Piper pseudocritical, Hall-Yarborough & Dranchuk Z-factor, Lee-Gonzalez-Eakin gas viscosity, gas Bg/density/compressibility
- **Water PVT** — McCain Bw/viscosity/density, Osif compressibility, gas solubility
- **IPR** — Vogel, Fetkovich, Rawlins-Schellhardt (C&n), PI-based, composite (Vogel + PI)
- **Decline Curves** — Arps (exponential, hyperbolic, harmonic), cumulative production, EUR
- **Multiphase Flow** — Beggs-Brill pressure gradient (all flow patterns, any inclination)
- **Hydraulics** — Darcy-Weisbach with Churchill friction factor
- **Relative Permeability** — Corey, Brooks-Corey, LET models (oil/water/gas)
- **Material Balance** — Gas P/Z, Havlena-Odeh, OOIP estimation, drive indices
- **Volumetrics** — STOIIP, GIIP, drainage radius, recovery factor

### Petrophysics
- **Vshale** — linear, Larionov (Tertiary / older), Clavier
- **Porosity** — density, sonic (Wyllie / Raymer-Hunt-Gardner), neutron-density, effective
- **Water saturation** — Archie, Simandoux, Indonesian (Poupon-Leveaux)
- **Permeability** — Timur, Coates (NMR)
- **Pay** — cutoff-based net pay, NTG, pay-weighted averages, hydrocarbon pore thickness

### Rate Transient Analysis (RTA)
- **Transforms** — pressure-normalized rate, material balance time
- **Type curves** — Blasingame, Agarwal-Gardner, NPI variables
- **Flowing material balance** — contacted OOIP/OGIP from producing-well data
- **Linear flow** — sqrt(t) analysis, sqrt(k)·xf extraction from fracture wells

### Drilling
- **Well control** — hydrostatic, ECD, MAASP, kill mud weight, ICP/FCP (Driller's / Wait-and-Weight)
- **Hydraulics** — annular velocity, nozzle TFA, bit pressure drop
- **Tubulars** — Barlow burst with API 0.875 factor, full API 5C3 collapse (yield / plastic / transition / elastic regimes)

### Production Engineering
- **Liquid loading** — Turner (1969) and Coleman (1991) critical droplet-lift velocities
- **Flow assurance** — Katz hydrate formation temperature, Hammerschmidt methanol/MEG/ethanol inhibitor dosing
- **Piping** — API RP 14E erosional velocity
- **Choke flow** — Gilbert (1954) critical-flow rate correlation

### Economics
- NPV, IRR, payback period, oil & gas monthly cashflow (WI/NRI/severance/opex/capex)

### I/O
- **LAS files** — Read well logs to pandas DataFrame (wraps lasio)
- **Production CSV** — Auto-detect date/oil/gas/water columns from any naming convention

### Datasets
- **Petrobras 3W** — Labeled well events for fault detection (CC BY 4.0)
- **NPD Wellbore** — Norwegian Continental Shelf well metadata (NLOD)
- **Sample Production** — Bundled 2-well, 12-month dataset for demos

### Notebooks
- `student_intro.ipynb` — Your first petroleum dataset in Python
- `decline_analysis.ipynb` — Arps decline curve analysis tutorial

## Why petropt?

| | petropt | pyResToolbox | DIY scripts |
|---|---|---|---|
| **License** | **MIT** (use anywhere) | GPL (copyleft) | N/A |
| **Datasets** | Built-in (3W, NPD, samples) | No | No |
| **LAS reader** | Yes | No | Manual |
| **Student notebooks** | Yes | No | No |
| **Web calculators** | [tools.petropt.com](https://tools.petropt.com) | No | No |
| **Economics** | NPV, IRR, cashflow | No | Manual |
| **Hosted & visual** | [tools.petropt.com](https://tools.petropt.com) — paid web app with calculators (decline curves, PVT, well economics, LAS viewer) and a built-in workspace by Groundwork Analytics | — | — |

petropt is **MIT licensed** — use it freely in commercial products, research, classrooms, and AI applications. No copyleft restrictions.

## History

This repository was first initiated 8 years ago, in July 2018 (see [`master` branch](https://github.com/petropt/petropt/tree/master) for the original placeholder). Most of the code was developed and used privately over the years. We consolidated the collected work and released the open-source version on April 24, 2026.

## For AI Builders

```bash
pip install petro-mcp  # MCP server that wraps petropt for Claude/ChatGPT/LLMs
```

## Links

- [tools.petropt.com](https://tools.petropt.com) — paid web app: PE calculators + workspace by Groundwork Analytics
- [tools.petropt.com/docs/](https://tools.petropt.com/docs/) — documentation
- [github.com/petropt/petropt](https://github.com/petropt/petropt) — source, issues, releases

## Citation

If you use petropt in academic work, please cite:

```
Shirangi, M.G. (2026). petropt: The Python Library for Petroleum Engineering.
https://github.com/petropt/petropt
```

## License

MIT — see [LICENSE](LICENSE) for details.
