RampBuilder

RampBuilder

RampBuilder(id=None)

Bases: Builder[Ramp]

Builder for creating RAMP namelists.

Provides convenient methods for creating common ramp patterns including linear, step, exponential, t-squared fire growth, and custom functions.

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

Examples:

>>> # Linear ramp
>>> ramp = RampBuilder('HRR_GROWTH') \
...     .linear(t_start=0, t_end=300, f_start=0, f_end=1000) \
...     .build()

>>> # T-squared fire growth
>>> ramp = RampBuilder('FIRE') \
...     .t_squared(growth_rate='MEDIUM', peak_hrr=2500, t_peak=300) \
...     .build()

>>> # Temperature-dependent conductivity
>>> ramp = RampBuilder('STEEL_K') \
...     .temperature_table({
...         20: 45.8,
...         100: 43.3,
...         200: 40.7,
...         400: 36.4
...     }) \
...     .build()

>>> # Custom points
>>> ramp = RampBuilder('CUSTOM') \
...     .add_point(0, 0) \
...     .add_point(60, 100) \
...     .add_point(120, 500) \
...     .add_point(300, 2000) \
...     .build()

>>> # Using with_id() method
>>> ramp = RampBuilder() \
...     .with_id('MY_RAMP') \
...     .linear(0, 100, 0, 1) \
...     .build()

