space_heater

Modules

space_heater_torch_system module

class SpaceHeaterTorchSystem(Q_flow_nominal_sh=1000, T_a_nominal_sh=60, T_b_nominal_sh=45, TAir_nominal_sh=21, thermalMassHeatCapacity=500000, nelements=3, **kwargs)[source]

Bases: System, Module

Space Heater (Radiator) Model with Finite Element Discretization.

This model represents a radiator that transfers heat from hot water to a room using multiple finite elements and bilinear state-space dynamics. The radiator is discretized to capture temperature distribution along its length with flow-dependent heat transfer characteristics.

Parameters:

  • Q_flow_nominal_sh (float) – Nominal heat output [W]

  • T_a_nominal_sh (float) – Nominal supply water temperature [°C]

  • T_b_nominal_sh (float) – Nominal return water temperature [°C]

  • TAir_nominal_sh (float) – Nominal room air temperature [°C]

  • thermalMassHeatCapacity (float) – Total thermal mass heat capacity [J/K]

  • nelements (int) – Number of finite elements

Mathematical Formulation:

Continuous-Time Differential Equations:

The model uses a state-space representation with n finite elements. For each element i, the temperature dynamics are described by:

\[C_1 \frac{dT_1}{dt} = \dot{m} \cdot c_p \cdot (T_{sup} - T_1) - \frac{UA}{n} \cdot (T_1 - T_z) \quad \forall i = 1\]
\[C_i \frac{dT_i}{dt} = \dot{m} \cdot c_p \cdot (T_{i-1} - T_i) - \frac{UA}{n} \cdot (T_i - T_z) \quad \forall i \in {2..n}\]
where:

  • \(C_i\) is the thermal capacitance of element i [J/K]

  • \(T_i\) is the temperature of element i [°C]

  • \(\dot{m}\) is the water mass flow rate [kg/s]

  • \(c_p\) is the specific heat capacity of water [J/(kg·K)]

  • \(UA\) is the overall heat transfer coefficient [W/K]

  • \(n\) is the number of elements

  • \(T_z\) is the zone (room) temperature [°C]

  • \(T_{sup}\) is the supply water temperature [°C]

Heat Output Calculation:

The total heat output is calculated as:

\[Q = \frac{UA}{n} \sum_{i=1}^n (T_i - T_z)\]

State-Space Representation:

The system is implemented using the DiscreteStatespaceSystem with matrices:

State vector: \(\mathbf{x} = \begin{bmatrix}T_1 \\ T_2 \\ \vdots \\ T_n\end{bmatrix}\)

Input vector: \(\mathbf{u} = \begin{bmatrix}T_{sup} \\ \dot{m} \\ T_z\end{bmatrix}\)

Base System Matrices:

For n finite elements:

\[\begin{split}\mathbf{A} = \begin{bmatrix} -\frac{UA/n}{C_1} & 0 & 0 & \cdots & 0 \\ 0 & -\frac{UA/n}{C_2} & 0 & \cdots & 0 \\ 0 & 0 & -\frac{UA/n}{C_3} & \cdots & 0 \\ \vdots & \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & 0 & \cdots & -\frac{UA/n}{C_n} \end{bmatrix}\end{split}\]
\[\begin{split}\mathbf{B} = \begin{bmatrix} 0 & 0 & \frac{UA/n}{C_1} \\ 0 & 0 & \frac{UA/n}{C_2} \\ \vdots & \vdots & \vdots \\ 0 & 0 & \frac{UA/n}{C_n} \end{bmatrix}\end{split}\]
\[\mathbf{C} = \begin{bmatrix} 0 & 0 & \cdots & 0 & 1 \end{bmatrix}\]
\[\mathbf{D} = \begin{bmatrix} 0 & 0 & 0 \end{bmatrix}\]

Bilinear Coupling Matrices:

State-Input Coupling (E matrices):

\[\begin{split}\mathbf{E} \in \mathbb{R}^{3 \times n \times n} = \begin{bmatrix} \mathbf{0}_{n \times n} & \text{(supply temperature)} \\ \begin{bmatrix} -\frac{c_p}{C_1} & 0 & 0 & \cdots & 0 & 0 \\ \frac{c_p}{C_1} & -\frac{c_p}{C_2} & 0 & \cdots & 0 & 0 \\ 0 & \frac{c_p}{C_2} & -\frac{c_p}{C_3} & \cdots & 0 & 0 \\ \vdots & \vdots & \vdots & \ddots & \vdots & \vdots \\ 0 & 0 & 0 & \cdots & \frac{c_p}{C_{n-1}} & -\frac{c_p}{C_n} \end{bmatrix} & \text{(water flow rate)} \\ \mathbf{0}_{n \times n} & \text{(zone temperature)} \end{bmatrix}\end{split}\]

Input-Input Coupling (F matrices):

\[\begin{split}\mathbf{F} \in \mathbb{R}^{3 \times n \times 3} = \begin{bmatrix} \begin{bmatrix} 0 & \frac{c_p}{C_1} & 0 \\ 0 & 0 & 0 \\ \vdots & \vdots & \vdots \\ 0 & 0 & 0 \end{bmatrix} & \text{(supply temperature)} \\ \mathbf{0}_{n \times 3} & \text{(water flow rate)} \\ \mathbf{0}_{n \times 3} & \text{(zone temperature)} \end{bmatrix}\end{split}\]

Bilinear Effects

