Stability_certificate.h File Reference

Device-level passivity / phase / geometric metrics and plots. More...

#include "../../Constants.h"
#include "../Helper_Functions/Visualization.h"
#include "Certificate_spec.h"
#include "Geometric_certificates.h"
#include <complex>
#include <string>
#include <vector>

Include dependency graph for Stability_certificate.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	CertificateSweep
	Frequency-domain certificate sweep for one device (or one H). More...
struct	OperatingRegionSample
	One sample of a (P,Q) operating-region certificate. More...

Functions
double	passivityIndex (const Eigen::MatrixXcd &Y)
	Hermitian passivity index λ_min((Y+Y*)/2).
double	shiftedPassivityIndex (const Eigen::MatrixXcd &Y, double delta)
	Shifted passivity λ_min(Her(Y + δ I)).
double	dwHermitianMargin (const Eigen::MatrixXcd &Y)
	Hermitian DW-slice margin (legacy): λ_min(Her Y).
double	maxEigenPhaseDeg (const Eigen::MatrixXcd &Y)
	Maximum |arg(λ)| over eigenvalues of Y, in degrees (heuristic).
bool	sweepPassesSpec (const CertificateSweep &sweep, const CertificateSpec &spec)
	True if all enabled spec gates pass on a completed sweep.
Eigen::MatrixXcd	extractAcDqBlock (const Eigen::MatrixXcd &Y)
	Extract AC dq 2×2 block from 2×2 or 3×3 Y.
Eigen::MatrixXcd	elementAdmittance (Element &elem, double freq_Hz, bool ac_dq_block=true)
	Numeric Y of an element at f (Hz), optionally AC dq block.
CertificateSweep	sweepDeviceCertificate (Element &elem, const CertificateSpec &spec)
	Sweep device Y and evaluate certificates per spec.
CertificateSweep	sweepDeviceCertificate (Element &elem, double f_min, double f_max, int n_points, bool ac_block=true, double phase_limit_deg=90.0)
	Convenience overload with explicit grid.
CertificateSweep	sweepReturnRatioCertificate (StabilityEstimate &stability, const std::string &converter_name, const std::string &location, const CertificateSpec &spec)
	Sweep H = Y Z_eq and report Her(I+H) passivity-style margins.
CertificateSweep	sweepReturnRatioCertificate (StabilityEstimate &stability, const std::string &converter_name, const std::string &location, double f_min, double f_max, int n_points)
void	finalizeCertificateSweep (CertificateSweep &sweep, const CertificateSpec &spec)
	Aggregate pass/fail from a completed sweep + spec.
void	writeCertificateSweepCsv (const CertificateSweep &sweep, const std::string &path)
void	writeOperatingRegionCsv (const std::vector< OperatingRegionSample > &samples, const std::string &path)
void	plot_certificate_passivity (const CertificateSweep &sweep, const std::string &title="Passivity index")
void	plot_certificate_phase (const CertificateSweep &sweep, const std::string &title="Device phase certificate")
void	plot_certificate_gate (const CertificateSweep &sweep, const std::string &title="Device gate certificate")
void	plot_certificate_operating_region (const std::vector< OperatingRegionSample > &samples, const std::string &title="Certified operating region (P,Q)")
void	plot_certificate_local_vs_system (const CertificateSweep &local, const CertificateSweep &system_H, const std::string &title="Local vs system certificate")
void	plot_certificate_tuning_compare (const CertificateSweep &before, const CertificateSweep &after, const std::string &title="Control tuning: passivity")
void	plot_certificate_dw_slice (const Eigen::MatrixXcd &Y, double freq_Hz, const std::string &title="DW-style Hermitian slice")
void	plot_certificate_numerical_range (const Eigen::MatrixXcd &Y, double freq_Hz, double phase_limit_deg=90.0, const std::string &title="Numerical range W(Y)")
void	plot_certificate_dw_shell (const Eigen::MatrixXcd &Y, double freq_Hz, const CertificateSpec &spec={}, const std::string &title="DW shell (xz projection)")
void	plot_certificate_geometric_sweep (const CertificateSweep &sweep, const std::string &title="Geometric certificates")

