Skip to main content

PSS®E Dynamic

Introduction​

The PSS®E Dynamic Node performs dynamic study simulations which are powered by PSS®E, a 3rd party power systems software. It leverages the following PSS®E modules:

  • Dynamic Simulation

This Node is typically used for the following:

  • Completing dynamic studies (e.g. validating Generator Performance Standards).
  • Benchmarking plant models (e.g. comparing the performance of PSS®E and PSCAD™ plant models).
info

The following PSS®E versions are currently supported:

  • PSS®E v34.4+
  • PSS®E v35 :::

User inputs​

Select model​

Title​

Defines the title of the Node.

Example:

DMAT | Table 1

Model​

Defines the input directory and file name of the PSS®E case file, including the .sav file extension. To use the PSS®E case file (.sav) from a linked PSS®E Static Node, select Use model from linked PSS®E Static Node.

Example:

sunny-solar-farm\SMIB.sav

File paths are relative to the Engine's 'inputs' directory, as defined by the Engine configuration parameter dirs.inputs. For example, if dirs.inputs was set as C:\Users\johnsmith\gridmo\Inputs\:

Absolute file pathRelative file path (required by gridmo)
C:\Users\johnsmith\gridmo\Inputs\sunny-solar-farm\SMIB.savsunny-solar-farm\SMIB.sav

:::

Dynamics model data​

Defines the input directory and file name of the PSS®E dynamics model data file, including the .dyr file extension.

Example:

sunny-solar-farm\settings.dyr

Alternatively, specify a directory and all .dyr files in the directory will be loaded into PSS®E.

Example of loading all in a folder:

sunny-solar-farm\

Dynamics user models​

Defines the input directory of the PSS®E dynamics user models.

Example:

sunny-solar-farm\dll-folder
caution

All .dll files located in the specified folder will be loaded into PSS®E. Ensure all .dll files in this folder are compatible with the PSS®E version you are using.

Define simulation​

Simulation time​

Defines the duration of the dynamic study in seconds.

Example: Run a 30 second dynamic simulation.

30
note

The minimum simulation time is 0.1 seconds.

info

The resolution of the output data (plot step) is automatically reduced if the simulation time is above 200 seconds.

This is to reduce size of output files and temporary files generated during the simulation.

For example, if gridmo is running a 950 second long simulation, gridmo will set PSS®E's plot step so that one channel data point is exported for every nine time steps, based on the below relationship.

graph on the horizontal axis is simulation time and vertical axis is plot step scaling factor

Control Thévenin equivalent source​

These controls allow you to define the behaviour of the grid. There are three options:

  • None: No additional grid behaviour is incorporated.
  • SMIB: The grid is modelled as an infinite bus generator for SMIB studies. One of the following may be controlled in a Node:
    • Voltage [p.u.]
    • Frequency [Hz]
    • Angle [degrees]
  • Network: This is used in conjunction with the PSS®E Static Node Network functionality which allows you to merge your model into a network model.
info

To use the SMIB control functionality, the PSS®E case file must be configured as follows:

  • The case file (.sav) has a single slack bus with a single slack generator.
  • The case file (.sav) has a single line between the slack bus and the plant model. This line represents the Thévenin equivalent source impedance of the infinite bus.

Example of a correctly configured PSS®E case file:

single line diagram from the PSS®E software package showing a correctly configured single machine infinite bus model for use with gridmo

note

If SMIB control functionality is enabled, the slack bus generator dynamic model (e.g. GENCLS) will be replaced with PLBVF1 or PLBVFU1 model (as required by your version of PSS®E) to allow voltage and frequency playback.

Voltage​

Defines the infinite bus generator voltage throughout the dynamic simulation. Enter a series of time [s], voltage [p.u.] pairs. The voltage is linearly interpolated between points. There are two methods for specifying the voltage - absolute and relative.

note

If your PSS®E dynamic study uses a case file from a linked PSS®E Static Node, it is often convenient to specify the voltage using the relative method, since it will utilise the infinite bus generator voltage solution from that specific case.

Specifying absolute voltage​

Defines the infinite bus generator voltage throughout the dynamic simulation by specifying absolute voltage [p.u.].

Example: Perform a 15 second dynamic simulation. At 5 seconds, step the voltage from 1.00 [p.u.] to 0.95 [p.u.] in a single rapid step. At 10 seconds, ramp the voltage back up to 1.00 [p.u.] over 2 seconds.

Example
0,      1.00
4.9999, 1.00
5,      0.95
10,     0.95
12,     1.00
15,     1.00
Plot
voltage-absolute-playback-plot
Specifying relative voltage​

Defines the infinite bus generator voltage throughout the dynamic simulation by specifying relative voltage [pu]. The voltage change is relative to the voltage of the infinite bus generator voltage at the start of the dynamic simulation.

Example: Perform a 45 second dynamic simulation. At 5 seconds, step the voltage up 0.05 per unit (pu) in a single rapid step. At 15 seconds, step the voltage down to its initial value in a single rapid step. At 25 seconds, step the voltage down 0.05 per unit (pu) in a single rapid step. At 35 seconds, step the voltage up to its initial value in a single rapid step.

Example
0,      0 pu
4.999,  0 pu
5,      +0.05 pu
14.999, +0.05 pu
15,     0 pu
24.999, 0 pu
25,     -0.05 pu
34.999, -0.05 pu
35,     0 pu
45,     0 pu
Plot
voltage-relative-playback-plot
Frequency​

Defines the infinite bus frequency throughout the dynamic simulation. Enter a series of time [s], frequency [Hz] pairs. The frequency is linearly interpolated between points.

Example: Perform a 25 second dynamic simulation. At 5 seconds, ramp the frequency up from 50.0 [Hz] to 52.0 [Hz] over 3 seconds. At 15 seconds, ramp the frequency back down to 50.0 [Hz] over 3 seconds.

Example
0,  50
5,  50
8,  52
15, 52
18, 50
25, 50
Plot
frequency-playback-plot
Angle​

Defines the infinite bus voltage phase angle throughout the dynamic simulation. Enter a series of time [s], angle [degrees] pairs. The voltage phase angle is not linearly interpolated between points - instead the angle is set to the absolute value at the time specified. The voltage phase angle values specified are relative to the initial angle at the infinite bus - which is typically 0° for SMIB studies. The phase angle is modified by inserting a lossless two-winding transformer next to the infinite bus, as shown below.

screenshot from the PSS®E software platform, showing a single line diagram with an arrow showing the lossless transformer automatically inserted by the gridmo engine

caution

Voltage phase angle changes are instantaneous. Ramps are not supported.

Example: Perform a 20 second dynamic simulation. At 5 seconds, step the voltage phase angle from 0° to 40°. At 15 seconds, step the voltage phase angle back to 0°.

Example
0,  0
5,  40
15,  0
Plot
angle-playback-plot

Merge into network​

Network dynamics model data​

Defines the input directory and file name of the network PSS®E dynamics model data file, including the .dyr file extension. This PSS®E dynamics model data is appended to the data specified in the Dynamics model data file.

Example:

network-model\settings.dyr

Alternatively, specify a directory and all .dyr files in the directory will be loaded into PSS®E.

Example of loading all in a folder:

network-model\psse\
Network dynamics user models​

Defines the input directory of the network PSS®E dynamics user models. These PSS®E dynamics user models are added to the user models specified in the PSS®E dynamics user models folder.

Example:

network-model\dll-folder
caution

All .dll files located in the specified folder will be loaded into PSS®E. Ensure all .dll files in this folder are compatible with the PSS®E version you are using.

Actions​

Defines the Commands which configure the dynamic simulation.

