Spec:NEVSolver

= Overview =

The NEV solver will utilize the current injection method outlined in [1]. The underlying algorithm is utilized in the existing Newton-Raphson (NR) solver inside GridLAB-D as TCIM-NR. The Neutral Earth Voltage (NEV) solver will use the same TCIM-NR approach, but will expand the solution to support more than three phases. superLU will continue to be the default LU decomposition solver for the NEV solver, but support for external LU solvers (such as KLU) will be incorporated in a manner similar to the existing Newton-Raphson solver.

= Process =

While the details of the algorithm are found in [1], the basic process for implementation within GridLAB-D will occur in the following steps:


 * 1) link objects will compute their static base admittance matrix contributions.  This occurs as part of the normal exec loop process, likely during presync calls.
 * 2) link objects will post their "off-block", "transfer admittance" diagonal matrix elements to the overall system admittance matrix, in Y_NEV format.  This will be the portions associated with the current transfers between nodes.
 * 3) link objects will post their "on-diagonal" block matrix components to the appropriate nodes "self-admittance" matrix.  This will be internal to the node objects.
 * 4) node objects will compute their admittance matrix contributions and deltaI vector contributions.  This will occur as part of the NEV solver call, executed by the SWING node(s) of the system.  This functionality will be initiated by the Y_update_fxn</tt> detailed in the node and data format specifications.
 * 5) node</tt> objects will use any fixed components from the link</tt> objects update to form the basis of the self admittance matrix.
 * 6) node</tt> objects will contribute any fixed, DELTAMODE</tt>-oriented contributions to the "self-admittance" matrix portions.
 * 7) node</tt> objects will perform the power calculations for all specific load contributions associated with that bus.
 * 8) node</tt> objects will perform the calculations associated with computing the deltaI</tt> components.
 * 9) Self admittance matrices will be utilized to compute base current values.
 * 10) Load currents calculated previously will be added to the base current values to compute deltaI</tt>.
 * 11) DELTAMODE</tt> contributions to deltaI</tt> will be accumulated.
 * 12) Formulate Jacobian A</tt>, B</tt>, C</tt>, and D</tt> matrices (from [1]).
 * 13) Apply current contributions of defined loads (ZIP portions)
 * 14) Apply current contributions from other devices (e.g., house_var</tt>)
 * 15) Update self admittance matrices with Jacobian <tt>A</tt>, <tt>B</tt>, <tt>C</tt>, and <tt>D</tt> components
 * 16) Format the input data to the LU solver (see functions below for current superLU-implemented functions).
 * 17) Form the larger admittance matrix to be passed to the LU solver method.
 * 18) Form the <tt>deltaI</tt> variable as the solution for the equations.
 * 19) Perform the LU decomposition to obtain the <tt>deltaV</tt> values
 * 20) <tt>node</tt> objects will perform "post-solution" updates via the <tt>NEVBUSDATA</tt>-mapped <tt>V_update_fxn</tt>.
 * 21) Voltage updates will be performed.
 * 22) Voltage convergence will be checked.
 * 23) <tt>DELTAMODE</tt>-related checks on the SWING bus role (SWING or PQ bus emulation) will be performed.
 * 24) Reiterate from step 2, as necessary until convergence or a convergence limit is reached.

= Solution Timing =

As with many items within GridLAB-D, timing of the various steps in the NEV solver process will be a key concern. Pieces of information must fully pass between dependent components before certain steps, such as the LU decomposition, can occur. Current implementations of GridLAB-D impose the following restriction on the dependency of steps above:


 * All admittance changes must be done and in the overall matrix format before the LU decomposition can occur.
 * All load contributions must be finalized before the nodal admittance contributions are computed.
 * All line contributions to nodal admittance portions must be finalized before the final nodal admittance contributions are computed.
 * Load contributions are typically included by other objects in sync or presync at this time.
 * Current and power calculations in individual objects will rely on the solved voltage values, so they must occur after the LU decomposition.

Based on these restrictions, the following execution order is proposed within the GridLAB-D framework. Note that the order of "intra-pass" operations will need to rely on object ranking or a similar mechanism to ensure operations occur in the proper order.


 * 1) Presync
 * 2) Link objects post admittance contributions to nodes and overall admittance matrix
 * 3) Sync
 * 4) All loads and interfacing objects have post their contributions.
 * 5) Childed objects post their contributions to the main, "electrically connected" parent.
 * 6) Island "membership" should be determined (if any change was on the system)
 * 7) Nodal contributions to the overall admittance matrix are computed and posted.
 * 8) LU decomposition and voltage update process occurs on all islands within the system (possibly multiple SWING bus objects).
 * 9) Post sync
 * 10) All "voltage-reliant" calculations (e.g., power, current) are computed and any control-related actions are decided

