honeybee_designbuilder.writer module

Methods to write Honeybee core objects to dsbXML.

honeybee_designbuilder.writer.face_to_dsbxml(face)[source]

Generate an dsbXML Surface string from a honeybee Face.

The resulting string has all constituent geometry (Apertures, Doors).

Parameters:

face – A honeybee Face for which an dsbXML Surface string object will be returned.

honeybee_designbuilder.writer.face_to_dsbxml_element(face, zone_body_element=None, zone_face_indices=None, adjacency_faces=None, tolerance=0.01, angle_tolerance=1.0, reset_counter=True)[source]

Generate an dsbXML Surface Element object from a honeybee Face.

The resulting Element has all constituent geometry (Apertures, Doors).

Parameters:

  • face – A honeybee Face for which an dsbXML Surface Element object will be returned.

  • zone_body_element – An optional XML Element for the Zone Body to which the generated surface object will be added. If None, a new XML Element will be generated. Note that this Zone Body element should have a Surfaces tag already created within it.

  • zone_face_indices – An optional tuple of integers for the vertex indices of the face in the parent Room Polyface3D. If None, some placeholder indices will be generated. (Default: None).

  • adjacency_faces – An optional list of Honeybee Faces for sub-elements of the input face that specify adjacencies to multiple other Faces. When specified, these adjacency faces should be coplanar to the input face and should together completely fill its area. If None, it will be assumed that the face in dsbXML should have only one adjacency. (Default: None).

  • tolerance – The absolute tolerance with which the Room geometry will be evaluated. (Default: 0.01, suitable for objects in meters).

  • angle_tolerance – The angle tolerance at which the geometry will be evaluated in degrees. This is needed to determine whether to write roof faces as flat or pitched. (Default: 1 degree).

  • reset_counter – A boolean to note whether the global counter for unique handles should be reset after the method is run. (Default: True).

honeybee_designbuilder.writer.model_to_dsbxml(model, xml_template='Default', program_name=None)[source]

Generate an dsbXML string for a Model.

The resulting string will include all geometry (Rooms, Faces, Apertures, Doors, Shades), all fully-detailed constructions + materials, all fully-detailed schedules, and the room properties. It will also include the simulation parameters. Essentially, the string includes everything needed to simulate the model.

Parameters:

  • model – A honeybee Model for which an dsbXML text string will be returned.

  • xml_template –

    Text for the type of template file to be used to write the dsbXML. Different templates contain different amounts of default assembly library data, which may be needed in order to import the dsbXML into older versions of DesignBuilder. However, this data can greatly increase the size of the resulting dsbXML file. Choose from the following options.

    • Default - a minimal file that imports into the latest versions

    • Assembly - the Default plus an AssemblyLibrary with typical objects

    • Full - a large file with all libraries that can be imported to version 7.3

  • program_name – Optional text to set the name of the software that will appear under a comment in the XML to identify where it is being exported from. This can be set things like “Ladybug Tools” or “Pollination” or some other software in which this dsbXML export capability is being run. If None, no comment will appear. (Default: None).

Usage:

import os
from honeybee.model import Model
from honeybee.room import Room
from honeybee.config import folders

# Crate an input Model
room = Room.from_box('Tiny House Zone', 5, 10, 3)
room.properties.energy.program_type = office_program
room.properties.energy.add_default_ideal_air()
model = Model('Tiny House', [room])

# create the dsbXML string for the model
xml_str = model.to.dsbxml(model)

# write the final string into an XML file using DesignBuilder encoding
dsbxml = os.path.join(folders.default_simulation_folder, 'in_dsb.xml')
with open(dsbxml, 'wb') as fp:
    fp.write(xml_str.encode('iso-8859-15'))
honeybee_designbuilder.writer.model_to_dsbxml_element(model, xml_template='Default')[source]

Generate an dsbXML Element object for a honeybee Model.

The resulting Element has all geometry (Rooms, Faces, Apertures, Doors, Shades).

Parameters:

  • model – A honeybee Model for which an dsbXML ElementTree object will be returned.

  • xml_template –

    Text for the type of template file to be used to write the dsbXML. Different templates contain different amounts of default assembly library data, which may be needed in order to import the dsbXML into older versions of DesignBuilder. However, this data can greatly increase the size of the resulting dsbXML file. Choose from the following options.

    • Default - a minimal file that imports into the latest versions

    • Assembly - the Default plus an AssemblyLibrary with typical objects

    • Full - a large file with all libraries that can be imported to version 7.3

honeybee_designbuilder.writer.model_to_dsbxml_file(model, output_file, xml_template='Default', program_name=None)[source]

Write an dsbXML file from a Honeybee Model.

Note that this method also ensures that the resulting dsbXML file uses the ISO-8859-15 encoding that is used by DesignBuilder.

