Simulation Parameters¶

16 object types from idfpy.models.simulation · EnergyPlus 26.2

Object	Summary
Building	Describes parameters that are used during the simulation of the building.
ConvergenceLimits	Specifies limits on HVAC system simulation timesteps and iterations.
HVACSystemRootFindingAlgorithm	Specifies a HVAC system solver algorithm to find a root
HeatBalanceAlgorithm	Determines which Heat Balance Algorithm will be used ie.
HeatBalanceSettings:ConductionFiniteDifference	Determines settings for the Conduction Finite Difference algorithm for surface heat transfer modeling.
PerformancePrecisionTradeoffs	This object enables users to choose certain options that speed up EnergyPlus simulation, but may lead to …
ShadowCalculation	This object is used to control details of the solar, shading, and daylighting models
SimulationControl	Note that the following 3 fields are related to the Sizing:Zone, Sizing:System, and Sizing:Plant objects.
SurfaceConvectionAlgorithm:Inside	Default indoor surface heat transfer convection algorithm to be used for all zones
SurfaceConvectionAlgorithm:Outside	Default outside surface heat transfer convection algorithm to be used for all zones
Timestep	Specifies the "basic" timestep for the simulation.
Version	Specifies the EnergyPlus version of the IDF file.
ZoneAirContaminantBalance	Determines which contaminant concentration will be simulates.
ZoneAirHeatBalanceAlgorithm	Controls the zone/space air heat balance.
ZoneAirMassFlowConservation	Enforces the zone air mass flow balance by either adjusting zone mixing object flow only, adjusting zone …
ZoneCapacitanceMultiplier:ResearchSpecial	Multiplier altering the relative capacitance of the air compared to an empty zone

Building¶

from idfpy.models import Building unique

Describes parameters that are used during the simulation of the building. There are necessary correlations between the entries for this object and some entries in the Site:WeatherStation and Site:HeightVariation objects, specifically the Terrain field.

Field	Type	Default	Details
`name` Name	string	`NONE`
`north_axis` North Axis	number deg	`0.0`	degrees from true North
`terrain` Terrain	choice	`Suburbs`	Country=FlatOpenCountry \| Suburbs=CountryTownsSuburbs \| City=CityCenter \| Ocean=body of water (5km) \| Urban=Urban-Industrial-Forest One of `City`, `Country`, `Ocean`, `Suburbs`, `Urban`
`loads_convergence_tolerance_value` Loads Convergence Tolerance Value	number W	`0.04`	Loads Convergence Tolerance Value is a change in load from one warmup day to the next Range: > 0, ≤ 0.5
`temperature_convergence_tolerance_value` Temperature Convergence Tolerance Value	number deltaC	`0.4`	Range: > 0, ≤ 0.5
`solar_distribution` Solar Distribution	choice	`FullExterior`	MinimalShadowing \| FullExterior \| FullInteriorAndExterior \| FullExteriorWithReflections \| FullInteriorAndExteriorWithReflections One of `FullExterior`, `FullExteriorWithReflections`, `FullInteriorAndExterior`, `FullInteriorAndExteriorWithReflections`, `MinimalShadowing`
`maximum_number_of_warmup_days` Maximum Number of Warmup Days	integer	`25`	EnergyPlus will only use as many warmup days as needed to reach convergence tolerance. This field's value should NOT be set less than 25. Range: > 0
`minimum_number_of_warmup_days` Minimum Number of Warmup Days	integer	`1`	The minimum number of warmup days that produce enough temperature and flux history to start EnergyPlus simulation for all reference buildings was suggested to be 6. However this can lead to excessive run times as warmup days can be repeated needlessly. For faster execution rely on the convergence criteria to detect when warmup is complete. When this field is greater than the maximum warmup days defined previous field the maximum number of warmup days will be reset to the minimum value entered here. Warmup days will be set to be the value you entered. The default is 1. Range: > 0
`construction_assignment_set_name` Construction Assignment Set Name	reference		Optional. Provides inherited construction assignments for surfaces and sub-surfaces in the building. Assignments referenced by Space take precedence over assignments referenced by Building. Names a ConstructionAssignmentSet

ConvergenceLimits¶

