4. Quickstart Plotter Guide

4. Quickstart Plotter Guide

4.1 System Requirements

The MTB plotter is located in the plotter folder and is run with Python. The plotter has its own dependency file, plotter/requirements.txt.

Install the plotter dependencies from the plotter folder:

cd plotter
python -m pip install -r requirements.txt

The plotter has been developed and tested with recent Python versions. PSCAD .psout support requires the mhi.psout package, and static image export requires Plotly/Kaleido.

4.2 Preparation

The MTB plotter creates comparative plots from RMS and EMT simulation results. It can generate HTML reports, image files, analytical guide curves for selected cases, and cursor metric tables.

The most important plotter files are:

File	Purpose
plotter.py	Main plotter script
config.ini	Plotter configuration and simulation result paths
figureSetup.csv	Defines which figures and signals should be plotted
cursorSetup.csv	Defines cursor metrics and cursor time intervals

Before running the plotter, configure at least config.ini. Optionally edit figureSetup.csv and cursorSetup.csv.

4.3 Configuration of config.ini

The plotter configuration file controls output folders, output formats, guide curves, cursor tables, multiprocessing, the testcase spreadsheet, and the result folders to scan.

Example configuration:

The current [config] parameters are:

Parameter	Type	Default	Description
resultsDir	string	results	Folder where generated.html, image, and cursor output files are stored. The folder is created if it does not exist.
genHTML	boolean	True	Generate HTML report files.
genImage	boolean	True	Generate static image files.
genGuide	boolean	False	Generate analytical guide curves for selected cases. See5. Generation of Guide Curves.
genCursorHTML	boolean	True	Include cursor metric tables in the HTML output. See6. Cursor Metrics.
genCursorPDF	boolean	False	Generate separate PDF files containing cursor metric tables.
imageFormat	string	png	Static image format, for examplepng, jpg, or svg, depending on Plotly/Kaleido support.
htmlColumns	integer	2	Number of columns used for HTML figure layout. Must be greater than 0 whengenHTML = True.
imageColumns	integer	3	Number of columns used for static image layout. Must be greater than 0 whengenImage = True.
htmlCursorColumns	integer	2	Number of columns used for cursor tables in HTML output.
processes	integer	8	Number of concurrent Python processes used to generate result files. Must be greater than 0. Use1 for sequential execution and easier debugging.
testcaseSheet	string	..\testcases.xlsx	Path to thetestcases.xlsx file used to generate the simulation results. This is mandatory for MTB 2.x.

Note

If htmlColumns > 3, the HTML output is created as a subplot with a common legend instead of separate figures with individual legends.

Important

From MTB 2.0, testcaseSheet must point to the same testcases.xlsx file that was used to generate the PowerFactory and PSCAD simulation results. The plotter uses it for case names, guide curves, and cursor-related context.

The [Simulation data paths] section defines the RMS and EMT result folders that should be plotted:

[Simulation data paths]
EMT = ..\export\MTB_10122025135456
RMS = ..\export\MTB_23122025140547

Each entry is read as:

Left side	Right side
Legend/group name shown in the plot output	Path to a folder containing result files

Tip

Add more lines under [Simulation data paths] to compare multiple model versions, for example RMS_V04, RMS_V05, EMT_V04, and EMT_V05.

The plotter automatically categorizes result files found in the configured paths:

Type	Enum	File pattern / detection
RMS	0	.csv file where the second line starts with "b:tnow in s"
EMT_INF	1	.inf file where the first line starts with PGB(1); associated .csv data files are expected in the same folder
EMT_PSOUT	2	.psout file
EMT_CSV	3	.csv file where the first line starts with time;
EMT_ZIP	4	.zip, .gz, .bz2, or .xz compressed EMT CSV output

Note

The plotter now determines the MTB path in .psout files automatically by searching for configured MTB signals. A separate psoutPathMTB setting is no longer required.

4.4 Configuration of figureSetup.csv

The figure setup file, figureSetup.csv, defines the plot figures and the RMS/EMT signals shown in each figure. A maximum of three EMT signals and three RMS signals can be specified per result file for each figure.

