Skip to main content

PSS®E Static

Introduction​

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

  • Power Flow
  • Short Circuit

This Node is typically used for the following:

  • Completing static studies (e.g. investigating thermal loading of an asset pre and post a variety of contingencies).
  • Setting up cases for dynamic studies (e.g. creating a case for a specific active power set point as part of a test).
info

Check our system requirements page for information on which PSS®E versions are currently supported.

User inputs​

Select model​

Model​

Defines the input directory and file name of the PSS®E Case file, including the .sav file extension.

Example:

sunny-solar-farm\SMIB.sav
note

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

Define simulation​

This allows you to merge your Model into a network model. If enabled, this merge process is completed before the Commands are applied.

Network model​

Defines the input directory and file name of the PSS®E Case file, including the .sav file extension.

Example:

network-model/case.sav

Model: Bus number​

Defines the bus number in the Model at which the network model is merged.

Example:

100

Network model: Bus number​

Defines the bus number in the Network model at which the model is merged.

Example:

30000

Commands​

Defines the Commands which configure the static simulation.

Supported Commands:

  • ADD: Adds a new type of network element (e.g. generator, load).
  • SET: Sets the status or value of a network element (e.g. bus, line, generator).
  • SCALE_TX: Scales a single transformer's base power, used to simulate a variable number of aggregated transformers.
  • CONTROL: Controls a network element.
  • SOLVE: Solves the static case, considering all previous SET and CONTROL Commands.
  • OUTPUT: Outputs a value as an Internode Variable.

Advanced​

PSS®E version​

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

info

gridmo Engine v1.5.0 onwards supports partial versions. See here for details.

PSS®E Python API​

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

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 generator​

ADD, TYPE=GEN, BUS=, [GEN_ID], PMAX=, PMIN=, QMAX=, QMIN=, [MBASE=100, RSOURCE=0, XSOURCE=1.0]

Adds a generator network element at a specified bus.

Arguments:

  • ADD
  • TYPE (str): Network element type. Set as GEN.
  • BUS (int): Bus number. This bus number must existing within the case file. We will add the generator at this bus and change the bus type code to "2 - Generator Bus".
  • GEN_ID (int)[Optional]: The ID of the newly created generator. If not provided, added generators have a PSS®E ID of x where x is an integer (e.g. 100#1, 100#99).
  • PMAX 🔢 (float): Maximum active power capability of the generator [MW].
  • PMIN 🔢 (float): Minimum active power capability of the generator [MW].
  • QMAX 🔢 (float): Maximum reactive power capability of the generator [MVAr].
  • QMIN 🔢 (float): Minimum reactive power capability of the generator [MVAr].
  • MBASE 🔢 (float)[Optional]: Base MVA of the generator [MVA]. Default value is 100.
  • RSOURCE 🔢 (float)[Optional]: Generator resistance [p.u. on MBASE]. Default value is 0.
  • XSOURCE 🔢 (float)[Optional]: Generator reactance [p.u. on MBASE]. Default value is 1.0.
note

By default, the generator dispatch conditions are set as the following:

  1. Generator terminal active power = 0 MW (i.e. Machine Data -> Pgen (MW) = 0).
  2. Control mode is direct voltage control (i.e. Wind data -> Control Mode = "Conventional Machine").
  3. Voltage control mode regulated bus is set as the bus number from the Argument BUS (i.e. Plant Data -> Sched Voltage = BUS number).
  4. Voltage reference is set as the bus voltage at BUS such that Qgen will be 0 MVAr (i.e. Plant Data -> Sched Voltage = BUS voltage).
Add generator command dispatch defaults

To change the generator dispatch conditions (e.g. Pgen, Qgen, Vref), please use the respective CONTROL Commands.

Example: Add a generator at bus 1000. Bus 1000 is already a generator type bus and therefore we can add the generator directly to this bus. The generator should have the following properties: Pmax = 100MW, Pmin = 20MW, Qmax = 30 MVAr, Qmin = -30MVAr.

ADD, TYPE=GEN, BUS=1000, PMAX=100, PMIN=20, QMAX=30, QMIN=-30

Add load​

ADD, TYPE=LOAD, BUS=, P=, Q=, YP=, YQ=

Adds a load network element at a specified bus.

Arguments:

  • ADD
  • TYPE (str): Network element type. Set as LOAD.
  • BUS (int): Bus number. This bus number must existing within the case file.
  • P 🔢 (float): Constant active power [MW].
  • Q 🔢 (float): Constant reactive power [MVAr].
  • YP 🔢 (float): Constant admittance active power [MW].
  • YQ 🔢 (float): Constant admittance reactive power [MVAr].

At least one of P=, Q=, YP= or YQ= must be specified. Any unspecified values default to 0.

Example: Add a 25 MW, 5 MVAr load at bus 400.

ADD, TYPE=LOAD, BUS=400, P=25, Q=5
note

Added loads have a PSS®E ID of Gx where x is an integer. For example:

  • The Command ADD, BUS=100, P=10 creates a load with identifier 100#G1.
  • If a second ADD, BUS=100, P=10 Command was used, a new load with identifier 100#G2 would be created.

SET Command​

Set bus​

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

Sets the status of a bus.

Arguments:

  • SET
  • BUS (int): Bus number.
  • BUS (int)[Optional]: Additional bus numbers.
  • STATUS (str): Bus status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.
    • STATUS=1: Explicitly set bus type code as 1 (i.e. Non-Gen Bus).
    • STATUS=2: Explicitly set bus type code as 2 (i.e. Generator Bus).
    • STATUS=3: Explicitly set bus type code as 3 (i.e. Swing bus).
    • STATUS=4: Explicitly set bus type code as 4 (i.e. Disconnected).
note

We recommend using STATUS=IN and STATUS=OUT Arguments. Explicitly setting the bus type code is not recommended since it doesn't consider what assets are connected to the selected bus.

Example: Set bus 100 out of service.

SET, BUS=100, STATUS=OUT

Set line​

SET, LINE=, [LINE=, 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)
  • STATUS (str)[Optional]: Line status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.
  • SCR (float)[Optional] Set the Short Circuit Ratio and X/R Ratio:
  • 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.
  • R 🔢 (float)[Optional]: Sets the resistance of the given line to the specified value in ohms.
  • X 🔢 (float)[Optional]: Sets the reactance of the given line to the specified value in ohms.
  • B 🔢 (float)[Optional]: Sets the susceptance of the given line to the specified value in microfarads (µF).
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.

R, X, and B Arguments can be used independently or together to set specific line parameters in ohms and microfarads respectively. Not all three need to be specified.

Example: 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, STATUS=IN, SCR=3, XR=2

Example: Set the impedance of the line from bus 1000 to bus 999 with ID 1 to near-zero impedance (infinite system strength), noting that XR= Argument is ignored.

SET, LINE=1000->999#1, STATUS=IN, SCR=INF, XR=1

Example: Set specific resistance, reactance and susceptance values for a line to model a collector group outage within a solar farm. Sets the line impedance to 0.2 + j1.3 ohms, with 4.7 uF of shunt capacitance.

SET, LINE=300->400#1, STATUS=IN, R=0.2, X=1.3, B=4.7

Set transformer​

SET, TX=, [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).
  • 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. The control mode of the transformer will be set to "None" to ensure the set tap ratio is maintained irrespective of whether SOLVE, LOCKTAPS=NO is used.
  • 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).
