Welcome to FuelLib’s documentation!

The Fuel Library (FuelLib) utilizes the group contribution method (GCM), as developed by Constantinou and Gani[1] [2] in the mid-1990s with additions from Govindaraju and Ihme (2016)[3], to provide a systematic approach for estimating the thermodynamic properties of pure organic compounds and mixtures of organic compounds. If you need help or have questions, please use the GitHub discussion. The source code is available at github.com/NatLabRockies/FuelLib.

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.

Or in BibTeX format:

@misc{fuellib_2025,
   title = {FuelLib (Fuel Library) [SWR-25-26]},
   author = {Montgomery, David and Appukuttan, Sreejith and Yellapantula, Shashank and Perry, Bruce and Binswanger, Adam},
   doi = {10.11578/dc.20250317.1},
   url = {https://doi.org/10.11578/dc.20250317.1},
   howpublished = {[Computer Software] \url{https://doi.org/10.11578/dc.20250317.1}},
   year = {2025},
   month = {feb}
}

Installation

The easiest way to install FuelLib is via pip:

pip install fuellib

After installation, several command-line tools will be available for exporting fuel data and plotting fuel properties. See the CLI Tutorials for detailed usage examples and options.

For more detailed information on a development setup, see the Contributing page.

Package Requirements

FuelLib requires:

• numpy ≥1.19.0

• pandas ≥1.0.0

• scipy ≥1.5.0

• matplotlib ≥3.0.0

Development tools (Sphinx, Black, pytest) are available for developers installing from source; see the installation instructions in the Contributing section.

Contents:

• Fuel Property Prediction Model
  • Table of GCM properties
  • Equations for GCM properties
  • Equations for individual compound correlations
    • Kinematic viscosity
    • Latent heat of vaporization
    • Liquid molar volume
    • Density
    • Mass specific heat capacity of the liquid
    • Saturated vapor pressure
    • Surface tension
    • Thermal conductivity
  • Equations for mixture properties from GCM
    • Conventional mixing rules
    • Mixture density
    • Mixture kinematic viscosity
    • Mixture vapor pressure
    • Mixture surface tension
    • Mixture thermal conductivity
  • Reference Compounds for Jet Fuels
  • Validation
    • Single Component Fuels
    • Multicomponent Fuels
    • Fuel Blends
  • References
• Tutorials
  • Introduction and Basic Usage
    • Download and Setup
    • Required Input Files
    • Decomposing Fuel Components into Fundamental Groups
    • Basic Usage
  • Command-Line Interface (CLI) Tools
    • Plotting
    • Unit Conversion Tools
    • Fuel Management
    • Export for CFD
    • Developer Tools
  • Adding Custom Fuels
    • Directory Structure
    • Metadata Configuration
    • GCxGC Composition Data
    • Group Decomposition Data
    • Using Custom Fuels
    • Tips and Best Practices
  • Exporting Properties for Pele
    • Default Options
    • Additional Options
    • Liquid Species Deposit to Single Gas-Phase Species
    • Liquid Species Deposit to Specific Gas-Phase Species
    • Export Liquid Fuel as Single Mixture Species
    • Exporting Properties for the MP Model in Pele
  • Exporting Properties for Converge
    • Default Options
    • Additional Options
• Source Code
  • FuelLib File Organization
  • Public API
    • fuellib.fuel
      • fuel
    • fuellib.constants
      • N_A
      • k_B
    • fuellib.convert
      • C2F()
      • C2K()
      • F2C()
      • F2K()
      • K2C()
      • K2F()
      • epsilon_to_characteristic_temperature()
    • fuellib.utility
      • droplet_mass()
      • droplet_volume()
      • mixing_rule()
• Contributing to FuelLib
  • Development Setup
    • Optional: Conda Environment
  • Contributing Guidelines
  • Building and Viewing Documentation Locally

[1]

Leonidas Constantinou and Rafiqul Gani. New group contribution method for estimating properties of pure compounds. AIChE Journal, 40(10):1697–1710, October 1994. URL: https://aiche.onlinelibrary.wiley.com/doi/10.1002/aic.690401011 (visited on 2024-07-08), doi:10.1002/aic.690401011.

[2]

Leonidas Constantinou, Rafiqul Gani, and John P. O’Connell. Estimation of the acentric factor and the liquid molar volume at 298 K using a new group contribution method. Fluid Phase Equilibria, 103(1):11–22, January 1995. URL: https://linkinghub.elsevier.com/retrieve/pii/037838129402593P (visited on 2024-07-08), doi:10.1016/0378-3812(94)02593-P.

[3]

Pavan B. Govindaraju and Matthias Ihme. Group contribution method for multicomponent evaporation with application to transportation fuels. International Journal of Heat and Mass Transfer, 102:833–845, November 2016. URL: https://linkinghub.elsevier.com/retrieve/pii/S0017931016309887 (visited on 2024-07-01), doi:10.1016/j.ijheatmasstransfer.2016.06.079.