from idfpy.models import ConvergenceLimits unique

Specifies limits on HVAC system simulation timesteps and iterations. This item is an advanced feature that should be used only with caution.

Field	Type	Default	Details
`minimum_system_timestep` Minimum System Timestep	integer minutes		0 sets the minimum to the zone timestep (ref: Timestep) 1 is normal (ratchet down to 1 minute) setting greater than zone timestep (in minutes) will effectively set to zone timestep Range: ≥ 0, ≤ 60
`maximum_hvac_iterations` Maximum HVAC Iterations	integer	`20`	Range: ≥ 1
`minimum_plant_iterations` Minimum Plant Iterations	integer	`2`	Controls the minimum number of plant system solver iterations within a single HVAC iteration Larger values will increase runtime but might improve solution accuracy for complicated plant systems Complex plants include: several interconnected loops, heat recovery, thermal load following generators, etc. Range: ≥ 1
`maximum_plant_iterations` Maximum Plant Iterations	integer	`8`	Controls the maximum number of plant system solver iterations within a single HVAC iteration Smaller values might decrease runtime but could decrease solution accuracy for complicated plant systems Range: ≥ 2

HVACSystemRootFindingAlgorithm¶

from idfpy.models import HVACSystemRootFindingAlgorithm unique

Specifies a HVAC system solver algorithm to find a root

Field	Type	Default	Details
`algorithm` Algorithm	choice	`RegulaFalsi`	One of `Alternation`, `Bisection`, `BisectionThenRegulaFalsi`, `RegulaFalsi`, `RegulaFalsiThenBisection`
`number_of_iterations_before_algorithm_switch` Number of Iterations Before Algorithm Switch	integer	`5`	This field is used when RegulaFalsiThenBisection or BisectionThenRegulaFalsi is entered. When iteration number is greater than the value, algorithm switches.

HeatBalanceAlgorithm¶

from idfpy.models import HeatBalanceAlgorithm unique

Determines which Heat Balance Algorithm will be used ie. CTF (Conduction Transfer Functions), EMPD (Effective Moisture Penetration Depth with Conduction Transfer Functions). Advanced/Research Usage: CondFD (Conduction Finite Difference) Advanced/Research Usage: ConductionFiniteDifferenceSimplified Advanced/Research Usage: HAMT (Combined Heat And Moisture Finite Element)

Field	Type	Default	Details
`algorithm` Algorithm	choice	`ConductionTransferFunction`	One of `CombinedHeatAndMoistureFiniteElement`, `ConductionFiniteDifference`, `ConductionTransferFunction`, `MoisturePenetrationDepthConductionTransferFunction`
`surface_temperature_upper_limit` Surface Temperature Upper Limit	number C	`200.0`	Range: ≥ 200
`minimum_surface_convection_heat_transfer_coefficient_value` Minimum Surface Convection Heat Transfer Coefficient Value	number W/m2-K	`0.1`	Range: > 0
`maximum_surface_convection_heat_transfer_coefficient_value` Maximum Surface Convection Heat Transfer Coefficient Value	number W/m2-K	`1000.0`	Range: ≥ 1

HeatBalanceSettings:ConductionFiniteDifference¶

from idfpy.models import HeatBalanceSettingsConductionFiniteDifference unique

Determines settings for the Conduction Finite Difference algorithm for surface heat transfer modeling.

Field	Type	Default	Details
`difference_scheme` Difference Scheme	choice	`FullyImplicitFirstOrder`	One of `CrankNicholsonSecondOrder`, `FullyImplicitFirstOrder`
`space_discretization_constant` Space Discretization Constant	number	`3.0`	increase or decrease number of nodes
`relaxation_factor` Relaxation Factor	number	`1.0`	Range: ≥ 0.01, ≤ 1
`inside_face_surface_temperature_convergence_criteria` Inside Face Surface Temperature Convergence Criteria	number	`0.002`	Range: ≥ 1e-07, ≤ 0.01

PerformancePrecisionTradeoffs¶

from idfpy.models import PerformancePrecisionTradeoffs unique

This object enables users to choose certain options that speed up EnergyPlus simulation, but may lead to small decreases in accuracy of results.

