Inverter.int

/***
 -------------------------------------------------------------------------------
 |                                                                             |
 | NASA Glenn Research Center                                                  |
 | 21000 Brookpark Rd 		                                                     |
 | Cleveland, OH 44135 	                                                       |
 |                                                                             |
 | File Name:     Inverter.int                                                 |
 | Author(s):     George Thomas, Jeffrey Csank, David Sadey, Tom Lavelle       |
 | Date(s):       March 2019	                                                 |
 |                                                                             |
 -------------------------------------------------------------------------------
***/

#ifndef __INVERTER__
#define __INVERTER__

#include "PSL_math.fnc"

class Inverter extends ElectricElement {
  
  //----------------------------
  // ****** DOCUMENTATION ******
  //----------------------------  
  
  // title = "";

  description = "The " + isA() + " represents the performance of a generic DC-to-AC converter. " +
  "This component is intended to run with an InverterRectifierMap subelement plugged into its " +
  "S_map socket that represents its losses.";

  usageNotes = isA() +
  "

- The input design parameters that must be specified by the modeler when creating an instance 
of this " + isA() + " component are mass specific power (SpecificPower) and design efficiency 
(eff). This component will transfer power from input to output, with losses according to its 
design efficiency. ONDESIGN, it calculates its mass (Mass) by dividing its ONDESIGN input power 
by its specific power.

- This component transforms power, from DC power at its input port, to AC output power. 
Because this component represents a transformation of power, it includes a node. Being a 
component including a node, its voltage is an indepedent variable. It also features a 
dependent that ensures that the electrical power at the input port, is sufficient to produce 
the output power demanded, plus the losses in this component (EP_I.S.r * eff == Pdemand).

- Also being a transformation component that involves AC power, this component features 
multiple independents and dependents. The independents, ind_Vreal and ind_Vimag give the 
solver the ability to vary the output voltage, such that the input/output power relationship, 
dep_Power is met (Pout_real == Pin_real * eff), a well as the output voltage phase 
relationship, dep_phase is met (Vout_phase == 0)

- Note that, as a component that contains a node and has its voltage known at the beginning
of the solverSequence, it uses its prePass() method to call the electrical port update 
function to pass this voltage information to electrical components that it is connected to. 
Note that in the current implementation of the NPSS Power System Library, these components 
containing nodes do not know what currents are going through their ports at the beginning of 
an iteration. Because of this, they must be connected to power transmission components (cables 
and breakers), and these transmission components must be run before node-bearing 
transformation components like this one, as the transmission components will calculate and 
populate these current values. Note that this design is intended to be analogous to a common 
approach taken in fluid networks within NPSS rocket models.

- This component, like other power system components in the NPSS Power System Library, can 
optionally include thermal models. An optional thermal model is enabled by setting 
switchThermPort to TRUE, and plugging an EThermalMass subelement into the S_eThermMass socket. 
Doing these will add a temperature state (existing within EThermalMass) and a thermal port to 
the model. The thermal port is intended to connect this component to a second component that 
represents the mechanism by which heat is extracted from this component. This second component 
could represent a heat exchanger, cold plate, or just model heat transfer from the first 
component to the surrounding environment. For more information, see EThermalMass.";

  //------------------------------
  // ****** SETUP VARIABLES ******
  //------------------------------
  
  ComplexNumber Sac;
  ComplexNumber Idc;
  ComplexNumber Iac;
  ComplexNumber Vac;
  ComplexNumber Vdc;
  
  eff {
    value = 1.0; IOstatus = "input"; units = "none";
    description = "Efficiency of the inverter.";
  }

  real effBase {
    value = 1.;  IOstatus = "output"; units = "none";
    description = "Converter efficiency.  Calculated and set by S_map socket during off design.";
  }

  real effDes {
    value = 1.;  IOstatus = "input"; units = "none";
    description = "Converter efficiency at design point.";
  }

  real pwrDes {
    value = 1.;  IOstatus = "input";  units = "kW"; // [kilowatts]
    description = "Input power at design.";
  }

  real pwrOut {
    value = 1.;  IOstatus = "output";  units = "kW"; // [kilowatts]
    description = "Output power.";
  }

  real pwrIn {
    value = 1.;  IOstatus = "output";  units = "kW"; // [kilowatts]
    description = "Input power.";
  }

  real Ro {
    value = 1.;  IOstatus = "output";  units = "ohm";
    description = "Output resistance.";
  }

  real Xo {
    value = 0.01;  IOstatus = "output";  units = "ohm";
    description = "Output reactance.";
  }

  // Set default frequency for an inverter.
  frequency = 400.;
  
  real SpecificPower {
    value = 13; IOstatus = "input"; units = "kW/kg"; // [kW / kg]
    description = "Power to weight ratio for the component.";
  }

  Mass {
    value = 1.; IOstatus = "output"; units = "kg"; // [kilograms]
    description = "Component mass.";
  }

  Loss_r {
    value = 0; IOstatus = "output"; units = "kW"; // [kilowatts]
    description = "Component loss.";
  }

