dragonfly_energy.des.ghe module

Ground Heat Exchanger (GHE) in a district thermal system.

class dragonfly_energy.des.ghe.BoreholeParameter(min_depth=60, max_depth=135, min_spacing=3, max_spacing=25, buried_depth=2, diameter=0.15)[source]

Bases: object

Represents the borehole properties within a ground heat exchanger field.

Parameters:

  • min_depth – A number for the minimum depth of the heat-exchanging part of the boreholes in meters. All boreholes will have a depth of at least this value. So this typically represents the depth at which borehole-drilling is most economical or the point at which it becomes more cost effective to start a new borehole instead of making a given borehole deeper. (Default: 60).

  • max_depth – A number for the maximum depth of the heat-exchanging part of the boreholes in meters. When the system demand cannot be met using boreholes with the min_depth, the boreholes will be extended until either the loads or met or they reach this depth. So this typically represents the depth of bedrock or the point at which drilling deeper ceases to be practical. (Default: 135).

  • min_spacing – A number for the minimum spacing between boreholes in meters. When the system demand cannot be met using boreholes with the max_spacing, the borehole spacing will be reduced until either the loads or met or they reach this spacing. So this typically represents the spacing at which each borehole will interfere with neighboring ones so much that it is not worthwhile to decrease the spacing further. (Default: 3).

  • max_spacing – A number for the maximum spacing between boreholes in meters. All boreholes will have a spacing of at most this value. So this typically represents the spacing at which the performance effects of one borehole on a neighboring one are negligible. (Default: 25).

  • buried_depth – A number for the depth below the ground surface at which the top of the heat exchanging part of the borehole sits in meters. (Default: 2).

  • diameter – A number for the diameter of the borehole in meters. (Default: 0.15).

Properties:

  • min_depth

  • max_depth

  • min_spacing

  • max_spacing

  • buried_depth

  • diameter

ToString()[source]

Overwrite .NET ToString method.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a BoreholeParameter object from a dictionary

Parameters:

data – A dictionary representation of an BoreholeParameter object in the format below.

{
'type': 'BoreholeParameter',
'min_depth': 30,  # float in meters
'max_depth': 90,  # float in meters
'min_spacing': 2.5,  # float in meters
'max_spacing': 8,  # float in meters
'buried_depth': 4,  # float in meters
'diameter': 0.2  # float in meters
}
to_dict()[source]

Get BoreholeParameter dictionary.

property buried_depth

Get or set a number for the depth of the top of the borehole in meters.

property diameter

Get or set a number for the diameter of the borehole in meters.

property max_depth

Get or set a number for the maximum depth of the borehole in meters.

property max_spacing

Get or set a number for the maximum spacing between boreholes in m.

property min_depth

Get or set a number for the minimum depth of the borehole in meters.

property min_spacing

Get or set a number for the minimum spacing between boreholes in m.

class dragonfly_energy.des.ghe.FluidParameter(fluid_type='Water', concentration=35, temperature=20)[source]

Bases: object

Represents the fluid properties within a ground heat exchanger field.

Parameters:

  • fluid_type –

    Text to indicate the type of fluid circulating through the ground heat exchanger loop. Choose from the options below. (Default: Water).

    • Water

    • EthylAlcohol

    • EthyleneGlycol

    • MethylAlcohol

    • PropyleneGlycol

  • concentration – A number between 0 and 60 for the concentration of the fluid_type in water in percent. Note that this variable has no effect when the fluid_type is Water. (Default: 35).

  • temperature – A number for the average design fluid temperature at peak conditions in Celsius. (Default: 20).

Properties:

  • fluid_type

  • concentration

  • temperature

ToString()[source]

Overwrite .NET ToString method.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a FluidParameter object from a dictionary

Parameters:

data – A dictionary representation of an FluidParameter object in the format below.

{
'type': 'FluidParameter',
'fluid_type': 'PropyleneGlycol',  # text for fluid_type
'concentration': 33,  # float for percentage concentration
'temperature': 22  # float in C
}
to_dict()[source]

Get FluidParameter dictionary.

FLUID_TYPES = ('Water', 'EthylAlcohol', 'EthyleneGlycol', 'MethylAlcohol', 'PropyleneGlycol')
property concentration

Get or set a number for the concentration of the fluid_type in water [%].

property fluid_type

Get or set text to indicate the type of fluid.

property temperature

Get or set a number for the average design fluid temperature in Celsius.

