Combustion Fuels

Overview

Introduction Combustion fuel analysis is the applied thermochemical framework used to quantify how fuels react with oxidizers, how much air is required, what products form, and how much energy is released. In engineering terms, this category links three tightly connected decisions: reaction balancing (stoichiometry), operating conditions (air-fuel ratio and oxygen excess), and fuel quality/performance metrics (heating values and octane numbers). Together, these calculations support boiler design, burner tuning, flare operation, emissions accounting, safety screening, and fuel blending strategy.

At a high level, combustion modeling starts with elemental conservation. Carbon tends to leave as CO2, hydrogen as H2O, sulfur as SO2, and inert species such as N2 mostly pass through unchanged under complete-combustion assumptions. The amount of oxygen needed is set by chemistry; the amount of oxygen supplied is set by process design and controls. The difference between the two appears as excess O2 in flue gas, which is both an operations KPI and an efficiency lever.

This category is built around the chemicals.combustion module from the Chemical Engineering Design Library (ChEDL) chemicals package, with wrappers that expose spreadsheet-friendly workflows. The category includes AIR_FUEL_RATIO, COMBUSTION_STOICH, FUEL_AIR_SPEC, HHV_STOICHIOMETRY, LHV_FROM_HHV, IS_COMBUSTIBLE, MON, and RON. These tools are complementary rather than redundant: some are equation solvers, some are thermochemistry evaluators, and some are property lookups.

For deeper background, canonical references include combustion, air%E2%80%93fuel ratio, heat of combustion, and octane rating. Boardflare’s value is that it operationalizes these concepts into auditable, reusable calculations that can be called consistently from Excel-like workflows and Python-backed calculators.

When to Use It Use this category when the job to be done is not simply “compute a formula,” but “make a defendable combustion decision” under practical constraints such as incomplete fuel characterization, changing feed composition, stack O2 limits, or product specification targets.

A common use case is burner and boiler tuning in process plants. Operations teams often measure dry O2 in flue gas and need to infer whether current firing is near target excess-air levels. In that workflow, FUEL_AIR_SPEC is typically the central solver because it can reconcile different known variables (air flow, fuel flow, outlet O2 fraction, oxygen excess, or ratio basis) into a consistent material-balance picture. AIR_FUEL_RATIO then provides quick what-if conversions among mole-, mass-, and volume-based ratios for controls and reporting systems that use different conventions.

A second use case is fuel qualification and safety screening for new feedstocks, off-spec streams, or blended fuels. Before detailed heat-release studies, teams first need a fast binary check: does this substance qualify as combustible in the current model context? IS_COMBUSTIBLE addresses that triage task with CAS-plus-composition logic. Once combustible behavior is confirmed, COMBUSTION_STOICH gives theoretical product coefficients for complete combustion, creating the basis for oxygen demand and emissions-factor calculations.

A third use case is energy accounting and commercial valuation. For procurement, utility planning, and performance guarantees, users frequently need to move between HHV and LHV conventions. HHV_STOICHIOMETRY estimates higher heating value from stoichiometry plus heats of formation, while LHV_FROM_HHV adjusts HHV to LHV using the number of water molecules formed. This is critical when contracts specify one basis and equipment guarantees use another.

A fourth use case is spark-ignition fuel blending and specification control. Gasoline and oxygenated blendstocks are often screened by octane metrics. RON and MON return reference octane values by CASRN, enabling rapid comparisons across candidate components. When combined with stoichiometric and heating-value tools, they support a broader multi-objective evaluation: knock resistance, required air supply, and thermal yield.

Two detailed scenario patterns illustrate how these calculators solve real problems:

  1. Plant retrofit with new fuel blend: An engineer receives a revised fuel gas composition after upstream debottlenecking. They use COMBUSTION_STOICH to establish baseline oxygen demand, FUEL_AIR_SPEC to compute required air and expected outlet O2 under operating constraints, and AIR_FUEL_RATIO to publish equivalent control ratios for DCS tags configured on mass basis.

  2. Commercial and performance reconciliation: A contracts analyst receives supplier HHV values while turbine vendor data is in LHV. They use LHV_FROM_HHV for direct conversion, cross-check reasonableness with HHV_STOICHIOMETRY where composition and formation data are available, and document assumptions explicitly for audit and settlement.

  3. Gasoline component selection: A fuels team compares candidate oxygenates and hydrocarbons by anti-knock quality using RON and MON. They then evaluate whether stoichiometric combustion implications and energy basis shifts are acceptable with COMBUSTION_STOICH and LHV_FROM_HHV, ensuring blend decisions are not made on octane alone.

How It Works The underlying mechanics combine elemental balances, ratio transformations, and thermochemical state functions. Under complete-combustion assumptions, each element is conserved across reactants and products. For a generic fuel molecule C_xH_yO_zS_w, the idealized oxygen requirement for complete combustion is:

\nu_{O_2,\,stoich} = x + \frac{y}{4} - \frac{z}{2} + w

with product tendencies:

C_xH_yO_zS_w + \nu_{O_2} O_2 \rightarrow x\,CO_2 + \frac{y}{2}H_2O + w\,SO_2

In multi-component fuels and oxidizer streams, the same idea applies component-wise and is summed over molar flows. COMBUSTION_STOICH handles this at the species level from an atoms dictionary, returning stoichiometric coefficients that can be reused in downstream energy and balance calculations.

Air-fuel ratios are usually expressed on different bases depending on domain:

\left(\frac{A}{F}\right)_{mole} = \frac{n_{air}}{n_{fuel}},\quad \left(\frac{A}{F}\right)_{mass} = \frac{n_{air}MW_{air}}{n_{fuel}MW_{fuel}},\quad \left(\frac{A}{F}\right)_{vol} = \frac{n_{air}V_{m,air}}{n_{fuel}V_{m,fuel}}

AIR_FUEL_RATIO solves for missing flow terms and reports all ratio bases consistently. This is valuable in organizations where process control tags are molar, compliance reports are mass-based, and test procedures are volumetric.

