Builder Libraries

libraries

Predefined libraries for common materials, fuels, species, and device properties.

Classes

CommonHoles

Library of predefined hole configurations.

Provides factory methods for common openings like doors and windows with sensible visualization defaults.

Examples:

>>> door = CommonHoles.door(xb=(5, 5, 2, 4, 0, 2.1))
>>> window = CommonHoles.window(xb=(0, 0, 2, 3, 1, 2))

Functions

door staticmethod

door(
    xb,
    id=None,
    ctrl_id=None,
    devc_id=None,
    color="BROWN",
    mult_id=None,
)

Create a standard door opening.

PARAMETER	DESCRIPTION
xb	Door bounds (xmin, xmax, ymin, ymax, zmin, zmax). One dimension should have zero thickness (planar opening). TYPE: tuple or Bounds3D
id	Hole identifier TYPE: str DEFAULT: None
ctrl_id	Control ID for door operation (e.g., open/close logic) TYPE: str DEFAULT: None
devc_id	Device ID for door operation TYPE: str DEFAULT: None
color	Visualization color (default: 'BROWN') TYPE: str DEFAULT: 'BROWN'
mult_id	Multiplier ID for creating arrays of doors TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Hole	Door hole object

Examples:

>>> # Simple door on X-boundary wall
>>> door = CommonHoles.door(xb=(5, 5, 2, 4, 0, 2.1))

>>> # Door with control logic
>>> door = CommonHoles.door(
...     xb=(5, 5, 2, 4, 0, 2.1),
...     id="MAIN_DOOR",
...     ctrl_id="DOOR_OPEN_CTRL"
... )

Notes

Standard door dimensions are typically: - Width: 0.9-1.2 m - Height: 2.0-2.1 m

Source code in src/pyfds/builders/libraries/holes.py

@staticmethod
def door(
    xb: tuple[float, float, float, float, float, float] | Bounds3D,
    id: str | None = None,
    ctrl_id: str | None = None,
    devc_id: str | None = None,
    color: str = "BROWN",
    mult_id: str | None = None,
) -> Hole:
    """
    Create a standard door opening.

    Parameters
    ----------
    xb : tuple or Bounds3D
        Door bounds (xmin, xmax, ymin, ymax, zmin, zmax).
        One dimension should have zero thickness (planar opening).
    id : str, optional
        Hole identifier
    ctrl_id : str, optional
        Control ID for door operation (e.g., open/close logic)
    devc_id : str, optional
        Device ID for door operation
    color : str, optional
        Visualization color (default: 'BROWN')
    mult_id : str, optional
        Multiplier ID for creating arrays of doors

    Returns
    -------
    Hole
        Door hole object

    Examples
    --------
    >>> # Simple door on X-boundary wall
    >>> door = CommonHoles.door(xb=(5, 5, 2, 4, 0, 2.1))

    >>> # Door with control logic
    >>> door = CommonHoles.door(
    ...     xb=(5, 5, 2, 4, 0, 2.1),
    ...     id="MAIN_DOOR",
    ...     ctrl_id="DOOR_OPEN_CTRL"
    ... )

    Notes
    -----
    Standard door dimensions are typically:
    - Width: 0.9-1.2 m
    - Height: 2.0-2.1 m
    """
    if isinstance(xb, tuple):
        xb = Bounds3D.of(*xb)
    return Hole(
        xb=xb,
        id=id,
        ctrl_id=ctrl_id,
        devc_id=devc_id,
        color=color,
        mult_id=mult_id,
    )

window staticmethod

window(
    xb,
    id=None,
    ctrl_id=None,
    devc_id=None,
    color="CYAN",
    transparency=0.5,
    mult_id=None,
)

Create a standard window opening.

PARAMETER	DESCRIPTION
xb	Window bounds (xmin, xmax, ymin, ymax, zmin, zmax). One dimension should have zero thickness (planar opening). TYPE: tuple or Bounds3D
id	Hole identifier TYPE: str DEFAULT: None
ctrl_id	Control ID for window operation (e.g., breakage logic) TYPE: str DEFAULT: None
devc_id	Device ID for window operation TYPE: str DEFAULT: None
color	Visualization color (default: 'CYAN') TYPE: str DEFAULT: 'CYAN'
transparency	Visualization transparency 0-1 (default: 0.5) TYPE: float DEFAULT: 0.5
mult_id	Multiplier ID for creating arrays of windows TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Hole	Window hole object

Examples:

>>> # Simple window on X-boundary wall
>>> window = CommonHoles.window(xb=(0, 0, 2, 3, 1, 2))

>>> # Window with breakage control
>>> window = CommonHoles.window(
...     xb=(0, 0, 2, 3, 1, 2),
...     id="WINDOW_1",
...     ctrl_id="GLASS_BREAK_CTRL"
... )

Notes

Windows are typically placed 0.9-1.0 m above floor level. Standard window heights are 1.0-1.5 m.

Source code in src/pyfds/builders/libraries/holes.py

@staticmethod
def window(
    xb: tuple[float, float, float, float, float, float] | Bounds3D,
    id: str | None = None,
    ctrl_id: str | None = None,
    devc_id: str | None = None,
    color: str = "CYAN",
    transparency: float = 0.5,
    mult_id: str | None = None,
) -> Hole:
    """
    Create a standard window opening.

    Parameters
    ----------
    xb : tuple or Bounds3D
        Window bounds (xmin, xmax, ymin, ymax, zmin, zmax).
        One dimension should have zero thickness (planar opening).
    id : str, optional
        Hole identifier
    ctrl_id : str, optional
        Control ID for window operation (e.g., breakage logic)
    devc_id : str, optional
        Device ID for window operation
    color : str, optional
        Visualization color (default: 'CYAN')
    transparency : float, optional
        Visualization transparency 0-1 (default: 0.5)
    mult_id : str, optional
        Multiplier ID for creating arrays of windows

    Returns
    -------
    Hole
        Window hole object

    Examples
    --------
    >>> # Simple window on X-boundary wall
    >>> window = CommonHoles.window(xb=(0, 0, 2, 3, 1, 2))

    >>> # Window with breakage control
    >>> window = CommonHoles.window(
    ...     xb=(0, 0, 2, 3, 1, 2),
    ...     id="WINDOW_1",
    ...     ctrl_id="GLASS_BREAK_CTRL"
    ... )

    Notes
    -----
    Windows are typically placed 0.9-1.0 m above floor level.
    Standard window heights are 1.0-1.5 m.
    """
    if isinstance(xb, tuple):
        xb = Bounds3D.of(*xb)
    return Hole(
        xb=xb,
        id=id,
        ctrl_id=ctrl_id,
        devc_id=devc_id,
        color=color,
        transparency=transparency,
        mult_id=mult_id,
    )

CommonMaterials

Library of predefined common materials.

Provides easy access to standard building and structural materials with typical thermal properties.

Examples:

>>> concrete = CommonMaterials.concrete()
>>> steel = CommonMaterials.steel()
>>> wood = CommonMaterials.wood()

Functions

concrete staticmethod

concrete()

Standard concrete.

Properties

• Density: 2400 kg/m³
• Thermal conductivity: 1.6 W/(m·K)
• Specific heat: 0.88 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Concrete material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def concrete() -> Material:
    """
    Standard concrete.

    Properties
    ----------
    - Density: 2400 kg/m³
    - Thermal conductivity: 1.6 W/(m·K)
    - Specific heat: 0.88 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Concrete material object
    """
    return (
        MaterialBuilder("CONCRETE")
        .density(2400)
        .thermal_conductivity(1.6)
        .specific_heat(0.88)
        .emissivity(0.9)
        .build()
    )

gypsum staticmethod

gypsum()

Gypsum board (drywall).

Properties

