VeraGridEngine.Simulations.EMT package

Subpackages

Submodules

VeraGridEngine.Simulations.EMT.emt_driver module

class VeraGridEngine.Simulations.EMT.emt_driver.EmtSimulationDriver(grid: MultiCircuit, options: EmtOptions, pf_results_3ph: PowerFlowResults3Ph | None = None, pf_results: PowerFlowResults | None = None, engine: EngineType = VeraGrid)[source]

Bases: DriverTemplate

line_states

name = 'EMT Simulation'

options

pf_results: PowerFlowResults | None

pf_results_3Ph: PowerFlowResults3Ph | None

problem: EmtProblemDae | None

run() → None[source]

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_time_simulation() → None[source]: Performs the EMTP loop using the chosen method. :return:

tpe = 'EMT Dynamic': Dynamic wrapper to use with Qt

VeraGridEngine.Simulations.EMT.emt_options module

class VeraGridEngine.Simulations.EMT.emt_options.EmtOptions(time_step: float = 5e-06, simulation_time: float = 0.02, tolerance: float = 1e-06, solver_type: EmtSolverTypes = structuralAD, integration_method: DynamicIntegrationMethod = DAE_Trapezoidal, verbose: int = 0, initialization_method: EmtInitializationMethod = Auto, problem_type: EmtProblemTypes = EmtProblemDae, init_newton_tol: float = 1e-08, init_newton_max_iter: int = 20, init_newton_backtracking: bool = True, init_dense_threshold: int = 48, init_ptc_dtau0: float = 1.0, init_ptc_dtau_min: float = 1e-06, init_ptc_dtau_max: float = 10.0, init_ptc_max_iter: int = 60, init_allow_state_equilibrium: bool = True, init_fix_pf_bus_voltages: bool = False, newton_compute_dense_cond: bool = False, newton_enable_fallback: bool = False, newton_enable_index1_check: bool = False, newton_enable_backtracking: bool = False, newton_step_norm_explode: float = 1000000.0, newton_dense_cond_warn: float = 1000000000000.0, newton_dense_cond_max_n: int = 600, newton_index1_max_block_n: int = 128, newton_index1_warn_pivot_ratio: float = 1e-10, newton_index1_fail_pivot_ratio: float = 1e-14, newton_backtracking_beta: float = 0.5, newton_backtracking_min_alpha: float = 0.0001, newton_backtracking_max_iter: int = 6, compiled_warmup_policy: StructuralCompiledWarmupPolicy = StructuralCompiledWarmupPolicy.Adaptive, sparse_solver: SparseSolver = SuperLU, external_sparse_solver_directory: str = '', external_sparse_solver_plugin_name: str = '', allow_internal_sparse_fallback: bool = True, fmi_state_event_time_tolerance: float = 1e-09, fmi_state_event_max_iterations: int = 32, fmi_me_newton_absolute_tolerance: float = 1e-08, fmi_me_newton_relative_tolerance: float = 1e-08, fmi_me_newton_max_iterations: int = 20, fmi_me_max_continuous_states: int = 128, fmi_me_max_runtime_evaluations_per_step: int = 100000)[source]

Bases: OptionsTemplate

EMT simulation options

