Harmony
HARMONic stabilitY assessment of PE-penetrated power systems
Loading...
Searching...
No Matches
MMC Class Reference

Modular Multilevel Converter with arm dynamics and control loops. More...

#include <MMC.h>

Inheritance diagram for MMC:
Collaboration diagram for MMC:

Public Member Functions

 MMC (const std::string &symbol, const std::string &location, double omega, double activePower, double reactivePower, double angle, double acVoltage, double Pdc, double dcVoltage, double armInductance, double armResistance, double armCapacitance, int numSubmodules, double reactorInductance, double reactorResistance, double timeDelay)
 Construct an MMC from individual scalar parameters.
 
 MMC (const std::string &symbol, const std::string &location, const std::vector< double > &converter_params)
 Construct an MMC from a converter parameter vector.
 
 MMC (const std::string &symbol, const std::string &location, const std::vector< double > &converter_params, const std::vector< double > &controller_params)
 Construct an MMC with converter and controller parameters.
 
 MMC (const std::string &symbol, const std::string &location, const std::vector< double > &converter_params, const std::vector< double > &controller_params, const std::vector< double > &filter_params)
 Construct an MMC with converter, controller, and filter parameters.
 
void init_Controller (const std::vector< double > &converter_params)
 Initialize the controller(s) in MMC using provided parameters.
 
void init_Filter (const std::vector< double > &converter_params)
 Initialize the filter(s) in MMC using provided parameters.
 
void update_MMC (double Vm, double theta, double Pac, double Qac, double Vdc, double Pdc)
 Update MMC operating point and controller references.
 
 ~MMC () override=default
 
virtual void solveEquilibrium () override
 Solve for the steady-state operating point x using Newton-Raphson.
 
virtual Eigen::MatrixXd computeStateDerivatives (const Eigen::VectorXd &x, const Eigen::VectorXd &u) override
 Compute the state derivatives for the MMC system.
 
virtual void computeABCD () override
 Numerically compute the Jacobian matrices A and B using finite differences.
 
Eigen::MatrixXd computePlantJacobian (double w, double mDd, double mDq, double mDZd, double mDZq, double mSd, double mSq, double mSz) const
 Exact 12×12 plant Jacobian (modulation treated as fixed parameters)
 
void computeABCD_analytical ()
 computeABCD variant: exact plant block + numerical controller block
 
std::vector< std::vector< complex< double > > > compute_y_parameters (double frequency) override
 Compute the numerical admittance (Y) parameters for the MMC.
 
virtual void printElementValues () override
 Print MMC element and controller parameter values.
 
void computePowerFlow (std::map< std::string, double > &data, std::map< std::string, double > &globalParams) const override
 Compute branch power-flow quantities (override in derived classes).
 
void writeMNAmatrix (SymEngine::DenseMatrix &, std::unordered_map< Bus *, int > &, int, std::map< Element *, std::vector< RCP< const Basic > > > &) override
 Stamp this element into the symbolic MNA matrix (override in derived classes).
 
std::vector< RCP< const Basic > > getVirtualInputSymbols () const override
 Return symbolic names for virtual inputs used in stamping.
 
std::vector< MatrixXcd > simulateInputStep (const std::vector< MatrixXcd > &states, int nKeep) const override
 Simulate a step response given input states (override in dynamic elements).
 
int getNumberOfInternalStates () const override
 Number of internal state variables for dynamic elements.
 
int getNumberOfPlantStates () const override
 Number of plant states exposed for simulation (may differ from internal states).
 
void stepControllers (double dt, const std::vector< Eigen::MatrixXcd > &states, const Eigen::Vector2d &Vg_dq)
 
map_basic_basic getParameterSubstitutions () const override
 Return parameter substitutions for symbolic evaluation.
 
- Public Member Functions inherited from Converter
 Converter (const std::string &symbol, const std::string &location)
 Construct a three-phase, two-terminal converter element.
 
virtual ~Converter ()
 
Eigen::MatrixXd getA () const
 
Eigen::MatrixXd getB () const
 
Eigen::MatrixXd getC () const
 
Eigen::MatrixXd getD () const
 
Eigen::MatrixXd getAd () const
 
Eigen::MatrixXd getBd () const
 
Eigen::MatrixXd getCd () const
 
Eigen::MatrixXd getDd () const
 
Eigen::VectorXd getEquilibriumState () const
 
VectorXcd getEigenvalues ()
 
VectorXcd getEigenvectors ()
 
string getACarea () const
 
string getDCarea () const
 
virtual void discretize (double Ts)
 
void computeEigenvalues ()
 
