VeraGridEngine.Simulations.SmallSignalStabilityEmt package

Submodules

VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_numba_kernels module

Numba kernels for EMT Floquet block methods.

This module is optional and degrades gracefully if Numba is unavailable. It includes: - A dense A_k sequence block propagator (monodromy application in block form). - A block MGS + optional second pass kernel for Arnoldi orthogonalisation.

Notes

• The kernels operate on real-valued arrays (float64). Complex Ritz handling remains in Python/Numpy and is split into real/imag operator applications upstream.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_numba_kernels.apply_ak_stack_block_numba(*args, **kwargs)

VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_numba_kernels.bmgs_twice_numba(*args, **kwargs)

VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_numba_kernels.solve_lu_dense_block_numba(*args, **kwargs)

VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_operator module

EMT Floquet Linear Operators Module.

This module provides high-performance LinearOperator subclasses compatible with SciPy’s sparse linear algebra solvers (like ARPACK). These operators define the action of the Monodromy Matrix (state-transition over one full limit cycle) without explicitly constructing it.

Included Operators: - EmtFloquetOperator: Standard (vector-by-vector) LU-cached operator. - BlockEmtFloquetOperator: Block (matrix-by-matrix) LU-cached operator. - AkStackBlockEmtFloquetOperator: Explicit pre-computed transition matrix stack operator.

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_operator.AkStackBlockEmtFloquetOperator(*args, **kwargs)

Bases: LinearOperator

Monodromy operator from an explicit stack of state-transition matrices A_k.

This is the preferred path for EMT/Floquet benchmarking when the EMT engine can expose the per-step linearized state map:

x_{k+1} = A_k x_k

for one limit-cycle period. The operator applies:

Phi = A_{M-1} * … * A_1 * A_0

on vectors or blocks. When Numba is available and use_numba=True, the block path is JIT-compiled to reduce Python overhead in repeated Arnoldi calls.

matmat(X: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Public alias for matrix-matrix multiplication.

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_operator.BlockEmtFloquetOperator(*args, **kwargs)

Bases: LinearOperator

Advanced HPC Block Monodromy Operator for EMT Small-Signal Stability.

This class is specifically designed to support Randomized Numerical Linear Algebra (RandNLA) and Block Krylov subspace methods. Unlike standard operators that process a single column vector at a time (BLAS Level 2), this operator accepts a dense block matrix (N x p) of vectors simultaneously.

By processing multiple perturbation vectors at once, it forces the underlying SciPy/SuperLU backend to utilize BLAS Level 3 routines (Matrix-Matrix multiplication and Block Forward/Backward Substitution). This maximizes CPU L1/L2 cache utilization, drastically reducing the memory-bound bottlenecks inherent to large-scale sparse electrical networks.

Attributes:

problem: The underlying EMT DAE problem instance. trajectory: List of pre-captured steady-state tuples (x, y) over one period T. h (float): Integration time step. n_states (int): Number of differential state variables. lu_solvers (list): Cached SuperLU factorizations for the entire trajectory.

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.emt_floquet_operator.EmtFloquetOperator(*args, **kwargs)

Bases: LinearOperator

HPC Matrix-Free Monodromy Operator for abc-frame EMT systems.

Optimized with LU Factorization Caching to eliminate redundant computations during Krylov subspace iterations (Arnoldi). This operator processes single perturbation vectors.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core module

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.EraBandResult(poles_s: ndarray[tuple[Any, ...], dtype[complex128]], poles_z: ndarray[tuple[Any, ...], dtype[complex128]], residues: ndarray[tuple[Any, ...], dtype[complex128]], modal_energy: ndarray[tuple[Any, ...], dtype[float64]], reconstruction_error: float, band_low_hz: float, band_high_hz: float, selected_order: int, observable_count: int, condition_number: float, successful: bool)

Bases: object

Result of one independent band extraction.

The object only stores one band outcome, which is the required shape for a later multiprocessing or joblib-style parallel map.

get_band_high_hz() → float

Return the upper source-band edge.

Returns:

Frequency in Hz.

get_band_low_hz() → float

Return the lower source-band edge.

Returns:

Frequency in Hz.

get_condition_number() → float

Return the band condition-number estimate.

Returns:

Condition-number estimate.

get_modal_energy() → ndarray[tuple[Any, ...], dtype[float64]]

Return the relative modal-energy vector.

Returns:

Modal-energy vector.

get_observable_count() → int

Return how many channels participated in this band extraction.

Returns:

Number of observables.

get_poles_s() → ndarray[tuple[Any, ...], dtype[complex128]]

Return the continuous-time poles.

Returns:

Complex pole vector.

get_poles_z() → ndarray[tuple[Any, ...], dtype[complex128]]

Return the discrete-time poles.

Returns:

Complex pole vector.

get_reconstruction_error() → float

Return the global reconstruction error.

Returns:

Relative reconstruction error.

get_residues() → ndarray[tuple[Any, ...], dtype[complex128]]

Return the physical residue matrix.

Returns:

Complex residue matrix.

get_selected_order() → int

Return the selected subspace order.

Returns:

Integer order.

get_successful() → bool

Return whether the band produced valid modes.

Returns:

Success flag.

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.EraBandSignal(time_data: ndarray[tuple[Any, ...], dtype[float64]], signal_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], physical_scales: ndarray[tuple[Any, ...], dtype[float64]], time_step: float, sampling_frequency_hz: float, low_hz: float, high_hz: float, decimation_factor: int)

Bases: object

Prepared sub-band signal and its numerical metadata.

The class holds all information required to solve one band independently so the outer driver can later parallelize bands without shared mutable state.

get_decimation_factor() → int

Return the effective integer decimation factor.

Returns:

Positive decimation factor.

get_high_hz() → float

Return the upper band edge.

Returns:

Frequency in Hz.

get_low_hz() → float

Return the lower band edge.

Returns:

Frequency in Hz.

get_physical_scales() → ndarray[tuple[Any, ...], dtype[float64]]

Return the original per-channel scaling factors.

Returns:

Scaling vector.

get_sampling_frequency_hz() → float

Return the effective decimated sampling frequency.

Returns:

Sampling frequency in Hz.

get_signal_data() → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Return the standardized band-limited observation matrix.

Returns:

Observation matrix.

get_time_data() → ndarray[tuple[Any, ...], dtype[float64]]

Return the decimated time vector.

Returns:

Time vector.

get_time_step() → float

Return the effective decimated time step.

Returns:

Time step in seconds.

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.EraChannelScaling(means: ndarray[tuple[Any, ...], dtype[float64]], scales: ndarray[tuple[Any, ...], dtype[float64]])

Bases: object

Container for channel centering and scaling information.

The object is immutable after construction because residue rescaling must use the exact same channel statistics that were used to normalize the data.

get_means() → ndarray[tuple[Any, ...], dtype[float64]]

Return the per-channel means.

Returns:

Mean vector.

get_scales() → ndarray[tuple[Any, ...], dtype[float64]]

Return the per-channel scaling vector.

Returns:

Scaling vector.

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.EraMergedModalData(poles_s: ndarray[tuple[Any, ...], dtype[complex128]], residues: ndarray[tuple[Any, ...], dtype[complex128]], modal_energy: ndarray[tuple[Any, ...], dtype[float64]], reconstruction_errors: ndarray[tuple[Any, ...], dtype[float64]], band_low_hz: ndarray[tuple[Any, ...], dtype[float64]], band_high_hz: ndarray[tuple[Any, ...], dtype[float64]], selected_orders: ndarray[tuple[Any, ...], dtype[int64]], observable_count_per_mode: ndarray[tuple[Any, ...], dtype[int64]])

Bases: object

Fused modal data produced after multi-band clustering.

The class feeds the final public result container while keeping all intermediate fusion logic detached from the GUI-facing object.

get_band_high_hz() → ndarray[tuple[Any, ...], dtype[float64]]

Return the upper source-band vector.

Returns:

Upper-band vector.

get_band_low_hz() → ndarray[tuple[Any, ...], dtype[float64]]

Return the lower source-band vector.

Returns:

Lower-band vector.

get_modal_energy() → ndarray[tuple[Any, ...], dtype[float64]]

Return the fused modal-energy vector.

Returns:

Modal-energy vector.

get_observable_count_per_mode() → ndarray[tuple[Any, ...], dtype[int64]]

