Tutorials

This section provides tutorials on how to use the FuelLib library.

Introduction

Clone the FuelLib repository from GitHub:

git clone https://github.com/NREL/FuelLib.git

Create and activate a Conda environment, install the required dependencies:

conda create --name fuellib-env matplotlib pandas scipy
conda activate fuellib-env

Change to the FuelLib/tutorials directory:

cd FuelLib/tutorials

Required Input files

FuelLib requires two input files for any given fuel, <fuel_name>:

• FuelLib/fuelData/gcData/<fuel_name>_init.csv: an initial weight percentage composition of the fuel components

• FuelLib/fuelData/groupDecompositionData/<fuel_name>.csv: the fundamental group decomposition for each component of the fuel

These files must have the same number of rows and the same order of components. Many examples can be found in the fuelData directory.

Basic Usage

To demonstrate the usage of FuelLib, we will use the fuel “heptane-decane”, which is a binary mixture of heptane and decane. The initial weight percentage composition is 73.75% heptane and 26.25% decane, and the group decomposition data is provided in the groupDecompositionData directory. The following tutorial is included in the FuelLib/tutorials as basic.py. To begin, we will import the necessary modules and create a groupContribution object for the two component fuel “heptane-decane”:

import os
import sys

# Add the FuelLib directory to the Python path
FUELLIB_DIR = os.path.dirname(os.path.dirname(__file__))
sys.path.append(FUELLIB_DIR)
import paths
import FuelLib as fl

# Create a fuel object for the fuel "heptane-decane"
fuel = fl.fuel("heptane-decane")

Upon initialization, the fuel object will read the initial weight percentage composition and group decomposition data from the specified files. The object stores vectors of the calculated fundamental properties at standard conditions for each component of the fuel as described in Equations for GCM properties. For example, we can display the fuel name, the components in the fuel, the initial composition, and the critical temperature for each component:

# Display fuel name, components, initial composition, and critical temperature
print(f"Fuel name: {fuel.name}")
print(f"Fuel components: {fuel.compounds}")
print(f"Initial composition: {fuel.Y_0}")
print(f"Critical temperature: {fuel.Tc} K")

>> Fuel name: heptane-decane
>> Fuel components: ['NC7H16', 'NC10H22']
>> Initial composition: [0.7375 0.2625]
>> Critical temperature: [549.85598051 623.69051582] K

Next, we can calculate any of the component- or mixture-level properties using the groupContribution object. For example, we can calculate the saturated vapor pressure for each component and the mixture at a given temperature:

# Calculate the saturated vapor pressure at 320 K
T = 320 # K
p_sat_i = fuel.psat(T)
p_sat_mix = fuel.mixture_vapor_pressure(T)
print(f"Saturated vapor pressure at {T} K: {p_sat_i} Pa")
print(f"Mixture saturated vapor pressure at {T} K: {p_sat_mix} Pa")

>> Saturated vapor pressure at 320 K: [13735.84605413   673.28876023] Pa
>> Mixture saturated vapor pressure at 320 K: 11117.84926875165 Pa

The following links provide more information on the Equations for individual compound correlations and the Equations for mixture properties from GCM that can be calculated using the groupContribution object.

Exporting GCM Properties for Pele

The development of FuelLib was motivated by the need for more accurate liquid fuel property prediction in computational fluid dynamics (CFD) simulations. The fundamental GCM properties can be exported for use in the spray module of the PelePhysics library[1] for combustion simulations in the PeleLMeX flow solver[2] [3].

The export script, Export4Pele.py, generates an input file named sprayPropsGCM_<fuel_name>.inp containing the necessary properties for each compound in the fuel. The properties are formatted for use in Pele and includes:

• Hydrocarbon family

• Molecular weight

• Critical temperature

• Critical pressure

• Critical volume

• Boiling point

• Accentric factor

• Molar volume

• Specific heat

• Latent heat of vaporization

Warning

The incorporation of the GCM in Pele is still under development and additional testing is required.

This example walks through the process and the available options for exporting GCM properties of a fuel named “heptane-decane”, which is a binary mixture of heptane and decane, using the Export4Pele.py script.

Default Options

Note

The units for PeleLMeX are MKS while the units for PeleC are CGS. This is the same for the spray inputs. Therefore, when running a spray simulation coupled with PeleC, the units for the liquid fuel properties must be in CGS. The default units for the Export4Pele.py script is MKS, but users can specify CGS by using the --units cgs option.

From the FuelLib directory, run the following command in the terminal, noting that --fuel_name is the only required input:

cd FuelLib/source
python Export4Pele.py --fuel_name heptane-decane

