DC_DC_Converter.int

/***
 -------------------------------------------------------------------------------
 |                                                                             |
 | NASA Glenn Research Center                                                  |
 | 21000 Brookpark Rd 		                                                     |
 | Cleveland, OH 44135 	                                                       |
 |                                                                             |
 | File Name:     DC_DC_Converter.int										                       |
 | Author(s):     Jonathan Fuzaro Alencar                                      |
 | Date(s):       March 2019                                                   |
 |                                                                             |
 | Description:   Electrical DC to DC power converter.                         |
 |                                                                             |
 -------------------------------------------------------------------------------
***/

#ifndef __DC_DC_CONVERTER__
#define __DC_DC_CONVERTER__

#include "PSL_math.fnc"

class DC_DC_Converter extends ElectricElement {

  //----------------------------
  // ****** DOCUMENTATION ******
  //----------------------------

  // title = "";

  description = "The " + isA() + " represents the performance of a generic DC-to-DC 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. Output voltage is related to input voltage by a ratio, K, which represents 
the combined effect of the turns ratio of an integrated transformer (if it exists) as well as 
the duty cycle. ONDESIGN, it calculates its mass (Mass) by dividing its ONDESIGN input power 
by its specific power.

- This component transforms power, from electrical power at its input port, to useful output 
(load) 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). 

- This component also has logic that represents control functions. These are enabled by adding 
the independent, ind_control, which will vary the Vo/Vi voltage ratio, K. This independent 
is intended to be a 'control knob' must be matched to a dependent somewhere else in the system 
(in the case of a hybrid power system with two sources, the dependent could represent a 
constraint on power split, or could represent the designation of one source or another as a 
constant power vs a constant voltage 'slack' bus).

- 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 ******
  //------------------------------

  eff {
    value = 1.0; IOstatus = "input"; units = "none";
    description = "Efficiency of the converter.";
  }

  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"; // [kilowatt]
    description = "Input power at design.";
  }

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

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

  real Voltage {
    value = 1000.; IOstatus = "input"; units = "V"; // [voltage]
    description = "Converter voltage.";
  }

  real K {
    value = 2; IOstatus = "input"; units = "none";
    description = "Voltage ratio (V_in * K = V_out).";
  }

  real SpecificPower {
    value = 9; IOstatus = "input"; units = "none"; // [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 = "Generator loss.";
  }

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

  //------------------------------------
  // ****** 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 = { "FALSE", "TRUE" }
    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 = { "DC" };
    setOption("ElectricPowerType", "DC"); // only DC output allowed
  }

  /* SOCKETS */

  Socket S_map {
    allowedValues = { "effBase" }
    description = "Socket to calculate converter 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_control { 
    varName = "K"; 
    autoSetup = FALSE;
    indepRef = "1000";
    description = "Varies the relationship between input and output voltage (voltage ratio)";
  }
  
  void variableChanged(string name, any oldVal) {
    if (name == "switchThermPort") { 
      if (switchThermPort == "TRUE") {
        create("", "ThermalInputPort", "Q_I");
      }
    }
  }

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

  void calculate() {
    pwrIn = EP_I.S.rRMS;

    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 loses 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 power
    pwrOut = pwrIn * eff**sign(pwrIn);

    // Update output port power variables.
    real Vo = EP_I.I.r * K;
    real Io = 1000.*pwrOut / Vo;
    EP_O.setIVRMS(Io, 0, Vo, 0);

    Loss_r = EP_I.S.r - EP_O.S.r;

    real KW_PER_BTU_PER_SEC = 1.05505585;
    Q_heat = Loss_r / KW_PER_BTU_PER_SEC;

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