Parameters#

Parameters are a type of building atom for DAE models. Most parameters are read directly from an input file and passed to equations, though some can be calculated from existing parameters.

Background#

The base class for parameters in ANDES is BaseParam, which defines interfaces for adding values and checking the number of values. BaseParam stores values in a plain list via the member attribute v. Subclasses such as NumParam store values using a NumPy ndarray for efficient numerical computation.

All parameters are v-providers: they have a v attribute containing values that can be used in equation strings. This shared interface enables parameters and services to be used interchangeably in equations. See Atomic Types for details on the v-provider concept.

Parameter Types#

`BaseParam`([default, name, tex_name, info, ...])	The base parameter class.
`NumParam`(default, name, tex_name, info, ...)	A computational numerical parameter.
`IdxParam`([default, name, tex_name, info, ...])	Parameter for storing idx references into other models.
`ExtParam`(model, src[, indexer, vtype, ...])	A parameter whose values are retrieved from an external model or group.
`DataParam`([default, name, tex_name, info, ...])	An alias of the BaseParam class.
`TimerParam`([callback, default, name, ...])	A parameter whose values are event occurrence times during the simulation.

NumParam#

The most common parameter type for numerical values that participate in equations.

from andes.core.param import NumParam

class MyModel(Model):
    def __init__(self):
        # Basic parameter
        self.R = NumParam(default=0.05,
                          info='Droop coefficient',
                          tex_name='R')

        # Parameter with constraints
        self.H = NumParam(default=3.0,
                          info='Inertia constant',
                          non_zero=True,
                          non_negative=True)

        # Parameter with units
        self.Vn = NumParam(default=20.0,
                           info='Rated voltage',
                           unit='kV')

NumParam values are stored in a NumPy array accessible via self.R.v. When used in equation strings like e_str='1/R', the parameter name is automatically substituted with its values during evaluation.

class andes.core.param.NumParam(default: float | str | ~typing.Callable | None = None, name: str | None = None, tex_name: str | None = None, info: str | None = None, unit: str | None = None, vrange: ~typing.List | ~typing.Tuple | None = None, vtype: ~typing.Type | None = <class 'float'>, iconvert: ~typing.Callable | None = None, oconvert: ~typing.Callable | None = None, non_zero: bool = False, non_positive: bool = False, non_negative: bool = False, mandatory: bool = False, power: bool = False, ipower: bool = False, voltage: bool = False, current: bool = False, z: bool = False, y: bool = False, r: bool = False, g: bool = False, dc_voltage: bool = False, dc_current: bool = False, export: bool = True)[source]

A computational numerical parameter.

Parameters defined using this class will have their v field converted to a NumPy array after adding.

The original input values will be copied to vin, and the system-base per-unit conversion coefficients (through multiplication) will be stored in pu_coeff.

Parameters:

defaultstr or float, optional: The default value of this parameter if no value is provided
namestr, optional: Name of this parameter. If not provided, name will be set to the attribute name of the owner model.
tex_namestr, optional: LaTeX-formatted parameter name. If not provided, tex_name will be assigned the same as name.
infostr, optional: A description of this parameter
mandatorybool: True if this parameter is mandatory
unitstr, optional: Unit of the parameter
vrangelist, tuple, optional: Typical value range
vtypetype, optional: Type of the v field. The default is float.

Attributes:

vinnp.ndarray or None: Raw input values before per-unit conversion. Used by restore() (pre-pu restore for System.reset).
_v_t0np.ndarray or None: Post-pu v at t=0, saved by snapshot_init(). Used by restore_init() to reset v during TDS.reinit.

Other Parameters:

Snstr: Name of the parameter for the device base power.
Vnstr: Name of the parameter for the device base voltage.
non_zerobool: True if this parameter must be non-zero. non_zero can be combined with non_positive or non_negative.
non_positivebool: True if this parameter must be non-positive.
non_negativebool: True if this parameter must be non-negative.
mandatorybool: True if this parameter must not be None.
powerbool: True if this parameter is a power per-unit quantity under the device base.
iconvertcallable: Callable to convert input data from excel or others to the internal v field.
oconvertcallable: Callable to convert input data from internal type to a serializable type.
ipowerbool: True if this parameter is an inverse-power per-unit quantity under the device base.
voltagebool: True if the parameter is a voltage pu quantity under the device base.
currentbool: True if the parameter is a current pu quantity under the device base.
zbool: True if the parameter is an AC impedance pu quantity under the device base.
ybool: True if the parameter is an AC admittance pu quantity under the device base.
rbool: True if the parameter is a DC resistance pu quantity under the device base.
gbool: True if the parameter is a DC conductance pu quantity under the device base.
dc_currentbool: True if the parameter is a DC current pu quantity under device base.
dc_voltagebool: True if the parameter is a DC voltage pu quantity under device base.

