Skip to content

API Reference

SystemClass

The distribution system abstraction class.

dss property

The instance of OpenDSSDirect.py.

dsscontent: List[str] writable property

The OpenDSS commands of the .dss file in path.

As well, you can change the list of commands.

Returns:

Type Description
List[str]

OpenDSS commands.

error: str property

Returns:

Type Description
str

The error of the last OpenDSS command.

kV: Iterable[float] property

Returns:

Type Description
Iterable[float]

The base voltages. See voltagebases in OpenDSS User Manual.

loadmult: float property

Returns:

Type Description
float

The load multiplier. See loadmult in OpenDSS User Manual..

name: str property

Returns:

Type Description
str

The name of the distribution system.

path: str property

Returns:

Type Description
str

The path of the .dss file.

__init__(*, path, kV, loadmult=1)

Parameters:

Name Type Description Default
path str

The path to the file that describes the distribution system.

 required
kV Iterable[float]

The base voltages. See voltagebases in OpenDSS User Manual.

 required
loadmult float

The load multiplier. See loadmult in OpenDSS User Manual.

 1

init_sys()

Run the commands in dsscontent.

run_command(cmd)

Run a comand on OpenDSS.

Parameters:

Name Type Description Default
cmd str

A OpenDSS command.

 required

Raises:

Type Description
Exception

If the command is invalid.

Returns:

Type Description
str

The OpenDSS command returns

decorators

actions(func)

See Creating your first action.

Parameters:

Name Type Description Default
func Callable

A action function

 required

tools(func)

See Creating your first tool.

Parameters:

Name Type Description Default
func Callable

A tool function

 required

Returns:

Type Description
Callable

The return of the tool function

pfmodes

cfg_tspf(distSys, step_size='1h', initial_time=(0, 0))

Set the time series mode in the distribution system.

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required
step_size str

The size of step time. See "Stepsize" in OpenDSS User Manual.

 '1h'
initial_time tuple

See "Time" in OpenDSS User Manual.

 (0, 0)

run_static_pf(distSys, actions=(lambda distSys: None), tools=(lambda distSys: None))

Run the static power flow mode. To see how it works, see Learning DSSData.

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required
actions Iterable[Callable]

Actions functions.

 (lambda distSys: None)
tools Iterable[Callable]

Tools functions.

 (lambda distSys: None)

Returns:

Type Description
tuple

Tools functions returns

run_tspf(distSys, num_steps, actions=(lambda distSys: None), tools=(lambda distSys: None))

Run the time series power flow. To see how it works, see Learning DSSData.

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required
num_steps

Number of time steps.

 required
actions Iterable[Callable]

Actions functions.

 (lambda distSys: None)
tools Iterable[Callable]

Tools functions.

 (lambda distSys: None)

Returns:

Type Description
Tuple[pandas.DataFrame]

Tools functions returns for all steps

reductions

regs

get_taps_changes(tapDataFrame)

Count the taps changes. That function is a reduction function.

E.g.: If a trafo starts in tap number 4 and goes to tap number -3. The result is 7.

(4 -> 3 -> 2 -> 1 -> 0 -> -1 -> -2 -> -3)

Parameters:

Name Type Description Default
tapDataFrame pandas.DataFrame

The return of get_all_taps_number or get_tap_number.

 required

Returns:

Type Description
pandas.DataFrame

The number of taps changes after time series power flow.

tools

lines

get_all_infos(distSys)

Get some relevant infos from all lines. See get_infos.

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required

Returns:

Type Description
pd.DataFrame

All lines infos

get_infos(distSys, names)

Get some relevant infos from lines. Ex:

name bus1 ph_bus1 bus2 ph_bus2 I(A)_bus1_ph_a I(A)_bus1_ph_b I(A)_bus1_ph_c I(A)_bus2_ph_a I(A)_bus2_ph_b I(A)_bus2_ph_c ang_bus1_ph_a ang_bus1_ph_b ang_bus1_ph_c ang_bus2_ph_a ang_bus2_ph_b ang_bus2_ph_c kw_losses kvar_losses emergAmps normAmps perc_NormAmps perc_EmergAmps
0 650632 rg60 abc 632 abc 562.609 419.029 591.793 562.61 419.03 591.794 -28.7 -141.3 93.4 151.3 38.7 -86.6 60.737 196.015 600.0 400.0 1.479 0.986
1 632670 632 abc 670 abc 481.916 218.055 480.313 481.916 218.055 480.313 -27.2 -135.2 99.6 152.8 44.8 -80.4 12.991 41.495 600.0 400.0 1.205 0.803
2 670671 670 abc 671 abc 473.795 188.824 424.942 473.795 188.824 424.942 -27.0 -132.6 101.3 153.0 47.4 -78.7 22.729 72.334 600.0 400.0 1.184 0.79

Parameters:

Name Type Description Default
distSys

An instance of SystemClass.

 required
names

Lines names.

 required

Returns:

Type Description
pd.DataFrame

Lines infos.

losses

get_all_line_losses(distSys)

Get all lines losses. Ex:

type name kw_losses kvar_losses
0 Line 650632 60.73738438443188 196.01456922721653
1 Line 632670 12.990633124585496 41.49451118066639
2 Line 670671 22.728758590972518 72.33414340631373
3 Line 671680 8.613828479544935e-12 -0.004169229516017848
4 Line 632633 0.8244871671261499 1.0561418323197722
5 Line 632645 2.75857850181032 2.4159107795492454
6 Line 645646 0.5274715389783668 0.41973513183818434
7 Line 692675 4.1629544212549225 2.419339661740261
8 Line 671684 0.5794876384501113 0.47068061342113654
9 Line 684611 0.3824044250881998 0.38734916932047053
10 Line 684652 0.7998267312559038 0.230879175578375
11 Line 671692 9.054614813067019e-06 4.3655745685100556e-14

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required