FUEL_AIR_SPEC generalizes the same relationships into a constrained system solver for combustion with known feed compositions (zs_air, zs_fuel) and species metadata (CASs, atomss). It allows multiple problem formulations: known fuel flow with target oxygen excess, known outlet oxygen fraction with unknown air flow, known ratio basis with unknown product flow, and similar variants. Conceptually, it enforces:

ext{Elemental balances} + \text{composition constraints} + \text{chosen operating specification(s)}

to produce a self-consistent set of outputs such as n_{air}, n_{out}, z_{O_2,out}, dry oxygen fraction, and derived ratios.

Oxygen excess is often reported as a normalized deviation from theoretical oxygen demand:

ext{Excess O}_2 = \frac{O_{2,\,supplied} - O_{2,\,stoich}}{O_{2,\,stoich}}

which links directly to efficiency and emissions behavior in real systems. High excess air can reduce CO risk but generally increases sensible heat loss in flue gas.

Heating-value functions in this category rely on reaction enthalpy. In sign convention terms used by many thermochemical libraries, combustion enthalpy is negative (exothermic). HHV_STOICHIOMETRY computes higher heating value from stoichiometry and heats of formation, effectively applying a Hess’s-law balance:

\Delta H_{rxn} = \sum_i \nu_i \Delta H_{f,i}^{\circ}

with product/reference-state choices corresponding to HHV conventions (including liquid-water recovery effect). LHV_FROM_HHV then removes the latent heat associated with water condensation by using the number of water molecules formed per mole of fuel burned:

LHV \approx HHV + N_{H_2O}\,\Delta H_{vap,H_2O}

where \Delta H_{vap,H_2O} is negative under the combustion sign convention in many datasets, so LHV is typically less exothermic in magnitude than HHV.

The property-lookup tools RON and MON are data-driven rather than balance-solvers. They map CASRNs to octane metrics and optionally allow method selection when multiple data sources exist. Their practical interpretation is tied to engine test standards: RON reflects milder test conditions than MON, so MON is usually lower. The sensitivity metric,

S = RON - MON

is often used to characterize knock behavior across operating regimes.

Finally, IS_COMBUSTIBLE provides rule-based screening to identify compounds treated as combustible in the library context, helping users avoid nonsensical stoichiometric or heating-value calculations on known non-combustibles.

All of these computations depend on assumptions that should be explicit in engineering documentation:

  • Complete combustion unless otherwise modeled.
  • Correct and normalized composition inputs.
  • Consistent units for molar volume, molecular weight, and flow rates.
  • Appropriate reference states for thermochemical properties.
  • Applicability limits of lookup datasets (especially octane values).

When these assumptions are respected, the category supports robust first-principles screening and operations-grade what-if analysis.

Practical Example Consider a chemical plant furnace transitioning from a legacy methane-rich fuel to a mixed fuel gas containing methane, ethane, propane, trace CO2, and water. The operations objective is to maintain throughput while keeping dry flue oxygen near a target and preserving a safety margin against incomplete combustion.

Step 1 is combustibility validation. Before sizing or tuning, the team checks key fuel components with IS_COMBUSTIBLE, using CAS and atomic composition metadata from the plant historian. This does not replace hazard review, but it flags whether modeled species are treated as burnable in the computational framework.

Step 2 is theoretical stoichiometry setup. For each combustible species (or for an effective blend), COMBUSTION_STOICH yields stoichiometric coefficients. This creates a transparent oxygen-demand baseline and expected product slate for complete combustion. At this stage, analysts can also sanity-check that carbon and hydrogen balances are physically reasonable.

Step 3 is operating-point solving. The team now applies FUEL_AIR_SPEC with known fuel composition and flow, known air composition, and a target oxygen excess or target dry outlet oxygen fraction. The solver returns air demand, outlet flow, and product composition estimates. This is the key move from chemistry to operations because it translates molecular-level constraints into controllable plant variables.

Step 4 is ratio translation for controls and reporting. Suppose control engineers use mass-based air-fuel ratio in the DCS, while laboratory protocols use mole basis. AIR_FUEL_RATIO converts and reconciles these viewpoints from the same underlying flows and property inputs (MW_air, MW_fuel, Vm_air, Vm_fuel). This avoids recurring confusion where teams compare ratios that are numerically different but physically equivalent under different bases.

Step 5 is energy basis reconciliation. Commercial fuel data arrives as HHV, but turbine and efficiency benchmarks in the plant are LHV-based. The analyst can calculate HHV from chemistry using HHV_STOICHIOMETRY when formation data is available, then convert to LHV via LHV_FROM_HHV using water-formation stoichiometry. This produces a consistent energy basis for KPI dashboards and contractual reporting.

Step 6 is spark-ignition blend screening (if relevant). If part of the site also formulates fuel blends for SI engines or generators, RON and MON are used to compare candidate components by knock resistance. These values are not substitutes for full blend-octane modeling, but they provide a fast first-pass filter for component selection.

In spreadsheet terms, this full workflow is significantly more reliable than ad hoc manual balancing because each stage is explicit and machine-reproducible. Instead of hard-coded stoichiometric coefficients and copied formulas scattered across worksheets, the Boardflare functions centralize assumptions and return structured outputs. That improves auditability, speeds troubleshooting when feed composition changes, and reduces the risk of basis-mismatch errors that commonly appear in hand-built combustion models.

How to Choose The most reliable way to choose among these calculators is to start from the decision question, not the available inputs. The table below provides a practical selection map.

