Separate adding components from adding buses in PowerElectronics system assembly.

[pelesh]

Summary

Suggested Change

In class PowerElectronicsModel when assembling the system and evaluating residual vectors and Jacobian matrices use separate loops to add contributions from components and connection nodes (buses).

Definitions

• Components are objects that:
  • own and evaluate their internal equations
  • contribute to the coupling equations
  • may own their internal but not coupling variables
• Coupling nodes (buses) are objects that:
  • own coupling equations and coupling variables
  • may contribute to coupling equations

Current State

• Internal and external variables are updated from the system solver class using distribute Vectors method called by the system model.
• Components have coupling variables tagged with values in extern_indices_, which is a std::set. It would give us more flexibility if components own arrays with mapping indices for internal and external (coupling) variables instead.
• There are no mapping vectors for component residual values.

Rationale

• Internal component equations can be updated by embarrassingly parallel computations. Separating components from buses helps expose this parallelism.
• Coupling variables are owned by coupling nodes (buses). Exposing these, provides better access to the variables that need to be communicated.
• Separating component's residual and Jacobian into internal part and contributions to the coupling (external) part will likely simplify implementation of co-simulation and multimethod integration methods.
• Mapping indices to variable and residual vectors, as well as Jacobians should be set in allocate function. That way we can preconfigure sparsity of the Jacobian to have favorable pattern for matrix factorization.
• Components owning mapping indices will allow us to remove local data copies in components and let components operate on system vectors and Jacobian.

Description

• Consider making function distributeVectors an internal method to component classes (and select better descriptive name for it). Upon allocation, each component should have a mapping vector with indices to the variable locations in global variable vector. Probably a good idea to have method updateVariables that would be called inside component's evaluateResidual and evaluateJacobian methods.
• Consider implementing separate methods to update internal component variables and coupling variables.
• Create separate component methods to update internal equations residuals and to add contributions to the coupling equations. Have each component own a mapping vector to the global residual vector.
• Change class name PowerElectronicsModel --> SystemModelPowerElectronics.

Additional information

Also, see #339.

CC @nkoukpaizan @PhilipFackler

[alexander-novo]

• Components have coupling variables tagged with values in extern_indices_, which is a std::set. It would give us more flexibility if components own arrays with mapping indices for internal and external (coupling) variables instead.
• There are no mapping vectors for component residual values.
• Have each component own a mapping vector to the global residual vector.

Can you expand on these? We currently have CircuitComponent::connection_nodes_, which is an array which maps from component state/residual indices to system indices.

[pelesh]

Can you expand on these? We currently have CircuitComponent::connection_nodes_, which is an array which maps from component state/residual indices to system indices.

Yes, you have all the ingredients in the code already. I would suggest separate mapping for internal variables $y$ and external (node) variables $w$. Similarly, have separate mapping for internal equation residuals $f(y,\dot y, w)$ and coupling equations residuals $h(y,w)$.

In power electronic case $w$ are node voltages and $h$ are residuals of the Kirchhoff current law.

[alexander-novo]

Great, this is exactly the direction I wanted to move in as well.

[alexander-novo]

• Change class name PowerElectronicsModel --> SystemModelPowerElectronics.

How do you feel about going down a similar route as PhasorDynamics and instead having PowerElectronics namespace and calling it PowerElectronics::SystemModel instead?

[alexander-novo]

Components owning mapping indices will allow us to remove local data copies in components and let components operate on system vectors and Jacobian.

I'm working on this right now. What do you think we should do about reference variables? For instance - the Rotor difference angle in the microgrid distributed generator.

[alexander-novo]

My next step is to remove copying from external variables, derivatives, and residuals.

My thought is to create a helper struct which contains a pointer to the appropriate system vector and the variable mapping that already exists. Then this mapping can start being only used for external variables and we apply it at access time, rather than when copying data.