OpenDSS Reader#

The OpenDSS reader parses an OpenDSS master file (.dss) and all referenced include files into a GDM DistributionSystem. It uses OpenDSSDirect.py to drive the OpenDSS engine and extract component data.

Reader Interface#

class ditto.readers.opendss.reader.Reader(Opendss_master_file: Path, crs: str | None = None, use_split_phase_representation: bool = True)#

Bases: AbstractReader

Class interface for Opendss case file reader

get_system() → DistributionSystem#

Returns an instance of DistributionSystem

Returns:: Instance of DistributionSystem
Return type:: DistributionSystem

Component Parsers#

Each component type is handled by a dedicated module that queries the OpenDSS engine and maps the results to GDM objects.

class ditto.readers.opendss.components.branches.MatrixBranchTypes(value)#

ditto.readers.opendss.components.branches.get_branches(system: System, mapping: dict[str, str], geometry_branch_equipment_catalog: dict, matrix_branch_equipments_catalog: dict, thermal_limit_catalog: dict) → tuple[list[MatrixImpedanceBranch | GeometryBranch]]#

Method to build a model branches

Parameters:

system (System) – Instance of System
mapping (dict[str, int]) – mapping of line geometries names to GeometryBranchEquipment hash
geometry_branch_equipment_catalog (dict) – mapping of model hash to GeometryBranchEquipment instance
matrix_branch_equipments_catalog (dict) – mapping of model hash to MatrixImpedanceBranchEquipment instance
thermal_limit_catalog (dict) – mapping of model hash to ThermalLimitSet instance

Returns:

Returns a list of system branches

Return type:

tuple[list[MatrixImpedanceBranch | GeometryBranch]]

ditto.readers.opendss.components.branches.get_fuses() → list[str]#

Returns a list of lines with fuses

Returns:: List of lines with fuses
Return type:: list[str]

ditto.readers.opendss.components.branches.get_geometry_branch_equipments(system: System) → tuple[list[GeometryBranchEquipment], dict[str, int]]#

Helper function that return a list of GeometryBranchEquipment objects

Parameters:: system (System) – Instance of System
Returns:: list of GeometryBranchEquipment objects dict[str, int]: mapping of line geometries names to GeometryBranchEquipment hash
Return type:: list[GeometryBranchEquipment]

ditto.readers.opendss.components.branches.get_matrix_branch_equipments() → tuple[dict[int, MatrixImpedanceBranchEquipment], dict[int, ThermalLimitSet]]#

Function to return list of all MatrixImpedanceBranchEquipment in Opendss model.

Returns:: mapping of model hash to MatrixImpedanceBranchEquipment instance dict[int, ThermalLimitSet]: mapping of model hash to ThermalLimitSet instance
Return type:: dict[int, MatrixImpedanceBranchEquipment]

ditto.readers.opendss.components.branches.get_reclosers()#

Returns a list of lines with reclosers

Returns:: List of lines with reclosers
Return type:: list[str]

ditto.readers.opendss.components.branches.get_tcc_curves() → dict[str, TimeCurrentCurve]#

method returns a dict of tcc curve names mapped to TimeCurrentCurve objects

Returns:: mapped TimeCurrentCurve objects
Return type:: dict[str, TimeCurrentCurve]

ditto.readers.opendss.components.buses.get_buses(crs: str = None) → list[DistributionBus]#

Function to return list of all buses in Opendss model

Parameters:: crs (str, optional) – Coordinate reference system name. Defaults to None.
Returns:: list of DistributionBus objects
Return type:: list[DistributionBus]

ditto.readers.opendss.components.cables.get_cables_equipment() → list[ConcentricCableEquipment]#

Method returns a list of ConcentricCableEquipment objects

Returns:: list of ConcentricCableEquipment
Return type:: list[ConcentricCableEquipment]

ditto.readers.opendss.components.capacitors.get_capacitors(system: System) → list[DistributionCapacitor]#

Function to return list of all capacitors in Opendss model.

Parameters:: system (System) – Instance of System
Returns:: List of DistributionCapacitor objects
Return type:: List[DistributionCapacitor]

ditto.readers.opendss.components.conductors.get_conductors_equipment() → list[BareConductorEquipment]#

