MaterialBuilder

MaterialBuilder

MaterialBuilder(id=None)

Bases: Builder[Material]

Builder for creating MATL namelists.

Provides a fluent API for constructing materials with thermal properties and optional multi-reaction pyrolysis.

PARAMETER	DESCRIPTION
id	Unique identifier for the material TYPE: str DEFAULT: None

Examples:

>>> # Simple material with constant properties
>>> wood = MaterialBuilder('PINE') \
...     .density(500) \
...     .thermal_conductivity(0.13) \
...     .specific_heat(2.5) \
...     .build()

>>> # Temperature-dependent properties using RAMPs
>>> steel = MaterialBuilder('STEEL') \
...     .density(7850) \
...     .thermal_conductivity_ramp('STEEL_K') \
...     .specific_heat(0.46) \
...     .emissivity(0.7) \
...     .build()

>>> # Multi-reaction pyrolysis material
>>> polymer = MaterialBuilder('POLYURETHANE') \
...     .density(40) \
...     .thermal_conductivity(0.04) \
...     .specific_heat(1.5) \
...     .add_reaction(PyrolysisReaction(
...         a=1e10, e=80000, heat_of_reaction=1000,
...         products=[PyrolysisProduct(spec_id='FUEL_VAPOR', nu_spec=1.0)]
...     )) \
...     .build()

>>> # Use predefined materials
>>> concrete = MaterialBuilder.concrete()
>>> gypsum = MaterialBuilder.gypsum()
>>> steel = MaterialBuilder.steel()

Initialize the MaterialBuilder.

PARAMETER	DESCRIPTION
id	Unique identifier for the material. Can also be set via .id() method. TYPE: str DEFAULT: None

Source code in src/pyfds/builders/material.py

def __init__(self, id: str | None = None):
    """
    Initialize the MaterialBuilder.

    Parameters
    ----------
    id : str, optional
        Unique identifier for the material. Can also be set via .id() method.
    """
    super().__init__()
    self._id = id
    self._density: float | None = None
    self._conductivity: float | None = None
    self._conductivity_ramp: str | None = None
    self._specific_heat: float | None = None
    self._specific_heat_ramp: str | None = None
    self._emissivity: float = 0.9
    self._absorption_coefficient: float = 50000.0
    self._structured_reactions: list[PyrolysisReaction] = []
    # Liquid fuel parameters
    self._boiling_temperature: float | None = None
    self._mw: float | None = None

Functions

id

id(material_id)

Set material identifier.

PARAMETER	DESCRIPTION
material_id	Unique identifier for the material TYPE: str

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Source code in src/pyfds/builders/material.py

def id(self, material_id: str) -> "MaterialBuilder":
    """
    Set material identifier.

    Parameters
    ----------
    material_id : str
        Unique identifier for the material

    Returns
    -------
    MaterialBuilder
        Self for method chaining
    """
    self._id = material_id
    return self

density

density(value)

Set material density.

PARAMETER	DESCRIPTION
value	Density in kg/m³ TYPE: float

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Source code in src/pyfds/builders/material.py

def density(self, value: float) -> "MaterialBuilder":
    """
    Set material density.

    Parameters
    ----------
    value : float
        Density in kg/m³

    Returns
    -------
    MaterialBuilder
        Self for method chaining
    """
    self._density = value
    return self

thermal_conductivity

thermal_conductivity(value)

Set constant thermal conductivity.

PARAMETER	DESCRIPTION
value	Thermal conductivity in W/(m·K) TYPE: float

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Notes

Use either thermal_conductivity or thermal_conductivity_ramp, not both.

Source code in src/pyfds/builders/material.py

def thermal_conductivity(self, value: float) -> "MaterialBuilder":
    """
    Set constant thermal conductivity.

    Parameters
    ----------
    value : float
        Thermal conductivity in W/(m·K)

    Returns
    -------
    MaterialBuilder
        Self for method chaining

    Notes
    -----
    Use either thermal_conductivity or thermal_conductivity_ramp, not both.
    """
    self._conductivity = value
    self._conductivity_ramp = None
    return self

thermal_conductivity_ramp

thermal_conductivity_ramp(ramp_id)

Use temperature-dependent conductivity via RAMP.

PARAMETER	DESCRIPTION
ramp_id	ID of the RAMP defining conductivity vs temperature TYPE: str

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Notes

