FuelLib

Overview

FuelLib (SWR-25-26) utilizes the tables and functions of the Group Contribution Method (GCM) as proposed by Constantinou and Gani (1994) and Constantinou, Gani and O'Connel (1995), with additional physical properties discussed in Govindaraju & Ihme (2016). The code is based on Pavan B. Govindaraju's Matlab implementation of the GCM, and has been expanded to include additional thermodynamic properties and mixture properties. The fuel library contains gas chromatography (GC x GC) data for a variety of fuels ranging from simple single component fuels to complex jet fuels. The GC x GC data for POSF jet fuels comes from Edwards (2020).

Citing this Work

If you use FuelLib in your research, please cite the following software record:

Montgomery, David, Appukuttan, Sreejith, Yellapantula, Shashank, Perry, Bruce, and Binswanger, Adam. FuelLib (Fuel Library) [SWR-25-26]. Computer Software. https://github.com/NatLabRockies/FuelLib. USDOE Office of Energy Efficiency and Renewable Energy (EERE), Office of Sustainable Transportation. Vehicle Technologies Office (VTO). 27 Feb. 2025. Web. doi:10.11578/dc.20250317.1.

Installation

Option 1: Install from PyPI (Recommended)

The easiest way to install FuelLib is via pip from pypi.org/project/fuellib:

pip install fuellib

For better dependency isolation, it is recommended to create a conda environment. For example:

Using Conda

conda create --name fuellib-env python
conda activate fuellib-env
pip install fuellib

Option 2: Development Installation (For Contributors)

Clone the repository and install in editable mode:

git clone https://github.com/NatLabRockies/FuelLib.git
cd FuelLib

Install Development Dependencies (uv, Recommended)

uv is the recommended way to set up a FuelLib development environment: it creates and manages a virtual environment for you and installs dependencies much faster than pip.

uv venv
uv pip install -e '.[dev]'  # Install with development tools (docs, testing, formatting)

Run uv lock to regenerate uv.lock after changing dependencies in pyproject.toml, keeping installs reproducible across machines.

Install Development Dependencies (Conda)

conda create --name fuellib-dev-env python
conda activate fuellib-dev-env
conda install -c conda-forge rust
pip install -e '.[dev]'  # Install with development tools (docs, testing, formatting)

Note: Building grimp (a dependency of import-linter) requires a Rust toolchain. On macOS you may need to run brew install rust.

See the Contributing page for more detailed setup instructions and contribution guidelines.

Library Usage

This repository includes tutorials of ways to use FuelLib. We recommend starting with the basic tutorial, tutorials/basic.py, which is documented at natlabrockies.github.io/FuelLib/tutorials-basic.html.

Command-Line Tools

After installing FuelLib using one of the methods above, you have access to several command-line tools for plotting, unit conversion, and exporting fuel data. A comprehensive list is provided in the documentation at https://natlabrockies.github.io/FuelLib/tutorials-cli.html.

Contributing

New contributions are always welcome! For detailed contribution guidelines, installation instructions, and development setup, see the Contributing page in the documentation.

Quick start:

1. Fork the main repository
2. Create a newFeature branch that contains your changes
3. Update the sphinx documentation in newFeature
4. Install development dependencies: uv venv && uv pip install -e '.[dev]' (or pip install -e '.[dev]')
5. Format the source code files using the provided CLI command: fl-format
6. Run tests and build documentation locally to verify your changes
7. Open a Pull Request (PR) from newFeature on your fork to branch main FuelLib repository.

Sphinx Documentation

This repository uses Sphinx to generate documentation.

To build the documentation, first install FuelLib with development support:

pip install -e ".[dev]"

Then use the provided CLI command:

fl-build-docs

The HTML documentation will be generated in docs/_build/html/. Open docs/_build/html/index.html in your web browser to view it.