Base class for multi-phase network elements with Y-parameters and MNA stamping hooks. More...

#include <Element.h>

Inheritance diagram for Element:

[legend]

Collaboration diagram for Element:

[legend]

Public Member Functions
	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).

virtual void	printElementValues ()
	Print extended element-specific values (override in derived classes).

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 void	plotEigenvalues ()
	Plot eigenvalues of the element model (override in state-space elements).

virtual void	plotParticipationFactors ()
	Plot participation factors (override in state-space elements).

virtual std::vector< std::vector< complex< double > > >	compute_y_parameters (double frequency)
	Compute complex Y-parameters at a single 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.

virtual void	writeMNAmatrix (SymEngine::DenseMatrix &, std::unordered_map< Bus , int > &, int, std::map< Element , std::vector< RCP< const Basic > > > &)
	Stamp this element into the symbolic MNA matrix (override in derived classes).

virtual int	getNumberOfInternalStates () const
	Number of internal state variables for dynamic elements.

virtual int	getNumberOfPlantStates () const
	Number of plant states exposed for simulation (may differ from internal states).

virtual std::vector< MatrixXcd >	simulateInputStep (const std::vector< MatrixXcd > &states, int nKeep) const
	Simulate a step response given input states (override in dynamic elements).

virtual std::vector< RCP< const Basic > >	getVirtualInputSymbols () const
	Return symbolic names for virtual inputs used in stamping.

virtual map_basic_basic	getParameterSubstitutions () const
	Return parameter substitutions for symbolic evaluation.

virtual void	computePowerFlow (std::map< std::string, double > &branchData, std::map< std::string, double > &globalParams) const
	Compute branch power-flow quantities (override in derived classes).

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.

Protected Attributes
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

Base class for multi-phase network elements with Y-parameters and MNA stamping hooks.

Derived classes implement frequency-domain admittance, symbolic MNA assembly, power-flow contributions, and optional state-space behavior. Bus connections are stored as non-owning terminal-to-bus mappings.

Constructor & Destructor Documentation

◆ Element()

Element::Element	(	const std::string &	symbol,
		const std::string &	location,
		int	inputPins,
		int	outputPins
	)

inline

Construct an element with symbol, location, and pin counts.

Initializes the internal Y-parameter matrix to zeros with dimensions (2 * inputPins) x (2 * outputPins).

Parameters

symbol	Component type symbol (e.g. "R", "L", "C").
location	Grid or partition label (e.g. "AC1", "DC2", "PEC1").
inputPins	Number of input pins/phases.
outputPins	Number of output pins/phases.

References createZeroMatrix(), and Y_matrix.

◆ ~Element()

Element::~Element ( )

virtual

Virtual destructor for derived-class cleanup.

Destructor for the Element class.

Member Function Documentation

◆ apply_transformation()

std::vector< std::vector< complex< double > > > Element::apply_transformation	(	std::vector< std::vector< complex< double > > > &	Y1,
		std::vector< std::vector< complex< double > > > &	Y2
	)

virtual

Apply a coordinate or coupling transformation to Y-parameter blocks.

Applies a transformation (e.g., abc to dq) to the admittance matrices.

Parameters

Y1	First Y-parameter block.
Y2	Second Y-parameter block.

Returns: Transformed Y-parameter matrix.

Parameters

Y1	The admittance matrix computed at angular frequency (omega - omega_0).
Y2	The admittance matrix computed at angular frequency (omega + omega_0).

Returns: The transformed 2D vector of complex numbers representing the Y-parameter matrix in the new frame.

References get_block(), j, mat_add(), mat_mul(), mat_transpose(), and mul_scalar().

Referenced by compute_y_parameters().

◆ attachBus()

void Element::attachBus	(	Bus *	bus,
		int	terminal
	)

Attach a bus to a specific element terminal.

Attaches a bus to a specific terminal of the element.

Parameters