Use either thermal_conductivity or thermal_conductivity_ramp, not both.

Source code in src/pyfds/builders/material.py

def thermal_conductivity_ramp(self, ramp_id: str) -> "MaterialBuilder":
    """
    Use temperature-dependent conductivity via RAMP.

    Parameters
    ----------
    ramp_id : str
        ID of the RAMP defining conductivity vs temperature

    Returns
    -------
    MaterialBuilder
        Self for method chaining

    Notes
    -----
    Use either thermal_conductivity or thermal_conductivity_ramp, not both.
    """
    self._conductivity_ramp = ramp_id
    self._conductivity = None
    return self

specific_heat

specific_heat(value)

Set constant specific heat capacity.

PARAMETER	DESCRIPTION
value	Specific heat in kJ/(kg·K) TYPE: float

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Notes

Use either specific_heat or specific_heat_ramp, not both.

Source code in src/pyfds/builders/material.py

def specific_heat(self, value: float) -> "MaterialBuilder":
    """
    Set constant specific heat capacity.

    Parameters
    ----------
    value : float
        Specific heat in kJ/(kg·K)

    Returns
    -------
    MaterialBuilder
        Self for method chaining

    Notes
    -----
    Use either specific_heat or specific_heat_ramp, not both.
    """
    self._specific_heat = value
    self._specific_heat_ramp = None
    return self

specific_heat_ramp

specific_heat_ramp(ramp_id)

Use temperature-dependent specific heat via RAMP.

PARAMETER	DESCRIPTION
ramp_id	ID of the RAMP defining specific heat vs temperature TYPE: str

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Notes

Use either specific_heat or specific_heat_ramp, not both.

Source code in src/pyfds/builders/material.py

def specific_heat_ramp(self, ramp_id: str) -> "MaterialBuilder":
    """
    Use temperature-dependent specific heat via RAMP.

    Parameters
    ----------
    ramp_id : str
        ID of the RAMP defining specific heat vs temperature

    Returns
    -------
    MaterialBuilder
        Self for method chaining

    Notes
    -----
    Use either specific_heat or specific_heat_ramp, not both.
    """
    self._specific_heat_ramp = ramp_id
    self._specific_heat = None
    return self

emissivity

emissivity(value)

Set surface emissivity.

PARAMETER	DESCRIPTION
value	Emissivity in range [0, 1], default: 0.9 TYPE: float

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Source code in src/pyfds/builders/material.py

def emissivity(self, value: float) -> "MaterialBuilder":
    """
    Set surface emissivity.

    Parameters
    ----------
    value : float
        Emissivity in range [0, 1], default: 0.9

    Returns
    -------
    MaterialBuilder
        Self for method chaining
    """
    self._emissivity = value
    return self

absorption_coefficient

absorption_coefficient(value)

Set radiation absorption coefficient.

PARAMETER	DESCRIPTION
value	Absorption coefficient in 1/m, default: 50000.0 TYPE: float

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Source code in src/pyfds/builders/material.py

def absorption_coefficient(self, value: float) -> "MaterialBuilder":
    """
    Set radiation absorption coefficient.

    Parameters
    ----------
    value : float
        Absorption coefficient in 1/m, default: 50000.0

    Returns
    -------
    MaterialBuilder
        Self for method chaining
    """
    self._absorption_coefficient = value
    return self

add_reaction

add_reaction(reaction)

Add a structured pyrolysis reaction to the material.

PARAMETER	DESCRIPTION
reaction	The structured pyrolysis reaction to add TYPE: PyrolysisReaction

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Examples:

>>> from pyfds.core.models import PyrolysisReaction, PyrolysisProduct
>>> reaction = PyrolysisReaction(
...     a=1e10, e=1.5e5, heat_of_reaction=500,
...     products=[PyrolysisProduct(spec_id="GAS", nu_spec=0.8)]
... )
>>> mat = MaterialBuilder('WOOD').add_reaction(reaction).build()

Source code in src/pyfds/builders/material.py

