|
Harmony
HARMONic stabilitY assessment of PE-penetrated power systems
|
Modular Multilevel Converter with arm dynamics and control loops. More...
#include <MMC.h>


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. | |
| Bus * | getOtherBus (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 |
Modular Multilevel Converter with arm dynamics and control loops.
| 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.
| symbol | Element identifier. |
| location | Network area string encoding AC and DC areas. |
| omega | Nominal angular frequency (rad/s). |
| activePower | Active power setpoint (W). |
| reactivePower | Reactive power setpoint (VAR). |
| angle | AC voltage angle (rad). |
| acVoltage | AC voltage amplitude (V). |
| Pdc | DC power (W). |
| dcVoltage | DC bus voltage (V). |
| armInductance | Arm inductance (H). |
| armResistance | Arm resistance (Ω). |
| armCapacitance | Submodule capacitance (F). |
| numSubmodules | Number of submodules per arm. |
| reactorInductance | Phase reactor inductance (H). |
| reactorResistance | Phase reactor resistance (Ω). |
| timeDelay | Control time delay (s). |
| symbol | Element symbol/name. |
| omega | Nominal angular frequency (rad/s). |
| activePower | Active power (W). |
| reactivePower | Reactive power (VAR). |
| angle | Initial phase angle (rad). |
| acVoltage | AC voltage amplitude (V). |
| dcVoltage | DC voltage (V). |
| armInductance | Arm inductance (H). |
| armResistance | Arm resistance (Ohm). |
| armCapacitance | Arm capacitance (F). |
| numSubmodules | Number of submodules. |
| reactorInductance | Reactor inductance (H). |
| reactorResistance | Reactor resistance (Ohm). |
| timeDelay | Modulation 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::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.
| symbol | Element identifier. |
| location | Network area string encoding AC and DC areas. |
| converter_params | Packed converter parameters from init_MMC. |
| symbol | Element symbol/name. |
| converter_params | Vector 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::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.
| symbol | Element identifier. |
| location | Network area string encoding AC and DC areas. |
| converter_params | Packed converter parameters. |
| controller_params | Controller gain and setpoint parameters. |
| symbol | Element symbol/name. |
| converter_params | Vector of converter parameters. |
| controller_params | Vector of controller parameters. |
References init_Controller().
| 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.
| symbol | Element identifier. |
| location | Network area string encoding AC and DC areas. |
| converter_params | Packed converter parameters. |
| controller_params | Controller gain and setpoint parameters. |
| filter_params | Filter time-constant and gain parameters. |
| symbol | Element symbol/name. |
| converter_params | Vector of converter parameters. |
| controller_params | Vector of controller parameters. |
| filter_params | Vector of filter parameters. |
References init_Controller(), and init_Filter().
|
overridedefault |
|
overridevirtual |
Compute the numerical admittance (Y) parameters for the MMC.
| omega | Angular frequency (rad/s). |
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().
|
overridevirtual |
Numerically compute the Jacobian matrices A and B using finite differences.
| x0 | Operating point state vector. |
| u0 | Operating 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().
| void MMC::computeABCD_analytical | ( | ) |
computeABCD variant: exact plant block + numerical controller block
References Converter::A_matrix, Converter::B_matrix, Converter::C_matrix, computeJacobians(), computePlantJacobian(), computeStateDerivatives(), Converter::controls, Converter::D_matrix, Converter::equilibrium_state, makeOperatingInput(), Converter::omega_0, Converter::P_dc, Converter::theta, Converter::V_dc, and Converter::V_m.
Referenced by example_MMC().
| 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().
|
inlineoverridevirtual |
Compute branch power-flow quantities (override in derived classes).
| branchData | Output map of branch OPF results. |
| globalParams | Shared 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.
|
overridevirtual |
Compute the state derivatives for the MMC system.
| x | State vector. |
| u | Input 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().
|
inlineoverridevirtual |
Number of internal state variables for dynamic elements.
Reimplemented from Element.
|
inlineoverridevirtual |
Number of plant states exposed for simulation (may differ from internal states).
Reimplemented from Element.
|
overridevirtual |
Return parameter substitutions for symbolic evaluation.
Reimplemented from Element.
References Element::element_symbol.
|
overridevirtual |
Return symbolic names for virtual inputs used in stamping.
Reimplemented from Element.
References Element::element_symbol.
Referenced by writeMNAmatrix().
| void MMC::init_Controller | ( | const std::vector< double > & | controller_params | ) |
Initialize the controller(s) in MMC using provided parameters.
| controller_params | Vector of controller parameters. |
References Converter::controller_list, Converter::controls, Converter::pade_order, and Converter::t_delay.
| void MMC::init_Filter | ( | const std::vector< double > & | filter_params | ) |
Initialize the filter(s) in MMC using provided parameters.
| filter_params | Vector of filter parameters, conaining filter names and their parameters. |
| filter_list | List of filter name to initialize. |
| filter_size | Size of the filter (default is 1). Only used for AC voltage dq filter. |
| filter_order | Order 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().
|
overridevirtual |
Print MMC element and controller parameter values.
Reimplemented from Element.
References Converter::controls, Converter::L_reactor, Converter::omega_0, Converter::P, Converter::P_dc, Element::printElementInfo(), Controller::printValues(), Converter::Q, Converter::R_reactor, Converter::t_delay, Converter::V_dc, and Converter::V_m.
|
overridevirtual |
Simulate a step response given input states (override in dynamic elements).
| states | Input state trajectories per channel. |
| nKeep | Number of states to retain in the output. |
Reimplemented from Element.
References dq_multiply(), dqsym_initialized_, mD_dqsym_, mS_dqsym_, and truncateHarmonics().
|
overridevirtual |
Solve for the steady-state operating point x using Newton-Raphson.
Reimplemented from Converter.
References computeStateDerivatives(), Converter::controls, Converter::equilibrium_state, findEquilibriumRobust(), makeOperatingInput(), Converter::P, Converter::P_dc, Converter::Q, Converter::theta, Converter::V_dc, and Converter::V_m.
Referenced by example_MMC().
| void MMC::stepControllers | ( | double | dt, |
| const std::vector< Eigen::MatrixXcd > & | states, | ||
| const Eigen::Vector2d & | Vg_dq | ||
| ) |
References computeStateDerivatives(), Converter::controls, dqsym_initialized_, last_vMDelta_d_ref_, last_vMDelta_q_ref_, last_vMSigma_z_ref_, mD_dqsym_, mS_dqsym_, Converter::V_dc, and x_ctrl_dqsym_.
Referenced by DQsym::run().
| void MMC::update_MMC | ( | double | Vm, |
| double | theta, | ||
| double | Pac, | ||
| double | Qac, | ||
| double | Vdc, | ||
| double | Pdc | ||
| ) |
Update MMC operating point and controller references.
| Vm | AC voltage magnitude. |
| theta | AC voltage phase angle. |
| Pac | Active power. |
| Qac | Reactive power. |
| Vdc | DC voltage. |
| Pdc | DC power. |
References Converter::controls, Converter::P, Converter::P_dc, Converter::Q, Converter::theta, Converter::V_dc, and Converter::V_m.
|
overridevirtual |
Stamp this element into the symbolic MNA matrix (override in derived classes).
| mna | Global MNA matrix being assembled. |
| busIndexMap | Maps buses to global node indices. |
| offset | Current matrix offset for stamping. |
| elementSymbols | Per-element symbolic substitution table. |
Reimplemented from Element.
References addSym(), Element::connections, Element::element_symbol, and getVirtualInputSymbols().
| bool MMC::dqsym_initialized_ = false |
Referenced by simulateInputStep(), and stepControllers().
|
mutable |
Referenced by computeStateDerivatives(), and stepControllers().
|
mutable |
Referenced by computeStateDerivatives(), and stepControllers().
|
mutable |
Referenced by computeStateDerivatives().
|
mutable |
Referenced by computeStateDerivatives().
|
mutable |
Referenced by computeStateDerivatives(), and stepControllers().
| Eigen::MatrixXcd MMC::mD_dqsym_ |
Referenced by simulateInputStep(), and stepControllers().
| Eigen::MatrixXcd MMC::mS_dqsym_ |
Referenced by simulateInputStep(), and stepControllers().
| Eigen::VectorXd MMC::x_ctrl_dqsym_ |
Referenced by stepControllers().