perc-studio > Commands > PSS/E and black box
Black-box validation characterizes any load model from outside: its records run unchanged on a one-bus PSS/E rig, a search finds its ride-through boundaries, and the result is compared with the presets you choose. Background: BLACK_BOX_VALIDATION.md. The commands here are the same work as the app's Black-Box Validation tab, for scripts.
| Command | Needs PSS/E | Purpose |
|---|---|---|
psse check |
yes | Prove a PSS/E selection works |
dll inspect |
no | Check a model DLL before PSS/E loads it |
blackbox |
yes | Run the validation |
results list/show/cases/plot |
no | Browse finished runs |
Starts PSS/E with a selection and reports what it says: the exact version, the Python, and whether it initialized and solved the test rig's power flow.
perc-studio psse check --psse-version 35.6
perc-studio psse check --psse-version 36.7 --psse-dir "D:/PTI/PSSE36/36.7" --python "C:/Python313/python.exe"| Option | Default |
|---|---|
--psse-version |
required; 35.x and 36.x only (34 and earlier are 32-bit) |
--psse-dir |
the version's standard folder, e.g. C:\Program Files\PTI\PSSE35\35.6 |
--python |
the interpreter the folder's PSSPYxx names, found with the py launcher |
--pspy |
the newest PSSPYxx folder |
Exit 4 when the selection does not work (wrong version in the folder, wrong Python, license refused);
errors[0] says which. All blackbox commands take the same four options.
Reads one or more DLLs without loading them: architecture, exported symbols, imports, SHA-256, and which imports
cannot be found next to the DLL, in PSS/E's PSSBIN or on PATH.
perc-studio dll inspect PERC2_v35_v2p3.dll --psse-root "C:/Program Files/PTI/PSSE35/35.6" --model PERCBL
perc-studio dll inspect a.dll b.dll | jq -r '.data.dlls[] | "\(.path)\t\(.machine)\t\(.sha256)"'--model NAME (repeatable) notes when the DLL does not export that model name. Exit 5 if any DLL has a problem
(not an x64 build - PSS/E 35 and later load only x64; unreadable; missing dependency); data.dlls[].problems says
what. data.all_ok is the summary.
perc-studio blackbox --psse-version 35.6 --dyr model.dyr --list
perc-studio blackbox --psse-version 35.6 --dyr model.dyr --dll model.dll --load 1 \
--level standard --preset ercot_nogrr282 --preset pjm_lcl --out output/bbv| Option | Meaning |
|---|---|
--dyr FILE |
The model's .dyr (required) |
--dll FILE |
The model's DLL; repeatable |
--list |
List the loads in the file and exit (no PSS/E needed) |
--load N |
Which load to test (1-based, from --list); required when the file has more than one |
--level quick|standard|full |
About 150, about 400, or 1500+ PSS/E runs (default standard) |
--preset ID |
A preset to compare with; repeatable |
--delt S |
Force the time step; otherwise the time-step check chooses |
--workers N |
Parallel PSS/E processes (default 4) |
--p-mw, --q-mvar |
The rig load (default 100 MW, 20 Mvar) |
--out DIR |
Required: gets report.html, validation.json, bundle.zip |
--include-dlls |
Put the DLLs in the bundle (default: hashes only) |
bundle.zip holds every case's job, trace and log, the worker, and a rerun.py that repeats them on any PSS/E
install. Exit 5 when the validation stopped before the end (for example PSS/E could not read the model);
data.stopped says why. data.overall maps each compared preset to its verdict (meets, fails, at the edge, ...).
perc-studio blackbox --psse-version 35.6 --dyr m.dyr --out out/bbv --preset ercot_nogrr282 | jq '.data.overall'Browse what blackbox (or the app) left on disk. None of these starts PSS/E.
perc-studio results list output/bbv_runs # every run under a root, newest first
perc-studio results show output/bbv_runs/20261012-140311 # one run's summary
perc-studio results cases output/bbv/bundle.zip # its cases
perc-studio results plot output/bbv/bundle.zip --case 14ee1457ccdbecf92813e73a --channel V --out v.htmlresults list RUN_ROOT: each run's title, date, level, case count, PSS/E version, DLLs,overallverdict, the verdict per compared preset and per event family, andwarnings.results show RUN_FOLDER: the same plusmeasured, the "measured behaviour" table (for exampleUndervoltage 0.3-0.4 pu | trips after | 0.273-0.289 s).results cases PATH: PATH is a run folder, itsvalidation.json, or abundle.zip. Each case has akey, the testgroup, alabel(the event), itsverdictand theeventwindow.--groupfilters by group title.results plot PATH --case KEY ... --out FILE.html: an interactive plot of the chosen cases' channels overlaid (--channelrepeatable; defaultVandP; others recorded in the run, such asF (Hz), are available). Zoom and hover come from the HTML; the event window is shaded.
To try these, run a Quick validation first (perc-studio blackbox ... --out out/demo) and point them at its run
folder.