modelBuilding

Model that declares a building to which EnergyPlus objects belong to

Extends from Modelica.Blocks.Icons.Block (Basic graphical layout of input/output block).

Information

Model that declares building-level specifications for Spawn of EnergyPlus.

This model is used to configure EnergyPlus. Each EnergyPlus idf file must have one instance of this model, and the instance name must be building. The instance must be placed in the model hierarchy at the same or at a higher level than the EnergyPlus objects that are related to the EnergyPlus idf file specified in this model through the parameter idfName.

For the parameter weaName, the name of the Modelica weather file must be provided. This is the file that can be read, for example, with Buildings.BoundaryConditions.WeatherData.ReaderTMY3. However, both weather files .mos and .epw must be provided. When starting the simulation, EnergyPlus will be run with the weather file whose name is identical to epwName, while Modelica will use the file specified by weaName.

The parameter runPeriod can be used to configure certain data of the EnergyPlus RunPeriod object. See Buildings.ThermalZones.EnergyPlus_24_2_0.Data.RunPeriod for the available options. Note however that the simulation start and stop time is controlled by Modelica, and therefore the entries in the EnergyPlus input data file for the RunPeriod object are ignored.

Note regarding `setInitialRadiativeHeatGainToZero` and `relativeSurfaceTolerance`

To configure models that connect components for radiative heat exchange to the thermal zone model, it is recommended to leave the parameter setInitialRadiativeHeatGainToZero at its default value true. This sets the radiative heat flow rate sent from Modelica to EnergyPlus to zero during the initialization of the model, thereby avoiding a potential nonlinear system of equations that may give convergence problems. This only affects the initialization of the model but not the time integration, hence the error should be small for typical models.

If you decide to set setInitialRadiativeHeatGainToZero = false, you need to be aware of the following: If setInitialRadiativeHeatGainToZero = false, then the radiative heat gain from the model input is being used. If this radiative heat gain depends on the radiative temperature that is an output of the EnergyPlus model, a nonlinear equation is formed. Because in EnergyPlus, computing the radiative temperature involves an iterative solution, this can cause convergence problems due to having two nested solvers, the outer being the Modelica solver that solves for the radiative heat flow rate QGaiRad_flow, and the innner being the EnergyPlus solver that solves for the radiative temperature TRad. Hence, we recommend to leave setInitialRadiativeHeatGainToZero = true.

If you decide to set setInitialRadiativeHeatGainToZero = false, you may need to also tighten the tolerance of the EnergyPlus solver by tightening relativeSurfaceTolerance, but one cannot assure that the nested nonlinear equations converge.

Because a Modelica model does not have knowledge of the solver tolerance, automatically tightening relativeSurfaceTolerance as a function of the Modelica solver tolerance is not possible.

Parameters

Type	Name	Default	Description
String	spawnExe	"spawn-0.6.0-9f1b36b00b"	Name of the spawn executable, without extension, such as spawn-0.6.0-9f1b36b00baaa
String	idfVersion	"24_2_0"	IDF version with underscore, used for error report
String	modelicaNameBuilding	getInstanceName()	Name of this instance
Boolean	usePrecompiledFMU	false	Set to true to use pre-compiled FMU with name specified by fmuName
String	fmuName	""	Specify if a pre-compiled FMU should be used instead of EnergyPlus (for development)
String	idfName		Name of the IDF file
String	epwName		Name of the EPW file
String	weaName		Name of the weather file, in .mos format and with .mos extension
Debug
Buildings.ThermalZones.EnergyPlus_24_2_0.Types.LogLevels	logLevel	Buildings.ThermalZones.EnergyPlus_24_2_0.Types.LogLevels.Warning	Log level of EnergyPlus output
Advanced
Boolean	computeWetBulbTemperature	true	If true, then this model computes the wet bulb temperature
Boolean	setInitialRadiativeHeatGainToZero	true	If true, then the radiative heat gain sent from Modelica to EnergyPlus is zero during the model initialization
Real	relativeSurfaceTolerance	1E-6	Relative tolerance of surface temperature calculations
Run period
Buildings.ThermalZones.EnergyPlus_24_2_0.Data.RunPeriod	runPeriod		EnergyPlus RunPeriod configuration
Diagnostics
Boolean	printUnits	true	Set to true to print units of OutputVariable instances to log file

Connectors

Type	Name	Default	Description
BoundaryConditions.WeatherData.Bus	weaBus		Weather data bus
BaseClasses.Synchronize.SynchronizeConnector	synchronize		Connector that synchronizes all Spawn objects of this buildings

Components

Type	Name	Default	Description
Real	isSynchronized		Flag used to synchronize Spawn objects

Revisions

August 21, 2024, by Michael Wetter:
Added support for EnergyPlus RunPeriod object.
This is for #2926.
March 16, 2024, by Michael Wetter:
Introduced parameter setInitialRadiativeHeatGainToZero. This is required for Buildings.ThermalZones.EnergyPlus_24_2_0.Examples.SingleFamilyHouse.Radiator with OpenModelica. See info section for rationale.
This was required for #3707.
November 18, 2021, by Michael Wetter:
Removed parameters showWeatherData and generatePortableFMU. Now, the weather data bus is always enabled as it is used in almost all simulations.
Converted usePrecompiledFMU and the associated fmuName from parameter to a constant as these are only used for debugging by developers.
Set annotation Evaluate=false for weather data files and idf files. The previous version had Evaluate=true for the .mos, and then OCT did not include it in the fmu.
This is for #2759.
November 11, 2021, by Michael Wetter:
Added constant spawnExe to allow different installation of Spawn.
August 19, 2021, by Michael Wetter:
Introduced parameter epwName.
This is for #2054.
February 18, 2021, by Michael Wetter:
Refactor synchronization of constructors.
This is for #2360.
January 28, 2020, by Michael Wetter:
First implementation.