class dragonfly_energy.des.ghe.GHEDesignParameter(flow_rate=0.2, flow_type='Borehole', max_eft=35, min_eft=5, month_count=240)[source]

Bases: object

Represents criteria used to design a ground heat exchanger.

Parameters:

  • flow_rate – A number for the volumetric design flow rate through the ground heat exchanger in L/s. The value specified will be either for the entire system system or per-borehole flow rate depending on the flow_type set. (Default: 0.2 L/s).

  • flow_type –

    Text to indicate whether the design volumetric flow rate set on a per-borehole or system basis. Choose from the following options. (Default: Borehole).

    • Borehole

    • System

  • max_eft – A number for the maximum heat pump entering fluid temperature in Celsius. (Default: 35C).

  • min_eft – A number for the minimum heat pump entering fluid temperature in Celsius. (Default: 5C).

  • month_count – An integer for the number of months over which the simulation will be run in order to ensure stable ground temperature conditions. (Default: 240).

Properties:

  • flow_rate

  • flow_type

  • max_eft

  • min_eft

  • month_count

ToString()[source]

Overwrite .NET ToString method.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a GHEDesignParameter object from a dictionary

Parameters:

data – A dictionary representation of an GHEDesignParameter object in the format below.

{
'type': 'GHEDesignParameter',
'flow_rate': 30,  # float in L/s
'flow_type': 'Borehole',  # text for the type of object flow_rate references
'max_eft': 35,  # float for max entering fluid temperature in C
'min_eft': 5,  # float for min entering fluid temperature in C
'month_count': 240  # int for the number of months to run the simulation
}
to_dict()[source]

Get GHEDesignParameter dictionary.

FLOW_TYPES = ('Borehole', 'System')
property flow_rate

Get or set a number the volumetric design flow rate in L/s.

property flow_type

Get or set text for the type of object flow_rate references.

Choose from the following options:

  • Borehole

  • System

property max_eft

Get or set a number for the maximum entering fluid temperature in Celsius.

property min_eft

Get or set a number for the minimum entering fluid temperature in Celsius.

property month_count

Get or set a number for the maximum entering fluid temperature in Celsius.

class dragonfly_energy.des.ghe.GroundHeatExchanger(identifier, geometry)[source]

Bases: _GeometryBase

Represents a Ground Heat Exchanger in a district thermal system.

Parameters:

  • identifier – Text string for a unique heat exchanger 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.

  • geometry – A Polygon2D or horizontal Face3D representing the geometry of the heat exchanger.

Properties:

  • identifier

  • display_name

  • geometry

  • boundary_2d

  • holes_2d

ToString()
duplicate()

Get a copy of this object.

classmethod from_dict(data)[source]

Initialize a GroundHeatExchanger from a dictionary.

Parameters:

data – A dictionary representation of an GroundHeatExchanger object.

classmethod from_geojson_dict(data, origin_lon_lat, conversion_factors)[source]

Get a GroundHeatExchanger from a dictionary as it appears in a GeoJSON.

Parameters:

  • data – A GeoJSON dictionary representation of an GroundHeatExchanger feature.

  • origin_lon_lat – An array of two numbers in degrees. The first value represents the longitude of the scene origin in degrees (between -180 and +180). The second value represents latitude of the scene origin in degrees (between -90 and +90). Note that the “scene origin” is the (0, 0) coordinate in the 2D space of the input polygon.

  • conversion_factors – A tuple with two values used to translate between meters and longitude, latitude.

load_boreholes(borehole_file, units='Meters', ortho_rotation=False)[source]

Load borehole positions for this GHE from a borehole file made by GHEDesigner.

Parameters:

  • borehole_file – Full path to a BoreFieldData.csv produced by GHEDesigner from this GroundHeatExchanger object.

  • units – The units system in which the geometry of this GroundHeatExchanger object exists. This is used to convert between GHEDesigner’s native units of Meters over to the units system of this GroundHeatExchanger object. (Default: Meters).

  • ortho_rotation – A boolean to note whether this GroundHeatExchanger geometry was rotated to have it’s right-angles align with the coordinate system of GHEDesigner. This should be False when this GroundHeatExchanger’s geometry was directly translated to GHEDesigner and should be True if the geometry was converted to GeoJSON and then translated to a GeoJSON by the ThermalNetwork package. (Default: False).

Returns:

A list of Point2D for the position of each borehole in the ground heat exchanger. These points should all be contained within the geometry of this object.