CLASS_NON_EDITABLE_PROPERTIES: Tuple[str, ...] = ('idtag', 'selected_to_merge', '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:selected_to_merge, prop:comment, prop:diff_changes, prop:time_step, prop:simulation_time, prop:tolerance, prop:solver_type, prop:integration_method, prop:verbose, prop:initialization_method, prop:problem_type, prop:init_newton_tol, prop:init_newton_max_iter, prop:init_newton_backtracking, prop:init_dense_threshold, prop:init_ptc_dtau0, prop:init_ptc_dtau_min, prop:init_ptc_dtau_max, prop:init_ptc_max_iter, prop:init_allow_state_equilibrium, prop:init_fix_pf_bus_voltages, prop:newton_compute_dense_cond, prop:newton_enable_fallback, prop:newton_enable_index1_check, prop:newton_enable_backtracking, prop:newton_step_norm_explode, prop:newton_dense_cond_warn, prop:newton_dense_cond_max_n, prop:newton_index1_max_block_n, prop:newton_index1_warn_pivot_ratio, prop:newton_index1_fail_pivot_ratio, prop:newton_backtracking_beta, prop:newton_backtracking_min_alpha, prop:newton_backtracking_max_iter, prop:compiled_warmup_policy, prop:sparse_solver, prop:external_sparse_solver_directory, prop:external_sparse_solver_plugin_name, prop:allow_internal_sparse_fallback, prop:fmi_state_event_time_tolerance, prop:fmi_state_event_max_iterations, prop:fmi_me_newton_absolute_tolerance, prop:fmi_me_newton_relative_tolerance, prop:fmi_me_newton_max_iterations, prop:fmi_me_max_continuous_states, prop:fmi_me_max_runtime_evaluations_per_step)

CLASS_PROPERTY_LIST: Tuple[GCProp, ...] = (prop:idtag, prop:name, prop:code, prop:rdfid, prop:action, prop:selected_to_merge, prop:comment, prop:diff_changes, prop:time_step, prop:simulation_time, prop:tolerance, prop:solver_type, prop:integration_method, prop:verbose, prop:initialization_method, prop:problem_type, prop:init_newton_tol, prop:init_newton_max_iter, prop:init_newton_backtracking, prop:init_dense_threshold, prop:init_ptc_dtau0, prop:init_ptc_dtau_min, prop:init_ptc_dtau_max, prop:init_ptc_max_iter, prop:init_allow_state_equilibrium, prop:init_fix_pf_bus_voltages, prop:newton_compute_dense_cond, prop:newton_enable_fallback, prop:newton_enable_index1_check, prop:newton_enable_backtracking, prop:newton_step_norm_explode, prop:newton_dense_cond_warn, prop:newton_dense_cond_max_n, prop:newton_index1_max_block_n, prop:newton_index1_warn_pivot_ratio, prop:newton_index1_fail_pivot_ratio, prop:newton_backtracking_beta, prop:newton_backtracking_min_alpha, prop:newton_backtracking_max_iter, prop:compiled_warmup_policy, prop:sparse_solver, prop:external_sparse_solver_directory, prop:external_sparse_solver_plugin_name, prop:allow_internal_sparse_fallback, prop:fmi_state_event_time_tolerance, prop:fmi_state_event_max_iterations, prop:fmi_me_newton_absolute_tolerance, prop:fmi_me_newton_relative_tolerance, prop:fmi_me_newton_max_iterations, prop:fmi_me_max_continuous_states, prop:fmi_me_max_runtime_evaluations_per_step)

CLASS_REGISTERED_PROPERTIES: Dict[str, GCProp] = {'action': prop:action, 'allow_internal_sparse_fallback': prop:allow_internal_sparse_fallback, 'code': prop:code, 'comment': prop:comment, 'compiled_warmup_policy': prop:compiled_warmup_policy, 'diff_changes': prop:diff_changes, 'external_sparse_solver_directory': prop:external_sparse_solver_directory, 'external_sparse_solver_plugin_name': prop:external_sparse_solver_plugin_name, 'fmi_me_max_continuous_states': prop:fmi_me_max_continuous_states, 'fmi_me_max_runtime_evaluations_per_step': prop:fmi_me_max_runtime_evaluations_per_step, 'fmi_me_newton_absolute_tolerance': prop:fmi_me_newton_absolute_tolerance, 'fmi_me_newton_max_iterations': prop:fmi_me_newton_max_iterations, 'fmi_me_newton_relative_tolerance': prop:fmi_me_newton_relative_tolerance, 'fmi_state_event_max_iterations': prop:fmi_state_event_max_iterations, 'fmi_state_event_time_tolerance': prop:fmi_state_event_time_tolerance, 'idtag': prop:idtag, 'init_allow_state_equilibrium': prop:init_allow_state_equilibrium, 'init_dense_threshold': prop:init_dense_threshold, 'init_fix_pf_bus_voltages': prop:init_fix_pf_bus_voltages, 'init_newton_backtracking': prop:init_newton_backtracking, 'init_newton_max_iter': prop:init_newton_max_iter, 'init_newton_tol': prop:init_newton_tol, 'init_ptc_dtau0': prop:init_ptc_dtau0, 'init_ptc_dtau_max': prop:init_ptc_dtau_max, 'init_ptc_dtau_min': prop:init_ptc_dtau_min, 'init_ptc_max_iter': prop:init_ptc_max_iter, 'initialization_method': prop:initialization_method, 'integration_method': prop:integration_method, 'name': prop:name, 'newton_backtracking_beta': prop:newton_backtracking_beta, 'newton_backtracking_max_iter': prop:newton_backtracking_max_iter, 'newton_backtracking_min_alpha': prop:newton_backtracking_min_alpha, 'newton_compute_dense_cond': prop:newton_compute_dense_cond, 'newton_dense_cond_max_n': prop:newton_dense_cond_max_n, 'newton_dense_cond_warn': prop:newton_dense_cond_warn, 'newton_enable_backtracking': prop:newton_enable_backtracking, 'newton_enable_fallback': prop:newton_enable_fallback, 'newton_enable_index1_check': prop:newton_enable_index1_check, 'newton_index1_fail_pivot_ratio': prop:newton_index1_fail_pivot_ratio, 'newton_index1_max_block_n': prop:newton_index1_max_block_n, 'newton_index1_warn_pivot_ratio': prop:newton_index1_warn_pivot_ratio, 'newton_step_norm_explode': prop:newton_step_norm_explode, 'problem_type': prop:problem_type, 'rdfid': prop:rdfid, 'selected_to_merge': prop:selected_to_merge, 'simulation_time': prop:simulation_time, 'solver_type': prop:solver_type, 'sparse_solver': prop:sparse_solver, 'time_step': prop:time_step, 'tolerance': prop:tolerance, 'verbose': prop:verbose}

LOCAL_PROPERTY_DECLARATIONS: Tuple[GCProp, ...] = (prop:time_step, prop:simulation_time, prop:tolerance, prop:solver_type, prop:integration_method, prop:verbose, prop:initialization_method, prop:problem_type, prop:init_newton_tol, prop:init_newton_max_iter, prop:init_newton_backtracking, prop:init_dense_threshold, prop:init_ptc_dtau0, prop:init_ptc_dtau_min, prop:init_ptc_dtau_max, prop:init_ptc_max_iter, prop:init_allow_state_equilibrium, prop:init_fix_pf_bus_voltages, prop:newton_compute_dense_cond, prop:newton_enable_fallback, prop:newton_enable_index1_check, prop:newton_enable_backtracking, prop:newton_step_norm_explode, prop:newton_dense_cond_warn, prop:newton_dense_cond_max_n, prop:newton_index1_max_block_n, prop:newton_index1_warn_pivot_ratio, prop:newton_index1_fail_pivot_ratio, prop:newton_backtracking_beta, prop:newton_backtracking_min_alpha, prop:newton_backtracking_max_iter, prop:compiled_warmup_policy, prop:sparse_solver, prop:external_sparse_solver_directory, prop:external_sparse_solver_plugin_name, prop:allow_internal_sparse_fallback, prop:fmi_state_event_time_tolerance, prop:fmi_state_event_max_iterations, prop:fmi_me_newton_absolute_tolerance, prop:fmi_me_newton_relative_tolerance, prop:fmi_me_newton_max_iterations, prop:fmi_me_max_continuous_states, prop:fmi_me_max_runtime_evaluations_per_step)

allow_internal_sparse_fallback: bool

compiled_warmup_policy: StructuralCompiledWarmupPolicy

external_sparse_solver_directory: str

external_sparse_solver_plugin_name: str

fmi_me_max_continuous_states: int

fmi_me_max_runtime_evaluations_per_step: int

fmi_me_newton_absolute_tolerance: float

fmi_me_newton_max_iterations: int

fmi_me_newton_relative_tolerance: float

fmi_state_event_max_iterations: int

fmi_state_event_time_tolerance: float

init_allow_state_equilibrium: bool

init_dense_threshold: int

init_fix_pf_bus_voltages: bool

init_newton_backtracking: bool

init_newton_max_iter: int

init_newton_tol: float

init_ptc_dtau0: float

init_ptc_dtau_max: float

init_ptc_dtau_min: float

init_ptc_max_iter: int

initialization_method: EmtInitializationMethod

integration_method: DynamicIntegrationMethod

newton_backtracking_beta

newton_backtracking_max_iter

newton_backtracking_min_alpha

newton_compute_dense_cond

newton_dense_cond_max_n

newton_dense_cond_warn

newton_enable_backtracking

newton_enable_fallback

newton_enable_index1_check

newton_index1_fail_pivot_ratio

newton_index1_max_block_n

newton_index1_warn_pivot_ratio

newton_step_norm_explode

problem_type: EmtProblemTypes

simulation_time: float

solver_type: EmtSolverTypes

sparse_solver: SparseSolver

time_step: float

tolerance: float

verbose

VeraGridEngine.Simulations.EMT.emt_problem_factory module

VeraGridEngine.Simulations.EMT.emt_problem_factory.build_emt_problem(grid: MultiCircuit, options: EmtOptions, pf_results: PowerFlowResults | None = None, pf_results_3ph: PowerFlowResults3Ph | None = None, progress_signal: DummySignal | None = None, logger: Logger | None = None) → EmtProblemDae[source]

Build the EMT problem implementation selected in the simulation options.

Parameters:

grid – Electrical grid whose devices define the EMT problem.
options – EMT configuration, including the requested problem type.
pf_results – Optional balanced power-flow initialization results.
pf_results_3ph – Optional three-phase power-flow initialization results.
progress_signal – Optional signal used to publish numeric progress.
logger – Optional logger owned by the simulation driver.

Returns:

Configured EMT problem ready to be passed to a solver.

VeraGridEngine.Simulations.EMT.emt_results module

Bases: ResultsTemplate

CLASS_DATA_VARIABLES = {'converged': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'diff_values': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'dynamic_metadata_json': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'emt_events_group_idtags': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'emt_events_group_names': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'has_event_group_results': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'time_array': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'values': <VeraGridEngine.Simulations.results_template.ResultsProperty object>, 'well_initialized': <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>)

consolidate_after_loading() → None[source]

Refresh the dynamic dimensions after disk restore.

Returns:: None.

converged

devices_vars_info: Dict[Generator | Battery | Load | ExternalGrid | StaticGenerator | Shunt | ControllableShunt | CurrentInjection | Line | DcLine | Transformer2W | HvdcLine | VSC | UPFC | Winding | Switch | SeriesReactance | FluidNode | FluidPath | FluidP2x | FluidTurbine | FluidPump | Substation | Bus | BusBar | VoltageLevel | Country | Region | Community | Municipality | Area | Zone | Transformer3W | TransformerNW | OverheadLineType | Wire | UndergroundCableType | TransformerType | EmissionGas | BranchGroup | LineLocations | LineLocation | ModellingAuthority | Facility | MarketUnit | MarketUnitsGroup | Fuel | Investment | InvestmentsGroup | Contingency | ContingencyGroup | RemedialAction | RemedialActionGroup | Technology | Owner | UndergroundLineType | DcCableType | SequenceLineType | ManufacturerNativeModel | RmsModelTemplate | EmtModelTemplate | FmuTemplate | ControlPc | RmsEvent | RmsEventsGroup | ShortCircuitEvent | IfMeasurement | ItMeasurement | QfMeasurement | PfMeasurement | QtMeasurement | PtMeasurement | QiMeasurement | PiMeasurement | VmMeasurement | VaMeasurement | PgMeasurement | QgMeasurement, List[Var]]

diff_values

diff_variables

dynamic_metadata_json

emt_events_group_idtags

emt_events_group_names

Build the device-variable tree consumed by the dynamic results handler.

Returns:: Nested mapping {device_type: {device: [variables]}}.

The handler preserves this structure when building the GUI tree of available dynamic variables.

get_initial_parameter_value(group_idx: int, device_idtag: str, parameter_name: str) → float | None[source]

Get one exported initial parameter value for one event group.

Parameters:

group_idx – Event-group index.
device_idtag – Stable device identifier.
parameter_name – Canonical symbolic parameter name.

Returns:

Initial parameter scalar value, or None.

get_parameter_value(group_idx: int, device_idtag: str, parameter_name: str) → float | None[source]

Get one exported parameter value for one event group.

Parameters:

group_idx – Event-group index.
device_idtag – Stable device identifier.
parameter_name – Canonical symbolic parameter name.

Returns:

Parameter scalar value, or None.

get_var(uid: int) → Var | None[source]

Get one exported EMT variable from its uid.

Parameters:: uid – Variable uid.
Returns:: Matching algebraic/state variable, matching differential variable, or None.

The EMT results object stores algebraic/state variables and differential variables in separate arrays. The lookup must therefore resolve the uid against both index maps and return the object from the matching storage.

get_vars_data(var_list: List[Var], group_idx: int = 0) → ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[int, int], dtype[float64]][source]: Get time, vars data matrix for the vars selection :param var_list: List of vars :param group_idx: group index :return: data (time, vars)

