dragonfly_energy.opendss.network module

Electrical network in OpenDSS.

class dragonfly_energy.opendss.network.ElectricalNetwork(identifier, substation, transformers, connectors)

Bases: object

Represents an electrical network in OpenDSS.

This includes a substation, transformers, and all electrical connectors needed to connect these objects to Dragonfly Buildings.

Parameters:

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

• substation – A Substation object representing the electrical substation supplying the network with electricity.

• transformers – An array of Transformer objects that are included within the electrical network. Generally, there should always be a transformer somewhere between the substation and a given building.

• connectors – An array of ElectricalConnector objects that are included within the electrical network. In order for a given connector to be valid within the network, each end of the connector must touch either another connector or a building footprint/transformer/substation. In order for the network as a whole to be valid, all Buildings and Transformers must be connected back to the Substation via connectors.

Properties:

• identifier

• display_name

• substation

• transformers

• connectors

• transformer_properties

• power_lines

• wires

ToString()

static assign_junction_buildings(junctions, buildings, tolerance=0.01)

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 ElectricalJunction objects to be associated with Dragonfly Buildings.

• buildings – An array of Dragonfly Building objects in the same units system as the ElectricalNetwork 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')

Convert all of the geometry in this ElectricalNetwork 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 network. (Default: Meters).

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Initialize an ElectricalNetwork from a dictionary.

Parameters:

data – A dictionary representation of an ElectricalNetwork object.

classmethod from_rnm_geojson(geojson_file_path, location=None, point=None, units='Meters')

Get an ElectricalNetwork from a dictionary as it appears in an RNM GeoJSON.

Parameters:

• geojson_file_path – Text for the full path to the geojson file to load as a ElectricalNetwork.

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

junctions(tolerance=0.01)

Get a list of ElectricalJunction objects for the unique network junctions.

The resulting ElectricalJunction objects will be associated with Transformers and Substations that they are in contact with across the network (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 ElectricalJunction objects that exist across the network.

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

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()

ElectricalNetwork dictionary representation.

to_electrical_database_dict()

Get ElectricalNetwork as it should appear in the electrical_database.json.

to_geojson_dict(buildings, location, point=Point2D(0.00, 0.00), tolerance=0.01)

Get ElectricalNetwork 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 network in the geoJSON. Note that, in order to successfully run OpenDSS, you will also have to write an electrical_database.json from this ElectricalNetwork using the to_electrical_database_dict method.

Parameters:

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

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

property connectors

Get or set the list of ElectricalConnector objects within the network.

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 identifier

Get or set the text string for unique object identifier.

property power_lines

A list of all unique PowerLines in the network.

property substation

Get or set a Substation object for the network’s substation.

property transformer_properties

A list of all unique TransformerProperties in the network.

property transformers

Get or set the list of Transformer objects within the network.

property wires

A list of all unique Wires in the network.

class dragonfly_energy.opendss.network.RoadNetwork(identifier, substation, roads)

Bases: object

Represents a road network for RNM input.

This includes a substation and roads that will be used to lay out the road network.

Parameters:

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

• substation – A Substation object representing the road substation supplying the network with electricity.

• roads – An array of Road objects that are included within the road network.

Properties:

• identifier

• display_name

• substation

• roads

ToString()

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Initialize an RoadNetwork from a dictionary.

Parameters:

data – A dictionary representation of an RoadNetwork object.

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()

RoadNetwork dictionary representation.

to_geojson_dict(location, point=Point2D(0.00, 0.00))

Get RoadNetwork 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 network in the geoJSON.

Parameters:

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

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 identifier

Get or set the text string for unique object identifier.

property roads

Get or set the list of Road objects within the network.

property substation

Get or set a Substation object for the network’s substation.