building_space

Modules

building_space_mass_torch_system module

class BuildingSpaceMassTorchSystem(V=100, G_occ=5e-06, m_inf=0.001, **kwargs)[source]

Bases: System, Module

Building Space CO2 Concentration Model using Mass Balance Dynamics.

This model represents the CO2 concentration dynamics in a building space considering supply and exhaust air flows, occupant CO2 generation, infiltration, and outdoor CO2 concentration using bilinear state-space dynamics.

Parameters:

V (float) – Volume of the space [m³]
G_occ (float) – CO2 generation rate per occupant [ppm·kg/s]
m_inf (float) – Infiltration rate [kg/s]

Mathematical Formulation:

Continuous-Time Differential Equation:

The CO2 concentration dynamics are governed by the mass balance equation:

\[V\frac{dC}{dt} = \dot{m}_{sup}C_{out} - \dot{m}_{exh}C + \dot{m}_{inf}(C_{out} - C) + G_{occ} N_{occ}\]

where:

\(V\): Volume of the space [m³]

\(C\): Indoor CO2 concentration [ppm] (state variable)

\(\dot{m}_{sup}\): Supply air flow rate [kg/s] (input)

\(\dot{m}_{exh}\): Exhaust air flow rate [kg/s] (input)

\(\dot{m}_{inf}\): Infiltration rate [kg/s] (parameter)

\(C_{out}\): Outdoor CO2 concentration [ppm] (input)

\(G_{occ}\): CO2 generation rate per occupant [ppm·kg/s] (parameter)

\(N_{occ}\): Number of occupants (input)

Note: Supply air CO2 concentration is assumed equal to outdoor CO2 concentration.

State-Space Representation:

The system is implemented using the DiscreteStatespaceSystem with matrices:

State vector: \(\mathbf{x} = \begin{bmatrix}C\end{bmatrix}\)

Input vector: \(\mathbf{u} = \begin{bmatrix}\dot{m}_{sup} \\ \dot{m}_{exh} \\ C_{out} \\ N_{occ}\end{bmatrix}\)

Base System Matrices:

\[ \begin{align}\begin{aligned}\mathbf{A} = \begin{bmatrix} -\frac{\dot{m}_{inf}}{V} \end{bmatrix}\\\mathbf{B} = \begin{bmatrix} 0 & 0 & \frac{\dot{m}_{inf}}{V} & \frac{G_{occ}}{V} \end{bmatrix}\\\mathbf{C} = \begin{bmatrix} 1 \end{bmatrix}\\\mathbf{D} = \begin{bmatrix} 0 & 0 & 0 & 0 \end{bmatrix}\end{aligned}\end{align} \]

Bilinear Coupling Matrices:

State-Input Coupling (E matrices):

\[\begin{split}\mathbf{E} \in \mathbb{R}^{4 \times 1 \times 1} = \begin{bmatrix} \begin{bmatrix} 0 \end{bmatrix} & \text{(supply flow)} \\ \begin{bmatrix} -\frac{1}{V} \end{bmatrix} & \text{(exhaust flow)} \\ \begin{bmatrix} 0 \end{bmatrix} & \text{(outdoor CO2)} \\ \begin{bmatrix} 0 \end{bmatrix} & \text{(occupants)} \end{bmatrix}\end{split}\]

Input-Input Coupling (F matrices):

\[\begin{split}\mathbf{F} \in \mathbb{R}^{4 \times 1 \times 4} = \begin{bmatrix} \begin{bmatrix} 0 & 0 & \frac{1}{V} & 0 \end{bmatrix} & \text{(supply flow)} \\ \begin{bmatrix} 0 & 0 & 0 & 0 \end{bmatrix} & \text{(exhaust flow)} \\ \begin{bmatrix} 0 & 0 & 0 & 0 \end{bmatrix} & \text{(outdoor CO2)} \\ \begin{bmatrix} 0 & 0 & 0 & 0 \end{bmatrix} & \text{(occupants)} \end{bmatrix}\end{split}\]

Bilinear Effects

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

