Gtopt

Documentation Guide

This project includes comprehensive documentation for different use cases:

• README.md (this file) - Project overview, quick installation, and basic usage
• Understanding gtopt - Global overview: repository layout, architecture layers, data flow, and technology stack
• Planning Guide - Complete planning guide: time structure, system elements, JSON format, and worked examples
• Mathematical Formulation - Full LP/MIP optimization formulation with LaTeX notation
• Building Guide - Detailed build instructions for all platforms, dependencies, and troubleshooting
• Usage Guide - Complete command-line reference, examples, and advanced usage patterns
• Input Data Reference - Input data structure and file format reference
• User Constraints - User-defined LP constraints: AMPL-inspired syntax, domain specs, external files
• Scripts Guide - Python utilities: conversion (plp2gtopt, pp2gtopt, igtopt, ts2gtopt, cvs2parquet, gtopt2pp), visualization (gtopt_diagram), validation (gtopt_check_json, gtopt_check_lp, gtopt_check_output), and solver management (run_gtopt, sddp_monitor)
• Tool Comparison - Detailed comparison of gtopt vs PLP, pandapower, and other tools (elements, parameters, units, methodology)
• SDDP Method - SDDP solver: theory, options, monitoring API, elastic filter modes, and JSON configuration
• Cascade Method - Cascade solver: multi-level hybrid SDDP with warm-start
• Monolithic Method - Default monolithic solver, boundary cuts, and sequential mode
• Changelog - Release history and notable changes
• Contributing Guide - Contribution guidelines, code style, and testing
• webservice/INSTALL.md - Web service installation, deployment, and API reference
• guiservice/INSTALL.md - GUI service installation, deployment, and usage guide
• Diagram Tool - Network and planning diagram tool with aggregation and large-case support

Table of Contents

• Features
• Quick Install (Ubuntu)
• Usage
• Running the Sample Case
• Python Scripts
• GUI Service
• Web Service
• Related Tools
• License

Features

• Cost Optimization: minimizes investment (CAPEX) and operational (OPEX) costs.
• System Modeling: supports single-bus or multi-bus DC power flow (Kirchhoff laws).
• Multiple Solvers: monolithic LP, SDDP decomposition, and cascade multi-level hybrid SDDP with progressive LP refinement.
• Flexible I/O: high-speed parsing and export to Parquet, CSV, and JSON.
• Scalability: designed for large-scale grids with sparse matrix assembly.
• Web Service: browser-based UI and REST API for submitting and retrieving optimization results.

Quick Install (Ubuntu)

Install all dependencies, build, and install gtopt system-wide:

# 1. Install dependencies
sudo apt-get update
sudo apt-get install -y gcc-14 g++-14 libboost-container-dev coinor-libcbc-dev \
  ca-certificates lsb-release wget
wget https://packages.apache.org/artifactory/arrow/$(lsb_release --id --short \
  | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release \
  --codename --short).deb
sudo apt-get install -y -V ./apache-arrow-apt-source-latest-$(lsb_release \
  --codename --short).deb
sudo apt-get update
sudo apt-get install -y -V libarrow-dev libparquet-dev

# 2. Clone and build
git clone https://github.com/marcelomatus/gtopt.git
cd gtopt
CC=gcc-14 CXX=g++-14 cmake -S standalone -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# 3. Install system-wide
sudo cmake --install build

# 4. Verify
gtopt --version

For detailed build instructions, alternative platforms, troubleshooting, and build options, see Building Guide.

Usage

Run gtopt on a system configuration file:

gtopt system_config.json

Common options:

# Output results to a specific directory
gtopt system_c0.json --set output_directory=results/

# Single-bus mode (ignore network topology)
gtopt system_c0.json --set use_single_bus=true

# Enable DC power flow (Kirchhoff's laws)
gtopt system_c0.json --set use_kirchhoff=true

For complete command-line reference, advanced examples, and detailed usage instructions, see Usage Guide.

Running the Sample Case

The repository includes a sample case in cases/c0/ — a single-bus system with one generator and one demand with capacity expansion over 5 stages.

cd cases/c0
gtopt system_c0.json

The solver produces output files organized by component type in the output/ directory. A status of 0 in solution.csv indicates an optimal solution was found.

For a step-by-step walkthrough of running and interpreting the simplest case (ieee_4b_ori), see the Quickstart: Your First Solve section in the Planning Guide. For detailed output file descriptions, system file format, and advanced examples, see Usage Guide.

Python Scripts

The scripts/ directory contains Python utilities for preparing, converting, validating, and post-processing data for use with gtopt:

pip install ./scripts

# Basic conversion
plp2gtopt -i plp_case_dir -o gtopt_case_dir

# Create a ZIP archive ready to upload to gtopt_guisrv / gtopt_websrv
plp2gtopt -z -i plp_case_2y -o gtopt_case_2y

# Two hydrology scenarios with 60/40 probability split
plp2gtopt -i input/ -y 1,2 -p 0.6,0.4

# Apply a 10% annual discount rate
plp2gtopt -i input/ -d 0.10

GUI Service

A web-based graphical interface for creating, editing, and visualizing gtopt cases. The GUI service also connects to the gtopt webservice for remote solving.

# Install guiservice (independent of gtopt binary)
cmake -S guiservice -B build-gui
sudo cmake --install build-gui

# Install Python dependencies
pip3 install -r /usr/local/share/gtopt/guiservice/requirements.txt

# Launch interactively (opens browser, auto-starts webservice)
gtopt_gui

# Or with a specific configuration file
gtopt_gui system_c0.json

# Start GUI service on default port 5001
gtopt_guisrv

# Or with custom options
gtopt_guisrv --port 8080
gtopt_guisrv --debug

pip install -r guiservice/requirements.txt
cd guiservice
python app.py
# Open http://localhost:5001 in your browser

Web Service

gtopt includes a web service that lets you upload optimization cases, run the solver, and download results — all through a browser or REST API.

# Install webservice (independent of gtopt binary)
cmake -S webservice -B build-web
sudo cmake --install build-web

# Install Node.js dependencies (including build dependencies)
cd /usr/local/share/gtopt/webservice
npm install
npm run build

# Launch the web service
gtopt_websrv

# Or with options
gtopt_websrv --port 8080
gtopt_websrv --gtopt-bin /path/to/gtopt

Related Tools

gtopt integrates with and compares against several established power system tools. The Python scripts in scripts/ provide converters and validators for interoperability:

License

This project is released into the public domain under the [Unlicense](LICENSE).