1. Quickstart Testcases Workbook Guide

1. Quickstart Testcases Workbook Guide

1.1 Overview

The testcases.xlsx workbook is the model-independent MTB interface used to enter plant settings and define simulation cases. The workbook contains predefined case sets used by Energinet for RfG, DCC, and unit test studies, and it also supports custom cases.

The workbook contains these sheets:

Sheet	Purpose
Settings	Model-specific plant data, grid data, default control settings, simulation timing, and execution options.
Area values	Requirement values derived from plant-specific settings such as area and connection point.
RfG cases	Predefined generation cases.
DCC cases	Predefined demand cases.
Unit cases	Unit test cases.
Co-located cases	Predefined co-located generation/demand cases.
Custom cases	User-defined custom cases.
Event types	Describes supported event types and howX1 and X2 are interpreted.
RfG cases overview	Overview of predefined RfG cases.
DCC cases overview	Overview of predefined DCC cases.
Unit cases overview	Overview of predefined unit cases.
Co-located cases overview	Overview of predefined co-located cases (Not yet fully configured in MTB 2.0).
Custom cases overview	Overview of custom cases.
datavalidation	Workbook helper sheet used for data validation lists.

The Settings sheet and case sheets are read directly by case_setup.py.

1.2 Settings Sheet

The Settings sheet contains model-specific data used by both PowerFactory and PSCAD execution.

Caution

Projectname should not contain spaces. The MTB replaces spaces with underscores internally, but avoiding spaces in the workbook keeps result folder and file names predictable.

1.2.1 General plant settings

case_setup.py reads the following general settings:

Setting	Used for
Casegroup	Selects which case sheet is used, for exampleRfG, DCC, Unit, or Co-located.
Run custom cases	Includes rows from theCustom cases sheet when enabled.
Projectname	Project/result file name prefix. Spaces are converted to underscores in code.
Pn	Nominal active power in MW.
Number of Units	Number of plant units represented in the model.
Default P available	Default available active power used byPavail0 = Default.
Uc	Connection-point voltage used in impedance calculations.
Un	Nominal voltage. Also used to determine whether DSO-specific guide logic applies.
Area	Danish area, normallyDK1 or DK2.
FSM deadband	Default FSM deadband in Hz, used by guide curves and cursor metrics.
FSM droop	Default FSM droop in percent, used by guide curves and cursor metrics.
Default Q(U) droop	Default Q(U) droop used byQUdroop0 = Default.
Main Transformer Grounded	Default main transformer grounding state used byMtrfrGnd0 = Default.
R0, X0	Zero-sequence grid impedance values.
Default Q mode	Default reactive power control mode used when a case hasQmode = Default.
Unit A type	Type label for co-located Unit A.
Unit B type	Type label for co-located Unit B.
Unit C type	Type label for co-located Unit C.
Unit D type	Type label for co-located Unit D.

1.2.2 Grid strength settings

There are three SCR and X/R levels:

Setting	Meaning
SCR min, X/R SCR min	Minimum short-circuit level.
SCR tuning, X/R SCR tuning	Intermediate short-circuit level used for tuning cases.
SCR max, X/R SCR max	Maximum short-circuit level.

In case rows, SCR0 and XR0 select the initial short-circuit level and X/R ratio. A negative SCR value is used as a stiff-grid indicator in the predefined cases.

1.2.3 Timing and PowerFactory settings

Setting	Used for
PSCAD Timestep	PSCAD simulation time step.
PSCAD Initialization time	PSCAD initialization period before case time 0.
PF flat time	PowerFactory flat-run period before case time 0.
PF variable step	PowerFactory variable-step configuration.
PF enforced sync.	PowerFactory synchronization setting.
PF force asymmetrical sim.	Forces asymmetrical PowerFactory simulation where required.
PF enforce P limits in LDF	Enforces active power limits in PowerFactory load flow.
PF enforce Q limits in LDF	Enforces reactive power limits in PowerFactory load flow.

PSCAD Initialization time and PF flat time offset the simulation time before the first event. In the plotter, these offsets are removed so the first event appears at time 0.

