# PyGERG

[![PyPI version](https://badge.fury.io/py/pygerg.svg)](https://badge.fury.io/py/pygerg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python implementation of the GERG-88 standard for calculating compression factors and other properties of natural gases. A simple, dependency-free package for gas engineering applications.

## Overview

PyGERG provides a complete implementation of the GERG-88 virial equation for calculating compression factors of natural gases using a simplified gas analysis. The GERG-88 standard was developed by the European Group for Gas Research (Groupe Européen de Recherches Gazières) and is widely used in the natural gas industry.

This implementation is based on the original FORTRAN code by J.P.J. Michels & J.A. Schouten from 1991 and has been carefully translated to modern Python with additional error checking, improved documentation, and type annotations.

## Features

- Implementation of the GERG-88 virial equation
- Calculation of compression factors for natural gases
- Simplified gas analysis based on just four parameters
- No external dependencies required
- Type-annotated for modern Python development
- Comprehensive error handling and input validation

## Installation

Install PyGERG using pip:

```bash
pip install pygerg
```

## Usage

The main function `sgerg()` calculates compression factors using a simplified gas analysis:

```python
from pygerg import sgerg

# Example parameters:
x3 = 0.01   # Mole fraction CO2 (0.0 -> 0.3)
hs = 37.0   # Calorific value in MJ/m^3 (20 -> 48)
rm = 0.7443  # Relative density (0.55 -> 0.9)
x5 = 0.00   # Mole fraction H2 (0.0 -> 0.1)
p = 8.0     # Pressure in bar (0 -> 120)
tc = 15.0   # Temperature in degrees Celsius (-23 -> 65)

# Calculate compression factor and other properties
x2, z, d = sgerg(x3, hs, rm, x5, p, tc)

print(f"Calculated N2 fraction: {x2:.4f}")
print(f"Compression factor Z: {z:.6f}")
print(f"Molar density: {d:.6f} mol/m^3")
```

For more advanced usage, you can also use the `GERG88` class directly:

```python
from pygerg import GERG88

calculator = GERG88()
x2, z, d = calculator.sgerg(x3, hs, rm, x5, p, tc)
```

### Input Parameters

- `x3`: Mole fraction of CO2 (range: 0.0 - 0.3)
- `hs`: Calorific value in MJ/m³ (range: 20 - 48)
- `rm`: Relative density (range: 0.55 - 0.9)
- `x5`: Mole fraction of H2 (range: 0.0 - 0.1)
- `p`: Pressure in bar (range: 0 - 120)
- `tc`: Temperature in degrees Celsius (range: -23 - 65)

### Output Values

- `x2`: Calculated mole fraction of N2
- `z`: Compression factor
- `d`: Molar density in mol/m³

## Documentation

The code is fully documented with docstrings and type annotations. You can generate API documentation using tools like Sphinx or access docstrings via Python's built-in `help()` function:

```python
import pygerg
help(pygerg.sgerg)
```

## Background

The GERG-88 standard is used for calculating thermodynamic properties of natural gases. The algorithm uses a simplified approach based on four key parameters (CO2 content, calorific value, relative density, and H2 content) to determine the full gas composition and calculate compression factors.

This implementation is based on the original work:
- Groupe Européen de Recherches Gazières (GERG)
- Original FORTRAN implementation by J.P.J. Michels & J.A. Schouten, August 16, 1991
- Python conversion by Tijs van der Velden, April 2nd, 2025

## License

This project is licensed under the MIT License - see the LICENSE file for details.