.Buildings.ThermalZones.EnergyPlus_24_2_0.Building

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.

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.