Field	Type	Default	Details
`use_coil_direct_solutions` Use Coil Direct Solutions	choice	`No`	If Yes, an analytical or empirical solution will be used to replace iterations in the coil performance calculations. One of `No`, `Yes`
`zone_radiant_exchange_algorithm` Zone Radiant Exchange Algorithm	choice	`ScriptF`	Determines which algorithm will be used to solve long wave radiant exchange among surfaces within a zone. One of `CarrollMRT`, `ScriptF`
`override_mode` Override Mode	choice	`Normal`	The increasing mode number roughly correspond with increased speed. A description of each mode are shown in the documentation. When Advanced is selected the N1 field value is used. One of `Advanced`, `Mode01`, `Mode02`, `Mode03`, `Mode04`, `Mode05`, `Mode06`, `Mode07`, `Mode08`, `Normal`
`maxzonetempdiff` MaxZoneTempDiff	number	`0.3`	Maximum zone temperature change before HVAC timestep is shortened. Only used when Override Mode is set to Advanced Range: ≥ 0.1, ≤ 3
`maxalloweddeltemp` MaxAllowedDelTemp	number	`0.002`	Maximum surface temperature change before HVAC timestep is shortened. Only used when Override Mode is set to Advanced Range: ≥ 0.002, ≤ 0.1
`use_representative_surfaces_for_calculations` Use Representative Surfaces for Calculations	choice	`No`	Automatically group surfaces with similar characteristics and perform relevant calculations only once for each group. One of `No`, `Yes`

ShadowCalculation¶

from idfpy.models import ShadowCalculation unique extensible

This object is used to control details of the solar, shading, and daylighting models

Field	Type	Default	Details
`shading_calculation_method` Shading Calculation Method	choice	`PolygonClipping`	Select between CPU-based polygon clipping method, the GPU-based pixel counting method, or importing from external shading data. If PixelCounting is selected and GPU hardware (or GPU emulation) is not available, a warning will be displayed and EnergyPlus will revert to PolygonClipping. If Scheduled is chosen, the Sunlit Fraction Schedule Name is required in SurfaceProperty:LocalEnvironment. If Imported is chosen, the Schedule:File:Shading object is required. One of `Imported`, `PixelCounting`, `PolygonClipping`, `Scheduled`
`shading_calculation_update_frequency_method` Shading Calculation Update Frequency Method	choice	`Periodic`	choose calculation frequency method. note that Timestep is only needed for certain cases and can increase execution time significantly. One of `Periodic`, `Timestep`
`shading_calculation_update_frequency` Shading Calculation Update Frequency	integer	`20`	enter number of days this field is only used if the previous field is set to Periodic warning issued if >31 Range: ≥ 1
`maximum_figures_in_shadow_overlap_calculations` Maximum Figures in Shadow Overlap Calculations	integer	`15000`	Number of allowable figures in shadow overlap in PolygonClipping calculations Range: ≥ 200
`polygon_clipping_algorithm` Polygon Clipping Algorithm	choice	`SutherlandHodgman`	Advanced Feature. Internal default is SutherlandHodgman Refer to InputOutput Reference and Engineering Reference for more information One of `ConvexWeilerAtherton`, `SlaterBarskyandSutherlandHodgman`, `SutherlandHodgman`
`pixel_counting_resolution` Pixel Counting Resolution	integer	`512`	Number of pixels in both dimensions of the surface rendering
`sky_diffuse_modeling_algorithm` Sky Diffuse Modeling Algorithm	choice	`SimpleSkyDiffuseModeling`	Advanced Feature. Internal default is SimpleSkyDiffuseModeling If you have shading elements that change transmittance over the year, you may wish to choose the detailed method. Refer to InputOutput Reference and Engineering Reference for more information One of `DetailedSkyDiffuseModeling`, `SimpleSkyDiffuseModeling`
`output_external_shading_calculation_results` Output External Shading Calculation Results	choice	`No`	If Yes is chosen, the calculated external shading fraction results will be saved to an external CSV file with surface names as the column headers. One of `No`, `Yes`
`disable_self_shading_within_shading_zone_groups` Disable Self-Shading Within Shading Zone Groups	choice	`No`	If Yes, self-shading will be disabled from all exterior surfaces in a given Shading Zone Group to surfaces within the same Shading Zone Group. If both Disable Self-Shading Within Shading Zone Groups and Disable Self-Shading From Shading Zone Groups to Other Zones = Yes, then all self-shading from exterior surfaces will be disabled. If only one of these fields = Yes, then at least one Shading Zone Group must be specified, or this field will be ignored. Shading from Shading:* surfaces, overhangs, fins, and reveals will not be disabled. One of `No`, `Yes`
`disable_self_shading_from_shading_zone_groups_to_other_zones` Disable Self-Shading From Shading Zone Groups to Other Zones	choice	`No`	If Yes, self-shading will be disabled from all exterior surfaces in a given Shading Zone Group to all other zones in the model. If both Disable Self-Shading Within Shading Zone Groups and Disable Self-Shading From Shading Zone Groups to Other Zones = Yes, then all self-shading from exterior surfaces will be disabled. If only one of these fields = Yes, then at least one Shading Zone Group must be specified, or this field will be ignored. Shading from Shading:* surfaces, overhangs, fins, and reveals will not be disabled. One of `No`, `Yes`
`shading_zone_groups`	list		Each item: `shading_zone_group_zonelist_name`