= Islanding/reconfiguration =

The NEV solver will include the capability to have multiple islanded systems within a single GLM, as well as support any "spontaneous islands" through reconfiguration and protective actions. Islands will be determined through the following criteria:


 * Connection to a source
 * SWING bus -- multiple SWINGs may exist
 * Distributed generation, especially in deltamode+. This will be determined with the <tt>HAS_SOURCE</tt> flag that already exists within <tt>node</tt> objects.
 * Pure support checks will be conducted via the <tt>fault_check</tt> object to see which objects have a connection to at least one source. This will require a slight modification to the connection determination inside ticket 767.
 * Unsupported objects will be placed into a state where they are excluded from current powerflow values. This will be indicated by a lack of information in the <tt>terminals</tt> field in NEVBUSDATA and <tt>terminals_from</tt> and <tt>terminals_to</tt> fields in the NEVBRANCHDATA structures.

+Note that while islands will solve individual powerflow sets, the current implementation of "failure to converge results in a failed simulation" will still apply to the whole system/set of system. i.e., if two islands are present and one fails to converge, the entire GridLAB-D instance will terminate, not just the divergent island. This condition is expected to be mitigated through object-level and user-level controls.

= Functions =

To implement the NEV solver in GridLAB-D, some support functions are required.

Merge Sort Function
Utilized in the existing NR-solver implementation, superLU requires the input matrices to be in a specific sparse matrix format known as COLAMD. In order to effectively place the data in this structure, it must be sorted by matrix location. The <tt>merge_sort</tt> function already implemented in <tt>solver_nr.cpp</tt> will be used for this function. It will continue to serve as the intermediate step between the "raw admittance" matrix and the COLAMD-formatted superLU-ready matrix.

Node functions
To compartmentalize the powerflow solution task and to enable easier parallelization, two new functions will be implemented at the <tt>node</tt>-object level. These will perform intermediate-solution updates for the powerflow process. This functionality was previously included in the <tt>solver_nr</tt> implementation.

Y_update_fxn
This function will perform any pre-LU-decomposition tasks. This is primarily the formation of the diagonal block portions of the admittance matrix and the "solution" vector containing the current injection components. A Boolean return flag will indicate if the operation completed successfully, or if an error occurred. Individual <tt>node</tt> objects will perform the following on every call of <tt>Y_update_fxn</tt>


 * 1) Add in any <tt>DELTAMODE</tt>-related self-admittance components.  These are typically associated with a shunt impedance of a Norton-equivalent circuit.
 * 2) Compute the "load power" as a current form for this bus.  This will be the net contributions of any load components at the bus.
 * 3) Compute the <tt>deltaI</tt> components for this bus.  This will include the load currents just computed, <tt>DELTAMODE</tt> generator contributions (<tt>DynCurrent</tt> values), and self-admittance matrix multiplications with voltage.
 * 4) Compute the Jacobian <tt>A</tt>, <tt>B</tt>, <tt>C</tt>, and <tt>D</tt> matrices (from [1]).  These are associated with the specific loading at the bus.  This is typically any ZIP components, as well as specific exogenous inputs (<tt>house_var</tt>, associated with "unrotated" current load from <tt>house</tt> objects).
 * 5) Combine the self-admittance portions and Jacobian <tt>A</tt>, <tt>B</tt>, <tt>C</tt>, and <tt>D</tt> matrices to form the final "diagonal block" portion of the admittance matrix.
 * 6) Convert the final "diagonal block" portions of the matrix into <tt>Y_NEV</tt> form for passing to the LU solver.
 * 7) Return <tt>true</tt> for a successful operation, <tt>false</tt> for a failure of the process.

V_update_fxn
This function will perform updates to the voltage values at a bus following a successful LU decomposition of the admittance-Jacobian and current injection different equations. Each individual bus will perform the following on every call of <tt>V_update_fxn</tt>:


 * 1) Apply <tt>deltaV</tt> updates associated with the LU decomposition solution.
 * 2) Check the "SWING" convergence condition if this is an initialization pass of <tt>DELTAMODE</tt>-enabled SWING bus with a generator attached.
 * 3) Check for convergence against the <tt>maximum_voltage_error</tt> field inside the <tt>node</tt> object.
 * 4) Return 0 for failed convergence, 1 for successful, and -1 for an error condition.

= References =


 * 1) Garcia, P, J.L. Pereira, S. Carneiro Jr., V. da Costa, and N. Martins, "Three-Phase Power Flow Calculations Using the Current Injection Method," IEEE Transactions on Power Systems, vol. 15, no. 2, May 2000, pp. 508-514.

= See also =


 * Overview Page
 * Requirements
 * Specifications
 * Implementation