Eigen::MatrixXd computeParticipationFactors (const Eigen::MatrixXd &A_matrix)
 
virtual vector< MatrixXcd > simulateTimeStep (const vector< MatrixXcd > &input, double Ts, int nKeep1, int nKeep2)
 
void checkStability () const
 Check system stability by evaluating eigenvalues of the A matrix.
 
void printEigenvalues () const
 Print eigenvalues of the A matrix.
 
virtual void plotEigenvalues () override
 Plot eigenvalues in the complex plane.
 
virtual void plotParticipationFactors () override
 Plot participation factors (override in state-space elements).
 
- Public Member Functions inherited from Element
 Element (const std::string &symbol, const std::string &location, int inputPins, int outputPins)
 Construct an element with symbol, location, and pin counts.
 
virtual ~Element ()
 Virtual destructor for derived-class cleanup.
 
int getInputPins () const
 Get the number of input pins/phases.
 
int getOutputPins () const
 Get the number of output pins/phases.
 
void setInputPins (int pins)
 Set the number of input pins/phases.
 
void setOutputPins (int pins)
 Set the number of output pins/phases.
 
void setTransformation (bool flag)
 Enable or disable coordinate transformation for this element.
 
std::string getElementSymbol () const
 Get the element type symbol.
 
std::vector< Bus * > getBuses ()
 Collect all buses connected to this element.
 
int getBusIndex (Bus *bus)
 Find the terminal index associated with a given bus.
 
BusgetOtherBus (Bus *)
 Get the bus connected at the opposite terminal from a given bus.
 
const std::map< Bus *, int > & getConnections () const
 Const access to the bus-to-terminal connection map.
 
std::map< Bus *, int > getConnections ()
 Copy of the bus-to-terminal connection map.
 
string getElementLocation () const
 Get the element's grid or partition location label.
 
void attachBus (Bus *, int)
 Attach a bus to a specific element terminal.
 
void printElementInfo () const
 Print basic element metadata (symbol, input/output pin counts).
 
void writeFile (double start_frequency, double end_frequency, int number_of_points)
 Write Y-parameter matrix samples over a frequency sweep to a file.
 
void plotYParameters (double start_frequency, double end_frequency, int number_of_points)
 Plot Y-parameter matrix entries versus frequency.
 
virtual DenseMatrix get_y_parameters ()
 Get the symbolic or stored Y-parameter matrix.
 
virtual std::vector< std::vector< complex< double > > > apply_transformation (std::vector< std::vector< complex< double > > > &Y1, std::vector< std::vector< complex< double > > > &Y2)
 Apply a coordinate or coupling transformation to Y-parameter blocks.
 
std::map< std::string, double > getOPFInfo () const
 Get stored OPF-related metadata for this element.
 
void setOPFInfo (std::map< std::string, double > &info)
 Store OPF-related metadata for this element.
 

Public Attributes

Eigen::VectorXd x_ctrl_dqsym_
 
Eigen::MatrixXcd mD_dqsym_
 
Eigen::MatrixXcd mS_dqsym_
 
bool dqsym_initialized_ = false
 
double last_vMDelta_d_ref_ = 0.0
 
double last_vMDelta_q_ref_ = 0.0
 
double last_vMSigma_d_ref_ = 0.0
 
double last_vMSigma_q_ref_ = 0.0
 
double last_vMSigma_z_ref_ = 0.0
 

Additional Inherited Members

- Protected Attributes inherited from Converter
double omega_0
 
double P
 
double Q
 
double P_dc
 
double P_min
 
double P_max
 
double Q_min
 
double Q_max
 
double theta
 
double V_m
 
double V_dc
 
double L_reactor
 
double R_reactor
 
double t_delay
 
MatrixXd A_matrix
 
MatrixXd B_matrix
 
MatrixXd C_matrix
 
MatrixXd D_matrix
 
MatrixXd Adelay
 
MatrixXd Bdelay
 
MatrixXd Cdelay
 
MatrixXd Ddelay
 
MatrixXd Ad_matrix
 
MatrixXd Bd_matrix
 
MatrixXd Cd_matrix
 
MatrixXd Dd_matrix
 
int pade_order = 2
 
VectorXd equilibrium_state
 
VectorXcd eigenvalues
 
VectorXcd eigenvectors
 
VectorXcd initial_state
 
std::map< std::string, Controller * > controls
 
std::map< std::string, Filter * > filters
 
const std::vector< std::string > controller_list
 
const std::vector< std::string > filter_list
 
- Protected Attributes inherited from Element
bool transformation = false
 
std::string element_symbol
 
std::string element_location
 
int input_pins
 