Supported Commands:

  • ADD: Adds a new network element for a fixed duration (e.g. capacitor, reactor).
  • SET: Sets the status or value of a network element (e.g. bus, line, generator).
  • CONTROL: Controls a network element.
  • SIMPLEFAULT: Applies a simple power system fault.
  • MULTIFAULT: Applies a simple power system fault.
  • ADVFAULT: Applies an advanced power system fault.
  • VDISTURBANCE: Applies a relative over or under voltage disturbance using a fault or shunt (capacitor).
  • SCALE_LOADS: Scales all loads in a model (or a subsystem within that model) by a specified factor.

Old Commands (not recommended for new projects):

  • TOVTEST: Completes a Transient Over-Voltage (TOV) test.
info

All Action Commands (except SET) include the AT= argument, which specifies the time [s] at which the Command is applied. Specifying AT=0 will apply the Command at the very first time step once the dynamic simulation has been initialised. Specifying AT=-1 will apply the Command at once the dynamic data record has been loaded, but before the dynamic simulation has been initialised.

caution

If you specify the value of the AT= argument beyond the simulation duration (e.g. simulation duration is 20 [s] and AT=25), the Command will not be applied and a warning will be raised.

Define outputs​

Outputs​

Defines the output channels of the dynamic simulation. The output channels defined here may be used later for plotting and/or further analysis.

Supported Commands:

info

OUTPUT Commands do not require the AT= argument because dynamic simulation values are recorded for the entire simulation.

Description​

Defines a short description of the dynamic simulation. This description will appear in the legend of any plot of the data generated by this Node.

Example:

Description here!

example from a Plot Node PDF output showing how the 'Description here!' text is added

Advanced​

PSS®E version​

Defines the PSS®E version used for the Node. Defaults to Engine configuration.

PSS®E Python API​

Defines the PSS®E API version used for the Node. Defaults to Engine configuration.

Distance factor​

Defines the distance from the connection point at which disturbances are applied. Allowable values are between 0 and 1, where d=1 applies disturbances at the connection point. The image below shows a Thévenin equivalent of the grid as used in SMIB studies, commonly referred to as the 'infinite source', whereby:

  • Vinf: Thévenin equivalent voltage source.
  • Zinf: Thévenin equivalent impedance.
  • Zf: Disturbance impedance.
  • d: Distance factor.
  • Vpoc: Connection point voltage prior to any disturbance.
dFactor

Distance factor will apply to all relevant Commands in the Node such as:

  • TOVTEST
  • VDISTURBANCE
  • SIMPLEFAULT
  • MULTIFAULT

Advanced Parameters​

Advanced Parameters allow users to configure test details which are not commonly used. Advanced Parameters are often specific to each Node type.

Each line represents a new Advanced Parameter and is entered as a=b format, where a is the name of the Parameter and b is the corresponding value. All Advanced Parameters are set to their default values if they are not included in the Advanced Parameters field.

Example: Set Advanced Parameter, sample.parameter to a value of 5.

sample.parameter=5

API Reference​

This section details the Commands and Advanced Parameters specific to the Node.

tip

Lines are defined using the following syntax: from->to#id. When completing SMIB studies, we recommend always having the 'to' bus closer to the connection point. Note that the 'from' and 'to' definitions used in Commands (i.e. from->to#id) don't necessarily need to match the .sav case.

ADD Command​

Add capacitor​

ADD, TYPE=CAP, BUS=, AT=, DURATION=, Q=

Adds a capacitor onto a bus for a fixed duration.

Arguments:

  • ADD
  • TYPE (str): Network element type. Set as CAP.
  • BUS (int): Bus number.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • Q (float): Reactive power rating of the capacitor [MVAr].
  • DURATION (float): Fixed duration [ms]. When the duration has expired, the capacitor is disconnected and the bus will remain in-service.

Example: Add a 20 MVAr capacitor to bus 500, turning the capacitor on at 5 seconds and off again at 5.8 seconds.

ADD, TYPE=CAP, BUS=500, AT=5 DURATION=800, Q=20

Add reactor​

ADD, TYPE=REACTOR, BUS=, AT=, DURATION=, Q=

Adds a reactor onto a bus for a fixed duration.

Arguments:

  • ADD
  • TYPE (str): Network element type. Set as REACTOR.
  • BUS (int): Bus number.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • DURATION (float): Fixed duration [ms]. When the duration has expired, the reactor is disconnected and the bus will remain in-service.
  • Q (float): Reactive power rating of the reactor [MVAr].

Example: Add a 80 MVAr reactor to bus 200, turning the reactor on at 11 seconds and off at 12.7 seconds.

ADD, TYPE=REACTOR, BUS=200, AT=11, DURATION=1700, Q=80
note

gridmo automatically manages the bus identifiers of capacitors and reactor to avoid clashes with existing assets.

SET Command​

Set bus​

SET, BUS=, [BUS=], AT=, STATUS=

Sets the status of a bus.

Arguments:

  • SET
  • BUS (int): Bus number.
  • BUS (int)[Optional]: Additional bus numbers.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • STATUS (str): Bus status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.

Example: At 5 seconds, set bus 100 out of service.

SET, BUS=100, AT=5, STATUS=OUT

Set line​

SET, LINE=, [LINE=], AT=, STATUS=, [SCR=, XR=]

Sets the status and impedance of a line.

Arguments:

  • SET
  • LINE (pas): Line definition. Lines are defined using the following syntax: from->to#id.
  • LINE (pas)[Optional]: Additional line definitions (only if using STATUS=, SCR= and XR= arguments only support one line)
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • STATUS (str): Line status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.
  • SCR (float)[Optional]:
    • SCR=X (where X is a number): Sets the impedance of the given line to the equivalent Thévenin impedance based on the Project's rated active power [MW], the line voltage and the specified SCR and X/R ratio.
    • SCR=INF: Sets the impedance of the given line to the minimum impedance value applicable in PSS®E (i.e. 1e-5 on system base). XR= Argument is ignored.
  • XR (float)[Optional]: Sets the impedance of the given line to the equivalent Thévenin impedance based on the Project's rated active power [MW], the line voltage and the specified SCR and X/R ratio.
note

SCR and XR Arguments must be used together. These Arguments are typically only used in SMIB studies and are used to calculate the Thévenin equivalent source impedance of the infinite generator.

Example: At 14.7 seconds, set the impedance of the line from bus 800 to bus 900 which has an ID of 1. The line impedance should represent the system Thévenin equivalent impedance for an SCR of 3 and X/R ratio of 2.

SET, LINE=800->900#1, AT=14.7, STATUS=IN, SCR=3, XR=2

Set transformer​

SET, TX=, AT=, [STATUS=, TAPRATIO=, WINDING=]

Sets the status of a transformer.

Arguments:

  • SET
  • TX (pas): Transformer definition. Transformers are defined using the following syntax: bus1->bus2#id (two-winding transformer) or bus1->bus2->bus3#id (three-winding transformer).
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • STATUS (str)[Optional]: Transformer status. If not specified, transformer status is not changed from the current state. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.
  • TAPRATIO (float)[Optional]: Sets the tap ratio of the specified winding number.
  • WINDING (int)[Optional]: The winding number used when setting the tap ratio. Options:
    • WINDING=1: Winding number 1.
    • WINDING=2: Winding number 2.
    • WINDING=3: Winding number 3 (only applicable for three-winding transformers).

Example: At 2 seconds, set the three-winding transformer in-service which is located between bus 100, bus 200, and bus 300 and which has an ID of 1.

SET, TX=100->200->300#1, AT=2, STATUS=IN

Example: After 10 seconds in the dynamic simulation, set the tap position of winding one of the two-winding transformer to 0.975 which is located between bus 100 and bus 200 and which has an ID of 1.

SET, AT=10, TX=100->200#1, TAPRATIO=0.975, WINDING=1

Set generator​

SET, GEN=, [GEN=], AT=, STATUS=, [QMAX=, QMIN=, PMAX=, PMIN=, MBASE=, VALSCALE=1]

Sets the status of a generator.