  Loss_j {
    value = 0; IOstatus = "output"; units = "kW"; // [kilowatts]
    description = "Component loss.";
  }

  Q_heat {
    value = 0; IOstatus = "output"; units = "Btu/sec"; // [BTUs / sec]
    description = "Power dissipation at current time.";
  }
  
  ComplexNumber dV;
  ComplexNumber Z;

  //------------------------------------
  // ****** OPTION VARIABLE SETUP ******
  //------------------------------------

  Option switchDes {
    allowedValues = { "DESIGN", "OFFDESIGN" };
    description = "Determines if the element is in design or off-design mode.";
    rewritableValues = FALSE;
  }

  Option switchThermPort {
    allowedValues = { "TRUE", "FALSE" };
    description = "Determines if component needs thermal port.";
    rewritableValues = FALSE;  // enables converter optimization
    trigger = TRUE;
  }
  
  //----------------------------------------------------------
  // ****** SETUP PORTS, FLOW STATIONS, SOCKETS, TABLES ******
  //----------------------------------------------------------  

  /* ELECTRICAL PORTS */

  ElectricInputPort EP_I {
    description = "Electric input port.";
    ElectricPowerType.allowedValues = { "DC" };
    setOption("ElectricPowerType", "DC"); // only DC input allowed
  }

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

  /* SOCKETS */

  Socket S_map {
    allowedValues = { "effBase" }
    description = "Socket to calculate motor map performance.";
    socketType = "INVERTER_RECTIFIER_MAP";
  }

  Socket S_eThermMass {
    allowedValues = { "Q_heat", "Mass" }
    description = "Thermal mass socket.";
    socketType = "EThermalMass";
  }

  //-----------------------------------------------------
  // ******  ADD SOLVER INDEPENDENTS & DEPENDENTS  ******
  //-----------------------------------------------------

  Independent ind_Xo { 
    varName = "Xo"; 
    autoSetup = TRUE;
    indepRef = "10";
    description = "Varies the inverter output reactance (to get whatever output voltage phase needed).";
  }
  
  //------------------------------------------------------------
  // ******* VARIABLE CHANGED METHODOLOGY *******
  //------------------------------------------------------------

  void variableChanged(string name, any oldVal) {
    if (name == "switchThermPort") { 
      if (switchThermPort == "TRUE") {
        create("", "ThermalInputPort", "Q_I" );
      }
    }
  }
  
  //-----------------------------------------------
  // ****** PERFORM ENGINEERING CALCULATIONS ******
  //-----------------------------------------------
  
  void calculate() {

    // Run the map first with input power as the input param
    pwrIn = EP_I.S.r;
    
    if (switchDes == "DESIGN" ) {

      // handle case where guessed design power is zero.
      if (abs(pwrIn) < 1e-4) { pwrIn = 1e-4; }
      pwrDes = pwrIn;

      // compute mass based on assumed specific power
      // both mass and losses are based on output power (power sent)
      Mass = pwrIn / SpecificPower;
    }

    // set efficiency value
    if(!S_map.isEmpty()) {
      S_map.execute();
    } else {
      effBase = effDes;
    }
    eff = effBase;
            
    // Calculate this component's real output power
    real pwrOut = pwrIn * eff**sign(pwrIn);

    // Calculate ideal output voltage, VAC line-to-neutral
    ComplexNumber VoIdeal; VoIdeal.setMagPhase( EP_I.V.r/sqrt(2)/sqrt(3), 0);
    
    // Calculate current, AC line current = conj(S*1000/(numPhases*VoIdeal));
    ComplexNumber Io;
    if (EP_O.ElectricPowerType == "AC3") {
      Io.setrj( pwrOut*1000./3., 0.);
    }
    else {
      Io.setrj( pwrOut*1000., 0. );
    }
    Io.div("VoIdeal"); Io.conjugate();
  
    
    // dV = I * Z
    Z.setrj(0, Xo);
    dV.setrj(Io.r, Io.j);
    dV.times("Z");
    
    // Vo_ln = Vi_ln - dV_ln
    ComplexNumber Vo; Vo.copy("VoIdeal");
    Vo.minus("dV");

    if (EP_O.ElectricPowerType == "AC3") {
      // Convert this VLN we have calculated into a VLL (port expects VLL inputs)
      Vo.ln2ll();
    } // If not AC3, then we do not need to convert, because VLL = VLN
    
    // Send output quantities to next downstream component
    EP_O.frequency = frequency;
    EP_O.setIVRMS(Io.r, Io.j, Vo.r, Vo.j);
    
    Loss_r = EP_I.S.r - EP_O.S.r;
    Loss_j = EP_I.S.j - EP_O.S.j;

    real KW_PER_BTU_PER_SEC = 1.05505585;
    Q_heat = sqrt(Loss_r**2 + Loss_j**2);
    Q_heat /= KW_PER_BTU_PER_SEC;

    if (switchThermPort == "TRUE") {
      // run the thermal mass model.
      if ( !S_eThermMass.isEmpty() ) {
        S_eThermMass.execute();
      }
    }
  }
}
#endif