static load_energyplus_properties(summary_file)[source]

Load E+ properties for this GHE from a summary file made by GHEDesigner.

Parameters:

summary_file – Full path to a SimulationSummary.json produced by GHEDesigner from this GroundHeatExchanger object.

Returns:

A list of properties of the ground heat exchanger that are needed to simulate it in EnergyPlus. These values output here correspond to the PROPERTY_NAMES on this object.

static load_g_function(g_func_file)[source]

Load the G-Function for this GHE from a G function file made by GHEDesigner.

Parameters:

g_func_file – Full path to a Gfunction.csv produced by GHEDesigner from this GroundHeatExchanger object.

Returns:

A list of lists of G-function coefficients that describe the response of the ground to the input loads. Each pair of factors represents a point on the G-function. Flattening this list of lists yields properties that can be plugged into the EnergyPlus G-function object.

static load_monthly_temperatures(summary_file)[source]

Load ground temperatures for this GHE from a summary file made by GHEDesigner.

Parameters:

summary_file – Full path to a SimulationSummary.json produced by GHEDesigner from this GroundHeatExchanger object.

Returns:

A list of ground temperatures in Celsius with one value for each month of the period over which the GHEDesigner simulation was run (typically 20 years). This can be used to check the drift in the ground temperature over long periods of time.

move(moving_vec)

Move this object along a vector.

Parameters:

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

reflect(plane)

Reflect this object across a plane.

Parameters:

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

rotate_xy(angle, origin)

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)

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_dict()[source]

GroundHeatExchanger dictionary representation.

to_geojson_dict(origin_lon_lat, conversion_factors)[source]

Get GroundHeatExchanger dictionary as it appears in an URBANopt geoJSON.

Parameters:

  • origin_lon_lat – An array of two numbers in degrees. The first value represents the longitude of the scene origin in degrees (between -180 and +180). The second value represents latitude of the scene origin in degrees (between -90 and +90). Note that the “scene origin” is the (0, 0) coordinate in the 2D space of the input polygon.

  • conversion_factors – A tuple with two values used to translate between meters and longitude, latitude.

PROPERTY_NAMES = ('Borehole Length (m)', 'Borehole Radius (m)', 'Design Flow Rate (m3/s)', 'Ground Temperature (C)', 'Ground Conductivity (W/m-K)', 'Ground Heat Capacity (J/m3-K)', 'Grout Conductivity (W/m-K)', 'Number of Boreholes', 'Pipe Outer Diameter (m)', 'Pipe Conductivity (W/m-K)', 'Pipe Thickness (m)', 'U Tube Distance (m)')
PROPERTY_PATHS = (('ghe_system', 'active_borehole_length', 'value'), ('ghe_system', 'borehole_diameter', 'value'), ('ghe_system', 'fluid_mass_flow_rate_per_borehole', 'value'), ('ghe_system', 'soil_undisturbed_ground_temp', 'value'), ('ghe_system', 'soil_thermal_conductivity', 'value'), ('ghe_system', 'soil_volumetric_heat_capacity', 'value'), ('ghe_system', 'grout_thermal_conductivity', 'value'), ('ghe_system', 'total_drilling', 'value'), ('ghe_system', 'pipe_geometry', 'pipe_outer_diameter', 'value'), ('ghe_system', 'pipe_thermal_conductivity', 'value'), ('ghe_system', 'pipe_geometry', 'pipe_inner_diameter', 'value'), ('ghe_system', 'shank_spacing', 'value'))
property boundary_2d

Get a Polygon2D for the outer boundary of the ground heat exchanger.

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 geometry

Get a Polygon2D or Face3D representing the ground heat exchanger.

property hole_polygon2d

Get a list of Polygon2D for the holes in the ground heat exchanger.

Will be None if the ground heat exchanger has no holes in it.

property identifier

Get or set the text string for unique object identifier.

class dragonfly_energy.des.ghe.PipeParameter(inner_diameter=0.0216, outer_diameter=0.0266, shank_spacing=0.0323, roughness=1e-06, conductivity=0.4, heat_capacity=1542000, arrangement='SingleUTube')[source]

Bases: object

Represents the pipe properties within a ground heat exchanger field.

