kit-iai / pyapi-rts Goto Github PK

Implement a clearer structure, divided between users and developers.

Users:

• Installation
• Examples
• Most important interfaces/classes
• Graph structure

Developers:

• Package/module structure, core ideas
• Additional dependencies
• Testing, Coverage
• Documentation

Currently, a default number of 10 load units is implemented for all components that don't define another value. This appears to be valid for power system components, but other components don't have load units at all.

This could be implemented with a condition on the COMPONENT-BUILDER-OPTIONS: COMPONENT-MODE: PSYS.
Cable ends have STACKING-LOAD: 0 defined. For transmission lines, it's defined in the calc block.
Split cables and tlines have 5 load units per subsystem. No matter where the calc block is located.

lf_rtds_sharc_sld_MACV31

• Exported components might lead to warnings due to differing parameter ordering. The order of SE10, SE12 and faccnfg seems to be important. Components should just print their parameters in the original order.

ground

• These components usually don't have a Parameter or Enumeration section, but all components export these sections, which leads to an error.

Connection Points of stretched components (bus, wire) can only be connected to regular connection points (e.g. at the ends of bus, wire components). Crossing two stretchable components results in a compilation error, not in a valid connection.

In order to use transmission lines in a simulation, the parameters need to be compiled to a .tlo file. For the subset of 3 phase RLC transmission lines, the necessary computations are actually fairly simple (see RSCAD documentation).

Currently, Components are created without any arguments, resulting in an initialization with default values.
While this behavior is close to the creation in the GUI, and thus somewhat intuitive, it might be useful to initialize them directly with the desired values.
This could be achieved with a class method that takes the parameters as a dictionary.

The current hooks implementation with a base class containing multiple method stubs that are only partially overwritten by the concrete hooks is a bit weird. And since the current use of hooks is limited to very few places in the code, a simpler and cleaner solution might be to just provide them as functions that are imported in the usual way.

lfrtdssharcsldRLSPLIT

• Error in bounding box calculation (L129): BoundingBox(0, 0, 16, "0) LineWidth(1", False, False)
  • Source (L44): LineWidth(3) LINE(0,0,16,0) LineWidth(1)
• Odd parameter parsing (L136): $(0.0)
  • Source (L98): If (Cs>0.0)

lfrtdssharcsldSERIESCAP

• Odd parameter parsing (L81): ParameterBoundProperty("$($A1PosY)",int)
  • Source (L38): If ($A1PosY, $A2PosY)

lfrtdssharcsldMACV31

• Li12: -self.get_by_key("Li1", 1.0, True) * self.get_by_key("tr", 1.0, True)

The rewritten condition trees are untested, which needs to change since they are an essential part of many component classes.

lfrtdssharcsldSHUNTRLCComponent has issues with name property. The component doesn't have any real name, but defines a name computation that calls an unknown function. This leads to crashes, e.g. in search_by_name().

Quick fix: wrap c.name in str().

ParameterBoundProperty calls get_value() on the entry it finds in the given dictionary. However, since computations are also included in the dictionary, this could lead to runtime errors. On the other hand, if computations are never accessed in these methods, they can be omitted from the dictionary creation (and thus speed up the process).

The current graph structure (full graph) is not accurate and in parts unclear.

• implement connection types as Enum for more clarity (see graph_visualization.py for overview)
• implement method to model multiple connections between two components
• document graph structures more clearly, provide best practices/tips
• investigate the necessity of different graph types (full graph, connection graph,...)

When creating the Python classes of the Components for the first time, there is a dependency from the class generation to the api module that can't be resolved because Hierarchy depends on the yet to be created HIERARCHY Component.

Example pick_wye_delta: Currently returns 1.0. We have no idea, when this is invoked and leads to wrong results. Would it help to just return None? And let the calling code fail?

Calculation of bounding boxes is untested. Every used graphics macro should be tested.

Some components rely on the isDistributionMode() function. This is currently not implemented.

The type defines a component and should not be changed in an instance of a certain component type. However, currently it is implemented as an instance property.

The KEYWORDS: section contains some useful information. E.g. one could check if a generator is connected to an exciter by checking for component with the exciter keyword.

This could be implemented as a list or set of strings for each component class.

Tasks

• min, max properties for IntegerParamter and FloatParameter
• index property for EnumParameter
• default property (per instance) for all Parameters
• set_with_boundary() method for IntegerParamter and FloatParameter
• reset() method for all Parameters
• Name and String validation: investigate the differences
• investigate escaping requirements for str values
• explicit setter for draft variable as value

Rationale

The current interaction with Parameter (get_value and set_value) is very cumbersome for Python. One would expect that

abc = componentx.collectiony.paramz

yields the result directly.
Furthermore, one would expect to set the value of a parameter just like this:

componentx.collectiony.paramz = xyz

instead of with the set_value() method.

However, there are a few features that parameters need to support:

• min, max values should be respected in setters (for int, float)
• nice to have: string and name parameters should be distinguishable, including an easy way to apply enumeration to names (if there is any difference between them)
• draft variables need to be supported → "$XY" has to be evaluated by scanning the draft for matching rtds_draft_var components
  • resolving draft variables could be a method in the Draft class or a method of the Parameter class that takes a dictionary with available draft variables

Thoughts:

• Parameters don't need their key attribute (this is all handled in the collection).
• Explicit getters and setters could be hidden via auto-generated properties in collections.
• BUT: when getting the value of a parameter, we need a way to specify if we want the raw value or the evaluated value (or always return the raw value and check for possible variables in the calling code)
• Maybe implementing the value as a property would be a viable compromise
• The from_str option could be implemented as a factory (class) method

Requirements

• Implement a method that allows resolving draft variables in component parameters.
• This needs to be possible for ParameterBoundProperty to evaluate conditions correctly.
  • ParameterBoundProperties are used for ConnectionPoint and BoundingBox evaluation. In both cases, draft variables are not allowed. It is possible to enter the name of a draft variable into a field used for the mentioned evaluations, but this will throw an error in RSCAD.

Draft Variables in RSCAD Components

rtds_draft_var:

Draft of preprocessor variable
Used to assign a value to preprocessor variable
Can be modified from RunTime to invoke recompile

DRAFT_DEFINE:
    $Name = $Value

Defines a draft variable with the Name of the component and assigns the Value to it. Also creates a slider for the runtime, but this is not relevant for the draft file.
Other components can then use $Name as the value of a parameter with the correct type. The API should be able to resolve these instances to the value that is assigned to the draft variable. However, there also needs to be a way to access the raw content of the parameter, in this example $Name.

_rtds_CT:

3 phase current transformer
Control component

DRAFT_DEFINE:
    $Name|$NRb = $Rbi
    $Name|$NLb = $Lbi

The current transformers can define draft variables for certain parameters. These variables include the name of the component and the given name for the parameter. The parameter name can be a string starting with "$" or a REAL value. It can't be an already taken name of a draft variable. Using the default values, a variable might be named CT1|$RBurd. A corresponding slider will be created for the runtime.

The values of those variables are usually REAL. However, the pipe symbol "|" in the name prevents the usage of these draft variables in other REAL parameters. They can be used as input for String parameters, but this doesn't make much sense.