Return the per-mode observable-count vector.

Returns:

Integer vector of observable counts.

get_poles_s() → ndarray[tuple[Any, ...], dtype[complex128]]

Return the fused continuous-time poles.

Returns:

Complex pole vector.

get_reconstruction_errors() → ndarray[tuple[Any, ...], dtype[float64]]

Return the reconstruction-error vector.

Returns:

Reconstruction-error vector.

get_residues() → ndarray[tuple[Any, ...], dtype[complex128]]

Return the fused physical residues.

Returns:

Complex residue matrix.

get_selected_orders() → ndarray[tuple[Any, ...], dtype[int64]]

Return the selected-order vector.

Returns:

Integer vector of orders.

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.EraSvdDecomposition(singular_values: ndarray[tuple[Any, ...], dtype[float64]], right_vectors: ndarray[tuple[Any, ...], dtype[complex128]], condition_number: float, truncated_backend: bool)

Bases: object

SVD decomposition used by the TLS matrix pencil stage.

The object keeps the right singular vectors because the shift-invariant TLS generalized eigenproblem is constructed from the right subspace.

get_condition_number() → float

Return the condition-number estimate.

Returns:

Condition-number estimate.

get_right_vectors() → ndarray[tuple[Any, ...], dtype[complex128]]

Return the right singular vectors.

Returns:

Matrix whose columns are right singular vectors.

get_singular_values() → ndarray[tuple[Any, ...], dtype[float64]]

Return the singular values.

Returns:

Singular-value vector.

get_truncated_backend() → bool

Return whether the decomposition came from a truncated backend.

Returns:

True when the decomposition is truncated.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.apply_ba_filter_matrix(y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], numerator: ndarray[tuple[Any, ...], dtype[float64]], denominator: ndarray[tuple[Any, ...], dtype[float64]], use_zero_phase_filtering: bool) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Apply one transfer-function filter channel-by-channel.

Parameters:

• y_data – Observation matrix.

• numerator – Numerator coefficients.

• denominator – Denominator coefficients.

• use_zero_phase_filtering – Use zero-phase filtering when feasible.

Returns:

Filtered observation matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.apply_notch_filter_matrix(y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], sampling_frequency_hz: float, nominal_frequency_hz: float, quality_factor: float, use_notch_filtering: bool, use_zero_phase_filtering: bool) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Apply the strict fundamental notch filter.

Parameters:

• y_data – Observation matrix.

• sampling_frequency_hz – Sampling frequency.

• nominal_frequency_hz – Nominal grid frequency.

• quality_factor – Notch quality factor.

• use_notch_filtering – Enable flag.

• use_zero_phase_filtering – Use zero-phase filtering when feasible.

Returns:

Filtered observation matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.apply_sos_filter_matrix(y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], sos_matrix: ndarray[tuple[Any, ...], dtype[float64]], use_zero_phase_filtering: bool) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Apply one SOS filter channel-by-channel.

Parameters:

• y_data – Observation matrix.

• sos_matrix – SOS filter coefficients.

• use_zero_phase_filtering – Use zero-phase filtering when feasible.

Returns:

Filtered observation matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_block_hankel_matrix(signal_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], block_rows: int) → ndarray[tuple[Any, ...], dtype[complex128]]

Build the MIMO block-Hankel matrix.

Parameters:

• signal_data – Band-limited MIMO observation matrix.

• block_rows – Number of block rows.

Returns:

Complex block-Hankel matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_candidate_orders(maximum_order: int) → ndarray[tuple[Any, ...], dtype[int64]]

Build the candidate orders explored inside one band.

Parameters:

maximum_order – Upper-order bound supplied by the IC stage.

Returns:

Integer vector of candidate orders.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_empty_complex_matrix() → ndarray[tuple[Any, ...], dtype[complex128]]

Build one empty complex matrix.

Returns:

Empty complex matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_empty_complex_vector() → ndarray[tuple[Any, ...], dtype[complex128]]

Build one empty complex vector.

Returns:

Empty complex vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_empty_float_vector() → ndarray[tuple[Any, ...], dtype[float64]]

Build one empty real vector.

Returns:

Empty real vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_forward_backward_hankel_matrix(signal_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], block_rows: int, use_forward_backward: bool) → ndarray[tuple[Any, ...], dtype[complex128]]

Build the forward-backward block-Hankel matrix.

Parameters:

• signal_data – Band-limited MIMO observation matrix.

• block_rows – Number of block rows.

• use_forward_backward – Enable flag.

Returns:

Combined forward-backward Hankel matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_full_svd_decomposition(hankel_matrix: ndarray[tuple[Any, ...], dtype[complex128]]) → EraSvdDecomposition

Build one decomposition from a dense full SVD.

Parameters:

hankel_matrix – Hankel matrix.

Returns:

SVD decomposition object.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_physical_band_signal(signal_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], physical_scales: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]]

Re-scale the band-limited observations back to physical units.

Parameters:

• signal_data – Standardized band-limited observation matrix.

• physical_scales – Original per-channel scales.

Returns:

Physical complex signal matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_results_from_merged_modal_data(merged_data: EraMergedModalData, observable_names: List[str]) → EraMatrixPencilResults

Build the public results object from the fused modal data.

Parameters:

• merged_data – Fused modal data.

• observable_names – Selected observable labels.

Returns:

Public results object.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_square_tls_pencil(right_vectors: ndarray[tuple[Any, ...], dtype[complex128]], selected_order: int) → Tuple[ndarray[tuple[Any, ...], dtype[complex128]], ndarray[tuple[Any, ...], dtype[complex128]]]

Build the square TLS pencil used by the generalized eigenproblem.

Parameters:

• right_vectors – Right singular vectors as columns.

• selected_order – Effective model order.

Returns:

Tuple (V2, V1) of square matrices.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.build_vandermonde_matrix(z_poles: ndarray[tuple[Any, ...], dtype[complex128]], n_samples: int) → ndarray[tuple[Any, ...], dtype[complex128]]

Build the Vandermonde matrix used to fit modal residues.

Parameters:

• z_poles – Discrete-time poles.

• n_samples – Number of time samples.

Returns:

Complex Vandermonde matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_band_result_score(band_result: EraBandResult) → float

Compute the selection score used to choose the best candidate order.

Parameters:

band_result – Candidate band result.

Returns:

Scalar score. Larger is better.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_block_rows(n_samples: int, era_options: EraMatrixPencilOptions) → int

Compute the block-Hankel depth.

Parameters:

• n_samples – Number of band samples.

• era_options – Matrix-pencil options.

Returns:

Number of block rows.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_channel_scaling(y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]) → EraChannelScaling

Compute channel centering and scaling factors.

Parameters:

y_data – Observation matrix.

Returns:

Scaling object.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_decimation_factor(n_samples: int, input_sampling_frequency_hz: float, band_high_hz: float, decimation_safety_factor: float, manual_cap_factor: int, minimum_samples_per_band: int) → int

Compute the safe integer decimation factor for one band.

Parameters:

• n_samples – Number of input samples.

• input_sampling_frequency_hz – Input sampling frequency.

• band_high_hz – Upper band edge.

• decimation_safety_factor – Requested oversampling factor.

• manual_cap_factor – Legacy manual cap.

• minimum_samples_per_band – Minimum samples allowed after decimation.

Returns:

Integer decimation factor.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_information_criterion_scores(singular_values: ndarray[tuple[Any, ...], dtype[float64]], n_snapshots: int) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

Compute MDL and AIC order-selection scores.

Parameters:

• singular_values – Singular-value vector.

• n_snapshots – Number of Hankel columns.

Returns:

Tuple (mdl_scores, aic_scores).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_modal_energies(physical_signal_data: ndarray[tuple[Any, ...], dtype[complex128]], z_poles: ndarray[tuple[Any, ...], dtype[complex128]], physical_residues: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[float64]]

Compute per-mode modal energy in physical units.

Parameters:

• physical_signal_data – Physical band-limited observations.

• z_poles – Discrete-time poles.

• physical_residues – Physical residue matrix.

Returns:

Relative modal-energy vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_pair_energy_keep_mask(s_poles: ndarray[tuple[Any, ...], dtype[complex128]], modal_energy: ndarray[tuple[Any, ...], dtype[float64]], energy_threshold: float, frequency_tolerance_hz: float, real_part_tolerance: float) → ndarray