\(\mathbf{E}[1,0,0] \cdot u_1 \cdot x_0 = -\frac{1}{V} \dot{m}_{exh} C\): Exhaust flow removing CO2
\(\mathbf{F}[0,0,2] \cdot u_0 \cdot u_2 = \frac{1}{V} \dot{m}_{sup} C_{out}\): Supply flow bringing outdoor air

Physical Interpretation:

Mass Balance System:

Single state represents indoor CO2 concentration
Inputs represent ventilation flows, outdoor conditions, and occupancy
Bilinear terms model flow-dependent mass transfer accurately

Flow-Dependent Effects:

Supply air flow brings outdoor CO2 at outdoor concentration (F matrix coupling)
Exhaust air flow removes CO2 at indoor concentration (E matrix coupling)

Computational Features:

Automatic Differentiation: PyTorch tensors enable gradient computation

Adaptive Discretization: Matrices updated when flows change significantly

Parameter Estimation: All mass balance parameters available for calibration

Examples

Basic CO2 model:

>>> import twin4build as tb
>>>
>>> # Create CO2 model with default parameters
>>> co2_model = tb.BuildingSpaceMassTorchSystem(
...     V=150,          # Room volume [m³]
...     G_occ=6e-6,     # Higher CO2 generation per person
...     m_inf=0.002,    # Higher infiltration rate
...     id="zone_1_co2"
... )

Large space CO2 model:

>>> # Model for large space with higher occupancy
>>> co2_model = tb.BuildingSpaceMassTorchSystem(
...     V=500,          # Large space volume
...     G_occ=4e-6,     # Lower per-person generation
...     m_inf=0.005,    # Higher infiltration for large space
...     id="large_space_co2"
... )

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

Execute a single simulation step using the state-space model.

Return type:: None

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

Initialize the mass balance model by setting up the state-space representation.

Return type:: None

property config: Get the system configuration.

building_space_thermal_torch_system module

class BuildingSpaceThermalTorchSystem(C_air=1000000.0, C_wall=1000000.0, C_int=100000.0, C_boundary=1000000.0, R_out=0.05, R_in=0.05, R_int=0.01, R_boundary=0.01, f_wall=0.3, f_air=0.1, Q_occ_gain=100.0, **kwargs)[source]

Bases: System, Module

Building Space Thermal Model using RC Network Dynamics.

This class implements a thermal model for building spaces using a network of thermal resistances and capacitances (RC network). The model represents heat transfer between indoor air, exterior walls, boundary walls, and adjacent zones using bilinear state-space dynamics.

Parameters:

C_air (float) – Thermal capacitance of indoor air [J/K]
C_wall (float) – Thermal capacitance of exterior wall [J/K]
C_int (float) – Thermal capacitance of internal structure [J/K]
C_boundary (float) – Thermal capacitance of boundary wall [J/K]
R_out (float) – Thermal resistance between wall and outdoor [K/W]
R_in (float) – Thermal resistance between wall and indoor [K/W]
R_int (float) – Thermal resistance between internal structure and indoor air [K/W]
R_boundary (float) – Thermal resistance of boundary [K/W]
f_wall (float) – Radiation factor for exterior wall
f_air (float) – Radiation factor for air
Q_occ_gain (float) – Heat gain per occupant [W]

Mathematical Formulation:

Continuous-Time Differential Equations:

The thermal dynamics are governed by energy balance equations for each thermal node:

1. Indoor Air Temperature:

\[C_{air}\frac{dT_i}{dt} = \frac{T_w - T_i}{R_{in}} + \frac{T_{bw} - T_i}{R_{boundary}} + \sum_{j}\frac{T_{iw,j} - T_i}{R_{int}} + Q_{occ} N_{occ} + Q_{sh} + f_{air}\Phi_{sol} + c_p\dot{m}_{sup}(T_{sup} - T_i) - c_p\dot{m}_{exh}T_i\]

2. Exterior Wall Temperature:

\[C_{wall}\frac{dT_w}{dt} = \frac{T_o - T_w}{R_{out}} + \frac{T_i - T_w}{R_{in}} + f_{wall}\Phi_{sol}\]

3. Boundary Wall Temperature (if present):

\[C_{boundary}\frac{dT_{bw}}{dt} = \frac{T_i - T_{bw}}{R_{boundary}} + \frac{T_{bound} - T_{bw}}{R_{boundary}}\]