int output_pins
 
std::map< Bus *, int > connections
 
std::map< std::string, double > element_OPF_info = {}
 
DenseMatrix Y_matrix
 

Detailed Description

Modular Multilevel Converter with arm dynamics and control loops.

Constructor & Destructor Documentation

◆ MMC() [1/4]

MMC::MMC ( const std::string &  symbol,
const std::string &  location,
double  omega,
double  activePower,
double  reactivePower,
double  angle,
double  acVoltage,
double  Pdc,
double  dcVoltage,
double  armInductance,
double  armResistance,
double  armCapacitance,
int  numSubmodules,
double  reactorInductance,
double  reactorResistance,
double  timeDelay 
)

Construct an MMC from individual scalar parameters.

MMC constructor with explicit parameters.

Parameters
symbolElement identifier.
locationNetwork area string encoding AC and DC areas.
omegaNominal angular frequency (rad/s).
activePowerActive power setpoint (W).
reactivePowerReactive power setpoint (VAR).
angleAC voltage angle (rad).
acVoltageAC voltage amplitude (V).
PdcDC power (W).
dcVoltageDC bus voltage (V).
armInductanceArm inductance (H).
armResistanceArm resistance (Ω).
armCapacitanceSubmodule capacitance (F).
numSubmodulesNumber of submodules per arm.
reactorInductancePhase reactor inductance (H).
reactorResistancePhase reactor resistance (Ω).
timeDelayControl time delay (s).
symbolElement symbol/name.
omegaNominal angular frequency (rad/s).
activePowerActive power (W).
reactivePowerReactive power (VAR).
angleInitial phase angle (rad).
acVoltageAC voltage amplitude (V).
dcVoltageDC voltage (V).
armInductanceArm inductance (H).
armResistanceArm resistance (Ohm).
armCapacitanceArm capacitance (F).
numSubmodulesNumber of submodules.
reactorInductanceReactor inductance (H).
reactorResistanceReactor resistance (Ohm).
timeDelayModulation time delay (s).

References Converter::A_matrix, Converter::Adelay, Converter::B_matrix, Converter::Bdelay, Converter::C_matrix, Converter::Cdelay, Converter::D_matrix, Converter::Ddelay, Converter::L_reactor, omega, Converter::omega_0, Converter::P, Converter::P_dc, Converter::P_max, Converter::P_min, Converter::pade_order, padeDelaySystemMulti2(), padeDelaySystemMulti3(), Converter::Q, Converter::Q_max, Converter::Q_min, Converter::R_reactor, Converter::t_delay, Converter::theta, Converter::V_dc, Converter::V_m, and Element::Y_matrix.

◆ MMC() [2/4]

MMC::MMC ( const std::string &  symbol,
const std::string &  location,
const std::vector< double > &  converter_params 
)

Construct an MMC from a converter parameter vector.

MMC constructor with converter parameter vector.

Parameters
symbolElement identifier.
locationNetwork area string encoding AC and DC areas.
converter_paramsPacked converter parameters from init_MMC.
symbolElement symbol/name.
converter_paramsVector of converter parameters.

References Converter::A_matrix, Converter::Adelay, Converter::B_matrix, Converter::Bdelay, Converter::C_matrix, Converter::Cdelay, Converter::D_matrix, Converter::Ddelay, Converter::equilibrium_state, Converter::L_reactor, Converter::omega_0, Converter::P, Converter::P_dc, Converter::P_max, Converter::P_min, Converter::pade_order, padeDelaySystemMulti2(), padeDelaySystemMulti3(), Converter::Q, Converter::Q_max, Converter::Q_min, Converter::R_reactor, Converter::t_delay, Converter::theta, Converter::V_dc, Converter::V_m, and Element::Y_matrix.

◆ MMC() [3/4]

MMC::MMC ( const std::string &  symbol,
const std::string &  location,
const std::vector< double > &  converter_params,
const std::vector< double > &  controller_params 
)

Construct an MMC with converter and controller parameters.

MMC constructor with converter and controller parameter vectors.

Parameters
symbolElement identifier.
locationNetwork area string encoding AC and DC areas.
converter_paramsPacked converter parameters.
controller_paramsController gain and setpoint parameters.
symbolElement symbol/name.
converter_paramsVector of converter parameters.
controller_paramsVector of controller parameters.

References init_Controller().

◆ MMC() [4/4]

MMC::MMC ( const std::string &  symbol,
const std::string &  location,
const std::vector< double > &  converter_params,
const std::vector< double > &  controller_params,
const std::vector< double > &  filter_params 
)

Construct an MMC with converter, controller, and filter parameters.