Build the keep mask while preserving conjugate pairs.

Parameters:

• s_poles – Continuous-time poles.

• modal_energy – Relative modal-energy vector.

• energy_threshold – Minimum retained energy.

• frequency_tolerance_hz – Frequency tolerance in Hz.

• real_part_tolerance – Real-part tolerance in 1/s.

Returns:

Boolean keep mask.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.compute_svd_decomposition(hankel_matrix: ndarray[tuple[Any, ...], dtype[complex128]], era_options: EraMatrixPencilOptions) → EraSvdDecomposition

Compute the Hankel SVD using the configured backend.

Parameters:

• hankel_matrix – Forward-backward Hankel matrix.

• era_options – Matrix-pencil options.

Returns:

SVD decomposition object.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.convert_signal_to_2d(y_data: ndarray) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Ensure that the input observation array is two-dimensional.

Parameters:

y_data – Raw observation array.

Returns:

Two-dimensional observation matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.create_empty_band_result(observable_count: int, low_hz: float, high_hz: float) → EraBandResult

Build an empty band result.

Parameters:

• observable_count – Number of observables assigned to the band.

• low_hz – Lower source-band edge.

• high_hz – Upper source-band edge.

Returns:

Empty unsuccessful band result.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.create_empty_merged_modal_data() → EraMergedModalData

Build one empty fused modal container.

Returns:

Empty merged modal data.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.deduplicate_continuous_poles(z_poles: ndarray[tuple[Any, ...], dtype[complex128]], s_poles: ndarray[tuple[Any, ...], dtype[complex128]], frequency_tolerance_hz: float, real_part_tolerance: float) → Tuple[ndarray[tuple[Any, ...], dtype[complex128]], ndarray[tuple[Any, ...], dtype[complex128]]]

Remove duplicate poles inside one band.

Parameters:

• z_poles – Discrete-time poles.

• s_poles – Continuous-time poles.

• frequency_tolerance_hz – Frequency tolerance in Hz.

• real_part_tolerance – Real-part tolerance in 1/s.

Returns:

Tuple (unique_z_poles, unique_s_poles).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.design_band_filter_sos(low_hz: float, high_hz: float, sampling_frequency_hz: float, filter_order: int) → ndarray[tuple[Any, ...], dtype[float64]] | None

Design the real-valued sub-band filter.

Parameters:

• low_hz – Lower band edge.

• high_hz – Upper band edge.

• sampling_frequency_hz – Sampling frequency.

• filter_order – Butterworth order.

Returns:

SOS matrix or None when the design is impossible.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.detrend_exponential_dc_offsets(time_data: ndarray[tuple[Any, ...], dtype[float64]], y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], use_exponential_detrending: bool) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Remove the exponential DC component from every observation channel.

Parameters:

• time_data – Time vector.

• y_data – Observation matrix.

• use_exponential_detrending – Enable flag.

Returns:

Detrended observation matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.enforce_conjugate_symmetry(z_poles: ndarray[tuple[Any, ...], dtype[complex128]], s_poles: ndarray[tuple[Any, ...], dtype[complex128]], time_step: float, frequency_tolerance_hz: float, real_part_tolerance: float) → Tuple[ndarray[tuple[Any, ...], dtype[complex128]], ndarray[tuple[Any, ...], dtype[complex128]]]

Enforce explicit conjugate-pair symmetry for real-valued EMT signals.

Parameters:

• z_poles – Discrete-time poles.

• s_poles – Continuous-time poles.

• time_step – Effective time step.

• frequency_tolerance_hz – Frequency tolerance in Hz.

• real_part_tolerance – Real-part tolerance in 1/s.

Returns:

Tuple (symmetrized_z_poles, symmetrized_s_poles).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.evaluate_exponential_offset_model(time_data: ndarray[tuple[Any, ...], dtype[float64]], offset: float, amplitude: float, decay_rate: float) → ndarray[tuple[Any, ...], dtype[float64]]

Evaluate the exponential DC-offset model used during detrending.

Parameters:

• time_data – Time vector.

• offset – Constant offset term.

• amplitude – Exponential amplitude term.

• decay_rate – Positive decay rate.

Returns:

Model vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.extract_band_modes(band_signal: EraBandSignal, era_options: EraMatrixPencilOptions) → EraBandResult

Extract one band of modes using the TLS forward-backward matrix pencil.

Parameters:

• band_signal – Prepared band record.

• era_options – Matrix-pencil options.

Returns:

One independent band result.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.extract_matrix_pencil_results_from_data(time_data: ndarray[tuple[Any, ...], dtype[float64]], y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], era_options: EraMatrixPencilOptions, nominal_frequency_hz: float, observable_names: List[str] | None = None) → EraMatrixPencilResults

Execute the full EMT frequency-zooming matrix pencil on dense data.

Parameters:

• time_data – Raw time vector.

• y_data – Raw observation matrix.

• era_options – Matrix-pencil options.

• nominal_frequency_hz – Nominal grid frequency.

• observable_names – Optional channel labels.

Returns:

Public EMT modal results.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.filter_discrete_poles(z_poles: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[complex128]]

Remove obviously invalid discrete-time poles.

Parameters:

z_poles – Raw generalized eigenvalues.

Returns:

Sanitized discrete pole vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.find_conjugate_index(s_poles: ndarray[tuple[Any, ...], dtype[complex128]], reference_index: int, frequency_tolerance_hz: float, real_part_tolerance: float) → int

Find the conjugate partner of one pole.

Parameters:

• s_poles – Continuous-time poles.

• reference_index – Reference pole index.

• frequency_tolerance_hz – Frequency tolerance in Hz.

• real_part_tolerance – Real-part tolerance in 1/s.

Returns:

Matching index or -1.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.fit_exponential_dc_component(time_data: ndarray[tuple[Any, ...], dtype[float64]], signal_data: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Fit one decaying DC component to a single channel.

Parameters:

• time_data – Time vector.

• signal_data – One observation channel.

Returns:

Estimated exponential offset component.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.infer_uniform_time_step(time_data: ndarray[tuple[Any, ...], dtype[float64]], fallback_step: float) → float

Infer the effective uniform time step from a possibly adaptive time grid.

Parameters:

• time_data – Time vector.

• fallback_step – Fallback value when the estimate is impossible.

Returns:

Effective time step.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.map_discrete_to_continuous_poles(z_poles: ndarray[tuple[Any, ...], dtype[complex128]], time_step: float, low_hz: float, high_hz: float, principal_log_tolerance_hz: float) → Tuple[ndarray[tuple[Any, ...], dtype[complex128]], ndarray[tuple[Any, ...], dtype[complex128]]]

Map discrete-time poles to continuous time and validate the principal log.

Parameters:

• z_poles – Discrete-time poles.

• time_step – Effective time step.

• low_hz – Lower band edge.

• high_hz – Upper band edge.

• principal_log_tolerance_hz – Validation tolerance in Hz.

Returns:

Tuple (valid_z_poles, valid_s_poles).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.merge_band_results(band_results: List[EraBandResult], era_options: EraMatrixPencilOptions) → EraMergedModalData

Fuse the valid band results into one modal set.

Parameters:

• band_results – List of band results.

• era_options – Matrix-pencil options.

Returns:

Fused modal data.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.prepare_band_signal(time_data: ndarray[tuple[Any, ...], dtype[float64]], y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], scaling: EraChannelScaling, band: EraMatrixPencilBand, era_options: EraMatrixPencilOptions) → EraBandSignal

Build one filtered and decimated sub-band record.

Parameters:

• time_data – Uniform time vector.

• y_data – Standardized and notched observation matrix.

• scaling – Original channel scaling information.

• band – Requested analysis band.

• era_options – Matrix-pencil options.

Returns:

Prepared band record.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.reject_excessively_fast_poles(z_poles: ndarray[tuple[Any, ...], dtype[complex128]], s_poles: ndarray[tuple[Any, ...], dtype[complex128]], record_duration_s: float) → Tuple[ndarray[tuple[Any, ...], dtype[complex128]], ndarray[tuple[Any, ...], dtype[complex128]]]

Reject poles whose real part is too extreme for the available record length.

Parameters:

• z_poles – Discrete-time poles.

• s_poles – Continuous-time poles.

• record_duration_s – Available record length in seconds.