Parameters:

  • model – A honeybee Model for which an dsbXML file will be written.

  • output_file – The path to the XML file that will be written from the model.

  • xml_template –

    Text for the type of template file to be used to write the dsbXML. Different templates contain different amounts of default assembly library data, which may be needed in order to import the dsbXML into older versions of DesignBuilder. However, this data can greatly increase the size of the resulting dsbXML file. Choose from the following options.

    • Default - a minimal file that imports into the latest versions

    • Assembly - the Default plus an AssemblyLibrary with typical objects

    • Full - a large file with all libraries that can be imported to version 7.3

  • program_name – Optional text to set the name of the software that will appear under a comment in the XML to identify where it is being exported from. This can be set things like “Ladybug Tools” or “Pollination” or some other software in which this dsbXML export capability is being run. If None, no comment will appear. (Default: None).

honeybee_designbuilder.writer.room_group_to_dsbxml_block(room_group, block_handle, building_element=None, block_name=None, tolerance=0.01, angle_tolerance=1.0, reset_counter=True)[source]

Generate an dsbXML BuildingBlock Element object for a list of honeybee Rooms.

The resulting Element has all geometry (Rooms, Faces, Apertures, Doors, Shades).

Parameters:

  • room_group – A list of honeybee Room objects for which an dsbXML BuildingBlock Element object will be returned. Note that these rooms must form a contiguous volume across their adjacencies for the resulting block to be valid.

  • block_handle – An integer for the handle of the block. This must be unique within the larger model.

  • building_element – An optional XML Element for the Building to which the generated block object will be added. If None, a new XML Element will be generated. Note that this Building element should have a BuildingBlocks tag already created within it.

  • tolerance – The absolute tolerance with which the Room geometry will be evaluated. (Default: 0.01, suitable for objects in meters).

  • angle_tolerance – The angle tolerance at which the geometry will be evaluated in degrees. (Default: 1 degree).

  • reset_counter – A boolean to note whether the global counter for unique handles should be reset after the method is run. (Default: True).

honeybee_designbuilder.writer.room_to_dsbxml(room)[source]

Generate an dsbXML Zone string object for a honeybee Room.

The resulting string has all constituent geometry (Faces, Apertures, Doors).

Parameters:

room – A honeybee Room for which an dsbXML Zone string object will be returned.

honeybee_designbuilder.writer.room_to_dsbxml_element(room, block_element=None, tolerance=0.01, angle_tolerance=1.0, reset_counter=True)[source]

Generate an dsbXML Zone Element object for a honeybee Room.

The resulting Element has all constituent geometry (Faces, Apertures, Doors).

Parameters:

  • room – A honeybee Room for which an dsbXML Zone Element object will be returned.

  • block_element – An optional XML Element for the BuildingBlock to which the generated zone object will be added. If None, a new XML Element will be generated. Note that this BuildingBlock element should have a Zones tag already created within it.

  • tolerance – The absolute tolerance with which the Room geometry will be evaluated. (Default: 0.01, suitable for objects in meters).

  • angle_tolerance – The angle tolerance at which the geometry will be evaluated in degrees. (Default: 1 degree).

  • reset_counter – A boolean to note whether the global counter for unique handles should be reset after the method is run. (Default: True).

honeybee_designbuilder.writer.shade_mesh_to_dsbxml(shade_mesh)[source]

Generate an dsbXML Planes string from a honeybee ShadeMesh.

Parameters:

shade_mesh – A honeybee ShadeMesh for which an dsbXML Planes XML string will be returned.

honeybee_designbuilder.writer.shade_mesh_to_dsbxml_element(shade_mesh, building_element=None, reset_counter=True)[source]

Generate an dsbXML Planes Element object from a honeybee ShadeMesh.

Parameters:

  • shade_mesh – A honeybee ShadeMesh for which an dsbXML Planes Element object will be returned.

  • building_element – An optional XML Element for the Building to which the generated objects will be added. If None, a new XML Element will be generated. Note that this Building element should have a Planes tag already created within it.

  • reset_counter – A boolean to note whether the global counter for unique handles should be reset after the method is run. (Default: True).

honeybee_designbuilder.writer.shade_to_dsbxml(shade)[source]

Generate an dsbXML Plane string from a honeybee Shade.

Parameters:

shade – A honeybee Shade for which an dsbXML Plane XML string will be returned.

honeybee_designbuilder.writer.shade_to_dsbxml_element(shade, building_element=None)[source]

Generate an dsbXML Plane Element object from a honeybee Shade.

Parameters:

  • shade – A honeybee Shade for which an dsbXML Plane Element object will be returned.

  • building_element – An optional XML Element for the Building to which the generated plane object will be added. If None, a new XML Element will be generated. Note that this Building element should have a Planes tag already created within it.

honeybee_designbuilder.writer.sub_face_to_dsbxml(sub_face)[source]

Generate an dsbXML Opening string from a honeybee Aperture or Door.

Parameters:

sub_face – A honeybee Aperture or Door for which an dsbXML Opening XML string will be returned.

honeybee_designbuilder.writer.sub_face_to_dsbxml_element(sub_face, surface_element=None)[source]

Generate an dsbXML Opening Element object from a honeybee Aperture or Door.

Parameters:

  • sub_face – A honeybee Aperture or Door for which an dsbXML Opening Element object will be returned.

  • surface_element – An optional XML Element for the Surface to which the generated opening object will be added. If None, a new XML Element will be generated. Note that this Surface element should have a Openings tag already created within it.