MMC constructor with converter, controller, and filter parameter vectors.

Parameters
symbolElement identifier.
locationNetwork area string encoding AC and DC areas.
converter_paramsPacked converter parameters.
controller_paramsController gain and setpoint parameters.
filter_paramsFilter time-constant and gain parameters.
symbolElement symbol/name.
converter_paramsVector of converter parameters.
controller_paramsVector of controller parameters.
filter_paramsVector of filter parameters.

References init_Controller(), and init_Filter().

◆ ~MMC()

MMC::~MMC ( )
overridedefault

Member Function Documentation

◆ compute_y_parameters()

std::vector< std::vector< complex< double > > > MMC::compute_y_parameters ( double  frequency)
overridevirtual

Compute the numerical admittance (Y) parameters for the MMC.

Parameters
omegaAngular frequency (rad/s).
Returns
Eigen::MatrixXcd Admittance matrix.

Reimplemented from Element.

References Converter::A_matrix, Converter::B_matrix, Converter::C_matrix, Converter::controls, Converter::D_matrix, j, and Element::Y_matrix.

Referenced by example_MMC(), and example_stability_check().

◆ computeABCD()

void MMC::computeABCD ( )
overridevirtual

Numerically compute the Jacobian matrices A and B using finite differences.

Parameters
x0Operating point state vector.
u0Operating point input vector.

Reimplemented from Converter.

References Converter::A_matrix, Converter::B_matrix, Converter::C_matrix, computeJacobians(), computeStateDerivatives(), Converter::controls, Converter::D_matrix, Converter::equilibrium_state, makeOperatingInput(), Converter::P_dc, Converter::theta, Converter::V_dc, and Converter::V_m.

Referenced by example_MMC().

◆ computeABCD_analytical()

◆ computePlantJacobian()

Eigen::MatrixXd MMC::computePlantJacobian ( double  w,
double  mDd,
double  mDq,
double  mDZd,
double  mDZq,
double  mSd,
double  mSq,
double  mSz 
) const

Exact 12×12 plant Jacobian (modulation treated as fixed parameters)

References Converter::L_reactor, and Converter::R_reactor.

Referenced by computeABCD_analytical().

◆ computePowerFlow()

void MMC::computePowerFlow ( std::map< std::string, double > &  branchData,
std::map< std::string, double > &  globalParams 
) const
inlineoverridevirtual

Compute branch power-flow quantities (override in derived classes).

Parameters
branchDataOutput map of branch OPF results.
globalParamsShared global OPF parameters.

Reimplemented from Element.

References Converter::controls, Element::element_location, Element::element_OPF_info, Converter::L_reactor, Converter::P, Converter::Q, Converter::R_reactor, and Converter::V_dc.

◆ computeStateDerivatives()

MatrixXd MMC::computeStateDerivatives ( const Eigen::VectorXd &  x,
const Eigen::VectorXd &  u 
)
overridevirtual

Compute the state derivatives for the MMC system.

Parameters
xState vector.
uInput vector.
Returns
MatrixXd State derivatives vector.

The state vector ordering is described at the top of this file. Controller, filter, PLL, and delay states are prepended to the main MMC states.

Reimplemented from Converter.

References Converter::Adelay, Converter::Bdelay, Converter::Cdelay, Converter::controls, Converter::Ddelay, Converter::filters, j, Converter::L_reactor, last_vMDelta_d_ref_, last_vMDelta_q_ref_, last_vMSigma_d_ref_, last_vMSigma_q_ref_, last_vMSigma_z_ref_, Converter::omega_0, Converter::pade_order, Converter::R_reactor, Converter::t_delay, Converter::theta, and Converter::V_dc.

Referenced by computeABCD(), computeABCD_analytical(), solveEquilibrium(), and stepControllers().

◆ getNumberOfInternalStates()

int MMC::getNumberOfInternalStates ( ) const
inlineoverridevirtual

Number of internal state variables for dynamic elements.

Returns
State count; zero for static linear elements.

Reimplemented from Element.

◆ getNumberOfPlantStates()

int MMC::getNumberOfPlantStates ( ) const
inlineoverridevirtual

Number of plant states exposed for simulation (may differ from internal states).

Returns
Plant state count; defaults to getNumberOfInternalStates().

Reimplemented from Element.

◆ getParameterSubstitutions()

map_basic_basic MMC::getParameterSubstitutions ( ) const
overridevirtual

Return parameter substitutions for symbolic evaluation.

Returns
Map from symbols to replacement expressions.

Reimplemented from Element.

References Element::element_symbol.

◆ getVirtualInputSymbols()

