Species Namelists¶

Classes for defining chemical species and combustion parameters in FDS simulations.

Species¶

The Species class represents the FDS SPEC namelist for defining gas species.

Species ¶

Bases: NamelistBase

FDS SPEC namelist - gas species definition.

Defines gas species for combustion and pyrolysis modeling. Species can be predefined (from FDS database), user-defined with chemical composition, or lumped components for simplified modeling.

ATTRIBUTE	DESCRIPTION
`id`	Unique species identifier TYPE: `str`
`formula`	Chemical formula (e.g., 'C2H6O2') TYPE: `(str, optional)`
`alt_id`	Alternative species ID for lookups TYPE: `(str, optional)`
`background`	Use as background species, default: False TYPE: `(bool, optional)`
`primitive`	Treat duplicate species as primitive, default: False TYPE: `(bool, optional)`
`copy_lumped`	Create copy of lumped species, default: False TYPE: `(bool, optional)`
`c`	Number of carbon atoms in molecule TYPE: `(float, optional)`
`h`	Number of hydrogen atoms in molecule TYPE: `(float, optional)`
`o`	Number of oxygen atoms in molecule TYPE: `(float, optional)`
`n`	Number of nitrogen atoms in molecule TYPE: `(float, optional)`
`mw`	Molecular weight [g/mol] TYPE: `(float, optional)`
`mass_fraction_0`	Initial mass fraction in ambient (e.g., 0.23 for oxygen) TYPE: `(float, optional)`
`mass_fraction_cond_0`	Initial condensed mass fraction TYPE: `(float, optional)`
`lumped_component_only`	Species is a lumped component (predefined properties), default: False TYPE: `(bool, optional)`
`spec_id`	Component species IDs for mixture species TYPE: `(list[str], optional)`
`mass_fraction`	Mass fractions of components for mixture species TYPE: `(list[float], optional)`
`volume_fraction`	Volume fractions of components for mixture species TYPE: `(list[float], optional)`
`specific_heat`	Specific heat capacity [kJ/(kg·K)] TYPE: `(float, optional)`
`conductivity`	Thermal conductivity [W/(m·K)] TYPE: `(float, optional)`
`conductivity_solid`	Solid phase conductivity for aerosols [W/(m·K)] TYPE: `(float, optional)`
`viscosity`	Dynamic viscosity [kg/(m·s)] TYPE: `(float, optional)`
`diffusivity`	Mass diffusivity [m²/s] TYPE: `(float, optional)`
`reference_temperature`	Reference temperature [°C] TYPE: `(float, optional)`
`reference_enthalpy`	Enthalpy at reference temp [kJ/kg] TYPE: `(float, optional)`
`enthalpy_of_formation`	Formation enthalpy [kJ/mol] TYPE: `(float, optional)`
`polynomial`	Polynomial type ('NASA7' or 'NASA9') TYPE: `(str, optional)`
`polynomial_coeff`	NASA polynomial coefficients (2 sets) TYPE: `(list[list[float]], optional)`
`polynomial_temp`	Polynomial temperature ranges [K] (3 values: T_low, T_mid, T_high) TYPE: `(list[float], optional)`
`ramp_cp`	Specific heat ramp ID TYPE: `(str, optional)`
`ramp_cp_l`	Liquid specific heat ramp ID TYPE: `(str, optional)`
`ramp_k`	Conductivity ramp ID TYPE: `(str, optional)`
`ramp_d`	Diffusivity ramp ID TYPE: `(str, optional)`
`ramp_mu`	Viscosity ramp ID TYPE: `(str, optional)`
`ramp_g_f`	Gibbs free energy ramp ID TYPE: `(str, optional)`
`aerosol`	Species is an aerosol, default: False TYPE: `(bool, optional)`
`density_solid`	Density of aerosol particles [kg/m³] TYPE: `(float, optional)`
`mean_diameter`	Mean diameter of aerosol particles [m] TYPE: `(float, optional)`
`thermophoretic_diameter`	Thermophoretic diameter [m] TYPE: `(float, optional)`
`radcal_id`	RadCal surrogate species for absorption TYPE: `(str, optional)`
`mass_extinction_coefficient`	Mass extinction coefficient for smoke TYPE: `(float, optional)`
`pr_gas`	Gas phase Prandtl number TYPE: `(float, optional)`
`turbulent_schmidt_number`	Turbulent Schmidt number TYPE: `(float, optional)`
`sigmalj`	Lennard-Jones sigma [Å] TYPE: `(float, optional)`
`epsilonklj`	Lennard-Jones epsilon/k [K] TYPE: `(float, optional)`
`vaporization_temperature`	Vaporization temperature [°C] TYPE: `(float, optional)`
`heat_of_vaporization`	Heat of vaporization [kJ/kg] TYPE: `(float, optional)`
`h_v_reference_temperature`	Reference temp for vaporization [°C] TYPE: `(float, optional)`
`beta_liquid`	Liquid thermal expansion coefficient [1/K] TYPE: `(float, optional)`
`density_liquid`	Liquid density [kg/m³] TYPE: `(float, optional)`
`specific_heat_liquid`	Liquid specific heat [kJ/(kg·K)] TYPE: `(float, optional)`
`conductivity_liquid`	Liquid conductivity [W/(m·K)] TYPE: `(float, optional)`
`viscosity_liquid`	Liquid viscosity [kg/(m·s)] TYPE: `(float, optional)`
`melting_temperature`	Melting temperature [°C] TYPE: `(float, optional)`
`fic_concentration`	FIC concentration for FED calculations [ppm] TYPE: `(float, optional)`
`fld_lethal_dose`	FLD lethal dose for FED calculations [ppmmin] TYPE:* `(float, optional)`
`real_refractive_index`	Real part of refractive index for condensation TYPE: `(float, optional)`
`complex_refractive_index`	Complex part of refractive index for condensation TYPE: `(float, optional)`
`min_diameter`	Minimum diameter for agglomeration [m] TYPE: `(float, optional)`
`max_diameter`	Maximum diameter for agglomeration [m] TYPE: `(float, optional)`
`n_bins`	Number of bins for agglomeration TYPE: `(int, optional)`
`ode_abs_error`	ODE absolute error tolerance for detailed chemistry TYPE: `(float, optional)`
`ode_rel_error`	ODE relative error tolerance for detailed chemistry TYPE: `(float, optional)`