Initialize the RampBuilder.

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

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

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

    Parameters
    ----------
    id : str, optional
        Unique identifier for the ramp
    """
    super().__init__()
    self._id = id
    self._points: list[tuple[float, float]] = []

Functions

with_id

with_id(id)

Set the ramp identifier.

PARAMETER	DESCRIPTION
id	Unique identifier for the ramp TYPE: str

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

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

def with_id(self, id: str) -> "RampBuilder":
    """
    Set the ramp identifier.

    Parameters
    ----------
    id : str
        Unique identifier for the ramp

    Returns
    -------
    RampBuilder
        Self for method chaining
    """
    self._id = id
    return self

add_point

add_point(t, f)

Add a single (T, F) point to the ramp.

PARAMETER	DESCRIPTION
t	Time or temperature value TYPE: float
f	Function value at this point TYPE: float

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

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

def add_point(self, t: float, f: float) -> "RampBuilder":
    """
    Add a single (T, F) point to the ramp.

    Parameters
    ----------
    t : float
        Time or temperature value
    f : float
        Function value at this point

    Returns
    -------
    RampBuilder
        Self for method chaining
    """
    self._points.append((t, f))
    return self

add_points

add_points(points)

Add multiple points at once.

PARAMETER	DESCRIPTION
points	List of (T, F) point tuples TYPE: list[tuple[float, float]]

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

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

def add_points(self, points: list[tuple[float, float]]) -> "RampBuilder":
    """
    Add multiple points at once.

    Parameters
    ----------
    points : list[tuple[float, float]]
        List of (T, F) point tuples

    Returns
    -------
    RampBuilder
        Self for method chaining
    """
    self._points.extend(points)
    return self

linear

linear(t_start, t_end, f_start=0.0, f_end=1.0)

Create a linear ramp between two points.

PARAMETER	DESCRIPTION
t_start	Start time/temperature TYPE: float
t_end	End time/temperature TYPE: float
f_start	Function value at start, default: 0.0 TYPE: float DEFAULT: 0.0
f_end	Function value at end, default: 1.0 TYPE: float DEFAULT: 1.0

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

Examples:

>>> ramp = RampBuilder('LINEAR').linear(0, 300, 0, 1000).build()

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

def linear(
    self, t_start: float, t_end: float, f_start: float = 0.0, f_end: float = 1.0
) -> "RampBuilder":
    """
    Create a linear ramp between two points.

    Parameters
    ----------
    t_start : float
        Start time/temperature
    t_end : float
        End time/temperature
    f_start : float, optional
        Function value at start, default: 0.0
    f_end : float, optional
        Function value at end, default: 1.0

    Returns
    -------
    RampBuilder
        Self for method chaining

    Examples
    --------
    >>> ramp = RampBuilder('LINEAR').linear(0, 300, 0, 1000).build()
    """
    self._points = [(t_start, f_start), (t_end, f_end)]
    return self

step

step(t_step, f_before=0.0, f_after=1.0)

Create a step function at time t_step.

PARAMETER	DESCRIPTION
t_step	Time/temperature where step occurs TYPE: float
f_before	Function value before step, default: 0.0 TYPE: float DEFAULT: 0.0
f_after	Function value after step, default: 1.0 TYPE: float DEFAULT: 1.0

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

Examples:

>>> ramp = RampBuilder('STEP').step(60, 0, 1).build()

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

def step(self, t_step: float, f_before: float = 0.0, f_after: float = 1.0) -> "RampBuilder":
    """
    Create a step function at time t_step.

    Parameters
    ----------
    t_step : float
        Time/temperature where step occurs
    f_before : float, optional
        Function value before step, default: 0.0
    f_after : float, optional
        Function value after step, default: 1.0

    Returns
    -------
    RampBuilder
        Self for method chaining

    Examples
    --------
    >>> ramp = RampBuilder('STEP').step(60, 0, 1).build()
    """
    epsilon = 1e-6
    self._points = [
        (0, f_before),
        (t_step - epsilon, f_before),
        (t_step, f_after),
    ]
    return self

t_squared

t_squared(growth_rate, peak_hrr, t_peak, t_start=0.0)

Create a t-squared fire growth curve.

The t-squared growth model is commonly used to represent fire development: HRR(t) = alpha * (t - t_start)²

PARAMETER	DESCRIPTION
growth_rate	Named growth rate: 'SLOW' (600s), 'MEDIUM' (300s), 'FAST' (150s), 'ULTRAFAST' (75s), or custom alpha value (kW/s²) TYPE: str or float
peak_hrr	Peak heat release rate (kW) TYPE: float
t_peak	Time to reach peak (s) TYPE: float
t_start	Start time (s), default: 0.0 TYPE: float DEFAULT: 0.0

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

Examples:

>>> # Medium growth rate fire
>>> ramp = RampBuilder('FIRE').t_squared('MEDIUM', 2500, 300).build()

>>> # Custom growth rate
>>> ramp = RampBuilder('FIRE').t_squared(0.01876, 2500, 300).build()

Notes

Growth rate times are based on time to reach 1055 kW (NFPA standard).

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

def t_squared(
    self,
    growth_rate: str | float,
    peak_hrr: float,
    t_peak: float,
    t_start: float = 0.0,
) -> "RampBuilder":
    """
    Create a t-squared fire growth curve.

    The t-squared growth model is commonly used to represent fire development:
    HRR(t) = alpha * (t - t_start)²

    Parameters
    ----------
    growth_rate : str or float
        Named growth rate: 'SLOW' (600s), 'MEDIUM' (300s), 'FAST' (150s),
        'ULTRAFAST' (75s), or custom alpha value (kW/s²)
    peak_hrr : float
        Peak heat release rate (kW)
    t_peak : float
        Time to reach peak (s)
    t_start : float, optional
        Start time (s), default: 0.0

    Returns
    -------
    RampBuilder
        Self for method chaining

    Examples
    --------
    >>> # Medium growth rate fire
    >>> ramp = RampBuilder('FIRE').t_squared('MEDIUM', 2500, 300).build()

    >>> # Custom growth rate
    >>> ramp = RampBuilder('FIRE').t_squared(0.01876, 2500, 300).build()

    Notes
    -----
    Growth rate times are based on time to reach 1055 kW (NFPA standard).
    """
    # Growth rate constants (time to 1055 kW)
    alpha_map = {"SLOW": 600, "MEDIUM": 300, "FAST": 150, "ULTRAFAST": 75}

    if isinstance(growth_rate, str):
        growth_key = growth_rate.upper()
        if growth_key not in alpha_map:
            available = ", ".join(alpha_map.keys())
            raise ValueError(f"Unknown growth rate '{growth_rate}'. Available: {available}")
        t_g = alpha_map[growth_key]
        alpha = 1055 / (t_g**2)
    else:
        alpha = growth_rate

    # Generate points along the curve (stop before t_peak to avoid duplicate)
    t_vals = np.linspace(t_start, t_peak, 21)[:-1]  # 20 points excluding t_peak
    self._points = [(float(t), float(alpha * (t - t_start) ** 2)) for t in t_vals]

    # Add the exact peak value
    self._points.append((float(t_peak), float(peak_hrr)))

    return self

temperature_table

temperature_table(table)

Create temperature-dependent property ramp from table.

Useful for defining thermal properties that vary with temperature.

PARAMETER	DESCRIPTION
table	Dictionary of {temperature: value} pairs TYPE: dict[float, float]

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

Examples:

>>> # Steel thermal conductivity vs temperature
>>> ramp = RampBuilder('STEEL_K').temperature_table({
...     20: 45.8,
...     100: 43.3,
...     200: 40.7,
...     400: 36.4,
...     600: 31.0
... }).build()

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

def temperature_table(self, table: dict[float, float]) -> "RampBuilder":
    """
    Create temperature-dependent property ramp from table.

    Useful for defining thermal properties that vary with temperature.

    Parameters
    ----------
    table : dict[float, float]
        Dictionary of {temperature: value} pairs

    Returns
    -------
    RampBuilder
        Self for method chaining

    Examples
    --------
    >>> # Steel thermal conductivity vs temperature
    >>> ramp = RampBuilder('STEEL_K').temperature_table({
    ...     20: 45.8,
    ...     100: 43.3,
    ...     200: 40.7,
    ...     400: 36.4,
    ...     600: 31.0
    ... }).build()
    """
    self._points = sorted(table.items())
    return self

exponential

exponential(t_start, t_end, f_start, f_end, n_points=20)

Create exponential growth/decay curve.

PARAMETER	DESCRIPTION
t_start	Start time/temperature TYPE: float
t_end	End time/temperature TYPE: float
f_start	Function value at start TYPE: float
f_end	Function value at end TYPE: float
n_points	Number of points to generate, default: 20 TYPE: int DEFAULT: 20

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

Examples:

>>> ramp = RampBuilder('EXP').exponential(0, 300, 1, 1000, n_points=30).build()

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

def exponential(
    self,
    t_start: float,
    t_end: float,
    f_start: float,
    f_end: float,
    n_points: int = 20,
) -> "RampBuilder":
    """
    Create exponential growth/decay curve.

    Parameters
    ----------
    t_start : float
        Start time/temperature
    t_end : float
        End time/temperature
    f_start : float
        Function value at start
    f_end : float
        Function value at end
    n_points : int, optional
        Number of points to generate, default: 20

    Returns
    -------
    RampBuilder
        Self for method chaining

    Examples
    --------
    >>> ramp = RampBuilder('EXP').exponential(0, 300, 1, 1000, n_points=30).build()
    """
    # Generate exponential curve
    t_vals = np.linspace(t_start, t_end, n_points)
    # Normalize to 0-1 range
    t_norm = (t_vals - t_start) / (t_end - t_start)
    # Exponential scaling (using e^3 for moderate curvature)
    f_norm = (np.exp(3 * t_norm) - 1) / (np.exp(3) - 1)
    # Scale to actual range
    f_vals = f_start + (f_end - f_start) * f_norm

    self._points = list(zip(t_vals.tolist(), f_vals.tolist(), strict=True))
    return self

sine_wave

sine_wave(
    t_start,
    t_end,
    amplitude,
    period,
    offset=0.0,
    n_points=50,
)

Create sinusoidal variation.

PARAMETER	DESCRIPTION
t_start	Start time/temperature TYPE: float
t_end	End time/temperature TYPE: float
amplitude	Wave amplitude TYPE: float
period	Wave period TYPE: float
offset	Vertical offset, default: 0.0 TYPE: float DEFAULT: 0.0
n_points	Number of points to generate, default: 50 TYPE: int DEFAULT: 50

RETURNS	DESCRIPTION
RampBuilder	Self for method chaining

Examples:

>>> # Oscillating heat flux
>>> ramp = RampBuilder('SINE').sine_wave(
...     t_start=0, t_end=600,
...     amplitude=50, period=60, offset=100
... ).build()

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

def sine_wave(
    self,
    t_start: float,
    t_end: float,
    amplitude: float,
    period: float,
    offset: float = 0.0,
    n_points: int = 50,
) -> "RampBuilder":
    """
    Create sinusoidal variation.

    Parameters
    ----------
    t_start : float
        Start time/temperature
    t_end : float
        End time/temperature
    amplitude : float
        Wave amplitude
    period : float
        Wave period
    offset : float, optional
        Vertical offset, default: 0.0
    n_points : int, optional
        Number of points to generate, default: 50

    Returns
    -------
    RampBuilder
        Self for method chaining

    Examples
    --------
    >>> # Oscillating heat flux
    >>> ramp = RampBuilder('SINE').sine_wave(
    ...     t_start=0, t_end=600,
    ...     amplitude=50, period=60, offset=100
    ... ).build()
    """
    t_vals = np.linspace(t_start, t_end, n_points)
    f_vals = offset + amplitude * np.sin(2 * np.pi * t_vals / period)

    self._points = list(zip(t_vals.tolist(), f_vals.tolist(), strict=True))
    return self

Overview

RampBuilder creates time-dependent functions (&RAMP namelists) for fire growth, temperature-dependent properties, and control schedules.

Key Features

• Fire Growth Patterns: T-squared curves (SLOW, MEDIUM, FAST, ULTRAFAST)
• Temperature Tables: For temperature-dependent material properties
• Standard Patterns: Linear, step, exponential, sine wave
• Custom Points: Full control over (T, F) pairs

Quick Examples

T-squared Fire Growth

from pyfds.builders import RampBuilder

# Fast t-squared fire
fire_ramp = (
    RampBuilder('HRR_GROWTH')
    .t_squared('FAST', peak_hrr=2500, t_peak=300)
    .build()
)

Growth rates and α values: - 'SLOW': α = 0.00293 kW/s² - 'MEDIUM': α = 0.01172 kW/s² - 'FAST': α = 0.04689 kW/s² - 'ULTRAFAST': α = 0.1876 kW/s²

Temperature-Dependent Properties

# Thermal conductivity vs temperature
k_ramp = (
    RampBuilder('STEEL_K')
    .temperature_table({
        20: 45.8,   # 20°C → 45.8 W/(m·K)
        100: 43.3,
        200: 40.7,
        400: 36.4,
        600: 31.0
    })
    .build()
)

# Use in material
steel = (
    MaterialBuilder('STEEL')
    .thermal_conductivity_ramp('STEEL_K')
    .build()
)

Linear Ramp

# Linear increase from 0 to 1 over 100 seconds
linear = (
    RampBuilder('LINEAR')
    .linear(t_start=0, t_end=100, f_start=0, f_end=1)
    .build()
)

Step Function

# Step from 0 to 1 at t=60s
step = (
    RampBuilder('STEP')
    .step(t_step=60, f_before=0, f_after=1)
    .build()
)

Exponential Growth

# Exponential growth
exp_ramp = (
    RampBuilder('EXP')
    .exponential(t_start=0, t_end=100, f_start=1, f_end=100, rate=0.05)
    .build()
)

Sine Wave

# Sine wave oscillation
sine = (
    RampBuilder('SINE')
    .sine_wave(period=60, amplitude=1.0, offset=0.5, phase=0)
    .build()
)

Custom Points

# Custom time-value pairs
custom = (
    RampBuilder('CUSTOM')
    .add_point(0, 0)
    .add_point(10, 1)
    .add_point(20, 0.5)
    .add_point(30, 0)
    .build()
)

Usage in Simulations

Fire Growth

from pyfds import Simulation
from pyfds.builders import RampBuilder

sim = Simulation('fire_growth')

# Create fire growth ramp
fire_ramp = RampBuilder('FIRE').t_squared('FAST', peak_hrr=2500, t_peak=300).build()
sim.add_ramp(fire_ramp)

# Use in surface
sim.add(Surface(id='BURNER', hrrpua=1000.0, ramp_q='FIRE'))

Material Properties

# Create temperature-dependent conductivity
k_ramp = RampBuilder('STEEL_K').temperature_table({
    20: 45.8, 100: 43.3, 200: 40.7, 400: 36.4, 600: 31.0
}).build()
sim.add_ramp(k_ramp)

# Create temperature-dependent specific heat
cp_ramp = RampBuilder('STEEL_CP').temperature_table({
    20: 0.46, 100: 0.49, 200: 0.52, 400: 0.58
}).build()
sim.add_ramp(cp_ramp)

# Use in material
steel = (
    MaterialBuilder('STEEL')
    .thermal_conductivity_ramp('STEEL_K')
    .specific_heat_ramp('STEEL_CP')
    .build()
)
sim.add_material(steel)

Control Schedules

# HVAC schedule
hvac_schedule = (
    RampBuilder('HVAC')
    .add_point(0, 0)        # Off initially
    .add_point(28800, 1)    # On at 8:00 AM (8*3600)
    .add_point(64800, 0)    # Off at 6:00 PM (18*3600)
    .add_point(86400, 0)    # Off at midnight
    .build()
)
sim.add_ramp(hvac_schedule)

Predefined Library

from pyfds.builders.libraries import CommonRamps

# T-squared fire growth (all rates)
slow = CommonRamps.t_squared_slow(peak_hrr=1000)
medium = CommonRamps.t_squared_medium(peak_hrr=2000)
fast = CommonRamps.t_squared_fast(peak_hrr=2500)
ultra = CommonRamps.t_squared_ultrafast(peak_hrr=5000)

# Step function
step = CommonRamps.step_at(t=60, value=1.0)

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

# HVAC schedule (24-hour)
hvac = CommonRamps.hvac_schedule_24h(on_time=8, off_time=18)

Implementation Details

T-squared Fire Growth

The t-squared fire growth model is:

\[ \text{HRR}(t) = \alpha (t - t_{\text{start}})^2 \]

where α is the growth rate constant:

Rate	α (kW/s²)	Time to 1000 kW
SLOW	0.00293	585 s (9.8 min)
MEDIUM	0.01172	292 s (4.9 min)
FAST	0.04689	146 s (2.4 min)
ULTRAFAST	0.1876	73 s (1.2 min)

Temperature Tables

Temperature tables use DEVC_ID='TEMPERATURE' to create temperature-dependent properties. The builder automatically sets this for you.

Validation

The builder validates: - No duplicate T values - T values are sorted - At least 2 points for valid ramp

See Also

• User Guide - Time-Varying Properties
• User Guide - Builders
• MaterialBuilder - Using ramps in materials