def add_reaction(self, reaction: "PyrolysisReaction") -> "MaterialBuilder":
    """
    Add a structured pyrolysis reaction to the material.

    Parameters
    ----------
    reaction : PyrolysisReaction
        The structured pyrolysis reaction to add

    Returns
    -------
    MaterialBuilder
        Self for method chaining

    Examples
    --------
    >>> from pyfds.core.models import PyrolysisReaction, PyrolysisProduct
    >>> reaction = PyrolysisReaction(
    ...     a=1e10, e=1.5e5, heat_of_reaction=500,
    ...     products=[PyrolysisProduct(spec_id="GAS", nu_spec=0.8)]
    ... )
    >>> mat = MaterialBuilder('WOOD').add_reaction(reaction).build()
    """
    self._structured_reactions.append(reaction)
    return self

add_pyrolysis_reaction

add_pyrolysis_reaction(
    a,
    e,
    heat_of_reaction,
    product_species=None,
    residue_material=None,
    yield_fraction=1.0,
)

Add a pyrolysis reaction using simplified parameters.

Creates a PyrolysisReaction from basic kinetic parameters. For more complex reactions, prefer using add_reaction() with PyrolysisReaction objects directly.

PARAMETER	DESCRIPTION
a	Pre-exponential factor [1/s] TYPE: float
e	Activation energy [J/mol] TYPE: float
heat_of_reaction	Heat of reaction [kJ/kg] TYPE: float
product_species	Gas species produced TYPE: str DEFAULT: None
residue_material	Solid residue material produced TYPE: str DEFAULT: None
yield_fraction	Yield fraction (default: 1.0) TYPE: float DEFAULT: 1.0

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Source code in src/pyfds/builders/material.py

def add_pyrolysis_reaction(
    self,
    a: float,
    e: float,
    heat_of_reaction: float,
    product_species: str | None = None,
    residue_material: str | None = None,
    yield_fraction: float = 1.0,
) -> "MaterialBuilder":
    """
    Add a pyrolysis reaction using simplified parameters.

    Creates a PyrolysisReaction from basic kinetic parameters.
    For more complex reactions, prefer using add_reaction() with
    PyrolysisReaction objects directly.

    Parameters
    ----------
    a : float
        Pre-exponential factor [1/s]
    e : float
        Activation energy [J/mol]
    heat_of_reaction : float
        Heat of reaction [kJ/kg]
    product_species : str, optional
        Gas species produced
    residue_material : str, optional
        Solid residue material produced
    yield_fraction : float, optional
        Yield fraction (default: 1.0)

    Returns
    -------
    MaterialBuilder
        Self for method chaining
    """
    from pyfds.core.models import PyrolysisProduct, PyrolysisReaction

    products = []
    if product_species:
        products.append(PyrolysisProduct(spec_id=product_species, nu_spec=yield_fraction))
    if residue_material:
        products.append(PyrolysisProduct(matl_id=residue_material, nu_matl=yield_fraction))

    reaction = PyrolysisReaction(
        a=a,
        e=e,
        heat_of_reaction=heat_of_reaction,
        products=products,
    )
    self._structured_reactions.append(reaction)
    return self

as_liquid_fuel

as_liquid_fuel(
    boiling_temperature,
    spec_id,
    mw=None,
    heat_of_vaporization=None,
    absorption_coefficient=None,
    nu_spec=1.0,
)

Configure as liquid fuel with evaporation properties.

Liquid fuels in FDS evaporate at their boiling temperature and produce gaseous fuel species for combustion.

PARAMETER	DESCRIPTION
boiling_temperature	Boiling point in °C (triggers liquid model in FDS) TYPE: float
spec_id	Gaseous species ID produced by evaporation TYPE: str
mw	Molecular weight in g/mol TYPE: float DEFAULT: None
heat_of_vaporization	Heat of vaporization in kJ/kg TYPE: float DEFAULT: None
absorption_coefficient	Radiation absorption coefficient in 1/m TYPE: float DEFAULT: None
nu_spec	Yield fraction (default: 1.0 for pure liquid) TYPE: float DEFAULT: 1.0

RETURNS	DESCRIPTION
MaterialBuilder	Self for method chaining

Examples:

>>> ethanol = MaterialBuilder("ETHANOL_LIQUID") \
...     .density(794) \
...     .thermal_conductivity(0.17) \
...     .specific_heat(2.44) \
...     .as_liquid_fuel(
...         boiling_temperature=78.5,
...         spec_id="ETHANOL",
...         mw=46.07,
...         heat_of_vaporization=837,
...         absorption_coefficient=1140
...     ) \
...     .build()