Arguments:

  • SET
  • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
  • GEN (pas)[Optional]: Additional generator definitions.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • STATUS (str): Generator status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.
  • QMAX (float)[Optional]: Maximum reactive power capability of the generator [MVAr].
  • QMIN (float)[Optional]: Minimum reactive power capability of the generator [MVAr].
  • PMAX (float)[Optional]: Maximum active power capability of the generator [MW].
  • PMIN (float)[Optional]: Minimum active power capability of the generator [MW].
  • MBASE (float)[Optional]: Base MVA of the generator [MVA].
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to QMAX, QMIN, PMAX and PMIN (i.e. PMAX x VALSCALE). Default value is 1.
info

Changing active/reactive power limits during a dynamic simulation may not be supported by all user-defined models.

Consider using AT=-1 to set the limits before the dynamic simulation is initialised, or make the change in a linked PSS®E Static Node using a SET Command.

Example: At 19 seconds, set the generator out of service which is located at bus 100 which has an ID of 1.

SET, GEN=100#1, AT=19, STATUS=OUT

Example: Set the aggregated generator at bus 150 with id 1 active power min and maximum range to -1.5 MW prior to dynamic model initialisation (for example, to represent a synchronous machine operating in synchronous condenser mode).

SET, GEN=150#1, AT=-1, PMIN=-1.5, PMAX=-1.5

Set load​

SET, LOAD=, AT=, STATUS=

Sets the status of a load.

Arguments:

  • SET
  • LOAD (pas): Load definition. Loads are defined using the following syntax: bus#id.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • STATUS (str): Load status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.

Example: At 45 seconds, set the load out of service which is located at bus 100 and which has an ID of 2.

SET, LOAD=100#2, AT=45, STATUS=OUT

Set fixed shunt​

SET, FSHUNT=, AT=, STATUS=

Sets the status of a fixed shunt.

Arguments:

  • SET
  • FSHUNT (pas): Fixed shunt definition. Fixed shunts are defined using the following syntax: bus#id.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • STATUS (str): Fixed shunt status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.
note

In PSS®E, fixed shunts are different network elements to loads.

Example: At 55 seconds, set the fixed shunt out of service which is located at bus 200 and which has an ID of 3.

SET, FSHUNT=200#3, AT=55, STATUS=OUT

CONTROL Command​

Control CON​

CONTROL, GEN/BUS/MINS=, [GEN/BUS/MINS=], DYRMODEL=, CON=, [VALSCALE=1], AT=, VAL/RELVAL=

Controls one generator (or generator controller) by changing the specified Constant Parameter (CON).

Arguments:

  • CONTROL
  • GEN or BUS or MINS:
    • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • GEN (pas)[Optional]: Additional generator definitions. Generators are defined using the following syntax: bus#id.
    • BUS (int): Bus number.
    • BUS (pas)[Optional]: Additional bus numbers.
    • MINS (int): Miscellaneous (other) type model global model instance identifier.
    • MINS (int)[Optional]: Additional miscellaneous (other) type model global model instance identifier.
  • DYRMODEL (str): Model name as specified in the dynamic model data file (.dyr).
  • CON (str): Constant Parameter ID. Must include J+. CONs are zero-indexed and apply to the generator itself, not the location of the relevant CON in the PSS®E CON array.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to VAL or RELVAL (i.e. new_value = VAL x VALSCALE or new_value = old_value + (RELVAL x VALSCALE)). Default value is 1.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s]. Use AT=-1 to set the variable before dynamic model initialisation.
  • VAL or RELVAL:
    • VAL (float): New value, expressed absolutely (i.e. new_value = VAL).
    • RELVAL (float): New value, expressed relatively (i.e. new_value = old_value + RELVAL).

Example: At 2 seconds, change the machine parameters of the GENSAL (salient pole) generator at bus 100 which has an ID of 1. Change CON J+3 (H, machine inertia) to a new value of H=0.78 MWs/MVA.

CONTROL, GEN=100#1, DYRMODEL=GENSAL, CON=J+3, AT=2, VAL=0.78

Example: At 2 seconds, change the machine parameters of the GENSAL (salient pole) generator at bus 100 which has an ID of 1. Increase CON J+3 (H, machine inertia) by 0.1 MWs/MVA.

CONTROL, GEN=100#1, DYRMODEL=GENSAL, CON=J+3, AT=2, RELVAL=0.1

Control ICON​

CONTROL, GEN/BUS/MINS=, [GEN/BUS/MINS=], DYRMODEL=, ICON=, [VALSCALE=1], AT=, VAL/RELVAL=

Controls one generator (or generator controller) by changing the specified Integer Parameter (ICON).

Arguments:

  • CONTROL
  • GEN or BUS or MINS:
    • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • GEN (pas)[Optional]: Additional generator definitions. Generators are defined using the following syntax: bus#id.
    • BUS (int): Bus number.
    • BUS (pas)[Optional]: Additional bus numbers.
    • MINS (int): Miscellaneous (other) type model global model instance identifier.
    • MINS (int)[Optional]: Additional miscellaneous (other) type model global model instance identifier.
  • DYRMODEL (str): Model name as specified in the dynamic model data file (.dyr).
  • ICON (str): Integer Parameter (ICON) ID. Must include M+. ICONs are zero-indexed and apply to the generator itself, not the location of the relevant ICON in the PSS®E ICON array.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to VAL or RELVAL (i.e. new_value = VAL x VALSCALE or new_value = old_value + (RELVAL x VALSCALE)). Default value is 1.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s]. Use AT=-1 to set the variable before dynamic model initialisation.
  • VAL or RELVAL:
    • VAL (int): New value, expressed absolutely (i.e. new_value = VAL).
    • RELVAL (int): New value, expressed relatively (i.e. new_value = old_value + RELVAL).

Example: At 5 seconds, change the controller parameter of the WT4E2 wind generator controller at bus 200 with an ID of 1. Change ICON M+5 (PQ priority flag for current limit) to 1 for P priority.

CONTROL, GEN=200#1, DYRMODEL=WT4E2, ICON=M+5, AT=5, VAL=1

Control VAR​

CONTROL, GEN/BUS/MINS=, [GEN/BUS/MINS=], DYRMODEL=, VAR=, [VALSCALE=1], AT=, VAL/RELVAL=

Controls one generator (or generator controller) by changing the specified Algebraic Variable (VAR).

Arguments:

  • CONTROL
  • GEN or BUS or MINS:
    • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • GEN (pas)[Optional]: Additional generator definitions. Generators are defined using the following syntax: bus#id.
    • BUS (int): Bus number.
    • BUS (int)[Optional]: Additional bus numbers.
    • MINS (int): Miscellaneous (other) type model global model instance identifier.
    • MINS (int)[Optional]: Additional miscellaneous (other) type model global model instance identifier.
  • DYRMODEL (str): Model name as specified in the dynamic model data file (.dyr).
  • VAR (str): Algebraic Variable (VAR) ID. Must include L+. VARs are zero-indexed and apply to the generator itself, not the location of the relevant VAR in the PSS®E VAR array.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to VAL or RELVAL (i.e. new_value = VAL x VALSCALE or new_value = old_value + (RELVAL x VALSCALE)). Default value is 1.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s]. Use AT=-1 to set the variable before dynamic model initialisation.
  • VAL or RELVAL:
    • VAL (float): New value, expressed absolutely (i.e. new_value = VAL).
    • RELVAL (float): New value, expressed relatively (i.e. new_value = old_value + RELVAL).
danger

Some PSS®E dynamic models use VARs for internal calculations. Therefore, changing a VAR may not have the intended result as your new value may be overridden by the model's internal calculation on the next time step.

Example: At 10.7 seconds, change the controller parameter of the REPCBU1 "other" bus model (USRBUS) at bus 1500. Change VAR L+1 (QREF, reactive power reference) to 0.15 [p.u.] on controller base.

CONTROL, BUS=1500, DYRMODEL=REPCBU1, VAR=L+1, AT=10.7, VAL=0.15