Returns:

Tuple (filtered_z_poles, filtered_s_poles).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.reject_notched_nominal_poles(z_poles: ndarray[tuple[Any, ...], dtype[complex128]], s_poles: ndarray[tuple[Any, ...], dtype[complex128]], era_options: EraMatrixPencilOptions) → Tuple[ndarray[tuple[Any, ...], dtype[complex128]], ndarray[tuple[Any, ...], dtype[complex128]]]

Remove poles that remain too close to the notched nominal frequency.

Parameters:

• z_poles – Discrete-time poles.

• s_poles – Continuous-time poles.

• era_options – Matrix-pencil options.

Returns:

Tuple (filtered_z_poles, filtered_s_poles).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.resample_to_uniform_time_grid(time_data: ndarray[tuple[Any, ...], dtype[float64]], y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], target_step: float) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]]

Resample the observations onto a uniform time grid.

Parameters:

• time_data – Original time vector.

• y_data – Observation matrix.

• target_step – Requested uniform time step.

Returns:

Tuple (uniform_time, uniform_signal).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.resolve_nominal_frequency_hz(explicit_nominal_frequency_hz: float, fallback_nominal_frequency_hz: float) → float

Resolve the nominal system frequency.

Parameters:

• explicit_nominal_frequency_hz – User override.

• fallback_nominal_frequency_hz – Grid-base fallback.

Returns:

Resolved nominal frequency in Hz.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.sanitize_analysis_bands(bands: Tuple[EraMatrixPencilBand, ...], sampling_frequency_hz: float) → Tuple[EraMatrixPencilBand, ...]

Sanitize analysis bands against the current Nyquist limit.

Parameters:

• bands – Requested bands.

• sampling_frequency_hz – Current sampling frequency.

Returns:

Sanitized tuple of bands.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.scale_residues_to_physical_units(residues: ndarray[tuple[Any, ...], dtype[complex128]], physical_scales: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]]

Re-scale residues back to the original physical channel magnitudes.

Parameters:

• residues – Standardized residue matrix.

• physical_scales – Original per-channel scales.

Returns:

Physical residue matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.select_mimo_observables(y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], observable_names: List[str] | None, maximum_observables: int) → Tuple[ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], List[str]]

Select the observable channels used to build the MIMO Hankel matrix.

Parameters:

• y_data – Observation matrix.

• observable_names – Optional channel labels.

• maximum_observables – Optional channel cap. 0 means all.

Returns:

Tuple (selected_signal, selected_names).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.select_model_order(decomposition: EraSvdDecomposition, n_snapshots: int, era_options: EraMatrixPencilOptions) → int

Select the effective signal subspace order.

Parameters:

• decomposition – SVD decomposition.

• n_snapshots – Number of Hankel columns.

• era_options – Matrix-pencil options.

Returns:

Selected model order.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.solve_band_modes_for_order(band_signal: EraBandSignal, era_options: EraMatrixPencilOptions, decomposition: EraSvdDecomposition, candidate_order: int) → EraBandResult

Solve one band for one explicit candidate order.

Parameters:

• band_signal – Prepared band record.

• era_options – Matrix-pencil options.

• decomposition – Band SVD decomposition.

• candidate_order – Explicit candidate order.

Returns:

One band result for that candidate order.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.solve_modal_residues(signal_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], z_poles: ndarray[tuple[Any, ...], dtype[complex128]]) → Tuple[ndarray[tuple[Any, ...], dtype[complex128]], float]

Solve the MIMO residue least-squares problem.

Parameters:

• signal_data – Standardized band-limited signal matrix.

• z_poles – Discrete-time poles.

Returns:

Tuple (residues, reconstruction_error).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.solve_tls_gevp(v2_matrix: ndarray[tuple[Any, ...], dtype[complex128]], v1_matrix: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[complex128]]

Solve the TLS generalized eigenvalue problem with a QZ-based backend.

Parameters:

• v2_matrix – Upper pencil matrix.

• v1_matrix – Lower pencil matrix.

Returns:

Discrete-time pole vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.sort_modes_by_frequency_and_damping(poles_s: ndarray[tuple[Any, ...], dtype[complex128]], residues: ndarray[tuple[Any, ...], dtype[complex128]], modal_energy: ndarray[tuple[Any, ...], dtype[float64]], reconstruction_errors: ndarray[tuple[Any, ...], dtype[float64]], band_low_hz: ndarray[tuple[Any, ...], dtype[float64]], band_high_hz: ndarray[tuple[Any, ...], dtype[float64]], selected_orders: ndarray[tuple[Any, ...], dtype[int64]], observable_count_per_mode: ndarray[tuple[Any, ...], dtype[int64]]) → EraMergedModalData

Sort fused modes by absolute frequency and then by damping.

Parameters:

• poles_s – Pole vector.

• residues – Residue matrix.

• modal_energy – Modal-energy vector.

• reconstruction_errors – Reconstruction-error vector.

• band_low_hz – Lower-band vector.

• band_high_hz – Upper-band vector.

• selected_orders – Selected-order vector.

• observable_count_per_mode – Observable-count vector.

Returns:

Sorted merged modal data.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_core.standardize_signal_matrix(y_data: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], scaling: EraChannelScaling) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Standardize all channels using the provided scaling object.

Parameters:

• y_data – Observation matrix.

• scaling – Centering and scaling information.

Returns:

Standardized observation matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver module

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.EraMatrixPencilDriver(grid: MultiCircuit, problem: EmtProblemTemplate, emt_options: EmtOptions, era_options: EraMatrixPencilOptions)

Bases: DriverTemplate

EMT driver for the frequency-zooming forward-backward TLS matrix pencil.

The driver is intentionally thin: it only runs the EMT simulation and then delegates the modal extraction to the pure stateless core module.

get_results() → EraMatrixPencilResults | None

Return the latest extraction results.

Returns:

Results object or None.

name = 'ERA Matrix Pencil EMT Simulation'

run() → None

Execute the EMT ringdown simulation and the modal extraction pipeline.

Returns:

None.

tpe = 'RMS Small Signal stability'

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.build_empty_era_results(observable_names: List[str] | None = None) → EraMatrixPencilResults

Build an empty public results object.

Parameters:

observable_names – Optional observable labels.

Returns:

Empty results object.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.build_hankel_zero_copy(y_signal: ndarray, window_length: int) → ndarray

Legacy helper that builds a scalar Hankel view.

The new solver uses a MIMO block-Hankel matrix, but the helper is preserved so older diagnostic scripts can still inspect the scalar construction.

Parameters:

• y_signal – Scalar observation signal.

• window_length – Hankel window length.

Returns:

Sliding-window Hankel view.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.extract_matrix_pencil_poles(y_signal: ndarray, dt: float, max_modes: int, tol_deflation: float) → ndarray[tuple[Any, ...], dtype[complex128]]

Compatibility wrapper around the new EMT matrix-pencil engine.

The wrapper keeps the legacy scalar API alive while internally using the refactored MIMO/TLS extraction path on a single observable channel.

Parameters:

• y_signal – Scalar observation signal.

• dt – Sampling time step.

• max_modes – Maximum number of retained modes.

• tol_deflation – Numerical singular-value floor.

Returns:

Continuous-time pole vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.extract_observable_names(problem: EmtProblemTemplate) → List[str]

Extract the ordered state-variable labels from the EMT problem.

Parameters:

problem – EMT problem definition.

Returns:

Ordered list of state labels.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.select_dominant_observable(y_data: ndarray) → ndarray

Legacy helper that selects one dominant observable by variance.

The new engine is fully MIMO and no longer depends on this reduction, but the function is preserved for backward compatibility with existing callers.

Parameters:

y_data – Real observation matrix with shape (n_samples, n_states).

Returns:

One-dimensional dominant observable.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.simulate_emt_state_history(solver: StructuralVectorizedSolver, n_states: int) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]]

Run the EMT solver and slice the differential-state block.

Parameters:

• solver – EMT structural solver.

• n_states – Number of differential states.

Returns:

Tuple (time_vector, state_history).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_driver.unpack_dense_state_matrix(y_full_tuples: list, n_states: int) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Convert the solver output into one dense real matrix.

Parameters:

• y_full_tuples – Raw solver state history.

• n_states – Number of differential states.

Returns:

Dense state matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_options module

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_options.EraMatrixPencilBand(low_hz: float, high_hz: float)

Bases: object

Immutable-looking light wrapper for one analysis band.

The class exposes explicit getters and setters because the EMT modal workflow needs predictable state inspection when debugging numerical conditioning problems.

get_high_hz() → float

Return the upper analysis frequency.

Returns:

Upper edge in Hz.

get_low_hz() → float

Return the lower analysis frequency.

Returns:

Lower edge in Hz.

property high_hz: float

Property wrapper for VeraGrid style compatibility.

Returns:

Upper edge in Hz.

property low_hz: float

Property wrapper for VeraGrid style compatibility.

Returns:

Lower edge in Hz.

set_high_hz(value: float) → None

Set the upper analysis frequency.

Parameters:

value – Requested upper edge in Hz.

Returns:

None.

set_low_hz(value: float) → None

Set the lower analysis frequency.

Parameters:

value – Requested lower edge in Hz.

Returns:

None.

to_tuple() → Tuple[float, float]

Export the band as a plain tuple.

Returns:

Two-float tuple (low_hz, high_hz).

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_options.EraMatrixPencilOptions(decimation_factor: int = 1, svd_solver: EraSvdSolverType = 0, tol_deflation: float = 1e-08, max_modes: int = 50, t_ringdown: float = 0.5, verbose: int = 0, nominal_frequency_hz: float = 0.0, use_notch_filtering: bool = True, notch_quality_factor: float = 60.0, decimation_safety_factor: float = 10.0, anti_alias_filter_order: int = 8, use_zero_phase_filtering: bool = True, block_rows_ratio: float = 0.35, minimum_block_rows: int = 8, minimum_samples_per_band: int = 64, use_forward_backward: bool = True, use_exponential_detrending: bool = True, maximum_observables: int = 0, min_mode_energy_ratio: float = 0.01, frequency_merge_tolerance_hz: float = 0.5, real_part_merge_tolerance: float = 0.5, principal_log_tolerance_hz: float = 2.0, condition_number_limit: float = 1000000000000.0, analysis_bands: Tuple[Tuple[float, float], ...] | None = None)

Bases: OptionsTemplate

Configuration object for the EMT frequency-zooming matrix pencil engine.

The class keeps the legacy public API while adding the numerical controls required by the multi-band forward-backward TLS formulation.

CLASS_NON_EDITABLE_PROPERTIES: Tuple[str, ...] = ('idtag', 'diff_changes')

CLASS_PROPERTIES_WITH_PROFILE: Dict[str, str] = {}

CLASS_PROPERTY_DECLARATIONS: Tuple[GCProp, ...] = (prop:idtag, prop:name, prop:code, prop:rdfid, prop:action, prop:comment, prop:diff_changes, prop:decimation_factor, prop:svd_solver, prop:tol_deflation, prop:max_modes, prop:t_ringdown, prop:verbose, prop:nominal_frequency_hz, prop:use_notch_filtering, prop:notch_quality_factor, prop:decimation_safety_factor, prop:anti_alias_filter_order, prop:use_zero_phase_filtering, prop:block_rows_ratio, prop:minimum_block_rows, prop:minimum_samples_per_band, prop:use_forward_backward, prop:use_exponential_detrending, prop:maximum_observables, prop:min_mode_energy_ratio, prop:frequency_merge_tolerance_hz, prop:real_part_merge_tolerance, prop:principal_log_tolerance_hz, prop:condition_number_limit)

CLASS_PROPERTY_LIST: Tuple[GCProp, ...] = (prop:idtag, prop:name, prop:code, prop:rdfid, prop:action, prop:comment, prop:diff_changes, prop:decimation_factor, prop:svd_solver, prop:tol_deflation, prop:max_modes, prop:t_ringdown, prop:verbose, prop:nominal_frequency_hz, prop:use_notch_filtering, prop:notch_quality_factor, prop:decimation_safety_factor, prop:anti_alias_filter_order, prop:use_zero_phase_filtering, prop:block_rows_ratio, prop:minimum_block_rows, prop:minimum_samples_per_band, prop:use_forward_backward, prop:use_exponential_detrending, prop:maximum_observables, prop:min_mode_energy_ratio, prop:frequency_merge_tolerance_hz, prop:real_part_merge_tolerance, prop:principal_log_tolerance_hz, prop:condition_number_limit)

CLASS_REGISTERED_PROPERTIES: Dict[str, GCProp] = {'action': prop:action, 'anti_alias_filter_order': prop:anti_alias_filter_order, 'block_rows_ratio': prop:block_rows_ratio, 'code': prop:code, 'comment': prop:comment, 'condition_number_limit': prop:condition_number_limit, 'decimation_factor': prop:decimation_factor, 'decimation_safety_factor': prop:decimation_safety_factor, 'diff_changes': prop:diff_changes, 'frequency_merge_tolerance_hz': prop:frequency_merge_tolerance_hz, 'idtag': prop:idtag, 'max_modes': prop:max_modes, 'maximum_observables': prop:maximum_observables, 'min_mode_energy_ratio': prop:min_mode_energy_ratio, 'minimum_block_rows': prop:minimum_block_rows, 'minimum_samples_per_band': prop:minimum_samples_per_band, 'name': prop:name, 'nominal_frequency_hz': prop:nominal_frequency_hz, 'notch_quality_factor': prop:notch_quality_factor, 'principal_log_tolerance_hz': prop:principal_log_tolerance_hz, 'rdfid': prop:rdfid, 'real_part_merge_tolerance': prop:real_part_merge_tolerance, 'svd_solver': prop:svd_solver, 't_ringdown': prop:t_ringdown, 'tol_deflation': prop:tol_deflation, 'use_exponential_detrending': prop:use_exponential_detrending, 'use_forward_backward': prop:use_forward_backward, 'use_notch_filtering': prop:use_notch_filtering, 'use_zero_phase_filtering': prop:use_zero_phase_filtering, 'verbose': prop:verbose}

LOCAL_PROPERTY_DECLARATIONS: Tuple[GCProp, ...] = (prop:decimation_factor, prop:svd_solver, prop:tol_deflation, prop:max_modes, prop:t_ringdown, prop:verbose, prop:nominal_frequency_hz, prop:use_notch_filtering, prop:notch_quality_factor, prop:decimation_safety_factor, prop:anti_alias_filter_order, prop:use_zero_phase_filtering, prop:block_rows_ratio, prop:minimum_block_rows, prop:minimum_samples_per_band, prop:use_forward_backward, prop:use_exponential_detrending, prop:maximum_observables, prop:min_mode_energy_ratio, prop:frequency_merge_tolerance_hz, prop:real_part_merge_tolerance, prop:principal_log_tolerance_hz, prop:condition_number_limit)

property anti_alias_filter_order: int

Property wrapper for VeraGrid schema access.

Returns:

Positive filter order.

property block_rows_ratio: float

Property wrapper for VeraGrid schema access.

Returns:

Ratio in the interval (0, 1).

property condition_number_limit: float

Property wrapper for VeraGrid schema access.

Returns:

Positive condition-number limit.

property decimation_factor: int

Property wrapper for VeraGrid schema access.

Returns:

Positive decimation cap.

property decimation_safety_factor: float

Property wrapper for VeraGrid schema access.

Returns:

Positive oversampling factor.

property frequency_merge_tolerance_hz: float

Property wrapper for VeraGrid schema access.

Returns:

Frequency tolerance in Hz.

get_analysis_band_limits() → Tuple[Tuple[float, float], ...]

Return the analysis-band plan as plain tuples.

Returns:

Tuple of (low_hz, high_hz) pairs.

get_analysis_bands() → Tuple[EraMatrixPencilBand, ...]

Return the configured analysis-band plan.

Returns:

Tuple of EraMatrixPencilBand objects.

get_anti_alias_filter_order() → int

Return the Butterworth anti-alias filter order.

Returns:

Positive filter order.

get_block_rows_ratio() → float

Return the block-Hankel sizing ratio.

Returns:

Ratio in the interval (0, 1).

get_condition_number_limit() → float

Return the numerical conditioning ceiling.

Returns:

Positive condition-number limit.

get_decimation_factor() → int

Return the legacy manual cap for dynamic decimation.

Returns:

Positive decimation cap.

get_decimation_safety_factor() → float

Return the post-band oversampling safety factor.