add(value=None)[source]

Add a value to the parameter value list.

In addition to BaseParam.add, this method checks for non-zero property and reset to default if is zero.

Returns:

str or None: The violation type string ('non_zero', 'non_positive', 'non_negative') if a correction was applied, or None if no correction was needed.

IdxParam#

References to devices in other models. IdxParam creates the connection graph between models, enabling external parameters and variables to look up values from referenced devices.

from andes.core.param import IdxParam

class PQ(Model):
    def __init__(self):
        # Reference to Bus model
        self.bus = IdxParam(model='Bus',
                            mandatory=True,
                            info='Connected bus idx')

The connection graph enables model relationships:

GENROU.bus → Bus.idx
GENROU.gen → StaticGen.idx
ESST1A.syn → GENROU.idx

Set status_parent=True to declare that the referenced device is a status parent. When a parent device is taken offline via set_status, the effective status (ue) of the child and its descendants is automatically propagated:

self.syn = IdxParam(model='SynGen', mandatory=True, status_parent=True)

Parameter for storing idx references into other models.

IdxParam creates the connection graph between models. It stores device idx values that point to entries in the referenced model (which can be a Model or Group name). These references are used by ExtParam and ExtAlgeb/ExtState to look up external values.

Parameters:

modelstr, optional: Name of the referenced Model or Group (e.g. 'Bus', 'StaticGen'). Required for BackRef and external-variable linking.
uniquebool, optional: If True, duplicate values raise IndexError. Useful when a one-to-one mapping is required (e.g. one TG per generator).
replacesbool, optional: If True, this model replaces the referenced device during time-domain simulation (static-dynamic replacement).
status_parentbool, optional: If True, the referenced device is treated as a status parent. When the parent is taken offline via set_status, the effective status ue of this device and its descendants is propagated automatically.

Examples

A PQ model connected to Bus

class PQModel(...):
    def __init__(...):
        self.bus = IdxParam(model='Bus')

An exciter referencing its parent generator with status propagation

self.syn = IdxParam(model='SynGen', mandatory=True,
                    status_parent=True)

add(value=None)[source]

Add a new parameter value (from a new device of the owner model) to the v list.

Parameters:

valuestr or float, optional: Parameter value of the new element. If None, the default will be used.

Notes

If the value is math.nan, it will set to None.

ExtParam#

Retrieves parameter values from external models. Uses an IdxParam as indexer to look up values from the referenced model.

from andes.core.param import ExtParam

class GENROU(Model):
    def __init__(self):
        # Get bus voltage from connected bus
        self.Vn = ExtParam(src='Vn',
                           model='Bus',
                           indexer=self.bus)

        # Get initial power from static generator
        self.p0 = ExtParam(src='p',
                           model='StaticGen',
                           indexer=self.gen)

ExtParam is essential for models that need configuration or initial conditions from other models. The retrieved values are stored locally in a NumPy array and can be used in equation strings just like NumParam.

class andes.core.param.ExtParam(model: str, src: str, indexer=None, vtype=<class 'float'>, allow_none=False, default=0.0, **kwargs)[source]

A parameter whose values are retrieved from an external model or group.

Parameters:

modelstr: Name of the model or group providing the original parameter
srcstr: The source parameter name
indexerBaseParam: A parameter defined in the model defining this ExtParam instance. indexer.v should contain indices into model.src.v. If is None, the source parameter values will be fully copied. If model is a group name, the indexer cannot be None.
vtypetype, optional, default to float: Type of each element to be retrieved. Can be str if the ExtParam is used to access an IdxParam.

Attributes:

parent_modelModel: The parent model providing the original parameter.

add(value=None)[source]: ExtParam has an empty add method.

link_external(ext_model)[source]

Update parameter values provided by external models. This needs to be called before pu conversion.

Parameters:

ext_modelModel, Group: Instance of the parent model or group, provided by the System calling this method.

restore()[source]: ExtParam has an empty restore method

to_array()[source]: Convert to array when d_type is not str

DataParam#

For non-numeric data such as names or string identifiers that should not participate in numerical calculations.

from andes.core.param import DataParam

class Bus(Model):
    def __init__(self):
        self.name = DataParam(info='Bus name')

An alias of the BaseParam class.

This class is used for string parameters or non-computational numerical parameters. This class does not provide a to_array method. All input values will be stored in v as a list.

TimerParam#

For time-based events. TimerParam stores callback functions that are triggered when simulation time reaches the parameter value. This parameter type enables the timed event mechanism used by Fault, Toggle, and Alter models.

from andes.core.param import TimerParam

class Fault(Model):
    def __init__(self):
        self.tf = TimerParam(info='Fault start time',
                             callback=self.apply_fault)
        self.tc = TimerParam(info='Fault clear time',
                             callback=self.clear_fault)

