282 lines
9.0 KiB
Markdown
282 lines
9.0 KiB
Markdown
# Gaspype
|
|
Gaspype is a performant Python library for thermodynamic calculations like equilibrium
|
|
reactions for several hundred gas species and their mixtures - written in Python/NumPy.
|
|
|
|
It is designed to address the needs of researchers and engineers working in chemical
|
|
engineering, combustion analysis, and energy systems. Thermodynamic calculations,
|
|
especially equilibrium reactions in gas mixtures, are essential for understanding
|
|
processes such as fuel combustion, solid oxide cell (SOFC/SOEC) operations, and other
|
|
high-temperature chemical reactions. Many existing tools present barriers to entry,
|
|
whether due to limited software development experience or restrictive licensing of
|
|
closed-source packages.
|
|
|
|
This library aims to minimize friction by providing a high-level abstraction and a
|
|
ergonomic API, making it accessible for both rapid exploratory calculations and
|
|
integration into large-scale models. Gaspype is implemented in pure Python, fully
|
|
typed, and leverages NumPy vectorization to combine high performance with an
|
|
intuitive interface. It was developed based on practical experience with
|
|
spatially-resolved modeling of solid oxide cells and high-temperature solar
|
|
applications, ensuring its suitability for a wide range of thermodynamic modeling
|
|
tasks.
|
|
|
|
Compared to other open-source packages like Cantera, Gaspype offers a streamlined,
|
|
Pythonic API and competitive performance, despite being implemented entirely in
|
|
Python. Its open-source nature and minimal dependencies make it an accessible and
|
|
powerful tool for researchers in chemistry, chemical engineering, energy systems,
|
|
and electrochemistry.
|
|
|
|
It is designed with goal to be portable to NumPy-style GPU frameworks like JAX and PyTorch.
|
|
|
|
## Key Features
|
|
- Pure Python implementation with NumPy vectorization for high performance
|
|
- Immutable types and comprehensive type hints for reliability
|
|
- Intuitive, Pythonic API for both rapid prototyping and complex multidimensional models
|
|
- Ready for Jupyter Notebook and educational use
|
|
- Designed for future GPU support (JAX, PyTorch)
|
|
- Ships with a comprehensive NASA9-based species database (500+ species with NASA9-polynomials)
|
|
- Supports electrochemical calculations including Nernst potentials and cell voltages
|
|
- Optimized binary database format for fast species lookup and minimal memory usage
|
|
|
|
## Installation
|
|
Installation with pip:
|
|
``` bash
|
|
pip install gaspype
|
|
```
|
|
|
|
Installation with conda:
|
|
``` bash
|
|
conda install conda-forge::gaspype
|
|
```
|
|
|
|
## Getting started
|
|
Gaspype provides two main classes: ```fluid``` and ```elements```.
|
|
|
|
### Fluid
|
|
A fluid class describes a mixture of molecular species and their individual molar amounts.
|
|
|
|
``` python
|
|
import gaspype as gp
|
|
fl = gp.fluid({'H2O': 1, 'H2': 2})
|
|
fl
|
|
```
|
|
```
|
|
Total 3.000e+00 mol
|
|
H2O 33.33 %
|
|
H2 66.67 %
|
|
```
|
|
|
|
Its functions provide thermodynamic, mass balance and ideal gas properties of the mixture.
|
|
|
|
``` python
|
|
cp = fl.get_cp(t=800+273.15)
|
|
mass = fl.get_mass()
|
|
gas_volume = fl.get_v(t=800+273.15, p=1e5)
|
|
```
|
|
|
|
The arguments can be provided as NumPy-arrays:
|
|
|
|
``` python
|
|
import numpy as np
|
|
t_range = np.linspace(600, 800, 5) + 273.15
|
|
fl.get_density(t=t_range, p=1e5)
|
|
```
|
|
```
|
|
array([0.10122906, 0.09574625, 0.09082685, 0.08638827, 0.08236328])
|
|
```
|
|
A ```fluid``` object can have multiple compositions. A multidimensional ```fluid``` object
|
|
can be created for example by multiplication with a NumPy array:
|
|
|
|
``` python
|
|
fl2 = gp.fluid({'H2O': 1, 'N2': 2}) + \
|
|
np.linspace(0, 10, 4) * gp.fluid({'H2': 1})
|
|
fl2
|
|
```
|
|
```
|
|
Total mol:
|
|
array([ 3. , 6.33333333, 9.66666667, 13. ])
|
|
Species:
|
|
H2 H2O N2
|
|
Molar fractions:
|
|
array([[0. , 0.33333333, 0.66666667],
|
|
[0.52631579, 0.15789474, 0.31578947],
|
|
[0.68965517, 0.10344828, 0.20689655],
|
|
[0.76923077, 0.07692308, 0.15384615]])
|
|
```
|
|
A fluid object can be converted to a pandas dataframe:
|
|
``` python
|
|
import pandas as pd
|
|
pd.DataFrame(list(fl2))
|
|
```
|
|
| | H2O | N2 | H2
|
|
|----|-----|-----|-------
|
|
|0 | 1.0 | 2.0 | 0.000000
|
|
|1 | 1.0 | 2.0 | 3.333333
|
|
|2 | 1.0 | 2.0 | 6.666667
|
|
|3 | 1.0 | 2.0 | 10.000000
|
|
|
|
The broadcasting behavior is not limited to 1D-arrays:
|
|
|
|
``` python
|
|
fl3 = gp.fluid({'H2O': 1}) + \
|
|
np.linspace(0, 10, 4) * gp.fluid({'H2': 1}) + \
|
|
np.expand_dims(np.linspace(1, 3, 3), axis=1) * gp.fluid({'N2': 1})
|
|
fl3
|
|
```
|
|
```
|
|
Total mol:
|
|
array([[ 2. , 5.33333333, 8.66666667, 12. ],
|
|
[ 3. , 6.33333333, 9.66666667, 13. ],
|
|
[ 4. , 7.33333333, 10.66666667, 14. ]])
|
|
Species:
|
|
H2 H2O N2
|
|
Molar fractions:
|
|
array([[[0. , 0.5 , 0.5 ],
|
|
[0.625 , 0.1875 , 0.1875 ],
|
|
[0.76923077, 0.11538462, 0.11538462],
|
|
[0.83333333, 0.08333333, 0.08333333]],
|
|
|
|
[[0. , 0.33333333, 0.66666667],
|
|
[0.52631579, 0.15789474, 0.31578947],
|
|
[0.68965517, 0.10344828, 0.20689655],
|
|
[0.76923077, 0.07692308, 0.15384615]],
|
|
|
|
[[0. , 0.25 , 0.75 ],
|
|
[0.45454545, 0.13636364, 0.40909091],
|
|
[0.625 , 0.09375 , 0.28125 ],
|
|
[0.71428571, 0.07142857, 0.21428571]]])
|
|
```
|
|
|
|
### Elements
|
|
In some cases not the molecular but the atomic composition is of interest.
|
|
The ```elements``` class can be used for atom based balances and works similar:
|
|
|
|
``` python
|
|
el = gp.elements({'N': 1, 'Cl': 2})
|
|
el.get_mass()
|
|
```
|
|
```
|
|
np.float64(0.08490700000000001)
|
|
```
|
|
A ```elements``` object can be as well instantiated from a ```fluid``` object.
|
|
Arithmetic operations between ```elements``` and ```fluid``` result in
|
|
an ```elements``` object:
|
|
``` python
|
|
el2 = gp.elements(fl) + el - 0.3 * fl
|
|
el2
|
|
```
|
|
```
|
|
Cl 2.000e+00 mol
|
|
H 4.200e+00 mol
|
|
N 1.000e+00 mol
|
|
O 7.000e-01 mol
|
|
```
|
|
|
|
Going from an atomic composition to a molecular composition is possible as well.
|
|
One way is to calculate the thermodynamic equilibrium for a mixture:
|
|
|
|
``` python
|
|
fs = gp.fluid_system('CH4, H2, CO, CO2, O2')
|
|
el3 = gp.elements({'C': 1, 'H': 2, 'O':1}, fs)
|
|
fl3 = gp.equilibrium(el3, t=800)
|
|
fl3
|
|
```
|
|
```
|
|
Total 1.204e+00 mol
|
|
CH4 33.07 %
|
|
H2 16.93 %
|
|
CO 16.93 %
|
|
CO2 33.07 %
|
|
O2 0.00 %
|
|
```
|
|
|
|
The ```equilibrium``` function can be called with a ```fluid``` or ```elements``` object
|
|
as first argument. ```fluid``` and ```elements``` referencing a ```fluid_system``` object
|
|
which can be set as shown above during the object instantiation. If not provided,
|
|
a new one will be created automatically. Providing a ```fluid_system``` gives more
|
|
control over which molecular species are included in derived ```fluid``` objects.
|
|
Furthermore arithmetic operations between objects with the same ```fluid_system```
|
|
are potentially faster:
|
|
|
|
``` python
|
|
fl3 + gp.fluid({'CH4': 1}, fs)
|
|
```
|
|
```
|
|
Total 2.204e+00 mol
|
|
CH4 63.44 %
|
|
H2 9.24 %
|
|
CO 9.24 %
|
|
CO2 18.07 %
|
|
O2 0.00 %
|
|
```
|
|
|
|
Especially if the ```fluid_system``` of one of the operands has not a subset of
|
|
molecular species of the other ```fluid_system``` a new ```fluid_system``` will
|
|
be created for the operation which might degrade performance:
|
|
|
|
``` python
|
|
fl3 + gp.fluid({'NH3': 1})
|
|
```
|
|
```
|
|
Total 2.204e+00 mol
|
|
CH4 18.07 %
|
|
CO 9.24 %
|
|
CO2 18.07 %
|
|
H2 9.24 %
|
|
NH3 45.38 %
|
|
O2 0.00 %
|
|
```
|
|
|
|
## Developer Guide
|
|
Contributions are welcome, please open an issue or submit a pull request on GitHub.
|
|
|
|
To get started with developing the `gaspype` package, follow these steps.
|
|
|
|
First, clone the repository to your local machine using Git:
|
|
|
|
```bash
|
|
git clone https://github.com/DLR-Institute-of-Future-Fuels/gaspype.git
|
|
cd gaspype
|
|
```
|
|
|
|
It's recommended to setup an venv:
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
|
|
```
|
|
|
|
Install the package and dev-dependencies while keeping the package files
|
|
in the current directory:
|
|
|
|
```bash
|
|
pip install -e .[dev]
|
|
```
|
|
|
|
Compile binary property database from text based files:
|
|
|
|
```bash
|
|
python thermo_data/combine_data.py thermo_data/combined_data.yaml thermo_data/nasa9*.yaml thermo_data/nasa9*.xml
|
|
python thermo_data/compile_to_bin.py thermo_data/combined_data.yaml src/gaspype/data/therm_data.bin
|
|
```
|
|
|
|
Ensure that everything is set up correctly by running the tests:
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
## Limitations
|
|
- **Ideal gas assumption**: Gaspype treats species as ideal gases, limiting applicability to moderate pressures or high-temperature applications.
|
|
- **Isobaric equilibrium**: Currently, only isobaric (constant pressure) equilibrium calculations are implemented.
|
|
|
|
## Quality Assurance
|
|
Gaspype's calculations are validated against reference data from:
|
|
- **Refprop** - for thermodynamic properties
|
|
- **Cantera** - for equilibrium calculations
|
|
- **Cycle-Tempo** - for additional equilibrium validation
|
|
|
|
The test suite includes over 1,000 reference values and covers all code snippets from the documentation.
|
|
|
|
## License
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|