honeybee_energy.properties.model module

Model Energy Properties.

class honeybee_energy.properties.model.ModelEnergyProperties(host, ventilation_simulation_control=None, electric_load_center=None)

Bases: object

Energy Properties for Honeybee Model.

Parameters:

• host – A honeybee_core Model object that hosts these properties.

• ventilation_simulation_control – A VentilationSimulationControl object that defines global parameters for ventilation simulation.

• electric_load_center – A ElectricLoadCenter object that defines the properties of the model’s electric loads center.

Properties:

• host

• materials

• constructions

• room_constructions

• face_constructions

• shade_constructions

• construction_sets

• global_construction_set

• schedule_type_limits

• schedules

• shade_schedules

• room_schedules

• program_type_schedules

• hvac_schedules

• orphaned_trans_schedules

• program_types

• hvacs

• shws

• ventilation_simulation_control

• electric_load_center

ToString()

add_autocal_properties_to_dict(data)

Add auto-calculated energy properties to a Model dictionary.

This includes Room volumes, ceiling heights, and (in the case of Faces and Shades with holes) vertices. These properties are used in translation from Honeybee to OpenStudio to ensure that the properties in Honeybee are aligned with those in OSM, IDF, and gbXML.

Note that the host model must be in Meters in order for the added properties to be in the correct units system.

Parameters:

data – A dictionary representation of an entire honeybee-core Model.

aperture_constructions(room_assigned_only=True)

Get only the constructions assigned to Apertures in the Model.

Parameters:

room_assigned_only – Boolean to note whether only the constructions that are a part of Room-assigned Apertures should be returned (True) or constructions assigned to all Apertures should be included (False).

apply_properties_from_dict(data)

Apply the energy properties of a dictionary to the host Model of this object.

Parameters:

data – A dictionary representation of an entire honeybee-core Model. Note that this dictionary must have ModelEnergyProperties in order for this method to successfully apply the energy properties.

assign_dynamic_aperture_groups()

Assign aperture groups to all Apertures with dynamic and shaded constructions.

Note that this method will only add two groups for each dynamic aperture. The first group will be completely transparent while the second group will be a 100% transmittance perfectly diffusing modifier. This is done with the assumption that EnergyPlus transmittance results will be used to appropriately account for the transmittance of states in the results.

assign_radiance_solar_exterior()

Assign honeybee Radiance modifiers based on exterior solar properties.

assign_radiance_solar_interior()

Assign honeybee Radiance modifiers based on interior solar properties.

assign_radiance_visible_exterior()

Assign honeybee Radiance modifiers based on exterior visible properties.

assign_radiance_visible_interior()

Assign honeybee Radiance modifiers based on interior visible properties.

autocalculate_ventilation_simulation_control()

Set geometry properties of ventilation_simulation_control with Model’s rooms.

The room geometry of the host Model will be used to assign the aspect_ratio, long_axis_angle, and the building_type. Note that these properties are only meaningful for simulations using the AirflowNetwork.

check_all(raise_exception=True, detailed=False)

Check all of the aspects of the Model energy properties.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if any errors are found. If False, this method will simply return a text string with all errors that were found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_all_air_boundaries_with_window(raise_exception=True, detailed=False)

Check there are no Rooms with windows and otherwise composed of AirBoundaries.

This is a requirement for energy simulation since EnergyPlus will throw an error if it encounters a Room composed entirely of AirBoundaries except for one Face with a window.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if a Room composed entirely of AirBoundaries is found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_detailed_hvac_rooms(raise_exception=True, detailed=False)

Check that any rooms referenced within a DetailedHVAC exist in the model.

This method will also check to make sure that two detailed HVACs do not reference the same room and that all rooms referencing a detailed HVAC have setpoints.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if DetailedHVAC reference Rooms that are not in the Model. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_construction_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Construction identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_construction_set_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate ConstructionSet identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_hvac_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate HVAC identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_material_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Material identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_program_type_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate ProgramType identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_schedule_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Schedule identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_schedule_type_limit_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate ScheduleTypeLimit identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_shw_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate SHW identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_for_extension(raise_exception=True, detailed=False)

Check that the Model is valid for EnergyPlus simulation.

This process includes all relevant honeybee-core checks as well as checks that apply only for EnergyPlus.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if any errors are found. If False, this method will simply return a text string with all errors that were found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_interior_constructions_reversed(raise_exception=True, detailed=False)

