Scenario Instance Population Parser

Parses a *.sip file (Scenario Instance Population) to yield an initial instance population.

📖 The sip modeling language is fully documented in the project wiki.

Why you need this

Before executing your system models, you need to define an initial population of instances, attribute values, and initial states. In the modeled elevator management (EVMAN) domain for example, you might specify a single Bank with two Shafts and several Floors. Starting off, one of the Shafts might be in service while the other is out of service.

Having set this stage, you can run any number of scenarios against that initial population.

The population is provided as a sip file to this sip parser which generates an AST (abstract syntax tree) as input to some downstream module. For example, the Blueprint popdata module imports the sip parser and passes in your .sip file.

So you don't typically run the sip parser by itself unless you are performing diagnostics or engineering an updated toolchain that doesn't feed into popdata.

Installation

Create or use a python 3.11+ environment. Then

% pip install sip-parser

At this point you can invoke the parser via the command line or from your python script.

From your python script

You need this import statement at a minimum:

from sip_parser.parser import SIParser

You can then specify a path as shown:

result = SIParser.parse_file(file_input=path_to_file, debug=False)

Here result will be a Scenario named tuple holding the scenario name and a dictionary of classes keyed by class name. Each value is a ClassModelPopulation named tuple holding the column header and the population of instance rows. You may find the header of the visitor.py file helpful in interpreting these results, and the Parser output wiki page breaks the whole structure down with examples.

The parser checks syntax only. It never reads the class or state models, so it cannot tell you that a class, attribute or state you named doesn't exist, or that a row is a value short. Those checks belong to whatever consumes the result.

From the command line

This is not the intended usage scenario, but may be helpful for testing or exploration. Since the parser may generate some diagnostic info you may want to create a fresh working directory and cd into it first. From there...

% sip EVMAN_three_bank1.sip

The .sip extension is not necessary, but the file must contain sip text. A successful parse just reports No problemo; anything else raises a parse error naming the line and column where the grammar gave up.

See this repository's wiki for more about the sip language. The grammar is defined in the sip.peg file. (if the link breaks after I do some update to the code, just browse through the code looking for the sip.peg file, and let me know so I can fix it)

You can also specify a debug option like this:

% sip EVMAN_three_bank1.sip -D

This will create a diagnostics folder in your current working directory and deposit a couple of PDFs defining the parse of both the sip grammar: si_model.pdf and your supplied text: si_parse_tree.pdf. These are rendered with graphviz, so you'll need dot on your path to get them.

You should also see a file named SI_parser.log in your current working directory