Detailed Description

Device-level passivity / phase / geometric metrics and plots.

Function Documentation

dwHermitianMargin()

double dwHermitianMargin

(

const Eigen::MatrixXcd &

Y

)

Hermitian DW-slice margin (legacy): λ_min(Her Y).

Prefer certifyNumericalRange / certifyDwShell for geometric certificates.

References passivityIndex().

elementAdmittance()

Eigen::MatrixXcd elementAdmittance	(	Element &	elem,
		double	freq_Hz,
		bool	ac_dq_block = true
	)

Numeric Y of an element at f (Hz), optionally AC dq block.

References Element::compute_y_parameters(), and extractAcDqBlock().

Referenced by example_certificate_figures(), and sweepDeviceCertificate().

extractAcDqBlock()

Eigen::MatrixXcd extractAcDqBlock

(

const Eigen::MatrixXcd &

Y

)

Extract AC dq 2×2 block from 2×2 or 3×3 Y.

Referenced by elementAdmittance().

finalizeCertificateSweep()

void finalizeCertificateSweep	(	CertificateSweep &	sweep,
		const CertificateSpec &	spec
	)

Aggregate pass/fail from a completed sweep + spec.

References CertificateSpec::gain_limit, CertificateSweep::gain_limit, CertificateSweep::pass_dw, CertificateSweep::pass_nr_phase, CertificateSweep::pass_nr_zero, CertificateSweep::pass_passivity, CertificateSweep::pass_phase, CertificateSweep::pass_sector, CertificateSweep::pass_shifted, CertificateSweep::pass_small_gain, CertificateSpec::passivity_eps, CertificateSpec::phase_limit_deg, CertificateSweep::phase_limit_deg, CertificateSpec::shift_delta, CertificateSweep::shift_delta, CertificateSweep::worst_nr_phase_deg, CertificateSweep::worst_nr_zero_margin, CertificateSweep::worst_passivity, CertificateSweep::worst_phase_deg, CertificateSweep::worst_shifted, and CertificateSweep::worst_small_gain.

Referenced by sweepDeviceCertificate(), and sweepReturnRatioCertificate().

maxEigenPhaseDeg()

double maxEigenPhaseDeg

(

const Eigen::MatrixXcd &

Y

)

Maximum |arg(λ)| over eigenvalues of Y, in degrees (heuristic).

Referenced by sweepReturnRatioCertificate().

passivityIndex()

double passivityIndex

(

const Eigen::MatrixXcd &

Y

)

Hermitian passivity index λ_min((Y+Y*)/2).

Referenced by dwHermitianMargin(), and shiftedPassivityIndex().

plot_certificate_dw_shell()

void plot_certificate_dw_shell	(	const Eigen::MatrixXcd &	Y,
		double	freq_Hz,
		const CertificateSpec &	spec = {},
		const std::string &	title = "DW shell (xz projection)"
	)

References add_plot_tab(), certifyDwShell(), CertificateSpec::dw_sphere, DwShellCertificate::excess_passivity, CertificateSpec::gain_limit, NumericalRangeCertificate::max_phase_deg, DwShellCertificate::max_singular, DwShellCertificate::nr, CertificateSpec::nr_theta, NumericalRangeCertificate::pass_phase, DwShellCertificate::pass_small_gain, CertificateSpec::passivity_eps, CertificateSpec::phase_limit_deg, DwShellCertificate::samples, and DwShellCertificate::shortage_passivity.

Referenced by example_certificate_figures().

plot_certificate_dw_slice()

void plot_certificate_dw_slice	(	const Eigen::MatrixXcd &	Y,
		double	freq_Hz,
		const std::string &	title = "DW-style Hermitian slice"
	)

References add_plot_tab(), NumericalRangeCertificate::boundary, certifyNumericalRange(), NumericalRangeCertificate::contains_zero, NumericalRangeCertificate::max_phase_deg, NumericalRangeCertificate::min_real, and NumericalRangeCertificate::zero_margin.