Returns:

Type Description
pd.DataFrame

A DataFrame containing all line losses.

get_all_pd_elements_losses(distSys)

Get all PD Elements losses. Ex:

type name kw_losses kvar_losses
0 Transformer sub 0.03228776756674051 0.26246840671868993
1 Transformer reg1 0.12209426402417012 0.12385869008488953
2 Transformer reg2 0.06534502545557916 0.06707698704162612
3 Transformer reg3 0.1350894299906213 0.13685391995031387
4 Transformer xfm1 5.552671994055243 10.09627035828575
5 Line 650632 60.73738438443188 196.01456922721653
6 Line 632670 12.990633124585496 41.49451118066639
7 Line 670671 22.728758590972518 72.33414340631373
8 Line 671680 8.613828479544935e-12 -0.004169229516017848
9 Line 632633 0.8244871671261499 1.0561418323197722
10 Line 632645 2.75857850181032 2.4159107795492454
11 Line 645646 0.5274715389783668 0.41973513183818434
12 Line 692675 4.1629544212549225 2.419339661740261
13 Line 671684 0.5794876384501113 0.47068061342113654
14 Line 684611 0.3824044250881998 0.38734916932047053
15 Line 684652 0.7998267312559038 0.230879175578375
16 Line 671692 9.054614813067019e-06 4.3655745685100556e-14

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required

Returns:

Type Description
pd.DataFrame

A DataFrame containing all PD Elements losses.

get_all_transformers_losses(distSys)

Get all transformers losses. Ex:

type name kw_losses kvar_losses
0 Transformer sub 0.03228776756674051 0.26246840671868993
1 Transformer reg1 0.12209426402417012 0.12385869008488953
2 Transformer reg2 0.06534502545557916 0.06707698704162612
3 Transformer reg3 0.1350894299906213 0.13685391995031387
4 Transformer xfm1 5.552671994055243 10.09627035828575

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required

Returns:

Type Description
pd.DataFrame

A DataFrame containing all transformers losses.

get_total_pd_elements_losses(distSys)

Get Total PD Elements losses. Ex:

name kw_losses_total kvar_losses_total
0 all_pd_elements 112.39948405966965 327.9256193105294

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required

Returns:

Type Description
pd.DataFrame

A DataFrame containing the sum of losses of all PD Elements.

pd_element_loss(distSys, element_name, element_type)

Get PD Element loss. Ex:

type name kw_losses kvar_losses
0 Transformer xfm1 5.552671994055243 10.09627035828575

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required
element_name str

The name of the desired PD element

 required
element_type str

The type of the PD element (Line or Transformer)

 required

Returns:

Type Description
pd.DataFrame

A DataFrame containing the losses of the desired PD element.

pd_element_loss_list(distSys, element_names, element_type)

Get PD Element loss List. Ex:

type name kw_losses kvar_losses
0 Transformer sub 0.03228776756674051 0.26246840671868993
1 Transformer reg1 0.12209426402417012 0.12385869008488953
2 Transformer reg2 0.06534502545557916 0.06707698704162612
3 Transformer reg3 0.1350894299906213 0.13685391995031387
4 Transformer xfm1 5.552671994055243 10.09627035828575

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass

 required
element_names list

A list of names of the desired PD elements

 required
element_type str

The type of the PD elements (Line or Transformer)

 required

Returns:

Type Description
pd.DataFrame

A DataFrame containing the losses of the desired list of PD elements.

regs

get_all_taps_number(distSys)

Get the tap number of all regulators.

Parameters:

Name Type Description Default
distSys SystemClass

An instance of SystemClass.

 required

Returns:

Type Description
pandas.DataFrame

The tap number of all regulators.

get_tap_number(distSys, names)

Get the tap number of regulators.

Parameters:

Name Type Description Default
distSys

An instance of SystemClass.

 required
names

Regulators names

 required

Returns:

Type Description
pandas.DataFrame

The tap number of regulators.

voltages

get_all(distSys)

Get line to neutral voltages (module and angle) in p.u. and phases configuration from buses. See get_from_buses.

Parameters:

Name Type Description Default
distSys

An instance of SystemClass.

 required

Returns:

Type Description
pandas.DataFrame

[type]: Line to neutral voltages (module and angle) in p.u. and phases configuration from buses.

get_from_buses(distSys, buses)

Get line to neutral voltages (module and angle) in p.u. and phases configuration from buses.

bus_name v_pu_a v_pu_b v_pu_c ang_a ang_b ang_c phases
0 sourcebus 0.99997 0.99999 0.99995 30.0 -90.0 150.0 abc
1 646 NaN 1.01803 1.00026 NaN -122.0 117.8 bc
2 611 NaN NaN 0.96083 NaN NaN 115.7 c
3 652 0.97533 NaN NaN -5.3 NaN NaN a

Parameters:

Name Type Description Default
distSys

An instance of SystemClass.

 required
buses

Buses names.

 required

Returns:

Type Description
pandas.DataFrame

[type]: Line to neutral voltages (module and angle) in p.u. and phases configuration from buses.