Routine

Routine includes three levels definition, which are descriptive routine data and model, optimization model, and data mapping.

Routine data and model

Dispatch routine is the descriptive model of the optimization problem.

Further, to facilitate the routine definition, AMS developed a class ams.core.param.RParam to pass the model data to multiple routine modeling.

class ams.core.param.RParam(name: str | None = None, tex_name: str | None = None, info: str | None = None, src: str | None = None, unit: str | None = None, model: str | None = None, v: ndarray | None = None, indexer: str | None = None, imodel: str | None = None, expand_dims: int | None = None, no_parse: bool | None = False, nonneg: bool | None = False, nonpos: bool | None = False, complex: bool | None = False, imag: bool | None = False, symmetric: bool | None = False, diag: bool | None = False, hermitian: bool | None = False, boolean: bool | None = False, integer: bool | None = False, pos: bool | None = False, neg: bool | None = False, sparse: list | None = None)

Class for parameters used in a routine. This class is developed to simplify the routine definition.

RParm is further used to define Parameter in the optimization model.

no_parse is used to skip parsing the RParam in optimization model. It means that the RParam will not be added to the optimization model. This is useful when the RParam contains non-numeric values, or it is not necessary to be added to the optimization model.

Parameters:

namestr, optional

Name of this parameter. If not provided, name will be set to the attribute name.

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

srcstr, optional

Source name of the parameter.

unitstr, optional

Unit of the parameter.

modelstr, optional

Name of the owner model or group.

vnp.ndarray, optional

External value of the parameter.

indexerstr, optional

Indexer of the parameter.

imodelstr, optional

Name of the owner model or group of the indexer.

no_parse: bool, optional

True to skip parsing the parameter.

nonneg: bool, optional

True to set the parameter as non-negative.

nonpos: bool, optional

True to set the parameter as non-positive.

complex: bool, optional

True to set the parameter as complex.

imag: bool, optional

True to set the parameter as imaginary.

symmetric: bool, optional

True to set the parameter as symmetric.

diag: bool, optional

True to set the parameter as diagonal.

hermitian: bool, optional

True to set the parameter as hermitian.

boolean: bool, optional

True to set the parameter as boolean.

integer: bool, optional

True to set the parameter as integer.

pos: bool, optional

True to set the parameter as positive.

neg: bool, optional

True to set the parameter as negative.

sparse: bool, optional

True to set the parameter as sparse.

Examples

Example 1: Define a routine parameter from a source model or group.

In this example, we define the parameter cru from the source model SFRCost with the parameter cru.

>>> self.cru = RParam(info='RegUp reserve coefficient',
>>>                   tex_name=r'c_{r,u}',
>>>                   unit=r'$/(p.u.)',
>>>                   name='cru',
>>>                   src='cru',
>>>                   model='SFRCost'
>>>                   )

Example 2: Define a routine parameter with a user-defined value.

In this example, we define the parameter with a user-defined value. TODO: Add example

RoutineModel([system, config])

Class to hold descriptive routine models and data mapping.

Optimization model

Optimization model is the optimization problem. Var, Constraint, and Objective are the basic building blocks of the optimization model. OModel is the container of the optimization model. A summary table is shown below.

Var([name, tex_name, info, src, unit, ...])	Base class for variables used in a routine.
Constraint([name, e_str, info, type])	Base class for constraints.
Objective([name, e_str, info, unit, sense])	Base class for objective functions.
OModel(routine)	Base class for optimization models.

Data mapping

Data mapping defines the relationship between AMS routine results and the dynamic simulator ANDES. The dynamic module, ams.interop.andes.Dynamic, is responsible for the conversion and synchronization of data between AMS and ANDES.

class ams.interop.andes.Dynamic(amsys=None, adsys=None)

ANDES interface class.

Parameters:

amsysAMS.system.System

The AMS system.

adsysANDES.system.System

The ANDES system.

Notes

1. Using the file conversion to_andes() will automatically link the AMS system to the converted ANDES system in the attribute dyn.

Examples

>>> import ams
>>> import andes
>>> sp = ams.load(ams.get_case('ieee14/ieee14_rted.xlsx'), setup=True)
>>> sa = sp.to_andes(setup=True,
...                  addfile=andes.get_case('ieee14/ieee14_wt3.xlsx'),
...                  overwrite=True, keep=False, no_output=True)
>>> sp.RTED.run()
>>> sp.RTED.dc2ac()
>>> sp.dyn.send()  # send RTED results to ANDES system
>>> sa.PFlow.run()
>>> sp.TDS.run()
>>> sp.dyn.receive()  # receive TDS results from ANDES system

Attributes:

linkpandas.DataFrame

The ANDES system link table.

receive(adsys=None, routine=None, no_update=False)

Receive ANDES system results to AMS devices.

Parameters:

adsysadsys.System.system, optional

The target ANDES dynamic system instance. If not provided, use the linked ANDES system isntance (sp.dyn.adsys).

routinestr, optional

The routine to be received from ANDES. If None, recent will be used.

no_updatebool, optional

True to skip update the AMS routine parameters after sync. Default is False.

send(adsys=None, routine=None)

Send results of the recent sovled AMS dispatch (sp.recent) to the target ANDES system.

Note that converged AC conversion DOES NOT guarantee successful dynamic initialization TDS.init(). Failed initialization is usually caused by limiter violation.

Parameters:

adsysadsys.System.system, optional

The target ANDES dynamic system instance. If not provided, use the linked ANDES system isntance (sp.dyn.adsys).

routinestr, optional

The routine to be sent to ANDES. If None, recent will be used.

When using this interface, the dynamic or static model is automatically selected based on the initialization status of the TDS. For more detailed information about the implementation of ams.interop.andes.Dynamic.send and ams.interop.andes.Dynamic.receive, refer to the full API reference or examine the source code.

Note

Check ANDES documentation StaticGen for more details about substituting static generators with dynamic generators.