bus	Non-owning bus pointer.
terminal	Terminal index (0-based).
bus	Pointer to the Bus object to attach.
terminal	The terminal number to which the bus is connected.

References connections.

Referenced by Network::connectElementToBus().

◆ compute_y_parameters()

std::vector< std::vector< complex< double > > > Element::compute_y_parameters ( double frequency )

virtual

Compute complex Y-parameters at a single frequency.

Computes the numerical Y-parameter matrix at a given frequency.

Default implementation returns an empty matrix; derived classes provide the frequency-dependent admittance.

Parameters

frequency Evaluation frequency in Hz.

Returns: Complex Y-parameter matrix as nested vectors.

Parameters

frequency The frequency in Hz for which to compute the Y-parameters.

Returns: A 2D vector of complex numbers representing the Y-parameter matrix.

Reimplemented in MMC, Cable, and Overhead_Line.

References apply_transformation(), element_location, j, omega, transformation, and Y_matrix.

Referenced by StabilityEstimate::compute_transfer_function(), example_admittance_parameters(), plotYParameters(), and writeFile().

◆ computePowerFlow()

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

inlinevirtual

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

Parameters

branchData	Output map of branch OPF results.
globalParams	Shared global OPF parameters.

Reimplemented in Transformer_base, Impedance_base, Load_base, RES_base, Source_base, LoadPQ, Load, and MMC.

Referenced by PowerFlow::make_BranchAC(), PowerFlow::make_BranchDC(), PowerFlow::make_Converter(), PowerFlow::make_Generator(), and PowerFlow::make_Load().

◆ get_y_parameters()

virtual DenseMatrix Element::get_y_parameters ( )

inlinevirtual

Get the symbolic or stored Y-parameter matrix.

Returns: SymEngine dense matrix representing Y-parameters.

References Y_matrix.

Referenced by WPplant::WPplant().

◆ getBuses()

std::vector< Bus * > Element::getBuses ( )

Collect all buses connected to this element.

Retrieves all buses connected to this element.

Returns: Vector of non-owning bus pointers from the connections map.; A vector of pointers to the connected Bus objects.

References connections.

Referenced by PowerFlow::make_BranchAC(), PowerFlow::make_BranchDC(), PowerFlow::make_Converter(), PowerFlow::make_Generator(), PowerFlow::make_Load(), PowerFlow::make_RES(), Resistor::writeMNAmatrix(), and Switch::writeMNAmatrix().

◆ getBusIndex()

int Element::getBusIndex ( Bus * bus )

inline

Find the terminal index associated with a given bus.

Parameters

bus	Bus pointer to look up.

Returns: Terminal index if connected; -1 if not found.

References connections.

◆ getConnections() [1/2]

std::map< Bus *, int > Element::getConnections ( )

inline

Copy of the bus-to-terminal connection map.

Returns: Map from bus pointer to terminal index.

References connections.

◆ getConnections() [2/2]

const std::map< Bus *, int > & Element::getConnections ( ) const

inline

Const access to the bus-to-terminal connection map.

Returns: Map from bus pointer to terminal index.

References connections.

Referenced by Network::add_areas(), StabilityEstimate::compute_transfer_function(), extendBusAC(), and DQsym::run().

◆ getElementLocation()

string Element::getElementLocation ( ) const

inline

Get the element's grid or partition location label.

Returns: Location string.

References element_location.

Referenced by Network::add_areas().

◆ getElementSymbol()

std::string Element::getElementSymbol ( ) const

inline

Get the element type symbol.

Returns: Symbol string (e.g. "R", "L", "C").

References element_symbol.

Referenced by Network::add_areas(), Network::addElement(), Network::connectElementToBus(), PowerFlow::make_BranchAC(), PowerFlow::make_BranchDC(), PowerFlow::make_Generator(), PowerFlow::make_OPF(), PowerFlow::make_RES(), printElementValues(), Capacitor::printElementValues(), Inductor::printElementValues(), Capacitor::writeMNAmatrix(), AC_source::writeMNAmatrix(), DC_source::writeMNAmatrix(), and Inductor::writeMNAmatrix().