4. Interior Wall Temperature (for each adjacent zone j):

\[C_{int}\frac{dT_{iw,j}}{dt} = \frac{T_i - T_{iw,j}}{R_{int}} + \frac{T_{adj,j} - T_{iw,j}}{R_{int}}\]

where:

\(T_i\): Indoor air temperature [°C] (state)

\(T_w\): Exterior wall temperature [°C] (state)

\(T_{bw}\): Boundary wall temperature [°C] (state, optional)

\(T_{iw,j}\): Interior wall temperature for zone j [°C] (state, optional)

\(T_o\): Outdoor temperature [°C] (input)

\(T_{sup}\): Supply air temperature [°C] (input)

\(T_{bound}\): Boundary temperature [°C] (input, optional)

\(T_{adj,j}\): Adjacent zone j temperature [°C] (input, optional)

\(\dot{m}_{sup}\): Supply air flow rate [kg/s] (input)

\(\dot{m}_{exh}\): Exhaust air flow rate [kg/s] (input)

\(\Phi_{sol}\): Solar radiation [W/m²] (input)

\(N_{occ}\): Number of occupants (input)

\(Q_{sh}\): Space heater heat input [W] (input)

State-Space Representation:

The system is implemented using the DiscreteStatespaceSystem with matrices:

State vector: \(\mathbf{x} = \begin{bmatrix}T_i \\ T_w \\ T_{bw} \\ T_{iw,1} \\ \vdots \\ T_{iw,n}\end{bmatrix}\)

Input vector: \(\mathbf{u} = \begin{bmatrix}T_o \\ \dot{m}_{sup} \\ \dot{m}_{exh} \\ T_{sup} \\ \Phi_{sol} \\ N_{occ} \\ Q_{sh} \\ T_{bound} \\ T_{adj,1} \\ \vdots \\ T_{adj,n}\end{bmatrix}\)

Base System Matrices:

For a system with base thermal states (air, wall) + 1 boundary + 1 adjacent zone:

\[ \begin{align}\begin{aligned}\begin{split}\mathbf{A} = \begin{bmatrix} -\frac{1}{R_{in}C_{air}} - \frac{1}{R_{boundary}C_{air}} - \frac{1}{R_{int}C_{air}} & \frac{1}{R_{in}C_{air}} & \frac{1}{R_{boundary}C_{air}} & \frac{1}{R_{int}C_{air}} \\ \frac{1}{R_{in}C_{wall}} & -\frac{1}{R_{in}C_{wall}} - \frac{1}{R_{out}C_{wall}} & 0 & 0 \\ \frac{1}{R_{boundary}C_{boundary}} & 0 & -\frac{2}{R_{boundary}C_{boundary}} & 0 \\ \frac{1}{R_{int}C_{int}} & 0 & 0 & -\frac{2}{R_{int}C_{int}} \end{bmatrix}\end{split}\\\begin{split}\mathbf{B} = \begin{bmatrix} 0 & 0 & 0 & 0 & \frac{f_{air}}{C_{air}} & \frac{Q_{occ}}{C_{air}} & \frac{1}{C_{air}} & 0 & 0 \\ \frac{1}{R_{out}C_{wall}} & 0 & 0 & 0 & \frac{f_{wall}}{C_{wall}} & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & \frac{1}{R_{boundary}C_{boundary}} & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & \frac{1}{R_{int}C_{int}} \end{bmatrix}\end{split}\\\begin{split}\mathbf{C} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \end{bmatrix}\end{split}\\\begin{split}\mathbf{D} = \begin{bmatrix} 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \end{bmatrix}\end{split}\end{aligned}\end{align} \]

Bilinear Coupling Matrices:

State-Input Coupling (E matrices):