SimulationControl¶

from idfpy.models import SimulationControl unique

Note that the following 3 fields are related to the Sizing:Zone, Sizing:System, and Sizing:Plant objects. Having these fields set to Yes but no corresponding Sizing object will not cause the sizing to be done. However, having any of these fields set to No, the corresponding Sizing object is ignored. Note also, if you want to do system sizing, you must also do zone sizing in the same run or an error will result.

Field	Type	Default	Details
`do_zone_sizing_calculation` Do Zone Sizing Calculation	choice	`No`	If Yes, Zone sizing is accomplished from corresponding Sizing:Zone objects and autosize fields. One of `No`, `Yes`
`do_system_sizing_calculation` Do System Sizing Calculation	choice	`No`	If Yes, System sizing is accomplished from corresponding Sizing:System objects and autosize fields. If Yes, Zone sizing (previous field) must also be Yes. One of `No`, `Yes`
`do_plant_sizing_calculation` Do Plant Sizing Calculation	choice	`No`	If Yes, Plant sizing is accomplished from corresponding Sizing:Plant objects and autosize fields. One of `No`, `Yes`
`run_simulation_for_sizing_periods` Run Simulation for Sizing Periods	choice	`Yes`	If Yes, SizingPeriod:* objects are executed and results from those may be displayed.. One of `No`, `Yes`
`run_simulation_for_weather_file_run_periods` Run Simulation for Weather File Run Periods	choice	`Yes`	If Yes, RunPeriod:* objects are executed and results from those may be displayed.. One of `No`, `Yes`
`do_hvac_sizing_simulation_for_sizing_periods` Do HVAC Sizing Simulation for Sizing Periods	choice	`No`	If Yes, SizingPeriod:* objects are executed additional times for advanced sizing. Currently limited to use with coincident plant sizing, see Sizing:Plant object One of `No`, `Yes`
`maximum_number_of_hvac_sizing_simulation_passes` Maximum Number of HVAC Sizing Simulation Passes	integer	`1`	the entire set of SizingPeriod:* objects may be repeated to fine tune size results this input sets a limit on the number of passes that the sizing algorithms can repeat the set Range: ≥ 1

SurfaceConvectionAlgorithm:Inside¶

from idfpy.models import SurfaceConvectionAlgorithmInside unique

Default indoor surface heat transfer convection algorithm to be used for all zones

Field	Type	Default	Details
`algorithm` Algorithm	choice	`TARP`	Simple = constant value natural convection (ASHRAE) TARP = variable natural convection based on temperature difference (ASHRAE, Walton) CeilingDiffuser = ACH-based forced and mixed convection correlations for ceiling diffuser configuration with simple natural convection limit AdaptiveConvectionAlgorithm = dynamic selection of convection models based on conditions ASTMC1340 = mixed convection correlations based on heat flow direction, surface tilt angle, surface characteristic length, and air speed past the surface. One of `ASTMC1340`, `AdaptiveConvectionAlgorithm`, `CeilingDiffuser`, `Simple`, `TARP`