Decision question Primary tool Typical inputs Main output Strengths Limits
Is this species treated as combustible in the model? IS_COMBUSTIBLE CAS, atoms, reactive flag Boolean Fast screening, prevents invalid downstream calculations Binary screening only; not a hazard or kinetics model
What is the complete-combustion stoichiometry from composition? COMBUSTION_STOICH Atoms dict, optional MW handling Product/reactant coefficients Transparent elemental balance basis Product assumptions may not represent unusual inorganic pathways
I know ratio and one flow; what is the other flow and equivalent ratio bases? AIR_FUEL_RATIO Ratio, one of n_air/n_fuel, MW and/or Vm data Missing flow and ratios on mole/mass/volume bases Excellent for controls/reporting basis conversion Requires consistent basis data; not a full combustion products solver
I need a full solved combustion operating point with multiple specification options FUEL_AIR_SPEC Air/fuel compositions, species metadata, one or more specs (e.g., O2 excess, outlet O2, ratio) Air flow, outlet flow/composition, oxygen metrics, ratios Most comprehensive workflow tool in category Input setup is heavier and requires consistent species lists
What is HHV from stoichiometry and heats of formation? HHV_STOICHIOMETRY Stoichiometric coefficients, fuel and species formation enthalpies HHV Thermochemically grounded via Hess’s law Sensitive to property-data quality and reference states
I have HHV and water stoichiometry; need LHV LHV_FROM_HHV HHV, number of H2O molecules formed LHV Fast conversion for reporting/contracts Assumes valid HHV input and correct water stoichiometry
What is the knock-resistance metric by CAS for SI fuels? RON CASRN, optional method Research octane number Simple property retrieval for blend screening Lookup availability varies by chemical
What is MON for the same purpose under more severe test conditions? MON CASRN, optional method Motor octane number Complements RON; supports sensitivity analysis Lookup availability varies; not a complete engine model

The following decision flow is useful in day-to-day engineering work:

graph TD
    A[Start with your problem] --> B{Need fuel property lookup only?}
    B -- Yes --> C{Octane property?}
    C -- RON --> D[Use RON]
    C -- MON --> E[Use MON]
    B -- No --> F{Need combustion feasibility screen?}
    F -- Yes --> G[Use IS_COMBUSTIBLE]
    F -- No --> H{Need stoichiometric reaction coefficients?}
    H -- Yes --> I[Use COMBUSTION_STOICH]
    H -- No --> J{Need full operating-point solve with outlet O2 or excess-air constraints?}
    J -- Yes --> K[Use FUEL_AIR_SPEC]
    J -- No --> L{Need only ratio and missing air/fuel flow conversion?}
    L -- Yes --> M[Use AIR_FUEL_RATIO]
    L -- No --> N{Need heating-value work?}
    N -- HHV from chemistry --> O[Use HHV_STOICHIOMETRY]
    N -- LHV from HHV --> P[Use LHV_FROM_HHV]

A practical rule set for ambiguous cases:

  • If outlet oxygen or excess oxygen appears in the requirement, default to FUEL_AIR_SPEC.
  • If the requirement is “convert or reconcile ratio basis,” default to AIR_FUEL_RATIO.
  • If only elemental composition is available and no flow data yet, start with COMBUSTION_STOICH.
  • If energy basis conversion is the only deliverable, LHV_FROM_HHV is usually sufficient; escalate to HHV_STOICHIOMETRY when HHV itself must be derived from chemistry.
  • If evaluating SI fuel anti-knock quality, retrieve both RON and MON, then evaluate sensitivity S=RON-MON for a fuller view.

In summary, this category is most effective when used as a pipeline: screen combustibility, establish stoichiometry, solve operating constraints, then compute energy and quality metrics appropriate to the business decision. That staged approach reduces model ambiguity, keeps assumptions explicit, and aligns engineering calculations with contractual and operational reporting needs.

AIR_FUEL_RATIO

This function solves for the air or fuel molar flow rate when an air-fuel ratio is known on a mole, mass, or volume basis. In addition to the missing flow rate, it also reports the equivalent ratio expressed in all three bases so the result can be compared across operating conventions.

The three ratio definitions are:

AFR_{mole} = \frac{n_{air}}{n_{fuel}}, \qquad AFR_{mass} = \frac{n_{air} MW_{air}}{n_{fuel} MW_{fuel}}, \qquad AFR_{volume} = \frac{n_{air} V_{m,air}}{n_{fuel} V_{m,fuel}}

All supplied quantities must use a consistent basis. For example, the mass ratio should be supplied as mass per mass, and the molar volumes should correspond to the same reference conditions if a volume-based ratio is used.

Excel Usage

=AIR_FUEL_RATIO(Vm_air, Vm_fuel, MW_air, MW_fuel, ratio, n_air, n_fuel, basis)
  • Vm_air (float, required): Molar volume of air [m^3/mol].
  • Vm_fuel (float, required): Molar volume of fuel [m^3/mol].
  • MW_air (float, required): Molecular weight of air [g/mol].
  • MW_fuel (float, required): Molecular weight of fuel [g/mol].
  • ratio (float, optional, default: null): Air-fuel ratio, in the specified basis.
  • n_air (float, optional, default: null): Molar flow rate of air [mol/s].
  • n_fuel (float, optional, default: null): Molar flow rate of fuel [mol/s].
  • basis (str, optional, default: “mass”): Basis of ratio (‘mass’, ‘mole’, or ‘volume’).

Returns (str): JSON string of n_air, n_fuel, mole_ratio, mass_ratio, volume_ratio.

Example 1: Air to fuel ratio by mole

Inputs:

Vm_air Vm_fuel MW_air MW_fuel ratio n_air n_fuel basis
0.02493 0.02488 28.85 17.86 5 5 mole

Excel formula:

=AIR_FUEL_RATIO(0.02493, 0.02488, 28.85, 17.86, 5, , 5, "mole")

Expected output:

"{\"n_air\": 25, \"n_fuel\": 5, \"mole_ratio\": 5.0, \"mass_ratio\": 8.076707726763718, \"volume_ratio\": 5.010048231511254}"

Example 2: Air to fuel ratio by mass

Inputs:

Vm_air Vm_fuel MW_air MW_fuel ratio n_air n_fuel basis
0.02493 0.02488 28.85 17.86 17.2 53.30051993067591 5 mass

Excel formula:

=AIR_FUEL_RATIO(0.02493, 0.02488, 28.85, 17.86, 17.2, 53.30051993067591, 5, "mass")

Expected output:

"{\"n_air\": 53.30051993067591, \"n_fuel\": 5, \"mole_ratio\": 10.660103986135182, \"mass_ratio\": 17.21970884658455, \"volume_ratio\": 10.681527024692526}"

Example 3: Solve fuel flow from air flow with volume ratio

Inputs:

Vm_air Vm_fuel MW_air MW_fuel ratio n_air basis
0.02493 0.02488 28.85 17.86 10 20 volume

Excel formula:

=AIR_FUEL_RATIO(0.02493, 0.02488, 28.85, 17.86, 10, 20, "volume")

