Interoperation with ANDES

One of the most interesting feature of AMS is its interoperation with dynamic simulator ANDES.

Interoperation includes compatible case conversion and data exchange, thus it facilitates scheduling-dynamics co-simulation using AMS and ANDES.

import numpy as np

import andes
import ams

ams.config_logger(stream_level=20)

Scheduling

sp = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'),
              setup=True,
              no_output=True,)

Parsing input file "/Users/jinningwang/work/ams/ams/cases/ieee14/ieee14_uced.xlsx"...
Input file parsed in 0.0736 seconds.
All bus type are PQ, adjusted given load and generator connection status.
System set up in 0.0018 seconds.

sp.RTED.init()

Building system matrices
Parsing OModel for <RTED>
Evaluating OModel for <RTED>
Finalizing OModel for <RTED>
<RTED> initialized in 0.0128 seconds.

<RTED> RParam <c2> should have all non-negative values.

True

sp.RTED.run(solver='CLARABEL')

<RTED> solved as optimal in 0.0132 seconds, converged in 10 iterations with CLARABEL.

True

Convert to ANDES

The built-in ANDES interface can convert an AMS case to ANDES case in memory.

The bridge between AMS and converted ANDES is the shared power flow devices, Bus, PQ, PV, Slack, Line, and Shunt.

sa = sp.to_andes(setup=True,
                 addfile=andes.get_case('ieee14/ieee14_full.xlsx'))

Generating code for 1 models on 12 processes.

Parsing additional file "/Users/jinningwang/work/andes/andes/cases/ieee14/ieee14_full.xlsx"...
Following PFlow models in addfile will be overwritten: <Bus>, <PQ>, <PV>, <Slack>, <Shunt>, <Line>, <Area>
Addfile parsed in 0.0241 seconds.
System converted to ANDES in 0.2118 seconds.
AMS system 0x16a1666c0 is linked to the ANDES system 0x30f1a88c0.

If you wish to add devices to the converted ANDES system, set setup=False to skip the ANDES setup process.

As indicated by the output information, in the conversion process, ANDES power flow devices will be overwritten by AMS ones, if exists.

Upon a successful conversion, you are ready to enjoy full capability of ANDES.

help command can give a quick reference.

help(sp.to_andes)

Help on method to_andes in module ams.system:

to_andes(addfile=None, setup=False, no_output=False, default_config=True, verify=False, tol=0.001, **kwargs) method of ams.system.System instance
    Convert the AMS system to an ANDES system.
    Wrapper method for `ams.interface.to_andes`.

    A preferred dynamic system file to be added has following features:
    1. The file contains both power flow and dynamic models.
    2. The file can run in ANDES natively.
    3. Power flow models are in the same shape as the AMS system.
    4. Dynamic models, if any, are in the same shape as the AMS system.

    This function is wrapped as the ``System`` class method ``to_andes()``.
    Using the file conversion ``to_andes()`` will automatically
    link the AMS system instance to the converted ANDES system instance
    in the AMS system attribute ``dyn``.

    It should be noted that detailed dynamic simualtion requires extra
    dynamic models to be added to the ANDES system, which can be passed
    through the ``addfile`` argument.

    Parameters
    ----------
    system : System
        The AMS system to be converted to ANDES format.
    addfile : str, optional
        The additional file to be converted to ANDES dynamic mdoels.
    setup : bool, optional
        Whether to call `setup()` after the conversion. Default is True.
    no_output : bool, optional
        To ANDES system.
    default_config : bool, optional
        To ANDES system.
    verify : bool
        If True, the converted ANDES system will be verified with the source
        AMS system using AC power flow.
    tol : float
        The tolerance of error.

    Returns
    -------
    adsys : andes.system.System
        The converted ANDES system.

    Examples
    --------
    >>> import ams
    >>> import andes
    >>> sp = ams.load(ams.get_case('ieee14/ieee14_uced.xlsx'), setup=True)
    >>> sa = sp.to_andes(addfile=andes.get_case('ieee14/ieee14_full.xlsx'),
    ...                  setup=False, overwrite=True, no_output=True)

    Notes
    -----
    - Power flow models in the addfile will be skipped and only dynamic models
      will be used.
    - The addfile format is guessed based on the file extension.
    - Index in the addfile is automatically adjusted when necessary.

Interoperation with ANDES

In the interface class dyn, the link table is stored in dyn.link.

It describes the mapping relationships between power flow devices and dynamic devices.

sp.dyn.link

	stg_idx	bus_idx	syg_idx	gov_idx	dg_idx	rg_idx	gammap	gammaq
0	Slack_1	1	GENROU_1	TGOV1_1	NaN	NaN	1.0	1.0
1	PV_5	8	GENROU_5	TGOV1_5	NaN	NaN	1.0	1.0
2	PV_4	6	GENROU_4	TGOV1_4	NaN	NaN	1.0	1.0
3	PV_3	3	GENROU_3	TGOV1_3	NaN	NaN	1.0	1.0
4	PV_2	2	GENROU_2	TGOV1_2	NaN	NaN	1.0	1.0

Send

As there is a gap between DC-based dispatch and AC-based TDS, a conversion is required to ensure the TDS initialization.

sp.RTED.dc2ac()

Parsing OModel for <ACOPF>
Evaluating OModel for <ACOPF>
Finalizing OModel for <ACOPF>
<ACOPF> initialized in 0.0065 seconds.
<ACOPF> converged in 0.1171 seconds, 12 iterations with PYPOWER.
<RTED> converted to AC.

PYPOWER Version 5.1.18, 10-Apr-2025 -- AC Optimal Power Flow
Python Interior Point Solver - PIPS, Version 1.0, 07-Feb-2011
Converged!

True

In the RTED routine, there are two mapping dictionaries to define the data exchange, namely, map1 for receiving data from ANDES and map2 for sending data to ANDES.

sp.RTED.map2

OrderedDict([('vBus', ('Bus', 'v0')),
             ('ug', ('StaticGen', 'u')),
             ('pg', ('StaticGen', 'p0'))])

sp.dyn.send(adsys=sa, routine='RTED')

Send <RTED> results to ANDES <0x30f1a88c0>...
*Send <vBus> to StaticGen.v0
Send <vBus> to Bus.v0
Send <ug> to StaticGen.u
Send <pg> to StaticGen.p0

True

Run ANDES

Sometimes, the ANDES TDS initialization may fail due to inapproriate limits.

Here, we alleviate the TGOV1 limit issue by enlarging the Pmax and Pmin to the same value.

sa.TGOV1.alter(src='VMAX', idx=sa.TGOV1.idx.v, value=100*np.ones(sa.TGOV1.n))
sa.TGOV1.alter(src='VMIN', idx=sa.TGOV1.idx.v, value=np.zeros(sa.TGOV1.n))

Run power flow.

sa.PFlow.run()

True

Try to init TDS.

_ = sa.TDS.init()

Run TDS.

sa.TDS.config.no_tqdm = True # disable progress bar
sa.TDS.run()

True

Receive

sp.RTED.map1

OrderedDict([('ug', ('StaticGen', 'u')), ('pg0', ('StaticGen', 'p'))])

sp.dyn.receive(adsys=sa, routine='RTED')

Receive <ug> from SynGen.u
Receive <pg0> from SynGen.Pe

True

The RTED parameter pg0, is retrieved from ANDES as the corresponding generator output power.

sp.RTED.pg0.v

array([0.48417982, 0.01000094, 0.02000094, 0.01000095, 1.79503641])