STEPSS GUI already saves and loads a case as a .cfg scenario file: which data
files it reads, the disturbance, the one-line diagram, the observables file and
wizard tick, the three run-time observable rows, and the four recording
checkboxes. File > Save configuration writes it and Load configuration
reads it back.
The Python interface expresses the same thing as stepss.cfg, and builds it in
code. So the two interfaces describe an identical object in two formats that
have nothing to do with each other, and a case set up in one cannot be opened
in the other.
What to add
stepss.cfg should be able to load from, and save to, the GUI's .cfg. A case
set up in the GUI should open in a notebook, and a case built in a notebook
should open in the GUI.
The format
Documented key by key, with a worked example and the rules a hand-written file
has to respect:
https://stepss.sps-lab.org/user-guide/file-formats/#scenario-file-cfg
The reference implementation is my.stepss.config in stepss-java-ui:
ScenarioFile owns the keys and the parsing, Scenario is the data, and
ScenarioPaths is the relative/absolute rule. ScenarioHarness is where the
round trip is pinned.
Three things worth getting right
-
Paths. A path inside the .cfg's own folder is stored relative to it with
forward slashes; anything else is absolute. Relative resolves against the
.cfg's directory, never the working directory, and never escapes the loader:
everything downstream sees an absolute path. This is what makes a case folder
portable, and getting it wrong means silently reading a different file.
-
Tolerant loading. Apply every key you understand and report the rest. A
key nobody knows, a bad boolean, a retired observable label, a file that has
since been deleted: one message each, and the rest of the scenario still
loads. Only the format number is fatal.
-
stepss.format. It is 1. An added optional key is deliberately not a
format bump, because the check refuses a format below the one a build
writes: bumping for a new key would make every build refuse every file
already saved. If the Python side needs to record something the GUI does not,
add a key and leave the number alone.
Not in the file, on purpose
The small-signal parameters, the working directory and the window geometry. A
run does not depend on any of them, and restoring them would change something
the case never asked for. Worth keeping to that if the Python side is tempted
to widen it.
Follow-up
Once both sides read and write it, the format is a contract between two repos
rather than one implementation's private file. It should get a note saying so,
and a shared round-trip case in stepss-test-systems would be the cheapest way
to keep the two honest.
STEPSS GUI already saves and loads a case as a
.cfgscenario file: which datafiles it reads, the disturbance, the one-line diagram, the observables file and
wizard tick, the three run-time observable rows, and the four recording
checkboxes. File > Save configuration writes it and Load configuration
reads it back.
The Python interface expresses the same thing as
stepss.cfg, and builds it incode. So the two interfaces describe an identical object in two formats that
have nothing to do with each other, and a case set up in one cannot be opened
in the other.
What to add
stepss.cfgshould be able to load from, and save to, the GUI's.cfg. A caseset up in the GUI should open in a notebook, and a case built in a notebook
should open in the GUI.
The format
Documented key by key, with a worked example and the rules a hand-written file
has to respect:
https://stepss.sps-lab.org/user-guide/file-formats/#scenario-file-cfg
The reference implementation is
my.stepss.configinstepss-java-ui:ScenarioFileowns the keys and the parsing,Scenariois the data, andScenarioPathsis the relative/absolute rule.ScenarioHarnessis where theround trip is pinned.
Three things worth getting right
Paths. A path inside the
.cfg's own folder is stored relative to it withforward slashes; anything else is absolute. Relative resolves against the
.cfg's directory, never the working directory, and never escapes the loader:everything downstream sees an absolute path. This is what makes a case folder
portable, and getting it wrong means silently reading a different file.
Tolerant loading. Apply every key you understand and report the rest. A
key nobody knows, a bad boolean, a retired observable label, a file that has
since been deleted: one message each, and the rest of the scenario still
loads. Only the format number is fatal.
stepss.format. It is1. An added optional key is deliberately not aformat bump, because the check refuses a format below the one a build
writes: bumping for a new key would make every build refuse every file
already saved. If the Python side needs to record something the GUI does not,
add a key and leave the number alone.
Not in the file, on purpose
The small-signal parameters, the working directory and the window geometry. A
run does not depend on any of them, and restoring them would change something
the case never asked for. Worth keeping to that if the Python side is tempted
to widen it.
Follow-up
Once both sides read and write it, the format is a contract between two repos
rather than one implementation's private file. It should get a note saying so,
and a shared round-trip case in
stepss-test-systemswould be the cheapest wayto keep the two honest.