Expected output:

"{\"n_air\": 20, \"n_fuel\": 2.0040192926045015, \"mole_ratio\": 9.979943842759727, \"mass_ratio\": 16.1210179094971, \"volume_ratio\": 10.0}"

Python Code

Show Code 
import json
from chemicals.combustion import air_fuel_ratio_solver

def air_fuel_ratio(Vm_air, Vm_fuel, MW_air, MW_fuel, ratio=None, n_air=None, n_fuel=None, basis='mass'):
    """
    Calculates molar flow rate of air or fuel from the other, using a specified air-fuel ratio.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        Vm_air (float): Molar volume of air [m^3/mol].
        Vm_fuel (float): Molar volume of fuel [m^3/mol].
        MW_air (float): Molecular weight of air [g/mol].
        MW_fuel (float): Molecular weight of fuel [g/mol].
        ratio (float, optional): Air-fuel ratio, in the specified basis. Default is None.
        n_air (float, optional): Molar flow rate of air [mol/s]. Default is None.
        n_fuel (float, optional): Molar flow rate of fuel [mol/s]. Default is None.
        basis (str, optional): Basis of ratio ('mass', 'mole', or 'volume'). Valid options: Mass, Mole, Volume. Default is 'mass'.

    Returns:
        str: JSON string of n_air, n_fuel, mole_ratio, mass_ratio, volume_ratio.
    """
    try:
        res = air_fuel_ratio_solver(ratio=ratio, Vm_air=Vm_air, Vm_fuel=Vm_fuel, MW_air=MW_air, MW_fuel=MW_fuel, n_air=n_air, n_fuel=n_fuel, basis=(basis if basis else 'mass'))
        names = ["n_air", "n_fuel", "mole_ratio", "mass_ratio", "volume_ratio"]
        return json.dumps(dict(zip(names, res)))
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

Molar volume of air [m^3/mol].
Molar volume of fuel [m^3/mol].
Molecular weight of air [g/mol].
Molecular weight of fuel [g/mol].
Air-fuel ratio, in the specified basis.
Molar flow rate of air [mol/s].
Molar flow rate of fuel [mol/s].
Basis of ratio ('mass', 'mole', or 'volume').

COMBUSTION_STOICH

This function constructs the ideal complete-combustion stoichiometry for a compound from its elemental composition. The returned dictionary contains product coefficients together with a negative oxygen coefficient, where a negative value indicates the amount of oxygen required per mole of fuel.

For a compound with elemental counts C_cH_hO_oN_nS_sBr_bI_iCl_xF_fP_p, the oxygen requirement is computed from:

k = c + s + \frac{h}{4} + \frac{5p}{4} - \frac{x + f}{4} - \frac{o}{2}

The result is intended for complete combustion calculations of typical fuels. Elements outside the standard combustion products can be returned in elemental form or lumped into ash, depending on the selected missing-atom handling rule.

Excel Usage

=COMBUSTION_STOICH(atoms, MW, missing_handling)
  • atoms (str, required): Dictionary of atoms and their counts.
  • MW (float, optional, default: null): Molecular weight of chemical, used only if missing_handling is ‘ash’ [g/mol].
  • missing_handling (str, optional, default: “elemental”): How to handle compounds which do not appear in the stoichiometric reaction.

Returns (str): Stoichiometric coefficients of combustion representation.

Example 1: Methane combustion

Inputs:

atoms
{“C”: 1, “H”: 4}

Excel formula:

=COMBUSTION_STOICH("{"C": 1, "H": 4}")

Expected output:

"{\"CO2\": 1, \"H2O\": 2.0, \"O2\": -2.0}"

Example 2: Ethanol combustion with oxygen in the fuel

Inputs:

atoms
{“C”: 2, “H”: 6, “O”: 1}

Excel formula:

=COMBUSTION_STOICH("{"C": 2, "H": 6, "O": 1}")

Expected output:

"{\"CO2\": 2, \"H2O\": 3.0, \"O2\": -3.0}"

Example 3: Sulfur-containing fuel stoichiometry

Inputs:

atoms
{“C”: 1, “H”: 4, “S”: 1}

Excel formula:

=COMBUSTION_STOICH("{"C": 1, "H": 4, "S": 1}")

Expected output:

"{\"CO2\": 1, \"H2O\": 2.0, \"O2\": -3.0, \"SO2\": 1}"

Example 4: Unknown atoms can be lumped into ash

Inputs:

atoms MW missing_handling
{“C”: 1, “H”: 4, “Na”: 1} 39 ash

Excel formula:

=COMBUSTION_STOICH("{"C": 1, "H": 4, "Na": 1}", 39, "ash")

Expected output:

"{\"Ash\": 22.95754, \"CO2\": 1, \"H2O\": 2.0, \"O2\": -2.0}"

Python Code

Show Code 
import json
from chemicals.combustion import combustion_stoichiometry

def combustion_stoich(atoms, MW=None, missing_handling='elemental'):
    """
    Returns a dictionary of stoichiometric coefficients of chemical combustion from an atoms dictionary.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        atoms (str): Dictionary of atoms and their counts.
        MW (float, optional): Molecular weight of chemical, used only if missing_handling is 'ash' [g/mol]. Default is None.
        missing_handling (str, optional): How to handle compounds which do not appear in the stoichiometric reaction. Valid options: Elemental, Ash. Default is 'elemental'.

    Returns:
        str: Stoichiometric coefficients of combustion representation.
    """
    try:
        if isinstance(atoms, str):
            atoms = json.loads(atoms)
        res = combustion_stoichiometry(atoms, MW, missing_handling)
        return json.dumps(res, sort_keys=True)
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

Dictionary of atoms and their counts.
Molecular weight of chemical, used only if missing_handling is 'ash' [g/mol].
How to handle compounds which do not appear in the stoichiometric reaction.

FUEL_AIR_SPEC

This function solves a complete-combustion mixing problem for an air stream and a fuel stream, returning the solved inlet and outlet flow quantities together with air-fuel ratios and product compositions. It can solve from any two extensive variables, or from one extensive variable and one intensive specification such as excess oxygen or outlet oxygen fraction.