Parameters:

  • inner_diameter – A number for the diameter of the inner pipe surface in meters. (Default: 0.0216).

  • outer_diameter – A number for the diameter of the outer pipe surface in meters. (Default: 0.0266).

  • shank_spacing – A number for the spacing between the U-tube legs, as referenced from outer surface of the pipes in meters. (NOT referenced from each pipe’s respective centerline). (Default: 0.0323).

  • roughness – A number for the linear dimension of bumps on the pipe surface in meters. (Default: 1e-06)

  • conductivity – A number for the conductivity of the pipe material in W/m-K. (Default: 0.4).

  • heat_capacity – A number for the volumetric heat capacity of the pipe material in J/m3-K. (Default: 1,542,000).

  • arrangement –

    Text for the specified pipe arrangement. Choose from the following options. (Default: SingleUTube).

    • SingleUTube

    • DoubleUTubeSeries

    • DoubleUTubeParallel

Properties:

  • inner_diameter

  • outer_diameter

  • shank_spacing

  • roughness

  • conductivity

  • heat_capacity

  • arrangement

ToString()[source]

Overwrite .NET ToString method.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a PipeParameter object from a dictionary

Parameters:

data – A dictionary representation of an PipeParameter object in the format below.

{
'type': 'PipeParameter',
'inner_diameter': 0.0216,  # float for inner diameter in meters
'outer_diameter': 0.0266  # float for outer diameter in meters
'shank_spacing': 0.0323,  # float for spacing between outer pipes in meters
'roughness': 1e-06,  # float for the dimension of the surface bumps
'conductivity': 0.6,  # float in W/m2-K
'heat_capacity': 1542000,  # float in J/m3-K
'arrangement': 'SingleUTube'  # text for arrangement type
}
to_dict()[source]

Get PipeParameter dictionary.

ARRANGEMENT_TYPES = ('SingleUTube', 'DoubleUTubeSeries', 'DoubleUTubeParallel')
property arrangement

Get or set text for the pipe arrangement.

Choose from the following options:

  • SingleUTube

  • DoubleUTubeSeries

  • DoubleUTubeParallel

property conductivity

Get or set a number for the conductivity of the pipe material in W/m-K.

property heat_capacity

Get or set a number for the volumetric heat capacity of the pipe in J/m3-K.

property inner_diameter

Get or set a number for the inner diameter of the pipe in meters.

property outer_diameter

Get or set a number for the outer diameter of the pipe in meters.

property roughness

Get or set a number for the dimension of the pipe surface bumps in meters.

property shank_spacing

Get or set a number for the shank spacing between the pipes in meters.

class dragonfly_energy.des.ghe.SoilParameter(conductivity=2.3, heat_capacity=2343500, undisturbed_temperature=Autocalculate, grout_conductivity=1.0, grout_heat_capacity=3901000)[source]

Bases: object

Represents the soil properties within a ground heat exchanger field.

Parameters:

  • conductivity – A number for the soil conductivity in W/m-K. (Default: 2.3).

  • heat_capacity – A number for the volumetric heat capacity of the soil in J/m3-K. (Default: 2,343,500).

  • undisturbed_temperature – A number for the undisturbed annual average soil temperature in degrees Celsius. If autocalculate, this value will automatically be replaced with the average EPW temperature before simulation. (Default: Autocalculate).

  • grout_conductivity – A number for the grout conductivity in W/m-K. (Default: 1.0).

  • grout_heat_capacity – A number for the volumetric heat capacity of the grout in J/m3-K. (Default: 3,901,000).

Properties:

  • conductivity

  • heat_capacity

  • undisturbed_temperature

  • grout_conductivity

  • grout_heat_capacity

ToString()[source]

Overwrite .NET ToString method.

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create a SoilParameter object from a dictionary

Parameters:

data – A dictionary representation of an SoilParameter object in the format below.

{
'type': 'SoilParameter',
'conductivity': 1.8,  # float in W/m2-K
'heat_capacity': 2100000,  # float in J/m3-K
'undisturbed_temperature': 18,  # float in C or autocalculate
'grout_conductivity': 1.0,  # float in W/m2-K
'grout_heat_capacity': 3901000
}
to_dict()[source]

Get SoilParameter dictionary.

property conductivity

Get or set a number for the soil conductivity in W/m-K.

property grout_conductivity

Get or set a number for the grout conductivity in W/m-K.

property grout_heat_capacity

Get or set a number for the volumetric heat capacity of the grout in J/m3-K.

property heat_capacity

Get or set a number for the volumetric heat capacity of the soil in J/m3-K.

property undisturbed_temperature

Get or set an integer (or Autocalculate) for the vegetation end month.