>>> methanol = MaterialBuilder("METHANOL_LIQUID") \
...     .density(792) \
...     .thermal_conductivity(0.2) \
...     .specific_heat(2.51) \
...     .as_liquid_fuel(
...         boiling_temperature=64.7,
...         spec_id="METHANOL",
...         mw=32.04
...     ) \
...     .build()

Source code in src/pyfds/builders/material.py

def as_liquid_fuel(
    self,
    boiling_temperature: float,
    spec_id: str,
    mw: float | None = None,
    heat_of_vaporization: float | None = None,
    absorption_coefficient: float | None = None,
    nu_spec: float = 1.0,
) -> "MaterialBuilder":
    """
    Configure as liquid fuel with evaporation properties.

    Liquid fuels in FDS evaporate at their boiling temperature
    and produce gaseous fuel species for combustion.

    Parameters
    ----------
    boiling_temperature : float
        Boiling point in °C (triggers liquid model in FDS)
    spec_id : str
        Gaseous species ID produced by evaporation
    mw : float, optional
        Molecular weight in g/mol
    heat_of_vaporization : float, optional
        Heat of vaporization in kJ/kg
    absorption_coefficient : float, optional
        Radiation absorption coefficient in 1/m
    nu_spec : float, optional
        Yield fraction (default: 1.0 for pure liquid)

    Returns
    -------
    MaterialBuilder
        Self for method chaining

    Examples
    --------
    >>> ethanol = MaterialBuilder("ETHANOL_LIQUID") \\
    ...     .density(794) \\
    ...     .thermal_conductivity(0.17) \\
    ...     .specific_heat(2.44) \\
    ...     .as_liquid_fuel(
    ...         boiling_temperature=78.5,
    ...         spec_id="ETHANOL",
    ...         mw=46.07,
    ...         heat_of_vaporization=837,
    ...         absorption_coefficient=1140
    ...     ) \\
    ...     .build()

    >>> methanol = MaterialBuilder("METHANOL_LIQUID") \\
    ...     .density(792) \\
    ...     .thermal_conductivity(0.2) \\
    ...     .specific_heat(2.51) \\
    ...     .as_liquid_fuel(
    ...         boiling_temperature=64.7,
    ...         spec_id="METHANOL",
    ...         mw=32.04
    ...     ) \\
    ...     .build()
    """
    from pyfds.core.models import PyrolysisProduct, PyrolysisReaction

    self._boiling_temperature = boiling_temperature
    if mw is not None:
        self._mw = mw
    if absorption_coefficient is not None:
        self._absorption_coefficient = absorption_coefficient

    # Create a structured reaction for the liquid evaporation
    # In FDS, heat_of_vaporization is specified as heat_of_reaction on the reaction
    evap_reaction = PyrolysisReaction(
        heat_of_reaction=heat_of_vaporization if heat_of_vaporization is not None else 0.0,
        products=[PyrolysisProduct(spec_id=spec_id, nu_spec=nu_spec)],
    )
    self._structured_reactions.append(evap_reaction)

    return self

Overview

MaterialBuilder creates material definitions (&MATL namelists) with thermal properties and pyrolysis reactions.

Key Features

• Simple Materials: Constant thermal properties
• Temperature-Dependent: Properties via RAMP references
• Multi-Reaction Pyrolysis: Complex material decomposition
• Predefined Materials: Common building materials

Quick Examples

Simple Material

from pyfds.builders import MaterialBuilder

# Material with constant properties
wood = (
    MaterialBuilder('PINE')
    .density(500)                    # kg/m³
    .thermal_conductivity(0.13)      # W/(m·K)
    .specific_heat(2.5)              # kJ/(kg·K)
    .emissivity(0.9)                 # 0-1
    .build()
)

Temperature-Dependent Properties

# Create ramp first
k_ramp = RampBuilder('STEEL_K').temperature_table({
    20: 45.8, 100: 43.3, 200: 40.7, 400: 36.4
}).build()
sim.add_ramp(k_ramp)

# Use ramp in material
steel = (
    MaterialBuilder('STEEL')
    .density(7850)
    .thermal_conductivity_ramp('STEEL_K')  # Reference ramp
    .specific_heat(0.46)
    .emissivity(0.7)
    .build()
)

Pyrolysis Material (Single Reaction)