SurfaceConvectionAlgorithm:Outside¶

from idfpy.models import SurfaceConvectionAlgorithmOutside unique

Default outside surface heat transfer convection algorithm to be used for all zones

Field	Type	Default	Details
`algorithm` Algorithm	choice	`DOE-2`	SimpleCombined = Combined radiation and convection coefficient using simple ASHRAE model TARP = correlation from models developed by ASHRAE, Walton, and Sparrow et. al. MoWiTT = correlation from measurements by Klems and Yazdanian for smooth surfaces DOE-2 = correlation from measurements by Klems and Yazdanian for rough surfaces AdaptiveConvectionAlgorithm = dynamic selection of correlations based on conditions One of `AdaptiveConvectionAlgorithm`, `DOE-2`, `MoWiTT`, `SimpleCombined`, `TARP`

Timestep¶

from idfpy.models import Timestep unique

Specifies the "basic" timestep for the simulation. The value entered here is also known as the Zone Timestep. This is used in the Zone Heat Balance Model calculation as the driving timestep for heat transfer and load calculations.

Field	Type	Default	Details
`number_of_timesteps_per_hour` Number of Timesteps per Hour	integer	`6`	Number in hour: normal validity 4 to 60: 6 suggested Must be evenly divisible into 60 Allowable values include 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, and 60 Normal 6 is minimum as lower values may cause inaccuracies A minimum value of 20 is suggested for both ConductionFiniteDifference and CombinedHeatAndMoistureFiniteElement surface heat balance algorithms A minimum of 12 is suggested for simulations involving a Vegetated Roof (Material:RoofVegetation). Range: ≥ 1, ≤ 60

Version¶

from idfpy.models import Version unique

Specifies the EnergyPlus version of the IDF file.

Field	Type	Default	Details
`version_identifier` Version Identifier	string	`26.2`

ZoneAirContaminantBalance¶

from idfpy.models import ZoneAirContaminantBalance unique

Determines which contaminant concentration will be simulates.

Field	Type	Default	Details
`carbon_dioxide_concentration` Carbon Dioxide Concentration	choice	`No`	If Yes, CO2 simulation will be performed. One of `No`, `Yes`
`outdoor_carbon_dioxide_schedule_name` Outdoor Carbon Dioxide Schedule Name	reference		Schedule values should be in parts per million (ppm) Names a ExternalInterface:FunctionalMockupUnitExport:To:Schedule, ExternalInterface:FunctionalMockupUnitImport:To:Schedule, ExternalInterface:Schedule, Schedule:Compact, Schedule:Constant, Schedule:File, Schedule:Year, Schedule:Year:Rules
`generic_contaminant_concentration` Generic Contaminant Concentration	choice	`No`	If Yes, generic contaminant simulation will be performed. One of `No`, `Yes`
`outdoor_generic_contaminant_schedule_name` Outdoor Generic Contaminant Schedule Name	reference		Schedule values should be generic contaminant concentration in parts per million (ppm) Names a ExternalInterface:FunctionalMockupUnitExport:To:Schedule, ExternalInterface:FunctionalMockupUnitImport:To:Schedule, ExternalInterface:Schedule, Schedule:Compact, Schedule:Constant, Schedule:File, Schedule:Year, Schedule:Year:Rules

ZoneAirHeatBalanceAlgorithm¶

from idfpy.models import ZoneAirHeatBalanceAlgorithm unique

Controls the zone/space air heat balance.

Field	Type	Default	Details
`algorithm` Algorithm	choice	`ThirdOrderBackwardDifference`	Determines which algorithm will be used to solve the air heat balance. One of `AnalyticalSolution`, `EulerMethod`, `ThirdOrderBackwardDifference`
`do_space_heat_balance_for_sizing` Do Space Heat Balance for Sizing	choice	`No`	If yes, space heat balance will be calculated and reported during sizing. One of `No`, `Yes`
`do_space_heat_balance_for_simulation` Do Space Heat Balance for Simulation	choice	`No`	If yes, space heat balance will be calculated and reported during simulation. One of `No`, `Yes`

