Generator.int

/***
 -------------------------------------------------------------------------------
 |                                                                             |
 | NASA Glenn Research Center                                                  |
 | 21000 Brookpark Rd 		                                                     |
 | Cleveland, OH 44135 	                                                       |
 |                                                                             |
 | File Name:     Generator.int											                           |
 | Author(s):     Jeffrey Csank, David Sadey, Tom Lavelle                      |
 | Date(s):       April 2018                                                   |
 |                                                                             |
 -------------------------------------------------------------------------------
***/

#ifndef __GENERATOR__
#define __GENERATOR__

#include "PSL_math.fnc"

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

  description = "The " + isA() + " represents the performance of a generic 3-phase generator. " +
  "The generator is intended to run with an efficiency map subelement, plugged into its S_map " +
  "socket.";

  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), design efficiency 
(effDes), frequency, and voltage (Vreal). This component will produce electrical power at 
the specified voltage and frequency, equal to the mechanical power at its shaft port. times 
its operating efficiency.

- When running ONDESIGN, this component will determine its design speed and design torque by 
saving off the values at the shaft port. The operating efficiency will be the effDes. when 
running OFFDESIGN, the model will call its S_map subelement (if it exists), to look up the 
efficiency at the current operating point. It will then run with that efficiency.

- This component, being a source component, must have its electricPowerType specified, and 
will propagate this power type information to components downstream of it when 
propagateEpsSolverListAndPowerTypes() is called. Further, being a generator, it is expected that the 
output power type is 3-phase AC, so this is the default value. Typically, this value does not 
need to be set manually. For more information, see ElectricPort.prt.

- This component transforms power, from mechanical power at its shaft port, to electrical 
output power. Because this component represents a transformation of power, it includes a node. 
Being a component including a node, a voltage must be specified at this component. However, 
being a source component, its voltage is typically set to a fixed value (unless the modeler 
changes it to be otherwise), and it does not need solver variables to operate.

- 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.