◆ getInputPins()

int Element::getInputPins ( ) const

inline

Get the number of input pins/phases.

Returns: Input pin count.

References input_pins.

Referenced by Network::connectElementToBus(), and getStateCount().

◆ getNumberOfInternalStates()

virtual int Element::getNumberOfInternalStates ( ) const

inlinevirtual

Number of internal state variables for dynamic elements.

Returns: State count; zero for static linear elements.

Reimplemented in MMC.

Referenced by getNumberOfPlantStates().

◆ getNumberOfPlantStates()

virtual int Element::getNumberOfPlantStates ( ) const

inlinevirtual

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

Returns: Plant state count; defaults to getNumberOfInternalStates().

Reimplemented in MMC.

References getNumberOfInternalStates().

Referenced by getStateCount().

◆ getOPFInfo()

std::map< std::string, double > Element::getOPFInfo ( ) const

inline

Get stored OPF-related metadata for this element.

Returns: Map of OPF parameter names to values.

References element_OPF_info.

Referenced by PowerFlow::make_Generator().

◆ getOtherBus()

Bus * Element::getOtherBus ( Bus * bus )

Get the bus connected at the opposite terminal from a given bus.

Gets the other bus connected to the element, assuming it's a two-terminal element.

Parameters

bus	One connected bus.

Returns: The other connected bus, or nullptr if not applicable.

Parameters

bus	A pointer to one of the connected buses.

Returns: A pointer to the other connected bus, or nullptr if no other bus is found.

References connections.

◆ getOutputPins()

int Element::getOutputPins ( ) const

inline

Get the number of output pins/phases.

Returns: Output pin count.

References output_pins.

Referenced by Network::connectElementToBus().

◆ getParameterSubstitutions()

virtual map_basic_basic Element::getParameterSubstitutions ( ) const

inlinevirtual

Return parameter substitutions for symbolic evaluation.

Returns: Map from symbols to replacement expressions.

Reimplemented in MMC.

◆ getVirtualInputSymbols()

virtual std::vector< RCP< const Basic > > Element::getVirtualInputSymbols ( ) const

inlinevirtual

Return symbolic names for virtual inputs used in stamping.

Returns: List of SymEngine symbol RCPs; empty if none.

Reimplemented in MMC.

◆ plotEigenvalues()

virtual void Element::plotEigenvalues ( )

inlinevirtual

Plot eigenvalues of the element model (override in state-space elements).

Reimplemented in Converter.

◆ plotParticipationFactors()

virtual void Element::plotParticipationFactors ( )

inlinevirtual

Plot participation factors (override in state-space elements).

Reimplemented in Converter.

◆ plotYParameters()

void Element::plotYParameters	(	double	start_frequency,
		double	end_frequency,
		int	number_of_points
	)

Plot Y-parameter matrix entries versus frequency.

Generates data and triggers a Bode plot for the Y-parameter matrix.

Parameters

start_frequency	Lower bound of frequency range (Hz).
end_frequency	Upper bound of frequency range (Hz).
number_of_points	Number of frequency samples.
start_frequency	The starting frequency for the plot.
end_frequency	The ending frequency for the plot.
number_of_points	The number of points to plot across the frequency range.

References bode_plot_implot(), compute_y_parameters(), element_symbol, input_pins, j, output_pins, and Y_matrix.

Referenced by example_cable(), example_generator(), example_MMC(), example_OHL(), example_PV_plant(), example_stability_check(), example_visuals(), example_WT_type_3(), and example_WT_type_4().

◆ printElementInfo()

void Element::printElementInfo ( ) const

inline

Print basic element metadata (symbol, input/output pin counts).

References element_symbol, input_pins, and output_pins.

Referenced by MMC::printElementValues(), and AC_source::printElementValues().

◆ printElementValues()

void Element::printElementValues ( )

virtual

