Command-line interface#

The gpf command runs the power flow solver from the shell.

gpf - CLI interface#

Power Flow solver for RAW, RAWX, or MATPOWER files.

gpf [-h] [-o [OUTPUT]] [--plain] [--json] [--backend {cuda,cpu}] [--max-iter MAX_ITER]
    [--tol TOL] [--outer-iters N] [--var-limit MODE] [--tap-adjust {on,off}]
    [--lcc-dc-tap-adjust {on,off}] [--phase-shift-adjust {on,off}]
    [--swshunt-adjust {on,off}] [--area-interchange {off,tie,tie-load}]
    [--low-voltage-load PU] [-q] [-v] [--skip-unmodeled]
    [--minimal-nr | --no-remote | --no-facts-dc] [--full | --summary] [-V]
    input

gpf positional arguments#

  • input - Input file (RAW, RAWX, or MATPOWER .m)

gpf options#

  • -h, --help - show this help message and exit

  • -o OUTPUT, --output OUTPUT - Output file (-o for auto-naming, -o FILE.html/json for specific format)

  • --plain - Force plain text (no colors)

  • --json - Force JSON output

  • --backend BACKEND - Backend to use (default: auto-detect, preferring cpu)

  • --max-iter MAX_ITER (default: 50)

  • --tol TOL (default: 1e-06)

  • --outer-iters N - Cap outer control passes (0=unlimited; 1=inner Newton only). (default: 0)

  • --var-limit MODE - VAR-limit policy: 'off' (never enforce), 'immediate' (enforce from outer 0), 'auto' (apply-automatically = enforce from outer 1), or 'at:<K>' for an explicit outer-pass index. Default: file-format aware — .raw/.rawx/.json use 'immediate', .m uses 'off' (MATPOWER's enforce_q_lims=0).

  • --tap-adjust TAP_ADJUST - AC tap-changer stepping. on (default) / off.

  • --lcc-dc-tap-adjust LCC_DC_TAP_ADJUST - LCC HVDC TAPR/TAPI stepping. on (default) / off.

  • --phase-shift-adjust PHASE_SHIFT_ADJUST - Phase-shifter MW-flow angle adjustment. on (default) / off.

  • --swshunt-adjust SWSHUNT_ADJUST - Switched-shunt discrete stepping. on (default) / off.

  • --area-interchange AREA_INTERCHANGE - Area-interchange control. off (default) / tie / tie-load.

  • --low-voltage-load PU - Voltage (pu) below which constant-power load tapers toward zero to bound low-voltage current. 0 (default) disables the taper. (default: 0.0)

  • -q, --quiet - Exit code only

  • -v, --verbose - Print run progress to stderr: setup-stage markers (parse, build, finalize) and a per-outer-pass solver trace. Auto-enabled for large inputs; silenced by -q.

  • --skip-unmodeled - Drop rows in unmodeled v34 sections (switching device, GNE, induction machine, substation). Use only when those records cannot affect the residual for your case.

  • --minimal-nr - Minimal Newton-Raphson: no outer-loop, no FACTS/HVDC (debug mode)

  • --no-remote - No remote voltage regulation from generators

  • --no-facts-dc - No FACTS devices or VSC-HVDC

  • --full - Show all tables (bus, gen, branch) regardless of system size

  • --summary - Show summary only (no per-bus/branch tables)

  • -V, --version - show program's version number and exit

gpf - GPF tool CLI.

Solve power flow for RAW, RAWX, or MATPOWER files and output results.

Examples:
    gpf ieee14.rawx                     # Solve and print (auto-detect format)
    gpf case9.m                         # Solve MATPOWER case
    gpf ieee14.rawx -o                  # Save to ieee14.txt
    gpf ieee14.rawx -o result.html      # Save as HTML (auto-detect from ext)
    gpf ieee14.rawx -o result.json      # Save as JSON (auto-detect from ext)
    gpf ieee14.rawx --plain             # Force plain text (no colors)
    gpf ieee14.rawx --json              # Force JSON to stdout
    gpf large_case.raw --full           # Show all tables for large systems
    gpf ieee14.rawx --summary           # Show summary only (no tables)

Output detail (terminal only):
    Auto mode hides tables for large systems to keep output readable:
      <=200 buses: full output (bus + gen + branch tables)
      201-500 buses: bus + gen tables (no branch)
      >500 buses: summary only (no tables)
    Use --full to override and show all, --summary to force minimal output.