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, 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)[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: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)

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

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, 'idtag': prop:idtag, 'init_allow_state_equilibrium': prop:init_allow_state_equilibrium, 'init_dense_threshold': prop:init_dense_threshold, '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: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)

action: ActionType

comment: str

device_type: DeviceType

diff_changes

selected_to_merge

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)[source]

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[ALL_DEV_TYPES, 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]]

plot_var(var: Var, group_idx: int = 0) → None[source]

Plot one EMT variable trace when it exists in the results arrays.

Parameters:

var – Variable to plot.
group_idx – Event-group index.

Returns:

None.

EMT variables may live either in the algebraic/state array or in the differential-variable array. The plotting path must therefore inspect both index maps and route to the matching numeric array explicitly.

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: SymbolicVector)[source]

Bases: object

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

get_vector() → SymbolicVector[source]

Return the cached symbolic vector evaluator.

Returns:: Cached symbolic vector evaluator.
Return type:: 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.build_uid_bindings(eq: Expr | Const, event_params_array: ndarray, x: ndarray, params_array: ndarray, dx: ndarray, uid2idx_event_params: Dict[int, int], uid2idx_vars: Dict[int, int], uid2idx_params: Dict[int, int], uid2idx_diff: Dict[int, int]) → Dict[int, float][source]

Builds a mapping of Unique Identifiers (UIDs) to their current numeric values.

Parameters:

eq – The symbolic expression to analyze.
event_params_array – Array containing resolved event parameters.
x – Array containing state and algebraic variables.
params_array – Array containing constant model parameters.
dx – Array containing derivative values.
uid2idx_event_params – Mapping of UID to index for event parameters.
uid2idx_vars – Mapping of UID to index for variables.
uid2idx_params – Mapping of UID to index for constants.
uid2idx_diff – Mapping of UID to index for derivatives.

Returns:

A dictionary mapping UIDs to their float values.

VeraGridEngine.Simulations.EMT.initialization_emt.can_compute_init(var: Var, eq: Expr | Const, mdl: Block, init_guess: Dict[int, float], diff_init_guess: Dict[int, float], uid2idx_diff: Dict[int, int], uid2idx_vars: Dict[int, int]) → bool[source]

Determines if an initialization equation is computable based on current knowns.

Parameters:

var – Target variable.
eq – The expression to evaluate.
mdl – The model block.
init_guess – Current variable guesses.
diff_init_guess – Current derivative guesses.
uid2idx_diff – UID map for derivatives.
uid2idx_vars – UID map for variables.

Returns:

Boolean indicating if all dependencies are met.

VeraGridEngine.Simulations.EMT.initialization_emt.event_param_is_resolved(v: Var, mdl: Block) → bool[source]

Checks if an event parameter has been assigned a concrete value.

Parameters:

v – The variable representing the event parameter.
mdl – The symbolic model block.

Returns:

True if resolved, False otherwise.

VeraGridEngine.Simulations.EMT.initialization_emt.init_explicit_emt(mdl: Block, sys_vars: Dict[int, Var], sys_diff_vars: Dict[int, Var], variable_parameters: List[Var], event_parameters_eqs: List[Expr | Const], constant_parameters: List[Var], constant_parameter_values: List[Const], init_guess: Dict[int, float], diff_init_guess: Dict[int, float], uid2idx_vars: Dict[int, int], uid2idx_diff: Dict[int, int], uid2idx_params: Dict[int, int], uid2idx_event_params: Dict[int, int], compiler_names_dict: Dict[int, str], alias_names_dict: Dict[int, str], VARIABLE_PARAMS_NAME: str, VARS_NAME: str, DIFF_NAME: str, CONSTANT_PARAMS_NAME: str, verbose: bool = False) → Tuple[Dict[int, float], Dict[int, float]] | None[source]

Initializes the EMT model by solving initialization and differential equations.

This function performs a topological-like resolution of model variables. It uses fixed-point iteration for self-referencing equations and handles dependencies between algebraic and differential states.

Parameters:

mdl – Symbolic model block.
sys_vars – Registry of system variables.
sys_diff_vars – Registry of system differential variables.
variable_parameters – List of parameters that change on events.
event_parameters_eqs – Initial equations for event parameters.
constant_parameters – List of constant parameters.
constant_parameter_values – Values associated with constant_parameters.
init_guess – Initial guesses for variables.
diff_init_guess – Initial guesses for derivatives.
uid2idx_vars – Index map for variables.
uid2idx_diff – Index map for derivatives.
uid2idx_params – Index map for parameters.
uid2idx_event_params – Index map for event parameters.
compiler_names_dict – Map for variable naming in compilation.
alias_names_dict – Map for variable aliases.
VARIABLE_PARAMS_NAME – Name for variable parameter array.
VARS_NAME – Name for state variable array.
DIFF_NAME – Name for derivative array.
CONSTANT_PARAMS_NAME – Name for constant parameter array.
verbose – Whether to print explicit initialization diagnostics.

Returns:

Updated initial guesses and modified model block.

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_explicit_initialization(problem: EmtProblemTemplate, verbose: bool = False) → None[source]

Run the explicit EMT initialization stage on a full problem object.

Parameters:

problem – EMT problem being initialized.
verbose – Print explicit initialization details.

Returns:

None

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. In the main EMT build workflow, the seed comes either from power-flow projection alone for pure PseudoTransient or from power-flow projection plus explicit initialization for the other modes. 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 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