# Simple decomposition
foam = (
    MaterialBuilder('FOAM')
    .density(40)
    .thermal_conductivity(0.04)
    .specific_heat(1.5)
    .add_pyrolysis_reaction(
        a=1e10,                      # Pre-exponential factor (1/s)
        e=80000,                     # Activation energy (J/mol)
        heat_of_reaction=1000,       # Heat of reaction (kJ/kg)
        product_species='FUEL_VAPOR' # Product species ID
    )
    .build()
)

Multi-Reaction Pyrolysis

# Complex decomposition with multiple pathways
polymer = (
    MaterialBuilder('POLYURETHANE')
    .density(40)
    .thermal_conductivity(0.04)
    .specific_heat(1.5)
    # First reaction: produces fuel vapor
    .add_pyrolysis_reaction(
        a=1e10,
        e=80000,
        heat_of_reaction=1000,
        product_species='FUEL_VAPOR'
    )
    # Second reaction: produces char residue
    .add_pyrolysis_reaction(
        a=5e8,
        e=120000,
        heat_of_reaction=1500,
        residue_material='CHAR'
    )
    .build()
)

Predefined Materials

# Use predefined common materials
concrete = MaterialBuilder.concrete()
gypsum = MaterialBuilder.gypsum()
steel = MaterialBuilder.steel()
aluminum = MaterialBuilder.aluminum()
brick = MaterialBuilder.brick()
wood = MaterialBuilder.wood()

sim.add_material(concrete)
sim.add_material(steel)

Available Predefined Materials

Material	ρ (kg/m³)	k (W/(m·K))	c (kJ/(kg·K))	ε
Concrete	2400	1.6	0.88	0.9
Gypsum	930	0.48	1.09	0.9
Steel	7850	45.8	0.46	0.7
Aluminum	2700	237	0.90	0.2
Brick	1920	0.69	0.84	0.9
Wood	500	0.13	2.5	0.9
Fiberglass	12	0.04	0.84	0.9
Ceramic	2600	1.4	0.88	0.9
Glass	2500	0.8	0.84	0.9
Copper	8900	387	0.38	0.05

Usage in Simulations

Simple Material in Surface

from pyfds import Simulation

sim = Simulation('wall_heating')

# Add material
wood = MaterialBuilder('WOOD').density(500).thermal_conductivity(0.13).build()
sim.add_material(wood)

# Use in surface
sim.add(Surface(id='WOOD_WALL', matl_id='WOOD', thickness=0.012))

# Apply to geometry
sim.add(Obstruction(xb=Bounds3D.of(0, 0, 0, 5, 0, 3), surf_id='WOOD_WALL'))

Layered Materials

# Create materials for layered assembly
gypsum = MaterialBuilder.gypsum()
insulation = MaterialBuilder.fiberglass_insulation()

sim.add_material(gypsum)
sim.add_material(insulation)