Returns:

Positive oversampling factor.

get_frequency_merge_tolerance_hz() → float

Return the frequency tolerance used while merging poles.

Returns:

Frequency tolerance in Hz.

get_max_modes() → int

Return the global maximum number of retained modes.

Returns:

Positive mode cap.

get_maximum_observables() → int

Return the optional cap on the number of observed channels.

Returns:

0 means all channels.

get_min_mode_energy_ratio() → float

Return the minimum retained modal-energy ratio.

Returns:

Positive energy threshold.

get_minimum_block_rows() → int

Return the minimum block-Hankel depth.

Returns:

Minimum block rows.

get_minimum_samples_per_band() → int

Return the minimum number of samples required for one band.

Returns:

Minimum number of samples.

get_nominal_frequency_hz() → float

Return the explicit nominal-frequency override.

Returns:

Frequency in Hz. 0.0 means auto-detect from the grid.

get_notch_quality_factor() → float

Return the notch quality factor.

Returns:

Positive quality factor.

get_principal_log_tolerance_hz() → float

Return the tolerance used while validating principal-log frequencies.

Returns:

Frequency tolerance in Hz.

get_real_part_merge_tolerance() → float

Return the real-part tolerance used while merging poles.

Returns:

Real-part tolerance in 1/s.

get_svd_solver() → EraSvdSolverType

Return the configured SVD backend.

Returns:

SVD backend enum.

get_t_ringdown() → float

Return the EMT ringdown simulation horizon.

Returns:

Time horizon in seconds.

get_tol_deflation() → float

Return the singular-value numerical floor.

Returns:

Positive floor value.

get_use_exponential_detrending() → bool

Return the exponential detrending flag.

Returns:

True when exponential detrending is enabled.

get_use_forward_backward() → bool

Return the forward-backward matrix-pencil flag.

Returns:

True when FBMP is enabled.

get_use_notch_filtering() → bool

Return the notch-filter activation flag.

Returns:

True when the fundamental notch is enabled.

get_use_zero_phase_filtering() → bool

Return the zero-phase filtering flag.

Returns:

True when zero-phase filtering is enabled.

get_verbose() → int

Return the verbosity level.

Returns:

Verbosity level.

property max_modes: int

Property wrapper for VeraGrid schema access.

Returns:

Positive mode cap.

property maximum_observables: int

Property wrapper for VeraGrid schema access.

Returns:

0 means all channels.

property min_mode_energy_ratio: float

Property wrapper for VeraGrid schema access.

Returns:

Positive energy threshold.

property minimum_block_rows: int

Property wrapper for VeraGrid schema access.

Returns:

Minimum block rows.

property minimum_samples_per_band: int

Property wrapper for VeraGrid schema access.

Returns:

Minimum number of samples.

property nominal_frequency_hz: float

Property wrapper for VeraGrid schema access.

Returns:

Frequency in Hz.

property notch_quality_factor: float

Property wrapper for VeraGrid schema access.

Returns:

Positive quality factor.

property principal_log_tolerance_hz: float

Property wrapper for VeraGrid schema access.

Returns:

Frequency tolerance in Hz.

property real_part_merge_tolerance: float

Property wrapper for VeraGrid schema access.

Returns:

Real-part tolerance in 1/s.

set_analysis_bands(band_limits: Tuple[Tuple[float, float], ...] | None) → None

Replace the complete analysis-band plan.

Parameters:

band_limits – Optional tuple of (low_hz, high_hz) pairs.

Returns:

None.

set_anti_alias_filter_order(value: int) → None

Set the Butterworth anti-alias filter order.

Parameters:

value – Requested filter order.

Returns:

None.

set_block_rows_ratio(value: float) → None

Set the block-Hankel sizing ratio.

Parameters:

value – Requested ratio.

Returns:

None.

set_condition_number_limit(value: float) → None

Set the numerical conditioning ceiling.

Parameters:

value – Requested condition-number limit.

Returns:

None.

set_decimation_factor(value: int) → None

Set the legacy manual cap for dynamic decimation.

Parameters:

value – Requested cap.

Returns:

None.

set_decimation_safety_factor(value: float) → None

Set the post-band oversampling safety factor.

Parameters:

value – Requested oversampling factor.

Returns:

None.

set_frequency_merge_tolerance_hz(value: float) → None

Set the frequency tolerance used while merging poles.

Parameters:

value – Requested tolerance in Hz.

Returns:

None.

set_max_modes(value: int) → None

Set the global maximum number of retained modes.

Parameters:

value – Requested mode cap.

Returns:

None.

set_maximum_observables(value: int) → None

Set the optional cap on the number of observed channels.

Parameters:

value – Requested cap. 0 means all channels.

Returns:

None.

set_min_mode_energy_ratio(value: float) → None

Set the minimum retained modal-energy ratio.

Parameters:

value – Requested energy threshold.

Returns:

None.

set_minimum_block_rows(value: int) → None

Set the minimum block-Hankel depth.

Parameters:

value – Requested minimum block rows.

Returns:

None.

set_minimum_samples_per_band(value: int) → None

Set the minimum number of samples required for one band.

Parameters:

value – Requested minimum number of samples.

Returns:

None.

set_nominal_frequency_hz(value: float) → None

Set the explicit nominal-frequency override.

Parameters:

value – Frequency in Hz. 0.0 means auto.

Returns:

None.

set_notch_quality_factor(value: float) → None

Set the notch quality factor.

Parameters:

value – Requested quality factor.

Returns:

None.

set_principal_log_tolerance_hz(value: float) → None

Set the tolerance used while validating principal-log frequencies.

Parameters:

value – Requested tolerance in Hz.

Returns:

None.

set_real_part_merge_tolerance(value: float) → None

Set the real-part tolerance used while merging poles.

Parameters:

value – Requested tolerance in 1/s.

Returns:

None.

set_svd_solver(value: EraSvdSolverType) → None

Set the configured SVD backend.

Parameters:

value – Requested SVD backend.

Returns:

None.

set_t_ringdown(value: float) → None

Set the EMT ringdown simulation horizon.

Parameters:

value – Requested time horizon in seconds.

Returns:

None.

set_tol_deflation(value: float) → None

Set the singular-value numerical floor.

Parameters:

value – Requested floor.

Returns:

None.

set_use_exponential_detrending(value: bool) → None

Set the exponential detrending flag.

Parameters:

value – Requested flag.

Returns:

None.

set_use_forward_backward(value: bool) → None

Set the forward-backward matrix-pencil flag.

Parameters:

value – Requested flag.

Returns:

None.

set_use_notch_filtering(value: bool) → None

Set the notch-filter activation flag.

Parameters:

value – Requested flag.

Returns:

None.

set_use_zero_phase_filtering(value: bool) → None

Set the zero-phase filtering flag.

Parameters:

value – Requested flag.

Returns:

None.

set_verbose(value: int) → None

Set the verbosity level.

Parameters:

value – Requested verbosity level.

Returns:

None.

property svd_solver: EraSvdSolverType

Property wrapper for VeraGrid schema access.

Returns:

SVD backend enum.

property t_ringdown: float

Property wrapper for VeraGrid schema access.

Returns:

Time horizon in seconds.

property tol_deflation: float

Property wrapper for VeraGrid schema access.

Returns:

Positive floor value.

property use_exponential_detrending: bool

Property wrapper for VeraGrid schema access.

Returns:

True when exponential detrending is enabled.

property use_forward_backward: bool

Property wrapper for VeraGrid schema access.

Returns:

True when FBMP is enabled.

property use_notch_filtering: bool

Property wrapper for VeraGrid schema access.

Returns:

True when the fundamental notch is enabled.

property use_zero_phase_filtering: bool

Property wrapper for VeraGrid schema access.

Returns:

True when zero-phase filtering is enabled.

property verbose: int

Property wrapper for VeraGrid schema access.

Returns:

Verbosity level.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_options.build_era_analysis_bands_from_pairs(band_limits: Tuple[Tuple[float, float], ...] | None) → Tuple[EraMatrixPencilBand, ...]

Convert raw tuple pairs into validated analysis-band objects.

Parameters:

band_limits – Optional tuple of (low_hz, high_hz) pairs.

Returns:

Sanitized tuple of EraMatrixPencilBand objects.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_options.create_default_era_analysis_bands() → Tuple[EraMatrixPencilBand, ...]

