VeraGridEngine.Simulations.SmallSignalStabilityRms package

Submodules

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver module

class VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.SmallSignalStabilityRmsDriver(grid: MultiCircuit, rms_options: RmsOptions | None = None, sss_options: RmsSmallSignalStabilityOptions | None = None, pf_results: PowerFlowResults | None = None, engine: EngineType = VeraGrid)

Bases: DriverTemplate

Small Signal Stability RMS driver

assessment_time

integration_methods_dict: dict[DynamicIntegrationMethod, type]

k

name = 'Small Signal Stability Simulation'

problem

results: SmallSignalStabilityRmsResults

rms_options: RmsOptions

run() → None

Main function to initialize and run the system simulation.

This function sets up logging, starts the dynamic simulation, and logs the outcome. It handles and logs any exceptions raised during execution. :return:

run_small_signal_stability() → None

Performs the numerical integration using the chosen method and the small signal stability assessment. :return:

sss_options: RmsSmallSignalStabilityOptions

tpe = 'RMS Small Signal stability'

class VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.SparseGeneralizedShiftInvertMethods(n_states: int, total_size: int, J_aug_lu, E: spmatrix)

Bases: object

Helper class to hold the matvec and rmatvec operations for the Sparse LinearOperator for generalized eigenvalues.

E

J_aug_lu

matvec(v: ndarray) → ndarray

n_states

rmatvec(v: ndarray) → ndarray

total_size

class VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.SparseShiftAndInvertMethods(n_states: int, total_size: int, J_aug_lu: SuperLU)

Bases: object

Helper class to hold the matvec and rmatvec operations for the Sparse LinearOperator.

J_aug_lu: SuperLU

matvec(b: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Matrix-vector multiplication.

Parameters:

b (Vec) – Input vector.

Returns:

Result vector.

n_states: int

rmatvec(b: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Adjoint matrix-vector multiplication.

Parameters:

b (Vec) – Input vector.

Returns:

Result vector.

total_size: int

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.compute_damping_ratios_and_frequencies(eigenvalues: ndarray[tuple[Any, ...], dtype[float64]], eig_no_conjugates: ndarray[tuple[Any, ...], dtype[float64]]) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

Parameters:

• eigenvalues – row np array with modes

• eig_no_conjugates – row np array with only the positive complex conjugate modes

Returns:

damping_ratios: list with damping ratios for the positive complex conjugate modes. Nan for other modes

Returns:

conjugate_frequencies: list with oscillation frequencies for the positive complex conjugate modes. Nan for other modes

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.compute_participation_factors(v: ndarray, w: ndarray) → ndarray

Calculates normalized participation factors correctly for both dense and sparse. Compatible with strict Numba (without keep dims). :param v: right eigenvectors (columns) - should be complex128 :param w: left eigenvectors (columns) - should be complex128 :return PF_norm: Return normalized participation factors

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.compute_participation_factors_generalized(v: ndarray, w: ndarray, E: ndarray | spmatrix) → ndarray

Participation factors for generalized eigenproblems A x = lambda E x. Normalization uses w^T E v = 1 per mode.

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.compute_state_matrix(problem: RmsProblemTemplate, x: ndarray[tuple[Any, ...], dtype[float64]], dx: ndarray[tuple[Any, ...], 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]]]

Small Signal Stability analysis state matrix computation. Handles rank-deficient (singular) Jacobian matrices using SVD-based pseudo-inverse. :param problem: RmsProblemTemplate :param x: Vec. Variables value at assessment time :param dx: Vec. Derivatives value at assessment time :return

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.plot_stability(eigenvalues: ndarray[tuple[Any, ...], dtype[float64]], plot_units: str = 'rad/s') → None

Parameters:

• eigenvalues – row np array with modes

• plot_units – string with the imaginary units “rad/s” or “Hz”

Returns:

plot S-domain modes

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.run_dense_small_signal_stability(problem: RmsProblemTemplate, x: ndarray[tuple[Any, ...], dtype[float64]], dx: ndarray[tuple[Any, ...], dtype[float64]], verbose: int = 0) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], None]