A central intensive relation used by the solver is the excess-oxygen definition:

O_{2,excess} = \frac{n_{O_2,in}}{n_{O_2,required}} - 1

The output dictionary includes total outlet flow, wet and dry oxygen fractions, all three air-fuel ratio bases, and the component-wise outlet mole flows and mole fractions. This makes the wrapper suitable for burner sizing, flue-gas analysis, and fuel-comparison workflows.

Excel Usage

=FUEL_AIR_SPEC(zs_air, zs_fuel, CASs, atomss, n_fuel, n_air, n_out, Oxy_excess, frac_out_Oxy, frac_out_Oxy_dry, ratio, Vm_air, Vm_fuel, MW_air, MW_fuel, ratio_basis, reactivities, combustion_stoichiometries)
  • zs_air (str, required): Mole fractions of the air in JSON array format.
  • zs_fuel (str, required): Mole fractions of the fuel in JSON array format.
  • CASs (str, required): CAS numbers of all compounds in JSON array format.
  • atomss (str, required): List of dictionaries of elements and their counts for all molecules in JSON array format.
  • n_fuel (float, optional, default: null): Flow rate of fuel [mol/s].
  • n_air (float, optional, default: null): Flow rate of air [mol/s].
  • n_out (float, optional, default: null): Flow rate of combustion products, remaining oxygen, and inerts [mol/s].
  • Oxy_excess (float, optional, default: null): The excess oxygen coming out.
  • frac_out_Oxy (float, optional, default: null): The mole fraction of oxygen out.
  • frac_out_Oxy_dry (float, optional, default: null): The mole fraction of oxygen out on a dry basis.
  • ratio (float, optional, default: null): Air-fuel ratio, in the specified basis.
  • Vm_air (float, optional, default: null): Molar volume of air [m^3/mol].
  • Vm_fuel (float, optional, default: null): Molar volume of fuel [m^3/mol].
  • MW_air (float, optional, default: null): Molecular weight of air [g/mol].
  • MW_fuel (float, optional, default: null): Molecular weight of fuel [g/mol].
  • ratio_basis (str, optional, default: “mass”): One of ‘mass’, ‘mole’, or ‘volume’.
  • reactivities (str, optional, default: null): Optional JSON array of booleans marking combustible species to leave unreacted.
  • combustion_stoichiometries (str, optional, default: null): Optional JSON array of precomputed combustion stoichiometry dictionaries.

Returns (str): JSON Dictionary of all calculated variables.

Example 1: Fuel air mixture specs with excess O2

Inputs:

zs_air zs_fuel CASs atomss n_fuel Oxy_excess Vm_air Vm_fuel MW_air MW_fuel ratio_basis
[0.79, 0.205, 0, 0, 0, 0.0045, 0.0005] [0.025, 0.025, 0.85, 0.07, 0.029, 0.0005, 0.0005] [“7727-37-9”, “7782-44-7”, “74-82-8”, “74-84-0”, “74-98-6”, “7732-18-5”, “124-38-9”] [{“N”: 2}, {“O”: 2}, {“H”: 4, “C”: 1}, {“H”: 6, “C”: 2}, {“H”: 8, “C”: 3}, {“H”: 2, “O”: 1}, {“C”: 1, “O”: 2}] 5 0.3 0.02493 0.02488 28.793 18.551 mass

Excel formula:

=FUEL_AIR_SPEC("[0.79, 0.205, 0, 0, 0, 0.0045, 0.0005]", "[0.025, 0.025, 0.85, 0.07, 0.029, 0.0005, 0.0005]", "["7727-37-9", "7782-44-7", "74-82-8", "74-84-0", "74-98-6", "7732-18-5", "124-38-9"]", "[{"N": 2}, {"O": 2}, {"H": 4, "C": 1}, {"H": 6, "C": 2}, {"H": 8, "C": 3}, {"H": 2, "O": 1}, {"C": 1, "O": 2}]", 5, 0.3, 0.02493, 0.02488, 28.793, 18.551, "mass")

Expected output:

"{\"O2_excess\": 0.3000000000000005, \"frac_out_O2\": 0.04416828172034147, \"frac_out_O2_dry\": 0.051774902132806985, \"mass_ratio\": 20.381717900948086, \"mole_ratio\": 13.131707317073175, \"n_air\": 65.65853658536588, \"n_fuel\": 5, \"n_out\": 70.97853658536589, \"ns_out\": [51.99524390243905, 3.1350000000000042, 0.0, 0.0, 0.0, 10.427963414634148, 5.420329268292683], \"volume_ratio\": 13.15809740412517, \"zs_out\": [0.7325488296015285, 0.04416828172034147, 0.0, 0.0, 0.0, 0.14691713743763138, 0.07636575124049863]}"

Example 2: Fuel air specification from ratio on a mass basis

Inputs:

zs_air zs_fuel CASs atomss n_fuel ratio Vm_air Vm_fuel MW_air MW_fuel ratio_basis
[0.79, 0.205, 0, 0, 0, 0.0045, 0.0005] [0.025, 0.025, 0.85, 0.07, 0.029, 0.0005, 0.0005] [“7727-37-9”, “7782-44-7”, “74-82-8”, “74-84-0”, “74-98-6”, “7732-18-5”, “124-38-9”] [{“N”: 2}, {“O”: 2}, {“H”: 4, “C”: 1}, {“H”: 6, “C”: 2}, {“H”: 8, “C”: 3}, {“H”: 2, “O”: 1}, {“C”: 1, “O”: 2}] 5 20.381717900948086 0.02493 0.02488 28.793 18.551 mass

Excel formula:

=FUEL_AIR_SPEC("[0.79, 0.205, 0, 0, 0, 0.0045, 0.0005]", "[0.025, 0.025, 0.85, 0.07, 0.029, 0.0005, 0.0005]", "["7727-37-9", "7782-44-7", "74-82-8", "74-84-0", "74-98-6", "7732-18-5", "124-38-9"]", "[{"N": 2}, {"O": 2}, {"H": 4, "C": 1}, {"H": 6, "C": 2}, {"H": 8, "C": 3}, {"H": 2, "O": 1}, {"C": 1, "O": 2}]", 5, 20.381717900948086, 0.02493, 0.02488, 28.793, 18.551, "mass")