- The " + isA() + " component does not use solver variables, however it includes sizing logic. 
this logic calculates mass as well as calculates the design torque and speed values. These 
values are used by a performance map (if one is plugged into the S_map socket) to calculate 
efficiency at the current operating point. For more information about performance maps for 
this component, see MotorGeneratorMap.int";
  
  //------------------------------
  // ****** SETUP VARIABLES ******
  //------------------------------
  
  real Current {
    value = 1.; IOstatus = "input"; units = "A";
    description = "Current.";
  } 
  
  real CurrentAngle {
    value = 0; IOstatus = "input"; units = "deg";
    description = "Current angle.";
  }

  eff {
    value = 1.; IOstatus = "input"; units = "none";
    description = "Mechanical-to-electrical power conversion efficiency.  Equal to effDes during design, and effBase during off design.";
  }

  real effBase {
    value = 1.;  IOstatus = "output";  units = "none";
    description = "Mechanical-to-electrical power conversion efficiency.  Calculated and set by S_map socket during off design.";	
  }

  real effDes {
    value = 1.;  IOstatus = "input";  units = "none";
    description = "Mechanical-to-electrical power conversion efficiency at design point.";
  }

  real genResistance {
    value = 1; IOstatus = "input"; units = "kW";
    description = "Resistance of generator (based on efficiency).";
  }

  Loss_r {
    value = 0; IOstatus = "output"; units = "kW";
    description = "Generator loss.";
  }

  Loss_j {
    value = 0; IOstatus = "output"; units = "kW";
    description = "Generator loss.";
  }

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

  Mass {
    value = 1.; IOstatus = "output"; units = "kg";
    description = "Mass output of the generator.";
  }

  real Ndes {
    value = 1.;  IOstatus = "output";  units = "rpm";
    description = "Rotational speed at design.";
  }
  
  real Pout {
    value = 1.;  IOstatus = "output";  units = "kW";
    description = "Power out of the generator.";
  }

  real Pin {
    value = 1.;  IOstatus = "input";  units = "kW";
    description = "Power in to the generator.";
  }

  // Set default frequency for the generator.
  frequency = 400.;

  real SpecificPower {
    value = 13; IOstatus = "input"; units = "none"; // [kW / kg]
    description = "Power to weight ratio for the generator.";
  }

  real Speed {
    value = 1.;  IOstatus = "input";  units = "rpm";
    description = "Shaft/generator speed.";
  }

  real trq {
    value = 1.;  IOstatus = "output";  units = "ft*lbf";
    description = "Torque from shaft.";
  }

  real trqDes {
    value = 1.;  IOstatus = "output";  units = "ft*lbf";
    description = "Torque at design.";
  }

  real trqTemp {
    value = 1.;  IOstatus = "output";  units = "ft*lbf";
    description = "Temporary torque which the solver drives to match actual torque.";
  }
  
  real Vrms {
    value = 1000.;  IOstatus = "output";  units = "V"; // [volts]
    description = "RMS value of output line-to-line voltage.";
  }
  
  real Vphase {
    value = 30.;  IOstatus = "output";  units = "deg"; // [volts]
    description = "Phase angle of of output line-to-line voltage.";
  }
  
  real Ireal {
    value = 100; IOstatus = "input"; units = "A"; // [amps]
    description = "Guess value for real component of output current.";
  }

  real Iimag {
    value = 0; IOstatus = "input"; units = "A"; // [amps]
    description = "Guess value for imaginary component of output current.";
  }
  
  //------------------------------------
  // ****** 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 */

  ElectricOutputPort EP_O {
    description = "Electric output port.";
    ElectricPowerType.allowedValues = { "AC3" };
    setOption("ElectricPowerType", "AC3"); // only AC3 output allowed
  }
  
  /* MECHANICAL PORTS */
  
  ShaftOutputPort Sh_O {
    description = "Mechanical connection to the turbine.";
  }

  /* SOCKETS */

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

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

  //-----------------------------------------------------
  // ******  ADD SOLVER INDEPENDENTS & DEPENDENTS  ******
  //-----------------------------------------------------
  
  Independent ind_Ireal { 
    varName = "Ireal"; 
    autoSetup = TRUE;
    indepRef = "1000";
    description = "Varies the real component of this component's current.";
  }
  
  Independent ind_Iimag { 
    varName = "Iimag"; 
    autoSetup = TRUE;
    indepRef = "1000";
    description = "Varies the imaginary component of this component's current.";
  }

  //-------------------------------------------
  // ****** VARIABLE CHANGED METHODOLOGY ******
  //-------------------------------------------

  void variableChanged(string name, any oldVal) {
    if (name == "switchThermPort") { 
      if (switchThermPort == "TRUE") {
        create("", "ThermalInputPort", "Q_I");
      }
    }

    if (name == "switchDes") {} // do nothing
  }

  //-----------------------------------------------
  // ****** PERFORM ENGINEERING CALCULATIONS ******
  //-----------------------------------------------

  void calculate() {

    // Start by populating electric port with power data.
    EP_O.frequency = frequency;
    ComplexNumber Vo; Vo.setMagPhase( Vrms, Vphase * PI/180. );
    EP_O.setIVRMS(Ireal, Iimag, Vo.r, Vo.j);

    real powerfactor = EP_O.PF;
    Speed = Sh_O.Nmech;
    Pout = EP_O.S.r;
    Current = EP_O.I.mag;

    if (switchDes == "DESIGN") {

      eff = effDes;
    
      // compute power to the generator
      Pin = Pout / eff**sign(Pout);

      // get design values 
      Ndes = Sh_O.Nmech;
      trqDes = C_HP_PER_RPMtoFT_LBF * (Pin / 0.745699872) / Ndes;
      trqTemp = trqDes;
      trq = trqDes;
    
      // determine loss in the generator
      Loss_r = Pin - Pout;
      Loss_j = sqrt((Pin / powerfactor)**2 - Pin**2);
    
      // determine resistance 
      genResistance =  Loss_r / 3 / Current**2;
    
      // compute mass based on assumed specific power
      // both mass and losses are based on output power (power sent)
      Mass = Pout / SpecificPower;
    }

    // set efficiency value
    if(!S_map.isEmpty()) {
      S_map.execute();
    } else {
      effBase = effDes;
    }
    eff = effBase;

    if (switchDes == "OFFDESIGN") { 
      
      // supply power is load power + losses
      Pin = Pout / eff**sign(Pout);
      
      // determine loss in the generator
      Loss_r = 3 * Current**2 * genResistance;
      Loss_j = sqrt((Pin / powerfactor)**2 - Pin**2);
    }
    
    // generator / turbine engine shaft connection
    trq =  C_HP_PER_RPMtoFT_LBF * (Pin / 0.745699872) / Speed;
    Sh_O.trq = -trq;

    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