Example: At 15 seconds, change the controller parameter of the REPCA1 "other" bus model at bus 1000. Increase VAR L+3 (Active power reference) by 0.1 [p.u.] on controller base.

CONTROL, BUS=1000, DYRMODEL=REPCA1, VAR=L+3, AT=15, RELVAL=0.1

Control VREF​

CONTROL, GEN=, [GEN=], [VALSCALE=1], AT=, VREF=

Controls one generator (or generator controller) by changing the voltage reference.

Arguments:

  • CONTROL
  • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
  • GEN (pas)[Optional]: Additional generator definitions. Generators are defined using the following syntax: bus#id.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to VREF (i.e. VREF x VALSCALE). Default value is 1.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • VREF: Generator voltage reference. There are two methods for specifying the voltage reference:
    • Absolute voltage (float): Absolute voltage [p.u.] (e.g. 1.07); or
    • Relative voltage (str): Relative voltage [pu] (e.g. +0.05 pu). The change is relative to the value at the start of the dynamic simulation (e.g. A +0.05 pu change followed by a -0.05 pu change will return VREF to its starting value).

Example: At 5 seconds, change the voltage reference of the generator model at bus 500 with an ID of 2. Change VREF (voltage reference) to 1.01 [p.u.].

CONTROL, GEN=500#2, AT=5, VREF=1.01

Example: At 5 seconds, change the voltage reference of the generator model at bus 500 with an ID of 2. Change VREF (voltage reference) by 0.04 per unit [pu] relative to the original VREF value before the start of the dynamic simulation.

CONTROL, GEN=500#2, AT=5, VREF=0.04 pu

Control GREF​

CONTROL, GEN=, [GEN=], [VALSCALE=1], AT=, GREF=

Controls one generator (or generator controller) by changing the governor (speed) reference.

Arguments:

  • CONTROL
  • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
  • GEN (pas)[Optional]: Additional generator definitions. Generators are defined using the following syntax: bus#id.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to GREF (i.e. GREF x VALSCALE). Default value is 1.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • GREF: Generator governor reference. There are two methods for specifying the reference:
    • Absolute speed deviation (float): Absolute speed deviation value [p.u. ] (e.g. 0.045); or
    • Relative speed deviation (str): Relative speed deviation [pu] (e.g. +0.05 pu). The change is relative to the value at the start of the dynamic simulation (e.g. A +0.05 pu change followed by a -0.05 pu change will return GREF to its starting value).

Example: At 5 seconds, change the governor reference of the generator model at bus 500 with an ID of 2. Change GREF (governor speed deviation) to 0.02 [p.u.].

CONTROL, GEN=500#2, AT=5, GREF=0.02

Example: At 5 seconds, change the governor reference of the GENROE generator model at bus 500 with an ID of 2. Change GREF (governor speed deviation) by +0.02 [pu] relative to the original GREF value before the start of the dynamic simulation.

CONTROL, GEN=500#2, AT=5, GREF=0.02 pu

SIMPLEFAULT Command​

SIMPLEFAULT, LINE=, AT=, DURATION=, [FZ=0, XR=3]

Applies a simple three phase fault at a line. The line remains in-service during and after the fault is cleared. Fault impedance can be specified in ohms or residual voltage (for SMIB studies).

info

SIMPLEFAULT is typically used in SMIB studies for simpler fault-related performance studies. For more realistic fault scenarios, as required in wide area network studies, we recommend using the ADVFAULT Command.

Arguments:

  • SIMPLEFAULT
  • LINE (pas): Line definition. Lines are defined using the following syntax: from->to#id.
  • AT (float): Time at which the fault is applied during the dynamic simulation [s].
  • DURATION (float): Fault duration [ms]. When the duration has expired, the fault is removed and the line will remain in service.
  • FZ [Optional]: Fault impedance. Default value is 0 Ω (i.e. bolted fault). There are two methods for specifying the fault:
    • Fault impedance (float): Fault impedance [Ω] (e.g. 0.2).
    • Residual voltage (str): Residual voltage [%] (e.g. 20%). The percentage is relative to the nominal voltage. This method is used in SMIB studies.
  • XR (float)[Optional]: Reactance to resistance ratio of the fault. Default value is 3.
danger

PSS®E only natively supports three phase (3PH) faults. Three phase to ground (3PHG) are not natively supported.

Example:

  • At 5 seconds, apply a three phase fault at the connection point bus of the SMIB model (where the from bus 500 is the connection point and the to bus 999 is the slack bus).
  • Fault duration is 430 ms.
  • Fault impedance is Zf=Zs (meaning 50% residual voltage).
  • X/R ratio of the fault is 3.
SIMPLEFAULT, LINE=500->999#1, AT=5, DURATION=430, FZ=50%

MULTIFAULT Command​

MULTIFAULT, LINE=, AT=, TYPE=, SEQ=, [XR=3]

Applies a pre-defined multiple fault sequence in one Command. The first fault is at AT= seconds. Fault X/R ratio and fault distance percentage can also optionally be provided.

info

MULTIFAULT is typically used in SMIB studies for simple one-Command multiple-fault ride-through (MFRT) studies. For more realistic fault scenarios, as required in wide area network studies, we recommend using the ADVFAULT Command.

Arguments:

  • MULTIFAULT
  • LINE (pas): Line definition. Lines are defined using the following syntax: from->to#id.
  • AT (float): Time at which the first fault in the sequence is applied during the dynamic simulation [s].
  • TYPE (str): Type of multiple fault ride through to apply. Options:
    • TYPE=AEMODMAT: AEMO Dynamic Model Acceptance Tests style MFRT tests.
  • SEQ (str): Type of pre-defined multi fault sequence to apply. Options:
    • If TYPE=AEMODMAT:
      • SEQ=Px: Where x is an integer of 1 to 10. P sequence faults are AEMO DMAT balanced MFRT tests. See below for details.
  • XR (float)[Optional]: Reactance to resistance ratio of the fault. Default value is 3.
danger

PSS®E only natively supports three phase (3PH) faults. Three phase to ground (3PHG) are not natively supported.

MULTIFAULT, TYPE=AEMODMAT, LINE=<line>, AT=, SEQ=P1 converts to:

SIMPLEFAULT, LINE=<line>, AT=5.00, DURATION=120, FZ=77.7%
SIMPLEFAULT, LINE=<line>, AT=7.43, DURATION=120, FZ=66.6%
SIMPLEFAULT, LINE=<line>, AT=12.65, DURATION=220, FZ=77.7%
SIMPLEFAULT, LINE=<line>, AT=12.97, DURATION=120, FZ=50%
SIMPLEFAULT, LINE=<line>, AT=13.59, DURATION=220, FZ=50%
SIMPLEFAULT, LINE=<line>, AT=15.21, DURATION=120, FZ=50%
SIMPLEFAULT, LINE=<line>, AT=17.33, DURATION=430, FZ=0%
SIMPLEFAULT, LINE=<line>, AT=17.95, DURATION=220, FZ=50%
SIMPLEFAULT, LINE=<line>, AT=18.18, DURATION=220, FZ=16.6%
SIMPLEFAULT, LINE=<line>, AT=18.41, DURATION=120, FZ=66.6%
SIMPLEFAULT, LINE=<line>, AT=18.83, DURATION=120, FZ=0%
SIMPLEFAULT, LINE=<line>, AT=22.05, DURATION=120, FZ=16.6%
SIMPLEFAULT, LINE=<line>, AT=32.27, DURATION=220, FZ=66.6%
SIMPLEFAULT, LINE=<line>, AT=33.39, DURATION=120, FZ=50%
SIMPLEFAULT, LINE=<line>, AT=40.51, DURATION=220, FZ=16.6%

Example:

  • At 5 seconds, apply the AEMO DMAT MFRT sequnce P6 based on the above definition. Apply to line 500->999#1
MULTIFAULT, LINE=500->999#1, TYPE=AEMODMAT, AT=5, SEQ=P6