1.2.4 Co-located settings

When Casegroup = Co-located, case_setup.py also reads co-located unit settings:

Setting	Used for
PnG3	Aggregated generation nominal power.
PnD3	Aggregated demand nominal power.
Pn Unit A (Generation)	Generation nominal power for Unit A.
Default P available or SoC Unit A	Default available power or state of charge for Unit A.
Pn Unit A (Consumption)	Consumption nominal power for Unit A.
Pn Unit B (Generation)	Generation nominal power for Unit B.
Default P available or SoC Unit B	Default available power or state of charge for Unit B.
Pn Unit B (Consumption)	Consumption nominal power for Unit B.
Pn Unit C (Generation)	Generation nominal power for Unit C.
Default P available or SoC Unit C	Default available power or state of charge for Unit C.
Pn Unit C (Consumption)	Consumption nominal power for Unit C.
Pn Unit D (Generation)	Generation nominal power for Unit D.
Default P available or SoC Unit D	Default available power or state of charge for Unit D.
Pn Unit D (Consumption)	Consumption nominal power for Unit D.

Note

Co-located case handling is present in the workbook parser, but some aggregation logic is still pending in the current implementation.

1.3 Case Sheets

The workbook contains predefined case sheets and a custom case sheet:

Each predefined case set also has an overview sheet:

Each case sheet has the same general structure:

1.3.1 Case basic information

Each row represents one case.

Column	Used for
Rank	Unique case rank number.
RMS	Whether the case is run in PowerFactory.
EMT	Whether the case is run in PSCAD.
Name	Case name used in generated study cases, result files, and plot titles.

1.3.2 Case initial settings

For normal RfG, DCC, and Unit cases, case_setup.py reads these initial settings:

Column	Used for
U0	Initial voltage in pu.
P0	Initial active power reference in pu.
Pavail0	Initial available active power in pu, orDefault to use Default P available.
Pmode	Initial active power control mode.
Qmode	Initial reactive power control mode, orDefault to use Default Q mode.
Qref0	Initial reactive power, voltage, or power factor reference, depending onQmode.
QUdroop0	Initial Q(U) droop in percent, orDefault to use Default Q(U) droop.
SCR0	Initial SCR.
XR0	Initial X/R ratio.
MtrfrGnd0	Initial main transformer grounding state:Default, Grounded, or ungrounded/not grounded.
Simulationtime	Case simulation time excluding initialization/flat time. If blank or 0 for recording cases, it can be derived from recording length.

For co-located cases, the parser reads per-unit values instead of the normal P0 and Pavail0 fields:

Column group	Used for
P0_unitA to P0_unitD	Initial active power per unit.
Pavail0_unitA to Pavail0_unitD	Initial available power or state of charge per unit.

1.3.3 Pmode and Qmode values

The accepted Pmode values are defined by PMODES in case_setup.py:

Pmode	MTB value
No P(f)	0
LFSM	1
FSM	2
LFSM+FSM	3
Pmode4	4
Pmode5	5
Pmode6	6
Pmode7	7

The accepted Qmode values are defined by QMODES:

Qmode	MTB value
Q	0
Q(U)	1
PF	2
Qmode3	3
Qmode4	4
Qmode5	5
Qmode6	6

Qref0 and Qref event values are interpreted according to the active Q mode:

Qmode	Meaning ofQref
Q	Reactive power reference in pu at PoC.
Q(U)	Voltage reference in pu at PoC.
PF	Power factor reference at PoC.
Qmode3 to Qmode6	Custom Q-mode reference.

1.3.4 Case events

Each case can define a sequence of events. In the current workbook, most sheets include Event 1 through Event 12, while RfG cases and Co-located cases include Event 1 through Event 13. Every event has four fields:

Field	Used for
type	Event type.
time	Event time relative to the end of PSCAD initialization time or PF flat time.
X1	First event argument. Meaning depends ontype.
X2	Second event argument. Meaning depends ontype.

The current parser supports these event types:

Event type	X1	X2
Pref	New active power reference in pu based onPn.	Gradient in 1/s.
Pavail	New available active power limit in pu based onPn.	Gradient in 1/s.
Qref	New Q, Q(U), PF, or custom Q-mode reference.	Gradient in 1/s.
QUdroop	New Q(U) droop in percent.	Ignored; set to 0 in code.
Voltage	New Thevenin grid voltage in pu based onUn.	Gradient in 1/s.
dVoltage	Delta change in Thevenin grid voltage in pu based onUn.	Gradient in 1/s.
Phase	New Thevenin grid voltage phase in degrees.	Gradient in 1/s.
Frequency	New Thevenin grid frequency in Hz.	Gradient in 1/s.
SCR	New short-circuit ratio.	New X/R ratio.
3p fault	Three phase fault; residual voltage (across fault reactance), base Un.	Fault time in seconds.
2p-g fault	Two phase to ground fault; residual voltage (across fault reactance), base Un.	Fault time in seconds.
2p fault	Two phase fault; residual voltage (across fault reactance), base Un.	Fault time in seconds.
1p fault	One phase fault; residual voltage (across fault reactance), base Un.	Fault time in seconds.
3p fault (ohm), 2p-g fault (ohm), 2p fault (ohm), 1p fault (ohm)	fault resistance.	fault reactance / fault time as configured by the fault implementation.
Clear fault	Clear any fault.	Ignored.
Pref recording	Relative path to measurement file used forPref.	Scaling factor.
Qref recording	Relative path to measurement file used forQref.	Scaling factor.
Voltage recording	Relative path to measurement file used for Thevenin grid voltage.	Scaling factor.
Inst. Voltage recording	Relative path to instantaneous three-phase voltage recording.	Scaling factor.
Phase recording	Relative path to measurement file used for Thevenin grid voltage phase.	Scaling factor.
Frequency recording	Relative path to measurement file used for Thevenin grid frequency.	Scaling factor.
SIPS Generation	SIPS generation integer command.	Ignored; set to 0 in code.
SIPS Demand	SIPS demand integer command.	Ignored; set to 0 in code.
Signal 1 to Signal 10	New custom signal value.	Gradient in 1/s.
Signal 1 recording to Signal 10 recording	Relative path to measurement file used for the custom signal.	Scaling factor.
PF disconnect all ref.	Ignored.	Ignored.
PF force asymmetrical	Ignored.	Ignored.

The custom event names in the workbook are written explicitly as Signal 1, Signal 2, Signal 3, Signal 4, Signal 5, Signal 6, Signal 7, Signal 8, Signal 9, and Signal 10, with equivalent recording event names Signal 1 recording, Signal 2 recording, Signal 3 recording, Signal 4 recording, Signal 5 recording, Signal 6 recording, Signal 7 recording, Signal 8 recording, Signal 9 recording, and Signal 10 recording.

The Event types sheet in the workbook contains the user-facing event descriptions:

1.4 Example Case Setup

Case rank 86 is used here as an example. This case simulates a three-phase fault and a change in SCR when the fault is cleared, representing for example a faulty line being disconnected.

In this example:

• The case is conditionally active depending on whether the plant is a DSO connection.
• The case is run for both RMS and EMT.
• The case name is ION_RfG_Fault_3_SCR.
• U0 is based on Uc from the Settings sheet.
• P0 initializes the active power reference at 1.0 pu.
• Pmode initializes LFSM as the active power control mode.
• Qmode is set to the default control mode from the Settings sheet.
• Qref0 is set to 0.
• SCR0 and XR0 use the tuning values from the Settings sheet.
• Simulationtime is 15 seconds, excluding the PF flat time or PSCAD initialization time.

The case consists of two events:

1. Event 1 is a 3p fault at time 0. X1 = 0.05 gives a 5% residual voltage at PoC, and X2 = 0.150 gives a 150 ms fault duration.
2. Event 2 is an SCR change at time 0.149. X1 is the new SCR value and X2 is the new X/R ratio.

The simulation then continues until the configured simulation time has elapsed.