dragonfly_energy.des.loop module

Thermal Loop of a District Energy System (DES).

class dragonfly_energy.des.loop.FourthGenThermalLoop(identifier, chilled_water_setpoint=6, hot_water_setpoint=54)[source]

Bases: object

Represents a Fourth Generation Heating/Cooling Thermal Loop in a DES.

Parameters
  • identifier – Text string for a unique thermal loop ID. Must contain only characters that are acceptable in OpenDSS. This will be used to identify the object across the exported geoJSON and OpenDSS files.

  • chilled_water_setpoint – A number for the temperature of chilled water in the DES in degrees C. (Default: 6).

  • hot_water_setpoint – A number for the temperature of hot water in the DES in degrees C. (Default: 54).

Properties:
  • identifier

  • display_name

  • chilled_water_setpoint

  • hot_water_setpoint

ToString()[source]
duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Initialize an FourthGenThermalLoop from a dictionary.

Parameters

data – A dictionary representation of an FourthGenThermalLoop object.

to_des_param_dict(buildings, tolerance=0.01)[source]

Get the DES System Parameter dictionary for the ThermalLoop.

Parameters
  • buildings – An array of Dragonfly Building objects that are along the FourthGenThermalLoop. Buildings that do not have their footprint touching the loop’s ThermalConnectors are automatically excluded in the result.

  • tolerance – The minimum difference between the coordinate values of two geometries at which they are considered co-located. (Default: 0.01, suitable for objects in meters).

to_dict()[source]

FourthGenThermalLoop dictionary representation.

property chilled_water_setpoint

Get or set a number for the chilled water setpoint in degrees C.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property hot_water_setpoint

Get or set a number for the hot water setpoint in degrees C.

property identifier

Get or set the text string for unique object identifier.

class dragonfly_energy.des.loop.GHEThermalLoop(identifier, ground_heat_exchangers, connectors, clockwise_flow=False, soil_parameters=None, fluid_parameters=None, pipe_parameters=None, borehole_parameters=None)[source]

Bases: object

Represents an Ground Heat Exchanger Thermal Loop in a DES.

This includes a GroundHeatExchanger and all thermal connectors needed to connect these objects to Dragonfly Buildings in a loop.

Parameters
  • identifier – Text string for a unique thermal loop ID. Must contain only characters that are acceptable in OpenDSS. This will be used to identify the object across the exported geoJSON and OpenDSS files.

  • ground_heat_exchangers – An array of GroundHeatExchanger objects representing the fields of boreholes that supply the loop with thermal capacity.

  • connectors – An array of ThermalConnector objects that are included within the thermal loop. In order for a given connector to be valid within the loop, each end of the connector must touch either another connector, a building footprint, or the ground_heat_exchangers. In order for the loop as a whole to be valid, the connectors must form a single continuous loop when passed through the buildings and the heat exchanger field.

  • clockwise_flow – A boolean to note whether the direction of flow through the loop is clockwise (True) when viewed from above in the GeoJSON or it is counterclockwise (False). (Default: False).

  • soil_parameters – Optional SoilParameter object to specify the properties of the soil in which the loop is operating.

  • fluid_parameters – Optional FluidParameter object to specify the properties of the fluid that is circulating through the loop.

  • pipe_parameters – Optional PipeParameter object to specify the properties of the ground-heat-exchanging pipes used across the loop.

  • borehole_parameters – Optional BoreholeParameter object to specify the properties of the boreholes used across the loop.

Properties:
  • identifier

  • display_name

  • ground_heat_exchangers

  • connectors

  • clockwise_flow

  • soil_parameters

  • fluid_parameters

  • pipe_parameters

  • borehole_parameters

ToString()[source]
static assign_junction_buildings(junctions, buildings, tolerance=0.01)[source]

Assign building_identifiers to a list of junctions using dragonfly Buildings.

Junctions will be assigned to a given Building if they are touching the footprint of that building in 2D space.

Parameters
  • junctions – An array of ThermalJunction objects to be associated with Dragonfly Buildings.

  • buildings – An array of Dragonfly Building objects in the same units system as the ThermalLoop geometry.

  • tolerance – The minimum difference between the coordinate values of two geometries at which they are considered co-located. (Default: 0.01, suitable for objects in meters).

convert_to_units(units='Meters', starting_units='Meters')[source]

Convert all of the geometry in this ThermalLoop to certain units.

Parameters
  • units

    Text for the units to which the Model geometry should be converted. (Default: Meters). Choose from the following:

    • Meters

    • Millimeters

    • Feet

    • Inches

    • Centimeters

  • starting_units – The starting units system of the loop. (Default: Meters).

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Initialize an GHEThermalLoop from a dictionary.

Parameters

data – A dictionary representation of an GHEThermalLoop object.

classmethod from_geojson(geojson_file_path, location=None, point=None, units='Meters', clockwise_flow=False)[source]

Get an GHEThermalLoop from a dictionary as it appears in a GeoJSON.

Parameters
  • geojson_file_path – Text for the full path to the geojson file to load as GHEThermalLoop.

  • location – An optional ladybug location object with longitude and latitude data defining the origin of the geojson file. If None, an attempt will be made to sense the location from the project point in the GeoJSON (if it exists). If nothing is found, the origin is autocalcualted as the bottom-left corner of the bounding box of all building footprints in the geojson file. (Default: None).

  • point – A ladybug_geometry Point2D for where the location object exists within the space of a scene. The coordinates of this point are expected to be in the units input. If None, an attempt will be made to sense the CAD coordinates from the GeoJSON if they exist. If not found, they will default to (0, 0).

  • units

    Text for the units system in which the model geometry exists. Default: ‘Meters’. Choose from the following:

    • Meters

    • Millimeters

    • Feet

    • Inches

    • Centimeters

    Note that this method assumes the point coordinates are in the same units.

  • clockwise_flow – A boolean to note whether the direction of flow through the loop is clockwise (True) when viewed from above in the GeoJSON or it is counterclockwise (False). (Default: False).

