Krangpower¶
Krangpower is a Python package for electrical network simulations based on OpenDSS by EPRI and a Python api for its direct library incarnation, OpenDSSDirect.py, by Dheepak Krishnamurthy.
Design goals¶
- Providing an even easier and more intuitive frontend;
- Introducing measurement units through the package pint, allowing the user to worry less about errors, to demand the burden of conversion and to correctly interpret the results without recurring to the OpenDSS docs;
- Returning results in interoperable data structures and containers;
- Enabling advanced analysis modes, for example:
- Exporting the network topology in a networkx graph
- Solving duty cycles that involve smart components that need to update themselves after every n steps
- Providing a I/O facility based on json files, allowing easier bookkeping and search and procedural generation of circuits with custom tools
Installation¶
Run as appropriate for your system:
pip install krangpower
pip3 install krangpower
Important
Krangpower is a python 3.x package; currently, compatibility with python 2.x is not sought after.
Alternatively, if you wish to contribute to the codebase too, you can clone and use the Github repo. As of june 2018, krangpower is in intense development and the Github repo is typically a few days/weeks ahead of the pypi index.
Contents¶
Usage¶
The central class of the krangpower package is the eponymous Krang
. It is designed to provide easy and intuitive interaction. Let’s see the basics of Krang
usage with a small walkthrough.
1 2 3 4 | >>> import krangpower as kp
>>> um = kp.UM
>>> src = kp.Vsource(basekv=15000*um.V)
>>> myKrang = kp.Krang('mighty_krang', src)
|
- @2 Krangpower uses the physical quantity management package pint, so the first thing we did here is to bring in the local namespace krangpower’s
UnitRegistry
: the constantUM
. Think of it as an object whose attributes are the measurement units. - @3 Every circuit has to be initialized with a slack voltage source, so
Krang
will need one. In krangpower, voltage sources are represented byVsource
. You can initializeVsource
, or any other electrical entity, with a set of keyword arguments to override the default values. We will call them “parameters”. Here we edited just the parameter ‘basekv’ to a value of 15000 Volts. More on parameters later. - @4 Here we instantiate a
Krang
with a name string and ourVsource
. Both parameters are optional; if not provided, they will default to'Unnamed_Krang'
andkp.Vsource()
. We can now start to add stuff tomyKrang
.
5 6 7 8 9 10 11 12 13 | >>> lc = kp.LineCode_S('lcs1', r0=1*um.ohm/um.km)
>>> myKrang << lc
>>> myKrang['sourcebus', 'alpha']
<BusView('sourcebus', 'alpha')>
>>> myKrang['sourcebus', 'alpha'] << kp.Line(length=45*um.ft).aka('line1') * lc
>>> myKrang['line1']
<PackedOpendssElement: line1>
>>> myKrang['line1']['r0']
<Quantity(0.001, 'ohm / meter')>
|
More irons in the fire.
- @5 We instantiate a
LineCode_S
. The syntax is the same as theVsource
, except that we must specify a name as first parameter. Because they’re not made of iron & copper but of information, LineCodes have a name of their own and do not have to be aliased every time they’re used (see line 9). - @6 Linecodes are meant to be associated to Lines. To make use of
lc
, we first have to informmyKrang
of its existence. A Linecode is not bound to a bus or couple of buses; so we add it directly. In krangpower, the operator that adds a component to aKrang
is left shift,<<
.
Note
Since version 0.2.1, it’s optional to explicitly declare abstract entities before declaring objects to which they are associated. Krangpower automatically declares associated entities that were not previously declared.
@7 This line demonstrates bracket indexing Krang with a tuple. The object returned is a
BusView
. You can add object that require topological collocation toBusView
, in the same way ofKrang
themselves.- @9 This line has a lot going on.
- We are instantiating a
Line
specifying its length in feet - we can use any length unit, krangpower will take care of the conversion. In order to be added to the circuit, the line has to be aliased with the methodaka
; in this way, it will have a name inside the circuit. - The line is then associated with
lc
, so it will make use of it in defining its impedance; the association operator is multiplication,*
. - The line is added to the
BusView
we saw at point 7.
- We are instantiating a
Note: The default name of the output bus of the circuit’s slack
Vsource
is ‘sourcebus’. You can customize it by passing it as a third parameter toKrang
constructor.@10 Now that ‘line1’ is inserted into
myKrang
, we can retrieve it by bracket indexing Krang with a string with its name. The object retrieved is a PackedOpendssElement.@12 Suffice to say, for now, that we can retrieve a PackedOpendssElement’s parameters with bracket indexing; here we print its
r0
. As expected, it’s a pintQuantity
, and it’s coincident withlc
14 15 16 17 18 | >>> myKrang['alpha']
<PackedOpendssElement: alpha>
>>> myKrang['alpha',]
<BusView('alpha',)>
>>> myKrang['alpha',] << kp.load(kv=15*um.kV, kW=130*um.kW)
|
- @14,@16 Demonstrate again, in the tricky case of buses, bracket indicization with strings and tuples. In the first case, as expected, we get the bus ‘alpha’ as a
PackedOpendssElement
; in the second case, we get aBusView
of the single bus ‘alpha’. - @18 We can add components bound to a single bus to the
BusView
; in this case, for example, we add aLoad
, instantiated with the usual keyword arguments passed to the constructor.
Krang reference¶
The Krang
is the main class of krangpower. It has facilities to drive the OpenDSS engine, retrieve and query
elements and options, saving and loading circuit data as JSON, representing the circuit as graph, perform repeated
solutions and reporting the results as DataFrames
. The basic workflow pertaining the Krang
is illustrated
in the Usage page.
It’s worth spending a word about the attribute Krang.brain
. It points to the krang.enhancer
submodule and is designed
to expose the exact same interface as the module OpenDSSDirect.py. This means that you can use Krang.brain
exactly as you would use this module, with two advantages:
- Results are returned in enhanced data containers as suitable, rather than as raw strings (integers will be of type
int
, arrays will be of typenumpy.ndarray
, pyhysical quantities will have a pint unit measure); - It’s bracket-indicizable with a string and returns a
PackedOpendssElement
.
More info on krang.enhancer
is available at the krang.enhancer reference page.
Important
Krang
is a singleton, meaning that you cannot have more than one instance around at any given time - an Exception will be raised when trying to instantiate more than one.
This is because OpenDSS supports only one circuit at any given time. If, in the future, the capability to have more than one circuit will be built in Opendss, this limitation will be removed.
Note
Krang
can be deleted with the del
keyword. After doing it, it will be possible (in principle) to instantiate a new one; beware, though, that if you made strong references to it
(for example, assigning it to variables, to lists, to object attributes) the new instantiation will fail even after the del
command. In other words, a new instantiation will be possible after you del the last
strong reference that was made to the Krang.
Class reference¶
-
class
krangpower.
Krang
(name='Unnamed_Krang', voltage_source=<krangpower.Vsource()(@0x7f55fa3cf890)>, source_bus_name='sourcebus', working_frequency=50.0, redirect_path=False, override_log=False)¶ The krang is an object capable of creating, editing, solving and retrieving information about an electrical distribution system.
-
Ybus_noload
()¶ Returns the Ybus matrix of the existing circuit with all loads, generators set to 0 kW and 0 kVAr. The Ybus computed in such a way can be used to compute the load/generator injection currents as Ybus_noload * V, where V is the node voltage vector computed in any other condition of load. The matrix is returned in Compressed Sparse Column representation.
-
__getattr__
(item)¶ Krang.item, aside from retrieving the builtin attributes, wraps by default the calls to opendssdirect’s ‘class_to_dataframe’ utility function. These are accessible via capital letter calls. Both singular and plural are accepted. (e.g., ‘Line’ or ‘Lines’, ‘RegControl’ , ‘Regcontrol’, ‘RegControls’, but not ‘transformers’)
-
__getitem__
(item)¶ Krang[‘bus.nname’], Krang[‘load.load1’], Krang[‘load1’] gets the component or a list of components of the bus; Krang[(‘bus.nname’,)], Krang[‘bus.b1’,’bus.b2’] gets a BusView to which you can add components with <<. Note that in order to get a BusView of a single bus, one needs to explicitly pack it in a tuple.
-
__init__
(name='Unnamed_Krang', voltage_source=<krangpower.Vsource()(@0x7f55fa3cf890)>, source_bus_name='sourcebus', working_frequency=50.0, redirect_path=False, override_log=False)¶ Initialize self. See help(type(self)) for accurate signature.
-
__lshift__
(other)¶ The left-shift operator << adds components to the Krang. Components that can and have to be directly added to the krang are those that represent data (WireData, TSData, LineGeometry…) or those that are in the circuit but above the topology (such as Monitors and all the Controllers). The names of these elements must not be blank when they are added.
-
static
__new__
(cls, *args, **kwargs)¶ Create and return a new object. See help(type) for accurate signature.
-
brain
= None¶ Krang.brain points to krangpower.enhancer It has the same interface as OpenDSSDirect.py, but can pack objects and returns enhanced data structures such as pint qtys and numpy arrays.
-
bus_coords
()¶ Returns a dict with the bus coordinates already loaded in Opendss. Beware that coordinates loaded through a link_kml or link_csv are not immediately loaded in the Opendss, but they are just before a solution is launched.
-
com
¶ Krang.com is a list of all the commands sent to the text interface throughout the Krang’s lifespan.
-
command
(cmd_str: str, echo=True)¶ Performs an opendss textual command and adds the commands to the record Krang.com if echo is True.
-
custom_drag_solve
(*qties, as_dict=False)¶ This command solves one step at a time and returns a list of values (of length equal to the number of steps solved) for each of the quantities indicated, as strings, in the arguments. For example:
pwr, lss = myKrang.custom_drag_solve(‘myKrang[“agent_1”].Powers()’, ‘myKrang.brain.Circuit.Losses()’)
(returns two lists with the values assumed by the expressions passed after each solution steps).
DEPRECATED IN FAVOR OF Krang.evalsolve
-
drag_solve
()¶ This command solves one step at a time and saves node currents and voltages in the two DataFrames returned.
-
evalsolve
(*fns, every_steps=1, always_rebuild_Y=False, as_df=True, detect_multindex=True)¶ Solves the circuit for the set number of steps, evaluating the function passed at each step and returning the results. Accepts as arguments a series of functions that take a Krang object as input. Returns a dictionary or a DF; each item/column contains the returned values of the corresponding function passed, indicized by simulation time.
Parameters: - fns – the functions to evaluate, passed as sequence of *args. The functions have to accept one positional argument of type Krang, as they will be passed this instance.
- every_steps – Every how many steps to perform the evaluation. Default = 1.
- always_rebuild_Y – Whether to impart the ‘BuildY’ command before solving.
- as_df – Whether to return the results in a dict or in a pandas.DataFrame
- detect_multindex – (NOT YET IMPLEMENTED) if set to True, and so is as_df, evalsolve checks if all the individual results returned by the functions are dicts with the same keys. If so, those keys are used as a multi-index for the DataFrame.
-
export
(object_descriptor)¶ Wraps the OpenDSS export command. Returns a DataFrame for csv exports, an ElementTree for xml exports. This method has a help attribute that prints to console the available options.
-
fingerprint
()¶ Returns the md5 hash digest for Krang.make_json_dict() in canonical form. Its main use is to compare two circuits in order to confirm that they are equivalent.
-
classmethod
from_dss
(file_path, target_krang=None, frequency=50.0)¶ from_dss(file_path, target_krang, frequency) allows to create a krang from an existing dss script or to pass commands to a krang from an existing dss script. USE AT YOUR OWN RISK.
Parameters: - file_path – The path of the dss file to utilize
- target_krang –
- If None, a new krang will be created and initialized with the information from the file (must contain a ‘new circuit’ command).
- If a Krang is passed, the commands in the script will be passed to that Krang.
- frequency – the general frequency to use for the krang, if a new one is created.
-
classmethod
from_json
(path, override_log=False)¶ Loads circuit data from a json structured like the ones returned by Krang.save_json. Declaration precedence due to dependency between objects is automatically taken care of.
-
get
(*opts)¶ Takes a list of circuit options and returns them as dict of name, value.
-
static
get_unit_registry
()¶ Retrieves krangpower’s UnitRegistry.
-
graph
()¶ Krang.graph is a Networkx.Graph that contains a description of the circuit. The elements are stored as _PackedOpendssElement’s in the edge/node property ‘el’. More information about how to make use of the graph can be found in the dedicated page.
-
id
= None¶ Krang.id is a string identifier for the krang that is used in the logs.
-
link_coords
(csv_path)¶ Notifies Krang of a csv file with bus coordinates to use.
-
make_json_dict
()¶ Returns a complete description of the circuit and its objects as a json.dumpable-dict.
-
name
¶ The name of the circuit..
-
classmethod
open_ckt
(path, strict=True)¶ Loads a ckt package saved through Krang.pack_ckt() and returns a Krang.
-
pack_ckt
(path=None)¶ Packs a ckt archive with all the information needed to reproduce the Krang. If a valid path string is passed, a file will be created, and None will be returned; if None is passed as path, a Binary buffered I/O (io.BytesIO) with the exact same information as the file will be returned instead.
-
plot
(object_descriptor)¶ Wraps the OpenDSS plot command. This method has a help attribute that prints to console the available options.
-
save_dss
(path=None)¶ Saves a file with the text commands that were imparted by the Krang.command method aside from those for which echo was False. The file output should be loadable and runnable in traditional OpenDSS with no modifications.
-
save_json
(path=None, indent=2)¶ Saves a complete JSON description of the circuit and its objects. If a valid path string is passed, a file will be created, and None will be returned; if None is passed as path, a Text buffered Stream (io.StringIO) with the exact same information as the file will be returned instead.
-
set
(**opts_vals)¶ Sets circuit options according to a dict. Option that have a physical dimensionality (such as stepsize) can be specified as pint quantities; otherwise, the default opendss units will be used.
-
show
(object_descriptor)¶ Wraps the OpenDSS show command. This method has a help attribute that prints to console the available options.
-
snap
()¶ Solves a circuit snapshot.
-
solve
(echo=True)¶ Imparts the solve command to OpenDSS.
-
BusView reference¶
BusView
are returned by bracket-indicizing a Krang
with a tuple containing the id of the desired buses.
The main functionality of BusView
is to enable the possibility of adding to a Krang
circuit components tied to a
particular set of buses. The operator used to carry out this operation is lshift
, or <<
, in the same fashion as direct
addition to a Krang
.
Aside from this, BusViews
can also return a list of the components already tied to their set of buses, a list of which
is available in the property content.
Class reference¶
-
class
krangpower._krangsuit.
_BusView
(oek: krangpower._krangsuit.Krang, bustermtuples)¶ -
__getattr__
(item)¶ Calculates a quantity from the submodule busquery on the BusView.
-
__init__
(oek: krangpower._krangsuit.Krang, bustermtuples)¶ Initialize self. See help(type(self)) for accurate signature.
-
__lshift__
(other)¶ Adds a component to the BusView, binding the component added to the buses referenced by the BusView.
-
__repr__
()¶ Return repr(self).
-
__str__
()¶ Return str(self).
-
content
¶ A list containing the PackedOpendssElements bound to the BusView’s buses.
-
PackedOpendssElement reference¶
PackedOpendssElements
are returned by bracket-indicizing a Krang
with a string containing the name of the desired
element. Aside from electrical components such as Vsource
, Line
, etc., buses can also be returned as
PackedOpendssElement
.
The main objective of PackedOpendssElement
is to conveniently pack in one object all the methods for the components
that are present in the various opendss interfaces (for example, for Vsource
, from opendssdirect.CktElement
and opendssdirect.Vsources
); Furthermore, with the classic opendss interface, before obtaining the correct data, the component has to be
selected via other interfaces, (again, for Vsource
, opendssdirect.Circuit.ActiveElement
and opendssdirect.Vsources.Name
).
With PackedOpendssElements
all the available methods are directly accessible, with no interface swap or the need to explicitly select the component
In addition to this core functionality, PackedOpendssElement
enables you to access the underlying object’s parameter
values through bracket indexing and also has a number of utility methods that you can see in the class detail docs in
this page.
Class reference¶
-
class
krangpower.enhancer.OpendssdirectEnhancer.
_PackedOpendssElement
(eltype, name)¶ -
__getitem__
(item)¶ Gets a property of the item from the text interface (as opposed to a natively exposed attribute of the object’s interface). For example, <>[‘xrharm’], where <> is a _PackedOpendssElement representing a Load, lets you access the ‘xrharm’ property, which is not available in any way through the standard interface.
-
__init__
(eltype, name)¶ Initialize self. See help(type(self)) for accurate signature.
-
__neg__
()¶ The - operator disables the _PackedOpendssElement, so that it’s like it does not exists. It directly wraps the ‘disable’ command from opendss.
-
__pos__
()¶ The + operator enables the _PackedOpendssElement, undoing the effects of a previous __neg__ call on the same element. It directly wraps the ‘enable’ command from opendss.
-
__repr__
()¶ Return repr(self).
-
__setitem__
(key, value)¶ Edits a property of the _PackedOpendssElement. Beware: If you do not pass a value with a pint measurement unit when editing a parameter that has a physical dimensionality, it will be assumed that you are using the default units.
-
__str__
()¶ Return str(self).
-
dump
()¶ Returns a dict with all the properties-values pairs of the object as they would be returned by calls to __getitem__.
-
help
¶ Displays informations about the object’s parameters.
-
topological
¶ Returns those properties that are marked as ‘topological’ in the configuration files and identify the wiring location of the element. (Typically, bus1 and, if it exists, bus2.)
-
unpack
(verbose=False)¶ Returns a _DssEntity (or a descendant) corresponding to _PackedOpendssElement.
-
Smart components example¶
Here follows a heavily commented example of how to use the smart component prototype, the FourQ
import krangpower as kp
import numpy as np
# In this example, we will simulate a battery with a toy logic that decides what to do according to its state and
# a price signal.
# -------------------------------------
# CONSTANTS
# -------------------------------------
PRICEPERIOD = 48
um = kp.UM
# -------------------------------------
# PRICE DEFINITION
# -------------------------------------
# we define a simple sinusoidal price with 12 hour period.
def price(t_hour):
return np.sin(t_hour/PRICEPERIOD/2/np.pi) + np.random.uniform(-0.7, 0.7)
# -------------------------------------
# BATTERY SMART LOGIC DEFINITION
# -------------------------------------
# we have to define the logic we want for the battery into a DecisionModel inherited class.
class BatteryManager(kp.DecisionModel):
def __init__(self, capacity=10*um.kWh, init_soc=5*um.kWh, pwr=3*um.kW, aggressiveness=2):
self.avg_price = 0
self.aggro = aggressiveness
self.nsamples = 0
self.capacity = capacity
self.SOC = init_soc
self.pwr_limit = pwr
self.money_gained = 0
self.pf = 0.985
def decide_pq(self, oek, mynode): # you have to override "decide_pq".
# the logic implemented here decides power according to how low is the price with respect to the recorded
# average and how much the battery is far from being filled at half capacity
# get the price
hour = oek.brain.Solution.DblHour() # returns the simulated hour
el_price = price(hour.magnitude) # this is the sell/buy price
# update the average
self.avg_price = (self.avg_price * self.nsamples + el_price) / (self.nsamples + 1)
self.nsamples += 1
# calculate conveniency and hunger (both are in [-1,1])
conveniency = self.avg_price - el_price
hunger = (self.capacity/2 - self.SOC)/(self.capacity/2)
# calculate the power as the sum of conveniency and hunger, clipped to the battery power limits. The logic
# operates in GENERATOR convention: positive power is produced, negative power is absorbed.
newpower = np.clip(
- (conveniency + hunger) * self.aggro,
- self.pwr_limit.magnitude,
self.pwr_limit.magnitude
)
energy_exchanged = newpower * um.kW * oek.get('stepsize')['stepsize']
# don't forget to update your SOC!
self.SOC += -energy_exchanged # negative energy exchanged CHARGES the battery
self.SOC = np.clip(self.SOC, 0*um.kWh, self.capacity)
# we update the gain/expense
self.money_gained += (energy_exchanged.to('kWh').magnitude * el_price)
# you must give back P, Q
return newpower * um.kW, 0.01 * newpower * um.kW
# -------------------------------------
# CREATING THE CIRCUIT
# -------------------------------------
# creating an appropriate voltage source. We want to simulate a 400V, 50Hz grid.
vs = kp.Vsource(basekv=0.4, frequency=50.0, Isc1=5)
# instantiating the circuit
circuit = kp.Krang('market_example', voltage_source=vs)
# we add a couple lines
circuit['sourcebus', 'bus_1'] << kp.Line(length=50 * um.m).aka('line_1')
circuit['bus_1', 'bus_2'] << kp.Line(length=50 * um.m).aka('line_2')
# definition and addition of our "smart battery" to bus_2
mylogic = BatteryManager()
circuit['bus_2', ] << kp.FourQ(kV=0.4).aka('controlled_battery') * mylogic
# setting the simulation step at 1 hr, tot sim time at three days
circuit.set(stepsize=1 * um.hr, number=72)
# -------------------------------------
# DEFINING WHAT RESULTS TO RECORD
# -------------------------------------
# in order to get interesting results, you have to define functions that take the Krang as argument and calculate
# interesting stuff. You can also refer to other objects in the namespace.
def my_power(oek):
pwr = sum(oek['controlled_battery'].Powers()[0][0:3]).magnitude
# we have to call magnitude, because they're all
# Pint Quantities!
return np.real(pwr)
def my_soc(_oek):
return (mylogic.SOC / mylogic.capacity).magnitude
def voltage_at_main(oek):
return (np.sum(np.abs((oek['sourcebus'].Voltages()[0:3]))) / 3).magnitude
# -------------------------------------
# SOLVE AND DISPLAY
# -------------------------------------
# evalsolve solves the prescribed steps of simulation and at each step evaluates the functions you pass to it.
pwr_hist = circuit.evalsolve(my_power, my_soc, voltage_at_main, as_df=False)
# we get a dict whose keys are the function names and whose values are lists of the results returned by the functions.
# print(pwr_hist)
# we display how many money units we gained with our wise battery operation.
print('\nBalance:')
print(mylogic.money_gained)
Components¶
Components are classes exposed by krangpower
that identify electrical components, monitors, linecodes…
They typically are instantiated with keyword arguments to set their parameters, possibly further modified, and then
added to a Krang with the <<
operator after, if necessary, associating them to one another with the *
operator.
the paramhelp() method¶
Don’t forget that every instance of a component has a paramhelp()
method, that will print to console useful information about parameters.
reference pages¶
Here you can find reference for each component available in krangpower. In particular, a table with the component’s parameters is provided.
wElectrical elements (bus-based)¶
These are electrical components that can be added to compose the grid topology.
Transformer¶
-
class
krangpower._components.
Transformer
(**parameters)¶ Transformer object
Property name type Default value windings int 2 phases int 3 conns stringarray wye,wye kvs floatarray 12.47,12.47 kvas floatarray 1000.0,1000.0 taps floatarray 1.000,1.000 %rs floatarray 0.20,0.20 xhl float 7.000 xht float 35.000 xlt float 30.000 x12 float 7.000 x13 float 35.000 x23 float 30.000 xscmatrix floatmatrix 7.00 normmaxhkva float 1100.0 emergmaxhkva float 1500.0 thermal float 2.0 n float 0.8 m float 0.8 flrise float 65.0 hsrise float 15.0 %loadloss float 0.0 %noloadloss float 0.0 normhkva float 1100.0 emerghkva float 1500.0 sub string n maxtap float 1.1 mintap float 0.9 numtaps int 32 subname string %imag float 0.0 ppm_antifloat float 1.0 bank string xfmrcode string xrconst string no x12 float 7.0 x13 float 35.0 x23 float 30.0 leadlag string lag normamps float 50.929 emergamps float 69.449 faultrate float 0.007 %perm float 100.0 repair float 36.0 basefreq float 50.0 -
__getitem__
(item)¶ Gets a parameter for the object.
-
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Line¶
-
class
krangpower._components.
Line
(**parameters)¶ Line object. Data for the conductors must specified by a LineCode or a LineGeometry.
Property name type Default value length float 1.000 switch string false rg float 0.01805 xg float 0.155081 rho float 100.0 units string none earthmodel string deri normamps float 400.0 emergamps float 600.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Vsource¶
-
class
krangpower._components.
Vsource
(**parameters)¶ Voltage source
Property name type Default value basekv float 115.0 pu float 1.0 angle float 0.0 frequency float 60.0 phases int 3 mvasc3 float 2000.0 mvasc1 float 2100.0 x1r1 float 4.0 x0r0 float 3.0 isc3 float 10000.0 isc1 float 10500.0 r1 float 1.6038 x1 float 6.4151 r0 float 1.796 x0 float 5.3881 scantype string pos sequence string pos z1 floatarray 1.6037668,6.4150673 z0 floatarray 1.7960358,5.3881075 z2 floatarray 1.6037668,6.4150673 puz1 floatarray 0.012126781,0.048507125 puz0 floatarray 0.013580611,0.040741834 puz2 floatarray 0.012126781,0.048507125 basemva float 100.0 yearly string daily string duty string spectrum string defaultvsource basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Isource¶
-
class
krangpower._components.
Isource
(**parameters)¶ Current source
Property name type Default value amps floatarray 0.0 angle float 0.0 frequency float 60.0 phases int 3 scantype string pos sequence string pos yearly string daily string duty string spectrum string default basefreq float 50.0 enabled string true -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Capacitor¶
-
class
krangpower._components.
Capacitor
(**parameters)¶ Capacitance
Property name type Default value phases int 3 kvar float 1200.0 kv float 12.470 conn string wye cuf float 20.47 r float 0.0 xl floatarray 0.0 harm intarray 0 numsteps int 1 states intarray 1 normamps float 75.0046059412345 emergamps float 100.006141254979 faultrate float 0.0 %perm float 100.0 repair float 3.0 basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Reactor¶
-
class
krangpower._components.
Reactor
(**parameters)¶ Reactor object
Property name type Default value phases int 3 kvar float 1200.0 kv float 12.47 conn string wye parallel string no r float 0 x float 1555.009 rp float 0 z1 floatarray 0,0 z2 floatarray 0,0 z0 floatarray 0,0 z floatarray 0.0,1555.009 rcurve string lcurve string lmh float 4124.7895 normamps float 5.0 emergamps float 6.0 faultrate float 0.0 %perm float 100.0 repair float 3.0 basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Generator¶
-
class
krangpower._components.
Generator
(**parameters)¶ Generator object
Property name type Default value phases int 3 kv float 12.47 kw float 1000.0 pf float 0.88 kvar float 60.0 model int 1 vminpu float 0.90 vmaxpu float 1.10 yearly string daily string duty string dispmode string default dispvalue float 0.0 conn string wye rneut float 0.0 xneut float 0.0 status string variable class int 1 vpu float 1.0 maxkvar float 120.0 minkvar float -120.0 pvfactor float 0.1 forceon string no kva float 1200.0 mva float 1.2 xd float 1.0 xdp float 0.28 xdpp float 0.2 h float 1.0 d float 0.0 usermodel string userdata string shaftmodel string shaftdata string dutystart float 0 debugtrace string no balanced string no xrdp float 20.0 spectrum string defaultgen basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Storage¶
-
class
krangpower._components.
Storage
(**parameters)¶ Storage object
Property name type Default value phases int 3 kv float 12.47 kw float 0.0 pf float 1.0 conn string wye kvar float 0.0 kva float 25.0 kwrated float 25.0 kwhrated float 50.0 kwhstored float 50.0 %stored float 100.0 %reserve float 20.0 state string idling %discharge float 100.0 %charge float 100.0 %effcharge float 90.0 %effdischarge float 90.0 %idlingkw float 1.0 %idlingkvar float 0.0 %r float 0.0 %x float 50.0 model int 1 vminpu float 0.9 vmaxpu float 1.1 balanced string no limitcurrent string no yearly string daily string duty string dispmode string default dischargetrigger float 0.0 chargetrigger float 0.0 timechargetrig float 2.0 class int 1 dynadll string dynadata string usermodel string userdata string debugtrace string no spectrum string basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
PvSystem¶
-
class
krangpower._components.
PvSystem
(**parameters)¶ PvSystem object.
Property name type Default value phases int 3 kv float 12.47 irradiance float 1.0 Pmpp float 500.0 pctPmpp float 100.0 Temperature float 25.0 pf float 1.0 conn string wye kvar float 0.0 kVA float 500.0 %Cutin float 20.0 %Cutout float 20.0 EffCurve float P-TCurve float %R float 50.0 %X float 0.0 model int 1 Vminpu float 0.9 Vmaxpu float 1.1 Balanced string No LimitCurrent string No yearly string daily string duty string Tyearly string Tdaily string Tduty string class int 1 UserModel string UserData string debugtrace string NO VarFollowInverter string No kvarLimit float 500.0 DutyStart float 0.0 spectrum string basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
UNDER CONSTRUCTION
UNDER CONSTRUCTION
UNDER CONSTRUCTION
Smart electrical elements¶
These are electrical components typical to krangpower that enable the simulation of electrical circuit that include smart/algorithmic agents. These classes provide the
facilities needed to integrate a fully custom and separate control logic into a Krang
, allowing for easy and intuitive information exchange.
FourQ¶
-
class
krangpower._smart_components.
FourQ
(**parameters)¶ -
aka
(name)¶ Aliases the object.
-
define_dm
(dm)¶
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
fus
(oek, myname)¶
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
update_pq
(oek, mybus)¶
-
Above-graph components (element-based)¶
These components provide control and monitoring function. They are not directly part of the grid topology. Their collocation in the system is determined by element, transformer winding, etc.
Regcontrol¶
-
class
krangpower._components.
Regcontrol
(name='', **parameters)¶ Regcontrol object
Property name type Default value vreg float 120.0 band float 3.0 ptratio float 60.0 ctprim float 300.0 r float 0.0 x float 0.0 bus float delay float 15.0 reversible string no revvreg float 120.0 revband float 3.0 revr float 0.0 revx float 0.0 tapdelay float 2.0 debugtrace string no maxtapchange int 16 inversetime string no tapwinding int 1 vlimit float 0.0 ptphase int 1 revthreshold float 100.0 revdelay float 60.0 revneutral string no eventlog string yes remoteptratio float 60.0 tapnum float 0 basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Monitor¶
-
class
krangpower._components.
Monitor
(name='', **parameters)¶ Monitor object. Several methods of odsswr.Circuit.py allow for exportation of the recordings of the monitors.
Property name type Default value mode int 0 action string residual string no vipolar string yes ppolar string yes basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
StorageController¶
-
class
krangpower._components.
StorageController
(name='', **parameters)¶ StorageController object
Property name type Default value Element string Terminal int 1 kWTarget float 8000.0 %kWBand float 2.0 PFTarget float 0.96 PFBand float 0.04 ElementList stringarray s1 Weights floatarray 1 ModeDischarge string peakshave ModeCharge string Time TimeDischargeTrigger int -1 TimeChargeTrigger int 2 %RatekW float 20.0 %Ratekvar float 20.0 %RateCharge float 20.0 %Reserve float 25.0 kWhTotal float 50.0 kWTotal float 25.0 kWhActual float 50.0 kWActual float 5.0 kWneed float 0.0 %Participation float Yearly string Daily string Duty string EventLog string No VarDispatch string No InhibitTime float 5.0 Tup float 0.25 TFlat float 2.0 Tdn float 0.25 kWThreshold float 6000.0 basefreq float 50.0 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Transmission line definition¶
These entities define transmission line parameters, directly via impedance matrix specification (LineCode) or via an arrangement of conductors defined in the Circuit (see section “Conductor definition”)
LineCode_S¶
-
class
krangpower.
LineCode_S
(name='', **parameters)¶ Contains a linecode defined with symmetrical components R0,R1,C0,C1,X0,X1.
Property name type Default value nphases int 3 r1 float 0.05800 x1 float 0.12060 r0 float 0.17840 x0 float 0.40470 C1 float 3.40000 C0 float 1.60000 units string none baseFreq float 50.0 normamps float 400.0 emergamps float 600.0 faultrate float 0.1 %perm float 20.0 repair float 3.0 Kron string N Rg float 0.01805 Xg float 0.15508 rho float 100.0 neutral int 3 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
LineCode_A¶
-
class
krangpower.
LineCode_A
(name='', **parameters)¶ Contains a linecode defined with generally asymmetrical components, rmatrix, cmatrix, xmatrix.
Property name type Default value nphases int 3 units string none rmatrix floatmatrix 0.09813333,0.04013333,…. xmatrix floatmatrix 0.21530000,0.09470000,… cmatrix floatmatrix 2.80000000,-0.60000000,… baseFreq float 50.0 normamps float 400.0 emergamps float 600.0 faultrate float 0.1 %perm float 20.0 repair float 3.0 Kron string N Rg float 0.01805 Xg float 0.15508 rho float 100.0 neutral int 3 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
LineGeometry_O¶
-
class
krangpower.
LineGeometry_O
(name, **parameters)¶ Line Geometry OVERHEAD
Property name type Default value nconds int 1 nphases int 1 wire stringarray x floatarray 0 h floatarray 0 units stringarray mt reduce string spacing string -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
specialparams
¶
-
toe
¶
-
LineGeometry_T¶
-
class
krangpower.
LineGeometry_T
(name, **parameters)¶ Line Geometry WITH TAPE SHIELDED CABLE
Property name type Default value nconds int 1 nphases int 1 tscable stringarray x floatarray 0 h floatarray 0 units stringarray mt reduce string spacing string -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
specialparams
¶
-
toe
¶
-
LineGeometry_C¶
-
class
krangpower.
LineGeometry_C
(name, **parameters)¶ Line Geometry WITH CONCENTRIC NEUTRAL CABLE
Property name type Default value nconds int 1 nphases int 1 cncable stringarray x floatarray 0 h floatarray 0 units stringarray mt reduce string spacing string -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
specialparams
¶
-
toe
¶
-
Conductor definition (for LineGeometry)¶
These entities are capable of memorizing the physical and geometrical data of conductors intended to be arranged in a LineGeometry
. The backend then derives the impedance matrix of the line for the simulation.
WireData¶
-
class
krangpower._components.
WireData
(name='', **parameters)¶ Contains overhead line conductor electro-physical constants and geometric parameters.
Property name type Default value rdc float -1 rac float -1 runits string none gmrac float -1 gmrunits string none radunits string none diam float -2 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
TSData¶
-
class
krangpower._components.
TSData
(name='', **parameters)¶ Contains tape shielded underground conductor electro-physical constant and geometric parameters
Property name type Default value DiaShield float -1 TapeLayer float -1 TapeLap float EpsR float -1 InsLayer float 0 DiaIns float -1 DiaCable float Rdc float -1 Rac float -1 Runits string -2 GMRac float GMRunits string radunits string normamps float emergamps float diam float -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
CNData¶
-
class
krangpower._components.
CNData
(name='', **parameters)¶ Contains concentric neutral underground conductor electro-physical constant and geometric parameters
Property name type Default value k int -1 DiaStrand float -1 GmrStrand float Rstrand float -1 EpsR float InsLayer float -1 DiaIns float DiaCable float -1 Rdc float -1 Rac float -2 Runits string GMRac float GMRunits string radunits string diam float k float 2.3 -
aka
(name)¶ Aliases the object.
-
eltype
¶
-
fcs
(**hookup)¶ Generates the opendss “new…” command for the object. Needs to be passed an appropriate set of keyword arguments to fill whatever topologic parameters are needed. It’s meant primarily for internal use by krangpower itself.
-
fullname
¶ Name, in the form eltype.elname
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
classmethod
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶ Returns a dict that describes the element’s parameters. It’s compatible with the json I/O functions.
-
paramhelp
()¶ Prints a cheatsheet for the object’s parameters.
-
sf_deepcopy
()¶ Returns a deep copy of the object. This method is to be used in place of the standard copy.deepcopy, that will raise an exception.
-
toe
¶
-
Curves and dependencies¶
These are auxiliary object that are used to manage data-points, mainly electrical characteristics and time-dependent quantities, for sequential simulations (duty-cycle, etc.) of a Circuit. Typical examples are inverter efficiencies, memorized in Curve (with ‘xycurve’ parameter), temperature profiles (Curve with ‘thsape’ parameter) and Load histories, memorized in loadshapes.
CsvLoadshape¶
-
class
krangpower._components.
CsvLoadshape
(name='', csv_path=None, column_scheme=None, interval=None, use_actual=True, npts=None)¶ Allows to specify a Loadshape that refers to a CSV file. Requires a path. The name of the loadshape will be the same as the file basename. Automatically recognizes if header is present or not.
Parameters: - name (str) – the loadshape name.
- csv_path (str) – the csv file path.
- column_scheme (dict) – A dictionary of one or more int:<’hour’|’mult’|’qmult’> couples that associate the column with one of the hour, mult and qmult properties.
- interval (_pint_qty_type) – length of step in the data as a pint unit with dimension [time]. If unspecified or None the first column of the csv will be used as the vector of times, that can be, in general, non uniformly spaced.
- use_actual (bool) – setting this to False indicates that you want to use the data values in the csv to rescale the base value of the DSS object, rather than using the values directly.
- npts (int) – the number of points to load from the csv. If None, all the lines in the csv will be loaded in the loadshape. If greater than the number of lines in the csv, the lines will be tiled from the beginning. Please note that, since the automatic determination of the number of datapoints requires opening the csv and counting the rows, specifying this parameter, when possible, will grant a speed-up, especially for big files and/or multiple imports.
-
eltype
= 'CsvLoadshape'¶
-
fcs
(**hookup)¶
-
fullname
¶
-
get_at_hour
¶
-
get_at_row
¶
-
has_hour
()¶
-
static
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
static
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
()¶
-
peek
()¶
-
uses_actual
¶
XYCurve¶
-
class
krangpower._components.
Curve
(name, curve_type, data, interval=None)¶ -
fcs
()¶
-
classmethod
isabove
()¶ Returns True if the class is an above-graph component, like a monitor or regulator, False otherwise.
-
classmethod
isai
()¶ Returns true if the class is ai-enabled, False otherwise.
-
static
isnamed
()¶ Returns True if the class is a named entity, like a LineCode, False otherwise.
-
jsonize
(all_params=False, flatten_mtx=True)¶
-
x
¶
-
y
¶
-
z
¶
-
I/O with JSON files¶
Krang has facilities to store all the relevant information they contain in structured JSON files. The essential structure of such file is this:
krangpower JSON v0.1.6
root
├──"ckt_name": <string>
├──"elements":
│ ├──"type1.name1":
│ │ ├──"type": <string>
│ │ ├──"name": <string>
│ │ ├──"properties": {<prop_name>: <value>}
│ │ ├──("units"): {<prop_name>: <unit_string>}
│ │ ├──("depends"): {<prop_name>: <name_string>}
│ │ ├──("topological"): [<bus_name_string>]
│ │ └──("hash"): <string> (*)
│ └──"type2.name2":
│ '.....
├──"settings":
│ ├──"values": {<setting_name>: <value>}
│ └──"units": {<setting_name>: <unit_string>}
└──"buscoords": {<bus_name_string>: [x y]}
# NOTES:
# keys in parentheses are not necessarily present
# (*) "hash" is used only for comparisons; when editing a json externally, it can be omitted
Full examples are available under the package’s /test
folder. The methods here illustrated are documented in the Krang reference page too.
Saving¶
Krang
can output such a json file through the Krang.save_json()
method.
-
Krang.
save_json
(path=None, indent=2) Saves a complete JSON description of the circuit and its objects. If a valid path string is passed, a file will be created, and None will be returned; if None is passed as path, a Text buffered Stream (io.StringIO) with the exact same information as the file will be returned instead.
Loading¶
Krang
exposes a Krang.from_json(path)
class method. It returns a Krang
in the state syntesised by the JSON.
-
classmethod
Krang.
from_json
(path, override_log=False) Loads circuit data from a json structured like the ones returned by Krang.save_json. Declaration precedence due to dependency between objects is automatically taken care of.
Note
Inside the box, from_json(path)
instantiates an empty Krang
, adds all the components in the right order of dependency and finally returns it.
I/O with zip archives¶
Krang
allows to export a package that encloses in one place everything needed to reproduce the circuit.
A bare JSON, in fact, contains all the topological information, but references such as csv loadprofile files, DecisionModels
for the smart components and the likes are not included.
In order to save/load a full pack, the following functions can be used:
Saving¶
-
Krang.
pack_ckt
(path=None) Packs a ckt archive with all the information needed to reproduce the Krang. If a valid path string is passed, a file will be created, and None will be returned; if None is passed as path, a Binary buffered I/O (io.BytesIO) with the exact same information as the file will be returned instead.
Loading¶
-
classmethod
Krang.
open_ckt
(path, strict=True) Loads a ckt package saved through Krang.pack_ckt() and returns a Krang.
The files saved are zip archives that contain, aside from the main JSON file, other archives and pickle-files with all the necessary information.
md5 hash¶
On save and load, the Krang is hashed with the fingerprint
method in order to verify correctness. The hash
can be seen in a .md5 file present in the ckt archive.
I/O with DSS files (debug)¶
krangpower
offers compatibilty with the classic DSS format of OpenDSS, mainly for purposes of back-compatibility
and debugging.
Loading¶
Krang
exposes a Krang.from_dss
class method. It was written with the only scope of allowing direct use of existing dss scripts without having to
translate them to krangpower instructions; in all other cases, writing a krangpower script is to be always preferred.
-
classmethod
Krang.
from_dss
(file_path, target_krang=None, frequency=50.0) from_dss(file_path, target_krang, frequency) allows to create a krang from an existing dss script or to pass commands to a krang from an existing dss script. USE AT YOUR OWN RISK.
Parameters: - file_path – The path of the dss file to utilize
- target_krang –
- If None, a new krang will be created and initialized with the information from the file (must contain a ‘new circuit’ command).
- If a Krang is passed, the commands in the script will be passed to that Krang.
- frequency – the general frequency to use for the krang, if a new one is created.
Saving¶
Krang.save_dss
saves a dss from the series of instructions that were imparted through the
Krang.command
method.
Warning
Modifications operated through other means than the text interface won’t be included!
-
Krang.
save_dss
(path=None) Saves a file with the text commands that were imparted by the Krang.command method aside from those for which echo was False. The file output should be loadable and runnable in traditional OpenDSS with no modifications.
krangpower.enhancer¶
The submodule krangpower.enhancer
constitues an OpenDSSDirect.py wrapper and overhaul, and is designed to expose the exact same interface - the api reference is the same you can find in its docs. It is usable in and by itself as a substitute of the OpenDSSDirect.py module when interested in the additional functionality.
This means that if:
import opendssdirect # the OpenDSSDirect.py module
opendssdirect.dss.<X>
is a valid expression, then:
import krangpower
krangpower.enhancer.<X>
also is, but the results returned by krangpower.enhancer
have several advantages:
- Items that OpenDSS returns as simple lists of floats (e.g.,
opendssdirect.dss.Circuit.Losses()
,opendssdirect.dss.Bus.Voltages()
, etc.) are returned as lists of complex numbers, matrices of [nterm x ncond], etc. as is appropriate. - Structured items such as
opendssdirect.Circuit.SistemY()
are returned aspandas.DataFrame
for easier manipulation and export - Items come, where appropriate, as Quantities (from the pint package) with the appropriate measurement unit. This enables easy conversions and secures against miscalculations.
- Through the exposed function
txt_command
, the OpenDSS text interface is checked for errors (that are normally just returned as strings without raising anything). - The exposed
pack
function that enables easy and intuitive element exploration by returning a PackedOpendssElement corresponding to the name passed as argument, either fully qualified or simple.
Additional functions¶
krangpower.enhancer
exposes a few more utility functions.
-
krangpower.enhancer.
pack
(item)¶ Returns a PackedOpendssElement corresponding to item.
-
krangpower.enhancer.
get_all_names
()¶ Gets the fully qualified names of the elements, plus buses, loadshapes and xycurves.
-
krangpower.enhancer.
txt_command
(cmd_str: str, echo=True)¶ Performs a text interface call with the argument passed and logs command and response. The results are checked for silent errors. When instantiating components through this function, the update of the names returned by get_all_names()is triggered. The log output can be suppressed by setting the keyword argument echo=False; but even in this case, if kp.get_log_level() is 0, the log of the command will be forced.
Circuit Graph and Views¶
krang.graph¶
Krang
has a graph attribute that returns a networkx Graph
. The nodes of this graph are constituted by the buses; the
edges are the elements that connect these buses, such as Line
, Transformer
, Reactor
…
The nodes have:
- a property
'bus'
, which is thePackedOpendssElement
corresponding to that bus; - a property
'el'
, which is a list of thePackedOpendssElement
that are bound to that bus;
The edges have:
- a property
'el'
, which is a list of thePackedOpendssElement
that are bound to that couple of buses.
Since it contains a plethora of PackedOpendssElement
, the graph has the potentiality for retrieving all sorts of useful
information and is amenable to data query and reorganization with networkx
.
GraphView¶
To aid in working with the graph, krangpower exposes the template class GraphView
. The GraphView
is initialized with a
Krang
instance and two arguments, busfun
and edgefun
, that are functions meant to be applied to every 'el'[0]
of the
edges and to every 'bus'
in the nodes (these function can also be None
).
Initialized in this way, the GraphView
is then bracket-indicizable with bus names
(for nodes) or couples of bus names (for edges) and retrieves the result of the application of the function on that bus
or edge.
-
class
krangpower.
GraphView
(busfun, edgefun, ckgr: krangpower._krangsuit.Krang, raw_mode=False)¶ -
__getitem__
(item)¶ Gets the value of busfun at a bus, or the value of edgefun at an edge. If GraphView.raw_mode == True, it behaves like a nx.Graph.
-
__init__
(busfun, edgefun, ckgr: krangpower._krangsuit.Krang, raw_mode=False)¶ Applies a busfun and and edgefun to the graph of a Krang. It then is indicizable with bus names and tuples of two bus names to retrieve the relative results.
-
raw_mode
= None¶ If True, __getitem__ has the same behavior as nx.Graph. If False, __getitem__ returns the values of busfun or edgefun directly.
-
Another method of usage is to inherit GraphView
and override its __init__ method in order to pack busfun and
edgefun inside it. This is done, for example, with the built-in VoltageView
, that can be found in the submodule gv
and initialized with just
a Krang
instance and returns the property Voltages()
of both 'bus'
at buses and 'el'[0]
at edges.
More specialized built-in GraphView
s can and will be added in the future to krangpower.gv
.
Example:
>>> import krangpower as kp
>>> from numpy import round
>>>
>>> um = kp.UM
>>> src = kp.Vsource(basekv = 10.0 * um.kV)
>>> twc = kp.Krang('twc', src)
>>> twc['sourcebus', 'a'] << kp.Line(units= 'm', length=20.0 * um.m).aka('l1')
>>> trf = kp.Transformer(windings=3,
>>> conns=['delta', 'wye', 'wye'],
>>> kvs=[10.0, 2.0, 3.0] * um.kV,
>>> kvas=[100.0, 20.0, 85.0] * um.kW,
>>> taps=[1.0, 1.0, 1.0],
>>> pctrs=[1.0, 1.0, 1.0]).aka('trf')
>>> twc['a', 'b', 'c'] << trf
>>> twc['b', 'bb'] << kp.Line(units= 'm', length=10.0 * um.m).aka('lbb')
>>> twc['c', 'cc'] << kp.Line(units= 'm', length=15.0 * um.m).aka('lcc')
>>> twc['bb',] << kp.Load(kv=2.0 * um.kV, kw = 5.0 * um.kW).aka('loadlow')
>>> twc['cc',] << kp.Load(kv=3.0 * um.kV, kw = 35.0 * um.kW).aka('loadhi')
>>> twc.solve()
>>> bvo = kp.gv.VoltageView(twc)
>>> print(round(bvo['bb'], 2))
[ 974.96 -581.68j -991.23 -553.5j 16.27+1135.18j] volt
>>> print(round(bvo['b','bb'], 2))
[[ 977.18 -581.47j -992.16 -555.52j 14.98+1137.j ] [ 974.96 -581.68j -991.23 -553.5j 16.27+1135.18j]] volt
Data files¶
Krangpower depends on a series of data/configuration files, contained in the /defaults
folder, in order to offer its functionality.
Warning
These files should only be touched if you know what you’re doing, and modifying them improperly could result in unpredictable and wrong behavior.
Important
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.
association_types.csv¶
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:
line,linegeometry,geometry,name
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.
default_dssentities.json¶
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
found:
“type”
It’s simply the type of the element. It’s there just for practical reasons.
“properties”:
They are the default values for the properties, keyed by name.
Implicitly, they define what is the correct data type for that parameter: string
, int
, float
, list
([...]
) or matrix
([[...], [...]]
)
“units”
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)
“associated”
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)
“topological”
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)
default_settings.json¶
This file is somewhat similar to default_dssentities.json. It’s used in Krang
methods set()
and get()
. It contains two dicts and a list:
“values”
The default value for every opendss option is specified, and, implicitly, its data type.
“units”
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
“contingent”
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.
interf_sel.json¶
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.
interfaces.json¶
It lists what are the available methods of each submodule of OpenDSSDirect.py
. It’s used in the automatic population
of krangpower.enhancer
that is performed on load.
This file is complete.
dangerous_stacks.txt¶
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.
measurement_units.json¶
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
retrieved.
treatments.json¶
This file contains, for each OpenDSSDirect.py
function, what chain of functions krangpower.enhancer
has
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 krangpower.enhancer
code.
error_strings.json¶
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.
Important
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.
mandatory_unit_dec.json¶
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.
bypassable_cmd_strings.txt¶
This file contains regular expressions that krangpower tries to match to any command sent through Krang.command()
.
If the command matches any of these regular expressions, the cached Krang.graph()
(whose calculation can be very expensive)
is mantained.
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.
splash.txt¶
Just a splash screen with the logo.
Configuration file¶
Krangpower comes with a configuration file that can be found in the package folder, under /config/krang_config.cfg
.
The sections are the following, and the single parameters should be sufficiently self-explicative.
- data_files
- temp_files
- log_settings
- precision
- misc_settings
Note
misc_settings
is the only section containing options that can be, at first, a little obscure; keep in mind
that this section contains parameters that have a cosmetic effect on the logs and packages and no influence on
functionality.
Logging¶
krangpower mantains two different logs that can be useful for debugging purposes. The log files are rolled over every time the enhancer submodule is loaded, and a number of historical version is mantained, up to a total configurable in the configuration file.
By default, in Windows, they can be found under:
%APPDATA%/krangpower/commands.log
%APPDATA%/krangpower/krangpower.log
For Linux, they are created under:
$home/krangpower_logs/commands.log
$home/krangpower_logs/krangpower.log
Log level¶
In order to utilize the logs, it is of uttermost importance to correctly set the module-wide log level. The level has to be set with a dedicated function exposed at the module level:
-
krangpower.
set_log_level
(lvl)¶
The default/starting value of the logging level, when using krangpower
out of the box, is set at logging.WARNING
(equivalent to a numerical value of 30).
Warning
The commands.log and krangpower.log files are only written if the log level is <= logging.DEBUG (10).
Warning
The log files are quite verbose and writing them often causes an appreciable execution time overhead, so they should be left unactive if not needed.
Tip
A log level between logging.DEBUG and logging.INFO (10 < log level <= 20) does not write the logs, but displays a bit
more information on the console at runtime, notably
progress bars for the computation/execution of properties/function such as krang.graph
, etc.
commands.log¶
This file contains every command passed to the underlying OpenDSS textual interface, complete with a timestamp and the result
returned by OpenDSS. The log is mantained directly by the krangpower.enhancer
submodule.
krangpower.log¶
This file logs various activity aspect of the Krang components and PackedOpendssElements
. In particular, you can find
here every call to the OpenDSSDirect.py attributes and reports on the choices made by the components’ _setparameter
method.
Note
The location of the logs, and the starting value of the log level, can be customized in the configuration file. They can be found under:
./config/krang_config.cfg --> misc settings --> default_logging_level
./config/krang_config.cfg --> log settings --> *
FAQ¶
We’re waiting for somebody to frequently ask questions!
Less-Frequently Asked Questions¶
Q: Wait a minute! << is not meant to do operations in-place! You’re a criminal!
A: Call the cops.
About¶
The name krangpower¶
Remember the Ninja Turtles? Krang, one of their enemies, was a genius-grade brain that could clumsily move only with his two little tentacles, so he used a bionic suit in order to gain strength and the ability to move and operate with ease. OpenDSS, too, is a genius-grade brain that can interact with the world only through a vintage COM interface. Krangpower is an attempt to endow it with an empowering suit. Dimension X will be ours.