This generates the following input file, FuelLib/exportData/sprayPropsGCM_heptane-decane.inp, for use in a PeleLMeX simulation:

# -----------------------------------------------------------------------------
# Liquid fuel properties for GCM in Pele
# Fuel: heptane-decane
# Number of compounds: 2
# Generated: <YYY-MM-DD> <HH-MM-SS>
# FuelLib remote URL: https://github.com/NREL/FuelLib.git
# Git commit: <commit-hash>
# Units: MKS
# -----------------------------------------------------------------------------

particles.fuel_species = NC7H16 NC10H22
particles.Y_0 = 0.7375 0.2625
particles.dep_fuel_species = NC7H16 NC10H22

# Properties for NC7H16 in MKS
particles.NC7H16_family = 0 # saturated hydrocarbons
particles.NC7H16_molar_weight = 0.100000 # kg/mol
particles.NC7H16_crit_temp = 549.855981 # K
particles.NC7H16_crit_press = 2821129.514417 # Pa
particles.NC7H16_crit_vol = 0.000425 # m^3/mol
particles.NC7H16_boil_temp = 379.073212 # K
particles.NC7H16_acentric_factor = 0.336945 # -
particles.NC7H16_molar_vol = 0.000146 # m^3/mol
particles.NC7H16_cp_a = 1636.255000 # J/kg/K
particles.NC7H16_cp_b = 3046.511000 # J/kg/K
particles.NC7H16_cp_c = -983.629000 # J/kg/K
particles.NC7H16_latent = 383110.000000 # J/kg

# Properties for NC10H22 in MKS
particles.NC10H22_family = 0 # saturated hydrocarbons
particles.NC10H22_molar_weight = 0.142000 # kg/mol
particles.NC10H22_crit_temp = 623.690516 # K
particles.NC10H22_crit_press = 2115522.932445 # Pa
particles.NC10H22_crit_vol = 0.000592 # m^3/mol
particles.NC10H22_boil_temp = 452.596977 # K
particles.NC10H22_acentric_factor = 0.468050 # -
particles.NC10H22_molar_vol = 0.000196 # m^3/mol
particles.NC10H22_cp_a = 1630.488028 # J/kg/K
particles.NC10H22_cp_b = 3098.105634 # J/kg/K
particles.NC10H22_cp_c = -1024.456338 # J/kg/K
particles.NC10H22_latent = 368035.211268 # J/kg

To include these parameters in your Pele simulation, copy the sprayPropsGCM_heptane-decane.inp file to the specific case directory and include the following line in your Pele input file:

FILE = sprayPropsGCM_heptane-decane.inp

Note: for liquid fuels from FuelLib with greater than 30 components, the script will assume that all liquid fuel species deposit to the same gas-phase species, namely the name of the fuel. This is designed for conventional jet fuels such as POSF10325, where there are 67 liquid fuel species corresponding to the GCxGC data, but only a single gas-phase mechanism species, “POSF10325”. For example:

cd FuelLib/source
python Export4Pele.py --fuel_name posf10325

will result in the following:

particles.spray_fuel_num = 67
particles.fuel_species = Toluene C2-Benzene C3-Benzene ... C12-Tricycloparaffin
particles.Y_0 = 0.001610 0.011172 0.0304982 ... 0.00110719
particles.dep_fuel_names = POSF10325 POSF10325 ... POSF10325

# Properties for Toluene in MKS
...

Additional Options

There are four additional options that can be specified when running the export script:

• --units: Specify the units for the properties. The default is “mks” but users can set the units to “cgs” for use in PeleC.

• --dep_fuel_names: Specify which gas-phase species the liquid fuel deposits. The default is the same as the fuel name, but users can specify a single gas-phase species or a list of gas-phase species.

• --max_dep_fuels: Specify the maximum number of dependent fuels. The default is 30 and is a bit arbitrary.

• --export_dir: Specify the directory to export the file. The default is “FuelLib/exportData”.

To specify all liquid fuel species deposity to a single gas-phase species, run the following command:

cd FuelLib/source
python Export4Pele.py --fuel_name heptane-decane --dep_fuel_names SINGLE_GAS

This will result in the following:

particles.spray_fuel_num = 2
particles.fuel_species = NC7H16 NC10H22
particles.Y_0 = 0.7375 0.2625
particles.dep_fuel_names = SINGLE_GAS SINGLE_GAS

# Properties for NC7H16 in MKS
...

Alternatively, to specify a list of gas-phase species, run the following command:

python Export4Pele.py --fuel_name heptane-decane --dep_fuel_names GAS_1 GAS_2

which produces:

particles.spray_fuel_num = 2
particles.fuel_species = NC7H16 NC10H22
particles.Y_0 = 0.7375 0.2625
particles.dep_fuel_names = GAS_1 GAS_2