The callback function receives a boolean array indicating which devices have reached their trigger time. See System Architecture for details on how the timed event mechanism works internally.

A parameter whose values are event occurrence times during the simulation.

The constructor takes an additional Callable self.callback for the action of the event. TimerParam has a default value of -1, meaning deactivated.

Examples

A connectivity status toggle class Toggle takes a parameter t for the toggle time. Inside Toggle.__init__, one would have

self.t = TimerParam()

The Toggle class also needs to define a method for togging the connectivity status

def _u_switch(self, is_time: np.ndarray):
    action = False
    for i in range(self.n):
        if is_time[i] and (self.u.v[i] == 1):
            instance = self.system.__dict__[self.model.v[i]]
            # get the original status and flip the value
            u0 = instance.get(src='u', attr='v', idx=self.dev.v[i])
            instance.set(src='u',
                         attr='v',
                         idx=self.dev.v[i],
                         value=1-u0)
            action = True
    return action

Finally, in Toggle.__init__, assign the function as the callback for self.t

self.t.callback = self._u_switch

is_time(dae_t)[source]

Element-wise check if the DAE time is the same as the parameter value. The current implementation uses np.equal.

Parameters:

dae_tfloat: Current simulation time

Returns:

np.ndarray: The array containing the truth value of if the DAE time is close to the parameter value.

Notes

The previous implementation with np.isclose with default rtol=1e-5 mistakes the immediate pre- and post-event time as in-event when simulation time is greater than 10.

BaseParam#

The abstract base class defining the parameter interface. All parameter types inherit from BaseParam.

The base parameter class.

This class provides the basic data structure and interfaces for all types of parameters. Parameters are from input files and in general constant once initialized.

Subclasses should overload the n() method for the total count of elements in the value array.

Parameters:

defaultstr or float, optional: The default value of this parameter if None is provided
namestr, optional: Parameter name. If not provided, it will be automatically set to the attribute name defined in the owner model.
tex_namestr, optional: LaTeX-formatted parameter name. If not provided, tex_name will be assigned the same as name.
infostr, optional: Descriptive information of parameter
mandatorybool: True if this parameter is mandatory
exportbool: True if the parameter will be exported when dumping data into files. True for most parameters. False for BackRef.

Attributes:

vlist: A list holding all the values. The BaseParam class does not convert the v attribute into NumPy arrays.
propertydict: A dict containing the truth values of the model properties.

Other Parameters:

iconvertCallable: Converter to be applied to input data when a device is being added.
oconvertcallable: Converter to be applied to internal data when outputting.

Warning

The most distinct feature of BaseParam, DataParam and IdxParam is that values are stored in a list without conversion to array. BaseParam, DataParam or IdxParam are not allowed in equations.

add(value=None)[source]

Add a new parameter value (from a new device of the owner model) to the v list.

Parameters:

valuestr or float, optional: Parameter value of the new element. If None, the default will be used.

Notes

If the value is math.nan, it will set to None.

property class_name: Return the class name.

get_names()[source]

Return self.name in a list.

This is a helper function to provide the same API as blocks or discrete components.

Returns:

list: A list only containing the name of the parameter

get_property(property_name: str)[source]

Check the boolean value of the given property. If the property does not exist in the dictionary, False will be returned.

Parameters:

property_namestr: Property name

Returns:

The truth value of the property.

property n: Return the count of elements in the value array.

set(pos, attr, value)[source]

Set attributes of the BaseParam class to new values at the given positions.

Parameters:

posint, list of integers: Positions in arrays where the values should be set
attr'v', 'vin': Name of the attribute to be set
valuestr, float or list of above: New values

set_all(attr, value)[source]

Set attributes of the BaseParam class to new values for all positions.

Parameters:

attr'v', 'vin': Name of the attribute to be set
valuelist of str, float or int: New values

Parameters in Equations#

Parameters can be used directly in equation strings by name. The symbolic framework substitutes parameter names with their v arrays during evaluation:

self.R = NumParam(default=0.05)
self.D = NumParam(default=2.0)

# Use parameters in service calculation
self.gain = ConstService(v_str='1/R')

# Use parameters in differential equation
self.omega = State(e_str='Tm - Pe - D*(omega-1)')

Mandatory vs Optional#

Mandatory: Must be provided in input data; simulation fails without it
Optional: Uses default value if not provided

self.bus = IdxParam(mandatory=True)   # Required
self.D = NumParam(default=0.0)        # Optional, defaults to 0

Input Validation#

ANDES validates parameters after loading:

NaN values raise ValueError
inf values are replaced with 1e8
Constraint violations (e.g., non_zero) use defaults with a warning

Parameters#

Background#

Parameter Types#

NumParam#

IdxParam#

ExtParam#

DataParam#

TimerParam#

BaseParam#

Parameters in Equations#

Mandatory vs Optional#

Input Validation#

See Also#