Expected output:

"{\"O2_excess\": 0.3000000000000005, \"frac_out_O2\": 0.04416828172034147, \"frac_out_O2_dry\": 0.051774902132806985, \"mass_ratio\": 20.381717900948086, \"mole_ratio\": 13.131707317073175, \"n_air\": 65.65853658536588, \"n_fuel\": 5, \"n_out\": 70.97853658536589, \"ns_out\": [51.99524390243905, 3.1350000000000042, 0.0, 0.0, 0.0, 10.427963414634148, 5.420329268292683], \"volume_ratio\": 13.15809740412517, \"zs_out\": [0.7325488296015285, 0.04416828172034147, 0.0, 0.0, 0.0, 0.14691713743763138, 0.07636575124049863]}"

Example 3: Leave methane unreacted with reactivities override

Inputs:

zs_air zs_fuel CASs atomss n_fuel Oxy_excess Vm_air Vm_fuel MW_air MW_fuel ratio_basis reactivities
[0.79, 0.205, 0, 0, 0, 0.0045, 0.0005] [0.025, 0.025, 0.85, 0.07, 0.029, 0.0005, 0.0005] [“7727-37-9”, “7782-44-7”, “74-82-8”, “74-84-0”, “74-98-6”, “7732-18-5”, “124-38-9”] [{“N”: 2}, {“O”: 2}, {“H”: 4, “C”: 1}, {“H”: 6, “C”: 2}, {“H”: 8, “C”: 3}, {“H”: 2, “O”: 1}, {“C”: 1, “O”: 2}] 5 0.3 0.02493 0.02488 28.793 18.551 mass [true, true, false, true, true, true, true]

Excel formula:

=FUEL_AIR_SPEC("[0.79, 0.205, 0, 0, 0, 0.0045, 0.0005]", "[0.025, 0.025, 0.85, 0.07, 0.029, 0.0005, 0.0005]", "["7727-37-9", "7782-44-7", "74-82-8", "74-84-0", "74-98-6", "7732-18-5", "124-38-9"]", "[{"N": 2}, {"O": 2}, {"H": 4, "C": 1}, {"H": 6, "C": 2}, {"H": 8, "C": 3}, {"H": 2, "O": 1}, {"C": 1, "O": 2}]", 5, 0.3, 0.02493, 0.02488, 28.793, 18.551, "mass", "[true, true, false, true, true, true, true]")

Expected output:

"{\"O2_excess\": 0.30000000000000004, \"frac_out_O2\": 0.03425841284351253, \"frac_out_O2_dry\": 0.03800997910520847, \"mass_ratio\": 3.6493269049988766, \"mole_ratio\": 2.3512195121951223, \"n_air\": 11.756097560975611, \"n_fuel\": 5, \"n_out\": 17.07609756097561, \"ns_out\": [9.412317073170733, 0.585, 4.25, 0.0, 0.0, 1.6854024390243905, 1.143378048780488], \"volume_ratio\": 2.355944631793585, \"zs_out\": [0.551198365994401, 0.03425841284351253, 0.24888590527338167, 0.0, 0.0, 0.09869950865565903, 0.06695780723304577]}"

Python Code

Show Code 
import json
from chemicals.combustion import fuel_air_spec_solver

def fuel_air_spec(zs_air, zs_fuel, CASs, atomss, n_fuel=None, n_air=None, n_out=None, Oxy_excess=None, frac_out_Oxy=None, frac_out_Oxy_dry=None, ratio=None, Vm_air=None, Vm_fuel=None, MW_air=None, MW_fuel=None, ratio_basis='mass', reactivities=None, combustion_stoichiometries=None):
    """
    Solves the system of equations describing a flow of air mixing with a flow of combustibles and burning completely.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        zs_air (str): Mole fractions of the air in JSON array format.
        zs_fuel (str): Mole fractions of the fuel in JSON array format.
        CASs (str): CAS numbers of all compounds in JSON array format.
        atomss (str): List of dictionaries of elements and their counts for all molecules in JSON array format.
        n_fuel (float, optional): Flow rate of fuel [mol/s]. Default is None.
        n_air (float, optional): Flow rate of air [mol/s]. Default is None.
        n_out (float, optional): Flow rate of combustion products, remaining oxygen, and inerts [mol/s]. Default is None.
        Oxy_excess (float, optional): The excess oxygen coming out. Default is None.
        frac_out_Oxy (float, optional): The mole fraction of oxygen out. Default is None.
        frac_out_Oxy_dry (float, optional): The mole fraction of oxygen out on a dry basis. Default is None.
        ratio (float, optional): Air-fuel ratio, in the specified basis. Default is None.
        Vm_air (float, optional): Molar volume of air [m^3/mol]. Default is None.
        Vm_fuel (float, optional): Molar volume of fuel [m^3/mol]. Default is None.
        MW_air (float, optional): Molecular weight of air [g/mol]. Default is None.
        MW_fuel (float, optional): Molecular weight of fuel [g/mol]. Default is None.
        ratio_basis (str, optional): One of 'mass', 'mole', or 'volume'. Valid options: Mass, Mole, Volume. Default is 'mass'.
        reactivities (str, optional): Optional JSON array of booleans marking combustible species to leave unreacted. Default is None.
        combustion_stoichiometries (str, optional): Optional JSON array of precomputed combustion stoichiometry dictionaries. Default is None.

    Returns:
        str: JSON Dictionary of all calculated variables.
    """
    try:
        _za = json.loads(zs_air) if isinstance(zs_air, str) else zs_air
        _zf = json.loads(zs_fuel) if isinstance(zs_fuel, str) else zs_fuel
        _c = json.loads(CASs) if isinstance(CASs, str) else CASs
        _a = json.loads(atomss) if isinstance(atomss, str) else atomss
        _r = json.loads(reactivities) if reactivities and isinstance(reactivities, str) else reactivities
        _s = json.loads(combustion_stoichiometries) if combustion_stoichiometries and isinstance(combustion_stoichiometries, str) else combustion_stoichiometries
        rb = ratio_basis if ratio_basis else "mass"
        res = fuel_air_spec_solver(_za, _zf, _c, _a, n_fuel=n_fuel, n_air=n_air, n_out=n_out, O2_excess=Oxy_excess, frac_out_O2=frac_out_Oxy, frac_out_O2_dry=frac_out_Oxy_dry, ratio=ratio, Vm_air=Vm_air, Vm_fuel=Vm_fuel, MW_air=MW_air, MW_fuel=MW_fuel, ratio_basis=rb, reactivities=_r, combustion_stoichiometries=_s)
        return json.dumps(res, sort_keys=True)
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

