Krangpower depends on a series of data/configuration files, contained in the
/defaults folder, in order to offer its functionality.
These files should only be touched if you know what you’re doing, and modifying them improperly could result in unpredictable and wrong behavior.
As of v0.2.2, these files are not yet complete. In order to contribute to the perfectioning of these files, a detailed knowledge of OpenDSS and meticulous study of its documentation is required. Completing these configuration files is not the current #1 priority, but it will be in the future, when all the important functionality is completely ironed out, and certainly before any development-state changing release.
In the meantime, any help on completing (and double-checking!!) these files is appreciated!
In order to aid the knowledgeable user to comprehend what these files do exactly, here follows a brief explanation of each one.
This csv file contains rows of four elements and its purpose is to decide what happens when the association operator
* is used to associate one element to the other. For example, the line:
means that when one multiplies a
Line by a
Linegeometry, the underlying opendss property “geometry” of the Line will be
filled with the Linegeometry’s property “name”.
In other words, association_types.csv is the file that manages the
* associations behavior.
This file is nevralgic to
krangpower component management. It somewhat resembles the lists of components found in
the JSON i/o files. This file defines a “default_<obj>” for each <obj> supported. Inside it, the following dicts can be
It’s simply the type of the element. It’s there just for practical reasons.
They are the default values for the properties, keyed by name.
Implicitly, they define what is the correct data type for that parameter:
The keys of this dict are a subset of properties’. It contains the measurement unit for the properties internally used by OpenDSS, to which values have to be converted when generating opendss code and when receiving pint quantities as user input. The measurement units are specified as pint-parsable strings. For matrices with non-homogeneous measurement units, units in a list can be specified (e.g., linegeometry’s x and h)
It works in the same way as properties, but it contains those ones that reflect the association of another object, rather than an intrinsic property (e.g., “geometry” for a Line)
It works in the same way as properties, but it contains those ones that reflect the topological collocation of the object, rather than an intrinsic property (e.g., “bus1” and “bus2” for a Line)
This file is somewhat similar to default_dssentities.json. It’s used in
get(). It contains two dicts and a list:
The default value for every opendss option is specified, and, implicitly, its data type.
The keys of this dictionary are a subset of values’ ones. For the properties listed, the measurement unit for the properties internally used by OpenDSS is indicated
A list of those settings that do not influence the identity and physical characterization of a circuit, but are just computational auxiliary parameters, not to be saved in output files.
It’s used when creating PackedOpendssElement.
For each object type supported by
krangpower.enhancer, it lists in “interfaces” what are the interfaces in which methods for that kind of
object can be found, and in selectors what are the functions to be used to select that object in order to retrieve the correct
data from the interfaces.
It lists what are the available methods of each submodule of
OpenDSSDirect.py. It’s used in the automatic population
krangpower.enhancer that is performed on load.
This file is complete.
It lists what are the OpenDSS calls that are unsafe to make when a circuit is not yet solved. These calls have an extremely high risk of retrieving non-physical results or, worse, cause a segmentation fault. Calls listed here are met with an UnsafeCallError raise instead of being performed when the circuit is unsolved; or, if the “force_unsafe_calls” setting is set to True, a WARNING is issued and the call is performed anyways.
This file is complete.
This file contains, for each
OpenDSSDirect.py function, what are the units the returned value has, if any. This
information is used when
krangpower.enhancer wraps a call to
OpenDSSDirect.py in order to enhance the data
This file contains, for each
OpenDSSDirect.py function, what chain of functions
to apply to the returned value, if any, in order to enhance the data retrieved. An explanation on what each of the functions
specified does can be found directly in
This file contains those substrings that characterise messages of error coming from the OpenDSS text interface. Since
in these cases OpenDSS does not raise any exception on its own, it’s necessary to check the returned strings to see if
they signal an error so that
krangpower.enhancer can raise an
OpenDSSTextError, thus avoiding dangerous
and difficult-to-debug silent errors.
If you know of error strings returned by the text interface that are not caught in the cases listed in the file, please drop a couple of lines to the developers!
error_strings.json contains two lists:
- beginning is the list of substrings that are found at the beginning of the error message;
- middle is the list of substrings that are found somewhere in the middle of the error message.
In vanilla OpenDSS, some element definitions allow you to specify in what units you are going to provide the numerical data (e.g., Lines). Since in krangpower, physical quantities are provided to the element constructors complete with a pint measurement unit, this specification becomes superfluous. This file contains the unit declarations chosen by krangpower for its internal workings; and krangpower then converts what the user provides to these units when generating an OpenDSS instruction.
This file contains regular expressions that krangpower tries to match to any command sent through
If the command matches any of these regular expressions, the cached
Krang.graph() (whose calculation can be very expensive)
In other words, this file contains regular expressions that identify those commands that have no influence on the graph and should not trigger its re-calculation.
Just a splash screen with the logo.