Creating new models
Introduction
This page aims to present a framework to ease the creation of new EnergyPlus models. Common EnergyPlus objects are listed with sample code and comments to aid their use.
The objects are grouped into various categories to increase the readability of this guide.
Infrastructure objects
These objects are common to virtually every model. They are fairly straighforward, and deal mainly with the model's overall "configuration" (as opposed to the actual building characteristics).
An .idf file containing the below objects configured for a building in Edmonton can be downloaded here (additional cities will be added as they are needed and created).
Version
This simply tells the EnergyPlus executable what version the .idf was prepared for. Example:
Version,
3.0; !- Version Identifier
SimulationControl
Controls which sizing runs will completed, and which simulation runs will be completed. Example:
SimulationControl,
Yes, !- Do Zone Sizing Calculation
No, !- Do System Sizing Calculation
No, !- Do Plant Sizing Calculation
Yes, !- Run Simulation for Sizing Periods
Yes; !- Run Simulation for Weather File Run Periods
Building
Basic simulation configuration information for the building. The Solar Distribution field will generally be set to FullExterior. FullInteriorAndExterior can be used in the event of a detailed passive solar study1, but this option can only be selected if the zone is "convex"2. The "WithReflections" option for either of these alternatives can be selected if there are exterior surfaces that will be reflecting a significant amount of solar radiation within the building3. Example:
Building,
tang-turner, !- Name
0, !- North Axis {deg}
Suburbs, !- Terrain
0.04, !- Loads Convergence Tolerance Value
0.4, !- Temperature Convergence Tolerance Value {deltaC}
FullExterior, !- Solar Distribution
25; !- Maximum Number of Warmup Days
ShadowCalculation
"ShadowCalculation" something of a misnomer, as this object deals more broadly with solar positioning calculations. The "Calculation Frequency" field controls the period of solar position updates. The "Maximum Figures in Shadow Overlap Calculations" field, in a nutshell, controls the accuracy of solar shading calculations. Increasing the value of this field with increase both the accuracy of the shading calculations and the associated computational expense. Example:
ShadowCalculation,
10, !- Calculation Frequency
15000; !- Maximum Figures in Shadow Overlap Calculations
SurfaceConvectionAlgorithm:Inside
Selects the algorithm used to calculate convection coefficients on internal vertical surfaces. A good rule of thumb: use the default. Example:
SurfaceConvectionAlgorithm:Inside,
Detailed; !- Algorithm
SurfaceConvectionAlgorithm:Outside
Selects the algorithm used to calculate convection coefficients on external vertical surfaces. A good rule of thumb: use the default. Example:
SurfaceConvectionAlgorithm:Outside,
Detailed; !- Algorithm
HeatBalanceAlgorithm
Selects the algorithm used for the iterative heat balance calculations. A good rule of thumb: use the defaults. Example:
HeatBalanceAlgorithm,
ConductionTransferFunction, !- Algorithm
200; !- Surface Temperature Upper Limit
Timestep
Controls the timestep used in the Zone Heat Balance Model to "drive" heat transfer and load calculations4. Use the default (6 timesteps per hour) as a base, decrease if simulation speed is an issue, and increase in the event of stability or control issues. Example:
Timestep,
6; !- Number of Timesteps per Hour
ConvergenceLimits
EnergyPlus uses a non-static timestep that is occasionally reduced in certain situations. The "Minimum System Timestep" field controls the minimum value to which EnergyPlus is able to reduce the simulation timestep. If nothing is entered, this defaults to 1 minute. The "Maximum HVAC Iterations" field controls the maximum number of iterations the HVAC Manager can make during system calculations. In practice, this field is only modified when the "SimHVAC: Maximum iterations... " warning is received. Example:
ConvergenceLimits,
, !- Minimum System Timestep {minutes}
20; !- Maximum HVAC Iterations
Site:Location
Contains basic site information. Example:
Site:Location,
Edmonton, !- Name
53.53, !- Latitude {deg}
-114.1, !- Longitude {deg}
-7, !- Time Zone {hr}
723; !- Elevation {m}
SizingPeriod:DesignDay
This object contains the data necesarry for creating a model of weather conditions on a hypothetical day representing climatic extremes, which is usually used for the purposes of equipment sizing. A simulation for each day represented by an object of this type if the "Run Simulation for Sizing Periods" option of the SimulationControl object is selected. Example:
SizingPeriod:DesignDay,
SummerDesignDay, !- Name
25.2, !- Maximum Dry-Bulb Temperature {C}
10.5, !- Daily Temperature Range {deltaC}
16.3, !- Humidity Indicating Conditions at Maximum Dry-Bulb
93330, !- Barometric Pressure {Pa}
4.3, !- Wind Speed {m/s}
150, !- Wind Direction {deg}
1, !- Sky Clearness
0, !- Rain Indicator
0, !- Snow Indicator
21, !- Day of Month
7, !- Month
SummerDesignDay, !- Day Type
1, !- Daylight Saving Time Indicator
WetBulb, !- Humidity Indicating Type
, !- Relative Humidity Day Schedule Name
DefaultMultipliers, !- Dry-Bulb Temperature Range Modifier Type
, !- Dry-Bulb Temperature Range Modifier Schedule Name
ASHRAEClearSky; !- Solar Model Indicator
RunPeriod
This object sets options for interpreting the weather file specified at run-time. A simulation using these options is completed if the "Run Simulation for Weather File Run Periods" option in the SimulationControl object is selected. Example:
RunPeriod,
1, !- Begin Month
1, !- Begin Day of Month
12, !- End Month
31, !- End Day of Month
UseWeatherFile, !- Day of Week for Start Day
Yes, !- Use Weather File Holidays and Special Days
Yes, !- Use Weather File Daylight Saving Period
No, !- Apply Weekend Holiday Rule
Yes, !- Use Weather File Rain Indicators
Yes, !- Use Weather File Snow Indicators
1; !- Number of Times Runperiod to be Repeated
Site:GroundReflectance
Specifies ground reflectances used in insolation calculations. Not necessary for simulation, and probably not worth the effort of creating one, but useful if available. Example:
Site:GroundReflectance,
0.395, !- January Ground Reflectance {dimensionless}
0.395, !- February Ground Reflectance {dimensionless}
0.362, !- March Ground Reflectance {dimensionless}
0.208, !- April Ground Reflectance {dimensionless}
0.235, !- May Ground Reflectance {dimensionless}
0.243, !- June Ground Reflectance {dimensionless}
0.243, !- July Ground Reflectance {dimensionless}
0.243, !- August Ground Reflectance {dimensionless}
0.218, !- September Ground Reflectance {dimensionless}
0.208, !- October Ground Reflectance {dimensionless}
0.321, !- November Ground Reflectance {dimensionless}
0.395; !- December Ground Reflectance {dimensionless}
Schedules
Objects in this category are used for specifying schedule information.
ScheduleTypeLimits
These objects delineate a schedule type, by specifying the range of allowable values for the schedule, as well as their type (integer or real number). They are used in Schedule objects as a check to ensure the user has entered reasonable values. A database containing some commonly-used ScheduleTypeLimits objects can be found here. Example:
ScheduleTypeLimits,
binary, !- Name
0:1, !- Range
Discrete; !- Numeric Type
Schedule:Compact
There are a number of object which one can use to specify schedule information, but this one is probably the most straightforward. A database of commonly used schedules can be found here. Example:
Schedule:Compact,
main-floor-thermostat-setpoint-schedule, !- Name
temperature, !- Schedule Type Limits Name
Through: 12/31, !- Field 1
For: Weekdays, !- Field 2
Interpolate: No, !- Field 3
Until: 7:00, !- Field 4
16, !- Field 5
Until: 9:00, !- Field 6
18, !- Field 7
Until: 18:00, !- Field 8
15, !- Field 9
Until: 24:00, !- Field 10
18, !- Field 11
For: AllOtherDays, !- Field 12
Until: 9:00, !- Field 13
16, !- Field 14
Until: 11:00, !- Field 15
18, !- Field 16
Until: 18:00, !- Field 17
15, !- Field 18
Until: 24:00, !- Field 19
18; !- Field 20
Materials/Constructions
Objects within this group specify the composition of envelope components.
**** THIS PAGE IS UNDER CONSTRUCTION ****
Notes
1. If this option is selected, EnergyPlus calculates the surface onto which solar incident to the zone falls upon, as opposed to assuming that it all falls on the zone's floor
2. See p 14 of the EnergyPlus Input Output Reference for a definition
3. If these exterior surfaces are complex, the DoNotMirrorDetachedShading option of the Output:Diagnostics object may need to be applied; see Input Output Reference
4. See p 9 of the Input Output Reference for a good discussion on the effects of timestep.