has_event_group_results

initial_parameter_value_maps: List[Dict[str, float]]

ndv

ng

nt

nv

parameter_value_maps: List[Dict[str, float]]

prepare_for_saving() → None[source]

Refresh the serialized dynamic metadata before the result archive is written.

Returns:: None.

restore_dynamic_metadata(grid: MultiCircuit) → None[source]

Restore dynamic variable metadata from the serialized payload.

Parameters:: grid – Current circuit used to resolve device idtags.
Returns:: None.

uid2idx: Dict[int, int]

uid2idx_diff: Dict[int, int]

uid2idx_vars: Dict[int, int]

uid2vars_glob_name

values

variable_array

variables

vars_glob_name2uid

well_initialized

VeraGridEngine.Simulations.EMT.emt_solver_factory module

VeraGridEngine.Simulations.EMT.emt_solver_factory.build_emt_solver(options: EmtOptions, problem: EmtProblemTemplate, t0: float, t_end: float, h: float, method: DynamicIntegrationMethod = DAE_Trapezoidal, newton_diag_config: NewtonDiagnosticsConfig | None = None, progress_signal: DummySignal | None = None, cancel_checker: Callable[[], bool] | None = None) → Any[source]

Build the configured EMT solver.

Parameters:

options (EmtOptions) – EMT options selecting the solver implementation.
problem (EmtProblemTemplate) – EMT problem instance consumed by the solver.
t0 (float) – Initial simulation time.
t_end (float) – Final simulation time.
h (float) – Nominal integration time step.
method (DynamicIntegrationMethod) – Integration method used by the solver.
newton_diag_config (NewtonDiagnosticsConfig | None) – Optional Newton diagnostics configuration.
progress_signal (DummySignal | None) – Optional progress signal propagated to the solver loop.
cancel_checker (Callable[[], bool] | None) – Optional cancellation callback checked by the solver at safe boundaries.