# Layered surface
sim.add(Surface(
    id='WALL',
    matl_id=['GYPSUM', 'INSULATION', 'GYPSUM'],
    thickness=[0.012, 0.10, 0.012]  # Gypsum-insulation-gypsum sandwich
)

Pyrolysis with Combustion

# Pyrolyzing material
polymer = (
    MaterialBuilder('POLYMER')
    .density(40)
    .thermal_conductivity(0.04)
    .specific_heat(1.5)
    .add_pyrolysis_reaction(
        a=1e10,
        e=80000,
        heat_of_reaction=1000,
        product_species='FUEL_VAPOR'
    )
    .build()
)
sim.add_material(polymer)

# Combustion reaction for fuel vapor
reac = ReactionBuilder().fuel('PROPANE').build()
sim.add_reaction(reac)

# Surface with pyrolysis
sim.add(Surface(id='FOAM', matl_id='POLYMER', thickness=0.05))

Structured Pyrolysis API

The MaterialBuilder provides a cleaner, more maintainable API for defining pyrolysis reactions using structured data classes.

Single-Step Pyrolysis

from pyfds.core.models import PyrolysisReaction, PyrolysisProduct

# Method 1: Arrhenius kinetics (explicit A and E)
wood = (
    MaterialBuilder('WOOD')
    .density(500)
    .thermal_conductivity(0.13)
    .specific_heat(2.5)
    .add_reaction(
        PyrolysisReaction(
            a=1e10,                    # Pre-exponential factor [1/s]
            e=100000,                  # Activation energy [kJ/kmol]
            heat_of_reaction=500,      # Optional, defaults to 0.0 [kJ/kg]
            products=[
                PyrolysisProduct(spec_id="WOOD_GAS", nu_spec=0.75),
                PyrolysisProduct(matl_id="CHAR", nu_matl=0.25),
            ]
        )
    )
    .build()
)

# Method 2: Simplified with REFERENCE_TEMPERATURE and PYROLYSIS_RANGE
wood_simple = (
    MaterialBuilder('WOOD_SIMPLE')
    .density(500)
    .thermal_conductivity(0.13)
    .specific_heat(2.5)
    .add_reaction(
        PyrolysisReaction(
            reference_temperature=300,  # Peak reaction temperature [°C]
            pyrolysis_range=80,         # Temperature width [°C]
            heat_of_reaction=500,
            products=[
                PyrolysisProduct(spec_id="WOOD_GAS", nu_spec=0.75),
                PyrolysisProduct(matl_id="CHAR", nu_matl=0.25),
            ]
        )
    )
    .build()
)

# Method 3: From TGA with known mass loss rate
tga_wood = (
    MaterialBuilder('TGA_WOOD')
    .density(500)
    .thermal_conductivity(0.13)
    .specific_heat(2.5)
    .add_reaction(
        PyrolysisReaction(
            reference_temperature=300,  # Peak temperature [°C]
            reference_rate=0.002,       # Normalized mass loss rate [1/s]
            heating_rate=5.0,           # TGA heating rate [K/min]
            heat_of_reaction=500,
            products=[
                PyrolysisProduct(spec_id="WOOD_GAS", nu_spec=0.75),
                PyrolysisProduct(matl_id="CHAR", nu_matl=0.25),
            ]
        )
    )
    .build()
)

Multi-Step Pyrolysis

# Complex material with multiple decomposition pathways
polyurethane = (
    MaterialBuilder('POLYURETHANE')
    .density(40)
    .thermal_conductivity(0.04)
    .specific_heat(1.5)
    .add_reaction(
        PyrolysisReaction(
            reference_temperature=100,  # Moisture evaporation
            pyrolysis_range=20,
            heat_of_reaction=2260,      # Heat of vaporization
            products=[PyrolysisProduct(spec_id="WATER_VAPOR", nu_spec=0.05)]
        )
    )
    .add_reaction(
        PyrolysisReaction(
            a=1e12, e=150000,          # Primary pyrolysis
            heat_of_reaction=800,
            products=[
                PyrolysisProduct(spec_id="FUEL_GAS", nu_spec=0.70),
                PyrolysisProduct(matl_id="CHAR", nu_matl=0.15),
            ]
        )
    )
    .add_reaction(
        PyrolysisReaction(
            a=1e8, e=120000,           # Char oxidation
            n_o2=1.0,                  # Heterogeneous oxidation
            heat_of_reaction=-30000,   # Exothermic
            products=[
                PyrolysisProduct(spec_id="CARBON_DIOXIDE", nu_spec=0.08),
                PyrolysisProduct(matl_id="ASH", nu_matl=0.02),
            ]
        )
    )
    .build()
)

Advanced Reaction Parameters

# Reaction with custom kinetics and advanced parameters
plywood = (
    MaterialBuilder('PLYWOOD')
    .density(545)
    .thermal_conductivity(0.12)
    .specific_heat(1.2)
    .add_reaction(
        a=2.5e11,
        e=148000,
        n_s=0.9,                    # Reaction order (slightly less than 1)
        n_t=0.5,                    # Temperature exponent
        gas_diffusion_depth=0.001,  # Gas diffusion length scale [m]
        max_reaction_rate=100.0,    # Maximum reaction rate [kg/(m³·s)]
        heat_of_reaction=420,
        products=[
            {"spec_id": "CELLULOSE", "nu_spec": 0.82},
            {"matl_id": "PLYWOOD_CHAR", "nu_matl": 0.18},
        ]
    )
    .build()
)

Pyrolysis Kinetics

Arrhenius Equation

Pyrolysis rate is governed by the Arrhenius equation:

\[ k = A e^{-E_a / RT} \]

where: - \(A\) = pre-exponential factor (1/s) - \(E_a\) = activation energy (J/mol) - \(R\) = gas constant (8.314 J/(mol·K)) - \(T\) = temperature (K)

Parameters

When adding pyrolysis reactions with PyrolysisReaction:

Kinetic Parameters (Mutually Exclusive)

Method 1: Arrhenius Kinetics - a: Pre-exponential factor [1/s] - typically 10⁸ to 10¹² for polymers - e: Activation energy [kJ/kmol] - typically 80,000 to 200,000 for polymers

Method 2: Simplified with Reference Rate - reference_temperature: Peak reaction temperature [°C] - reference_rate: Normalized mass loss rate at peak [1/s] - heating_rate: TGA heating rate [K/min] (default: 5.0)

Method 3: Simplified with Temperature Range - reference_temperature: Peak reaction temperature [°C] - pyrolysis_range: Temperature width of reaction [°C] (default: 80.0) - heating_rate: TGA heating rate [K/min] (default: 5.0)

Method 4: Auto-Derive - reference_temperature: Peak reaction temperature [°C] only

Other Parameters

• heat_of_reaction: Heat absorbed (+) or released (-) [kJ/kg] (optional, default: 0.0)
• n_s: Reaction order (default: 1.0)
• n_t: Temperature exponent (default: 0.0)
• n_o2: Oxygen reaction order (default: 0.0)
• gas_diffusion_depth: Gas diffusion length scale [m] (optional)
• max_reaction_rate: Maximum reaction rate limit [kg/(m³·s)] (optional)
• products: List of PyrolysisProduct objects

Typical Values

Material	A (1/s)	E (J/mol)	ΔH (kJ/kg)
Wood	1×10¹⁰	80,000	1000
Polyurethane	1×10¹⁰	80,000	1000
PMMA	5×10⁸	120,000	1500
Polystyrene	3×10⁹	100,000	1200

Property Methods

Constant Properties

material = (
    MaterialBuilder('TEST')
    .density(1000)                      # Required
    .thermal_conductivity(1.0)          # W/(m·K)
    .specific_heat(1.0)                 # kJ/(kg·K)
    .emissivity(0.9)                    # 0-1, default: 0.9
    .absorption_coefficient(50000)      # 1/m, default: 50000
    .reference_temperature(20)          # °C
    .build()
)

Temperature-Dependent Properties

material = (
    MaterialBuilder('TEST')
    .density(1000)
    .thermal_conductivity_ramp('K_RAMP')    # Reference to &RAMP
    .specific_heat_ramp('CP_RAMP')          # Reference to &RAMP
    .build()
)

Overriding

Setting a ramp overrides a constant value:

material = (
    MaterialBuilder('TEST')
    .density(1000)
    .thermal_conductivity(1.0)         # Set constant
    .thermal_conductivity_ramp('K')    # Override with ramp
    .build()
)
# Result: conductivity=None, conductivity_ramp='K'

Validation

The builder validates:

• Density is required - All materials must have density
• Either constant or ramp - Can't have both for same property
• Pyrolysis reactions - Valid parameters for each reaction

Predefined Library

from pyfds.builders.libraries import CommonMaterials

# All predefined materials
concrete = CommonMaterials.concrete()
gypsum = CommonMaterials.gypsum()
steel = CommonMaterials.steel()
aluminum = CommonMaterials.aluminum()
brick = CommonMaterials.brick()
wood = CommonMaterials.wood()
fiberglass = CommonMaterials.fiberglass_insulation()
ceramic = CommonMaterials.ceramic()
glass = CommonMaterials.glass()
copper = CommonMaterials.copper()

Best Practices

Use Predefined When Available

# Good
concrete = MaterialBuilder.concrete()

# Avoid
concrete = MaterialBuilder('CONCRETE').density(2400).thermal_conductivity(1.6)...

Layer Materials Appropriately

# Good: Thin surface materials
sim.add(Surface(id='WALL', matl_id='GYPSUM', thickness=0.012))

# Avoid: Very thick single layer (use multiple cells instead)
sim.add(Surface(id='WALL', matl_id='GYPSUM', thickness=1.0)  # Too thick

Validate Pyrolysis Parameters

# Good: Reasonable Arrhenius parameters
.add_pyrolysis_reaction(a=1e10, e=80000, heat_of_reaction=1000, ...)

# Avoid: Unrealistic values
.add_pyrolysis_reaction(a=1e50, e=10, heat_of_reaction=1e6, ...)

See Also

• User Guide - Materials & Surfaces
• User Guide - Builders
• RampBuilder - For temperature-dependent properties