std::vector< RCP< const Basic > > MMC::getVirtualInputSymbols ( ) const
overridevirtual

Return symbolic names for virtual inputs used in stamping.

Returns
List of SymEngine symbol RCPs; empty if none.

Reimplemented from Element.

References Element::element_symbol.

Referenced by writeMNAmatrix().

◆ init_Controller()

void MMC::init_Controller ( const std::vector< double > &  controller_params)

Initialize the controller(s) in MMC using provided parameters.

Parameters
controller_paramsVector of controller parameters.

References Converter::controller_list, Converter::controls, Converter::pade_order, and Converter::t_delay.

Referenced by MMC(), and MMC().

◆ init_Filter()

void MMC::init_Filter ( const std::vector< double > &  filter_params)

Initialize the filter(s) in MMC using provided parameters.

Parameters
filter_paramsVector of filter parameters, conaining filter names and their parameters.
filter_listList of filter name to initialize.
filter_sizeSize of the filter (default is 1). Only used for AC voltage dq filter.
filter_orderOrder of the filter (default is 2). Only used for AC voltage dq filter.

filter_params should contain the following structure: 0 if the filer is not used, 1 if the filter is used, followed by the filter parameters (3 double values for each filter, representing Kp, Ki, and T). For the first order fiter, only T is used, and Kp and Ki are set to 0 in the main.cpp.

References Converter::filter_list, and Converter::filters.

Referenced by MMC().

◆ printElementValues()

void MMC::printElementValues ( )
overridevirtual

◆ simulateInputStep()

std::vector< MatrixXcd > MMC::simulateInputStep ( const std::vector< MatrixXcd > &  states,
int  nKeep 
) const
overridevirtual

Simulate a step response given input states (override in dynamic elements).

Parameters
statesInput state trajectories per channel.
nKeepNumber of states to retain in the output.
Returns
Simulated state matrices; empty for static elements.

Reimplemented from Element.

References dq_multiply(), dqsym_initialized_, mD_dqsym_, mS_dqsym_, and truncateHarmonics().

◆ solveEquilibrium()

void MMC::solveEquilibrium ( )
overridevirtual

◆ stepControllers()

void MMC::stepControllers ( double  dt,
const std::vector< Eigen::MatrixXcd > &  states,
const Eigen::Vector2d &  Vg_dq 
)

◆ update_MMC()

void MMC::update_MMC ( double  Vm,
double  theta,
double  Pac,
double  Qac,
double  Vdc,
double  Pdc 
)

Update MMC operating point and controller references.

Parameters
VmAC voltage magnitude.
thetaAC voltage phase angle.
PacActive power.
QacReactive power.
VdcDC voltage.
PdcDC power.

References Converter::controls, Converter::P, Converter::P_dc, Converter::Q, Converter::theta, Converter::V_dc, and Converter::V_m.

◆ writeMNAmatrix()

void MMC::writeMNAmatrix ( SymEngine::DenseMatrix &  ,
std::unordered_map< Bus *, int > &  ,
int  ,
std::map< Element *, std::vector< RCP< const Basic > > > &   
)
overridevirtual

Stamp this element into the symbolic MNA matrix (override in derived classes).

Parameters
mnaGlobal MNA matrix being assembled.
busIndexMapMaps buses to global node indices.
offsetCurrent matrix offset for stamping.
elementSymbolsPer-element symbolic substitution table.

Reimplemented from Element.

References addSym(), Element::connections, Element::element_symbol, and getVirtualInputSymbols().

Member Data Documentation

◆ dqsym_initialized_

bool MMC::dqsym_initialized_ = false

◆ last_vMDelta_d_ref_

double MMC::last_vMDelta_d_ref_ = 0.0
mutable

◆ last_vMDelta_q_ref_

double MMC::last_vMDelta_q_ref_ = 0.0
mutable

◆ last_vMSigma_d_ref_

double MMC::last_vMSigma_d_ref_ = 0.0
mutable

Referenced by computeStateDerivatives().

◆ last_vMSigma_q_ref_

double MMC::last_vMSigma_q_ref_ = 0.0
mutable

Referenced by computeStateDerivatives().

◆ last_vMSigma_z_ref_

double MMC::last_vMSigma_z_ref_ = 0.0
mutable

◆ mD_dqsym_

Eigen::MatrixXcd MMC::mD_dqsym_

◆ mS_dqsym_

Eigen::MatrixXcd MMC::mS_dqsym_

◆ x_ctrl_dqsym_

Eigen::VectorXd MMC::x_ctrl_dqsym_

Referenced by stepControllers().


The documentation for this class was generated from the following files: