Stability_certificate.cpp File Reference

Device certificate metrics and paper-style ImPlot figures. More...

#include "Stability_certificate.h"
#include "../../Elements/Element.h"
#include "../Stability_Estimate/Stability_estimate.h"
#include <algorithm>
#include <cmath>
#include <fstream>
#include <iomanip>
#include <limits>
#include <stdexcept>

Include dependency graph for Stability_certificate.cpp:

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).
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)
	Numeric Y of an element at f (Hz), optionally AC dq block.
void	finalizeCertificateSweep (CertificateSweep &sweep, const CertificateSpec &spec)
	Aggregate pass/fail from a completed sweep + spec.
bool	sweepPassesSpec (const CertificateSweep &sweep, const CertificateSpec &spec)
	True if all enabled spec gates pass on a completed sweep.
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, double phase_limit_deg)
	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	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)
void	plot_certificate_phase (const CertificateSweep &sweep, const std::string &title)
void	plot_certificate_gate (const CertificateSweep &sweep, const std::string &title)
void	plot_certificate_operating_region (const std::vector< OperatingRegionSample > &samples, const std::string &title)
void	plot_certificate_local_vs_system (const CertificateSweep &local, const CertificateSweep &system_H, const std::string &title)
void	plot_certificate_tuning_compare (const CertificateSweep &before, const CertificateSweep &after, const std::string &title)
void	plot_certificate_dw_slice (const Eigen::MatrixXcd &Y, double freq_Hz, const std::string &title)
void	plot_certificate_numerical_range (const Eigen::MatrixXcd &Y, double freq_Hz, double phase_limit_deg, const std::string &title)
void	plot_certificate_dw_shell (const Eigen::MatrixXcd &Y, double freq_Hz, const CertificateSpec &spec, const std::string &title)
void	plot_certificate_geometric_sweep (const CertificateSweep &sweep, const std::string &title)

Detailed Description

Device certificate metrics and paper-style ImPlot figures.

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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,
		const std::string &	title
	)

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
	)

References add_plot_tab(), and s.

Referenced by reportOperatingRegion().

plot_certificate_passivity()

void plot_certificate_passivity	(	const CertificateSweep &	sweep,
		const std::string &	title
	)

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
	)

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
	)

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,
		double	phase_limit_deg
	)

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().