Returns:

Configured EMT solver instance.

Return type:

Any

VeraGridEngine.Simulations.EMT.initialization_emt module

class VeraGridEngine.Simulations.EMT.initialization_emt.EmtInitializationReport(method_requested: EmtInitializationMethod)[source]

Bases: object

Stores the outcome of the EMT-native initialization workflow.

automatic_dx0_count: int

constant_param_build_s: float

dx0_completion_s: float

dx0_seed_build_s: float

elapsed_s: float

final_residual_inf: float

initial_residual_eval_s: float

initial_residual_inf: float

message: str

method_requested: EmtInitializationMethod

method_used: EmtInitializationMethod

missing_dx_problem_collect_s: float

missing_dx_scatter_s: float

newton_elapsed_s: float

newton_iterations: int

persistent_cache_hit: bool

persistent_cache_load_s: float

persistent_cache_store_s: float

pseudo_transient_elapsed_s: float

pseudo_transient_steps: int

reduced_system_build_s: float

runtime_param_build_s: float

solution_apply_s: float

state_rhs_eval_s: float

state_rhs_vector_build_s: float

state_rhs_vector_cache_hit: bool

status: EmtInitializationStatus

unknown_var_count: int

unresolved_state_count: int

x0_rebuild_s: float

class VeraGridEngine.Simulations.EMT.initialization_emt.EmtPseudoTransientProblemAdapter(reduced_system: ReducedInitializationSystem, problem: EmtProblemTemplate, x_full: ndarray, dx_full: ndarray, runtime_params: ndarray, constant_params: ndarray)[source]

