4. Quickstart Guide Plotter
The MTB Plotter is a tool that allows comparative plotting of the MTB's generated RMS and EMT results with ideal signal overlays (for some cases) and cursor metrics to aid with the evaluation of the results.
The tool is located in the "plotter" folder which includes, among others, the main script plotter.py, a configuration file, config.ini, a figure setup file, figureSetup.csv, and a cursor setup file, cursorSetup.csv
Before running the main script, you should configure at least the configuration file, config.ini and optionally, the figure setup file, figureSetup.csv
Below, an example of the plotter configuration file, config.ini, is given.
The plotter configuration file contains the following modifiable parameters:
| Parameter | Type | Default | Description | Version |
|---|---|---|---|---|
| [config] | ||||
| resultsDir | string | results | The relative path for plotter results folder | |
| genHTML | boolean | True | Whether or not to generate HTML plot result files | |
| genlmage | boolean | True | Whether or not to generate image plot result files | |
| genGuide | boolean | False | Generate guideline curve(s) to selected cases | >= 2.0 |
| genCursorHTML | boolean | True | Generated a cursor table in the HTML output | >= 2.0 |
| genCursorPDF | boolean | False | Generated PDF cursor output files for each case | >= 2.0 |
| imageFormat | string | png | Plot image format, either png or jpeg | |
| htmlColumns | integer | 2 | Number of HTML columns produced | |
| imageColumns | integer | 3 | Number of image columns produced | |
| htmlCursorColumns | integer | 2 | Number of HTML columns produced | |
| processes | integer | 8 | Number of concurrent Python processes for producing result files | |
| testcaseSheet | string | -- | Path to testcases.xlsx (mandatory) | |
| psoutPathMTB | string | -- | PSOUT path from Main Canvas to the MTB Block | |
| [Simulation data paths] | ||||
| PathlLegendName | string | ..\export\MTB_XXX | Path1 for RMS or EMT data directory, e.g. RMS | |
| Path2LegendName | string | ..\export\MTB_YYY | Path2 for RMS or EMT data directory, e.g. EMT | |
| Path3LegendName | string | -- | Path3 for RMS or EMT data directory | |
| etc. |
Note
If htmlColumns > 3, the HTML output will be a "subplot" with a common legend on the righthand side instead of each plot figure having its own legend from where signals can hidden or shown again by clicking on the coloured line next to the signal name.
Important
From MTB version 2.0, is mandatory to include the relative path to testcases.xlsx file that was used by the MTB to generate the simulation result files. To use the new plotter.py with legacy version of the testcases.xlsx spreadsheet, please have a look here.
Note
The option psoutPathMTB can be left blank if the MTB block is placed on the 'Main' Canvas. If it is however places on another canvas inside the 'Main' Canvas, e.g. 'External_Grid', then psoutPathMTB = External_Grid
This is because the PSOUT signal path would now be, e.g Root/Main/External_Grid/MTB/meas_Vab_pu/0 and not Root/Main/MTB/meas_Vab_pu/0 as usual
Tip
The paths under the section header [Simulation data paths] can be appended to compare additional results from multiple models. Simply add a new line matching the folder containing the data one wants to plot.
The strings Path1LegendName, Path2LegendName, etc. used for each data path will be appended in front of all the signals names from that specified data path. It could be as simple as e.g.
- EMT
- RMS
or more elaborate if different versions of RMS and EMT results are being plotted to compare results from different versions, e.g.
- RMS_V04,
- RMS_V05,
- EMT_V04,
- EMT_V05,
- etc.
The plotter tool automatically categorizes results found in the paths of the [Simulation data paths] section header. An RMS result file is defined as a .csv file with the leftmost column named b:tnow in s and an EMT_INF result file (metafile) is defined as an .inf file with the first line starting with PGB(1). _EMT_INF_datafiles (*.csv) are assumed to be in the same folder as the .inf metafile. All files with extension .psout are assumed to be of type EMT_PSOUT, the new binary-based PSCAD output.
Note
The plotter tool also supports .csv and compressed .csv output generated by the psout_to_csv.py script
| Type | Enum | Description |
|---|---|---|
| RMS | 0 | PowerFactory standard .csv output |
| EMT_INF | 1 | PSCAD legacy .inf/.csv output |
| EMT_PSOUT | 2 | PSCAD new style .psout output |
| EMT_CSV | 3 | PSCAD .psout -> .csv support |
| EMT_ZIP | 4 | PSCAD .psout -> .zip, .gz, .bz2 and .xz support |
The figure setup file, figureSetup.csv, is used to configure individual plot figures. A maximum of three EMT signals per EMT result file, and three RMS signals per result file can be specified for each plot figure.
| Column | Description |
|---|---|
| figure | Figure number (currently not used) |
| title | Figure title to be used for each plot figure |
| units | Units to be displayed on the y-axis for each plot figure |
| emt_signal_1 | Name of first EMT signal to be plotted for each figure |
| emt_signal_2 | Name of second EMT signal to be plotted for each figure |
| emt_signal_3 | Name of third EMT signal to be plotted for each figure |
| rms_signal_1 | Name of first RMS signal to be plotted for each figure |
| rms_signal_2 | Name of second RMS signal to be plotted for each figure |
| rms_signal_3 | Name of third RMS signal to be plotted for each figure |
| down_sampling_method | Down sampling method to use [gradient (default) | amount | no_down_sampling ] |
| gradient_threshold | Only valid if down_sampling_method = gradient was selected (default = 0.5) |
| include_in_case | Comma separated list of values of all the cases the specific plot figure should be included in |
| exclude_in_case | Comma separated list of values of all the cases the specific plot figure should be excluded from |
Tip
If more than two result files are specified in the config.ini file, e.g. (say) two EMT result files and (say) two RMS result files, the plot figure legend could have up to twelve signals in the plot figure legend, and the plot itself could have up to six EMT signals and six RMS signals.
In such cases it would be better to maybe specify only one EMT and oneRSM signal per plot figure. For the above example, this will lead to only four signals in the plot figure legend, and only two EMT and two RMS signals per plot figure
Warning
If down_sampling_method = no_down_sampling is selected, the HTML files can become quite large and might take quite a long time to load.
Note
If include_in_case is left blank, the figure plot will be included in all cases/ranks And similar, if exclude_in_case is left blank, the figure plot will not be excluded from all cases/ranks
The default figureSetup.csv can easier be edited using Microsoft Excel,
Caution
The CSV file used Danish regional settings which implies ';' should be used as field separator. If the CSV file where to be saved with ',' delimiters, it will not open correctly by the plotter.py script.
The default signal selection in figureSetup.csv are:
- Phase-phase voltages at POC
- Phase-ground voltages at POC
- Positive- and Negative-sequence voltages at POC
- Total currents at POC
- Id current at POC
- Iq current at POC
- Active power at POC
- Reactive power at POC
- Frequency at POC
- Id current at POC measured by pll
- Iq component current at POC measured by pll
- Id and Iq currents, and positive-sequence voltage at a terminal
- Direct measurement at the generating unit's terminals using the Unit block in PSCAD & PowerFactory (delete if not used)
- Instantaneous Voltage from the EMT model
- Instantaneous Current from the EMT model
Execute the "plotter.py" script after config.ini, see section 4.2, and optionally, figureSetup.csv, see section 4.3 have been configured. The plotter HTML, PNG|JPG result will be generated in the results folder as defined in the config.ini file.
If the '.py' extension is associated with a Python interpreter,
double clicking on the 'plotter.py' script, will open a new console window, and start executing the script.
Note
As soon as the script is done, the console window will close automatically. It is thus better to run the 'plotter.py' script from an open console window.
The script will first load and display the 'config.ini' information, and then assemble a list with all the simulation data files, i.e. all the '.csv' and '.psout' files. Depending on the number of processes, the script may take some time to distribute the concurrent plotting processes among the CPU processors.
When running with processes > 1, a progress bar will be displayed
Next to the progress bar, something like the following will be displayed, e.g. 141/176 [08:54<07:00, 12.02s/it]
It indicated that,
- 141 of the 176 concurrent processes has been completed, and hence the progress bar will show 80% completion
- 08:54 is time elapsed
- <07:00 is the estimated time remaining, based on the last completed process
- 12.02s/it is the time it took for the last iteration, or process
When executing the 'plotter.py' script with processes = 1, plots are generated sequentially and is the preferred method for debugging, as it is difficult to determine which plot is generating an error message, when (say) 10 plots are being generated concurrently.
Below, the plot results for Case/Rank 38 is shown with htmlColumns = 3, ideal for a 40" monitor.
A zoomed-in view of the above picture is shown below with red numbers to highlight certain aspects of the HTML output.
- Previous Rank - button to navigate to the previous rank in the study (supports wraparound)
- Next Rank - button to navigate to the next rank in the study (supports wraparound)
- More Ranks - drop-down list that lists every tenth rank in the study to enable quicker navigation between results further away from each other
- Rank Number and Title - display the case's rank number and the more descriptive rank title as defined in the testcases.xlsx sheet
- Subsection Hyperlinks - hyperlinks to the Figures, Cursors and Source Data sections
- Figures subsection - where all the result plot figures are shown
- Plot Figure Hyperlinks - hyperlinks to all the plot figures of the case
- Plot Figure Title - as defined in the figureSetup.csv file
- Plot Figure Units - as defined in the figureSetup.csv file
- Plot Figure Legend - list all the signals in the plot figure. By clicking on the coloured line to the left of the legend text, the specific signal can be hidden or shown again in the figure plot.
-
Plotly Buttons button to:
- Download plot as png - the plot figure will be download as a PNG as Rank_<rank no>-<rank title>-Plot-<plot figure title>.png
- Zoom - to zoom in with the mouse (double clicking anywhere on the plot figure will reset the zoom)
- Pan - to pan with the mouse after zooming
- Zoom in - zooms in step-wise with respect to the center of the plot figure
- Zoom out - zooms out step-wise with respect to the center of the plot figure
- Autoscale - auto scales the plot figure to show all data points
- Reset axis - reset back to the default plot figure scale (which currently is set to Autoscale)
Additionally, keyboard shortcuts are added to navigate through HTML result ranks:
- Alt + Page Up = Navigates to previous rank.
- Alt + Page Down = Navigates to next rank.
- Alt + H = Displays help message.