Check that all interior constructions are in reversed order for paired faces.

Note that, if there are missing adjacencies in the model, the message from this method will simply note this fact without reporting on mis-matched layers.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if mis-matched interior construction layers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_one_vegetation_material(raise_exception=True, detailed=False)

Check that there no more than one EnergyMaterialVegetation in the model.

It is a limitation of EnergyPlus that it can only simulate a single eco roof per model. This should probably be addressed at some point so that we don’t always have to check for it.

Parameters:

• raise_exception – Boolean for whether a ValueError should be raised if there’s more than one EnergyMaterialVegetation in the Model. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_shw_rooms_in_model(raise_exception=True, detailed=False)

Check that the room_identifiers of SHWSystems are in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if SHWSystems reference Rooms that are not in the Model. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

door_constructions(room_assigned_only=True)

Get only the constructions assigned to Doors in the Model.

Parameters:

room_assigned_only – Boolean to note whether only the constructions that are a part of Room-assigned Doors should be returned (True) or constructions assigned to all Doors should be included (False).

static dump_properties_to_dict(materials=None, constructions=None, construction_sets=None, schedule_type_limits=None, schedules=None, program_types=None, hvacs=None, shws=None)

Get a ModelEnergyProperties dictionary from arrays of Python objects.

Parameters:

• materials – A list or tuple of energy material objects.

• constructions – A list or tuple of construction objects.

• construction_sets – A list or tuple of construction set objects.

• schedule_type_limits – A list or tuple of schedule type limit objects.

• schedules – A list or tuple of schedule objects.

• program_types – A list or tuple of program type objects.

• hvacs – A list or tuple of HVACSystem objects.

• shws – A list or tuple of SHWSystem objects.

Returns:

A dictionary representation of ModelEnergyProperties. Note that

all objects in this dictionary will follow the abridged schema.

Return type:

data

duplicate(new_host=None)

Get a copy of this object.

Parameters:

new_host – A new Model object that hosts these properties. If None, the properties will be duplicated with the same host.

generate_ground_room(soil_construction)

Generate and add a Room to the Model that represents the ground.

The Room will be added such that it exists below all of the other geometry of the model and covers the full XY extents of the model.

This is useful when it is desirable to track the ground surface temperature or when the model needs a simple Room to be able to simulate in EnergyPlus.

Parameters:

soil_construction – An OpaqueConstruction that reflects the soil type of the ground. If a multi-layered construction is input, the multiple layers will only be used for the roof Face of the Room and all other Faces will get a construction with the inner-most layer assigned. If the outer-most material is an EnergyMaterialVegetation and there are no other layers in the construction, the vegetation’s soil material will be used for all other Faces.

static load_properties_from_dict(data, skip_invalid=False)

Load model energy properties of a dictionary to Python objects.

Loaded objects include Materials, Constructions, ConstructionSets, ScheduleTypeLimits, Schedules, and ProgramTypes.

The function is called when re-serializing a Model object from a dictionary to load honeybee_energy objects into their Python object form before applying them to the Model geometry.

Parameters:

• data – A dictionary representation of an entire honeybee-core Model. Note that this dictionary must have ModelEnergyProperties in order for this method to successfully load the energy properties.

• skip_invalid – A boolean to note whether objects that cannot be loaded should be ignored (True) or whether an exception should be raised about the invalid object (False). (Default: False).

Returns:

A tuple with eight elements

• materials – A dictionary with identifiers of materials as keys and Python material objects as values.

• constructions – A dictionary with identifiers of constructions as keys and Python construction objects as values.

• construction_sets – A dictionary with identifiers of construction sets as keys and Python construction set objects as values.

• schedule_type_limits – A dictionary with identifiers of schedule type limits as keys and Python schedule type limit objects as values.

• schedules – A dictionary with identifiers of schedules as keys and Python schedule objects as values.

• program_types – A dictionary with identifiers of program types as keys and Python program type objects as values.

• hvacs – A dictionary with identifiers of HVAC systems as keys and Python HVACSystem objects as values.

• shws – A dictionary with identifiers of SHW systems as keys and Python SHWSystem objects as values.

missing_adjacencies_to_adiabatic()

Set any Faces with missing adjacencies in the model to adiabatic.

If any of the Faces with missing adjacencies have sub-faces, these will be removed in order to accommodate the adiabatic condition. Similarly, if the Face is an AirBoundary, the type will be set to a Wall.

Note that this method assumes all of the Surface boundary conditions are set up correctly with the last boundary_condition_object being the adjacent room.