The bilinear terms handle specific flow-dependent heat transfer effects:

  • \(\mathbf{E}[1,i,i] \cdot u_1 \cdot x_i = -\frac{c_p}{C_i} \dot{m} T_i\): Water flow removing heat from element i

  • \(\mathbf{E}[1,i,i-1] \cdot u_1 \cdot x_{i-1} = \frac{c_p}{C_i} \dot{m} T_{i-1}\): Water flow bringing heat from previous element

  • \(\mathbf{F}[0,0,1] \cdot u_0 \cdot u_1 = \frac{c_p}{C_1} T_{sup} \dot{m}\): Supply temperature bringing heat to first element

Model Initialization:

The model is initialized by solving numerically for UA in steady-state nominal conditions:

\[0 = \mathbf{A}_{U\!A} \mathbf{x} + \mathbf{B}_{U\!A} \mathbf{u}\]
where:

  • \(\mathbf{A}_{U\!A}\) is the A matrix given \(U\!A\)

  • \(\mathbf{B}_{U\!A}\) is the B matrix given \(U\!A\)

  • \(\mathbf{x}\) is the state vector

  • \(\mathbf{u}\) is the input vector

Note: the gradients of this computation is not tracked, meaning that that parameters Q_flow_nominal_sh, T_a_nominal_sh, T_b_nominal_sh, TAir_nominal_sh cannot be calibrated.

Physical Interpretation:

Finite Element Discretization:

  • Each element represents a section of the radiator with its own thermal mass

  • States capture temperature distribution along radiator length

  • Flow-dependent heat transfer between elements modeled with bilinear terms

Flow-Dependent Effects:

  • Water flow brings heat at supply temperature to first element (F matrix coupling)

  • Water flow transfers heat between consecutive elements (E matrix coupling)

  • These effects are critical for accurate radiator performance modeling

Computational Features:

  • Automatic Differentiation: PyTorch tensors enable gradient computation

  • Adaptive Discretization: Matrices updated when flow conditions change significantly

  • Parameter Estimation: UA coefficient and thermal mass available for calibration

Examples

Basic space heater model:

>>> import twin4build as tb
>>>
>>> # Create single-element radiator
>>> heater = tb.SpaceHeaterTorchSystem(
...     Q_flow_nominal_sh=2000,        # 2 kW nominal output
...     T_a_nominal_sh=70,             # 70°C supply temperature
...     T_b_nominal_sh=50,             # 50°C return temperature
...     TAir_nominal_sh=20,            # 20°C room temperature
...     thermalMassHeatCapacity=50000, # 50 kJ/K thermal mass
...     nelements=1,
...     id="radiator_single"
... )

Multi-element radiator for detailed modeling:

>>> # Create multi-element radiator for better temperature distribution
>>> heater = tb.SpaceHeaterTorchSystem(
...     Q_flow_nominal_sh=3500,        # 3.5 kW nominal output
...     T_a_nominal_sh=75,             # Higher supply temperature
...     T_b_nominal_sh=55,             # Higher return temperature
...     TAir_nominal_sh=22,            # Slightly warmer room
...     thermalMassHeatCapacity=80000, # Higher thermal mass
...     nelements=5,                   # 5 elements for detail
...     id="radiator_multi_element"
... )

Notes

Model Characteristics:

  • The radiator is discretized into multiple elements for accurate temperature distribution modeling

  • Each element has its own thermal mass and heat transfer characteristics

  • The UA value is calculated numerically to match nominal conditions

  • The model accounts for both convective and radiative heat transfer

Implementation Details:

  • The model uses a state-space representation for efficient computation

  • All calculations are performed using PyTorch tensors for gradient tracking

  • The UA value is optimized using numerical methods during initialization

  • The model supports both steady-state and dynamic simulations

do_step(secondTime=None, dateTime=None, step_size=None, stepIndex=None)[source]

Perform one simulation step.

This method advances the state-space model by one time step and calculates the outlet water temperature and heat output. The method: 1. Collects current input values 2. Updates the state-space model 3. Calculates the heat output based on element temperatures 4. Updates output values

Parameters:

  • secondTime (float, optional) – Current simulation time in seconds.

  • dateTime (datetime, optional) – Current simulation date and time.

  • step_size (float, optional) – Time step size in seconds.

  • stepIndex (int, optional) – Current simulation step index.

initialize(start_time, end_time, step_size, simulator)[source]

Initialize the space heater system for simulation.

This method performs the following initialization steps: 1. Numerically solves for the UA value that matches the nominal heat output 2. Initializes input/output data structures 3. Creates or reinitializes the state-space model

Parameters:

  • start_time (datetime.datetime) – Start time of the simulation period.

  • end_time (datetime.datetime) – End time of the simulation period.

  • step_size (int) – Time step size in seconds.

  • simulator (core.Simulator) – Simulation model object.

Return type:

None

property config: Dict[str, List[str]]

Get the configuration parameters.

Returns:

Dictionary containing configuration parameter names.

Return type:

Dict[str, List[str]]

property input: dict

Get the input ports of the space heater system.

Returns:

Dictionary containing input ports:

  • ”supplyWaterTemperature”: Supply water temperature [°C]

  • ”waterFlowRate”: Water flow rate [kg/s]

  • ”indoorTemperature”: Indoor air temperature [°C]

Return type:

dict

property output: dict

Get the output ports of the space heater system.

Returns:

Dictionary containing output ports:

  • ”outletWaterTemperature”: Outlet water temperature [°C]

  • ”Power”: Heating power [W]

Return type:

dict

sp = [<twin4build.translator.translator.SignaturePattern object>]
get_signature_pattern()[source]

Get the signature pattern of the FMU component.

Returns:

The signature pattern for the building space 0 adjacent boundary outdoor FMU system.

Return type:

SignaturePattern