# Properties for NC7H16 in MKS
...

In the case that the liquid fuel has more than 30 components, the script will automatically set the deposition mapping to fuel.name for all components. If there are more than 30 components and the user wants each component to deposit to a gas-phase species of the same name, the user can increase --max_dep_fuels to a value greater than 30, however this would be required a massive mechanism for Pele and is not advised

cd FuelLib/source
python Export4Pele.py --fuel_name posf10325 --max_dep_fuels 67

Exporting GCM-Based Mixture Properties for Converge

The export script, Export4Converge.py, generates a csv file named mixturePropsGCM_<fuel_name>.csv containing mixture property predictions for a given fuel over a specified temperature range. The properties include:

• Critical temperature

• Dynamic viscosity

• Surface tension

• Latent heat of vaporization

• Vapor pressure

• Density

• Specific heat

• Thermal conductivity

Warning

Mixture properties for critical temperature, latent heat, and specific heat are provided by Conventional mixing rules and need additional validation.

This example walks through the process and the available options for exporting GCM-based mixture properties for “posf10325”, which is conventional Jet-A, using the Export4Converge.py script.

Default Options

From the FuelLib directory, run the following command in the terminal, noting that --fuel_name is the only required input:

cd FuelLib/source
python Export4Converge.py --fuel_name posf10325

This generates the file FuelLib/exportData/mixturePropsGCM_posf10325.csv with mixture property predictions from 0 K to 1000 K for use in a Converge simulation.

Additional Options

There are four additional options that can be specified when running the export script:

• --units: Specify the units for the mixture properties. The default is “mks” but users can set the units to “cgs”.

• --temp_min: Specify the minimum temperature. The default is 0 K.

• --temp_max: Specify the maximum temperature. The default is 1000 K.

• --temp_step: Specify the temperature step size. The default is \(\Delta T = 10\) K.

• --export_dir: Specify the directory to export the file. The default is “FuelLib/exportData”.

Note

The mixture property predictions may not be valid from the specified temp_min to temp_max, as the mixture properties are based on the GCM properties and correlations of the individual components. Constant values are set for temperatures below the freezing point of the mixture or above the minimum critical temperature of all compounds in the fuel. These temperature values will be noted in the terminal output and should be considered when using the mixture properties in a simulation.

[1]

Landon D. Owen, Wenjun Ge, Martin Rieth, Marco Arienti, Lucas Esclapez, Bruno S. Soriano, Michael E. Mueller, Marcus Day, Ramanan Sankaran, and Jacqueline H. Chen. PeleMP: The Multiphysics Solver for the Combustion Pele Adaptive Mesh Refinement Code Suite. Journal of Fluids Engineering, 146(4):041103, April 2024. URL: https://asmedigitalcollection.asme.org/fluidsengineering/article/146/4/041103/1194173/PeleMP-The-Multiphysics-Solver-for-the-Combustion (visited on 2024-10-29), doi:10.1115/1.4064494.

[2]

Marc T. Henry de Frahan, Lucas Esclapez, Jon Rood, Nicolas T. Wimer, Paul Mullowney, Bruce A. Perry, Landon Owen, Hariswaran Sitaraman, Shashank Yellapantula, Malik Hassanaly, Mohammad J. Rahimi, Michael J. Martin, Olga A. Doronina, Sreejith Nadakkal Appukuttan, Martin Rieth, Ge Wenjun, Ramanan Sankaran, Ann S. Almgren, Weiqun Zhang, John B. Bell, Ray Grout, Marc S. Day, and Jacqueline H. Chen. The Pele Simulation Suite for Reacting Flows at Exascale. In Proceedings of the 2024 SIAM Conference on Parallel Processing for Scientific Computing (PP), 13–25. Philadelphia, PA, January 2024. Society for Industrial and Applied Mathematics. URL: https://epubs.siam.org/doi/book/10.1137/1.9781611977967 (visited on 2024-06-26), doi:10.1137/1.9781611977967.2.

[3]

Lucas Esclapez, Marc Day, John Bell, Anne Felden, Candace Gilet, Ray Grout, Marc Henry De Frahan, Emmanuel Motheau, Andrew Nonaka, Landon Owen, Bruce Perry, Jon Rood, Nicolas Wimer, and Weiqun Zhang. PeleLMeX: an AMR Low Mach Number Reactive FlowSimulation Code without level sub-cycling. Journal of Open Source Software, 8(90):5450, October 2023. URL: https://joss.theoj.org/papers/10.21105/joss.05450 (visited on 2024-06-26), doi:10.21105/joss.05450.