Bases: RmsProblemTemplate

Adapt one EMT reduced initialization system to the RMS pseudo-transient solver API.

The RMS pseudo-transient implementation expects a problem object exposing the RMS numerical interface. This adapter provides that interface on top of the EMT reduced initialization residual and Jacobian so the EMT initializer can reuse the existing pseudo-transient algorithm without changing the solver.

algebraic_vars() → List[Var][source]

Return the reduced non-state unknowns.

Returns:: Reduced non-state unknown list.
Return type:: List[Var]

get_algebraic_var_number() → int[source]

Return the number of reduced algebraic-like unknowns.

The reduced initialization system mixes algebraic variables with any unresolved states. The RMS solver only needs a partition size, so the complementary block to the unresolved-state count is returned here.

Returns:: Number of reduced unknowns treated as non-state variables.
Return type:: int

get_algebraic_vars() → List[Var][source]

Return the reduced unknowns treated as algebraic by the adapter partition.

Returns:: Reduced non-state unknown list.
Return type:: List[Var]

get_all_vars_number() → int[source]

Return the number of reduced initialization unknowns.

Returns:: Number of reduced unknowns.
Return type:: int

get_diff_var_number() → int[source]

Return the number of differential variables used by the reduced solver.

The RMS pseudo-transient solver asks for a differential-vector size even when the EMT reduced initialization stage does not solve an explicit EMT differential system in local coordinates. Returning the full EMT dx length preserves compatibility with the residual evaluation helpers.