Print extended element-specific values (override in derived classes).

Prints the symbolic Y-parameter matrix of the element to the console.

Reimplemented in MMC, Capacitor, Inductor, Resistor, AC_source, Switch, and Cable.

References getElementSymbol(), j, and Y_matrix.

◆ setInputPins()

void Element::setInputPins ( int pins )

inline

Set the number of input pins/phases.

Parameters

pins	New input pin count.

References input_pins.

◆ setOPFInfo()

void Element::setOPFInfo ( std::map< std::string, double > & info )

inline

Store OPF-related metadata for this element.

Parameters

info	Map of OPF parameter names to values.

References element_OPF_info.

Referenced by example_OPF_double_area(), example_OPF_single_area(), example_point2point_case(), and example_stability_check().

◆ setOutputPins()

void Element::setOutputPins ( int pins )

inline

Set the number of output pins/phases.

Parameters

pins	New output pin count.

References output_pins.

◆ setTransformation()

void Element::setTransformation ( bool flag )

inline

Enable or disable coordinate transformation for this element.

Parameters

flag	True to apply transformation (e.g. three-phase to dq).

References transformation.

Referenced by example_admittance_parameters().

◆ simulateInputStep()

virtual std::vector< MatrixXcd > Element::simulateInputStep	(	const std::vector< MatrixXcd > &	states,
		int	nKeep
	)		const

inlinevirtual

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

Parameters

states	Input state trajectories per channel.
nKeep	Number of states to retain in the output.

Returns: Simulated state matrices; empty for static elements.

Reimplemented in MMC, AC_source, and DC_source.

◆ writeFile()

void Element::writeFile	(	double	start_frequency,
		double	end_frequency,
		int	number_of_points
	)

Write Y-parameter matrix samples over a frequency sweep to a file.

Writes the Y-parameter matrix to a CSV file over a specified frequency range.

Parameters

start_frequency	Lower bound of frequency range (Hz).
end_frequency	Upper bound of frequency range (Hz).
number_of_points	Number of frequency samples.
start_frequency	The starting frequency for the sweep.
end_frequency	The ending frequency for the sweep.
number_of_points	The number of frequency points to compute and write.

References compute_y_parameters(), element_symbol, j, and Y_matrix.

Referenced by example_cable(), example_constructors(), example_MMC(), example_OHL(), example_transformer(), example_visuals(), and example_WT_type_3().

◆ writeMNAmatrix()

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

inlinevirtual

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

Parameters

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 in MMC, Capacitor, Resistor, AC_source, DC_source, Switch, and Inductor.

Member Data Documentation

◆ connections

std::map<Bus* , int> Element::connections

protected

Referenced by attachBus(), getBuses(), getBusIndex(), getConnections(), getConnections(), getOtherBus(), MMC::writeMNAmatrix(), Capacitor::writeMNAmatrix(), Resistor::writeMNAmatrix(), AC_source::writeMNAmatrix(), DC_source::writeMNAmatrix(), and Inductor::writeMNAmatrix().

◆ element_location

std::string Element::element_location

protected

Referenced by compute_y_parameters(), TransmissionLine::computePowerFlow(), Transformer_base::computePowerFlow(), Impedance_base::computePowerFlow(), Load_base::computePowerFlow(), RES_base::computePowerFlow(), Source_base::computePowerFlow(), LoadPQ::computePowerFlow(), Load::computePowerFlow(), MMC::computePowerFlow(), Converter::getACarea(), Converter::getDCarea(), and getElementLocation().

◆ element_OPF_info

std::map<std::string, double> Element::element_OPF_info = {}

protected

Referenced by TransmissionLine::computePowerFlow(), Transformer_base::computePowerFlow(), Impedance_base::computePowerFlow(), Load_base::computePowerFlow(), Source_base::computePowerFlow(), MMC::computePowerFlow(), getOPFInfo(), and setOPFInfo().

◆ element_symbol

std::string Element::element_symbol