• Density: 930 kg/m³
• Thermal conductivity: 0.48 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Gypsum board material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def gypsum() -> Material:
    """
    Gypsum board (drywall).

    Properties
    ----------
    - Density: 930 kg/m³
    - Thermal conductivity: 0.48 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Gypsum board material object
    """
    return (
        MaterialBuilder("GYPSUM")
        .density(930)
        .thermal_conductivity(0.48)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

steel staticmethod

steel()

Structural steel.

Properties

• Density: 7850 kg/m³
• Thermal conductivity: 45.8 W/(m·K)
• Specific heat: 0.46 kJ/(kg·K)
• Emissivity: 0.7

RETURNS	DESCRIPTION
Material	Steel material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def steel() -> Material:
    """
    Structural steel.

    Properties
    ----------
    - Density: 7850 kg/m³
    - Thermal conductivity: 45.8 W/(m·K)
    - Specific heat: 0.46 kJ/(kg·K)
    - Emissivity: 0.7

    Returns
    -------
    Material
        Steel material object
    """
    return (
        MaterialBuilder("STEEL")
        .density(7850)
        .thermal_conductivity(45.8)
        .specific_heat(0.46)
        .emissivity(0.7)
        .build()
    )

aluminum staticmethod

aluminum()

Aluminum.

Properties

• Density: 2700 kg/m³
• Thermal conductivity: 237 W/(m·K)
• Specific heat: 0.90 kJ/(kg·K)
• Emissivity: 0.2

RETURNS	DESCRIPTION
Material	Aluminum material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def aluminum() -> Material:
    """
    Aluminum.

    Properties
    ----------
    - Density: 2700 kg/m³
    - Thermal conductivity: 237 W/(m·K)
    - Specific heat: 0.90 kJ/(kg·K)
    - Emissivity: 0.2

    Returns
    -------
    Material
        Aluminum material object
    """
    return (
        MaterialBuilder("ALUMINUM")
        .density(2700)
        .thermal_conductivity(237)
        .specific_heat(0.90)
        .emissivity(0.2)
        .build()
    )

brick staticmethod

brick()

Standard brick.

Properties

• Density: 1920 kg/m³
• Thermal conductivity: 0.69 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Brick material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def brick() -> Material:
    """
    Standard brick.

    Properties
    ----------
    - Density: 1920 kg/m³
    - Thermal conductivity: 0.69 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Brick material object
    """
    return (
        MaterialBuilder("BRICK")
        .density(1920)
        .thermal_conductivity(0.69)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

wood staticmethod

wood()

Wood (pine).

Properties

• Density: 500 kg/m³
• Thermal conductivity: 0.13 W/(m·K)
• Specific heat: 2.5 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Wood material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def wood() -> Material:
    """
    Wood (pine).

    Properties
    ----------
    - Density: 500 kg/m³
    - Thermal conductivity: 0.13 W/(m·K)
    - Specific heat: 2.5 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Wood material object
    """
    return (
        MaterialBuilder("WOOD")
        .density(500)
        .thermal_conductivity(0.13)
        .specific_heat(2.5)
        .emissivity(0.9)
        .build()
    )

fiberglass_insulation staticmethod

fiberglass_insulation()

Fiberglass insulation.

Properties

• Density: 12 kg/m³
• Thermal conductivity: 0.04 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Fiberglass insulation material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def fiberglass_insulation() -> Material:
    """
    Fiberglass insulation.

    Properties
    ----------
    - Density: 12 kg/m³
    - Thermal conductivity: 0.04 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Fiberglass insulation material object
    """
    return (
        MaterialBuilder("FIBERGLASS")
        .density(12)
        .thermal_conductivity(0.04)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

ceramic staticmethod

ceramic()

Ceramic.

Properties

• Density: 2300 kg/m³
• Thermal conductivity: 1.5 W/(m·K)
• Specific heat: 0.90 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Ceramic material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def ceramic() -> Material:
    """
    Ceramic.

    Properties
    ----------
    - Density: 2300 kg/m³
    - Thermal conductivity: 1.5 W/(m·K)
    - Specific heat: 0.90 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Ceramic material object
    """
    return (
        MaterialBuilder("CERAMIC")
        .density(2300)
        .thermal_conductivity(1.5)
        .specific_heat(0.90)
        .emissivity(0.9)
        .build()
    )

glass staticmethod

glass()

Glass.

Properties

• Density: 2500 kg/m³
• Thermal conductivity: 0.80 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Glass material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def glass() -> Material:
    """
    Glass.

    Properties
    ----------
    - Density: 2500 kg/m³
    - Thermal conductivity: 0.80 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Glass material object
    """
    return (
        MaterialBuilder("GLASS")
        .density(2500)
        .thermal_conductivity(0.80)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

copper staticmethod

copper()

Copper.

Properties

• Density: 8930 kg/m³
• Thermal conductivity: 401 W/(m·K)
• Specific heat: 0.39 kJ/(kg·K)
• Emissivity: 0.03

RETURNS	DESCRIPTION
Material	Copper material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def copper() -> Material:
    """
    Copper.

    Properties
    ----------
    - Density: 8930 kg/m³
    - Thermal conductivity: 401 W/(m·K)
    - Specific heat: 0.39 kJ/(kg·K)
    - Emissivity: 0.03

    Returns
    -------
    Material
        Copper material object
    """
    return (
        MaterialBuilder("COPPER")
        .density(8930)
        .thermal_conductivity(401)
        .specific_heat(0.39)
        .emissivity(0.03)
        .build()
    )

CommonProps

Library of predefined device properties.

Provides factory methods for common sprinklers, smoke detectors, heat detectors, and nozzles with typical configurations.

Examples:

>>> sprinkler = CommonProps.quick_response_sprinkler()
>>> detector = CommonProps.smoke_detector(id="SMOKE_DET")
>>> heat_det = CommonProps.heat_detector(id="HEAT_DET", activation_temp=74)

Functions

sprinkler staticmethod

sprinkler(
    id,
    activation_temp,
    rti,
    flow_rate=None,
    k_factor=None,
    spray_angle=None,
    c_factor=None,
    pressure=None,
    orifice_diameter=None,
)

Create a sprinkler property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
activation_temp	Activation temperature in °C TYPE: float
rti	Response Time Index in (m·s)^0.5 TYPE: float
flow_rate	Flow rate in L/min TYPE: float DEFAULT: None
k_factor	K-factor in (L/min)/bar^0.5 TYPE: float DEFAULT: None
spray_angle	Spray angle limits in degrees TYPE: tuple[float, float] DEFAULT: None
c_factor	Sprinkler C-factor TYPE: float DEFAULT: None
pressure	Operating pressure in Pa TYPE: float DEFAULT: None
orifice_diameter	Orifice diameter in m TYPE: float DEFAULT: None

RETURNS	DESCRIPTION
Property	Sprinkler property object

Examples:

>>> # Quick response sprinkler
>>> sprinkler = CommonProps.sprinkler(
...     id='QUICK_RESPONSE',
...     activation_temp=68,
...     rti=50,
...     flow_rate=60
... )

>>> # Standard response sprinkler with pressure
>>> sprinkler = CommonProps.sprinkler(
...     id='STANDARD',
...     activation_temp=74,
...     rti=100,
...     k_factor=80,
...     pressure=200000
... )

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def sprinkler(
    id: str,
    activation_temp: float,
    rti: float,
    flow_rate: float | None = None,
    k_factor: float | None = None,
    spray_angle: tuple[float, float] | None = None,
    c_factor: float | None = None,
    pressure: float | None = None,
    orifice_diameter: float | None = None,
) -> Property:
    """
    Create a sprinkler property.

    Parameters
    ----------
    id : str
        Unique property identifier
    activation_temp : float
        Activation temperature in °C
    rti : float
        Response Time Index in (m·s)^0.5
    flow_rate : float, optional
        Flow rate in L/min
    k_factor : float, optional
        K-factor in (L/min)/bar^0.5
    spray_angle : tuple[float, float], optional
        Spray angle limits in degrees
    c_factor : float, optional
        Sprinkler C-factor
    pressure : float, optional
        Operating pressure in Pa
    orifice_diameter : float, optional
        Orifice diameter in m

    Returns
    -------
    Property
        Sprinkler property object

    Examples
    --------
    >>> # Quick response sprinkler
    >>> sprinkler = CommonProps.sprinkler(
    ...     id='QUICK_RESPONSE',
    ...     activation_temp=68,
    ...     rti=50,
    ...     flow_rate=60
    ... )

    >>> # Standard response sprinkler with pressure
    >>> sprinkler = CommonProps.sprinkler(
    ...     id='STANDARD',
    ...     activation_temp=74,
    ...     rti=100,
    ...     k_factor=80,
    ...     pressure=200000
    ... )
    """
    return Property(
        id=id,
        activation_temperature=activation_temp,
        rti=rti,
        flow_rate=flow_rate,
        k_factor=k_factor,
        spray_angle=spray_angle,
        c_factor=c_factor,
        pressure=pressure,
        orifice_diameter=orifice_diameter,
    )

smoke_detector staticmethod

smoke_detector(
    id,
    activation_obscuration=3.28,
    alpha_e=None,
    beta_e=None,
    smokeview_id=None,
)

Create a smoke detector property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
activation_obscuration	Activation obscuration in %/m (default: 3.28, UL standard) TYPE: float DEFAULT: 3.28
alpha_e	Extinction coefficient in 1/m TYPE: float DEFAULT: None
beta_e	Scattering coefficient in 1/m TYPE: float DEFAULT: None
smokeview_id	Smokeview object ID for visualization TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Property	Smoke detector property object

Examples:

>>> # Basic smoke detector
>>> detector = CommonProps.smoke_detector(
...     id='PHOTOELECTRIC',
...     activation_obscuration=3.28
... )

>>> # Smoke detector with optical properties
>>> detector = CommonProps.smoke_detector(
...     id='OPTICAL',
...     activation_obscuration=3.28,
...     alpha_e=0.5,
...     beta_e=0.3
... )

Notes

Default value of 3.28 %/m is the UL listed smoke detector sensitivity.

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def smoke_detector(
    id: str,
    activation_obscuration: float = 3.28,
    alpha_e: float | None = None,
    beta_e: float | None = None,
    smokeview_id: str | None = None,
) -> Property:
    """
    Create a smoke detector property.

    Parameters
    ----------
    id : str
        Unique property identifier
    activation_obscuration : float, optional
        Activation obscuration in %/m (default: 3.28, UL standard)
    alpha_e : float, optional
        Extinction coefficient in 1/m
    beta_e : float, optional
        Scattering coefficient in 1/m
    smokeview_id : str, optional
        Smokeview object ID for visualization

    Returns
    -------
    Property
        Smoke detector property object

    Examples
    --------
    >>> # Basic smoke detector
    >>> detector = CommonProps.smoke_detector(
    ...     id='PHOTOELECTRIC',
    ...     activation_obscuration=3.28
    ... )

    >>> # Smoke detector with optical properties
    >>> detector = CommonProps.smoke_detector(
    ...     id='OPTICAL',
    ...     activation_obscuration=3.28,
    ...     alpha_e=0.5,
    ...     beta_e=0.3
    ... )

    Notes
    -----
    Default value of 3.28 %/m is the UL listed smoke detector sensitivity.
    """
    return Property(
        id=id,
        quantity="CHAMBER_OBSCURATION",
        activation_obscuration=activation_obscuration,
        alpha_e=alpha_e,
        beta_e=beta_e,
        smokeview_id=smokeview_id,
    )

heat_detector staticmethod

heat_detector(
    id,
    activation_temp,
    rti=5.0,
    bead_diameter=None,
    bead_density=None,
    bead_specific_heat=None,
)

Create a heat detector property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
activation_temp	Activation temperature in °C TYPE: float
rti	Response Time Index in (m·s)^0.5, default: 5.0 TYPE: float DEFAULT: 5.0
bead_diameter	Detector bead diameter in m TYPE: float DEFAULT: None
bead_density	Detector bead density in kg/m³ TYPE: float DEFAULT: None
bead_specific_heat	Bead specific heat in kJ/kg/K TYPE: float DEFAULT: None

RETURNS	DESCRIPTION
Property	Heat detector property object

Examples:

>>> # Basic heat detector
>>> heat_det = CommonProps.heat_detector(
...     id='HEAT_DET',
...     activation_temp=74
... )

>>> # Heat detector with bead properties
>>> heat_det = CommonProps.heat_detector(
...     id='HEAT_DET_CUSTOM',
...     activation_temp=74,
...     rti=10.0,
...     bead_diameter=0.001,
...     bead_density=8000
... )

Notes

Default RTI of 5.0 represents a fast-response heat detector.

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def heat_detector(
    id: str,
    activation_temp: float,
    rti: float = 5.0,
    bead_diameter: float | None = None,
    bead_density: float | None = None,
    bead_specific_heat: float | None = None,
) -> Property:
    """
    Create a heat detector property.

    Parameters
    ----------
    id : str
        Unique property identifier
    activation_temp : float
        Activation temperature in °C
    rti : float, optional
        Response Time Index in (m·s)^0.5, default: 5.0
    bead_diameter : float, optional
        Detector bead diameter in m
    bead_density : float, optional
        Detector bead density in kg/m³
    bead_specific_heat : float, optional
        Bead specific heat in kJ/kg/K

    Returns
    -------
    Property
        Heat detector property object

    Examples
    --------
    >>> # Basic heat detector
    >>> heat_det = CommonProps.heat_detector(
    ...     id='HEAT_DET',
    ...     activation_temp=74
    ... )

    >>> # Heat detector with bead properties
    >>> heat_det = CommonProps.heat_detector(
    ...     id='HEAT_DET_CUSTOM',
    ...     activation_temp=74,
    ...     rti=10.0,
    ...     bead_diameter=0.001,
    ...     bead_density=8000
    ... )

    Notes
    -----
    Default RTI of 5.0 represents a fast-response heat detector.
    """
    return Property(
        id=id,
        activation_temperature=activation_temp,
        rti=rti,
        bead_diameter=bead_diameter,
        bead_density=bead_density,
        bead_specific_heat=bead_specific_heat,
    )

nozzle staticmethod

nozzle(
    id,
    flow_rate=None,
    pressure=None,
    orifice_diameter=None,
    k_factor=None,
)

Create a nozzle/spray property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
flow_rate	Flow rate in L/min or kg/s TYPE: float DEFAULT: None
pressure	Operating pressure in Pa TYPE: float DEFAULT: None
orifice_diameter	Orifice diameter in m TYPE: float DEFAULT: None
k_factor	K-factor in (L/min)/bar^0.5 TYPE: float DEFAULT: None

RETURNS	DESCRIPTION
Property	Nozzle property object

Examples:

>>> # Nozzle with flow rate
>>> nozzle = CommonProps.nozzle(
...     id='SPRAY_NOZZLE',
...     flow_rate=50,
...     pressure=300000
... )

>>> # Nozzle with k-factor
>>> nozzle = CommonProps.nozzle(
...     id='K_NOZZLE',
...     k_factor=80,
...     orifice_diameter=0.01
... )

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def nozzle(
    id: str,
    flow_rate: float | None = None,
    pressure: float | None = None,
    orifice_diameter: float | None = None,
    k_factor: float | None = None,
) -> Property:
    """
    Create a nozzle/spray property.

    Parameters
    ----------
    id : str
        Unique property identifier
    flow_rate : float, optional
        Flow rate in L/min or kg/s
    pressure : float, optional
        Operating pressure in Pa
    orifice_diameter : float, optional
        Orifice diameter in m
    k_factor : float, optional
        K-factor in (L/min)/bar^0.5

    Returns
    -------
    Property
        Nozzle property object

    Examples
    --------
    >>> # Nozzle with flow rate
    >>> nozzle = CommonProps.nozzle(
    ...     id='SPRAY_NOZZLE',
    ...     flow_rate=50,
    ...     pressure=300000
    ... )

    >>> # Nozzle with k-factor
    >>> nozzle = CommonProps.nozzle(
    ...     id='K_NOZZLE',
    ...     k_factor=80,
    ...     orifice_diameter=0.01
    ... )
    """
    return Property(
        id=id,
        flow_rate=flow_rate,
        pressure=pressure,
        orifice_diameter=orifice_diameter,
        k_factor=k_factor,
    )

quick_response_sprinkler staticmethod

quick_response_sprinkler(id='SPRINKLER_QR')

Create a standard quick-response sprinkler (68°C, RTI=50).

PARAMETER	DESCRIPTION
id	Unique property identifier, default: 'SPRINKLER_QR' TYPE: str DEFAULT: 'SPRINKLER_QR'

RETURNS	DESCRIPTION
Property	Quick-response sprinkler property

Examples:

>>> sprinkler = CommonProps.quick_response_sprinkler()

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def quick_response_sprinkler(id: str = "SPRINKLER_QR") -> Property:
    """
    Create a standard quick-response sprinkler (68°C, RTI=50).

    Parameters
    ----------
    id : str, optional
        Unique property identifier, default: 'SPRINKLER_QR'

    Returns
    -------
    Property
        Quick-response sprinkler property

    Examples
    --------
    >>> sprinkler = CommonProps.quick_response_sprinkler()
    """
    return CommonProps.sprinkler(id=id, activation_temp=68, rti=50, flow_rate=60)

standard_response_sprinkler staticmethod

standard_response_sprinkler(id='SPRINKLER_SR')

Create a standard-response sprinkler (74°C, RTI=100).

PARAMETER	DESCRIPTION
id	Unique property identifier, default: 'SPRINKLER_SR' TYPE: str DEFAULT: 'SPRINKLER_SR'

RETURNS	DESCRIPTION
Property	Standard-response sprinkler property

Examples:

>>> sprinkler = CommonProps.standard_response_sprinkler()

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def standard_response_sprinkler(id: str = "SPRINKLER_SR") -> Property:
    """
    Create a standard-response sprinkler (74°C, RTI=100).

    Parameters
    ----------
    id : str, optional
        Unique property identifier, default: 'SPRINKLER_SR'

    Returns
    -------
    Property
        Standard-response sprinkler property

    Examples
    --------
    >>> sprinkler = CommonProps.standard_response_sprinkler()
    """
    return CommonProps.sprinkler(id=id, activation_temp=74, rti=100, k_factor=80)

CommonRamps

Library of common ramp function patterns.

Provides predefined ramps for common fire growth scenarios, HVAC schedules, and other time-varying functions.

Examples:

>>> fire_ramp = CommonRamps.t_squared_fast(peak_hrr=2500)
>>> step_ramp = CommonRamps.step_at(t=60, value=1.0)

Functions

t_squared_slow staticmethod

t_squared_slow(peak_hrr, t_peak=600, id='T2_SLOW')

Slow t-squared fire growth (600s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 600 TYPE: float DEFAULT: 600
id	Ramp identifier, default: 'T2_SLOW' TYPE: str DEFAULT: 'T2_SLOW'

RETURNS	DESCRIPTION
Ramp	Slow growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_slow(peak_hrr=1500)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_slow(peak_hrr: float, t_peak: float = 600, id: str = "T2_SLOW") -> Ramp:
    """
    Slow t-squared fire growth (600s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 600
    id : str, optional
        Ramp identifier, default: 'T2_SLOW'

    Returns
    -------
    Ramp
        Slow growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_slow(peak_hrr=1500)
    """
    return RampBuilder(id).t_squared("SLOW", peak_hrr, t_peak).build()

t_squared_medium staticmethod

t_squared_medium(peak_hrr, t_peak=300, id='T2_MEDIUM')

Medium t-squared fire growth (300s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 300 TYPE: float DEFAULT: 300
id	Ramp identifier, default: 'T2_MEDIUM' TYPE: str DEFAULT: 'T2_MEDIUM'

RETURNS	DESCRIPTION
Ramp	Medium growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_medium(peak_hrr=2500)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_medium(peak_hrr: float, t_peak: float = 300, id: str = "T2_MEDIUM") -> Ramp:
    """
    Medium t-squared fire growth (300s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 300
    id : str, optional
        Ramp identifier, default: 'T2_MEDIUM'

    Returns
    -------
    Ramp
        Medium growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_medium(peak_hrr=2500)
    """
    return RampBuilder(id).t_squared("MEDIUM", peak_hrr, t_peak).build()

t_squared_fast staticmethod

t_squared_fast(peak_hrr, t_peak=150, id='T2_FAST')

Fast t-squared fire growth (150s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 150 TYPE: float DEFAULT: 150
id	Ramp identifier, default: 'T2_FAST' TYPE: str DEFAULT: 'T2_FAST'

RETURNS	DESCRIPTION
Ramp	Fast growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_fast(peak_hrr=3000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_fast(peak_hrr: float, t_peak: float = 150, id: str = "T2_FAST") -> Ramp:
    """
    Fast t-squared fire growth (150s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 150
    id : str, optional
        Ramp identifier, default: 'T2_FAST'

    Returns
    -------
    Ramp
        Fast growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_fast(peak_hrr=3000)
    """
    return RampBuilder(id).t_squared("FAST", peak_hrr, t_peak).build()

t_squared_ultrafast staticmethod

t_squared_ultrafast(peak_hrr, t_peak=75, id='T2_ULTRAFAST')

Ultrafast t-squared fire growth (75s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 75 TYPE: float DEFAULT: 75
id	Ramp identifier, default: 'T2_ULTRAFAST' TYPE: str DEFAULT: 'T2_ULTRAFAST'

RETURNS	DESCRIPTION
Ramp	Ultrafast growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_ultrafast(peak_hrr=5000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_ultrafast(peak_hrr: float, t_peak: float = 75, id: str = "T2_ULTRAFAST") -> Ramp:
    """
    Ultrafast t-squared fire growth (75s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 75
    id : str, optional
        Ramp identifier, default: 'T2_ULTRAFAST'

    Returns
    -------
    Ramp
        Ultrafast growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_ultrafast(peak_hrr=5000)
    """
    return RampBuilder(id).t_squared("ULTRAFAST", peak_hrr, t_peak).build()

step_at staticmethod

step_at(t, value=1.0, id='STEP')

Step function at specified time.

PARAMETER	DESCRIPTION
t	Time at which step occurs in seconds TYPE: float
value	Value after step, default: 1.0 TYPE: float DEFAULT: 1.0
id	Ramp identifier, default: 'STEP' TYPE: str DEFAULT: 'STEP'

RETURNS	DESCRIPTION
Ramp	Step function ramp

Examples:

>>> ramp = CommonRamps.step_at(t=60, value=1.0)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def step_at(t: float, value: float = 1.0, id: str = "STEP") -> Ramp:
    """
    Step function at specified time.

    Parameters
    ----------
    t : float
        Time at which step occurs in seconds
    value : float, optional
        Value after step, default: 1.0
    id : str, optional
        Ramp identifier, default: 'STEP'

    Returns
    -------
    Ramp
        Step function ramp

    Examples
    --------
    >>> ramp = CommonRamps.step_at(t=60, value=1.0)
    """
    return RampBuilder(id).step(t, 0, value).build()

linear_growth staticmethod

linear_growth(t_end, f_end=1.0, id='LINEAR')

Linear growth from 0 to specified value.

PARAMETER	DESCRIPTION
t_end	End time in seconds TYPE: float
f_end	Final value, default: 1.0 TYPE: float DEFAULT: 1.0
id	Ramp identifier, default: 'LINEAR' TYPE: str DEFAULT: 'LINEAR'

RETURNS	DESCRIPTION
Ramp	Linear growth ramp

Examples:

>>> ramp = CommonRamps.linear_growth(t_end=300, f_end=1000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def linear_growth(t_end: float, f_end: float = 1.0, id: str = "LINEAR") -> Ramp:
    """
    Linear growth from 0 to specified value.

    Parameters
    ----------
    t_end : float
        End time in seconds
    f_end : float, optional
        Final value, default: 1.0
    id : str, optional
        Ramp identifier, default: 'LINEAR'

    Returns
    -------
    Ramp
        Linear growth ramp

    Examples
    --------
    >>> ramp = CommonRamps.linear_growth(t_end=300, f_end=1000)
    """
    return RampBuilder(id).linear(0, t_end, 0, f_end).build()

exponential_growth staticmethod

exponential_growth(t_end, f_end=1.0, id='EXPONENTIAL')

Exponential growth from 0 to specified value.

PARAMETER	DESCRIPTION
t_end	End time in seconds TYPE: float
f_end	Final value, default: 1.0 TYPE: float DEFAULT: 1.0
id	Ramp identifier, default: 'EXPONENTIAL' TYPE: str DEFAULT: 'EXPONENTIAL'

RETURNS	DESCRIPTION
Ramp	Exponential growth ramp

Examples:

>>> ramp = CommonRamps.exponential_growth(t_end=300, f_end=2000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def exponential_growth(t_end: float, f_end: float = 1.0, id: str = "EXPONENTIAL") -> Ramp:
    """
    Exponential growth from 0 to specified value.

    Parameters
    ----------
    t_end : float
        End time in seconds
    f_end : float, optional
        Final value, default: 1.0
    id : str, optional
        Ramp identifier, default: 'EXPONENTIAL'

    Returns
    -------
    Ramp
        Exponential growth ramp

    Examples
    --------
    >>> ramp = CommonRamps.exponential_growth(t_end=300, f_end=2000)
    """
    return RampBuilder(id).exponential(0, t_end, 0, f_end).build()

hvac_schedule_24h staticmethod

hvac_schedule_24h(
    on_time=8.0, off_time=18.0, id="HVAC_SCHEDULE"
)

24-hour HVAC on/off schedule.

PARAMETER	DESCRIPTION
on_time	Hour when HVAC turns on (0-24), default: 8.0 (8 AM) TYPE: float DEFAULT: 8.0
off_time	Hour when HVAC turns off (0-24), default: 18.0 (6 PM) TYPE: float DEFAULT: 18.0
id	Ramp identifier, default: 'HVAC_SCHEDULE' TYPE: str DEFAULT: 'HVAC_SCHEDULE'

RETURNS	DESCRIPTION
Ramp	HVAC schedule ramp (0=off, 1=on)

Examples:

>>> # On from 6 AM to 10 PM
>>> ramp = CommonRamps.hvac_schedule_24h(on_time=6, off_time=22)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def hvac_schedule_24h(
    on_time: float = 8.0,
    off_time: float = 18.0,
    id: str = "HVAC_SCHEDULE",
) -> Ramp:
    """
    24-hour HVAC on/off schedule.

    Parameters
    ----------
    on_time : float, optional
        Hour when HVAC turns on (0-24), default: 8.0 (8 AM)
    off_time : float, optional
        Hour when HVAC turns off (0-24), default: 18.0 (6 PM)
    id : str, optional
        Ramp identifier, default: 'HVAC_SCHEDULE'

    Returns
    -------
    Ramp
        HVAC schedule ramp (0=off, 1=on)

    Examples
    --------
    >>> # On from 6 AM to 10 PM
    >>> ramp = CommonRamps.hvac_schedule_24h(on_time=6, off_time=22)
    """
    # Convert hours to seconds
    on_seconds = on_time * 3600
    off_seconds = off_time * 3600

    return (
        RampBuilder(id)
        .add_point(0, 0)
        .add_point(on_seconds - 1e-6, 0)
        .add_point(on_seconds, 1)
        .add_point(off_seconds - 1e-6, 1)
        .add_point(off_seconds, 0)
        .add_point(86400, 0)  # 24 hours
        .build()
    )

Functions

get_fuel_info

get_fuel_info(name)

Get detailed information about a fuel.

PARAMETER	DESCRIPTION
name	Fuel name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
FuelData	Dictionary with fuel composition and properties

RAISES	DESCRIPTION
ValueError	If fuel name is not in database

Examples:

>>> info = get_fuel_info('PROPANE')
>>> print(f"Heat of combustion: {info['hoc']} kJ/kg")
Heat of combustion: 46000 kJ/kg

Source code in src/pyfds/builders/libraries/fuels.py

def get_fuel_info(name: str) -> FuelData:
    """
    Get detailed information about a fuel.

    Parameters
    ----------
    name : str
        Fuel name (case-insensitive)

    Returns
    -------
    FuelData
        Dictionary with fuel composition and properties

    Raises
    ------
    ValueError
        If fuel name is not in database

    Examples
    --------
    >>> info = get_fuel_info('PROPANE')
    >>> print(f"Heat of combustion: {info['hoc']} kJ/kg")
    Heat of combustion: 46000 kJ/kg
    """
    fuel_key = name.upper()
    if fuel_key not in FUEL_DATABASE:
        available = ", ".join(sorted(FUEL_DATABASE.keys()))
        raise ValueError(f"Unknown fuel '{name}'. Available fuels:\n{available}")

    return FUEL_DATABASE[fuel_key].copy()

list_fuels

list_fuels()

Get list of all available predefined fuels.

RETURNS	DESCRIPTION
list[str]	Sorted list of fuel names

Examples:

>>> fuels = list_fuels()
>>> print(fuels[:5])
['ACETONE', 'BUTANE', 'ETHANE', 'ETHANOL', 'GASOLINE']

Source code in src/pyfds/builders/libraries/fuels.py

def list_fuels() -> list[str]:
    """
    Get list of all available predefined fuels.

    Returns
    -------
    list[str]
        Sorted list of fuel names

    Examples
    --------
    >>> fuels = list_fuels()
    >>> print(fuels[:5])
    ['ACETONE', 'BUTANE', 'ETHANE', 'ETHANOL', 'GASOLINE']
    """
    return sorted(FUEL_DATABASE.keys())

create_standard_air

create_standard_air(humidity=40.0)

Create standard air composition dictionary.

This function creates a dictionary suitable for creating a lumped Species object representing standard atmospheric air composition. The composition is adjusted for humidity.

PARAMETER	DESCRIPTION
humidity	Relative humidity percentage (default: 40.0) Valid range: 0-100 TYPE: float DEFAULT: 40.0

RETURNS	DESCRIPTION
dict	Dictionary with species definition parameters suitable for creating a lumped Species with background=True

Examples:

>>> air_dict = create_standard_air(humidity=50.0)
>>> print(air_dict['id'])
AIR
>>> print(f"Components: {len(air_dict['spec_id'])}")
Components: 4

Notes

Standard dry air composition (by volume): - Nitrogen: 78.084% - Oxygen: 20.946% - Argon: 0.934% - Carbon dioxide: 0.036%

Water vapor is added based on humidity, displacing nitrogen and oxygen.

Source code in src/pyfds/builders/libraries/species.py

def create_standard_air(humidity: float = 40.0) -> dict:
    """
    Create standard air composition dictionary.

    This function creates a dictionary suitable for creating a lumped Species
    object representing standard atmospheric air composition. The composition
    is adjusted for humidity.

    Parameters
    ----------
    humidity : float, optional
        Relative humidity percentage (default: 40.0)
        Valid range: 0-100

    Returns
    -------
    dict
        Dictionary with species definition parameters suitable for
        creating a lumped Species with background=True

    Examples
    --------
    >>> air_dict = create_standard_air(humidity=50.0)
    >>> print(air_dict['id'])
    AIR
    >>> print(f"Components: {len(air_dict['spec_id'])}")
    Components: 4

    Notes
    -----
    Standard dry air composition (by volume):
    - Nitrogen: 78.084%
    - Oxygen: 20.946%
    - Argon: 0.934%
    - Carbon dioxide: 0.036%

    Water vapor is added based on humidity, displacing nitrogen and oxygen.
    """
    if not (0 <= humidity <= 100):
        raise ValueError("Humidity must be between 0 and 100 percent")

    # Standard dry air composition (volume fractions)
    dry_air = {
        "NITROGEN": 0.78084,
        "OXYGEN": 0.20946,
        "ARGON": 0.00934,
        "CARBON_DIOXIDE": 0.00036,
    }

    # Adjust for humidity (approximate - assumes 25°C, atmospheric pressure)
    # Water vapor volume fraction ≈ (humidity/100) * (saturation_vapor_pressure / atmospheric_pressure)
    # At 25°C, saturation vapor pressure of water is ~23.8 mmHg = 0.0317 atm
    # Atmospheric pressure = 1 atm
    # So maximum water vapor volume fraction ≈ 0.0317
    water_vapor_fraction = (humidity / 100.0) * 0.0317

    # Adjust dry air components (water vapor displaces N2 and O2 proportionally)
    total_dry = sum(dry_air.values())
    adjustment_factor = (total_dry - water_vapor_fraction) / total_dry

    adjusted_fractions = {}
    for species, fraction in dry_air.items():
        adjusted_fractions[species] = fraction * adjustment_factor

    # Add water vapor
    adjusted_fractions["WATER_VAPOR"] = water_vapor_fraction

    # Convert to mass fractions (need molecular weights)
    species_list = list(adjusted_fractions.keys())

    # Calculate mass fractions properly
    total_mass = sum(
        adjusted_fractions[species] * get_species_info(species)["mw"]
        for species in adjusted_fractions
    )

    mass_fractions = [
        (adjusted_fractions[species] * get_species_info(species)["mw"]) / total_mass
        for species in species_list
    ]

    return {
        "id": "AIR",
        "background": True,
        "spec_id": species_list,
        "mass_fraction": mass_fractions,
        "description": f"Standard air (humidity: {humidity}%)",
    }

get_species_formula

get_species_formula(name)

Get the chemical formula of a predefined species.

PARAMETER	DESCRIPTION
name	Species name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
str	Chemical formula

Examples:

>>> formula = get_species_formula('PROPANE')
>>> print(f"Propane formula: {formula}")
Propane formula: C3H8

Source code in src/pyfds/builders/libraries/species.py

def get_species_formula(name: str) -> str:
    """
    Get the chemical formula of a predefined species.

    Parameters
    ----------
    name : str
        Species name (case-insensitive)

    Returns
    -------
    str
        Chemical formula

    Examples
    --------
    >>> formula = get_species_formula('PROPANE')
    >>> print(f"Propane formula: {formula}")
    Propane formula: C3H8
    """
    info = get_species_info(name)
    return str(info["formula"])

get_species_info

get_species_info(name)

Get detailed information about a predefined species.

PARAMETER	DESCRIPTION
name	Species name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
dict	Dictionary with species properties including formula, molecular weight, and description

RAISES	DESCRIPTION
ValueError	If species name is not in database

Examples:

>>> info = get_species_info('PROPANE')
>>> print(f"Formula: {info['formula']}, MW: {info['mw']} g/mol")
Formula: C3H8, MW: 44.0956 g/mol

>>> info = get_species_info('oxygen')
>>> print(f"Description: {info['description']}")
Description: Oxygen (air component)

Source code in src/pyfds/builders/libraries/species.py

def get_species_info(name: str) -> dict[str, Any]:
    """
    Get detailed information about a predefined species.

    Parameters
    ----------
    name : str
        Species name (case-insensitive)

    Returns
    -------
    dict
        Dictionary with species properties including formula, molecular weight,
        and description

    Raises
    ------
    ValueError
        If species name is not in database

    Examples
    --------
    >>> info = get_species_info('PROPANE')
    >>> print(f"Formula: {info['formula']}, MW: {info['mw']} g/mol")
    Formula: C3H8, MW: 44.0956 g/mol

    >>> info = get_species_info('oxygen')
    >>> print(f"Description: {info['description']}")
    Description: Oxygen (air component)
    """
    species_key = name.upper()
    if species_key not in PREDEFINED_SPECIES:
        available = ", ".join(sorted(PREDEFINED_SPECIES.keys()))
        raise ValueError(f"Unknown species '{name}'. Available species:\n{available}")

    return PREDEFINED_SPECIES[species_key].copy()

get_species_molecular_weight

get_species_molecular_weight(name)

Get the molecular weight of a predefined species.

This is a convenience function for quickly accessing molecular weights.

PARAMETER	DESCRIPTION
name	Species name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
float	Molecular weight in g/mol

Examples:

>>> mw = get_species_molecular_weight('WATER_VAPOR')
>>> print(f"Water molecular weight: {mw} g/mol")
Water molecular weight: 18.0153 g/mol

Source code in src/pyfds/builders/libraries/species.py

def get_species_molecular_weight(name: str) -> float:
    """
    Get the molecular weight of a predefined species.

    This is a convenience function for quickly accessing molecular weights.

    Parameters
    ----------
    name : str
        Species name (case-insensitive)

    Returns
    -------
    float
        Molecular weight in g/mol

    Examples
    --------
    >>> mw = get_species_molecular_weight('WATER_VAPOR')
    >>> print(f"Water molecular weight: {mw} g/mol")
    Water molecular weight: 18.0153 g/mol
    """
    info = get_species_info(name)
    return float(info["mw"])

is_predefined

is_predefined(name)

Check if a species name is in the predefined database.

PARAMETER	DESCRIPTION
name	Species name to check (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
bool	True if species is predefined, False otherwise

Examples:

>>> is_predefined('METHANE')
True
>>> is_predefined('CUSTOM_FUEL')
False
>>> is_predefined('methane')  # Case insensitive
True

Source code in src/pyfds/builders/libraries/species.py

def is_predefined(name: str) -> bool:
    """
    Check if a species name is in the predefined database.

    Parameters
    ----------
    name : str
        Species name to check (case-insensitive)

    Returns
    -------
    bool
        True if species is predefined, False otherwise

    Examples
    --------
    >>> is_predefined('METHANE')
    True
    >>> is_predefined('CUSTOM_FUEL')
    False
    >>> is_predefined('methane')  # Case insensitive
    True
    """
    return name.upper() in PREDEFINED_SPECIES

list_predefined_species

list_predefined_species()

Get list of all available predefined species.

RETURNS	DESCRIPTION
list[str]	Sorted list of species names

Examples:

>>> species = list_predefined_species()
>>> print(f"Available species: {len(species)}")
Available species: 35
>>> print(species[:5])
['ACETONE', 'ACETYLENE', 'AMMONIA', 'ARGON', 'BENZENE']

Source code in src/pyfds/builders/libraries/species.py

def list_predefined_species() -> list[str]:
    """
    Get list of all available predefined species.

    Returns
    -------
    list[str]
        Sorted list of species names

    Examples
    --------
    >>> species = list_predefined_species()
    >>> print(f"Available species: {len(species)}")
    Available species: 35
    >>> print(species[:5])
    ['ACETONE', 'ACETYLENE', 'AMMONIA', 'ARGON', 'BENZENE']
    """
    return sorted(PREDEFINED_SPECIES.keys())

Overview

Builder libraries provide pre-configured objects for common scenarios. Instead of manually configuring every parameter, you can use factory functions to create standard materials, props, ramps, and more with sensible defaults.

Importing Libraries

from pyfds.builders.libraries import (
    CommonMaterials,
    CommonProps,
    CommonHoles,
    CommonRamps,
    CommonSpecies,
    CommonFuels,
)

Common Materials

Pre-configured material definitions.

materials

Common building and structural materials library.

Classes

CommonMaterials

Library of predefined common materials.

Provides easy access to standard building and structural materials with typical thermal properties.

Examples:

>>> concrete = CommonMaterials.concrete()
>>> steel = CommonMaterials.steel()
>>> wood = CommonMaterials.wood()

Functions

concrete staticmethod

concrete()

Standard concrete.

Properties

• Density: 2400 kg/m³
• Thermal conductivity: 1.6 W/(m·K)
• Specific heat: 0.88 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Concrete material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def concrete() -> Material:
    """
    Standard concrete.

    Properties
    ----------
    - Density: 2400 kg/m³
    - Thermal conductivity: 1.6 W/(m·K)
    - Specific heat: 0.88 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Concrete material object
    """
    return (
        MaterialBuilder("CONCRETE")
        .density(2400)
        .thermal_conductivity(1.6)
        .specific_heat(0.88)
        .emissivity(0.9)
        .build()
    )

gypsum staticmethod

gypsum()

Gypsum board (drywall).

Properties

• Density: 930 kg/m³
• Thermal conductivity: 0.48 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Gypsum board material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def gypsum() -> Material:
    """
    Gypsum board (drywall).

    Properties
    ----------
    - Density: 930 kg/m³
    - Thermal conductivity: 0.48 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Gypsum board material object
    """
    return (
        MaterialBuilder("GYPSUM")
        .density(930)
        .thermal_conductivity(0.48)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

steel staticmethod

steel()

Structural steel.

Properties

• Density: 7850 kg/m³
• Thermal conductivity: 45.8 W/(m·K)
• Specific heat: 0.46 kJ/(kg·K)
• Emissivity: 0.7

RETURNS	DESCRIPTION
Material	Steel material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def steel() -> Material:
    """
    Structural steel.

    Properties
    ----------
    - Density: 7850 kg/m³
    - Thermal conductivity: 45.8 W/(m·K)
    - Specific heat: 0.46 kJ/(kg·K)
    - Emissivity: 0.7

    Returns
    -------
    Material
        Steel material object
    """
    return (
        MaterialBuilder("STEEL")
        .density(7850)
        .thermal_conductivity(45.8)
        .specific_heat(0.46)
        .emissivity(0.7)
        .build()
    )

aluminum staticmethod

aluminum()

Aluminum.

Properties

• Density: 2700 kg/m³
• Thermal conductivity: 237 W/(m·K)
• Specific heat: 0.90 kJ/(kg·K)
• Emissivity: 0.2

RETURNS	DESCRIPTION
Material	Aluminum material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def aluminum() -> Material:
    """
    Aluminum.

    Properties
    ----------
    - Density: 2700 kg/m³
    - Thermal conductivity: 237 W/(m·K)
    - Specific heat: 0.90 kJ/(kg·K)
    - Emissivity: 0.2

    Returns
    -------
    Material
        Aluminum material object
    """
    return (
        MaterialBuilder("ALUMINUM")
        .density(2700)
        .thermal_conductivity(237)
        .specific_heat(0.90)
        .emissivity(0.2)
        .build()
    )

brick staticmethod

brick()

Standard brick.

Properties

• Density: 1920 kg/m³
• Thermal conductivity: 0.69 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Brick material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def brick() -> Material:
    """
    Standard brick.

    Properties
    ----------
    - Density: 1920 kg/m³
    - Thermal conductivity: 0.69 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Brick material object
    """
    return (
        MaterialBuilder("BRICK")
        .density(1920)
        .thermal_conductivity(0.69)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

wood staticmethod

wood()

Wood (pine).

Properties

• Density: 500 kg/m³
• Thermal conductivity: 0.13 W/(m·K)
• Specific heat: 2.5 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Wood material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def wood() -> Material:
    """
    Wood (pine).

    Properties
    ----------
    - Density: 500 kg/m³
    - Thermal conductivity: 0.13 W/(m·K)
    - Specific heat: 2.5 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Wood material object
    """
    return (
        MaterialBuilder("WOOD")
        .density(500)
        .thermal_conductivity(0.13)
        .specific_heat(2.5)
        .emissivity(0.9)
        .build()
    )

fiberglass_insulation staticmethod

fiberglass_insulation()

Fiberglass insulation.

Properties

• Density: 12 kg/m³
• Thermal conductivity: 0.04 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Fiberglass insulation material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def fiberglass_insulation() -> Material:
    """
    Fiberglass insulation.

    Properties
    ----------
    - Density: 12 kg/m³
    - Thermal conductivity: 0.04 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Fiberglass insulation material object
    """
    return (
        MaterialBuilder("FIBERGLASS")
        .density(12)
        .thermal_conductivity(0.04)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

ceramic staticmethod

ceramic()

Ceramic.

Properties

• Density: 2300 kg/m³
• Thermal conductivity: 1.5 W/(m·K)
• Specific heat: 0.90 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Ceramic material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def ceramic() -> Material:
    """
    Ceramic.

    Properties
    ----------
    - Density: 2300 kg/m³
    - Thermal conductivity: 1.5 W/(m·K)
    - Specific heat: 0.90 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Ceramic material object
    """
    return (
        MaterialBuilder("CERAMIC")
        .density(2300)
        .thermal_conductivity(1.5)
        .specific_heat(0.90)
        .emissivity(0.9)
        .build()
    )

glass staticmethod

glass()

Glass.

Properties

• Density: 2500 kg/m³
• Thermal conductivity: 0.80 W/(m·K)
• Specific heat: 0.84 kJ/(kg·K)
• Emissivity: 0.9

RETURNS	DESCRIPTION
Material	Glass material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def glass() -> Material:
    """
    Glass.

    Properties
    ----------
    - Density: 2500 kg/m³
    - Thermal conductivity: 0.80 W/(m·K)
    - Specific heat: 0.84 kJ/(kg·K)
    - Emissivity: 0.9

    Returns
    -------
    Material
        Glass material object
    """
    return (
        MaterialBuilder("GLASS")
        .density(2500)
        .thermal_conductivity(0.80)
        .specific_heat(0.84)
        .emissivity(0.9)
        .build()
    )

copper staticmethod

copper()

Copper.

Properties

• Density: 8930 kg/m³
• Thermal conductivity: 401 W/(m·K)
• Specific heat: 0.39 kJ/(kg·K)
• Emissivity: 0.03

RETURNS	DESCRIPTION
Material	Copper material object

Source code in src/pyfds/builders/libraries/materials.py

@staticmethod
def copper() -> Material:
    """
    Copper.

    Properties
    ----------
    - Density: 8930 kg/m³
    - Thermal conductivity: 401 W/(m·K)
    - Specific heat: 0.39 kJ/(kg·K)
    - Emissivity: 0.03

    Returns
    -------
    Material
        Copper material object
    """
    return (
        MaterialBuilder("COPPER")
        .density(8930)
        .thermal_conductivity(401)
        .specific_heat(0.39)
        .emissivity(0.03)
        .build()
    )

Usage Examples

from pyfds.builders.libraries import CommonMaterials
from pyfds import Simulation

sim = Simulation(chid="test")

# Add standard materials
sim.add(CommonMaterials.concrete())
sim.add(CommonMaterials.steel())
sim.add(CommonMaterials.gypsum())
sim.add(CommonMaterials.wood())

# Use in surfaces
sim.add(Surface(
    id="CONCRETE_WALL",
    matl_id="CONCRETE",
    thickness=0.2
))

Available Materials

• concrete(): Standard concrete
• Density: 2400 kg/m³
• Conductivity: 1.8 W/(m·K)

• Specific heat: 0.88 kJ/(kg·K)

• steel(): Structural steel

• Density: 7850 kg/m³
• Conductivity: 45 W/(m·K)

• Specific heat: 0.46 kJ/(kg·K)

• gypsum(): Gypsum board

• Density: 790 kg/m³
• Conductivity: 0.48 W/(m·K)

• Specific heat: 1.09 kJ/(kg·K)

• wood(): Generic wood

• Density: 500 kg/m³
• Conductivity: 0.13 W/(m·K)

• Specific heat: 2.5 kJ/(kg·K)

• glass(): Standard glass

• Density: 2500 kg/m³
• Conductivity: 0.76 W/(m·K)

• Specific heat: 0.84 kJ/(kg·K)

• insulation(): Thermal insulation

• Density: 65 kg/m³
• Conductivity: 0.04 W/(m·K)
• Specific heat: 1.0 kJ/(kg·K)

Common Properties

Pre-configured device properties (sprinklers, detectors, etc.).

props

Common device property presets for sprinklers, detectors, and nozzles.

Classes

CommonProps

Library of predefined device properties.

Provides factory methods for common sprinklers, smoke detectors, heat detectors, and nozzles with typical configurations.

Examples:

>>> sprinkler = CommonProps.quick_response_sprinkler()
>>> detector = CommonProps.smoke_detector(id="SMOKE_DET")
>>> heat_det = CommonProps.heat_detector(id="HEAT_DET", activation_temp=74)

Functions

sprinkler staticmethod

sprinkler(
    id,
    activation_temp,
    rti,
    flow_rate=None,
    k_factor=None,
    spray_angle=None,
    c_factor=None,
    pressure=None,
    orifice_diameter=None,
)

Create a sprinkler property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
activation_temp	Activation temperature in °C TYPE: float
rti	Response Time Index in (m·s)^0.5 TYPE: float
flow_rate	Flow rate in L/min TYPE: float DEFAULT: None
k_factor	K-factor in (L/min)/bar^0.5 TYPE: float DEFAULT: None
spray_angle	Spray angle limits in degrees TYPE: tuple[float, float] DEFAULT: None
c_factor	Sprinkler C-factor TYPE: float DEFAULT: None
pressure	Operating pressure in Pa TYPE: float DEFAULT: None
orifice_diameter	Orifice diameter in m TYPE: float DEFAULT: None

RETURNS	DESCRIPTION
Property	Sprinkler property object

Examples:

>>> # Quick response sprinkler
>>> sprinkler = CommonProps.sprinkler(
...     id='QUICK_RESPONSE',
...     activation_temp=68,
...     rti=50,
...     flow_rate=60
... )

>>> # Standard response sprinkler with pressure
>>> sprinkler = CommonProps.sprinkler(
...     id='STANDARD',
...     activation_temp=74,
...     rti=100,
...     k_factor=80,
...     pressure=200000
... )

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def sprinkler(
    id: str,
    activation_temp: float,
    rti: float,
    flow_rate: float | None = None,
    k_factor: float | None = None,
    spray_angle: tuple[float, float] | None = None,
    c_factor: float | None = None,
    pressure: float | None = None,
    orifice_diameter: float | None = None,
) -> Property:
    """
    Create a sprinkler property.

    Parameters
    ----------
    id : str
        Unique property identifier
    activation_temp : float
        Activation temperature in °C
    rti : float
        Response Time Index in (m·s)^0.5
    flow_rate : float, optional
        Flow rate in L/min
    k_factor : float, optional
        K-factor in (L/min)/bar^0.5
    spray_angle : tuple[float, float], optional
        Spray angle limits in degrees
    c_factor : float, optional
        Sprinkler C-factor
    pressure : float, optional
        Operating pressure in Pa
    orifice_diameter : float, optional
        Orifice diameter in m

    Returns
    -------
    Property
        Sprinkler property object

    Examples
    --------
    >>> # Quick response sprinkler
    >>> sprinkler = CommonProps.sprinkler(
    ...     id='QUICK_RESPONSE',
    ...     activation_temp=68,
    ...     rti=50,
    ...     flow_rate=60
    ... )

    >>> # Standard response sprinkler with pressure
    >>> sprinkler = CommonProps.sprinkler(
    ...     id='STANDARD',
    ...     activation_temp=74,
    ...     rti=100,
    ...     k_factor=80,
    ...     pressure=200000
    ... )
    """
    return Property(
        id=id,
        activation_temperature=activation_temp,
        rti=rti,
        flow_rate=flow_rate,
        k_factor=k_factor,
        spray_angle=spray_angle,
        c_factor=c_factor,
        pressure=pressure,
        orifice_diameter=orifice_diameter,
    )

smoke_detector staticmethod

smoke_detector(
    id,
    activation_obscuration=3.28,
    alpha_e=None,
    beta_e=None,
    smokeview_id=None,
)

Create a smoke detector property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
activation_obscuration	Activation obscuration in %/m (default: 3.28, UL standard) TYPE: float DEFAULT: 3.28
alpha_e	Extinction coefficient in 1/m TYPE: float DEFAULT: None
beta_e	Scattering coefficient in 1/m TYPE: float DEFAULT: None
smokeview_id	Smokeview object ID for visualization TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Property	Smoke detector property object

Examples:

>>> # Basic smoke detector
>>> detector = CommonProps.smoke_detector(
...     id='PHOTOELECTRIC',
...     activation_obscuration=3.28
... )

>>> # Smoke detector with optical properties
>>> detector = CommonProps.smoke_detector(
...     id='OPTICAL',
...     activation_obscuration=3.28,
...     alpha_e=0.5,
...     beta_e=0.3
... )

Notes

Default value of 3.28 %/m is the UL listed smoke detector sensitivity.

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def smoke_detector(
    id: str,
    activation_obscuration: float = 3.28,
    alpha_e: float | None = None,
    beta_e: float | None = None,
    smokeview_id: str | None = None,
) -> Property:
    """
    Create a smoke detector property.

    Parameters
    ----------
    id : str
        Unique property identifier
    activation_obscuration : float, optional
        Activation obscuration in %/m (default: 3.28, UL standard)
    alpha_e : float, optional
        Extinction coefficient in 1/m
    beta_e : float, optional
        Scattering coefficient in 1/m
    smokeview_id : str, optional
        Smokeview object ID for visualization

    Returns
    -------
    Property
        Smoke detector property object

    Examples
    --------
    >>> # Basic smoke detector
    >>> detector = CommonProps.smoke_detector(
    ...     id='PHOTOELECTRIC',
    ...     activation_obscuration=3.28
    ... )

    >>> # Smoke detector with optical properties
    >>> detector = CommonProps.smoke_detector(
    ...     id='OPTICAL',
    ...     activation_obscuration=3.28,
    ...     alpha_e=0.5,
    ...     beta_e=0.3
    ... )

    Notes
    -----
    Default value of 3.28 %/m is the UL listed smoke detector sensitivity.
    """
    return Property(
        id=id,
        quantity="CHAMBER_OBSCURATION",
        activation_obscuration=activation_obscuration,
        alpha_e=alpha_e,
        beta_e=beta_e,
        smokeview_id=smokeview_id,
    )

heat_detector staticmethod

heat_detector(
    id,
    activation_temp,
    rti=5.0,
    bead_diameter=None,
    bead_density=None,
    bead_specific_heat=None,
)

Create a heat detector property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
activation_temp	Activation temperature in °C TYPE: float
rti	Response Time Index in (m·s)^0.5, default: 5.0 TYPE: float DEFAULT: 5.0
bead_diameter	Detector bead diameter in m TYPE: float DEFAULT: None
bead_density	Detector bead density in kg/m³ TYPE: float DEFAULT: None
bead_specific_heat	Bead specific heat in kJ/kg/K TYPE: float DEFAULT: None

RETURNS	DESCRIPTION
Property	Heat detector property object

Examples:

>>> # Basic heat detector
>>> heat_det = CommonProps.heat_detector(
...     id='HEAT_DET',
...     activation_temp=74
... )

>>> # Heat detector with bead properties
>>> heat_det = CommonProps.heat_detector(
...     id='HEAT_DET_CUSTOM',
...     activation_temp=74,
...     rti=10.0,
...     bead_diameter=0.001,
...     bead_density=8000
... )

Notes

Default RTI of 5.0 represents a fast-response heat detector.

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def heat_detector(
    id: str,
    activation_temp: float,
    rti: float = 5.0,
    bead_diameter: float | None = None,
    bead_density: float | None = None,
    bead_specific_heat: float | None = None,
) -> Property:
    """
    Create a heat detector property.

    Parameters
    ----------
    id : str
        Unique property identifier
    activation_temp : float
        Activation temperature in °C
    rti : float, optional
        Response Time Index in (m·s)^0.5, default: 5.0
    bead_diameter : float, optional
        Detector bead diameter in m
    bead_density : float, optional
        Detector bead density in kg/m³
    bead_specific_heat : float, optional
        Bead specific heat in kJ/kg/K

    Returns
    -------
    Property
        Heat detector property object

    Examples
    --------
    >>> # Basic heat detector
    >>> heat_det = CommonProps.heat_detector(
    ...     id='HEAT_DET',
    ...     activation_temp=74
    ... )

    >>> # Heat detector with bead properties
    >>> heat_det = CommonProps.heat_detector(
    ...     id='HEAT_DET_CUSTOM',
    ...     activation_temp=74,
    ...     rti=10.0,
    ...     bead_diameter=0.001,
    ...     bead_density=8000
    ... )

    Notes
    -----
    Default RTI of 5.0 represents a fast-response heat detector.
    """
    return Property(
        id=id,
        activation_temperature=activation_temp,
        rti=rti,
        bead_diameter=bead_diameter,
        bead_density=bead_density,
        bead_specific_heat=bead_specific_heat,
    )

nozzle staticmethod

nozzle(
    id,
    flow_rate=None,
    pressure=None,
    orifice_diameter=None,
    k_factor=None,
)

Create a nozzle/spray property.

PARAMETER	DESCRIPTION
id	Unique property identifier TYPE: str
flow_rate	Flow rate in L/min or kg/s TYPE: float DEFAULT: None
pressure	Operating pressure in Pa TYPE: float DEFAULT: None
orifice_diameter	Orifice diameter in m TYPE: float DEFAULT: None
k_factor	K-factor in (L/min)/bar^0.5 TYPE: float DEFAULT: None

RETURNS	DESCRIPTION
Property	Nozzle property object

Examples:

>>> # Nozzle with flow rate
>>> nozzle = CommonProps.nozzle(
...     id='SPRAY_NOZZLE',
...     flow_rate=50,
...     pressure=300000
... )

>>> # Nozzle with k-factor
>>> nozzle = CommonProps.nozzle(
...     id='K_NOZZLE',
...     k_factor=80,
...     orifice_diameter=0.01
... )

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def nozzle(
    id: str,
    flow_rate: float | None = None,
    pressure: float | None = None,
    orifice_diameter: float | None = None,
    k_factor: float | None = None,
) -> Property:
    """
    Create a nozzle/spray property.

    Parameters
    ----------
    id : str
        Unique property identifier
    flow_rate : float, optional
        Flow rate in L/min or kg/s
    pressure : float, optional
        Operating pressure in Pa
    orifice_diameter : float, optional
        Orifice diameter in m
    k_factor : float, optional
        K-factor in (L/min)/bar^0.5

    Returns
    -------
    Property
        Nozzle property object

    Examples
    --------
    >>> # Nozzle with flow rate
    >>> nozzle = CommonProps.nozzle(
    ...     id='SPRAY_NOZZLE',
    ...     flow_rate=50,
    ...     pressure=300000
    ... )

    >>> # Nozzle with k-factor
    >>> nozzle = CommonProps.nozzle(
    ...     id='K_NOZZLE',
    ...     k_factor=80,
    ...     orifice_diameter=0.01
    ... )
    """
    return Property(
        id=id,
        flow_rate=flow_rate,
        pressure=pressure,
        orifice_diameter=orifice_diameter,
        k_factor=k_factor,
    )

quick_response_sprinkler staticmethod

quick_response_sprinkler(id='SPRINKLER_QR')

Create a standard quick-response sprinkler (68°C, RTI=50).

PARAMETER	DESCRIPTION
id	Unique property identifier, default: 'SPRINKLER_QR' TYPE: str DEFAULT: 'SPRINKLER_QR'

RETURNS	DESCRIPTION
Property	Quick-response sprinkler property

Examples:

>>> sprinkler = CommonProps.quick_response_sprinkler()

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def quick_response_sprinkler(id: str = "SPRINKLER_QR") -> Property:
    """
    Create a standard quick-response sprinkler (68°C, RTI=50).

    Parameters
    ----------
    id : str, optional
        Unique property identifier, default: 'SPRINKLER_QR'

    Returns
    -------
    Property
        Quick-response sprinkler property

    Examples
    --------
    >>> sprinkler = CommonProps.quick_response_sprinkler()
    """
    return CommonProps.sprinkler(id=id, activation_temp=68, rti=50, flow_rate=60)

standard_response_sprinkler staticmethod

standard_response_sprinkler(id='SPRINKLER_SR')

Create a standard-response sprinkler (74°C, RTI=100).

PARAMETER	DESCRIPTION
id	Unique property identifier, default: 'SPRINKLER_SR' TYPE: str DEFAULT: 'SPRINKLER_SR'

RETURNS	DESCRIPTION
Property	Standard-response sprinkler property

Examples:

>>> sprinkler = CommonProps.standard_response_sprinkler()

Source code in src/pyfds/builders/libraries/props.py

@staticmethod
def standard_response_sprinkler(id: str = "SPRINKLER_SR") -> Property:
    """
    Create a standard-response sprinkler (74°C, RTI=100).

    Parameters
    ----------
    id : str, optional
        Unique property identifier, default: 'SPRINKLER_SR'

    Returns
    -------
    Property
        Standard-response sprinkler property

    Examples
    --------
    >>> sprinkler = CommonProps.standard_response_sprinkler()
    """
    return CommonProps.sprinkler(id=id, activation_temp=74, rti=100, k_factor=80)

Usage Examples

from pyfds.builders.libraries import CommonProps
from pyfds import Simulation

sim = Simulation(chid="test")

# Add standard sprinkler
sprinkler = CommonProps.quick_response_sprinkler()
sim.add(sprinkler)

# Add smoke detector
detector = CommonProps.smoke_detector()
sim.add(detector)

# Use in devices
sim.add(Device(
    id="SPK_1",
    prop_id="SPRINKLER_QR",
    xyz=(5, 5, 2.5)
))

Available Properties

• quick_response_sprinkler(): Quick-response sprinkler
• RTI: 50 (m·s)^0.5
• Activation temp: 68°C

• Spray angle: 60°

• standard_sprinkler(): Standard sprinkler

• RTI: 165 (m·s)^0.5
• Activation temp: 74°C

• Spray angle: 60°

• smoke_detector(): Photoelectric smoke detector

• Activation obscuration: 3.28%/m

• Beta: 1.8 (m/s)^-1

• heat_detector(): Fixed-temperature heat detector

• RTI: 100 (m·s)^0.5

• Activation temp: 57°C

• aspirating_detector(): Aspirating smoke detection

• Activation obscuration: 0.5%/m
• Sampling rate: 0.05 m³/s

Common Holes

Pre-configured hole geometries (doors, windows, etc.).

holes

Common hole presets for doors and windows.

Classes

CommonHoles

Library of predefined hole configurations.

Provides factory methods for common openings like doors and windows with sensible visualization defaults.

Examples:

>>> door = CommonHoles.door(xb=(5, 5, 2, 4, 0, 2.1))
>>> window = CommonHoles.window(xb=(0, 0, 2, 3, 1, 2))

Functions

door staticmethod

door(
    xb,
    id=None,
    ctrl_id=None,
    devc_id=None,
    color="BROWN",
    mult_id=None,
)

Create a standard door opening.

PARAMETER	DESCRIPTION
xb	Door bounds (xmin, xmax, ymin, ymax, zmin, zmax). One dimension should have zero thickness (planar opening). TYPE: tuple or Bounds3D
id	Hole identifier TYPE: str DEFAULT: None
ctrl_id	Control ID for door operation (e.g., open/close logic) TYPE: str DEFAULT: None
devc_id	Device ID for door operation TYPE: str DEFAULT: None
color	Visualization color (default: 'BROWN') TYPE: str DEFAULT: 'BROWN'
mult_id	Multiplier ID for creating arrays of doors TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Hole	Door hole object

Examples:

>>> # Simple door on X-boundary wall
>>> door = CommonHoles.door(xb=(5, 5, 2, 4, 0, 2.1))

>>> # Door with control logic
>>> door = CommonHoles.door(
...     xb=(5, 5, 2, 4, 0, 2.1),
...     id="MAIN_DOOR",
...     ctrl_id="DOOR_OPEN_CTRL"
... )

Notes

Standard door dimensions are typically: - Width: 0.9-1.2 m - Height: 2.0-2.1 m

Source code in src/pyfds/builders/libraries/holes.py

@staticmethod
def door(
    xb: tuple[float, float, float, float, float, float] | Bounds3D,
    id: str | None = None,
    ctrl_id: str | None = None,
    devc_id: str | None = None,
    color: str = "BROWN",
    mult_id: str | None = None,
) -> Hole:
    """
    Create a standard door opening.

    Parameters
    ----------
    xb : tuple or Bounds3D
        Door bounds (xmin, xmax, ymin, ymax, zmin, zmax).
        One dimension should have zero thickness (planar opening).
    id : str, optional
        Hole identifier
    ctrl_id : str, optional
        Control ID for door operation (e.g., open/close logic)
    devc_id : str, optional
        Device ID for door operation
    color : str, optional
        Visualization color (default: 'BROWN')
    mult_id : str, optional
        Multiplier ID for creating arrays of doors

    Returns
    -------
    Hole
        Door hole object

    Examples
    --------
    >>> # Simple door on X-boundary wall
    >>> door = CommonHoles.door(xb=(5, 5, 2, 4, 0, 2.1))

    >>> # Door with control logic
    >>> door = CommonHoles.door(
    ...     xb=(5, 5, 2, 4, 0, 2.1),
    ...     id="MAIN_DOOR",
    ...     ctrl_id="DOOR_OPEN_CTRL"
    ... )

    Notes
    -----
    Standard door dimensions are typically:
    - Width: 0.9-1.2 m
    - Height: 2.0-2.1 m
    """
    if isinstance(xb, tuple):
        xb = Bounds3D.of(*xb)
    return Hole(
        xb=xb,
        id=id,
        ctrl_id=ctrl_id,
        devc_id=devc_id,
        color=color,
        mult_id=mult_id,
    )

window staticmethod

window(
    xb,
    id=None,
    ctrl_id=None,
    devc_id=None,
    color="CYAN",
    transparency=0.5,
    mult_id=None,
)

Create a standard window opening.

PARAMETER	DESCRIPTION
xb	Window bounds (xmin, xmax, ymin, ymax, zmin, zmax). One dimension should have zero thickness (planar opening). TYPE: tuple or Bounds3D
id	Hole identifier TYPE: str DEFAULT: None
ctrl_id	Control ID for window operation (e.g., breakage logic) TYPE: str DEFAULT: None
devc_id	Device ID for window operation TYPE: str DEFAULT: None
color	Visualization color (default: 'CYAN') TYPE: str DEFAULT: 'CYAN'
transparency	Visualization transparency 0-1 (default: 0.5) TYPE: float DEFAULT: 0.5
mult_id	Multiplier ID for creating arrays of windows TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Hole	Window hole object

Examples:

>>> # Simple window on X-boundary wall
>>> window = CommonHoles.window(xb=(0, 0, 2, 3, 1, 2))

>>> # Window with breakage control
>>> window = CommonHoles.window(
...     xb=(0, 0, 2, 3, 1, 2),
...     id="WINDOW_1",
...     ctrl_id="GLASS_BREAK_CTRL"
... )

Notes

Windows are typically placed 0.9-1.0 m above floor level. Standard window heights are 1.0-1.5 m.

Source code in src/pyfds/builders/libraries/holes.py

@staticmethod
def window(
    xb: tuple[float, float, float, float, float, float] | Bounds3D,
    id: str | None = None,
    ctrl_id: str | None = None,
    devc_id: str | None = None,
    color: str = "CYAN",
    transparency: float = 0.5,
    mult_id: str | None = None,
) -> Hole:
    """
    Create a standard window opening.

    Parameters
    ----------
    xb : tuple or Bounds3D
        Window bounds (xmin, xmax, ymin, ymax, zmin, zmax).
        One dimension should have zero thickness (planar opening).
    id : str, optional
        Hole identifier
    ctrl_id : str, optional
        Control ID for window operation (e.g., breakage logic)
    devc_id : str, optional
        Device ID for window operation
    color : str, optional
        Visualization color (default: 'CYAN')
    transparency : float, optional
        Visualization transparency 0-1 (default: 0.5)
    mult_id : str, optional
        Multiplier ID for creating arrays of windows

    Returns
    -------
    Hole
        Window hole object

    Examples
    --------
    >>> # Simple window on X-boundary wall
    >>> window = CommonHoles.window(xb=(0, 0, 2, 3, 1, 2))

    >>> # Window with breakage control
    >>> window = CommonHoles.window(
    ...     xb=(0, 0, 2, 3, 1, 2),
    ...     id="WINDOW_1",
    ...     ctrl_id="GLASS_BREAK_CTRL"
    ... )

    Notes
    -----
    Windows are typically placed 0.9-1.0 m above floor level.
    Standard window heights are 1.0-1.5 m.
    """
    if isinstance(xb, tuple):
        xb = Bounds3D.of(*xb)
    return Hole(
        xb=xb,
        id=id,
        ctrl_id=ctrl_id,
        devc_id=devc_id,
        color=color,
        transparency=transparency,
        mult_id=mult_id,
    )

Usage Examples

from pyfds.builders.libraries import CommonHoles
from pyfds import Simulation

sim = Simulation(chid="test")

# Single door at wall location
door = CommonHoles.door(location=(5, 0, 0), wall_normal="y")
sim.add(door)

# Window
window = CommonHoles.window(location=(3, 10, 1.2), wall_normal="y", width=1.2, height=1.0)
sim.add(window)

# Double door
double_door = CommonHoles.double_door(location=(8, 0, 0), wall_normal="y")
sim.add(double_door)

Available Holes

• door(location, wall_normal, width=0.9, height=2.1): Standard door

• Default: 0.9m × 2.1m

• double_door(location, wall_normal, width=1.8, height=2.1): Double door

• Default: 1.8m × 2.1m

• window(location, wall_normal, width, height): Window opening

• Custom dimensions

• vent_opening(location, wall_normal, width, height): Vent opening

• Custom dimensions

Common Ramps

Pre-configured time-varying functions.

ramps

Common ramp function patterns library.

Classes

CommonRamps

Library of common ramp function patterns.

Provides predefined ramps for common fire growth scenarios, HVAC schedules, and other time-varying functions.

Examples:

>>> fire_ramp = CommonRamps.t_squared_fast(peak_hrr=2500)
>>> step_ramp = CommonRamps.step_at(t=60, value=1.0)

Functions

t_squared_slow staticmethod

t_squared_slow(peak_hrr, t_peak=600, id='T2_SLOW')

Slow t-squared fire growth (600s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 600 TYPE: float DEFAULT: 600
id	Ramp identifier, default: 'T2_SLOW' TYPE: str DEFAULT: 'T2_SLOW'

RETURNS	DESCRIPTION
Ramp	Slow growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_slow(peak_hrr=1500)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_slow(peak_hrr: float, t_peak: float = 600, id: str = "T2_SLOW") -> Ramp:
    """
    Slow t-squared fire growth (600s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 600
    id : str, optional
        Ramp identifier, default: 'T2_SLOW'

    Returns
    -------
    Ramp
        Slow growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_slow(peak_hrr=1500)
    """
    return RampBuilder(id).t_squared("SLOW", peak_hrr, t_peak).build()

t_squared_medium staticmethod

t_squared_medium(peak_hrr, t_peak=300, id='T2_MEDIUM')

Medium t-squared fire growth (300s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 300 TYPE: float DEFAULT: 300
id	Ramp identifier, default: 'T2_MEDIUM' TYPE: str DEFAULT: 'T2_MEDIUM'

RETURNS	DESCRIPTION
Ramp	Medium growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_medium(peak_hrr=2500)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_medium(peak_hrr: float, t_peak: float = 300, id: str = "T2_MEDIUM") -> Ramp:
    """
    Medium t-squared fire growth (300s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 300
    id : str, optional
        Ramp identifier, default: 'T2_MEDIUM'

    Returns
    -------
    Ramp
        Medium growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_medium(peak_hrr=2500)
    """
    return RampBuilder(id).t_squared("MEDIUM", peak_hrr, t_peak).build()

t_squared_fast staticmethod

t_squared_fast(peak_hrr, t_peak=150, id='T2_FAST')

Fast t-squared fire growth (150s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 150 TYPE: float DEFAULT: 150
id	Ramp identifier, default: 'T2_FAST' TYPE: str DEFAULT: 'T2_FAST'

RETURNS	DESCRIPTION
Ramp	Fast growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_fast(peak_hrr=3000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_fast(peak_hrr: float, t_peak: float = 150, id: str = "T2_FAST") -> Ramp:
    """
    Fast t-squared fire growth (150s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 150
    id : str, optional
        Ramp identifier, default: 'T2_FAST'

    Returns
    -------
    Ramp
        Fast growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_fast(peak_hrr=3000)
    """
    return RampBuilder(id).t_squared("FAST", peak_hrr, t_peak).build()

t_squared_ultrafast staticmethod

t_squared_ultrafast(peak_hrr, t_peak=75, id='T2_ULTRAFAST')

Ultrafast t-squared fire growth (75s to 1055 kW).

PARAMETER	DESCRIPTION
peak_hrr	Peak heat release rate in kW TYPE: float
t_peak	Time to reach peak in seconds, default: 75 TYPE: float DEFAULT: 75
id	Ramp identifier, default: 'T2_ULTRAFAST' TYPE: str DEFAULT: 'T2_ULTRAFAST'

RETURNS	DESCRIPTION
Ramp	Ultrafast growth fire ramp

Examples:

>>> ramp = CommonRamps.t_squared_ultrafast(peak_hrr=5000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def t_squared_ultrafast(peak_hrr: float, t_peak: float = 75, id: str = "T2_ULTRAFAST") -> Ramp:
    """
    Ultrafast t-squared fire growth (75s to 1055 kW).

    Parameters
    ----------
    peak_hrr : float
        Peak heat release rate in kW
    t_peak : float, optional
        Time to reach peak in seconds, default: 75
    id : str, optional
        Ramp identifier, default: 'T2_ULTRAFAST'

    Returns
    -------
    Ramp
        Ultrafast growth fire ramp

    Examples
    --------
    >>> ramp = CommonRamps.t_squared_ultrafast(peak_hrr=5000)
    """
    return RampBuilder(id).t_squared("ULTRAFAST", peak_hrr, t_peak).build()

step_at staticmethod

step_at(t, value=1.0, id='STEP')

Step function at specified time.

PARAMETER	DESCRIPTION
t	Time at which step occurs in seconds TYPE: float
value	Value after step, default: 1.0 TYPE: float DEFAULT: 1.0
id	Ramp identifier, default: 'STEP' TYPE: str DEFAULT: 'STEP'

RETURNS	DESCRIPTION
Ramp	Step function ramp

Examples:

>>> ramp = CommonRamps.step_at(t=60, value=1.0)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def step_at(t: float, value: float = 1.0, id: str = "STEP") -> Ramp:
    """
    Step function at specified time.

    Parameters
    ----------
    t : float
        Time at which step occurs in seconds
    value : float, optional
        Value after step, default: 1.0
    id : str, optional
        Ramp identifier, default: 'STEP'

    Returns
    -------
    Ramp
        Step function ramp

    Examples
    --------
    >>> ramp = CommonRamps.step_at(t=60, value=1.0)
    """
    return RampBuilder(id).step(t, 0, value).build()

linear_growth staticmethod

linear_growth(t_end, f_end=1.0, id='LINEAR')

Linear growth from 0 to specified value.

PARAMETER	DESCRIPTION
t_end	End time in seconds TYPE: float
f_end	Final value, default: 1.0 TYPE: float DEFAULT: 1.0
id	Ramp identifier, default: 'LINEAR' TYPE: str DEFAULT: 'LINEAR'

RETURNS	DESCRIPTION
Ramp	Linear growth ramp

Examples:

>>> ramp = CommonRamps.linear_growth(t_end=300, f_end=1000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def linear_growth(t_end: float, f_end: float = 1.0, id: str = "LINEAR") -> Ramp:
    """
    Linear growth from 0 to specified value.

    Parameters
    ----------
    t_end : float
        End time in seconds
    f_end : float, optional
        Final value, default: 1.0
    id : str, optional
        Ramp identifier, default: 'LINEAR'

    Returns
    -------
    Ramp
        Linear growth ramp

    Examples
    --------
    >>> ramp = CommonRamps.linear_growth(t_end=300, f_end=1000)
    """
    return RampBuilder(id).linear(0, t_end, 0, f_end).build()

exponential_growth staticmethod

exponential_growth(t_end, f_end=1.0, id='EXPONENTIAL')

Exponential growth from 0 to specified value.

PARAMETER	DESCRIPTION
t_end	End time in seconds TYPE: float
f_end	Final value, default: 1.0 TYPE: float DEFAULT: 1.0
id	Ramp identifier, default: 'EXPONENTIAL' TYPE: str DEFAULT: 'EXPONENTIAL'

RETURNS	DESCRIPTION
Ramp	Exponential growth ramp

Examples:

>>> ramp = CommonRamps.exponential_growth(t_end=300, f_end=2000)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def exponential_growth(t_end: float, f_end: float = 1.0, id: str = "EXPONENTIAL") -> Ramp:
    """
    Exponential growth from 0 to specified value.

    Parameters
    ----------
    t_end : float
        End time in seconds
    f_end : float, optional
        Final value, default: 1.0
    id : str, optional
        Ramp identifier, default: 'EXPONENTIAL'

    Returns
    -------
    Ramp
        Exponential growth ramp

    Examples
    --------
    >>> ramp = CommonRamps.exponential_growth(t_end=300, f_end=2000)
    """
    return RampBuilder(id).exponential(0, t_end, 0, f_end).build()

hvac_schedule_24h staticmethod

hvac_schedule_24h(
    on_time=8.0, off_time=18.0, id="HVAC_SCHEDULE"
)

24-hour HVAC on/off schedule.

PARAMETER	DESCRIPTION
on_time	Hour when HVAC turns on (0-24), default: 8.0 (8 AM) TYPE: float DEFAULT: 8.0
off_time	Hour when HVAC turns off (0-24), default: 18.0 (6 PM) TYPE: float DEFAULT: 18.0
id	Ramp identifier, default: 'HVAC_SCHEDULE' TYPE: str DEFAULT: 'HVAC_SCHEDULE'

RETURNS	DESCRIPTION
Ramp	HVAC schedule ramp (0=off, 1=on)

Examples:

>>> # On from 6 AM to 10 PM
>>> ramp = CommonRamps.hvac_schedule_24h(on_time=6, off_time=22)

Source code in src/pyfds/builders/libraries/ramps.py

@staticmethod
def hvac_schedule_24h(
    on_time: float = 8.0,
    off_time: float = 18.0,
    id: str = "HVAC_SCHEDULE",
) -> Ramp:
    """
    24-hour HVAC on/off schedule.

    Parameters
    ----------
    on_time : float, optional
        Hour when HVAC turns on (0-24), default: 8.0 (8 AM)
    off_time : float, optional
        Hour when HVAC turns off (0-24), default: 18.0 (6 PM)
    id : str, optional
        Ramp identifier, default: 'HVAC_SCHEDULE'

    Returns
    -------
    Ramp
        HVAC schedule ramp (0=off, 1=on)

    Examples
    --------
    >>> # On from 6 AM to 10 PM
    >>> ramp = CommonRamps.hvac_schedule_24h(on_time=6, off_time=22)
    """
    # Convert hours to seconds
    on_seconds = on_time * 3600
    off_seconds = off_time * 3600

    return (
        RampBuilder(id)
        .add_point(0, 0)
        .add_point(on_seconds - 1e-6, 0)
        .add_point(on_seconds, 1)
        .add_point(off_seconds - 1e-6, 1)
        .add_point(off_seconds, 0)
        .add_point(86400, 0)  # 24 hours
        .build()
    )

Usage Examples

from pyfds.builders.libraries import CommonRamps
from pyfds import Simulation

sim = Simulation(chid="test")

# Fast t² fire growth to 2500 kW at 300s
fire_ramp = CommonRamps.t_squared_fast(peak_hrr=2500, t_peak=300)
sim.add(fire_ramp)

# HVAC schedule: on 8AM-6PM
hvac_ramp = CommonRamps.hvac_schedule_24h(on_time=8, off_time=18)
sim.add(hvac_ramp)

# Linear ramp
linear_ramp = CommonRamps.linear(t_start=0, t_end=100, f_start=0, f_end=1)
sim.add(linear_ramp)

Available Ramps

• t_squared_fast(peak_hrr, t_peak): Fast t² fire growth

• Growth rate: α = 0.047 kW/s²

• t_squared_medium(peak_hrr, t_peak): Medium t² fire growth

• Growth rate: α = 0.012 kW/s²

• t_squared_slow(peak_hrr, t_peak): Slow t² fire growth

• Growth rate: α = 0.003 kW/s²

• t_squared_ultra_fast(peak_hrr, t_peak): Ultra-fast t² fire growth

• Growth rate: α = 0.188 kW/s²

• linear(t_start, t_end, f_start, f_end): Linear ramp

• Straight line between two points

• step(t_step, f_before, f_after): Step function

• Instantaneous change at time t

• hvac_schedule_24h(on_time, off_time): 24-hour HVAC schedule

• On/off times in hours (0-24)

• exponential(tau, t_end): Exponential growth/decay

• Time constant: τ

Common Species

Pre-configured chemical species.

species

Predefined species database for common gas species in FDS simulations.

Functions

list_predefined_species

list_predefined_species()

Get list of all available predefined species.

RETURNS	DESCRIPTION
list[str]	Sorted list of species names

Examples:

>>> species = list_predefined_species()
>>> print(f"Available species: {len(species)}")
Available species: 35
>>> print(species[:5])
['ACETONE', 'ACETYLENE', 'AMMONIA', 'ARGON', 'BENZENE']

Source code in src/pyfds/builders/libraries/species.py

def list_predefined_species() -> list[str]:
    """
    Get list of all available predefined species.

    Returns
    -------
    list[str]
        Sorted list of species names

    Examples
    --------
    >>> species = list_predefined_species()
    >>> print(f"Available species: {len(species)}")
    Available species: 35
    >>> print(species[:5])
    ['ACETONE', 'ACETYLENE', 'AMMONIA', 'ARGON', 'BENZENE']
    """
    return sorted(PREDEFINED_SPECIES.keys())

get_species_info

get_species_info(name)

Get detailed information about a predefined species.

PARAMETER	DESCRIPTION
name	Species name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
dict	Dictionary with species properties including formula, molecular weight, and description

RAISES	DESCRIPTION
ValueError	If species name is not in database

Examples:

>>> info = get_species_info('PROPANE')
>>> print(f"Formula: {info['formula']}, MW: {info['mw']} g/mol")
Formula: C3H8, MW: 44.0956 g/mol

>>> info = get_species_info('oxygen')
>>> print(f"Description: {info['description']}")
Description: Oxygen (air component)

Source code in src/pyfds/builders/libraries/species.py

def get_species_info(name: str) -> dict[str, Any]:
    """
    Get detailed information about a predefined species.

    Parameters
    ----------
    name : str
        Species name (case-insensitive)

    Returns
    -------
    dict
        Dictionary with species properties including formula, molecular weight,
        and description

    Raises
    ------
    ValueError
        If species name is not in database

    Examples
    --------
    >>> info = get_species_info('PROPANE')
    >>> print(f"Formula: {info['formula']}, MW: {info['mw']} g/mol")
    Formula: C3H8, MW: 44.0956 g/mol

    >>> info = get_species_info('oxygen')
    >>> print(f"Description: {info['description']}")
    Description: Oxygen (air component)
    """
    species_key = name.upper()
    if species_key not in PREDEFINED_SPECIES:
        available = ", ".join(sorted(PREDEFINED_SPECIES.keys()))
        raise ValueError(f"Unknown species '{name}'. Available species:\n{available}")

    return PREDEFINED_SPECIES[species_key].copy()

is_predefined

is_predefined(name)

Check if a species name is in the predefined database.

PARAMETER	DESCRIPTION
name	Species name to check (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
bool	True if species is predefined, False otherwise

Examples:

>>> is_predefined('METHANE')
True
>>> is_predefined('CUSTOM_FUEL')
False
>>> is_predefined('methane')  # Case insensitive
True

Source code in src/pyfds/builders/libraries/species.py

def is_predefined(name: str) -> bool:
    """
    Check if a species name is in the predefined database.

    Parameters
    ----------
    name : str
        Species name to check (case-insensitive)

    Returns
    -------
    bool
        True if species is predefined, False otherwise

    Examples
    --------
    >>> is_predefined('METHANE')
    True
    >>> is_predefined('CUSTOM_FUEL')
    False
    >>> is_predefined('methane')  # Case insensitive
    True
    """
    return name.upper() in PREDEFINED_SPECIES

create_standard_air

create_standard_air(humidity=40.0)

Create standard air composition dictionary.

This function creates a dictionary suitable for creating a lumped Species object representing standard atmospheric air composition. The composition is adjusted for humidity.

PARAMETER	DESCRIPTION
humidity	Relative humidity percentage (default: 40.0) Valid range: 0-100 TYPE: float DEFAULT: 40.0

RETURNS	DESCRIPTION
dict	Dictionary with species definition parameters suitable for creating a lumped Species with background=True

Examples:

>>> air_dict = create_standard_air(humidity=50.0)
>>> print(air_dict['id'])
AIR
>>> print(f"Components: {len(air_dict['spec_id'])}")
Components: 4

Notes

Standard dry air composition (by volume): - Nitrogen: 78.084% - Oxygen: 20.946% - Argon: 0.934% - Carbon dioxide: 0.036%

Water vapor is added based on humidity, displacing nitrogen and oxygen.

Source code in src/pyfds/builders/libraries/species.py

def create_standard_air(humidity: float = 40.0) -> dict:
    """
    Create standard air composition dictionary.

    This function creates a dictionary suitable for creating a lumped Species
    object representing standard atmospheric air composition. The composition
    is adjusted for humidity.

    Parameters
    ----------
    humidity : float, optional
        Relative humidity percentage (default: 40.0)
        Valid range: 0-100

    Returns
    -------
    dict
        Dictionary with species definition parameters suitable for
        creating a lumped Species with background=True

    Examples
    --------
    >>> air_dict = create_standard_air(humidity=50.0)
    >>> print(air_dict['id'])
    AIR
    >>> print(f"Components: {len(air_dict['spec_id'])}")
    Components: 4

    Notes
    -----
    Standard dry air composition (by volume):
    - Nitrogen: 78.084%
    - Oxygen: 20.946%
    - Argon: 0.934%
    - Carbon dioxide: 0.036%

    Water vapor is added based on humidity, displacing nitrogen and oxygen.
    """
    if not (0 <= humidity <= 100):
        raise ValueError("Humidity must be between 0 and 100 percent")

    # Standard dry air composition (volume fractions)
    dry_air = {
        "NITROGEN": 0.78084,
        "OXYGEN": 0.20946,
        "ARGON": 0.00934,
        "CARBON_DIOXIDE": 0.00036,
    }

    # Adjust for humidity (approximate - assumes 25°C, atmospheric pressure)
    # Water vapor volume fraction ≈ (humidity/100) * (saturation_vapor_pressure / atmospheric_pressure)
    # At 25°C, saturation vapor pressure of water is ~23.8 mmHg = 0.0317 atm
    # Atmospheric pressure = 1 atm
    # So maximum water vapor volume fraction ≈ 0.0317
    water_vapor_fraction = (humidity / 100.0) * 0.0317

    # Adjust dry air components (water vapor displaces N2 and O2 proportionally)
    total_dry = sum(dry_air.values())
    adjustment_factor = (total_dry - water_vapor_fraction) / total_dry

    adjusted_fractions = {}
    for species, fraction in dry_air.items():
        adjusted_fractions[species] = fraction * adjustment_factor

    # Add water vapor
    adjusted_fractions["WATER_VAPOR"] = water_vapor_fraction

    # Convert to mass fractions (need molecular weights)
    species_list = list(adjusted_fractions.keys())

    # Calculate mass fractions properly
    total_mass = sum(
        adjusted_fractions[species] * get_species_info(species)["mw"]
        for species in adjusted_fractions
    )

    mass_fractions = [
        (adjusted_fractions[species] * get_species_info(species)["mw"]) / total_mass
        for species in species_list
    ]

    return {
        "id": "AIR",
        "background": True,
        "spec_id": species_list,
        "mass_fraction": mass_fractions,
        "description": f"Standard air (humidity: {humidity}%)",
    }

get_species_molecular_weight

get_species_molecular_weight(name)

Get the molecular weight of a predefined species.

This is a convenience function for quickly accessing molecular weights.

PARAMETER	DESCRIPTION
name	Species name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
float	Molecular weight in g/mol

Examples:

>>> mw = get_species_molecular_weight('WATER_VAPOR')
>>> print(f"Water molecular weight: {mw} g/mol")
Water molecular weight: 18.0153 g/mol

Source code in src/pyfds/builders/libraries/species.py

def get_species_molecular_weight(name: str) -> float:
    """
    Get the molecular weight of a predefined species.

    This is a convenience function for quickly accessing molecular weights.

    Parameters
    ----------
    name : str
        Species name (case-insensitive)

    Returns
    -------
    float
        Molecular weight in g/mol

    Examples
    --------
    >>> mw = get_species_molecular_weight('WATER_VAPOR')
    >>> print(f"Water molecular weight: {mw} g/mol")
    Water molecular weight: 18.0153 g/mol
    """
    info = get_species_info(name)
    return float(info["mw"])

get_species_formula

get_species_formula(name)

Get the chemical formula of a predefined species.

PARAMETER	DESCRIPTION
name	Species name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
str	Chemical formula

Examples:

>>> formula = get_species_formula('PROPANE')
>>> print(f"Propane formula: {formula}")
Propane formula: C3H8

Source code in src/pyfds/builders/libraries/species.py

def get_species_formula(name: str) -> str:
    """
    Get the chemical formula of a predefined species.

    Parameters
    ----------
    name : str
        Species name (case-insensitive)

    Returns
    -------
    str
        Chemical formula

    Examples
    --------
    >>> formula = get_species_formula('PROPANE')
    >>> print(f"Propane formula: {formula}")
    Propane formula: C3H8
    """
    info = get_species_info(name)
    return str(info["formula"])

Usage Examples

from pyfds.builders.libraries import CommonSpecies
from pyfds import Simulation

sim = Simulation(chid="test")

# Add tracer species
tracer = CommonSpecies.tracer(id="SF6")
sim.add(tracer)

# Add water vapor tracking
water = CommonSpecies.water_vapor()
sim.add(water)

Available Species

• tracer(id="TRACER"): Massless tracer
• Zero diffusivity

• No reactions

• water_vapor(): Water vapor species

• Molecular weight: 18 g/mol

• carbon_dioxide(): CO₂ species

• Molecular weight: 44 g/mol

• carbon_monoxide(): CO species

• Molecular weight: 28 g/mol

Common Fuels

Pre-configured fuel definitions for reactions.

fuels

Predefined fuel database for common combustion reactions.

Classes

FuelData

Bases: TypedDict

Type definition for fuel database entries.

Functions

list_fuels

list_fuels()

Get list of all available predefined fuels.

RETURNS	DESCRIPTION
list[str]	Sorted list of fuel names

Examples:

>>> fuels = list_fuels()
>>> print(fuels[:5])
['ACETONE', 'BUTANE', 'ETHANE', 'ETHANOL', 'GASOLINE']

Source code in src/pyfds/builders/libraries/fuels.py

def list_fuels() -> list[str]:
    """
    Get list of all available predefined fuels.

    Returns
    -------
    list[str]
        Sorted list of fuel names

    Examples
    --------
    >>> fuels = list_fuels()
    >>> print(fuels[:5])
    ['ACETONE', 'BUTANE', 'ETHANE', 'ETHANOL', 'GASOLINE']
    """
    return sorted(FUEL_DATABASE.keys())

get_fuel_info

get_fuel_info(name)

Get detailed information about a fuel.

PARAMETER	DESCRIPTION
name	Fuel name (case-insensitive) TYPE: str

RETURNS	DESCRIPTION
FuelData	Dictionary with fuel composition and properties

RAISES	DESCRIPTION
ValueError	If fuel name is not in database

Examples:

>>> info = get_fuel_info('PROPANE')
>>> print(f"Heat of combustion: {info['hoc']} kJ/kg")
Heat of combustion: 46000 kJ/kg

Source code in src/pyfds/builders/libraries/fuels.py

def get_fuel_info(name: str) -> FuelData:
    """
    Get detailed information about a fuel.

    Parameters
    ----------
    name : str
        Fuel name (case-insensitive)

    Returns
    -------
    FuelData
        Dictionary with fuel composition and properties

    Raises
    ------
    ValueError
        If fuel name is not in database

    Examples
    --------
    >>> info = get_fuel_info('PROPANE')
    >>> print(f"Heat of combustion: {info['hoc']} kJ/kg")
    Heat of combustion: 46000 kJ/kg
    """
    fuel_key = name.upper()
    if fuel_key not in FUEL_DATABASE:
        available = ", ".join(sorted(FUEL_DATABASE.keys()))
        raise ValueError(f"Unknown fuel '{name}'. Available fuels:\n{available}")

    return FUEL_DATABASE[fuel_key].copy()

Usage Examples

from pyfds.builders.libraries import CommonFuels

# Get fuel properties
propane = CommonFuels.get_fuel("PROPANE")
print(f"Heat of combustion: {propane['heat_of_combustion']} kJ/kg")
print(f"Soot yield: {propane['soot_yield']}")

# List available fuels
all_fuels = CommonFuels.list_fuels()
print(f"Available fuels: {all_fuels}")

Available Fuels

The library includes properties for common fuels:

• Hydrocarbons: METHANE, PROPANE, ETHANE, BUTANE, HEPTANE, OCTANE
• Polymers: POLYSTYRENE, POLYETHYLENE, POLYPROPYLENE, PMMA
• Natural materials: WOOD, CELLULOSE
• Liquids: METHANOL, ETHANOL, ACETONE, GASOLINE, DIESEL

Each fuel includes: - Chemical formula (C, H, O, N atoms) - Heat of combustion (kJ/kg) - Soot yield - CO yield - Radiative fraction

Customization

All library functions return standard PyFDS objects that can be modified:

from pyfds.builders.libraries import CommonMaterials

# Get base material
concrete = CommonMaterials.concrete()

# Modify as needed
concrete.emissivity = 0.95
concrete.absorption = 50000  # J/m³

sim.add(concrete)

Creating Custom Libraries

You can create your own library following the same pattern:

from pyfds import Material

class MyMaterials:
    """Custom material library."""

    @staticmethod
    def my_custom_material() -> Material:
        """Create custom material."""
        return Material(
            id="MY_MATERIAL",
            density=1500,
            conductivity=1.2,
            specific_heat=1.8,
            emissivity=0.9
        )

# Use it
from my_library import MyMaterials
sim.add(MyMaterials.my_custom_material())

See Also

• Material Builder - Building custom materials
• Ramp Builder - Building custom ramps
• Builders Index - All builder documentation
• Materials Guide - Material modeling guide