ZoneAirMassFlowConservation¶

from idfpy.models import ZoneAirMassFlowConservation unique

Enforces the zone air mass flow balance by either adjusting zone mixing object flow only, adjusting zone total return flow only, zone mixing and the zone total return flows, or adjusting the zone total return and zone mixing object flows. Zone infiltration flow air flow is increased or decreased depending user selection in the infiltration treatment method. If either of zone mixing or zone return flow adjusting methods or infiltration is active, then the zone air mass flow balance calculation will attempt to enforce conservation of mass for each zone. If flow balancing method is "None" and infiltration is "None", then the zone air mass flow calculation defaults to assume self-balanced simple flow mixing and infiltration objects.

Field	Type	Default	Details
`adjust_zone_mixing_and_return_for_air_mass_flow_balance` Adjust Zone Mixing and Return For Air Mass Flow Balance	choice	`None`	If "AdjustMixingOnly", zone mixing object flow rates are adjusted to balance the zone air mass flow and zone infiltration air flow may be increased or decreased if required in order to balance the zone air mass flow. If "AdjustReturnOnly", zone total return flow rate is adjusted to balance the zone air mass flow and zone infiltration air flow may be increased or decreased if required in order to balance the zone air mass flow. If "AdjustMixingThenReturn", first the zone mixing objects flow rates are adjusted to balance the zone air flow, second zone total return flow rate is adjusted and zone infiltration air flow may be increased or decreased if required in order to balance the zone air mass flow. If "AdjustReturnThenMixing", first zone total return flow rate is adjusted to balance the zone air flow, second the zone mixing object flow rates are adjusted and infiltration air flow may be increased or decreased if required in order to balance the zone air mass flow. One of `AdjustMixingOnly`, `AdjustMixingThenReturn`, `AdjustReturnOnly`, `AdjustReturnThenMixing`, `None`
`infiltration_balancing_method` Infiltration Balancing Method	choice	`AddInfiltrationFlow`	This input field allows user to choose how zone infiltration flow is treated during the zone air mass flow balance calculation. AddInfiltrationFlow may add infiltration to the base flow specified in the infiltration object to balance the zone air mass flow. The additional infiltration air mass flow is not self-balanced. The base flow is assumed to be self-balanced. AdjustInfiltrationFlow may adjust the base flow calculated using the base flow specified in the infiltration object to balance the zone air mass flow. If it If no adjustment is required, then the base infiltration is assumed to be self-balanced. None will make no changes to the base infiltration flow. One of `AddInfiltrationFlow`, `AdjustInfiltrationFlow`, `None`
`infiltration_balancing_zones` Infiltration Balancing Zones	choice	`MixingSourceZonesOnly`	This input field allows user to choose which zones are included in infiltration balancing. MixingSourceZonesOnly allows infiltration balancing only in zones which as source zones for mixing which also have an infiltration object defined. AllZones allows infiltration balancing in any zone which has an infiltration object defined. One of `AllZones`, `MixingSourceZonesOnly`

ZoneCapacitanceMultiplier:ResearchSpecial¶

from idfpy.models import ZoneCapacitanceMultiplierResearchSpecial

Multiplier altering the relative capacitance of the air compared to an empty zone

Field	Type	Default	Details
`name` Name required	string
`zone_or_zonelist_name` Zone or ZoneList Name	reference		If this field is left blank, the multipliers are applied to all the zones not specified Names a Zone, ZoneList
`temperature_capacity_multiplier` Temperature Capacity Multiplier	number	`1.0`	Used to alter the capacitance of zone air with respect to heat or temperature Range: > 0
`humidity_capacity_multiplier` Humidity Capacity Multiplier	number	`1.0`	Used to alter the capacitance of zone air with respect to moisture or humidity ratio Range: > 0
`carbon_dioxide_capacity_multiplier` Carbon Dioxide Capacity Multiplier	number	`1.0`	Used to alter the capacitance of zone air with respect to zone air carbon dioxide concentration Range: > 0
`generic_contaminant_capacity_multiplier` Generic Contaminant Capacity Multiplier	number	`1.0`	Used to alter the capacitance of zone air with respect to zone air generic contaminant concentration Range: > 0