Returns:: Differential-vector size expected by the EMT residual evaluation.
Return type:: int

get_dx(x: ndarray, xn: ndarray, dx: ndarray, h: float) → ndarray[source]

Return the EMT differential vector used by the reduced residual helpers.

The RMS pseudo-transient code requests a derivative estimate for its DAE residual construction. The EMT reduced initialization residual already carries all required differential information through the full EMT dx buffer, so the adapter returns a copy of that frozen vector.

Parameters:

x (np.ndarray) – Current reduced iterate.
xn (np.ndarray) – Previous reduced iterate.
dx (np.ndarray) – Previous differential estimate.
h (float) – Pseudo-time step size.

Returns:

Differential vector used by EMT residual evaluation.

Return type:

np.ndarray

get_j11(x: ndarray, dx: ndarray, h: float) → csc_matrix[source]

Return the reduced Jacobian state-state block.

Parameters:

x (np.ndarray) – Current reduced iterate.
dx (np.ndarray) – Differential vector requested by the solver.
h (float) – Pseudo-time step size.

Returns:

State-state Jacobian block.

Return type:

sp.csc_matrix

get_j12(x: ndarray, dx: ndarray, h: float) → csc_matrix[source]

Return the reduced Jacobian state-algebraic block.

Parameters:

x (np.ndarray) – Current reduced iterate.
dx (np.ndarray) – Differential vector requested by the solver.
h (float) – Pseudo-time step size.

Returns:

State-algebraic Jacobian block.

Return type:

sp.csc_matrix

get_j21(x: ndarray, dx: ndarray, h: float) → csc_matrix[source]

Return the reduced Jacobian algebraic-state block.

Parameters:

x (np.ndarray) – Current reduced iterate.
dx (np.ndarray) – Differential vector requested by the solver.
h (float) – Pseudo-time step size.

Returns:

Algebraic-state Jacobian block.

Return type:

sp.csc_matrix

get_j22(x: ndarray, dx: ndarray, h: float) → csc_matrix[source]