Column	Description
figure	Figure number. Currently used as an identifier in the setup file.
title	Figure title used in the plot output.
units	Units displayed on the y-axis.
emt_signal_1	First EMT signal to plot.
emt_signal_2	Second EMT signal to plot.
emt_signal_3	Third EMT signal to plot.
rms_signal_1	First RMS signal to plot.
rms_signal_2	Second RMS signal to plot.
rms_signal_3	Third RMS signal to plot.
down_sampling_method	Down-sampling method:gradient, amount, or no_down_sampling.
gradient_threshold	Threshold used whendown_sampling_method = gradient.
include_in_case	Comma-separated list of ranks where this figure should be included. If blank, the figure is global.
exclude_in_case	Comma-separated list of ranks where this figure should be excluded.

The plotter first builds a list of global figures where include_in_case is blank. For each rank mentioned in include_in_case or exclude_in_case, it starts with those global figures, adds specifically included figures, and removes specifically excluded figures.

Tip

If several RMS and EMT result folders are configured, a figure can quickly contain many traces. In that case, consider plotting fewer signals per figure to keep the legend readable.

Warning

If down_sampling_method = no_down_sampling, generated HTML files can become large and slow to load.

Note

The CSV file uses Danish regional settings, so ; must be used as the field separator. If the file is saved with comma delimiters, plotter.py will not read it correctly.

The default figureSetup.csv can be edited in Microsoft Excel:

The default figure setup includes signal selections for:

• Phase-phase voltages at PoC
• Phase-ground voltages at PoC
• Positive- and negative-sequence voltages at PoC
• Total currents at PoC
• Id and Iq currents at PoC
• Active and reactive power at PoC
• Frequency at PoC
• Id and Iq currents measured by the PLL
• Id and Iq currents and positive-sequence voltage at terminals
• Direct measurements at generating-unit terminals using the Unit block in PSCAD and PowerFactory
• Instantaneous voltage and current from the EMT model

4.5 Configuration of cursorSetup.csv

The cursor setup file, cursorSetup.csv, defines cursor metric tables for selected ranks. It is only used when genCursorHTML = True or genCursorPDF = True.

The detailed cursor metric setup is described in 6. Cursor Metrics.

4.6 Script Execution

Run the plotter from the plotter folder after config.ini, and optionally figureSetup.csv and cursorSetup.csv, have been configured:

cd plotter
python plotter.py

The generated HTML, image, and cursor result files are written to the folder defined by resultsDir in config.ini.

If the .py extension is associated with a Python interpreter, double-clicking plotter.py opens a new console window and starts the script:

Note

The console window may close automatically when the script finishes. Running python plotter.py from an already-open console is usually better, especially when debugging.

The script first loads and prints the configuration, then scans the configured simulation data paths and maps recognized result files by rank. Depending on processes, the plotter either processes ranks sequentially or distributes them across multiple Python processes.

When processes > 1, a progress bar is displayed:

Next to the progress bar, output similar to the following may be displayed:

136/181 [07:43<03:03,  4.09s/it]

This means:

• 136/181: 136 out of 181 ranks have completed.
• 07:43: elapsed time.
• 03:03: estimated remaining time.
• 4.09s/it: time used for the latest completed iteration.

When processes = 1, plots are generated sequentially. This is the preferred mode for debugging because errors can be associated with the rank currently being processed.

Caution

With genGuide = True, this might take a while, so only run with processes = 1 on a small subset of *.csv and *.psout files

4.7 Plot Result Examples

Below, the plot results for Case/Rank 40 are shown with htmlColumns = 2,

A zoomed-in view is shown below with red numbers highlighting key parts of the HTML output.

1. Previous Rank - navigates to the previous rank in the study, with wraparound.
2. Next Rank - navigates to the next rank in the study, with wraparound.
3. More Ranks - drop-down list for faster navigation between ranks.
4. Rank Number and Title - shows the rank number and case title from testcases.xlsx.
5. Subsection Hyperlinks - links to Figures, Cursors, and Source Data.
6. Figures subsection - contains the result plot figures.
7. Plot Figure Hyperlinks - links to each plot figure on the page.
8. Plot Figure Title - taken from figureSetup.csv.
9. Plot Figure Units - taken from figureSetup.csv.
10. Plot Figure Legend - lists the plotted signals. Click a legend item to hide or show the corresponding trace.
11. Plotly Buttons - standard Plotly controls for downloading, zooming, panning, autoscaling, and resetting axes.

The HTML reports also support keyboard shortcuts:

• Alt + Page Up: navigate to previous rank.
• Alt + Page Down: navigate to next rank.
• Alt + H: display help message.