protected

Referenced by getElementSymbol(), MMC::getParameterSubstitutions(), MMC::getVirtualInputSymbols(), Converter::plotEigenvalues(), Converter::plotParticipationFactors(), plotYParameters(), printElementInfo(), Switch::printElementValues(), writeFile(), and MMC::writeMNAmatrix().

◆ input_pins

int Element::input_pins

protected

Referenced by Load::Load(), Overhead_Line::Overhead_Line(), getInputPins(), plotYParameters(), printElementInfo(), setInputPins(), DC_source::simulateInputStep(), Capacitor::writeMNAmatrix(), Resistor::writeMNAmatrix(), AC_source::writeMNAmatrix(), DC_source::writeMNAmatrix(), Switch::writeMNAmatrix(), and Inductor::writeMNAmatrix().

◆ output_pins

int Element::output_pins

protected

Referenced by Overhead_Line::Overhead_Line(), getOutputPins(), plotYParameters(), printElementInfo(), setOutputPins(), and Resistor::writeMNAmatrix().

◆ transformation

bool Element::transformation = false

protected

Referenced by compute_y_parameters(), and setTransformation().

◆ Y_matrix

DenseMatrix Element::Y_matrix

protected

Referenced by AC_source::AC_source(), AC_source::AC_source(), AC_source::AC_source(), Admittance::Admittance(), Cable::Cable(), Capacitor::Capacitor(), DC_source::DC_source(), DC_source::DC_source(), DC_source::DC_source(), DC_source::DC_source(), Element(), Generator::Generator(), Impedance::Impedance(), Impedance::Impedance(), Impedance::Impedance(), Impedance::Impedance(), Impedance::Impedance(), Inductor::Inductor(), Load::Load(), MMC::MMC(), MMC::MMC(), Overhead_Line::Overhead_Line(), PVplant::PVplant(), Resistor::Resistor(), Transformer_classic::Transformer_classic(), Transformer_real::Transformer_real(), TransformerDeltaDelta::TransformerDeltaDelta(), TransformerDeltaY::TransformerDeltaY(), TransformerDeltaY_real::TransformerDeltaY_real(), TransformerYDelta::TransformerYDelta(), TransmissionLine::TransmissionLine(), WPplant::WPplant(), WTtype3::WTtype3(), WTtype4::WTtype4(), compute_y_parameters(), MMC::compute_y_parameters(), TransmissionLine::computePowerFlow(), Transformer_base::computePowerFlow(), Impedance_base::computePowerFlow(), get_y_parameters(), plotYParameters(), printElementValues(), Capacitor::printElementValues(), Inductor::printElementValues(), Resistor::printElementValues(), and writeFile().

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

harmony/src/Elements/Element.h
harmony/src/Elements/Element.cpp

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Element()

◆ ~Element()

Member Function Documentation

◆ apply_transformation()

◆ attachBus()

◆ compute_y_parameters()

◆ computePowerFlow()

◆ get_y_parameters()

◆ getBuses()

◆ getBusIndex()

◆ getConnections() [1/2]

◆ getConnections() [2/2]

◆ getElementLocation()

◆ getElementSymbol()

◆ getInputPins()

◆ getNumberOfInternalStates()

◆ getNumberOfPlantStates()

◆ getOPFInfo()

◆ getOtherBus()

◆ getOutputPins()

◆ getParameterSubstitutions()

◆ getVirtualInputSymbols()

◆ plotEigenvalues()

◆ plotParticipationFactors()

◆ plotYParameters()

◆ printElementInfo()

◆ printElementValues()

◆ setInputPins()

◆ setOPFInfo()

◆ setOutputPins()

◆ setTransformation()

◆ simulateInputStep()

◆ writeFile()

◆ writeMNAmatrix()

Member Data Documentation

◆ connections

◆ element_location

◆ element_OPF_info

◆ element_symbol

◆ input_pins

◆ output_pins

◆ transformation

◆ Y_matrix