Return the reduced Jacobian algebraic-algebraic block.

Parameters:

x (np.ndarray) – Current reduced iterate.
dx (np.ndarray) – Differential vector requested by the solver.
h (float) – Pseudo-time step size.

Returns:

Algebraic-algebraic Jacobian block.

Return type:

sp.csc_matrix

get_states_number() → int[source]

Return the number of reduced unknowns that correspond to unresolved states.

Returns:: Count of reduced state unknowns.
Return type:: int

get_x0() → ndarray[source]

Return the reduced unknown vector used to seed pseudo-transient iterations.

Returns:: Reduced initialization vector.
Return type:: np.ndarray

rhs_algebraic(values: ndarray, diff_values: ndarray) → ndarray[source]

Return the reduced residual entries associated with non-state unknowns.

Parameters:

values (np.ndarray) – Current reduced iterate.
diff_values (np.ndarray) – Differential vector requested by the solver.

Returns:

Reduced residual algebraic block.

Return type:

np.ndarray

rhs_state(x: ndarray, dx: ndarray) → ndarray[source]

Return the reduced residual entries associated with unresolved states.

Parameters:

x (np.ndarray) – Current reduced iterate.
dx (np.ndarray) – Differential vector requested by the solver.

Returns:

Reduced residual state block.

Return type:

np.ndarray

state_vars() → List[Var][source]

Return the reduced unknowns treated as states by the adapter partition.

Returns:: Reduced state unknown list.
Return type:: List[Var]

uid2idx_vars: Dict[int, int]

update_variable_params(t: float, x_snapshot: ndarray | None = None) → None[source]

Keep the EMT runtime-parameter snapshot aligned with the RMS solver API.

The EMT reduced initializer freezes the runtime parameters before entering the pseudo-transient solve. The RMS solver still invokes this hook at the beginning of the loop, so the adapter accepts the call and intentionally preserves the already prepared parameter arrays.

Parameters:

t (float) – Pseudo-time value requested by the solver
x_snapshot (np.ndarray | None) – Optional reduced state snapshot

Returns:

None

Return type:

None

class VeraGridEngine.Simulations.EMT.initialization_emt.InitializationStateRhsVector(source_code: str, use_jit: bool, output_size: int)[source]

Bases: object

Lightweight state-RHS evaluator used by dx0 completion.

class VeraGridEngine.Simulations.EMT.initialization_emt.InitializationVectorCache[source]

Bases: object

In-process cache for symbolic vectors used during EMT initialization.

get_entry(cache_key: str) → InitializationVectorCacheEntry | None[source]

Return one cached initialization-vector entry.

Parameters:: cache_key (str) – Deterministic cache key.
Returns:: Cached entry or None.
Return type:: InitializationVectorCacheEntry | None

set_entry(cache_key: str, entry: InitializationVectorCacheEntry) → None[source]

Store one cached initialization-vector entry.

Parameters:

cache_key (str) – Deterministic cache key.
entry (InitializationVectorCacheEntry) – Cache entry.

Returns:

None.

Return type:

None

class VeraGridEngine.Simulations.EMT.initialization_emt.InitializationVectorCacheEntry(vector: InitializationStateRhsVector | SymbolicVector)[source]

Bases: object

In-process cache entry for one initialization-stage symbolic vector.

get_vector() → InitializationStateRhsVector | SymbolicVector[source]

Return the cached symbolic vector evaluator.

Returns:: Cached symbolic vector evaluator.
Return type:: InitializationStateRhsVector | SymbolicVector

class VeraGridEngine.Simulations.EMT.initialization_emt.ReducedInitializationSystem(problem: EmtProblemTemplate, unknown_vars: List[Var], residual_eqs: List[Expr], state_unknown_mask: ndarray)[source]

Bases: object

Reduced EMT initialization system built on top of the unresolved variables only.

jacobian_fn

residual_eqs

residual_fn

state_unknown_mask

unknown_vars

class VeraGridEngine.Simulations.EMT.initialization_emt.ReducedInitializationSystemCache[source]

Bases: object

In-process cache for reduced EMT initialization systems.