\[\begin{split}\mathbf{E} \in \mathbb{R}^{9 \times 4 \times 4} = \begin{bmatrix} \mathbf{0}_{4 \times 4} & \text{(outdoor temp)} \\ \mathbf{0}_{4 \times 4} & \text{(supply flow)} \\ \begin{bmatrix} -\frac{c_p}{C_{air}} & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \end{bmatrix} & \text{(exhaust flow)} \\ \mathbf{0}_{4 \times 4} & \text{(supply temp)} \\ \mathbf{0}_{4 \times 4} & \text{(solar)} \\ \mathbf{0}_{4 \times 4} & \text{(occupants)} \\ \mathbf{0}_{4 \times 4} & \text{(heater)} \\ \mathbf{0}_{4 \times 4} & \text{(boundary)} \\ \mathbf{0}_{4 \times 4} & \text{(adjacent)} \end{bmatrix}\end{split}\]

Input-Input Coupling (F matrices):

\[\begin{split}\mathbf{F} \in \mathbb{R}^{9 \times 4 \times 9} = \begin{bmatrix} \mathbf{0}_{4 \times 9} & \text{(outdoor temp)} \\ \begin{bmatrix} 0 & 0 & 0 & \frac{c_p}{C_{air}} & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \end{bmatrix} & \text{(supply flow)} \\ \mathbf{0}_{4 \times 9} & \text{(exhaust flow)} \\ \mathbf{0}_{4 \times 9} & \text{(supply temp)} \\ \mathbf{0}_{4 \times 9} & \text{(solar)} \\ \mathbf{0}_{4 \times 9} & \text{(occupants)} \\ \mathbf{0}_{4 \times 9} & \text{(heater)} \\ \mathbf{0}_{4 \times 9} & \text{(boundary)} \\ \mathbf{0}_{4 \times 9} & \text{(adjacent)} \end{bmatrix}\end{split}\]

Input vector mapping: \([T_o, \dot{m}_{sup}, \dot{m}_{exh}, T_{sup}, \Phi_{sol}, N_{occ}, Q_{sh}, T_{bound}, T_{adj,1}]^T\)

Bilinear Effects

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

\(\mathbf{E}[2,0,0] \cdot u_2 \cdot x_0 = -\frac{c_p}{C_{air}} \dot{m}_{exh} T_i\): Exhaust air removing heat
\(\mathbf{F}[1,0,3] \cdot u_1 \cdot u_3 = \frac{c_p}{C_{air}} \dot{m}_{sup} T_{sup}\): Supply air bringing heat

Physical Interpretation:

Thermal Network:

RC network represents building thermal mass and resistances
States capture temperature of air, walls, and structural elements
Inputs represent weather, HVAC, occupancy, and heat sources
Bilinear terms model flow-dependent heat transfer accurately

Flow-Dependent Effects:

Supply air flow brings heat at supply temperature (F matrix coupling)
Exhaust air flow removes heat at indoor temperature (E matrix coupling)
These effects are critical for accurate HVAC modeling

Computational Features:

Automatic Differentiation: PyTorch tensors enable gradient computation

Adaptive Discretization: Matrices updated when flows change significantly

Parameter Estimation: All RC parameters available for calibration

Examples

Basic thermal model:

>>> import twin4build as tb
>>>
>>> # Create thermal model with default RC parameters
>>> thermal_model = tb.BuildingSpaceThermalTorchSystem(
...     C_air=2e6,      # Higher air thermal mass
...     C_wall=5e6,     # Wall thermal mass
...     R_out=0.1,      # Outdoor thermal resistance
...     R_in=0.05,      # Indoor thermal resistance
...     f_air=0.15,     # Air radiation factor
...     id="zone_1_thermal"
... )

Thermal model with specific boundary conditions:

>>> # Model with boundary wall and adjacent zones
>>> thermal_model = tb.BuildingSpaceThermalTorchSystem(
...     C_air=1.5e6,
...     C_boundary=3e6,   # Boundary wall thermal mass
...     R_boundary=0.02,  # Low boundary resistance
...     Q_occ_gain=120.0, # Higher occupant heat gain
...     id="zone_thermal_with_boundary"
... )

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

Perform one step of the RC model simulation.

Parameters:

secondTime (Optional[float]) – Current simulation time in seconds.
dateTime (Optional[datetime]) – Current simulation date/time.
step_size (Optional[float]) – Current simulation step size.

Return type:

None

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

Initialize the RC model by initializing the state space model.

Parameters:

start_time (datetime.datetime) – Simulation start time.
end_time (datetime.datetime) – Simulation end time.
step_size (int) – Simulation step size.
simulator (core.Simulator) – Reference to the simulation model.