Run small signal stability analysis using dense matrices calculations. The operation returns all the eigenvalues. :param problem: RmsProblemTemplate :param x: Vec. Variables value at assessment time :param dx: Vec. Derivatives value at assessment time :param verbose: verbosity :return eigenvalues: Vec. Modes :return participation_factors: Mat. Normalized participation factors :return damping_ratios: Vec. Damping ratios of oscillatory modes. :return conjugate_freq: Vec. Frequency of oscillatory modes. :return A_orig: Mat. Original state matrix

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.run_sparse_small_signal_stability(problem: RmsProblemTemplate, x: ndarray[tuple[Any, ...], dtype[float64]], dx: ndarray[tuple[Any, ...], dtype[float64]], k: int, verbose: int = 0) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], None]

Run small signal stability analysis using sparse matrices calculations. The operation returns k eigenvalues. :param problem: RmsProblemTemplate :param x: Vec. Variables value at assessment time :param dx: Vec. Derivatives value at assessment time :param k: int. Number of modes to be calculated. k max = N-2 :param verbose: verbosity :return eigenvalues: Vec. Modes :return participation_factors: Mat. Normalized participation factors :return damping_ratios: Vec. Damping ratios of oscillatory modes. :return conjugate_freq: Vec. Frequency of oscillatory modes. :return A_orig: Mat. Original state matrix

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_driver.select_eigs_without_conjugates(eigenvalues: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Select oscillatory modes. Conjugate modes appear only once in the selection. :param eigenvalues: row np array with modes :return: row np array with only the positive complex conjugate modes

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_options module

class VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_options.RmsSmallSignalStabilityOptions(k: int | None = None, ss_assessment_time: float = 5.0, verbose: int = 0)

Bases: OptionsTemplate

Small Signal Stability RMS simulation options.

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:ss_assessment_time, prop:k, prop:verbose)

CLASS_PROPERTY_LIST: Tuple[GCProp, ...] = (prop:idtag, prop:name, prop:code, prop:rdfid, prop:action, prop:comment, prop:diff_changes, prop:ss_assessment_time, prop:k, prop:verbose)

CLASS_REGISTERED_PROPERTIES: Dict[str, GCProp] = {'action': prop:action, 'code': prop:code, 'comment': prop:comment, 'diff_changes': prop:diff_changes, 'idtag': prop:idtag, 'k': prop:k, 'name': prop:name, 'rdfid': prop:rdfid, 'ss_assessment_time': prop:ss_assessment_time, 'verbose': prop:verbose}

LOCAL_PROPERTY_DECLARATIONS: Tuple[GCProp, ...] = (prop:ss_assessment_time, prop:k, prop:verbose)

k: int | None

ss_assessment_time: float

verbose: int

VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_results module

class VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_results.SPlotInteractionHandler(sc: Any, annot: Any, fig: Any, ax: Any)

Bases: object

Handles interactive annotations and hover events for S-Domain stability plots.

annot: Any

ax: Any

fig: Any

on_hover(event: Any) → None

Hover event callback logic.

sc: Any

update_annotation(ind: dict) → None

Updates the annotation text and position based on the hovered point.

class VeraGridEngine.Simulations.SmallSignalStabilityRms.small_signal_results.SmallSignalStabilityRmsResults(eigenvalues: ndarray[tuple[Any, ...], dtype[float64]], participation_factors: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], damping_ratios: ndarray[tuple[Any, ...], dtype[float64]], conjugate_frequencies: ndarray[tuple[Any, ...], dtype[float64]], state_matrix: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]], stat_vars: List[Var])

Bases: ResultsTemplate

Small-signal Analysis results storage and visualization.

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>, 'participation_factors': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'stat_vars_array': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'state_matrix': <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>)

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

conjugate_frequencies: Vec

damping_ratios: Vec

eigenvalues: Vec

mdl(result_type: ResultTypes) → ResultsTable

Export the results as a ResultsTable for plotting.

participation_factors: Mat

stat_vars_array: Vec

state_matrix: Mat

Module contents