get_entry(cache_key: str) → ReducedInitializationSystemCacheEntry | None[source]

Return one cached reduced-system entry.

Parameters:: cache_key (str) – Deterministic cache key.
Returns:: Cached entry or None.
Return type:: ReducedInitializationSystemCacheEntry | None

set_entry(cache_key: str, entry: ReducedInitializationSystemCacheEntry) → None[source]

Store one cached reduced-system entry.

Parameters:

cache_key (str) – Deterministic cache key.
entry (ReducedInitializationSystemCacheEntry) – Cache entry.

Returns:

None.

Return type:

None

class VeraGridEngine.Simulations.EMT.initialization_emt.ReducedInitializationSystemCacheEntry(residual_fn: SymbolicVector, jacobian_fn: SymbolicJacobian)[source]

Bases: object

In-process cache entry for reduced EMT initialization systems.

get_jacobian_fn() → SymbolicJacobian[source]

Return the cached reduced Jacobian evaluator.

Returns:: Reduced Jacobian evaluator.
Return type:: SymbolicJacobian

get_residual_fn() → SymbolicVector[source]

Return the cached reduced residual evaluator.

Returns:: Reduced residual evaluator.
Return type:: SymbolicVector

VeraGridEngine.Simulations.EMT.initialization_emt.init_pseudo_transient(problem: EmtProblemTemplate, options: EmtOptions) → EmtInitializationReport[source]

Run the EMT-native initialization workflow forcing the pure pseudo-transient path.

This helper does not execute explicit initialization. It starts from the current problem seed, which in the main EMT build workflow corresponds to the power-flow projected variables.

Parameters:

problem – EMT problem being initialized.
options – EMT simulation options.

Returns:

Initialization report.

VeraGridEngine.Simulations.EMT.initialization_emt.run_emt_device_pseudo_transient_initialization(problem: EmtProblemTemplate, blocks: List[Block], options: EmtOptions, check_kcl: bool = True) → EmtInitializationReport[source]

Solve each complete device at a balanced periodic PF operating point.

Device registration and residuals use only dynamic equations. Machine and controller children share one solve. PF terminal voltages remain fixed and mapped terminal currents anchor the operating point. Unseeded Const(None) event parameters become unknown references; symbolic references also carry their defining residual. Neither init_eqs nor diff_init_eqs is evaluated.

Pseudo time relaxes f(x)-D_periodic(x)=0. ABC state triples use their fundamental sinusoidal derivatives; dq/controller states use zero and absolute rotor angles advance at grid frequency. This balanced fundamental approximation is checked against the assembled DAE at four cycle phases.

VeraGridEngine.Simulations.EMT.initialization_emt.run_emt_native_initialization(problem: EmtProblemTemplate, options: EmtOptions) → EmtInitializationReport[source]

Run the EMT-native initialization stages after power-flow variable projection.

The workflow keeps the current seed intact, then solves only the unresolved subset with the native initialization algorithm requested by options.initialization_method. The concrete EMT build uses device-local periodic pseudo-transient initialization directly from PF seeds for PseudoTransient; this native dispatcher remains available for direct helper calls and the other initialization methods. Missing differential initial values are computed automatically from the state equations.

Parameters:

problem – EMT problem being initialized.
options – EMT simulation options.

Returns:

Initialization report.

VeraGridEngine.Simulations.EMT.initialization_emt.validate_emt_periodic_initialization(problem: EmtProblemTemplate, blocks: List[Block], options: EmtOptions, report: EmtInitializationReport) → EmtInitializationReport[source]: Check the assembled periodic DAE at four phases without time integration.

VeraGridEngine.Simulations.EMT package

Subpackages

Submodules

VeraGridEngine.Simulations.EMT.emt_driver module

VeraGridEngine.Simulations.EMT.emt_options module

VeraGridEngine.Simulations.EMT.emt_problem_factory module

VeraGridEngine.Simulations.EMT.emt_results module

VeraGridEngine.Simulations.EMT.emt_solver_factory module

VeraGridEngine.Simulations.EMT.initialization_emt module

Module contents