Return type:

None

property config: Get the configuration of the RC model.

property manual_setup_n_adjacent_zones

property manual_setup_n_boundary_temperature

property n_adjacent_zones

property n_boundary_temperature

building_space_torch_system module

class BuildingSpaceTorchSystem(thermal_kwargs=None, mass_kwargs=None, **kwargs)[source]

Bases: System, Module

Combined building space model for both thermal (RC) and CO2 (mass balance) dynamics.

This class composes BuildingSpaceThermalTorchSystem and BuildingSpaceMassTorchSystem to provide a unified building space model that captures both thermal and air quality dynamics in a building zone.

Parameters:

thermal_kwargs (Optional[dict]) – Keyword arguments for BuildingSpaceThermalTorchSystem
mass_kwargs (Optional[dict]) – Keyword arguments for BuildingSpaceMassTorchSystem
kwargs – Additional keyword arguments (must include ‘id’)

Mathematical Formulation:

See individual component documentation:

BuildingSpaceThermalTorchSystem: RC network thermal dynamics

BuildingSpaceMassTorchSystem: CO2 mass balance dynamics

Both models use DiscreteStatespaceSystem for efficient computation and automatic differentiation support.

System Composition:

The combined model consists of two parallel subsystems:

Thermal Subsystem (BuildingSpaceThermalTorchSystem):

Models temperature dynamics using RC network

Handles heat transfer between indoor air, walls, and adjacent zones

Includes HVAC thermal effects, solar gains, and occupant heat gains

Mass Balance Subsystem (BuildingSpaceMassTorchSystem):

Models CO2 concentration dynamics using mass balance equations

Handles ventilation, infiltration, and occupant CO2 generation

Tracks indoor air quality changes

Implementation Details:

Both subsystems run in parallel during each simulation step

Input signals are shared between both models where applicable

Each subsystem maintains its own state variables and outputs

The combined model provides unified input/output interfaces

All parameters from both subsystems are available for calibration

Combined Input/Output Interface:

Shared Inputs:

supplyAirFlowRate: Used by both thermal (heating/cooling) and mass (ventilation)

exhaustAirFlowRate: Used by both thermal (heat removal) and mass (CO2 removal)

numberOfPeople: Used by both thermal (heat gain) and mass (CO2 generation)

outdoorTemperature: Used by thermal model

outdoorCO2: Used by mass balance model

Thermal-Only Inputs:

supplyAirTemperature, globalIrradiation, heatGain

boundaryTemperature, adjacentZoneTemperature

Combined Outputs:

indoorTemperature: From thermal subsystem

wallTemperature: From thermal subsystem

indoorCO2: From mass balance subsystem

do_step(secondTime, dateTime, step_size, stepIndex)[source]

Execute a single simulation step for both submodels.

Return type:: None

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

Initialize the system and its submodels.

Return type:: None

property config: Get the system configuration.

property input: dict

Get the input ports of the building space system.

Returns:: Dictionary containing combined input ports from thermal and mass models
Return type:: dict

property output: dict

Get the output ports of the building space system.

Returns:: Dictionary containing combined output ports from thermal and mass models
Return type:: dict

sp = [<twin4build.translator.translator.SignaturePattern object>, <twin4build.translator.translator.SignaturePattern object>, <twin4build.translator.translator.SignaturePattern object>, <twin4build.translator.translator.SignaturePattern object>]

get_signature_pattern()[source]

Get the signature pattern of the FMU component.

Returns:: The signature pattern of the FMU component.
Return type:: SignaturePattern

get_signature_pattern_brick()[source]

Get the BRICK-only signature pattern of the building space component.

Returns:: The BRICK-only signature pattern of the building space component.
Return type:: SignaturePattern

get_signature_pattern_sensor()[source]

Get the signature pattern of the FMU component.

Returns:: The signature pattern of the FMU component.
Return type:: SignaturePattern

get_signature_pattern_sensor_brick()[source]

Get the BRICK-only signature pattern with sensor for the building space component.

Returns:: The BRICK-only signature pattern with sensor of the building space component.
Return type:: SignaturePattern