Build the default multi-band plan for EMT modal zooming.

Returns:

Tuple of default analysis bands.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results module

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.EraMatrixPencilResults(eigenvalues_s: ndarray[tuple[Any, ...], dtype[complex128]], residues: ndarray[tuple[Any, ...], dtype[complex128]] | None = None, modal_energy: ndarray[tuple[Any, ...], dtype[float64]] | None = None, reconstruction_errors: ndarray[tuple[Any, ...], dtype[float64]] | None = None, band_low_hz: ndarray[tuple[Any, ...], dtype[float64]] | None = None, band_high_hz: ndarray[tuple[Any, ...], dtype[float64]] | None = None, selected_orders: ndarray[tuple[Any, ...], dtype[int64]] | None = None, observable_count_per_mode: ndarray[tuple[Any, ...], dtype[int64]] | None = None, observable_names: List[str] | None = None)

Bases: ResultsTemplate

Detailed results container for the EMT frequency-zooming matrix pencil.

The class stores the fused continuous-time poles together with the residue matrix, modal energy and the provenance of each accepted band estimate.

CLASS_DATA_VARIABLES = {'band_high_hz': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'band_low_hz': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'damping_ratios': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'eigenvalues_s': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'frequencies_hz': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'is_stable': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'modal_energy': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'observable_count_per_mode': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'reconstruction_errors': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'residues': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'selected_orders': <VeraGridEngine.Simulations.results_template.ResultsProperty object>}

CLASS_RESULTS_DECLARATIONS = (<VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>)

LOCAL_RESULTS_DECLARATIONS = (<VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>)

property band_high_hz: ndarray[tuple[Any, ...], dtype[float64]]

Return the upper edge of the source band for each mode.

Returns:

Upper-band vector in Hz.

property band_low_hz: ndarray[tuple[Any, ...], dtype[float64]]

Return the lower edge of the source band for each mode.

Returns:

Lower-band vector in Hz.

property damping_ratios: ndarray[tuple[Any, ...], dtype[float64]]

Return modal damping ratios.

Returns:

Damping-ratio vector.

property eigenvalues_s: ndarray[tuple[Any, ...], dtype[complex128]]

Return the continuous-time poles.

Returns:

Complex pole vector.

property frequencies_hz: ndarray[tuple[Any, ...], dtype[float64]]

Return modal frequencies in Hz.

Returns:

Frequency vector in Hz.

get_eigenvalues() → ndarray[tuple[Any, ...], dtype[complex128]]

Backward-compatible accessor used by older callers.

Returns:

Complex pole vector.

get_modal_energy() → ndarray[tuple[Any, ...], dtype[float64]]

Return the relative modal-energy vector.

Returns:

Modal-energy vector.

get_observable_names() → List[str]

Return the observable labels used during extraction.

Returns:

List of observable names.

get_residues() → ndarray[tuple[Any, ...], dtype[complex128]]

Return the complex residue matrix.

Returns:

Complex residue matrix.

property is_stable: ndarray[tuple[Any, ...], dtype[bool]]

Return the continuous-time stability mask.

Returns:

Stability mask.

mdl(result_type: ResultTypes) → ResultsTable

Export a VeraGrid ResultsTable view.

Parameters:

result_type – Requested result type.

Returns:

Results table for the GUI.

property modal_energy: ndarray[tuple[Any, ...], dtype[float64]]

Return the relative modal-energy vector.

Returns:

Modal-energy vector.

property observable_count_per_mode: ndarray[tuple[Any, ...], dtype[int64]]

Return how many channels participated in each mode estimate.

Returns:

Integer vector with the number of observables per mode.

property reconstruction_errors: ndarray[tuple[Any, ...], dtype[float64]]

Return the reconstruction error attached to each mode.

Returns:

Reconstruction-error vector.

property residues: ndarray[tuple[Any, ...], dtype[complex128]]

Return the complex residue matrix.

Returns:

Complex residue matrix.

property selected_orders: ndarray[tuple[Any, ...], dtype[int64]]

Return the selected subspace order for each mode.

Returns:

Integer vector of selected orders.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.build_empty_bool_vector() → ndarray[tuple[Any, ...], dtype[bool]]

Build one empty boolean vector with the engine canonical dtype.

Returns:

Empty boolean vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.build_empty_complex_matrix() → ndarray[tuple[Any, ...], dtype[complex128]]

Build one empty complex matrix with the engine canonical dtype.

Returns:

Empty complex128 matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.build_empty_complex_vector() → ndarray[tuple[Any, ...], dtype[complex128]]

Build one empty complex vector with the engine canonical dtype.

Returns:

Empty complex128 vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.build_empty_float_vector() → ndarray[tuple[Any, ...], dtype[float64]]

Build one empty real vector with the engine canonical dtype.

Returns:

Empty float64 vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.build_empty_int_vector() → ndarray[tuple[Any, ...], dtype[int64]]

Build one empty integer vector with the engine canonical dtype.

Returns:

Empty integer vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.build_modes_results_table_data(results: EraMatrixPencilResults) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Build the numeric table used by the VeraGrid mode browser.

Parameters:

results – Result container.

Returns:

Dense 2-D numeric matrix.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.compute_damping_ratios_from_poles(eigenvalues_s: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[float64]]

Compute damping ratios from continuous-time poles.

Parameters:

eigenvalues_s – Continuous-time poles.

Returns:

Damping-ratio vector.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.compute_frequencies_from_poles(eigenvalues_s: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[float64]]

Compute modal frequencies in Hz from continuous-time poles.

Parameters:

eigenvalues_s – Continuous-time poles.

Returns:

Frequency vector in Hz.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.era_matrix_pencil_results.compute_stability_mask_from_poles(eigenvalues_s: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[bool]]

Compute the linear stability mask from continuous-time poles.

Parameters:

eigenvalues_s – Continuous-time poles.

Returns:

Boolean stability mask.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_driver module

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_driver.BestPack

Bases: object

Data structure to hold the best Ritz pairs found during restarts.

U_sel: ndarray[tuple[Any, ...], dtype[complex128]] | None

max_rr: float

mu_sel: ndarray[tuple[Any, ...], dtype[complex128]] | None

rel: ndarray[tuple[Any, ...], dtype[float64]] | None

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_driver.RobustBlockArnoldiEngine(monodromy_op: BlockEmtFloquetOperator, n_states: int, p_init: int, max_iters: int, tol_deflation: float = 1e-12)

Bases: object

Implements: 1. Block Modified Gram-Schmidt (BMGS). 2. DGKS/Kahan Re-orthogonalization (“Twice is Enough”). 3. Rank-Revealing SVD for Block Deflation.

H

V

block_indices

build_krylov_space(V_init: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]) → Tuple[ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]]

Executes the robust Block Arnoldi process to build the Krylov subspace.

Parameters:

V_init – The initial orthonormal block seed (n_states x p_init).

Returns:

A tuple (V_final, H_final) representing the Krylov basis and Hessenberg matrix.

max_iters

monodromy_op

n

p_active

p_init

tol_deflation

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_driver.SmallSignalStabilityEmtDriver(grid: MultiCircuit, problem: EmtProblemTemplate, emt_options: EmtOptions, options: EmtSmallSignalStabilityOptions)

Bases: DriverTemplate

Base class for EMT Floquet stability analysis. Orchestrates the entire limit cycle capture and Krylov subspace generation workflow.

emt_options: EmtOptions

options: EmtSmallSignalStabilityOptions

problem: EmtProblemTemplate

run()

Executes the analysis based on the selected builder type in the options.

run_arnoldi()

Executes the Standard Arnoldi Floquet analysis using SciPy ARPACK. Suited for small-to-medium systems.

run_arnoldi_hybrid()

Executes the Hybrid Block-Arnoldi (BIRAM) Floquet analysis. Suited for extremely large sparse DAE systems utilizing BLAS-3 acceleration and robust block projection to handle invariant subspace degeneracy.

VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_driver.build_restart_seed(U_sel: ndarray[tuple[Any, ...], dtype[complex128]], p_target: int, seed: int = 42) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]]

Builds a real orthonormal restart block from complex Ritz/refined vectors. Extracts real and imaginary parts to form a strictly real subspace seed.

Parameters:

• U_sel – Complex matrix of selected Ritz or Refined vectors.

