Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GridOPTICS/GridPACK/llms.txt

Use this file to discover all available pages before exploring further.

GridPACK separates network input from simulation output into two distinct subsystems. On the input side, a family of PSS/E RAW parsers (and a MATPOWER parser) read industry-standard files and populate distributed DataCollection objects on each MPI rank. On the output side, SerialBusIO and SerialBranchIO gather result strings from all ranks to process 0 for ordered, sequential output. Results can also be exported in JSON or CSV format through ResultsExporter.

​
PSS/E RAW parsers

GridPACK ships six PTI/PSS/E parsers covering format versions 23 through 36. Each is a header-only template class parameterized by the application network type.
ClassHeaderPSS/E version
PTI23ParserPTI23_parser.hppv23 (legacy PTI)
PTI33ParserPTI33_parser.hppv33
PTI34ParserPTI34_parser.hppv34
PTI35ParserPTI35_parser.hppv35
PTI36ParserPTI36_parser.hppv36
The unreleased development branch can also auto-detect the PSS/E version from the RAW file header, removing the need to select a specific parser class at compile time.

​
Selecting a parser

#include <gridpack/parser/PTI33_parser.hpp>
#include <gridpack/parser/PTI35_parser.hpp>

// Choose the parser that matches your .raw file's PSS/E version
gridpack::parser::PTI33Parser<PFNetwork> parser33;
gridpack::parser::PTI35Parser<PFNetwork> parser35;

​
Parsing a RAW file

// network is a boost::shared_ptr<PFNetwork>
parser.parse("network.raw", network);

// After parsing, partition across MPI ranks
network->partition();
Each PTI parser populates a DataCollection for every bus and branch. The factory’s load() method then transfers those values into the strongly-typed bus and branch component objects.

​
MATPOWER parser

For MATPOWER .mat case files, use MAT_parser: 
#include <gridpack/parser/MAT_parser.hpp>

gridpack::parser::MAT_parser<PFNetwork> matParser;
matParser.parse("case118.mat", network);
network->partition();
MATPOWER format stores bus, generator, branch, and cost data in MATLAB structure arrays. The parser maps these to the same DataCollection keys used by the PSS/E parsers, so the rest of the application pipeline is format-agnostic.

​
XML input file structure

Every GridPACK application is driven by an XML configuration file. The networkConfiguration field inside the application block points to the network RAW file: 
<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <PowerFlow>
    <networkConfiguration>network.raw</networkConfiguration>
    <maxIteration>50</maxIteration>
    <tolerance>1.0e-6</tolerance>
    <dampingFactor>1.0</dampingFactor>
    <LinearSolver>
      <PETScOptions>
        -ksp_type bcgs
        -pc_type bjacobi
        -ksp_rtol 1.0e-8
      </PETScOptions>
    </LinearSolver>
  </PowerFlow>
</Configuration>
The application reads the file path from XML at runtime: 
std::string rawFile;
config->get("Configuration.PowerFlow.networkConfiguration", &rawFile);
parser.parse(rawFile, network);

​
SerialBusIO

gridpack::serial_io::SerialBusIO<_network> gathers formatted strings from every active bus across all MPI ranks and writes them in global bus index order from process 0. 
#include <gridpack/serial_io/serial_io.hpp>

// max_str_len: maximum characters any single bus might write
int max_str_len = 256;
gridpack::serial_io::SerialBusIO<PFNetwork> busIO(max_str_len, network);

// Write to standard output
busIO.header("Bus  Voltage(pu)  Angle(deg)\n");
busIO.write();

// Redirect to a file (only process 0 opens the file)
busIO.open("powerflow_results.txt");
busIO.header("Bus  Voltage(pu)  Angle(deg)\n");
busIO.write();
busIO.close();

// Pass an optional signal string to select output content
busIO.write("voltages");   // components inspect signal in serialWrite()

​
Component interface required

Each bus class must implement: 
// Fill buf with up to bufsize characters; return true if output was written
bool serialWrite(char *buf, int bufsize, const char *signal = NULL);
The signal parameter lets the application request different output formats from the same component — for example "voltages", "generation", or "mismatch".

​
SerialBranchIO

gridpack::serial_io::SerialBranchIO<_network> works identically to SerialBusIO but gathers output from branch components, ordered by global branch index. 
gridpack::serial_io::SerialBranchIO<PFNetwork> branchIO(128, network);

branchIO.open("line_flows.txt");
branchIO.header("From  To  P_from(MW)  Q_from(MVAR)\n");
branchIO.write();
branchIO.close();

​
Gathering structured data

Both IO classes provide gatherData for retrieving typed data (not just strings) to process 0: 
struct BusResult { int bus_id; double voltage; double angle; };

std::vector<BusResult> results;
busIO.gatherData(results, "voltages");
// results is populated only on process 0; empty on all other ranks

​
ResultsExporter (JSON and CSV)

As of GridPACK 3.6, power flow and contingency analysis results can be exported to JSON or CSV via ResultsExporter. This enables post-processing by downstream tools without parsing fixed-width text files. 
// JSON export (power flow results)
exporter.exportJSON("powerflow_results.json");

// CSV export (contingency analysis)
exporter.exportCSV("contingency_results.csv");
JSON export includes nested objects with bus voltage, generator output, and branch flow data grouped by bus and branch index. CSV export produces flat tables suitable for spreadsheet analysis.

​
Switching between PSS/E versions

1

Check the RAW file header

Open the .raw file and read the first line. The version number appears in the metadata string, for example 0, 100, 33, 0, 0, 60.0 / PSS/E-33.
2

Select the matching parser class

Replace PTI33Parser with PTI34Parser, PTI35Parser, or PTI36Parser in your application source to match the file version.
3

Recompile

All parsers share the same public API (parse(filename, network)), so no other source changes are required.
Using the wrong parser version for a given RAW file can silently misparse fields — particularly for switched shunts, three-winding transformers, and generator cost curves which differ across versions. Always verify the PSS/E version before selecting a parser.

XML configuration system

Detailed reference for the XML file format consumed by all GridPACK parsers.

Factory pattern

How factory.load() transfers parsed DataCollection values into network components.

Build docs developers (and LLMs) love

Get started for freeTalk to us