Examples:

>>> # Predefined species (oxygen)
>>> o2 = Species(id='OXYGEN', mass_fraction_0=0.23)

>>> # User-defined fuel species with formula
>>> fuel = Species(id='MY_FUEL', formula='C3H8O3N4', mw=92.0)

>>> # Background species
>>> air = Species(id='AIR', background=True, spec_id=['N2', 'O2'], volume_fraction=[0.79, 0.21])

>>> # Species with temperature-dependent properties
>>> gas = Species(id='HOT_GAS', ramp_cp='CP_RAMP', ramp_mu='MU_RAMP')

>>> # Species with Lennard-Jones parameters
>>> lj_species = Species(id='LJ_SPEC', sigmalj=3.5, epsilonklj=150.0)

Combustion¶

The Combustion class represents the FDS COMB namelist for combustion model parameters.

Combustion ¶

Bases: NamelistBase

FDS COMB namelist - combustion model parameters.

Controls global combustion behavior including extinction models, turbulent combustion, mixing parameters, and ODE solver configuration.

ATTRIBUTE	DESCRIPTION
`extinction_model`	Extinction model ('EXTINCTION 1' or 'EXTINCTION 2'). TYPE: `(ExtinctionModel, optional)`
`suppression`	Enable flame suppression model, default: True. TYPE: `(bool, optional)`
`initial_unmixed_fraction`	Initial unmixed fraction (0-1), default: 1.0. TYPE: `(float, optional)`
`tau_chem`	Minimum bound for mixing time [s], default: 1e-5. TYPE: `(float, optional)`
`tau_flame`	Maximum bound for mixing time [s], default: 1e10. TYPE: `(float, optional)`
`ode_solver`	ODE solver for chemistry integration ('EXPLICIT EULER', 'RK2', 'RK2 RICHARDSON', 'RK3', 'CVODE'). TYPE: `(str, optional)`

Examples:

>>> comb = Combustion(extinction_model=ExtinctionModel.EXTINCTION_2)

Usage Examples¶

Predefined Species¶

from pyfds import Simulation, Species, Reaction

sim = Simulation(chid="species_example")

# Use a predefined fuel - FDS knows the properties
sim.add(Reaction(fuel="METHANE", co_yield=0.1))

Custom Species¶

from pyfds import Simulation, Species

sim = Simulation(chid="custom_species")

# Define a custom species with specific properties
sim.add(Species(
    id="MY_GAS",
    formula="C2H6O",  # Ethanol
    mw=46.07
))

Lumped Species¶

from pyfds import Simulation, Species

sim = Simulation(chid="lumped_example")

# Define component species
sim.add(Species(id="NITROGEN", lumped_component_only=True))
sim.add(Species(id="OXYGEN", lumped_component_only=True))

# Define lumped species from components
sim.add(Species(
    id="AIR",
    spec_id=["NITROGEN", "OXYGEN"],
    mass_fraction=[0.767, 0.233],
    background=True
))

Species Namelists¶

Species¶

Species ¶

Species with NASA polynomials¶

Liquid properties for droplet simulation¶