Referenced by example_certificate_figures().

plot_certificate_gate()

void plot_certificate_gate	(	const CertificateSweep &	sweep,
		const std::string &	title = "Device gate certificate"
	)

References add_plot_tab(), CertificateSweep::freq_Hz, CertificateSweep::max_phase_deg, CertificateSweep::pass_passivity, CertificateSweep::pass_phase, CertificateSweep::passivity_index, and CertificateSweep::phase_limit_deg.

Referenced by reportDeviceGate().

plot_certificate_geometric_sweep()

void plot_certificate_geometric_sweep	(	const CertificateSweep &	sweep,
		const std::string &	title = "Geometric certificates"
	)

References add_plot_tab(), CertificateSweep::freq_Hz, CertificateSweep::gain_limit, CertificateSweep::max_phase_deg, CertificateSweep::nr_phase_deg, CertificateSweep::nr_zero_margin, CertificateSweep::pass_dw, CertificateSweep::pass_nr_phase, CertificateSweep::pass_nr_zero, CertificateSweep::pass_small_gain, CertificateSweep::phase_limit_deg, CertificateSweep::shortage_passivity, CertificateSweep::small_gain, CertificateSweep::worst_nr_phase_deg, CertificateSweep::worst_nr_zero_margin, CertificateSweep::worst_shortage, and CertificateSweep::worst_small_gain.

Referenced by example_certificate_figures(), and reportDeviceGate().

plot_certificate_local_vs_system()

void plot_certificate_local_vs_system	(	const CertificateSweep &	local,
		const CertificateSweep &	system_H,
		const std::string &	title = "Local vs system certificate"
	)

References add_plot_tab(), CertificateSweep::freq_Hz, CertificateSweep::pass_passivity, and CertificateSweep::passivity_index.

Referenced by reportLocalVsSystem().

plot_certificate_numerical_range()

void plot_certificate_numerical_range	(	const Eigen::MatrixXcd &	Y,
		double	freq_Hz,
		double	phase_limit_deg = 90.0,
		const std::string &	title = "Numerical range W(Y)"
	)

References add_plot_tab(), NumericalRangeCertificate::boundary, certifyNumericalRange(), NumericalRangeCertificate::max_phase_deg, NumericalRangeCertificate::pass_phase, and NumericalRangeCertificate::zero_margin.

Referenced by example_certificate_figures().

plot_certificate_operating_region()

void plot_certificate_operating_region	(	const std::vector< OperatingRegionSample > &	samples,
		const std::string &	title = "Certified operating region (P,Q)"
	)

References add_plot_tab(), and s.

Referenced by reportOperatingRegion().

plot_certificate_passivity()

void plot_certificate_passivity	(	const CertificateSweep &	sweep,
		const std::string &	title = "Passivity index"
	)

References add_plot_tab(), CertificateSweep::freq_Hz, CertificateSweep::pass_passivity, CertificateSweep::passivity_index, CertificateSweep::shift_delta, CertificateSweep::shifted_passivity, and CertificateSweep::worst_passivity.

Referenced by reportDeviceGate().

plot_certificate_phase()

void plot_certificate_phase	(	const CertificateSweep &	sweep,
		const std::string &	title = "Device phase certificate"
	)

References add_plot_tab(), CertificateSweep::freq_Hz, CertificateSweep::max_phase_deg, CertificateSweep::pass_phase, CertificateSweep::phase_limit_deg, and CertificateSweep::worst_phase_deg.

Referenced by reportDeviceGate().

plot_certificate_tuning_compare()

void plot_certificate_tuning_compare	(	const CertificateSweep &	before,
		const CertificateSweep &	after,
		const std::string &	title = "Control tuning: passivity"
	)

References add_plot_tab(), CertificateSweep::freq_Hz, CertificateSweep::pass_passivity, CertificateSweep::passivity_index, and CertificateSweep::worst_passivity.

Referenced by reportGfmTuning().

shiftedPassivityIndex()

double shiftedPassivityIndex	(	const Eigen::MatrixXcd &	Y,
		double	delta
	)