• p_target – Desired number of columns (block size) for the restart seed.

• seed – Random seed for generating orthogonal padding if needed.

Returns:

A real orthonormal block matrix of shape (n_states, p_target).

VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_options module

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_options.EmtSmallSignalStabilityOptions(k: int = 6, target_period: float = 0.02, target_frequency_hz: float = None, max_krylov_dim: int = 30, ss_assessment_time: float = 0.1, verbose: int = 0, max_restarts: int = 4, restart_tol: float = 1e-06, use_refined_ritz: bool = True, adaptive_restart: bool = True, stagnation_improve_ratio: float = 0.9, stagnation_patience: int = 2, deflation_tol: float = 1e-12, prefer_ak_operator: bool = True, use_numba_kernels: bool = True, min_block_size: int | None = None, max_block_size: int | None = None, max_krylov_dim_cap: int | None = None, build_type: SmallSignalEmtBuildTypes = Arnoldi)

Bases: OptionsTemplate

EmtFloquetOptions

Parameters

kint

Number of Floquet multipliers to be calculated.

target_periodfloat

Period of the periodic orbit in seconds (e.g., 0.02 for 50 Hz).

target_frequency_hzfloat | None

Specific oscillation frequency to target. None for standard analysis.

max_krylov_dimint

Nominal Krylov subspace dimension budget for each restart cycle.

ss_assessment_timefloat

Time to simulate before starting Floquet to ensure steady-state (s).

verboseint

Verbosity level.

Restart / robustness knobs

max_restartsint

Maximum number of explicit restart cycles (total cycles = max_restarts + 1).

restart_tolfloat

Relative residual tolerance for converged Ritz pairs.

use_refined_ritzbool

Use refined Ritz vectors to seed restarts and improve convergence robustness.

adaptive_restartbool

Enable residual-stagnation detection with elastic block/depth adaptation.

stagnation_improve_ratiofloat

If residual improvement is worse than this factor, adaptation is triggered.

stagnation_patienceint

Number of cycles to observe before declaring stagnation.

deflation_tolfloat

Singular-value threshold for block deflation.

Performance knobs

prefer_ak_operatorbool

Prefer an explicit EMT A_k operator if the problem exposes it.

use_numba_kernelsbool

Enable Numba-accelerated kernels (BMGS / A_k block propagator) when available.

min_block_size, max_block_sizeint | None

Elastic block-size limits for restarted Block-Arnoldi.

max_krylov_dim_capint | None

Upper cap for adaptive Krylov dimension expansion.

CLASS_NON_EDITABLE_PROPERTIES: Tuple[str, ...] = ('idtag', 'diff_changes')

CLASS_PROPERTIES_WITH_PROFILE: Dict[str, str] = {}

CLASS_PROPERTY_DECLARATIONS: Tuple[GCProp, ...] = (prop:idtag, prop:name, prop:code, prop:rdfid, prop:action, prop:comment, prop:diff_changes, prop:k, prop:target_period, prop:target_frequency_hz, prop:max_krylov_dim, prop:ss_assessment_time, prop:verbose, prop:max_restarts, prop:restart_tol, prop:use_refined_ritz, prop:adaptive_restart, prop:stagnation_improve_ratio, prop:stagnation_patience, prop:deflation_tol, prop:prefer_ak_operator, prop:use_numba_kernels, prop:min_block_size, prop:max_block_size, prop:max_krylov_dim_cap, prop:build_type)

CLASS_PROPERTY_LIST: Tuple[GCProp, ...] = (prop:idtag, prop:name, prop:code, prop:rdfid, prop:action, prop:comment, prop:diff_changes, prop:k, prop:target_period, prop:target_frequency_hz, prop:max_krylov_dim, prop:ss_assessment_time, prop:verbose, prop:max_restarts, prop:restart_tol, prop:use_refined_ritz, prop:adaptive_restart, prop:stagnation_improve_ratio, prop:stagnation_patience, prop:deflation_tol, prop:prefer_ak_operator, prop:use_numba_kernels, prop:min_block_size, prop:max_block_size, prop:max_krylov_dim_cap, prop:build_type)

CLASS_REGISTERED_PROPERTIES: Dict[str, GCProp] = {'action': prop:action, 'adaptive_restart': prop:adaptive_restart, 'build_type': prop:build_type, 'code': prop:code, 'comment': prop:comment, 'deflation_tol': prop:deflation_tol, 'diff_changes': prop:diff_changes, 'idtag': prop:idtag, 'k': prop:k, 'max_block_size': prop:max_block_size, 'max_krylov_dim': prop:max_krylov_dim, 'max_krylov_dim_cap': prop:max_krylov_dim_cap, 'max_restarts': prop:max_restarts, 'min_block_size': prop:min_block_size, 'name': prop:name, 'prefer_ak_operator': prop:prefer_ak_operator, 'rdfid': prop:rdfid, 'restart_tol': prop:restart_tol, 'ss_assessment_time': prop:ss_assessment_time, 'stagnation_improve_ratio': prop:stagnation_improve_ratio, 'stagnation_patience': prop:stagnation_patience, 'target_frequency_hz': prop:target_frequency_hz, 'target_period': prop:target_period, 'use_numba_kernels': prop:use_numba_kernels, 'use_refined_ritz': prop:use_refined_ritz, 'verbose': prop:verbose}

LOCAL_PROPERTY_DECLARATIONS: Tuple[GCProp, ...] = (prop:k, prop:target_period, prop:target_frequency_hz, prop:max_krylov_dim, prop:ss_assessment_time, prop:verbose, prop:max_restarts, prop:restart_tol, prop:use_refined_ritz, prop:adaptive_restart, prop:stagnation_improve_ratio, prop:stagnation_patience, prop:deflation_tol, prop:prefer_ak_operator, prop:use_numba_kernels, prop:min_block_size, prop:max_block_size, prop:max_krylov_dim_cap, prop:build_type)

action: ActionType

comment: str

device_type: DeviceType

diff_changes

selected_to_merge

VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_results module

class VeraGridEngine.Simulations.SmallSignalStabilityEmt.small_signal_stability_emt_results.SmallSignalStabilityEmtResults(multipliers: ndarray[tuple[Any, ...], dtype[complex128]], right_vecs: ndarray[tuple[Any, ...], dtype[complex128]], left_vecs: ndarray[tuple[Any, ...], dtype[complex128]], period: float, stat_vars: List[Var])

Bases: ResultsTemplate

Container and processor for EMT Floquet Small-Signal Stability results.

Handles the mapping of discrete Floquet multipliers (Z-domain) to continuous eigenvalues (S-domain), computes bi-orthonormal participation factors, and interfaces with the VeraGrid UI for plotting and reporting.

EmtFloquetResults :param multipliers: Floquet multipliers (eigenvalues of Monodromy Matrix) :param right_vecs: Right eigenvectors (columns) :param left_vecs: Left eigenvectors from adjoint problem (columns) :param period: Cycle period T (s) :param stat_vars: List of state variables

CLASS_DATA_VARIABLES = {'conjugate_frequencies': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'damping_ratios': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'eigenvalues': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'left_vecs': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'multipliers': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'participation_factors': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'period': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'right_vecs': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'stat_vars_array': <VeraGridEngine.Simulations.results_template.ResultsProperty object>}

CLASS_RESULTS_DECLARATIONS = (<VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>)

LOCAL_RESULTS_DECLARATIONS = (<VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>, <VeraGridEngine.Simulations.results_template.ResultsProperty object>)

conjugate_frequencies

damping_ratios

eigenvalues

left_vecs

mdl(result_type: ResultTypes) → ResultsTable

Export results as ResultsTable for the VeraGrid UI/Engine.

multipliers

participation_factors

period

report_stability() → str

Generates a standard stability report string based on the spectral radius.

Returns:

Formatted stability assessment string.

right_vecs

stat_vars

stat_vars_array

validate_spectral_gaps(h_step: float) → Tuple[ndarray[tuple[Any, ...], dtype[bool]], ndarray[tuple[Any, ...], dtype[float64]]]

Evaluates the metric compactness of ALL calculated modes. Uses the discretization step (h) as the numerical noise floor (tolerance).

Parameters:

h_step – Problem integration step (e.g., 1e-4)

Returns:

Tuple (is_isolated_array, spectral_gaps_array)

Module contents