ADVFAULT Command​

ADVFAULT, LINE=, AT=, DURATION1=, DURATION2=, DISTANCE%=, [TYPE=3PH, FZ=0, XR=0, AR_RETRIES=0, AR_DEADTIME=, AR_FINALSTATE=]

Applies a power system fault on a line at a specified distance with configurable auto-reclosing and final state.

Arguments:

  • ADVFAULT
  • LINE (pas): Line definition. Lines are defined using the following syntax: from->to#id.
  • AT (float): Time at which the fault is applied during the dynamic simulation [s].
  • DURATION1 (float): Fault duration [ms]. When the duration has expired, the line segment connecting the from bus to the fault will be disconnected.
  • DURATION2 (float): Fault duration [ms]. When the duration has expired, the line segment connecting the to bus to the fault will be disconnected.
  • DISTANCE% (float): The distance of the fault from the from bus to the to bus [%] (i.e. 10% specifies a fault located close to the from bus).
  • TYPE (str)[Optional]: Fault type. Defaults to 3PH. Options:
    • TYPE=3PH: Three phase fault.
    • TYPE=2PHG: Two phase to ground fault.
    • TYPE=PHPH: Phase to phase fault.
    • TYPE=PHG: Phase to ground fault.
  • FZ (float)[Optional]: Fault impedance [Ω]. Default value is 0 Ω (i.e. bolted fault).
  • XR (float)[Optional]: Reactance to resistance ratio of the fault. Default value is 0 (pure resistive fault).
  • AR_RETRIES (int)[Optional]: Number of auto-reclose attempts. Default value is 0. If AR_RETRIES > 0 then the following additional parameters must be provided:
    • AR_DEADTIME (float): Dead time for line reclosure [ms]. Each end of the line has an independent auto-reclose timer (i.e. DURATION1 and DURATION2), but they must have the same dead time.
    • AR_INDEPENDENT_TIMERS (bool)[Optional]: Are the auto-reclose timers at each end of the line independent? Options:
      • [Default] If AR_INDEPENDENT_TIMERS=YES then the auto-reclose timers at each end of the line are independent. This is common for most real-world auto-reclose schemes.
      • If AR_INDEPENDENT_TIMERS=NO then the auto-reclose timers at each end of the line are time-synchronized. Both ends will attempt to auto-reclose at the same time once the dead-time has passed after the slowest clearing end has cleared. Note this arrangement is fictitious and relatively uncommon in real-world applications.
    • AR_FINALSTATE (str): Final state for the line after the fault and AR_RETRIES auto-reclose attempts. Options:
      • AR_FINALSTATE=IN: After the fault and (at least one) auto-reclose attempt(s), the line is back in service.
      • AR_FINALSTATE=OUT: After the fault and (at least one) auto-reclose attempt(s), the line is out of service.
    • AR_CLOSE_ONE_END(int, str)[Optional] Single sided auto-reclose logic. Options:
      • [Default] If AR_CLOSE_ONE_END=frombus where frombus is in the line definition (frombus->tobus#id), only this end of the line will attempt auto-reclose. The other end of the line is assumed to have dead-line blocking which prevents it from reclosing.
      • If AR_CLOSE_ONE_END=tobus where tobus is in the line definition (tobus->tobus#id), only this end of the line will attempt auto-reclose. The other end of the line is assumed to have dead-line blocking which prevents it from reclosing.
      • If AR_CLOSE_ONE_END=NO then both ends of the line will attempt to auto-reclose independently - this is equivalent to there being no dead-line blocking of the auto-reclose logic on this line.
info

The AR_RETRIES argument specifies the total number of retry events, and the AR_FINALSTATE specifies if the final reclose was successful. For example:

  • If AR_RETRIES=1 and AR_FINALSTATE=OUT, the line will attempt to reclose once, the fault will still be present and the line will lock out.
  • If AR_RETRIES=1 and AR_FINALSTATE=IN, the line will attempt to reclose once, the fault will not be present and the line will return to service.
  • If AR_RETRIES=2 and AR_FINALSTATE=IN, the line will attempt to reclose once, fail (fault still present), then reclose again. This second reclose will be successful, the fault will no longer be present and the line will return to service. :::
  • If AR_FINALSTATE=IN, the line will be returned to service and the buses at both ends of the line will be reconnected, even if the bus was disconnected automatically by PSS®E due to being islanded.
  • If AR_FINALSTATE=OUT, the line will stay out of service. The buses at both ends of the line will remain in service unless they were disconnected automatically by PSS®E due to being islanded. :::
danger

PSS®E only natively supports three phase (3PH) faults. Three phase to ground (3PHG) are not natively supported.

danger

AR_RETRIES, AR_DEADTIME and AR_FINALSTATE arguments must be used together. If AR_RETRIES > 0, then AR_DEADTIME and AR_FINALSTATE are required.

Example:

  • At 6 seconds, apply a three phase fault on the line from bus 500 to bus 800 with an ID of 1.
  • The fault is very close to bus 500 (10% of line impedance from bus 500).
  • The fault is a bolted fault and was cleared on both ends in 80 ms and the line is now out of service.
  • No auto-reclose is enabled.

Note TYPE=3PH, FZ=0, XR=0, AR_RETRIES=0, AR_FINALSTATE=OUT have been omitted, as these are the default values.

ADVFAULT, AT=6, LINE=500->800#1, DURATION1=80, DURATION2=80, DISTANCE%=10

Example:

  • At 10 seconds, a phase to phase fault occurs between substation 300 and substation 400. Only one line (ID 1) connects the two substations. The fault occurs 92% down the line (i.e. is very close to bus 400).
  • The fault has an impedance of 3+9j [Ω].
  • Bus 300 clears the fault on its end in zone 2 distance protection in 220 [ms] (the line from bus 300 to the fault is tripped, no acceleration method is installed).
  • Bus 400 clears the fault on its end in zone 1 distance protection in 67 [ms] (the line from bus 400 to the fault is tripped).
  • Bus 300 recloses after a 5 second delay (at 15.220 [s]). The fault is still present. The line from bus 300 to the fault re-trips after 220 [ms].
  • Bus 400 recloses after a 5 second delay (i.e. at 15.067 [s]). The fault is still present. The line from bus 400 to the fault re-trips after 67 [ms].
  • The line is locked out after the reclose attempt and remains out of service.
ADVFAULT, AT=10, LINE=300->400#1, TYPE=PHPH, DURATION1=220, DURATION2=67, DISTANCE%=92, FZ=9.487, XR=3, AR_RETRIES=1, AR_DEADTIME=5000, AR_FINALSTATE=OUT

TOVTEST Command​

danger

TOVTEST Command is no longer recommended for new Projects. Instead, use the VDISTURBANCE Command.

TOVTEST, BUS=, AT=, QCAP=, DURATION=, [TARGET=, LINE=]

Completes a Transient Over-Voltage (TOV) test whereby a fixed shunt (capacitor) is switched in service on BUS= bus of QCAP= MVAr, AT= seconds into the dynamic simulation. The capacitor is removed after DURATION= milliseconds.

Arguments:

  • TOVTEST
  • BUS (int): Bus number to which the capacitor is applied. This is typically the connection point bus in SMIB studies.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • QCAP (float): Options:
    • QCAP=X (whereX is a number): Size of the capacitor to switch in [MVAr].
    • QCAP=CALC: Enables the automatic calculation of the capacitor size to achieve a target overvoltage based on the TARGET= Argument. Any contribution from the generator under test is not included in this calculation.
  • DURATION (float): Disturbance duration [ms]. When the duration has expired, the capacitor is removed.
  • TARGET (float)[Optional]: Only required if QCAP=CALC [p.u.].
  • LINE (float)[Optional]: Line definition of the Thévenin equivalent impedance. Only required if QCAP=CALC. Lines are defined using the following syntax: from->to#id.
danger

Only one TOVTEST Command is supported in a single PSS®E Dynamic Node.

Example: At 10 seconds, switch in a capacitor of 15 MVAr at bus 500 which, based on the SCR and X/R, gives a TOV of 1.15pu. Switch the capacitor out again after 0.9 seconds.

TOVTEST, BUS=500, AT=10, QCAP=15, DURATION=900

Example: At 5 seconds switch in a capacitor large enough to achieve a 1.2 pu over-voltage at the connection point bus 500, using the line 500->999#1 as the source impedance to calculate the correct capacitor size. Switch the capacitor out again after 0.5 seconds.

TOVTEST, BUS=500, AT=5, QCAP=CALC, DURATION=500, TARGET=1.2, LINE=500->999#1

VDISTURBANCE Command​

VDISTURBANCE, LINE=, [OP=VDIVIDER/COMPENSATED], AT=, DURATION=, VCHANGEPU/VPU=, [XR=3]

At AT= seconds after the start of the dynamic simulation, applies a voltage disturbance at the from bus of the LINE=from->to#id. Depending on the values of VCHANGEPU/VPU, OP and the connection point bus voltage prior to the disturbance, the Command automatically switches between:

  • Applying a 3PH fault to create an undervoltage disturbance; or
  • Inserting a capacitor to create an overvoltage disturbance.

The disturbance is removed after DURATION= milliseconds.

note

VDISTURBANCE is only for single machine infinite bus (SMIB) studies. The LINE=from->to#id Argument should be specified where the from bus is the generator point of connection and the to bus is the infinite source.

Arguments:

  • VDISTURBANCE
  • LINE (float): Line definition of the Thévenin equivalent impedance. Lines are defined using the following syntax: from->to#id.
  • OP (str)[Optional]: Calculation methodology. Defaults to OP=VDIVIDER. Options:
    • OP=VDIVIDER: Voltage divider calculation methodology.
    • OP=COMPENSATED: Voltage divider calculation methodology extended to consider generating system contribution prior to voltage disturbances.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].
  • DURATION (float): Disturbance duration [ms]. When the duration has expired, the disturbance is removed.
  • VCHANGEPU or VPU:
    • VCHANGEPU (float): Relative voltage disturbance [p.u.]. The voltage is relative to the from bus voltage of the LINE=from->to#id prior to the disturbance.
    • VPU (float): Absolute voltage disturbance [p.u.].
  • XR (float)[Optional]: Reactance to resistance ratio of the 3PH fault impedance used for undervoltages. Default value is 3. When inserting a capacitor for overvoltage disturbances, XR is ignored.
note

Multiple VDISTURBANCE Commands are supported in a single Node, which may include a mix of under and over voltage disturbances. To enable this functionality, distance factor is fixed at 1 (i.e. all disturbances are applied at the connection point).

Calculation methodology

The image below shows a Thévenin equivalent of the grid as used in SMIB studies, commonly referred to as the 'infinite source', whereby:

  • Vinf: Thévenin equivalent voltage source.
  • Zinf: Thévenin equivalent impedance.
  • Vpoc: Connection point voltage prior to any disturbance.
vdisturbance-general

The VDISTURBANCE Command introduces a fault impedance, Zf, in order to achieve a desired voltage disturbance as specified by VCHANGEPU or VPU. There are two calculation methodologies used to calculate Zf:

  • OP=VDIVIDER; and
  • OP=COMPENSATED.
vdisturbance-vdivider
Zf is calculated using voltage divider circuit theory. The formula assumes that the generating system current contribution prior to the disturbance is ≈ 0 (i.e. Vpoc ≈ Vinf) and the generating system current contribution during the disturbance is ≈ 0.

Example: At 5 seconds, apply a 430 ms voltage disturbance at the connection point which is located at bus 200. The voltage disturbance should cause a -0.1 p.u. relative change in the connection point voltage by applying a 3PH fault. The fault impedance should be calculated using the Thévenin equivalent source impedance of line 200->300#1.

VDISTURBANCE, LINE=200->300#1, AT=5, DURATION=430, VCHANGEPU=-0.1

At 5 seconds, apply a 500 ms voltage disturbance at the connection point which is located at bus 200. The voltage disturbance should target 1.2 p.u. at the connection point voltage by switching in a capacitor. The capacitance should be calculated using the Thévenin equivalent source impedance of line 200->300#1.

VDISTURBANCE, LINE=200->300#1, AT=5, DURATION=500, VPU=1.2

At 5 seconds, apply a 500 ms voltage disturbance at the connection point which is located at bus 200. The voltage disturbance should target 1.2 p.u. at the connection point voltage by switching in a capacitor. The capacitance should be calculated using the Thévenin equivalent source impedance of line 200->300#1. At 10 seconds, once the previous disturbance has cleared, apply another 500 ms voltage disturbance at the connection point which is located at bus 200. The voltage disturbance should target 0.35 p.u. at the connection point voltage by applying a 3PH fault. The fault impedance should be calculated using the Thévenin equivalent source impedance of line 200->300#1.

VDISTURBANCE, LINE=200->300#1, AT=5, DURATION=500, VPU=1.2
VDISTURBANCE, LINE=200->300#1, AT=5, DURATION=500, VPU=0.35

SCALE_LOADS Command​

SCALE_LOADS, CHANGE=, [SUBSYSTEM=ALL], AT=

At AT= seconds after the start of the dynamic simulation, scales all loads (excluding motor loads e.g. ignores all generator models absorbing real power) by a factor of CHANGE=.

Arguments:

  • SCALE_LOADS
  • CHANGE: How to change the loads in the loaded model. There are two methods for specifying the fault:
    • Absolute value (float): Reduce all loads equally by a fixed factor, such as CHANGE = -500 meaning reduce by 500 MW.
    • Relative value (float%): Apply a percentage scale to all loads equally. For example, to reduce all loads by 20% set CHANGE = -20%.
  • SUBSYSTEM (float or ALL)[Optional]: PSS®E subsystem to apply the load scaling to. Default value is ALL. Options:
    • SUBSYSTEM=ALL: Apply the load scaling to all subsystems.
    • SUBSYSTEM=x: Apply the load scaling to subsystem x where x is an int.
  • AT (float): Time at which the Command is applied during the dynamic simulation [s].

Example: Reduce all loads in subsystem 1 in the loaded PSS®E model by 15% at 5 seconds.

SCALE_LOADS, CHANGE=-15%, SUBSYSTEM=1, AT=5

Increase all loads in the loaded PSS®E model by 100 MW (spread evenly across all in service loads) at 5 seconds.

SCALE_LOADS, CHANGE=100, AT=5

OUTPUT Command​

caution

By default when completing SMIB studies, the Thevenin equivalent voltage source and impedance should not be used for POC metering in OUTPUT Commands or in generating system dynamics model data file (i.e. .dyr files). This is for two reasons:

  1. SMIB studies: During certain SMIB events (e.g. faults, consideration of distance factor, voltage phase angle playback), there will be fictitious Thevenin equivalent source contribution or we will need to break the Thevenin equivalent impedance line into multiple parts to complete the event. See the image below considering the example of applying a fault using SIMPLEFAULT; and
  2. Network studies: When your generating system is merged into a network model, the Thevenin equivalent voltage source and impedance will no longer be present and therefore can't be referenced.

For clarity:

  • ✅ Example of recommended POC metering:
    • OUTPUT, BUS=1000, VAL=V, NAME=i_poc_v
    • OUTPUT, TX=1002->1000#1, METERBUS=1000, VAL=P, NAME=i_ch_poc_p
    • OUTPUT, TX=1002->1000#1, METERBUS=1000, VAL=Q, NAME=i_ch_poc_q
  • ❌ Example of incorrect POC metering:
    • OUTPUT, BUS=999, VAL=V, NAME=i_poc_v
    • OUTPUT, LINE=1000->999#1, VAL=P, NAME=i_ch_poc_p
    • OUTPUT, LINE=1000->999#1, VAL=Q, NAME=i_ch_poc_q
PSSE Dynamic recommended POC metering

Output bus variable​

OUTPUT, BUS=, VAL=, [VALSCALE=1], NAME=, [LEGEND=]

Outputs a variable from a bus.

Arguments:

  • OUTPUT
  • BUS (int): Bus number.
  • VAL (str): Bus value. Options:
    • VAL=V: Voltage [p.u.].
    • VAL=F: Frequency [Hz].
    • VAL=ANGLE: Angle [degrees]. Angle is relative to the generator which was specified as the slack generator prior to the start of the dynamic simulation.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to the output value (i.e. scaled_output = VAL x VALSCALE). Default value is 1.
  • PROCESS (str)[Optional]:
    • If VAL=ANGLE:
      • PROCESS=ANGLE_WRAP: Post process the output angle to wrap between -180° to 180°. This can improve benchmarking between PSS®E and other software packages. Default value is no wrapping. Note if enabled, a small note will be added to all plots to indicate that the PSS®E angle channel has been post-processed by gridmo.
  • NAME (str): Output name. Output names must be unique within a Node.
  • LEGEND (str)[Optional]: Subplot legend name. Default value is no legend name.

Example: Output the voltage [p.u] at bus 100, name this output "i_poc_v".

OUTPUT, BUS=100, VAL=V, NAME=i_poc_v

Output line variable​

OUTPUT, LINE=, [METERBUS=], VAL=, [PBASE=, QBASE=, SBASE=, VALSCALE=1], NAME=, [LEGEND=]

Outputs a variable from a line.

Arguments:

  • OUTPUT
  • LINE (pas): Line definition. Lines are defined using the following syntax: from->to#id. Values are given at the 'from-side' of the line.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the LINE= line. Default value is the 'from' bus number as per the LINE= argument.
  • VAL (str): Line value. Options:
    • VAL=P: Active power [MW].
    • VAL=Q: Reactive power [MVAr].
    • VAL=S: Apparent power [MVA].
    • VAL=PF: Power factor [unitless] (positive power factor corresponds to active power travelling towards the to bus from the from bus). Click here for details on how gridmo calculates power factor.
    • VAL=I: Current [p.u.] on SBASE, where I [p.u.] = S [MVA] / (V [p.u.] * SBASE [MVA]).
    • VAL=ID: Active current [p.u.] on PBASE; where ID [p.u.] = P [MW] / (V [p.u.] * PBASE [MW]).
    • VAL=IQ: Reactive current [p.u.] on QBASE; where IQ [p.u.] = Q [MVAr] / (V [p.u.] * QBASE [MVAr]).
  • PBASE (float)[Optional]: MW base used for Id calculation [MW]. Only required if VAL=ID .
  • QBASE (float)[Optional]: MVAr base used for Iq calculation [MVAr]. Only required if VAL=IQ.
  • SBASE (float)[Optional]: MVA base used for I calculation [MVA]. Only required if VAL=I.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to the output value (i.e. scaled_output = VAL x VALSCALE). Default value is 1.
  • NAME (str): Output name. Output names must be unique within a Node.
  • LEGEND (str)[Optional]: Subplot legend name. Default value is no legend name.

Example: Output the active power flowing through the line from bus 100 to bus 200 (measured at the 'from-side' of the line) which has an ID of 1. Name this output "i_poc_p".

OUTPUT, LINE=100->200#1, VAL=P, NAME=i_poc_p

Example: Output the active power flowing through the line from bus 100 to bus 200 (measured at the 'to-side' of the line) which has an ID of 1. Name this output "i_poc_p_farend".

OUTPUT, LINE=100->200#1, METERBUS=200, VAL=P, NAME=i_poc_p_farend

Example: Output the reactive current flowing through the line from bus 100 to bus 200 (measured at the 'from-side' of the line) which has an ID of 1. The QBASE used in the reactive current calculation is 15 MVAr. Name this output i_poc_iq.

OUTPUT, LINE=100->200#1, VAL=IQ, QBASE=15, NAME=i_poc_iq

Output transformer variable​

OUTPUT, TX=, [METERBUS=], VAL=, [PBASE=, QBASE=, SBASE=, VALSCALE=1], NAME=, [LEGEND=]

Outputs a variable from a transformer.

Arguments:

  • OUTPUT
  • TX (pas): Transformer definition. Transformers are defined using the following syntax: bus1->bus2#id (two-winding transformer) or bus1->bus2->bus3#id (three-winding transformer).
  • METERBUS (int)[Optional]: Bus number which is the metering point for the TX= line. Default value is the 'from' bus number as per the TX= argument.
  • VAL (str): Transformer value. Options:
    • VAL=P: Active power [MW].
    • VAL=Q: Reactive power [MVAr].
    • VAL=S: Apparent power [MVA].
    • VAL=PF: Power factor [unitless] (positive power factor corresponds to active power travelling towards the to bus from the from bus). Click here for details on how gridmo calculates power factor.
    • VAL=I: Current [p.u.] on SBASE, where I [p.u.] = S [MVA] / (V [p.u.] * SBASE [MVA]).
    • VAL=ID: Active current [p.u.] on PBASE; where ID [p.u.] = P [MW] / (V [p.u.] * PBASE [MW]).
    • VAL=IQ: Reactive current [p.u.] on QBASE; where IQ [p.u.] = Q [MVAr] / (V [p.u.] * QBASE [MVAr]).
  • PBASE (float)[Optional]: MW base used for Id calculation [MW]. Only required if VAL=ID .
  • QBASE (float)[Optional]: MVAr base used for Iq calculation [MVAr]. Only required if VAL=IQ.
  • SBASE (float)[Optional]: MVA base used for I calculation [MVA]. Only required if VAL=I.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to the output value (i.e. scaled_output = VAL x VALSCALE). Default value is 1.
  • NAME (str): Output name. Output names must be unique within a Node.
  • LEGEND (str)[Optional]: Subplot legend name. Default value is no legend name.
danger

The OUTPUT, TX= Command currently only supports two-winding transformers. If you need to monitor a three-winding transformer, please consider instead using a 'dummy' line and monitoring that line.

Example: Output the apparent power flowing through the transformer located between bus 500 to bus 900 which has an ID of 2. Name this output, i_tx_loading.

OUTPUT, TX=500->900#2, VAL=S, NAME=i_tx_loading

Output generator variable​

OUTPUT, GEN=, VAL=, [PBASE=, QBASE=, VALSCALE=1], NAME=, [LEGEND=]

Outputs a variable from a generator.

Arguments:

  • OUTPUT
  • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
  • VAL (str): Generator value. Options:
    • VAL=P: Active power [MW].
    • VAL=Q: Reactive power [MVAr].
    • VAL=S: Apparent power [MVA].
    • VAL=PF: Power factor [unitless] (positive power factor corresponds to active power exiting the generator). Click here for details on how gridmo calculates power factor.
    • VAL=ID: Active current [p.u.] on PBASE; where ID [p.u.] = P [MW] / (V [p.u.] * PBASE [MW]).
    • VAL=IQ: Reactive current [p.u.] on QBASE; where IQ [p.u.] = Q [MVAr] / (V [p.u.] * QBASE [MVAr]).
Additional machine variables

  • VAL=ANGLE: Rotor angle [degrees].
  • VAL=EFD: Field voltage [p.u.].
  • VAL=PMECH: Mechanical power [p.u. on MBASE].
  • VAL=SPEED: Speed deviation [p.u.].
  • VAL=XADIFD: Field current [p.u.].
  • VAL=ECOMP: Compensated voltage [p.u.].
  • VAL=VOTHSG: Stabilizer signal [p.u.].
  • VAL=VREF: Regulator reference [p.u.].
  • VAL=VUEL: Minimum excitation limiter signal [p.u.].
  • VAL=VOEL: Maximum excitation limiter signal [p.u.].
  • VAL=GREF: Governor reference [p.u.].
  • VAL=LCREF: Turbine load controller reference [p.u.].
  • VAL=WVLCTY: Wind velocity [m/s].
  • VAL=WTRBSP: Wind turbine speed [p.u.].
  • VAL=WPITCH: Wind pitch [degrees].
  • VAL=WAEROT: Wind aerodynamic torque [p.u.].
  • VAL=WROTRV: Wind rotor voltage [p.u.].
  • VAL=WROTRI: Wind rotor current [p.u.].
  • VAL=WPCMND: Wind active power command from electrical control [p.u.].
  • VAL=WQCMND: Wind reactive power command from electrical control [p.u.].
  • VAL=WAUXSG: Wind auxiliary control output [p.u.].

  • PBASE (float)[Optional]: MW base used for Id calculation [MW]. Only required if VAL=ID .
  • QBASE (float)[Optional]: MVAr base used for Iq calculation [MVAr]. Only required if VAL=IQ.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to the output value (i.e. scaled_output = VAL x VALSCALE). Default value is 1.
  • NAME (str): Output name. Output names must be unique within a Node.
  • LEGEND (str)[Optional]: Subplot legend name. Default value is no legend name.
  • PROCESS (str)[Optional]:
    • If VAL=ANGLE:
      • PROCESS=ANGLE_WRAP: Post process the output angle to wrap between -180° to 180°. This can improve benchmarking between PSS®E and other software packages. Default value is no wrapping. Note if enabled, a small note will be added to all plots to indicate that the PSS®E angle channel has been post-processed by gridmo.

Example: Output the reactive power flowing through the generator located at bus 100 which has an ID of 1. Name this output, "i_terminal_q".

OUTPUT, GEN=100#1, VAL=Q, NAME=i_terminal_q

Example: Output the voltage regulator reference point for a synchronous machine located at bus 35402 which has an ID of 1. Name this output, "i_vref".

OUTPUT, GEN=35402#1, VAL=VREF, NAME=i_vref

Output VAR variable​

OUTPUT, GEN/BUS/MINS=, DYRMODEL=, VAR=, [VALSCALE=], NAME=, [LEGEND=]

Outputs an Algebraic Variable (VAR) from a generator or bus.

Arguments:

  • OUTPUT
  • GEN or BUS or MINS:
    • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • BUS (int): Bus number.
    • MINS (int): Miscellaneous (other) type model global model instance identifier.
  • DYRMODEL (str): Model name as specified in the dynamic model data file (.dyr).
  • VAR (str): Algebraic Variable (VAR) ID. Must include L+. VARs are zero-indexed and apply to the generator itself, not the location of the relevant VAR in the PSS®E VAR array.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to the output value (i.e. scaled_output = VAL x VALSCALE). Default value is 1.
  • NAME (str): Output name. Output names must be unique within a Node.
  • LEGEND (str)[Optional]: Subplot legend name. Default value is no legend name.

Example: Output the reactive power reference of the REPCA1 plant controller at bus 500. Name this output, i_q_ref_val.

OUTPUT, GEN=100#1, DYRMODEL=REPCA1, VAR=L+1, NAME=i_q_ref_val

Output STATE variable​

OUTPUT, GEN/BUS/MINS=, DYRMODEL=, STATE=, [VALSCALE=], NAME=, [LEGEND=]

Outputs a State Variable (STATE) from a generator or bus.

Parameters:

  • OUTPUT
  • GEN or BUS or MINS:
    • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • BUS (int): Bus number.
    • MINS (int): Miscellaneous (other) type model global model instance identifier.
  • DYRMODEL (str): Model name as specified in the dynamic model data file (.dyr).
  • STATE (str): State Variable (STATE) ID. Must include K+. STATEs are zero-indexed and apply to the generator itself, not the location of the relevant STATE in the PSS®E STATE array.
  • VALSCALE (float)[Optional]: Multiplicative scaling factor applied to the output value (i.e. scaled_output = VAL x VALSCALE). Default value is 1.
  • NAME (str): Output name. Output names must be unique within a Node.
  • LEGEND (str)[Optional]: Subplot legend name. Default value is no legend name.

Example: Output the speed deviation (in per unit) of the GENROE model located at bus 100 with ID 1. Name this output, i_delta_speed.

OUTPUT, GEN=100#1, DYRMODEL=GENROE, STATE=K+4, NAME=i_delta_speed

Advanced Parameters​

info

The below default values align with the requirements as per Appendix A1 of AEMO's Dynamic Model Acceptance Guidelines (Appendix A1, item 15) released November 2021.

sim.accel​

  • Description: PSS®E convergence acceleration factor.
  • Type: float
  • Units: N/A
  • Default: 0.2
  • Range: 0.2 to 2.00
sim.accel=value

sim.tolerance​

  • Description: PSS®E convergence tolerance factor.
  • Type: float
  • Units: N/A
  • Default: 0.0001
  • Range: 0.0001 to 0.001
sim.tolerance=value

sim.frequency.filter​

  • Description: PSS®E frequency filter.
  • Type: float
  • Units: N/A
  • Default: 0.008
  • Range: 0.008 to 0.04
sim.frequency.filter=value

sim.timestep​

  • Description: Simulation time step.
  • Type: float
  • Units: [s]
  • Default: 0.001
  • Range: 0.001 to 0.01
sim.timestep=value

sim.maxiter​

  • Description: Simulation iterations per time step.
  • Type: int
  • Units: N/A
  • Default: 600
  • Range: 250 to 600
sim.maxiter=value

sim.relative.angles​

  • Description: Defines whether angles should be relative to the generator which was the slack bus prior to starting the dynamic simulation.
  • Type: bool
  • Units: N/A
  • Default: Yes
  • Range: Yes, No
sim.relative.angles=value

ignore.generators.without.dyre​

  • Description: If set to no (default), the dynamic simulation will not launch unless all generators in the case file have a dynamic model specified in the loaded *.dyr files. If set to yes, any machines without dynamic records are ignored and converted to negative loads.
  • Type: bool
  • Units: N/A
  • Default: No
  • Range: Yes, No
ignore.generators.without.dyre=value

run.chunk.time​

  • Description: Split large dynamic simulations into individal run commands of this many simulation seconds.
  • Type: int
  • Units: [s]
  • Default: 6
  • Range: >= 1
run.chunk.time=value

sim.frequency.network.dependence​

  • Description: Network frequency dependence. If disabled, capacitive and reactive reactance are modelled as fixed values regardless of system frequency.
  • Type: bool
  • Units: N/A
  • Default: No
  • Range: Yes, No
danger

Enabling network frequency dependence may cause unexpected behaviour for some SMIB studies. For example, system voltage may vary during a frequency ramp test.

sim.frequency.network.dependence=value

p.load.constant.current​

  • Description: Defines the percentage of active power (P) load to be converted to a constant current characteristic.
  • Type: float
  • Units: [p.u.]
  • Default: 1
  • Range: 0-1
p.load.constant.current=value

q.load.constant.current​

  • Description: Defines the percentage of reactive power (Q) load to be converted to a constant current characteristic.
  • Type: float
  • Units: [p.u.]
  • Default: 1
  • Range: 0-1
q.load.constant.current=value
note

The balance (remaining proportion) of the p.load.constant.current and 1.load.constant.current are converted to a constant admittance characteristic.

sim.repeat.init.if.suspect​

  • Description: Repeats dynamic initialisation the specified number of times if PSS®E dynamic initial conditions are suspect.
  • Type: int
  • Units: unitless
  • Default: 0
  • Range: >= 0
sim.repeat.init.if.suspect=value

aus.nem.conl​

  • Description: Attempts to apply Australian NEM specific load constant current/constant admittance parameters based on specific loads in the loaded case. Only applicable to Australian NEM network studies.
  • Type: bool
  • Units: N/A
  • Default: No
  • Range: Yes, No
aus.nem.conl=value