Document all simulation interfaces: Command Line, GUI, and Python

apetros · apetros · commit 4353f11998b5 · 2026-03-28T21:08:47.000Z
- Restructured Quick Start with separate RAMSES and PFC sections
- Added RAMSES CLI: -t (command file), -v (version), interactive prompts
- Added PFC CLI: -t, -o, -c, -v flags and full menu commands (P/D/M/RI/CA/CL/O/DF/VT/S/E)
- Added Simulation Interfaces table to Overview page
- Clarified: RAMSES = CLI + GUI + Python; PFC = CLI + GUI
diff --git a/src/content/docs/getting-started/overview.md b/src/content/docs/getting-started/overview.md
@@ -84,11 +84,24 @@ Four types of user-defined models are supported:
 
 The user model is **compiled, not interpreted** — resulting in efficient number-crunching code. While the solver code is proprietary, the models are designed to be freely shared, making STEPSS an **open-source simulation software** for the modeling part.
 
+## Simulation Interfaces
+
+STEPSS modules can be run through three interfaces:
+
+| Interface | RAMSES (Dynamic) | PFC (Static) | CODEGEN |
+|-----------|:----------------:|:------------:|:-------:|
+| **Command Line** | `ramses.exe -t cmd.txt` | `pfc.exe -t cmd.txt` | Via STEPSS GUI |
+| **GUI (Java)** | Full support | Full support | Full support |
+| **Python (PyRAMSES)** | Full support | — | — |
+
+See the [Quick Start](/stepss-docs/getting-started/quickstart/) for details on each interface.
+
 ## Platform Support
 
 | Feature | Details |
 |---------|---------|
 | **STEPSS GUI** | Windows 64-bit, Java 20 |
 | **PyRAMSES** | Windows and Linux, Python 3.x |
+| **Command-line executables** | Windows 64-bit (ramses.exe, pfc.exe) |
 | **CODEGEN compilation** | Visual Studio 2022 + Intel oneAPI Fortran |
 | **Free version limits** | 1000 buses max, 2 OpenMP cores |
diff --git a/src/content/docs/getting-started/quickstart.mdx b/src/content/docs/getting-started/quickstart.mdx
@@ -5,10 +5,86 @@ description: Run your first STEPSS simulation
 
 import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
 
-This guide walks through running a basic power system simulation using either the STEPSS GUI or PyRAMSES.
+STEPSS provides three ways to run simulations:
+
+| Interface | Dynamic Simulator (RAMSES) | Static Simulator (PFC) |
+|-----------|:-------------------------:|:----------------------:|
+| **Command Line** | `ramses.exe -t cmd.txt` | `pfc.exe -t cmd.txt` |
+| **GUI (Java)** | Via STEPSS GUI | Via STEPSS GUI |
+| **Python** | Via PyRAMSES | — |
+
+---
+
+## Dynamic Simulation (RAMSES)
 
 <Tabs>
-<TabItem label="GUI">
+<TabItem label="Command Line">
+
+### RAMSES Command-Line Interface
+
+The RAMSES executable accepts the following arguments:
+
+```bash
+ramses.exe [-t command_file] [-v]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-t command_file` | Read inputs from a command file (non-interactive mode) |
+| `-v` | Print version information and exit |
+
+**Interactive mode** (no `-t` flag): RAMSES prompts for each input sequentially:
+
+```
+Dump settings, comments and initialization data in file [press enter to skip] :
+Disturbance file name [compulsory] :
+Dump system trajectory in file [press enter to skip] :
+Observable file name [compulsory] :
+Dump continuous simulation trace in file [press enter to skip] :
+Dump discrete simulation trace in file [press enter to skip] :
+```
+
+**Non-interactive mode** (`-t` flag): The command file provides the same inputs as lines, in order:
+
+<Steps>
+
+1. **Prepare data files**: Network data, dynamic data, solver settings, LFRESV (power flow solution)
+
+2. **Create a command file** (`cmd.txt`):
+   ```
+   data.dat volt_rat.dat settings.dat
+   
+   disturbance.dst
+   result.rtrj
+   obs.obs
+   cont.trace
+   disc.trace
+   ```
+
+   The command file contains, in order:
+   - **Data files** (one or more, space- or newline-separated) — read until a blank line
+   - **Initialization dump file** (blank line to skip)
+   - **Disturbance file** (required)
+   - **Trajectory file** (blank line to skip)
+   - **Observables file** (required if trajectory file is given)
+   - **Continuous trace file** (blank line to skip)
+   - **Discrete trace file** (blank line to skip)
+
+3. **Run the simulation**:
+   ```bash
+   ramses.exe -tcmd.txt
+   ```
+
+4. **Process results**: Use PyRAMSES extractor, MATLAB, or other tools to read the trajectory file
+
+</Steps>
+
+:::note
+Lines starting with `#` in the command file are treated as comments and skipped.
+:::
+
+</TabItem>
+<TabItem label="GUI (Java)">
 
 <Steps>
 
