.. _TimedEvent: ================================================================================ TimedEvent ================================================================================ Timed event group Common Parameters: u, name Available models: Toggle_, Fault_, Alter_ .. _Toggle: -------------------------------------------------------------------------------- Toggle -------------------------------------------------------------------------------- Time-based connectivity status toggle. Toggle is used to toggle the connection status (online/offline) of a device at the predefined time. Both the model name (or group name) and the device idx need to be specified. It effectively negates the ``u`` field of the connected device. Toggle can be useful to implement disconnection, connection, and reconnection of devices. For example, a line trip can be implemented by setting ``Line`` to the ``model`` field and the corresponding line's ``idx`` to the ``dev`` field. Multiple Toggles can be added to the same device at different times. Adding two Toggles for an initially connected line with ``t=0.1`` and ``t=0.2``, for instance, will disconnect the line at t=0.1 sec and reconnect it at t=0.2 sec. Parameters ---------- +--------+-----------+-----------------------------------+---------+--------+------------+ | Name | Symbol | Description | Default | Unit | Properties | +========+===========+===================================+=========+========+============+ | idx | | unique device idx | | | | +--------+-----------+-----------------------------------+---------+--------+------------+ | u | :math:`u` | connection status | 1 | *bool* | | +--------+-----------+-----------------------------------+---------+--------+------------+ | name | | device name | | | | +--------+-----------+-----------------------------------+---------+--------+------------+ | model | | model or group name of the device | | | mandatory | +--------+-----------+-----------------------------------+---------+--------+------------+ | dev | | idx of the device to control | | | mandatory | +--------+-----------+-----------------------------------+---------+--------+------------+ | t | | switch time for connection status | -1 | | mandatory | +--------+-----------+-----------------------------------+---------+--------+------------+ Services ---------- +------+------------+-----------+--------------+ | Name | Symbol | Equation | Type | +======+============+===========+==============+ | _u | :math:`_u` | :math:`1` | ConstService | +------+------------+-----------+--------------+ Config Fields in [Toggle] +---------------+--------+-------+---------------------------------------+-----------------+ | Option | Symbol | Value | Info | Accepted values | +===============+========+=======+=======================================+=================+ | allow_adjust | | 1 | allow adjusting upper or lower limits | (0, 1) | +---------------+--------+-------+---------------------------------------+-----------------+ | adjust_lower | | 0 | adjust lower limit | (0, 1) | +---------------+--------+-------+---------------------------------------+-----------------+ | adjust_upper | | 1 | adjust upper limit | (0, 1) | +---------------+--------+-------+---------------------------------------+-----------------+ .. _Fault: -------------------------------------------------------------------------------- Fault -------------------------------------------------------------------------------- Three-phase-to-ground fault. A Fault device is used to apply and clear three-phase-to-ground fault to the given bus. One can set two time parameters, ``tf`` and ``tc``, for the fault-on and fault-clearance time, respectively, although only ``tf`` is mandatory. A fault is implemented by a very small internal shunt impedance to be connected at the fault-on time. Its reactance and resistance are specified by the parameters ``xf`` and ``rf``. To implement a fault and its clearance by tripping a line, one can combine ``Fault`` and ``Toggle``. That is, clear a fault in concurrence with a Toggle. The user needs to ensure data consistency so that the line trip actually clears the fault. Non-convergence can occur in the proximity of a fault due to various reasons, including network power transfer capability limitation and parameter issues of controllers. When a fault gets cleared, algebraic variables change drastically. E.g., voltages can go from nearly zero back to 1.0. As we are using Newton's method for solving the DAE, the initial values are crucial for the immediate step after fault clearance. This Fault model restores the pre-fault values for algebraic variables ``Fault.config.scale`` is the scaling factor to be multiplied to the pre-fault values for adjusting the initial values. Some trial and error are expected for severe disturbances, combined with increasing the fault reactance ``xf``. Parameters ---------- +-------+-------------+---------------------------------------+---------+-------------+------------+ | Name | Symbol | Description | Default | Unit | Properties | +=======+=============+=======================================+=========+=============+============+ | idx | | unique device idx | | | | +-------+-------------+---------------------------------------+---------+-------------+------------+ | u | :math:`u` | connection status | 1 | *bool* | | +-------+-------------+---------------------------------------+---------+-------------+------------+ | name | | device name | | | | +-------+-------------+---------------------------------------+---------+-------------+------------+ | bus | | linked bus idx | | | mandatory | +-------+-------------+---------------------------------------+---------+-------------+------------+ | tf | | Bus fault start time | -1 | *second* | mandatory | +-------+-------------+---------------------------------------+---------+-------------+------------+ | tc | | Bus fault end time | -1 | *second* | | +-------+-------------+---------------------------------------+---------+-------------+------------+ | xf | :math:`x_f` | Fault to ground reactance (positive) | 0.000 | *p.u.(sys)* | | +-------+-------------+---------------------------------------+---------+-------------+------------+ | rf | :math:`x_f` | Fault to ground resistance (positive) | 0 | *p.u.(sys)* | | +-------+-------------+---------------------------------------+---------+-------------+------------+ Variables --------- +------+-----------+----------+-----------------------+------------+------------+ | Name | Symbol | Type | Description | Unit | Properties | +======+===========+==========+=======================+============+============+ | a | :math:`a` | ExtAlgeb | Bus voltage angle | *p.u.(kV)* | | +------+-----------+----------+-----------------------+------------+------------+ | v | :math:`v` | ExtAlgeb | Bus voltage magnitude | *p.u.(kV)* | | +------+-----------+----------+-----------------------+------------+------------+ Initialization Equations ------------------------ +------+-----------+----------+---------------+ | Name | Symbol | Type | Initial Value | +======+===========+==========+===============+ | a | :math:`a` | ExtAlgeb | | +------+-----------+----------+---------------+ | v | :math:`v` | ExtAlgeb | | +------+-----------+----------+---------------+ Algebraic Equations ----------------------------- +------+-----------+----------+-------------------------------+ | Name | Symbol | Type | RHS of Equation "0 = g(x, y)" | +======+===========+==========+===============================+ | a | :math:`a` | ExtAlgeb | :math:`gf u uf v^{2}` | +------+-----------+----------+-------------------------------+ | v | :math:`v` | ExtAlgeb | :math:`- bf u uf v^{2}` | +------+-----------+----------+-------------------------------+ Services ---------- +------+---------------+--------------------------------------+--------------+ | Name | Symbol | Equation | Type | +======+===============+======================================+==============+ | gf | :math:`g_{f}` | :math:`\frac{rf}{rf^{2} + xf^{2}}` | ConstService | +------+---------------+--------------------------------------+--------------+ | bf | :math:`b_{f}` | :math:`- \frac{xf}{rf^{2} + xf^{2}}` | ConstService | +------+---------------+--------------------------------------+--------------+ | uf | :math:`u_f` | :math:`0` | ConstService | +------+---------------+--------------------------------------+--------------+ Config Fields in [Fault] +---------------+--------+-------+---------------------------------------------------+-----------------+ | Option | Symbol | Value | Info | Accepted values | +===============+========+=======+===================================================+=================+ | allow_adjust | | 1 | allow adjusting upper or lower limits | (0, 1) | +---------------+--------+-------+---------------------------------------------------+-----------------+ | adjust_lower | | 0 | adjust lower limit | (0, 1) | +---------------+--------+-------+---------------------------------------------------+-----------------+ | adjust_upper | | 1 | adjust upper limit | (0, 1) | +---------------+--------+-------+---------------------------------------------------+-----------------+ | restore | | 1 | restore algebraic variables to pre-fault values | (0, 1) | +---------------+--------+-------+---------------------------------------------------+-----------------+ | mode | | 1 | 1. restore all algeb variables, 2. fault bus only | (1, 2, 3) | +---------------+--------+-------+---------------------------------------------------+-----------------+ | scale | | 1 | scaling factor of restored algebraic values | | +---------------+--------+-------+---------------------------------------------------+-----------------+ .. _Alter: -------------------------------------------------------------------------------- Alter -------------------------------------------------------------------------------- Model for altering device internal data at predefined time. Alter is useful to apply load changing, tap changing, step response, etc. can be applied to parameters and constant services but cannot be used to update variables. Alter is implemented by applying the given calculation to the ``v`` field of the linked parameter or constant. Alter will not affect other parameters or constants that depend on the altered variable. It is not uncommon for equations to depend on intermediate constants rather than the input parameters. Therefore, one will need to inspect model equations to determine the parameter/service to be altered. Examples -------- To apply a PQ load change, according to :ref:`PQ`, one needs to set the load model to constant power and alter ``Ppf`` and ``Qpf``. Altering ``p0`` and ``q0`` will have no impact as they are not used in the equations for time-domain simulation. Parameters ---------- +---------+-----------+----------------------------------------------+---------+--------+------------+ | Name | Symbol | Description | Default | Unit | Properties | +=========+===========+==============================================+=========+========+============+ | idx | | unique device idx | | | | +---------+-----------+----------------------------------------------+---------+--------+------------+ | u | :math:`u` | connection status | 1 | *bool* | | +---------+-----------+----------------------------------------------+---------+--------+------------+ | name | | device name | | | | +---------+-----------+----------------------------------------------+---------+--------+------------+ | t | | switch time for connection status | -1 | | mandatory | +---------+-----------+----------------------------------------------+---------+--------+------------+ | model | | model or group name of the device | | | mandatory | +---------+-----------+----------------------------------------------+---------+--------+------------+ | dev | | idx of the device to alter | | | mandatory | +---------+-----------+----------------------------------------------+---------+--------+------------+ | src | | model source field (param or service) | | | mandatory | +---------+-----------+----------------------------------------------+---------+--------+------------+ | attr | | attribute (e.g., v) of the source field | v | | | +---------+-----------+----------------------------------------------+---------+--------+------------+ | method | | alteration method in `+`, `-`, `*`, `/`, `=` | | | mandatory | +---------+-----------+----------------------------------------------+---------+--------+------------+ | amount | | the amount to apply | | | mandatory | +---------+-----------+----------------------------------------------+---------+--------+------------+ | rand | | use uniform ramdom sampling | 0 | | | +---------+-----------+----------------------------------------------+---------+--------+------------+ | lb | | lower bound of random sampling | 0 | | | +---------+-----------+----------------------------------------------+---------+--------+------------+ | ub | | upper bound of random sampling | 0 | | | +---------+-----------+----------------------------------------------+---------+--------+------------+ Discretes ----------- +------+------------+----------+--------------------------------+ | Name | Symbol | Type | Info | +======+============+==========+================================+ | SW | :math:`SW` | Switcher | Switcher for alteration method | +------+------------+----------+--------------------------------+ Config Fields in [Alter] +---------------+--------+-------+---------------------------------------+-----------------+ | Option | Symbol | Value | Info | Accepted values | +===============+========+=======+=======================================+=================+ | allow_adjust | | 1 | allow adjusting upper or lower limits | (0, 1) | +---------------+--------+-------+---------------------------------------+-----------------+ | adjust_lower | | 0 | adjust lower limit | (0, 1) | +---------------+--------+-------+---------------------------------------+-----------------+ | adjust_upper | | 1 | adjust upper limit | (0, 1) | +---------------+--------+-------+---------------------------------------+-----------------+