offset_and_assign_exterior_face_modifiers(reflectance_type='Solar', offset=0.02)

Offset all exterior Faces and assign them a modifier based on exterior layer.

This is often useful in conjunction with the assign_radiance_solar_interior or the assign_radiance_visible_interior to make a radiance model that accounts for both the interior and exterior material layers.

Note that this method will add the offset faces as orphaned faces and so the model will not be simulate-able in EnergyPlus after running this method (it is only intended to be simulated within Radiance).

Parameters:

• reflectance_type – Text for the type of reflectance to be used in the assigned modifier. Must be either Solar or Visible. (Default: Solar).

• offset – A number for the distance at which the exterior Faces should be offset. (Default: 0.02, suitable for models in meters).

remove_child_constructions()

Remove constructions assigned to Faces, Apertures, Doors and Shades.

This means that all constructions of the Mode’s rooms will be assigned by the Rooms’ construction_set (or the Honeybee default ConstructionSet if Rooms have no construction set).

remove_hvac_from_no_setpoints()

Remove any HVAC systems assigned to Rooms that have no thermostat setpoints.

This will ensure that EnergyPlus does not fail when it tries to simulate a HVAC for which there are no criteria to meet.

Returns:

A list of text strings for each room that had an HVAC removed because of a lack of setpoints. This can be printed to logs or registered as a warning in the interface.

reset_resource_ids(reset_materials=True, reset_constructions=True, reset_construction_sets=True, reset_schedules=True, reset_programs=True)

Reset the identifiers of energy resource objects in this Model.

Note that this method may have unintended consequences if the resources assigned to this Model instance are also being used by another Model instance that exists in the current Python session. In this case, running this method will result in the resource identifiers of the other Model also being reset.

This method is useful when human-readable names are needed when the model is exported to other formats like IDF and OSM. Cases of duplicate IDs resulting from non-unique names will be resolved by adding integers to the ends of the new IDs that are derived from the name.

Parameters:

• reset_materials – Boolean to note whether the IDs of all materials in the model should be reset or kept. (Default: True).

• reset_constructions – Boolean to note whether the IDs of all constructions in the model should be reset or kept. (Default: True).

• reset_construction_sets – Boolean to note whether the IDs of all construction sets in the model should be reset or kept. (Default: True).

• reset_schedules – Boolean to note whether the IDs of all schedules in the model should be reset or kept. (Default: True).

• reset_programs – Boolean to note whether the IDs of all program types in the model should be reset or kept. (Default: True).

Returns:

A dictionary with the original identifiers of resources as keys and the edited resource objects as values. This can be used to set the identifiers of the objects back to the original value after this method has been run and any other routines have been performed. This will help prevent unintended consequences of changing the resource identifiers in the global resource library or in other Models that may be using the same resource object instances.

static reset_resource_ids_in_dict(data, add_uuid=False, reset_materials=True, reset_constructions=True, reset_construction_sets=True, reset_schedules=True, reset_programs=True)

Reset the identifiers of energy resource objects in a Model dictionary.

This is useful when human-readable names are needed when the model is exported to other formats like IDF and OSM and the uniqueness of the identifiers is less of a concern.

Parameters:

• data – A dictionary representation of an entire honeybee-core Model. Note that this dictionary must have ModelEnergyProperties in order for this method to successfully edit the energy properties.

• add_uuid – Boolean to note whether newly-generated resource object IDs should be derived only from a cleaned display_name (False) or whether this new ID should also have a unique set of 8 characters appended to it to guarantee uniqueness. (Default: False).

• reset_materials – Boolean to note whether the IDs of all materials in the model should be reset or kept. (Default: True).

• reset_constructions – Boolean to note whether the IDs of all constructions in the model should be reset or kept. (Default: True).

• reset_construction_sets – Boolean to note whether the IDs of all construction sets in the model should be reset or kept. (Default: True).

• reset_schedules – Boolean to note whether the IDs of all schedules in the model should be reset or kept. (Default: True).

• reset_programs – Boolean to note whether the IDs of all program types in the model should be reset or kept. (Default: True).

Returns:

A new Model dictionary with the resource identifiers reset. All references to the reset resources will be correct and valid in the resulting dictionary, assuming that the input is valid.

static restore_resource_ids(resource_map)

Restore the identifiers of resource objects after resetting them.

This can be used to set the identifiers of the objects back to the original value after the reset_resource_ids() method was called. This will help prevent unintended consequences of changing the resource identifiers in the global resource library or in other Models that may be using the same resource object instances.