@@ -21,6 +97,8 @@ This guide walks through running a basic power system simulation using either th
 
 </Steps>
 
+The GUI coordinates PFC and RAMSES through lock files (`.lock_RAMSES`, `.kill_RAMSES`) for graceful process management.
+
 For detailed GUI usage, visit the [STEPSS website](https://sps-lab.org/project/stepss/).
 
 </TabItem>
@@ -33,96 +111,144 @@ For detailed GUI usage, visit the [STEPSS website](https://sps-lab.org/project/s
    pip install pyramses
    ```
 
-2. **Create a command file** (`cmd.txt`):
-   ```
-   data.dat
-   
-   init.trace
-   dst.dst
-   result.rtrj
-   obs.obs
-   cont.trace
-   disc.trace
-   ```
-
-3. **Run a simulation**:
+2. **Run a simulation**:
    ```python
    import pyramses
-   
-   # Initialize simulator
+
+   # Configure the case
+   case = pyramses.cfg()
+   case.addData("data.dat")
+   case.addData("volt_rat.dat")
+   case.addData("settings.dat")
+   case.addObs("obs.obs")
+   case.addDst("disturbance.dst")
+
+   # Run
    ram = pyramses.sim()
-   
-   # Load test case from command file
-   case = pyramses.cfg("cmd.txt")
-   
-   # Run full simulation
-   ram.execSim(case)
+   ram.execSim(case, 150.0)
    ```
 
-4. **Extract and plot results**:
+3. **Extract and plot results**:
    ```python
-   # Extract trajectory data
    ext = pyramses.extractor(case.getTrj())
-   
+
    # Plot bus voltage magnitude
    ext.getBus('1041').mag.plot()
-   
+
    # Plot synchronous machine speed
    ext.getSync('g1').speed.plot()
    ```
 
 </Steps>
 
+See the [PyRAMSES API Reference](/stepss-docs/pyramses/api-reference/) for the complete interface.
+
 </TabItem>
-<TabItem label="CLI">
+</Tabs>
+
+---
+
+## Static Simulation (PFC)
+
+<Tabs>
+<TabItem label="Command Line">
+
+### PFC Command-Line Interface
+
+The PFC executable accepts the following arguments:
+
+```bash
+pfc.exe [-t command_file] [-o output_file] [-c trigger_file] [-v verbosity]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-t command_file` | Read inputs from a command file (non-interactive mode) |
+| `-o output_file` | Redirect output to a file instead of the console |
+| `-c trigger_file` | Cycle mode — wait for trigger file to start/proceed |
+| `-v N` | Verbosity level (0 = silent, 1 = normal) |
+
+**Interactive mode** (no `-t` flag): PFC prompts for data files, then presents a command menu.
+
+**Non-interactive mode** (`-t` flag): The command file provides data file names (one per line, blank line to end), followed by menu commands.
 
 <Steps>
 
-1. **Prepare data files**: Create network data, dynamic data, disturbance, and solver settings files
+1. **Prepare data files**: Network data, PFC-specific data (generators, loads, SVC, LTC-V, PSHIFT-P)
 
-2. **Run simulation via RAMSES executable**:
-   ```bash
-   dynsim.exe cmd.txt
+2. **Create a command file** (`pfc_cmd.txt`):
+   ```
+   network.dat
+   pfc_data.dat
+
+   VT
+   volt_rat.dat
+   E
    ```
 
-3. **Process results** using MATLAB, Python, or other tools
+3. **Run the power flow**:
+   ```bash
+   pfc.exe -tpfc_cmd.txt -ooutput.txt
+   ```
 
 </Steps>
 
+### PFC Menu Commands
+
+After loading data and solving, PFC presents these commands:
+
+| Command | Description |
+|---------|-------------|
+| `P` | Take new control parameters from file |
+| `D` | Display output values |
+| `1` | Display outputs on 1-line diagram (SVG) |
+| `M` | Modify system (change loads, generators, topology) |
+| `RI` | Reset system to initial configuration |
+| `CA` | Perform contingency analysis |
+| `CL` | Check operating limits (voltage bounds, branch overloads) |
+| `O` | Change output file |
+| `DF` | Update all records and dump them to a file |
+| `VT` | Generate a file with voltages and adjustable transformer ratios (LFRESV format) |
+| `S` | Save operating point and Y matrix to MATLAB file |
+| `E` | Exit |
+
+The `VT` command produces the LFRESV file needed to initialize RAMSES.
+
 </TabItem>
-</Tabs>
+<TabItem label="GUI (Java)">
 
-## Command File Structure
+<Steps>
 
-The command file (`cmd.txt`) lists the input files for a simulation, separated by blank lines:
+1. **Launch STEPSS** by double-clicking `stepss.jar`
+2. **Load data files**: Use File → Open to load network and PFC data files
+3. **Run Power Flow**: Click the PFC button to compute the power flow
+4. **Inspect results**: View bus voltages, branch flows, generator outputs, and reactive power limits
+5. **Export LFRESV**: Save the power flow solution for use with RAMSES
 
-```
-datafile1.dat        # Network + dynamic data files
-datafile2.dat        # (one or more)
-
-init.trace           # Initialization output (optional)
-disturbance.dst      # Disturbance scenario
-result.rtrj          # Trajectory output (optional)
-obs.obs              # Observables definition (required if trajectory given)
-cont.trace           # Continuous trace output (optional)
-disc.trace           # Discrete trace output (optional)
-```
+</Steps>
 
-Records can be distributed across an arbitrary number of data files, read sequentially. The order of records and files does not matter.
+For detailed GUI usage, visit the [STEPSS website](https://sps-lab.org/project/stepss/).
+
+</TabItem>
+</Tabs>
+
+---
 
 ## Typical Workflow
 
 1. **Define the network**: Specify buses, lines, transformers, and shunts
 2. **Set up power flow data**: Define generators, loads, and the slack bus
-3. **Add dynamic models**: Specify synchronous machines, excitation systems, speed governors, loads, and controllers
-4. **Configure solver**: Set integration method, time steps, and tolerances
-5. **Define disturbances**: Specify faults, line trips, parameter changes, etc.
-6. **Run simulation**: Execute PFC for initialization, then RAMSES for dynamics
-7. **Analyze results**: Extract and visualize trajectories of voltages, frequencies, and powers
+3. **Run PFC**: Compute the initial operating point and export LFRESV
+4. **Add dynamic models**: Specify synchronous machines, excitation systems, speed governors, loads, and controllers
+5. **Configure solver**: Set integration method, time steps, and tolerances
+6. **Define disturbances**: Specify faults, line trips, parameter changes, etc.
+7. **Run RAMSES**: Execute the dynamic simulation
+8. **Analyze results**: Extract and visualize trajectories of voltages, frequencies, and powers
 
 ## Next Steps
 
 - [File Formats](/stepss-docs/user-guide/file-formats/) — Learn about data file syntax
 - [Network Modeling](/stepss-docs/user-guide/network/) — Define your power system network
+- [Power Flow (PFC)](/stepss-docs/user-guide/pfc/) — PFC data and control parameters
 - [Dynamic Models](/stepss-docs/user-guide/dynamic-models/) — Add generators, loads, and controllers
 - [PyRAMSES API](/stepss-docs/pyramses/api-reference/) — Full Python API documentation