Shifted passivity λ_min(Her(Y + δ I)).

References passivityIndex().

sweepDeviceCertificate() [1/2]

CertificateSweep sweepDeviceCertificate	(	Element &	elem,
		const CertificateSpec &	spec
	)

Sweep device Y and evaluate certificates per spec.

References CertificateSpec::ac_dq_block, elementAdmittance(), CertificateSpec::f_max_Hz, CertificateSpec::f_min_Hz, finalizeCertificateSweep(), CertificateSweep::freq_Hz, CertificateSpec::n_points, and s.

Referenced by compareLocalVsSystem(), evaluateDeviceGate(), sweepDeviceCertificate(), and tuneGfmDroops().

sweepDeviceCertificate() [2/2]

CertificateSweep sweepDeviceCertificate	(	Element &	elem,
		double	f_min,
		double	f_max,
		int	n_points,
		bool	ac_block = true,
		double	phase_limit_deg = 90.0
	)

Convenience overload with explicit grid.

References CertificateSpec::ac_dq_block, CertificateSpec::f_max_Hz, CertificateSpec::f_min_Hz, CertificateSpec::n_points, CertificateSpec::phase_limit_deg, and sweepDeviceCertificate().

sweepPassesSpec()

bool sweepPassesSpec	(	const CertificateSweep &	sweep,
		const CertificateSpec &	spec
	)

True if all enabled spec gates pass on a completed sweep.

References CertificateSweep::pass_dw, CertificateSweep::pass_nr_phase, CertificateSweep::pass_nr_zero, CertificateSweep::pass_passivity, CertificateSweep::pass_phase, CertificateSweep::pass_sector, CertificateSweep::pass_shifted, CertificateSweep::pass_small_gain, CertificateSpec::require_dw, CertificateSpec::require_nr_phase, CertificateSpec::require_nr_zero_outside, CertificateSpec::require_passivity, CertificateSpec::require_phase, CertificateSpec::require_sector, CertificateSpec::require_shifted, and CertificateSpec::require_small_gain.

Referenced by evaluateDeviceGate(), and tuneGfmDroops().

sweepReturnRatioCertificate() [1/2]

CertificateSweep sweepReturnRatioCertificate	(	StabilityEstimate &	stability,
		const std::string &	converter_name,
		const std::string &	location,
		const CertificateSpec &	spec
	)

Sweep H = Y Z_eq and report Her(I+H) passivity-style margins.

References StabilityEstimate::compute_transfer_function(), CertificateSpec::f_max_Hz, CertificateSpec::f_min_Hz, finalizeCertificateSweep(), CertificateSweep::freq_Hz, maxEigenPhaseDeg(), CertificateSpec::n_points, s, and spectralNorm().

Referenced by compareLocalVsSystem(), and sweepReturnRatioCertificate().

sweepReturnRatioCertificate() [2/2]

CertificateSweep sweepReturnRatioCertificate	(	StabilityEstimate &	stability,
		const std::string &	converter_name,
		const std::string &	location,
		double	f_min,
		double	f_max,
		int	n_points
	)

References CertificateSpec::f_max_Hz, CertificateSpec::f_min_Hz, CertificateSpec::n_points, and sweepReturnRatioCertificate().

writeCertificateSweepCsv()

void writeCertificateSweepCsv	(	const CertificateSweep &	sweep,
		const std::string &	path
	)

References CertificateSweep::dw_margin, CertificateSweep::freq_Hz, CertificateSweep::max_phase_deg, CertificateSweep::min_real_eig, CertificateSweep::nr_phase_deg, CertificateSweep::nr_zero_margin, CertificateSweep::passivity_index, CertificateSweep::shifted_passivity, CertificateSweep::shortage_passivity, and CertificateSweep::small_gain.

Referenced by example_certificate_figures().

writeOperatingRegionCsv()

void writeOperatingRegionCsv	(	const std::vector< OperatingRegionSample > &	samples,
		const std::string &	path
	)

References s.

Referenced by example_certificate_figures().