Parameters:

resource_map – A dictionary with the original identifiers of resources as keys and the edited resource objects as values. This type of dictionary is output from the reset_resource_ids method.

simplify_window_constructions_in_dict(data)

Convert all window constructions in a model dictionary to SimpleGlazSys.

This is useful when translating to gbXML and other formats that do not support layered window constructions.

Parameters:

data – A dictionary representation of an entire honeybee-core Model.

sync_detailed_hvac_ids(room_map)

Sync room identifiers in DetailedHVAC with rooms that had their IDs changed.

This is useful after running the Model.reset_ids() command to ensure that the bi-directional Room references between DetailedHVAC and Honeybee Rooms is correct.

Parameters:

room_map – A dictionary that relates the original Rooms identifiers (keys) to the new identifiers (values) of the Rooms in the Model.

to_dict()

Return Model energy properties as a dictionary.

window_construction_by_orientation(construction, orientation=0, offset=45, north_vector=Vector2D(0.00, 1.00))

Set the construction of exterior Apertures facing a given orientation.

This is useful for testing orientation-specific energy conservation strategies or creating ASHRAE baseline buildings.

Parameters:

• construction – A WindowConstruction that will be assigned to all of the room’s Apertures in Walls that are facing a certain orientation.

• orientation – A number between 0 and 360 that represents the orientation in degrees to which the construction will be assigned. 0 = North, 90 = East, 180 = South, 270 = West. (Default: 0 for North).

• offset – A number between 0 and 180 that represents the offset from the orientation in degrees for which the construction will be assigned. For example, a value of 45 indicates that any Apertures falling in the 90 degree range around the orientation will get the input construction. (Default: 45).

• north_vector – A ladybug_geometry Vector3D for the north direction. Default is the Y-axis (0, 1).

property construction_schedules

Get a list of all unique schedules assigned to constructions in the model.

This includes schedules on al AirBoundaryConstructions.

property construction_sets

Get a list of all unique Room-Assigned ConstructionSets in the Model.

property constructions

Get a list of all unique constructions in the model.

This includes constructions across all Faces, Apertures, Doors, Shades, and Room ConstructionSets but it does NOT include the Honeybee generic default construction set.

property electric_load_center

Get or set global parameters for ventilation cooling simulation.

property face_constructions

Get a list of all unique constructions assigned to Faces, Apertures and Doors.

property global_construction_set

The global energy construction set.

This is what is used whenever no construction has been assigned to a given Face/Aperture/Door/Shade and there is no construction_set assigned to the parent Room.

property host

Get the Model object hosting these properties.

property hvac_schedules

Get a list of all unique HVAC-assigned schedules in the model.

property hvacs

Get a list of all unique HVAC systems in the Model.

property materials

Get a list of all unique materials contained within the model.

This includes materials across all Faces, Apertures, Doors and Room ConstructionSets but it does NOT include the Honeybee generic default construction set.

property orphaned_trans_schedules

Get a list of constant transmittance schedules for transparent orphaned objs.

These schedules are not directly assigned to any honeybee objects but they are automatically generated from the constructions of orphaned objects. They are intended to be assigned to shade representations of the orphaned objects in the simulation in order to account for their transparency.

property program_type_schedules

Get a list of all unique schedules assigned to ProgramTypes in the model.

property program_types

Get a list of all unique ProgramTypes in the Model.

property room_constructions

Get a list of all unique constructions assigned to Room ConstructionSets.

This also includes the constructions assigned to Room InternalMasses.

property room_schedules

Get a list of all unique schedules assigned directly to Rooms in the model.

Note that this does not include schedules from ProgramTypes assigned to the rooms. For this, use the program_type_schedules property.

property schedule_type_limits

Get a list of all unique schedule type limits contained within the model.

This includes schedules across all Shades and Rooms.

property schedules

Get a list of all unique schedules directly assigned to objects in the model.

This includes schedules across all ProgramTypes, HVACs, Rooms and Shades. However, it does not include any of the orphaned_trans_schedules as these are not directly assigned to objects but rather generated from their constructions.

property shade_constructions

Get a list of all unique constructions assigned to Shades in the model.

property shade_schedules

Get a list of unique transmittance schedules assigned to Shades in the model.

property shws

Get a list of all unique SHW systems in the Model.

property ventilation_simulation_control

Get or set global parameters for ventilation cooling simulation.