stepss-cg-studio 0.1.0

Visual block diagram editor for STEPSS CODEGEN power system models

CODEGEN Studio

CODEGEN Studio is a browser-based, drag-and-drop visual editor for building STEPSS CODEGEN User-Defined Models — part of the STEPSS power system simulation suite. It lets you create device models by wiring blocks on a canvas instead of manually writing DSL files.

STEPSS has been developed by Dr. Petros Aristidou (Cyprus University of Technology) and Dr. Thierry Van Cutsem (Emeritus, University of Liège).

Overview

CODEGEN Studio replaces the manual editing of CODEGEN DSL .txt files with a graphical workflow. You drag blocks from a categorised palette, connect input/output ports to define signal flow, fill in metadata tables, and export ready-to-compile DSL files — or run the codegen binary directly from the editor to generate Fortran .f90 source.

The tool supports all four CODEGEN model types:

Type	Purpose	Mandatory Outputs
EXC	Excitation controller	vf
TOR	Torque controller	tm
INJ	Current injector	ix, iy
TWOP	Two-port device	ix1, iy1, ix2, iy2

Key Features

• Drag-and-drop block diagram editor — assemble models visually on a canvas with 51 built-in blocks
• Live DSL preview — syntax-highlighted code updates in real time as you edit
• Lossless round-trip — import existing .txt DSL files with automatic canvas layout, edit, and re-export
• One-click Fortran generation — run the codegen binary directly from the browser
• Project save/load — .cgproj files preserve full editor state including block positions
• Mandatory output validation — warns when required outputs for the model type are missing
• Undo/redo — 60-step history with keyboard shortcuts
• Extensible block catalogue — add new blocks via a single JSON entry, no code changes required
• No build step — vanilla JavaScript frontend served by a Python backend

Installation

Requirements

• Python ≥ 3.10
• A modern browser (Chrome, Firefox, or Edge)
• (Optional) CODEGEN binary for .f90 generation

Install

git clone https://github.com/SPS-L/stepss-cg-studio.git
cd stepss-cg-studio
pip install -r requirements.txt

Quick Start

# Start the server
python server/app.py

# Open in browser
# http://localhost:8765

On Windows, double-click run.bat. On Linux/macOS, run ./run.sh.

Building a model

1. Select model type and name — choose EXC, TOR, INJ, or TWOP from the toolbar dropdown
2. Add blocks — drag blocks from the left-hand palette onto the canvas
3. Connect blocks — wire output ports to input ports to define signal flow
4. Edit block properties — select a block to configure output names and arguments in the inspector
5. Populate metadata — fill in Data, Parameters, States, and Observables in the tabs below the canvas
6. Export — click "Export DSL" for the .txt file, or "Run Codegen" to generate Fortran directly

Keyboard shortcuts

Shortcut	Action
Ctrl/Cmd + S	Save project
Ctrl/Cmd + Z	Undo
Ctrl/Cmd + Shift + Z	Redo
Delete / Backspace	Delete selected block
Escape	Close modal

Project Structure

stepss-cg-studio/
├── server/
│   ├── app.py              # FastAPI server & API endpoints
│   ├── dsl_parser.py       # DSL .txt → ModelProject dict
│   ├── dsl_emitter.py      # ModelProject dict → DSL .txt
│   └── config.json         # Runtime config (codegen path, host, port)
├── frontend/
│   ├── index.html          # Single-page app
│   ├── css/style.css
│   ├── js/
│   │   ├── main.js         # App bootstrap, toolbar, file I/O
│   │   ├── canvas.js       # Drawflow integration & auto-layout
│   │   ├── store.js        # ModelProject state, topological sort, undo/redo
│   │   ├── forms.js        # Metadata tables & block inspector
│   │   ├── palette.js      # Block palette with search
│   │   ├── dsl_preview.js  # Live DSL preview (CodeMirror)
│   │   └── api.js          # Backend API wrappers
│   └── blocks.json         # Block catalogue (51 blocks, extend here)
├── examples/               # Example .cgproj project files
├── tests/                  # Pytest test suite (~75 tests)
├── docs/                   # Design documents
├── requirements.txt
├── run.bat                 # Windows launcher
└── run.sh                  # Linux/macOS launcher

Adding New Blocks

Edit frontend/blocks.json — add a single JSON entry with the block name, ports, argument schema, DSL line templates, and category. No JavaScript or Python changes required.

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_parser.py -v

# Run a single test
pytest tests/test_parser.py::test_function_name -v

CI runs pytest on Python 3.10–3.12 via GitHub Actions.

Settings

Access via the gear icon in the toolbar:

• Codegen binary path — full path to the codegen executable (default: codegen on system PATH)
• Server host — change to 0.0.0.0 for network access (default: 127.0.0.1)
• Server port — HTTP port (default: 8765)

Settings are stored in server/config.json and also editable via the REST API at /docs.

Documentation

Full documentation is available at https://stepss.sps-lab.org/developer/cg-studio/.

• User-Defined Models — DSL format specification
• CODEGEN Blocks Library — complete block reference
• CODEGEN Model Examples — annotated example files

License

MIT — see LICENSE.

Authors

Developed by the Sustainable Power Systems Lab (SPS-L), Cyprus University of Technology.

• Dr. Petros Aristidou — Cyprus University of Technology
• Dr. Thierry Van Cutsem — Emeritus, University of Liège

Support

• Documentation: https://stepss.sps-lab.org/developer/cg-studio/
• Issues: https://github.com/SPS-L/stepss-cg-studio/issues
• Project page: https://sps-lab.org/