Mole fractions of the air in JSON array format.
Mole fractions of the fuel in JSON array format.
CAS numbers of all compounds in JSON array format.
List of dictionaries of elements and their counts for all molecules in JSON array format.
Flow rate of fuel [mol/s].
Flow rate of air [mol/s].
Flow rate of combustion products, remaining oxygen, and inerts [mol/s].
The excess oxygen coming out.
The mole fraction of oxygen out.
The mole fraction of oxygen out on a dry basis.
Air-fuel ratio, in the specified basis.
Molar volume of air [m^3/mol].
Molar volume of fuel [m^3/mol].
Molecular weight of air [g/mol].
Molecular weight of fuel [g/mol].
One of 'mass', 'mole', or 'volume'.
Optional JSON array of booleans marking combustible species to leave unreacted.
Optional JSON array of precomputed combustion stoichiometry dictionaries.

HHV_STOICHIOMETRY

This function computes the higher heating value from a fuel’s theoretical combustion stoichiometry and its heat of formation. It evaluates the combustion reaction enthalpy using standard heats of formation for the products in the stoichiometric dictionary.

The sign convention follows the reaction enthalpy:

HHV = \sum_i \nu_i H_{f,i}^{\circ} - H_{f,fuel}^{\circ}

For an exothermic combustion reaction, the returned value is typically negative because the products have a lower enthalpy than the reactants. This convention is useful when combining the result directly with stoichiometric balances and downstream heating-value conversions.

Excel Usage

=HHV_STOICHIOMETRY(stoichiometry, Hf, Hf_chemicals)
  • stoichiometry (str, required): Stoichiometric coefficients of combustion.
  • Hf (float, required): Heat of formation [J/mol].
  • Hf_chemicals (str, optional, default: null): Heat of formation of chemicals present in stoichiometry [J/mol].

Returns (float): Higher heating value [J/mol].

Example 1: Methane HHV

Inputs:

stoichiometry Hf
{“O2”: -2.0, “CO2”: 1, “H2O”: 2.0} -74520

Excel formula:

=HHV_STOICHIOMETRY("{"O2": -2.0, "CO2": 1, "H2O": 2.0}", -74520)

Expected output:

-890604

Example 2: Methanol HHV

Inputs:

stoichiometry Hf
{“O2”: -1.5, “CO2”: 1, “H2O”: 2.0} -201000

Excel formula:

=HHV_STOICHIOMETRY("{"O2": -1.5, "CO2": 1, "H2O": 2.0}", -201000)

Expected output:

-764124

Example 3: Methane HHV with explicit product heats of formation

Inputs:

stoichiometry Hf Hf_chemicals
{“O2”: -2.0, “CO2”: 1, “H2O”: 2.0} -74520 {“O2”: 0, “CO2”: -393474, “H2O”: -285825}

Excel formula:

=HHV_STOICHIOMETRY("{"O2": -2.0, "CO2": 1, "H2O": 2.0}", -74520, "{"O2": 0, "CO2": -393474, "H2O": -285825}")

Expected output:

-890604

Python Code

Show Code 
import json
from chemicals.combustion import HHV_stoichiometry

def hhv_stoichiometry(stoichiometry, Hf, Hf_chemicals=None):
    """
    Returns the higher heating value based on theoretical combustion stoichiometry and heat of formation.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        stoichiometry (str): Stoichiometric coefficients of combustion.
        Hf (float): Heat of formation [J/mol].
        Hf_chemicals (str, optional): Heat of formation of chemicals present in stoichiometry [J/mol]. Default is None.

    Returns:
        float: Higher heating value [J/mol].
    """
    try:
        st = json.loads(stoichiometry) if isinstance(stoichiometry, str) else stoichiometry
        hfc = json.loads(Hf_chemicals) if Hf_chemicals and isinstance(Hf_chemicals, str) else Hf_chemicals
        return float(HHV_stoichiometry(st, Hf, hfc))
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

Stoichiometric coefficients of combustion.
Heat of formation [J/mol].
Heat of formation of chemicals present in stoichiometry [J/mol].

IS_COMBUSTIBLE

This function determines whether a chemical should be treated as combustible by combining a CAS-based lookup with the supplied elemental composition. It is useful when preparing combustion balances because some compounds are structurally incapable of releasing further heat under complete oxidation, while others can be forced to behave as inert with the reactive flag.

In practical terms, the decision is a logical classification rather than a thermodynamic calculation: a species is treated as combustible only when its identity and composition indicate that further oxidation is possible and the wrapper has not been instructed to mark it as non-reactive.

Excel Usage

=IS_COMBUSTIBLE(CAS, atoms, reactive)
  • CAS (str, required): CAS number.
  • atoms (str, required): Dictionary of atoms and their counts.
  • reactive (bool, optional, default: true): Default True. Set false to mark as non-reactive.

Returns (bool): True if combustible, else False.

Example 1: Check if methane is combustible

Inputs:

CAS atoms
74-82-8 {“C”: 1, “H”: 4}

Excel formula:

=IS_COMBUSTIBLE("74-82-8", "{"C": 1, "H": 4}")

Expected output:

true

Example 2: Carbon dioxide is not combustible

Inputs:

CAS atoms
124-38-9 {“C”: 1, “O”: 2}

Excel formula:

=IS_COMBUSTIBLE("124-38-9", "{"C": 1, "O": 2}")

Expected output:

false

Example 3: Reactive flag can mark a fuel as inert

Inputs:

CAS atoms reactive
74-82-8 {“C”: 1, “H”: 4} false

Excel formula:

=IS_COMBUSTIBLE("74-82-8", "{"C": 1, "H": 4}", FALSE)

