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, design_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. If None, default values will be used. (Default: None).

  • fluid_parameters – Optional FluidParameter object to specify the properties of the fluid that is circulating through the loop. If None, default values will be used. (Default: None).

  • pipe_parameters – Optional PipeParameter object to specify the properties of the ground-heat-exchanging pipes used across the loop. If None, default values will be used. (Default: None).

  • borehole_parameters – Optional BoreholeParameter object to specify the properties of the boreholes used across the loop. If None, default values will be used. (Default: None).

  • design_parameters – Optional GHEDesignParameter object to specify the design constraints across the loop. If None, default values will be used. (Default: None).

Properties:

  • identifier

  • display_name

  • ground_heat_exchangers

  • connectors

  • clockwise_flow

  • soil_parameters

  • fluid_parameters

  • pipe_parameters

  • borehole_parameters

  • design_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).

static ghe_designer_dict(thermal_load, site_geometry, soil_parameters=None, fluid_parameters=None, pipe_parameters=None, borehole_parameters=None, design_parameters=None, tolerance=0.01)[source]

Get a dictionary following the schema of the input JSON for GHEDesigner.

This includes many of the same parameters that are used to size ground heat exchangers in an URBANopt DES system but it requires the input of hourly thermal loads.

The dictionary returned by this method can be written to a JSON and passed directly to the GHEDesigner CLI in order to receive sizing information for the GHE and a G-function that can be used to meet the input load in a building energy simulation.

Parameters:

  • thermal_load – An annual data collection of hourly thermal loads on the ground in Watts. These are the heat extraction and heat rejection loads directly on the ground heat exchanger and should already account for factors like additional heat added or removed by the heat pump compressors. Positive values indicate heat extraction from the ground and negative values indicate heat rejection to the ground.

  • site_geometry – A list of horizontal Face3D representing the footprint of the site to be populated with boreholes. These Face3D can have holes in them and these holes will be excluded from borehole placement. Note that it is expected that this geometry’s dimensions are in meters and, if they are not, then it should be scaled before input to this method.

  • soil_parameters – Optional SoilParameter object to specify the properties of the soil in which the loop is operating. If None, default values will be used. (Default: None).

  • fluid_parameters – Optional FluidParameter object to specify the properties of the fluid that is circulating through the loop. If None, default values will be used. (Default: None).

  • pipe_parameters – Optional PipeParameter object to specify the properties of the ground-heat-exchanging pipes used across the loop. If None, default values will be used. (Default: None).

  • borehole_parameters – Optional BoreholeParameter object to specify the properties of the boreholes used across the loop. If None, default values will be used. (Default: None).

  • design_parameters – Optional GHEDesignParameter object to specify the design constraints across the loop. If None, default values will be used. (Default: None).

  • 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).

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.00, 0.00), 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 design_parameters

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

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.