ElectricPort

Electric Port

The ElectricPort class is used by the components of the NPSS Power System Library communicate with each other. Nearly every component in the Power System Library will have at least one or more ports that is uses to transfer the physical attributes that have been defined or calculated (voltage, current, etc.) within it. This works in nearly the same fashion as the fluid and other type ports in the original NPSS framework.

The ElectricPort component is never used directly. Instead, components in the library will define only its child classes, ElectricInputPort and ElectricOutputPort. This is done for simplicity and to accord to standard NPSS conventions of separating input and output port components (although they are all functionally identical).

An additional consideration when connecting electrical components is ElectricPowerType. Each electric port declares its own ElectricPowerType NPSS Option variable that must either be set by the user when defining or automatically set by the findSourcesAndPropagate() function. Many components will have some or all of their port power types already set in their source files.

Usage

Electric ports are defined into all NPSS Power System Library electrical components. Thus, it is typically not required for a user to define their own electric ports. For a model to use the electric port, it must first include ElectricPort.prt and InterpretedPort.int in its source file.

#include "ElectricPort.prt"
#include "InterpretedPort.int"

Linking Ports

As shown in the Home page, once model components have been defined, a user may connect them to each other using the linkPortsI() (see InterpretedPort). This works almost identically to the linkPorts() method used for ports in the standard NPSS framework. All Power System Library electrical components will contain at least one electric port (input or output) to connect to.

The function header for linkPortsI() is:

void linkPortsI(string E1, string E2)

The naming convention used in the Power System Library follows that of the standard NPSS framework. ElectricInputPorts are named EP_I and ElectricOutputPorts are named EP_O. Components with more than one input or output port such as Enode will simply append a number like: EP_I1, EP_I2, EP_O1, EP_O2, etc. to the port names.

Simple DC Powertrain Example

Consider a DC Source (Battery) component Src with ElectricPort EP_O and Cable component C1 with ElectricInputPort EP_I and ElectricOutputPort EP_O. If we wish to connect the Sources output port with the Cables input port to form a connection, we use linkPortsI() like so:

linkPortsI("Src.EP_O", "C1.EP_I");

Following this, consider an Inverter component (Inv) with ElectricInputPort (EP_I) and ElectricOutputPort (EP_O). If we'd like to now connect the cable C1 to the inverter's input port, we add another line:

linkPortsI("C1.EP_O", "Inv.EP_I");

Finally, to add a Motor component (Mtr) to the Inverter component, another power transfer compnent like a Breaker component (B1) is required (see solver configuration in Home). If electric power types have also not been manually set, we may add findSourcesAndPropagate() to populate each component's port with the correct power type.

NOTE: The Src power type must be manually set because it is a Source component.

linkPortsI("Inv.EP_O", "B1.EP_I");
linkPortsI("B1.EP_O", "Mtr.EP_I");
findSourcesAndPropagate();

The model now looks like:

Src [DC] -> C1 [DC]-> Inv [AC3] -> B1 [AC3] -> Mtr ...

Creating Ports

The ElectricPort class extends the generic NPSS Subelement and may be defined like any other interpreted NPSS component. Here is an example of the output port found in Inverter.int.

ElectricOutputPort EP_O {
  description = "Electric output port.";
  ElectricPowerType.allowedValues = { "AC3" };
  setOption("ElectricPowerType", "AC3"); // only AC3 output allowed
}

Because the Inverter is a power converter component, only certain power types are presently allowed in its ports (in this case AC3 for output). A component that allows for more power types may change ElectricPowerType.allowedValues accordingly.

Nodal Component prePass()

Every Power System Library component which is defined as a nodal component (contains voltage independents) must define a prePass() function which adheres to the Power System Library solver requirements. The prePass() function sets the voltage and frequency values for the component's ports.

The function headers for setIVRMS() and its derivatives are:

void setIVRMS(real IrRMS, real IjRMS, real VrRMS, real VjRMS)
void setIVRMSphaseDeg(real ImagRMS, real Iangle, real VmagRMS, real Vangle) // polar (degrees)
void setIVRMSphaseRad(real ImagRMS, real Iangle, real VmagRMS, real Vangle) // polar (radians)

Setting the voltage values is done using the setIVRMS() function for each port (shown here for ports EP_O and EP_I). Here is an example of the prePass() function found in the Inverter component.

void prePass() {
  EP_O.frequency = frequency;
  EP_O.setIVRMS(EP_O.I.r, EP_O.I.j, Vreal, Vimag);
  EP_I.setIVRMS(EP_I.I.r, EP_I.I.j, EP_O.V.mag * sqrt(2), 0);
}

Because only nodal components implement their prePass() function, only their voltage values are propagated and their current values remain unknown or undefined. For this reason, a completed model must modify its solverSequence[] so that nodeless components (cables & breakers) are run before nodal components because they do define their current values. For example, in the baseline_all_elec.mdl model, the two cables are set to run before the rest of the power components:

solverSequence = {
  "A1", "A2",                   // Power transmission components (cables)
  "Converter", "Source", "Load" // Power components
};

Implementation

The source code for the ElectricPort class may be found in the ElectricPort.prt file. The ElectricPort class contains voltage V, current I, power S, and line to neutral voltage (VLN) values. Each is contained in a ComplexNumber class variable with internal calculations dependent on which ElectricPowerType has been set (DC, AC1, or AC3).

Calculations are performed to determine the correct power value (in kW) for the port power type when calling setIVRMS(). After the calculations have been performed, the port values are then pushed to the connected port (defined as refport).

For the DC and AC1 power types, V is taken to mean the line voltage and I is taken to mean the line current (or phase current). For the DC power type, power is calculated as the product of voltage V and current I i.e. S = P = V * I. For the AC1 power type, (complex) power is calculated as the product of the voltage V (VLL) and the complex conjugate of the current phasor (I.conjugate()) i.e. S = V * conj(I).

For the AC3 power type V is take as the line to line voltage (VLL) so line to neutral VLN voltage is used to calculate (complex) power as the product of three times the VLN and complex conjugate of the line current (I) i.e. S = 3 * VLN * conj(I_line).

NOTE: For DC and AC1 power types, VLN is considered the same as V.

The implementation of linkPortsI() may be found in InterpretedPort.int and more information may be found in Interpreted Port.