andes.core.service.VarService

class andes.core.service.VarService(v_str: str | None = None, v_numeric: Callable | None = None, vtype: type | None = None, name: str | None = None, tex_name: str | None = None, info: str | None = None, unit: str | None = None, sequential: bool | None = True)

Variable service that gets updated in each step/iteration before computing the residual equations. As a results, variable values from the k-th step are used to compute a VarService that will be used to compute the residual for the (k+1)-th step.

This class is useful when one has non-differentiable algebraic equations, which make use of abs(), re and im. Instead of creating Algeb, one can put the equation in VarService, which will be updated before solving algebraic equations.

Parameters:

sequentialbool, optional, default to True

True if this VarService depends on previously defined VarService and should be evaluated in sequence. False if this VarService only uses known variables.

Warning

VarService is intended for non-differentiable expressions (e.g., Abs(), re(), im()) that cannot appear in algebraic equations. If the expression is differentiable, an Algeb variable should be used instead.

During model initialization, VarService is evaluated before any variable v_str assignment is computed. If the expression references algebraic or state variables, those variables will still hold their default (typically zero) values, resulting in an incorrect initial VarService value. Variables whose v_str depends on this VarService will consequently be initialized from an erroneous starting point. At runtime, this effect is self-correcting because VarService is re-evaluated every iteration with updated variable values. However, the incorrect initial value can cause convergence difficulties or incorrect limiter flag settings during the first few iterations.

VarService is not solved simultaneously with algebraic equations, meaning that a one-step delay exists between the algebraic variables and the VarService value.

Examples

In ESST3A model, the voltage and current sensors (vd + jvq), (Id + jIq) estimate the sensed VE using equation

\[VE = | K_{PC}*(v_d + 1j v_q) + 1j (K_I + K_{PC}*X_L)*(I_d + 1j I_q)|\]

One can use VarService to implement this equation

self.VE = VarService(
    tex_name='V_E', info='VE', v_str='Abs(KPC*(vd + 1j*vq) + 1j*(KI +
    KPC*XL)*(Id + 1j*Iq))', )

__init__(v_str: str | None = None, v_numeric: Callable | None = None, vtype: type | None = None, name: str | None = None, tex_name: str | None = None, info: str | None = None, unit: str | None = None, sequential: bool | None = True)

Methods

assign_memory(n)	Assign memory for self.v and set the array to zero.
get_names()	Return name in a list
restore_init()	No-op: VarService is recomputed each step.
snapshot_init()	No-op: VarService is recomputed each step.

Attributes

class_name	Return the class name
n	Return the count of values in self.v.