junctions(tolerance=0.01)[source]

Get a list of ThermalJunction objects for the unique thermal loop junctions.

The resulting ThermalJunction objects will be associated with the loop’s GroundHeatExchanger if they are in contact with it (within the tolerance). However, they won’t have any building_identifier associated with them. The assign_junction_buildings method on this object can be used to associate the junctions with an array of Dragonfly Buildings.

Parameters

tolerance – The minimum difference between the coordinate values of two faces at which they can be considered centered adjacent. (Default: 0.01, suitable for objects in meters).

Returns

A tuple with two items.

  • junctions - A list of lists of the unique ThermalJunction objects that exist across the loop.

  • connector_junction_ids - A list of lists that align with the connectors in the loop. Each sub-list contains two string values for the junction IDs for each of the start and end of each of the connectors.

loop_polygon(buildings, tolerance=0.01)[source]

Get a Polygon2D for the single continuous loop formed by connectors.

This method will raise an exception if the ThermalConnectors do not form a single continuous loop through the Buildings and the ground_heat_exchangers. The Polygon2D will have the correct clockwise ordering according to this object’s clockwise_flow property.

Parameters
  • buildings – An array of Dragonfly Building objects in the same units system as the GHEThermalLoop geometry.

  • tolerance – The minimum difference between the coordinate values of two geometries at which they are considered co-located. (Default: 0.01, suitable for objects in meters).

move(moving_vec)[source]

Move this object along a vector.

Parameters

moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the object.

ordered_connectors(buildings, tolerance=0.01)[source]

Get the ThermalConnectors of this GHEThermalLoop correctly ordered in a loop.

The resulting connectors will not only be ordered correctly along the loop but the orientation of the connector geometries will be property coordinated with the clockwise_flow property on this object.

This method will raise an exception if the ThermalConnectors do not form a single continuous loop through the Buildings and the ground_heat_exchangers.

Parameters
  • buildings – An array of Dragonfly Building objects in the same units system as the GHEThermalLoop geometry.

  • tolerance – The minimum difference between the coordinate values of two geometries at which they are considered co-located. (Default: 0.01, suitable for objects in meters).

reflect(plane)[source]

Reflect this object across a plane.

Parameters

plane – A ladybug_geometry Plane across which the object will be reflected.

rotate_xy(angle, origin)[source]

Rotate this object counterclockwise in the XY plane by a certain angle.

Parameters
  • angle – An angle in degrees.

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)[source]

Scale this object by a factor from an origin point.

Parameters
  • factor – A number representing how much the object should be scaled.

  • origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

to_des_param_dict(buildings, tolerance=0.01)[source]

Get the DES System Parameter dictionary for the ThermalLoop.

Parameters
  • buildings – An array of Dragonfly Building objects that are along the GHEThermalLoop. Buildings that do not have their footprint touching the loop’s ThermalConnectors are automatically excluded in the result.

  • tolerance – The minimum difference between the coordinate values of two geometries at which they are considered co-located. (Default: 0.01, suitable for objects in meters).

to_dict()[source]

GHEThermalLoop dictionary representation.

to_geojson_dict(buildings, location, point=Point2D(0.0, 0.0), tolerance=0.01)[source]

Get GHEThermalLoop dictionary as it appears in an URBANopt geoJSON.

The resulting dictionary array can be directly appended to the “features” key of a base GeoJSON dict in order to represent the loop in the GeoJSON. Note that, in order to successfully simulate the DES, you will also have to write a system_parameter.json from this GHEThermalLoop using the to_des_param_dict method.

Parameters
  • buildings – An array of Dragonfly Building objects that are along the GHEThermalLoop. Buildings that do not have their footprint touching the loop’s ThermalConnectors are automatically excluded in the result.

  • location – A ladybug Location object possessing longitude and latitude data.

  • point – A ladybug_geometry Point2D for where the location object exists within the space of a scene. The coordinates of this point are expected to be in the units of this Model. (Default: (0, 0)).

  • tolerance – The minimum difference between the coordinate values of two geometries at which they are considered co-located. (Default: 0.01, suitable for objects in meters).

to_ghe_param_dict(tolerance=0.01)[source]

Get the GroundHeatExchanger as it appears in a System Parameter dictionary.

Parameters

tolerance – The minimum difference between the coordinate values of two geometries at which they are considered co-located. (Default: 0.01, suitable for objects in meters).

property borehole_parameters

Get or set a BoreholeParameter object for the heat exchanger field.

property clockwise_flow

Get or set a boolean for whether the flow through the loop is clockwise.

property connectors

Get or set the list of ThermalConnector objects within the loop.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property fluid_parameters

Get or set a FluidParameter object for the heat exchanger field.

property ground_heat_exchangers

Get or set a tuple of GroundHeatExchanger objects for the loop’s GHEs.

property identifier

Get or set the text string for unique object identifier.

property pipe_parameters

Get or set a PipeParameter object for the heat exchanger field.

property soil_parameters

Get or set a SoilParameter object for the heat exchanger field.