Expected output:

false

Python Code

Show Code 
import json
from chemicals.combustion import is_combustible as chemicals_is_combustible

def is_combustible(CAS, atoms, reactive=True):
    """
    Checks if a chemical is combustible based on its CAS and atoms.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        CAS (str): CAS number.
        atoms (str): Dictionary of atoms and their counts.
        reactive (bool, optional): Default True. Set false to mark as non-reactive. Default is True.

    Returns:
        bool: True if combustible, else False.
    """
    try:
        _a = json.loads(atoms) if isinstance(atoms, str) else atoms
        r = True if reactive is None else reactive
        return bool(chemicals_is_combustible(CAS, _a, reactive=r))
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

CAS number.
Dictionary of atoms and their counts.
Default True. Set false to mark as non-reactive.

LHV_FROM_HHV

This function converts a higher heating value into a lower heating value by removing the latent heat associated with condensing the water formed during combustion. It is appropriate when combustion products are assumed to leave with water remaining in the vapor phase instead of being fully condensed.

The conversion is:

LHV = HHV + H_{vap} N_{H_2O}

where H_{vap} is the molar enthalpy of vaporization of water used by the underlying library and N_{H_2O} is the number of water molecules produced per mole of fuel burned.

Excel Usage

=LHV_FROM_HHV(HHV, N_H_two_O)
  • HHV (float, required): Higher heating value [J/mol].
  • N_H_two_O (int, required): Number of water molecules produced per molecule burned.

Returns (float): Lower heating value [J/mol].

Example 1: Methanol LHV

Inputs:

HHV N_H_two_O
-726024 2

Excel formula:

=LHV_FROM_HHV(-726024, 2)

Expected output:

-638001

Example 2: Methane LHV from HHV

Inputs:

HHV N_H_two_O
-890604 2

Excel formula:

=LHV_FROM_HHV(-890604, 2)

Expected output:

-802581

Example 3: Propane LHV from HHV

Inputs:

HHV N_H_two_O
-2220500 4

Excel formula:

=LHV_FROM_HHV(-2220500, 4)

Expected output:

-2044450

Python Code

Show Code 
from chemicals.combustion import LHV_from_HHV

def lhv_from_hhv(HHV, N_H_two_O):
    """
    Returns the lower heating value (LHV) of a chemical given the higher heating value (HHV) and number of water molecules formed.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        HHV (float): Higher heating value [J/mol].
        N_H_two_O (int): Number of water molecules produced per molecule burned.

    Returns:
        float: Lower heating value [J/mol].
    """
    try:
        return float(LHV_from_HHV(HHV, N_H_two_O))
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

Higher heating value [J/mol].
Number of water molecules produced per molecule burned.

MON

This function retrieves a chemical’s motor octane number from reference or model datasets keyed by CAS number. If no method is specified, the underlying library selects an available source automatically and returns the corresponding MON value.

Motor octane number is an empirical fuel-quality index used to characterize resistance to engine knock under more severe operating conditions than the research octane test. The wrapper is a data lookup rather than a predictive calculation, so the result depends on the chosen source and on whether a record exists for the requested compound.

Excel Usage

=MON(CASRN, mon_method)
  • CASRN (str, required): CASRN
  • mon_method (str, optional, default: null): A string for the method name to use.

Returns (float): Motor octane number.

Example 1: Ethanol MON

Inputs:

CASRN
64-17-5

Excel formula:

=MON("64-17-5")

Expected output:

89.7

Example 2: Methanol MON

Inputs:

CASRN
67-56-1

Excel formula:

=MON("67-56-1")

Expected output:

88.6

Example 3: Ethanol MON with explicit data source

Inputs:

CASRN mon_method
64-17-5 FLORIAN_LIMING

Excel formula:

=MON("64-17-5", "FLORIAN_LIMING")

Expected output:

89.7

Python Code

Show Code 
from chemicals.combustion import MON

def mon(CASRN, mon_method=None):
    """
    This function handles the retrieval of a chemical's motor octane number (MON), using CASRN.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        CASRN (str): CASRN
        mon_method (str, optional): A string for the method name to use. Valid options: Florian Liming, Florian Liming ANN, CombustDB, CombustDB Predictions. Default is None.

    Returns:
        float: Motor octane number.
    """
    try:
        res = MON(CASRN, method=mon_method)
        if res is None:
            return "Error: Data not available"
        return float(res)
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

CASRN
A string for the method name to use.

RON

This function retrieves a chemical’s research octane number from reference or model datasets keyed by CAS number. If the method is omitted, the underlying library selects an available source automatically and returns the corresponding RON value.

Research octane number is an empirical fuel-quality index for knock resistance under lighter standardized test conditions than motor octane number. Because the wrapper performs a source-backed lookup rather than a first-principles calculation, availability and exact values depend on the selected dataset for the requested compound.

Excel Usage

=RON(CASRN, ron_method)
  • CASRN (str, required): CASRN
  • ron_method (str, optional, default: null): A string for the method name to use.

Returns (float): Research octane number.

Example 1: Ethanol RON

Inputs:

CASRN
64-17-5

Excel formula:

=RON("64-17-5")

Expected output:

108.6

Example 2: Methanol RON

Inputs:

CASRN
67-56-1

Excel formula:

=RON("67-56-1")

Expected output:

108.7

Example 3: Ethanol RON with explicit data source

Inputs:

CASRN ron_method
64-17-5 FLORIAN_LIMING

Excel formula:

=RON("64-17-5", "FLORIAN_LIMING")

Expected output:

108.6

Python Code

Show Code 
from chemicals.combustion import RON

def ron(CASRN, ron_method=None):
    """
    This function handles the retrieval of a chemical's research octane number (RON), using CASRN.

    See: https://chemicals.readthedocs.io/chemicals.combustion.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        CASRN (str): CASRN
        ron_method (str, optional): A string for the method name to use. Valid options: Florian Liming, Florian Liming ANN, CombustDB, CombustDB Predictions. Default is None.

    Returns:
        float: Research octane number.
    """
    try:
        res = RON(CASRN, method=ron_method)
        if res is None:
            return "Error: Data not available"
        return float(res)
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

CASRN
A string for the method name to use.