danger

The Engine will check that the specified tap ratio is valid given the transformer tap configuration.

If the transformer does not have a tap changer enabled, or the transformer's configuration does not allow the specified tap ratio, the Engine will raise an error.

Example: 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, STATUS=IN

Example: 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, TX=100->200#1, TAPRATIO=0.975, WINDING=1
note

Setting the tap ratio assumes that the transformer winding I/O code is in p.u., not kV.

Set generator​

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

Sets the status or active/reactive power limits of a generator.

Arguments:

  • SET
  • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
  • GEN (pas)[Optional]: Additional generator definitions.
  • STATUS (str): Generator status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.
  • PMAX 🔢 (float)[Optional]: Maximum active power capability of the generator [MW].
  • PMIN 🔢 (float)[Optional]: Minimum active power capability of the generator [MW].
  • QMAX 🔢 (float)[Optional]: Maximum reactive power capability of the generator [MVAr].
  • QMIN 🔢 (float)[Optional]: Minimum reactive power capability of the generator [MVAr].
  • 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

Setting PMIN= or PMAX= will clamp the active power (Pgen) of the generator to within the specified bounds.

Example: Set the generator out of service which is located at bus 100 which has an ID of 1.

SET, GEN=100#1, STATUS=OUT

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

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

Set load​

SET, LOAD=, STATUS=

Sets the status of a load.

Arguments:

  • SET
  • LOAD (pas): Load definition. Loads are defined using the following syntax: bus#id.
  • STATUS (str): Load status. Options:
    • STATUS=IN: Status is in-service.
    • STATUS=OUT: Status is out of service.

Example: Set the load out of service which is located at bus 100 and which has an ID of 2.

SET, LOAD=100#2, STATUS=OUT

Set fixed shunt​

SET, FSHUNT=, 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.
  • 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: Set the fixed shunt out of service which is located at bus 200 and which has an ID of 3.

SET, FSHUNT=200#3, STATUS=OUT

SCALE_TX Command​

SCALE_TX, [TX=], CHANGE=

Applies an absolute or relative scaling factor to one or more transformers. Typically used to simulate a variable number of aggregated transformers.

Arguments:

  • SCALE_TX
  • 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).
  • TX (pas)[Optional]: Additional transformer definition(s).
  • CHANGE: How to scale the specified transformers. Options:
    • Absolute value 🔢 (float): Reduce/increase the specified transformers equally by a fixed factor, such as CHANGE = -2 meaning reduce each transformer's base value by 2 MVA.
    • Relative value (float%): Apply a percentage scale to each transformer specified, such as CHANGE = -20% meaning reduce each transformer's base value by 20%.
danger

For three winding transformers, the CHANGE= specified is applied to each winding.

Example: The transformer between buses 1225 and 1226 with ID 1 represents an aggregatation of 25 equivalent transformers as part of a SMIB model. Scale the transformer so it represents only a single aggregated transformer (for benchmarking purposes with site commissioning data).

SCALE_TX, TX=1225->1226#1, CHANGE=-96%  // 1/25 = 0.04, so scale down by 96% to turn 25 transformers into 1

CONTROL Command​

Control Commands are additional solution requirements added to the convergence algorithm which is initiated by the SOLVE Command. These Commands typically cover functionality which is not natively supported by PSS®E. A SOLVE Command is required for preceding CONTROL Commands to be considered.

note

You can control multiple generators by using multiple GEN= arguments. If more than one generator specified, the active/reactive power requirement will be shared between the generators based on the ratio of the respective generators' rated MVA.

CONTROL_P Active power from generator(s)​

CONTROL_P, GEN=[DEFINITION=, PRIORITY=1, RATIO=], GEN=[...], ATLINE=, [METERBUS=, VALSCALE=1], VAL=

Uses a software agonistic power plant controller to achieve an active power target. The target can be specified at the generator terminals, or at a remote line. Supports dispatch order and active power sharing (and a mixture of both).