Method returns a list of BareConductorEquipment objects

Returns:: list of BareConductorEquipment
Return type:: list[BareConductorEquipment]

ditto.readers.opendss.components.loads.get_loads(system: System) → list[DistributionLoad]#

Function to return list of DistributionLoad in Opendss model.

Parameters:: system (System) – Instance of System
Returns:: List of DistributionLoad objects
Return type:: List[DistributionLoad]

ditto.readers.opendss.components.pv_systems.get_pvsystems(system: System) → list[DistributionSolar]#

Function to return list of DistributionSolar in Opendss model.

Parameters:: system (System) – Instance of System
Returns:: List of DistributionSolar objects
Return type:: List[DistributionSolar]

class ditto.readers.opendss.components.transformers.XfmrModelTypes(value)#

ditto.readers.opendss.components.transformers.get_transformer_equipments(system: System) → list[DistributionTransformerEquipment]#

Function to return list of all DistributionTransformerEquipment in Opendss model.

Parameters:: system (System) – Instance of infrasys System
Returns:: List of DistributionTransformerEquipment objects
Return type:: list[DistributionTransformerEquipment]

ditto.readers.opendss.components.transformers.get_transformers(system: System, distribution_transformer_equipment_catalog: dict[int, DistributionTransformerEquipment], winding_equipment_catalog: dict[int, WindingEquipment]) → list[DistributionTransformer]#

Method returns a list of DistributionTransformer objects

Parameters:

system (System) – Instance of System
distribution_transformer_equipment_catalog (dict[int, DistributionTransformerEquipment]) – mapping of model hash to DistributionTransformerEquipment instance
winding_equipment_catalog – mapping of model hash to WindingEquipment instance

Utility Functions#

ditto.readers.opendss.graph_utils.update_split_phase_nodes(graph: Graph, system: DistributionSystem) → DistributionSystem#

Return the system with corrected split phase representation

Parameters:

graph (Graph) – Graph representation of the dirtribution model
system (DistributionSystem) – Instance of an gdm DistributionSystem

Returns:

Updated system with fixed split phase representation

Return type:

DistributionSystem

class ditto.readers.opendss.common.LoadTypes(value)#: Load types represented in Ditto

ditto.readers.opendss.common.get_equipment_from_catalog(model: Component, catalog: dict[int, Component], sub_catalog: str | None = None) → Component | None#

If the equipment already exixts in th system the equipment instance is returned else None is returned

Parameters:

model (Component) – Instance of GDM equipment
catalog (dict[int, Component]) – mapping model hash to model
sub_catalog (str | None, optional) – sub catalog in a catalog. Defaults to None.

Returns:

Instance of GDM equipment

Return type:

Component | None

ditto.readers.opendss.common.get_source_bus(system: System) → str#

Returns the name of the source bus

Parameters:: system (System) – Instance of an Infrasys System

ditto.readers.opendss.common.get_unit_index(units_value) → int#

Extract an int from an opendssdirect Units() return value.

Older versions of opendssdirect (>=0.7) return a plain int while newer versions return an IntEnum with a .value attribute.

ditto.readers.opendss.common.hash_model(model: Component, key_names: list[str] = ['name', 'uuid']) → int#

Return hash of the passed model

Parameters:

model (Component) – Instance of a derived infrasys Component model
key_names (list[str], optional) – List of keys to be removed from the model. Defaults to [“name”, “uuid”].

Returns:

model hash

Return type:

int

ditto.readers.opendss.common.query_model_data(model_type: str, model_name: str, property: str, dtype: type) → Any#

query OpenDSS model property

Parameters:

model_type (str) – OpenDSS model type
model_name (str) – OpenDSS model name
property (str) – OpenDSS model property
dtype (type) – data type e.g. str, float

Returns:

OpenDSS model property value

Return type:

Any

ditto.readers.opendss.common.remove_keys_from_dict(model_dict: dict, key_names: list[str] = ['name', 'uuid']) → dict#

Method recursively removes keys from the model

Parameters:

model_dict (dict) – model in dict representation
key_names (list[str]) – keys to remove from the model

Returns:

reduced model dictionary

Return type:

dict