Arguments​
  • CONTROL
  • GEN (object): Generator definition with parameters on a per-generator level within square brackets [...]:
    • DEFINITION (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • PRIORITY 🔢 (int)[Optional]:
      • Dispatch priority (order) for this generator. Defaults to 1.
      • Generators with the highest priority will be dispatched first as far as their operational limits allow, then generators in later orders are dispatched next.
    • RATIO 🔢 (float)[Optional]:
      • Sharing ratio for this generator. Defaults to generator base (in MVA).
      • Generators in the same PRIORITY will share the active power target based on their RATIO values.
      • The engine will normalize all share values, so it can be ratios or percentages or pu etc.
  • ATLINE Location of the target active power [Optional].
    • If not specified, the active power target is regulated at the generator terminals.
    • If ATLINE=from->to#id (pas): Active power target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to VAL (i.e. VAL x VALSCALE). Default value is 1.
  • VAL 🔢 (float): Active power setpoint [MW].
Examples​

Solar farm with single aggregated generator

  • Control the aggregated generator at bus 100 with ID 1 to achieve a target active power of 95 MW at the point of connection, between bus 400 and bus 500 with branch ID 1.
CONTROL_P, GEN=[DEFINITION=100#1], ATLINE=400->500#1, VAL=95

Solar farm with multiple aggregated generators

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target active power of 95 MW at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The active power contibution from each generator should be shared equally.
CONTROL_P, GEN=[DEFINITION=100#1, RATIO=0.5], GEN=[DEFINITION=200#2, RATIO=0.5], ATLINE=400->500#1, VAL=95

Solar farm with multiple aggregated generators and priority dispatch

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target active power of 95 MW at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The active power contibution from each generator should be shared equally.
  • Priorise supplying active power from the aggregated solar farm generator at bus 100 before supplying any active power from the aggregated BESS generator at bus 200.
CONTROL_P, GEN=[DEFINITION=100#1, PRIORITY=1], GEN=[DEFINITION=200#2, PRIORITY=2], ATLINE=400->500#1, VAL=95

Solar farm with multiple aggregated generators and unequal power sharing

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target active power of 95 MW at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The active power contibution from each generator should be 70% from the aggregated solar farm generator at bus 100 and 30% from the aggregated solar farm generator at bus 200.
CONTROL_P, GEN=[DEFINITION=100#1, RATIO=70], GEN=[DEFINITION=200#2, RATIO=30], ATLINE=400->500#1, VAL=95

Large wind farm with multiple aggregated generators, power sharing based on relative size

  • Control the four aggregated generators at buses 100, 101, 200 and 201 - all with ID 1.
  • Achieve an active power target of 760 MW at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The active power contibution from each generator should be shared equally based on the relative size of each generator.
CONTROL_P, GEN=[DEFINITION=100#1], GEN=[DEFINITION=101#1], GEN=[DEFINITION=200#1], GEN=[DEFINITION=201#1], ATLINE=400->500#1, VAL=760

CONTROL_VDROOP Voltage droop control from generator(s)​

CONTROL_VDROOP, GEN=[DEFINITION=, PRIORITY=1, RATIO=], GEN=[...], QBASE=, DROOP%=, DEADBAND=, QMIN=, QMAX=, ATBUS=, ATLINE=, [METERBUS=, VALSCALE=1], VAL=

Uses a software agnostic power plant controller to achieve voltage droop control. Controls one or more generators using voltage droop control. If the measured voltage is larger/smaller than the voltage target + deadband, the specified generators will be controlled to absorb/supply reactive power equal to the droop percentage of QBASE for every 1% the measured voltage is above the voltage target + deadband.

voltage droop characteristic with a deadband and fixed maximum and minimum reactive power limits

Arguments​
  • CONTROL_VDROOP
  • GEN (object): Generator definition with parameters on a per-generator level within square brackets [...]:
    • DEFINITION (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • PRIORITY 🔢 (int)[Optional]:
      • Dispatch priority (order) for this generator. Defaults to 1.
      • Generators with the highest priority will be dispatched first as far as their operational limits allow, then generators in later orders are dispatched next.
    • RATIO 🔢 (float)[Optional]:
      • Sharing ratio for this generator. Defaults to generator base (in MVA).
      • Generators in the same PRIORITY will share the reactive power based on their RATIO values.
      • The engine will normalize all share values, so it can be ratios or percentages or pu etc.
  • QBASE 🔢 (float): Base reactive power [MVAr].
  • DROOP% (float): Droop percentage [%].
  • DEADBAND 🔢 (float): Voltage deadband [p.u.].
  • QMIN 🔢 (float)[Optional]: Minimum reactive power limit at the ATLINE= line [MVAr]. Default value is negative infinity.
  • QMAX 🔢 (float)[Optional]: Maximum reactive power limit at the ATLINE= line [MVAr]. Default value is positive infinity.
  • ATBUS (int): Bus number which has the target voltage.
  • ATLINE (pas): Line which is used for measuring the reactive power. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to VAL (i.e. VAL x VALSCALE). Default value is 1.
  • VAL 🔢 (float): Target voltage set point [p.u.].
Examples​

Single generator voltage droop control

  • Control a generator at bus 100 with ID 1 using voltage droop control with a target voltage of 1.01 p.u. at bus 600, a QBASE of 50 MVAr, a droop percentage of 4% and a voltage deadband of 0.01 p.u. The reactive power is measured at the line between bus 600 and bus 700 with branch ID 1.
CONTROL_VDROOP, GEN=[DEFINITION=100#1], QBASE=50, DROOP%=4, DEADBAND=0.01, ATBUS=600, ATLINE=600->700#1, VAL=1.01

Multiple generators with equal sharing

  • Control two generators at bus 100 with ID 1 and bus 200 with ID 1 using voltage droop control. The generators have equal machine base and represent two aggregated collector groups of a wind farm. Target voltage of 1.01 p.u. at bus 600, QBASE of 50 MVAr, droop percentage of 4% and voltage deadband of 0.01 p.u. The static controller logic should not consider existing dispatch files and should ensure reactive power dispatch is shared equally.
CONTROL_VDROOP, GEN=[DEFINITION=100#1, RATIO=0.5], GEN=[DEFINITION=200#1, RATIO=0.5], QBASE=50, DROOP%=4, DEADBAND=0.01, ATBUS=600, ATLINE=600->700#1, VAL=1.01

Multiple generators with priority dispatch

  • Control two generators with priority dispatch where the solar farm generator at bus 100 is prioritised before the BESS generator at bus 200. Target voltage of 1.0 p.u. at bus 500, QBASE of 100 MVAr, droop percentage of 5% and voltage deadband of 0.02 p.u.
CONTROL_VDROOP, GEN=[DEFINITION=100#1, PRIORITY=1], GEN=[DEFINITION=200#1, PRIORITY=2], QBASE=100, DROOP%=5, DEADBAND=0.02, ATBUS=500, ATLINE=500->600#1, VAL=1.0

Multiple generators with unequal power sharing

  • Control two generators with unequal sharing where 70% of reactive power comes from the generator at bus 100 and 30% from the generator at bus 200. Target voltage of 1.02 p.u. at bus 400, QBASE of 75 MVAr, droop percentage of 3% and voltage deadband of 0.015 p.u.
CONTROL_VDROOP, GEN=[DEFINITION=100#1, RATIO=70], GEN=[DEFINITION=200#1, RATIO=30], QBASE=75, DROOP%=3, DEADBAND=0.015, ATBUS=400, ATLINE=400->500#1, VAL=1.02

Large wind farm with multiple generators and reactive power limits

  • Control four generators at buses 100, 101, 200 and 201 (all with ID 1) with reactive power limits. Target voltage of 1.0 p.u. at bus 300, QBASE of 200 MVAr, droop percentage of 6%, voltage deadband of 0.01 p.u., minimum reactive power limit of -150 MVAr and maximum reactive power limit of 150 MVAr.
CONTROL_VDROOP, GEN=[DEFINITION=100#1], GEN=[DEFINITION=101#1], GEN=[DEFINITION=200#1], GEN=[DEFINITION=201#1], QBASE=200, DROOP%=6, DEADBAND=0.01, QMIN=-150, QMAX=150, ATBUS=300, ATLINE=300->400#1, VAL=1.0

CONTROL_VDIRECT Direct voltage control from generator(s)​

CONTROL_VDIRECT, GEN=, GEN=..., ATBUS=, [VALSCALE=1], VAL=

Controls one or more generators using direct voltage control (not voltage droop control). CONTROL_VDIRECT is a simpler command compared to the others.

Arguments​
  • CONTROL_VDIRECT
  • 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.
  • ATBUS (int): Bus number which has the target voltage.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to VAL (i.e. VAL x VALSCALE). Default value is 1.
  • VAL 🔢 (float): Target voltage set point [p.u.].

Basic direct voltage control

  • Control the generator at bus 100 with ID 1. The control is direct voltage control of bus 300 with a target voltage of 1.01 p.u.
CONTROL_VDIRECT, GEN=100#1, ATBUS=300, VAL=1.01

Multiple generator voltage control

  • Control two generators at bus 100 with ID 1 and bus 200 with ID 1 using direct voltage control. The control is direct voltage control of bus 300 with a target voltage of 1.03 p.u.
CONTROL_VDIRECT, GEN=100#1, GEN=200#1, ATBUS=300, VAL=1.03

CONTROL_Q Reactive power from generator(s)​

CONTROL_Q, GEN=[DEFINITION=, PRIORITY=1, RATIO=], GEN=[...], ATLINE=, [METERBUS=, VALSCALE=1], VAL=

Uses a software agonistic power plant controller to achieve a reactive power target. The target can be specified at the generator terminals, or at a remote line. Supports dispatch order and reactive power sharing (and a mixture of both).

Arguments​
  • CONTROL
  • GEN (object): Generator definition with parameters on a per-generator level within square brackets [...]:
    • DEFINITION (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • PRIORITY 🔢 (int)[Optional]:
      • Dispatch priority (order) for this generator. Defaults to 1.
      • Generators with the highest priority will be dispatched first as far as their operational limits allow, then generators in later orders are dispatched next.
    • RATIO 🔢 (float)[Optional]:
      • Sharing ratio for this generator. Defaults to generator base (in MVA).
      • Generators in the same PRIORITY will share the reactive power target based on their RATIO values.
      • The engine will normalize all share values, so it can be ratios or percentages or pu etc.
  • ATLINE Location of the target reactive power [Optional].
    • If not specified, the reactive power target is regulated at the generator terminals.
    • If ATLINE=from->to#id (pas): Reactive power target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to VAL (i.e. VAL x VALSCALE). Default value is 1.
  • VAL 🔢 (float): Reactive power setpoint [MVAr].
Examples​

Solar farm with single aggregated generator

  • Control the aggregated generator at bus 100 with ID 1 to achieve a target reactive power of 0 MVAr at the point of connection, between bus 400 and bus 500 with branch ID 1.
CONTROL_Q, GEN=[DEFINITION=100#1], ATLINE=400->500#1, VAL=0

Solar farm with multiple aggregated generators

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target reactive power of 0 MVAr at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The reactive power contibution from each generator should be shared equally.
CONTROL_Q, GEN=[DEFINITION=100#1, RATIO=0.5], GEN=[DEFINITION=200#2, RATIO=0.5], ATLINE=400->500#1, VAL=0

Solar farm with multiple aggregated generators and priority dispatch

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target reactive power of 0 MVAr at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The reactive power contibution from each generator should be shared equally.
  • Priorise supplying reactive power from the aggregated solar farm generator at bus 100 before supplying any reactive power from the aggregated BESS generator at bus 200.
CONTROL_Q, GEN=[DEFINITION=100#1, PRIORITY=1], GEN=[DEFINITION=200#2, PRIORITY=2], ATLINE=400->500#1, VAL=0

Solar farm with multiple aggregated generators and unequal power sharing

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target reactive power of 0 MVAr at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The reactive power contibution from each generator should be 70% from the aggregated solar farm generator at bus 100 and 30% from the aggregated solar farm generator at bus 200.
CONTROL_Q, GEN=[DEFINITION=100#1, RATIO=70], GEN=[DEFINITION=200#2, RATIO=30], ATLINE=400->500#1, VAL=0

Large wind farm with multiple aggregated generators, power sharing based on relative size

  • Control the four aggregated generators at buses 100, 101, 200 and 201 - all with ID 1.
  • Achieve a reactive power target of 0 MVAr at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The reactive power contibution from each generator should be shared equally based on the relative size of each generator.
CONTROL_Q, GEN=[DEFINITION=100#1], GEN=[DEFINITION=101#1], GEN=[DEFINITION=200#1], GEN=[DEFINITION=201#1], ATLINE=400->500#1, VAL=0

CONTROL_PF - Control generator(s) power factor​

CONTROL_PF, GEN=[DEFINITION=, PRIORITY=1, RATIO=], GEN=[...], ATLINE=, [METERBUS=, VALSCALE=1], VAL=

Uses a software agonistic power plant controller to achieve a power factor target. The target can be specified at the geneartor terminals, or at a remote line. Supports dispatch order and power factor control sharing (and a mixture of both).

Arguments​
  • CONTROL
  • GEN (object): Generator definition with parameters on a per-generator level within square brackets [...]:
    • DEFINITION (pas): Generator definition. Generators are defined using the following syntax: bus#id.
    • PRIORITY 🔢 (int)[Optional]:
      • Dispatch priority (order) for this generator. Defaults to 1.
      • Generators with the highest priority will be dispatched first as far as their operational limits allow, then generators in later orders are dispatched next.
    • RATIO 🔢 (float)[Optional]:
      • Sharing ratio for this generator. Defaults to generator base (in MVA).
      • Generators in the same PRIORITY will share the power factor control target based on their RATIO values.
      • The engine will normalize all share values, so it can be ratios or percentages or pu etc.
  • ATLINE Location of the target power factor [Optional].
    • If not specified, the power factor target is regulated at the generator terminals.
    • If ATLINE=from->to#id (pas): Power factor target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to VAL (i.e. VAL x VALSCALE). Default value is 1.
  • VAL 🔢 (float): Power factor setpoint. Using generator convention, positive power factor means injecting reactive power. Range is from -1.0 to 1.0.
Examples​

Solar farm with single aggregated generator

  • Control the aggregated generator at bus 100 with ID 1 to achieve a target power factor of 0.95 (injecting reactive power) at the point of connection, between bus 400 and bus 500 with branch ID 1.
CONTROL_PF, GEN=[DEFINITION=100#1], ATLINE=400->500#1, VAL=0.95

Solar farm with multiple aggregated generators

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target power factor of 1.0 (unity) at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The power factor control contribution from each generator should be shared equally.
CONTROL_PF, GEN=[DEFINITION=100#1, RATIO=0.5], GEN=[DEFINITION=200#2, RATIO=0.5], ATLINE=400->500#1, VAL=1.0

Solar farm with multiple aggregated generators and priority dispatch

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target power factor of 0.98 (injecting reactive power) at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The power factor control contribution from each generator should be shared equally.
  • Priorise supplying reactive power from the aggregated solar farm generator at bus 100 before supplying any reactive power from the aggregated BESS generator at bus 200.
CONTROL_PF, GEN=[DEFINITION=100#1, PRIORITY=1], GEN=[DEFINITION=200#2, PRIORITY=2], ATLINE=400->500#1, VAL=0.98

Solar farm with multiple aggregated generators and unequal power sharing

  • Control the two aggregated generators at bus 100 with ID 1 and bus 200 with ID 2 to achieve a target power factor of 0.95 (injecting reactive power) at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The power factor control contribution from each generator should be 70% from the aggregated solar farm generator at bus 100 and 30% from the aggregated solar farm generator at bus 200.
CONTROL_PF, GEN=[DEFINITION=100#1, RATIO=70], GEN=[DEFINITION=200#2, RATIO=30], ATLINE=400->500#1, VAL=0.95

Large wind farm with multiple aggregated generators, power sharing based on relative size

  • Control the four aggregated generators at buses 100, 101, 200 and 201 - all with ID 1.
  • Achieve a power factor target of -0.95 (absorbing reactive power) at the point of connection, between bus 400 and bus 500 with branch ID 1.
  • The power factor control contribution from each generator should be shared equally based on the relative size of each generator.
CONTROL_PF, GEN=[DEFINITION=100#1], GEN=[DEFINITION=101#1], GEN=[DEFINITION=200#1], GEN=[DEFINITION=201#1], ATLINE=400->500#1, VAL=-0.95

Control load - Fixed reactive power control​

CONTROL, LOAD=, Q=FIXED, ATLINE=, [METERBUS=, VALSCALE=1], QTARGET/YQTARGET=

Controls a load/shunt using fixed reactive power control.

Arguments:

  • CONTROL
  • LOAD (pas): Load/shunt definition. Loads and shunts are defined using the following syntax: bus#id.
  • Q (str): Reactive power control methodology. Set as FIXED.
  • Target reactive power set point. Options:
    • QTARGET= 🔢 (float): Target reactive power set point [MVAr] for constant power load; or
    • YQTARGET= 🔢 (float): Target reactive power set point [MVAr] for constant admittance load.
  • ATLINE Location of the target active power. Options:
    • ATLINE=TERMINALS: Reactive power target is regulated at the generator terminals.
    • ATLINE=from->to#id (pas): Reactive power target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to QTARGET (i.e. QTARGET x VALSCALE). Default value is 1.
note

Only one LOAD= argument is supported per Command.

Example: Control the load at bus 100 which has an ID of 1. The control mode is fixed reactive power control of -10 MVAr across the line from bus 400 to bus 500 (measured at the 'from-side') which has an ID of 1.

CONTROL, LOAD=100#1, Q=FIXED, ATLINE=400->500#1, QTARGET=-10

Control load - Power factor control​

CONTROL, LOAD=, Q=PF, ATLINE=, [METERBUS=, VALSCALE=1], PFTARGET=

Controls a load/shunt using power factor control.

Arguments:

  • CONTROL
  • LOAD (pas): Load/shunt definition. Loads and shunts are defined using the following syntax: bus#id.
  • Q (str): Reactive power control methodology. Set as PF.
  • ATLINE Location of the target power factor. Options:
    • ATLINE=TERMINALS: Power factor target is regulated at the generator terminals.
    • ATLINE=from->to#id (pas): Power factor target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to PFTARGET (i.e. PFTARGET x VALSCALE). Default value is 1.
  • PFTARGET 🔢 (float): Target power factor power set point.
note

Only one LOAD= argument is supported per Command.

Example: Control the load at bus 100 which has an ID of 1. The control is power factor control of -0.97 at the load terminals.

CONTROL, LOAD=100#1, Q=PF, ATLINE=TERMINALS, PFTARGET=-0.97

Control load - Active power control​

CONTROL, LOAD=, ATLINE=, [METERBUS=, VALSCALE=1], P/YP=

Controls the active power of a load/shunt.

Arguments:

  • CONTROL
  • LOAD (pas): Load/shunt definition. Loads and shunts are defined using the following syntax: bus#id.
  • Load setpoint. Options:
    • P 🔢 (float): Active power target [MW] for constant power load; or
    • YP 🔢 (float): Active power target [MW] for constant admittance load.
  • ATLINE Location of the target active power. Options:
    • ATLINE=TERMINALS: Active power target is regulated at the generator terminals.
    • ATLINE=from->to#id (pas): Active power target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to P (i.e. P x VALSCALE). Default value is 1.
note

Only one LOAD= argument is supported per Command.

Example: Control the load at bus 100 which has an ID of 1. The active power set point is 22 MW and is applied across load terminals.

CONTROL, LOAD=100#1, ATLINE=TERMINALS, P=22

SOLVE Command​

SOLVE, [LOCKTAPS=, LOCKSHUNTS=, IGNORE_CONTROL_IF_OFFLINE=]

Solves the static case, considering all previous SET and CONTROL Commands. CONTROL Commands are achieved by solving the static case, observing the monitored buses/lines (e.g. ATLINE=), comparing the observed value with the desired value and tolerance limits, adjusting the controlled elements (e.g. GEN=) if required and repeating this process as required.

Arguments:

  • SOLVE
  • LOCKTAPS (str)[Optional]: Solution option specifying whether the position of transformer taps may change during the solution. Defaults to NO. Options:
    • LOCKTAPS=YES: Transformer taps are locked.
    • LOCKTAPS=NO: Transformer taps are unlocked (stepped taps).
  • LOCKSHUNTS (str)[Optional]: Solution option specifying whether the position of switched shunts may change during the solution. Defaults to NO. Options:
    • LOCKSHUNTS=YES: Switched shunt positions are locked.
    • LOCKSHUNTS=NO: Switched shunt positions are unlocked (stepped shunt steps).
  • IGNORE_CONTROL_IF_OFFLINE (str)[Optional]: Defaults to NO. Options:
    • IGNORE_CONTROL_IF_OFFLINE=YES: Any CONTROL commands which have all assets offline are ignored when solving the case. This is typically only used for static load flow simulations as part of preliminary project development.
    • IGNORE_CONTROL_IF_OFFLINE=NO: All CONTROL commands are considered, even for assets that are offline.
info

All SET, SCALE_TX and CONTROL Commands preceding a SOLVE Command are applied at the same time when the SOLVE Command is used. Multiple SOLVE Commands are supported and can be used when you want to apply SET and CONTROL Commands sequentially. For example:

SET COMMAND 1
SET COMMANDS 2
CONTROL COMMAND 1
SOLVE
CONTROL COMMAND 2
SOLVE

This following two static solves will occur:

  1. Solve considering SET COMMAND 1, SET COMMAND 2 and CONTROL COMMAND 1; then
  2. Solve considering CONTROL COMMAND 2.

Example: Solve the case where transformer taps are not locked and where switched shunt positions are locked.

SOLVE, LOCKTAPS=NO, LOCKSHUNTS=YES

OUTPUT Command​

note

Only one value can be output per OUTPUT Command.

info

The Node automatically outputs .sav cases ready for use by connected PSS®E Dynamic Nodes. Therefore, you don't need to specify this output.

Output bus value​

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

Outputs a value from a bus.

Arguments:

  • OUTPUT
  • BUS (int): Bus number.
  • VAL (str): Bus value. Options:
    • VAL=V: Voltage [p.u.].
    • VAL=VKV: Voltage [kV].
    • VAL=ANGLE: Angle [degrees].
  • 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.

Example: Output the voltage [p.u] at bus 100 and name the Internode Variable 'busvolts'.

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

Output line value​

OUTPUT, LINE=, VAL=, [RATING_NAME=, METERBUS=, VALSCALE=1], NAME=

Outputs a value from a line.

Arguments:

  • OUTPUT
  • LINE (pas): Line definition. Lines are defined using the following syntax: from->to#id. Values are output at the 'from-side' of the line.
  • VAL (str): Line value. Options:
    • VAL=P: Active power [MW].
    • VAL=Q: Reactive power [MVAr].
    • VAL=S: Apparent power [MVA].
    • VAL=PF: Power factor (generator convention, P/S) [unitless]. Click here for details on how gridmo calculates power factor.
    • VAL=LOAD%: Thermal loading using the 'RATE1' field [%].
    • VAL=RATING: Line rating [MVA]. Requires RATING_NAME= to be specified.
  • RATING_NAME (str)[Optional]: Name of the rating to be output (e.g. "RATE1"). Only required if VAL=RATING.
  • 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.
  • 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.

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

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

Output transformer value​

OUTPUT, TX=, VAL=, [RATING_NAME=, WINDING=, METERBUS=, VALSCALE=1], NAME=

Outputs a value 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).
  • VAL (str): Transformer value. Options:
    • VAL=P: Active power [MW].
    • VAL=Q: Reactive power [MVAr].
    • VAL=S: Apparent power [MVA].
    • VAL=PF: Power factor (generator convention, P/S) [unitless]. Click here for details on how gridmo calculates power factor.
    • VAL=TAPRATIO: Tap ratio of the winding with the highest base voltage - as this is most likely where the tap changer is present (decimal, such as 0.90 meaning 90% of default tap) [unitless].
    • VAL=LOAD%: Thermal loading using the 'RATE1' field [%].
    • VAL=RATING: Transformer rating [MVA]. Requires RATING_NAME= to be specified. Requires WINDING= to be specified for three-winding transformers.
  • RATING_NAME (str)[Optional]: Name of the rating to be output (e.g. "RATE1"). Only required if VAL=RATING.
  • WINDING (int)[Optional]: Winding number for outputting transformer rating. Only required if VAL=RATING and the transformer has three-windings.
  • 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. Not supported for three-winding transformers.
  • 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.
danger

The OUTPUT, TX= Command has limited support for three-winding transformers. Specifically, measuring power flow through a three-winding transformer is not recommended as it is ambiguous where the metering is occurring.

Using METERBUS= is not supported for three-winding transformers as it is unclear what direction to assign to 'positive' power flow - for more information see Error 114.

If you need to monitor a three-winding transformer, please consider instead using a 'dummy' line (a line with zero impedance) and monitoring that line.

Example: Output the apparent power flowing through the transformer located between bus 100 to bus 200 which has an ID of 2. Name the Internode Variable i_tx_sload.

OUTPUT, TX=100->200#2, VAL=S, NAME=i_tx_sload

Output generator value​

OUTPUT, GEN=, VAL=, [VALSCALE=1], NAME=

Outputs a value from a generator.

Arguments:

  • OUTPUT
  • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
  • VAL (str): Generator value. Options:
  • 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.

Example: Output the reactive power flowing through the generator located at bus 100 which has an ID of 1. Name the Internode Variable 'generator-Q'.

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

Output load value​

OUTPUT, LOAD=, VAL=, [VALSCALE=1], NAME=

Outputs a value from a load.

Arguments:

  • OUTPUT
  • LOAD (pas): Load/shunt definition. Loads and shunts are defined using the following syntax: bus#id.
  • VAL (str): Load value. Options:
  • 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.
note

The following sign convention is used in the outputs:

  • Positive P: Load is consuming active power.
  • Negative P: Load is generating active power (e.g. a generator is modelled as a 'negative load').
  • Positive Q: Load is consuming reactive power (e.g. a reactive load).
  • Negative Q: Load is generating reactive power (e.g. a capacitive load).
  • Positive power factor: A load which is consuming reactive power (e.g. a reactive load).
  • Negative power factor: A load which is generating reactive power (e.g. a capacitive load).

Example: Output the active power flowing into a load located at bus 100 which has an ID of 1. Name the Internode Variable 'p_load'.

OUTPUT, LOAD=100#1, VAL=P, NAME=p_load

Output voltage droop target value​

OUTPUT, VAL=VDROOPTARGET, QBASE=, DROOP%=, DEADBAND=, QMIN=, QMAX=, ATBUS=, ATLINE=, [METERBUS=, VALSCALE=1], NAME=

Outputs the expected target voltage set point [p.u.] for a pre-defined voltage droop characteristic.

Arguments:

  • OUTPUT
  • VAL (str): Voltage droop characteristic value. Options:
    • VAL=VDROOPTARGET: Target voltage set point [p.u.].
  • QBASE 🔢 (float): Base reactive power [MVAr].
  • DROOP% 🔢 (float): Droop percentage [%].
  • DEADBAND 🔢 (float): Voltage deadband [p.u.].
  • QMIN 🔢 (float): Minimum reactive power limit at the ATLINE= line [MVAr].
  • QMAX 🔢 (float): Maximum reactive power limit at the ATLINE= line [MVAr].
  • ATBUS (int): Bus number which has the target voltage.
  • ATLINE (pas): Line which is used for measuring the reactive power. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • 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.

Example: Output the voltage droop target given the measured voltage at bus 500, the reactive power flow from bus 400 to 500 (id 1) metered at the bus 500 end, using 80 MVAr as the reactive power base, QMAX of 60 MVAr, QMIN of -60 MVAr and with a droop of 6%. Name the Internode Variable i_poc_vdroop_target.

OUTPUT, VAL=VDROOPTARGET, QBASE=80, DROOP%=6, DEADBAND=0, QMIN=-60, QMAX=60, ATBUS=500, ATLINE=400->500#1, METERBUS=500,  NAME=i_poc_vdroop_target

Advanced Parameters​

node.convergence.gain​

  • Description: Defines the proportional gain used by the convergence algorithm. Large generators connected to weak networks with low droop percentages may require a gain lower than default to converge.
  • Type: float
  • Units: N/A
  • Default: 0.2
  • Range: 0.001 - 0.5
node.convergence.gain=value

node.convergence.mva​

  • Description: Defines the acceptable tolerance error in the convergence algorithm. A load/generator is deemed converged when the absolute value of the difference (between actual and target values) is less than this value.
  • Type: float
  • Units: MW or MVAr
  • Default: 0.001
  • Range: 0.001 - 5
node.convergence.mva=value

node.convergence.converge_at_limit​

  • Description: Defines if a generator in a CONTROL Command, which cannot achieve the control target due to hitting its minimum or maximum reactive power limit (as per the PSS®E Case file), is considered converged. For example, a generator is asked to regulate to 22 MVAr, but it can only inject 20 MVAr. If this Advanced Parameter is set to Yes, the generator is treated as converged. If this Advanced Parameter is set to No the generator will prevent the static study solution from converging. Regardless of the setting, an Engine warning is raised if a generator reaches its minimum or maximum reactive power capability.
  • Type: bool
  • Units: N/A
  • Default: Yes
  • Range: Yes, No
node.convergence.converge_at_limit=value

system.convergence.mva​

  • Description: Defines the acceptable whole-network MVA mismatch. A network is deemed converged and stable when the mismatch is less than this value.
  • Type: float
  • Units: MVA
  • Default: 0.5
  • Range: >=0.1
system.convergence.mva=value

max_iter​

  • Description: Defines the acceptable number of iterations during Case file and generator/load control mode convergence. Very sensitive control modes (low droop % values) or weak networks may require higher than default max_iter to converge.
  • Type: int
  • Units: N/A
  • Default: 500
  • Range: 50 - 10000
max_iter=value

voltages.tolerance​

  • Description: Defines the acceptable voltage tolerance for the static study. Voltage regulation schemes are considered on target when the actual voltage is within this value (+/- the voltage tolerance).
  • Type: float
  • Units: p.u.
  • Default: 1e-5
  • Range: 0 - 1
voltages.tolerance=value

stop.on.extreme.voltages​

  • Description: If YES, the Engine will stop the static study from converging if any bus voltage is lower or higher than 0.05 p.u. below the bounds as calculated below:
    • Lower bound is the lower of 0.85 p.u. and the lowest bus voltage in the input case file.
    • Upper bound is the upper of 1.15 p.u. and the highest bus voltage in the input case file.

For example, if the highest bus voltage in the input case file is 1.17 p.u. and this Advanced Parameter is set to YES, the Engine will stop the static study from converging if any bus voltage is higher than 1.17 + 0.05 = 1.22 p.u.

  • Type: bool
  • Units: N/A
  • Default: Yes
  • Range: Yes, No
stop.on.extreme.voltages=value

voltages.lower​

danger

voltages.higher is deprecated in v1.4.21.1 and will be removed in a future release. Please use stop.on.extreme.voltages=no to stop the gridmo Engine from converging if any bus voltage is too low.

  • Description: Defines the acceptable lower voltage bound for the static study. Any buses with voltage lower than this value will prevent the case from converging. A network is deemed converged and stable when all in-service buses have per unit voltage higher than this value.
  • Type: float
  • Units: p.u.
  • Default: 0.85
  • Range: 0 - 0.99
voltages.lower=value

voltages.higher​

danger

voltages.higher is deprecated in v1.4.21.1 and will be removed in a future release. Please use stop.on.extreme.voltages=no to stop the gridmo Engine from converging if any bus voltage is too high.

  • Description: Defines the acceptable upper voltage bound for the static study. Any buses with voltage higher than this value will prevent the case from converging. A network is deemed converged and stable when all in-service buses have per unit voltage lower than this value.
  • Type: float
  • Units: p.u.
  • Default: 1.15
  • Range: 1.01 - 2
voltages.higher=value

system.swingbus.ignorevolt​

  • Description: Should the swing bus (type 3 bus in PSS®E model) be excluded from the voltage tolerance checks? This value defaults to Yes which is typically appropriate for SMIB studies. For full system model studies, setting this value to No is recommended, but not mandatory.
  • Type: bool
  • Units: N/A
  • Default: Yes
  • Range: Yes / No
system.swingbus.ignorevolt=value

low.scr.mode​

note

To use low SCR mode, the PSS®E Static Node must have:

  • Exactly one SOLVE command.
  • Exactly one SET, LINE=, SCR=, XR= command.
  • A VDIRECT command for the Thévenin equivalent source regulating the connection point voltage.

By setting low.scr.mode=Yes, the gridmo Engine will convert your SOLVE into a multi-step solve to converged your SMIB model to very low SCR values.

Specifically, the first series of iterations solves the case at a relatively high SCR (of 25). The second solve is a two-stage iterative process, quadratically ramping the Thévenin equivalent impedance until the target SCR is reached. The point of connection voltage is then adjusted to ensure the target voltage is maintained. The final solve is a single iteration to ensure the case remains in a converged state.

  • Description: Enables a low SCR mode where impedance changes (via SET, LINE=, SCR=, XR=) are slowly ramped during a SOLVE command.
  • Type: bool
  • Units: N/A
  • Default: No
  • Range: Yes / No
low.scr.mode=value

legacy.invalid.number.support​

If set to Yes, sets additional PSS®E settings to reduce PSS®E crashes if PSS®E encounters an invalid number (e.g. NaN value). However, we're aware that this can cause some user-defined models to crash if they don't also support these invalid numbers.

tip

Prior to gridmo Engine v1.7.0, this was enabled by default, but is now disabled by default.

  • Type: bool
  • Units: N/A
  • Default: No
  • Range: Yes / No
legacy.invalid.number.support=value

Deprecated Commands​

danger

The following commands are no longer recommended for new Projects as they have been replaced with new commands with expanded functionality.

These older commands will continue to be supported and you do not need to update any of your existing gridmo Projects to use these new commands, unless you need to use the new functionality.

Control generator - Direct voltage control​

CONTROL, GEN=, Q=VDIRECT, ATBUS=, [QMIN=, QMAX=, VALSCALE=1, VTARGET=]

Controls one generator using direct voltage control (not droop control).

Arguments:

  • CONTROL
  • GEN (pas): Generator definition. Generators are defined using the following syntax: bus#id.
  • Q (str): Reactive power control methodology. Set as VDIRECT.
  • ATBUS (int): Bus number which has the target voltage.
  • QMIN (float)[Optional]: Minimum reactive power capability of the generator [MVAr]. Default value is as per the generator's configuration in the PSS®E case file.
  • QMAX (float)[Optional]: Maximum reactive power capability of the generator [MVAr]. Default value is as per the generator's configuration in the PSS®E case file.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to VTARGET (i.e. VTARGET x VALSCALE). Default value is 1.
  • VTARGET 🔢 (float)[Optional]: Target voltage set point [p.u.]. Default value is the voltage specified in the Schedu Voltage field (within Plant Data) for the specified generator.

Example: Control the generator at bus 100 which has an ID of 1. The control is direct voltage control of bus 300 with a target voltage of 1.01 [p.u.]. The generator can supply reactive power between -10 MVAr and +15 MVAr.

CONTROL, GEN=100#1, Q=VDIRECT, QMIN=-10, QMAX=15, ATBUS=300, VTARGET=1.01

Example: Control the generator at bus 1257 which has an ID of 1. The control is direct voltage control of bus 1000 with a target voltage of 1.02 [p.u.]. Do not change the reactive power limits of the generator from its current definition as per the case file.

CONTROL, GEN=1257#1, Q=VDIRECT, ATBUS=1000, VTARGET=1.02

Control generator - Droop voltage control​

CONTROL, GEN=, [GEN=], Q=VDROOP, QBASE=, DROOP%=, DEADBAND=, [QMIN=, QMAX=], ATBUS=, ATLINE=, [METERBUS =, VALSCALE=1], VTARGET=, [CONSIDER_EXISTING_DISPATCH=YES]

Controls one or more generators using voltage droop control. If the measured voltage is larger/smaller than the voltage target + deadband, the specified generators will be controlled to absorb/supply reactive power equal to the droop percentage of QBASE for every 1% the measured voltage is above the voltage target + deadband.

voltage droop characteristic with a deadband and fixed maximum and minimum reactive power limits

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.
  • Q (str): Reactive power control methodology. Set as VDROOP.
  • QBASE (float): Base reactive power [MVAr].
  • DROOP% (float): Droop percentage [%].
  • DEADBAND (float): Voltage deadband [p.u.].
  • QMIN (int)[Optional]: Minimum reactive power limit at the ATLINE= line [MVAr]. Default value is -∞.
  • QMAX (int)[Optional]: Maximum reactive power limit at the ATLINE= line [MVAr]. Default value is ∞.
  • ATBUS (int): Bus number which has the target voltage.
  • ATLINE (pas): Line which is used for measuring the reactive power. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to VTARGET (i.e. VTARGET x VALSCALE). Default value is 1.
  • VTARGET 🔢 (float): Target voltage set point [p.u.]. Default value is the voltage specified in the Schedu Voltage field (within Plant Data) for the specified generator.
  • CONSIDER_EXISTING_DISPATCH (bool)[Optional]: Defaults to YES. Options:
    • CONSIDER_EXISTING_DISPATCH=YES: The static controller logic considers the existing reactive power dispatch values in the case file (i.e. Qgen) for the controlled generators. If the existing dispatch values are not distributed equally amongst the controlled generators according to their machine MVA ratings, they will likely remain unequal.
    • CONSIDER_EXISTING_DISPATCH=NO: The existing dispatch values are ignored and dispatch values are forced to be distributed equally amongst the controlled generators according to their machine MVA ratings.

Example: A PPC exists between bus 600 and bus 700 (ID=1) and is controlling a generator at bus 100 which has an ID of 1. The PPC is acting in voltage droop control with a target voltage of 1.01 [p.u.] at bus 600, a QBASE of 50 MVAr, a droop percentage of 4% and a voltage deadband of 0.01 [p.u.].

CONTROL, GEN=100#1, Q=VDROOP, QBASE=50, DROOP%=4, DEADBAND=0.01, ATBUS=600, ATLINE=600->700#1, VTARGET=1.01

Example: A PPC exists between bus 600 and bus 700 (ID=1) and is controlling two generators at bus 100 which has an ID of 1 and at bus 200 which has an ID of 1. The PPC is controlling two generators with equal machine base (which represent two aggregated collector groups of a wind farm). The PPC is acting in voltage droop control with a target voltage of 1.01 [p.u.] at bus 600, a QBASE of 50 MVAr, a droop percentage of 4% and a voltage deadband of 0.01 [p.u.]. The static controller logic should not consider the existing dispatch files in the case file and should ensure that the reactive power dispatch is shared equally across the two generators.

CONTROL, GEN=100#1, GEN=200#1, Q=VDROOP, QBASE=50, DROOP%=4, DEADBAND=0.01, ATBUS=600, ATLINE=600->700#1, VTARGET=1.01, CONSIDER_EXISTING_DISPATCH=NO

Control generator - Fixed reactive power control​

CONTROL, GEN=, [GEN=], Q=FIXED, ATLINE=, [METERBUS=, VALSCALE=1], QTARGET=, [CONSIDER_EXISTING_DISPATCH=YES]

Controls one or more generators using fixed reactive power control. The reactive power target will be applied across the specified line.

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.
  • Q (str): Reactive power control methodology. Set as FIXED.
  • ATLINE: Location of the target reactive power. Options:
    • ATLINE=TERMINALS: Reactive power target is regulated at the generator terminals.
    • ATLINE=from->to#id (pas): Reactive power target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to QTARGET (i.e. QTARGET x VALSCALE). Default value is 1.
  • QTARGET (float): Target reactive power set point [MVAr].
  • CONSIDER_EXISTING_DISPATCH (bool)[Optional]: Defaults to YES. Options:
    • CONSIDER_EXISTING_DISPATCH=YES: The static controller logic considers the existing reactive power dispatch values in the case file (i.e. Qgen) for the controlled generators. If the existing dispatch values are not distributed equally amongst the controlled generators according to their machine MVA ratings, they will likely remain unequal.
    • CONSIDER_EXISTING_DISPATCH=NO: The existing dispatch values are ignored and dispatch values are forced to be distributed equally amongst the controlled generators according to their machine MVA ratings.

Example: Control the generator at bus 100 which has an ID of 1. The control mode is fixed reactive power control regulating -20 MVAr across the line from bus 400 to bus 500 (measured at the 'to-side') which has an ID of 1.

CONTROL, GEN=100#1, Q=FIXED, ATLINE=400->500#1, METERBUS=500, QTARGET=-20

Example: Control two generators. The first generator has a machine base of 100MVA and is at bus 1500 with ID of 1. The second generator has a machine base of 100MVA and is at bus 1505 with ID of 2. The control mode is fixed reactive power control regulating -20 MVAr across the line from bus 400 to bus 500 (measured at the 'to-side') which has an ID of 1. The static controller logic should not consider the existing dispatch files in the case file and should ensure that the reactive power dispatch is shared equally across the two generators.

CONTROL, GEN=1500#1, GEN=#1505#2, Q=FIXED, ATLINE=400->500#1, METERBUS=500, QTARGET=-20, CONSIDER_EXISTING_DISPATCH=NO

Example: Control two generators to achieve 15 MVAr each at their respective terminals. The two generators have ID of 1 and are located on bus 123 and 456 respectively. The generators must be the same size (machine base). CONSIDER_EXISTING_DISPATCH= cannot be used with multiple ATLINE=TERMINALS arguments.

CONTROL, GEN=123#1, GEN=456#1, Q=FIXED, ATLINE=TERMINALS, QTARGET=15

Control generator - Power factor control​

CONTROL, GEN=, [GEN=], Q=PF, ATLINE=, [METERBUS=, VALSCALE=1], PFTARGET=, [CONSIDER_EXISTING_DISPATCH=YES]

Controls one or more generators using power factor power control.

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.
  • Q (str): Reactive power control methodology. Set as PF.
  • ATLINE: Location of the target power factor. Options:
    • ATLINE=TERMINALS: Power factor target is regulated at the generator terminals.
    • ATLINE=from->to#id (pas): Power factor target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to PFTARGET (i.e. PFTARGET x VALSCALE). Default value is 1.
  • PFTARGET (float): Target power factor set point.
  • CONSIDER_EXISTING_DISPATCH (bool)[Optional]: Defaults to YES. Options:
    • CONSIDER_EXISTING_DISPATCH=YES: The static controller logic considers the existing reactive power dispatch values in the case file (i.e. Qgen) for the controlled generators. If the existing dispatch values are not distributed equally amongst the controlled generators according to their machine MVA ratings, they will likely remain unequal.
    • CONSIDER_EXISTING_DISPATCH=NO: The existing dispatch values are ignored and dispatch values are forced to be distributed equally amongst the controlled generators according to their machine MVA ratings.

Example: Control the generator at bus 100 which has an ID of 1. The control is power factor control of -0.97 at the generator terminals.

CONTROL, GEN=100#1, Q=PF, ATLINE=TERMINALS, PFTARGET=-0.97

Example: Control two generators to achieve 0.95 injecting power factor each at their respective terminals. The two generators have ID of 1 and are located on bus 123 and 456 respectively. The generators must be the same size (machine base). CONSIDER_EXISTING_DISPATCH= cannot be used with multiple ATLINE=TERMINALS arguments.

CONTROL, GEN=123#1, GEN=456#1, Q=PF, ATLINE=TERMINALS, PFTARGET=0.95

Control generator - Active power control​

CONTROL, GEN=, [GEN=], ATLINE=, [METERBUS=, VALSCALE=1], P=, [CONSIDER_EXISTING_DISPATCH=YES]

Controls the active power of one or more generators.

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.
  • ATLINE Location of the target active power. Options:
    • ATLINE=TERMINALS: Active power target is regulated at the generator terminals.
    • ATLINE=from->to#id (pas): Active power target is regulated across the specified line. Lines are defined using the following syntax: from->to#id.
  • METERBUS (int)[Optional]: Bus number which is the metering point for the ATLINE= line. Default value is the 'from' bus number as per the ATLINE= argument.
  • VALSCALE 🔢 (float)[Optional]: Multiplicative scaling factor applied to P (i.e. P x VALSCALE). Default value is 1.
  • P (float): Active power target [MW].
  • CONSIDER_EXISTING_DISPATCH (bool)[Optional]: Defaults to YES. Options:
    • CONSIDER_EXISTING_DISPATCH=YES: The static controller logic considers the existing active power dispatch values in the case file (i.e. Pgen) for the controlled generators. If the existing dispatch values are not distributed equally amongst the controlled generators according to their machine MVA ratings, they will likely remain unequal.
    • CONSIDER_EXISTING_DISPATCH=NO: The existing dispatch values are ignored and dispatch values are forced to be distributed equally amongst the controlled generators according to their machine MVA ratings.

Example: A PPC has a target active power set point and is controlling two generators at bus 100 (ID=1) and bus 200 (ID=1). The active power set point is 95 MW and is applied across the line from bus 400 to bus 500 (measured at the 'from-side') which has an ID of 1.

CONTROL, GEN=100#1, GEN=200#1, ATLINE=400->500#1, P=95

Example: Control two generators to achieve 59 MW each at their respective terminals. The two generators have ID of 1 and are located on bus 123 and 456 respectively. The generators must be the same size (machine base). CONSIDER_EXISTING_DISPATCH= cannot be used with multiple ATLINE=TERMINALS arguments.

CONTROL, GEN=123#1, GEN=456#1, ATLINE=TERMINALS, P=59