Case

class sim_explorer.case.Case(cases: Cases, name: str, spec: dict[str, Any], special: dict[str, Any] | None = None)

Bases: object

Instantiation of a Case object. Sub-cases are strored ins list ‘self.subs’. Parent case is stored as ‘self.parent’ (None for ‘base’). The Cases object is registered as ‘self.cases’ and registers the unique case ‘self.base’.

Parameters:

• cases (Cases) – Reference to the related Cases object

• name (str) – Unique name of the case

• spec (dict) – the dictionary of the case specification

__init__(cases: Cases, name: str, spec: dict[str, Any], special: dict[str, Any] | None = None) → None

Methods

__init__(cases, name, spec[, special])
add_results_object(res)
append(case)	Append a case as sub-case to this case.
case_by_name(name)	Find the case 'name' within sub-hierarchy of this case.
iter()	Construct an iterator, allowing iteration from base case to this case through the hierarchy.
list_cases(*[, as_name, flat])	List this case and all sub-cases recursively, as name or case objects.
read_assertion(key[, expr_descr])	Read an assert statement, compile as sympy expression, register and store the key..
read_spec_item(key[, value])	Use the alias variable information (key) and the value to construct an action function, which is run when this variable is set/read.
run([dump])	Set up case and run it.

add_results_object(res: Results) → None

append(case: Case) → None

Append a case as sub-case to this case.

case_by_name(name: str) → Case | None

Find the case ‘name’ within sub-hierarchy of this case. Return None if not found.

Parameters:

name (str) – the case name to find

Returns:

The case object or None

iter() → Generator[Case, None, None]

Construct an iterator, allowing iteration from base case to this case through the hierarchy.

list_cases(*, as_name: bool = True, flat: bool = False) → list[str] | list[str | list[str]] | list[Case] | list[Case | list[Case]]

List this case and all sub-cases recursively, as name or case objects.

read_assertion(key: str, expr_descr: list[str] | None = None) → str

Read an assert statement, compile as sympy expression, register and store the key..

Parameters:

• key (str) – Identification key for the assertion. Should be unique. Recommended to use numbers

• specifications (Also assertion keys can have temporal) –

  • @A : The expression is expected to be Always (globally) true

  • @F : The expression is expected to be true during the end of the simulation

  • @<val> or @T<val>: The expression is expected to be true at the specific time value

• expr – A python expression using available variables

read_spec_item(key: str, value: Any | None = None) → None

Use the alias variable information (key) and the value to construct an action function, which is run when this variable is set/read.

In the simplest case, the key is a cases variable name. Optionally two elements can be added:

1. a range, denoted by [range-spec] : choosing elements of a multi-valued variable. Note: when disecting the key, the actual length of the case variable is unknown, such that checks are limited. Rules:

   • no ‘[]’: addresses always the whole variable - scalar or multi-valued. rng = ‘’

   • ‘[int]’: addresses a single element of a multi-valued variable. rng = ‘int’

   • ‘[int,int, …]’: addresses several elements of a multi-valued variable. rng = ‘int,int,…’

   • ‘[int…int]’: addresses a range of elements of a multi-valued variable. rng = ‘int:int’, i.e. a slice

2. a time specification, denoted by @time-spec : action performed at specified time. Rules:

   • no ‘@’: set actions are performed initially. get actions are performed at end of simulation (record final value)

   • @float: set/get action perfomred at specified time

   • @step optional-time-spec: Not allowed for set actions. Get actions performed at every communication point (no time-spec), or at time-spec time intervals

Note: ‘Get’ actions can be specified in a few ways:

1. All case settings are automatically reported at start time and do not need to be specified.

2. Within a ‘results’ section of a case (use the base case to get the same recordings for all cases). The results variables specification must be a list and must be explicit strings to conform to Json5.

3. Usage of a normal variable specification as for ‘set’, but specifying the keyword ‘result’ or ‘res’ as value: ‘keep the value but record the variable’.

Parameters:

• key (str) – the key of the spec item

• value (Any]) – the values with respect to the item. For ‘results’ this is not used

Return type:

updated self.act_*** actions through add_actions() of the SystemInterface***

run(dump: str | None = '') → None

Set up case and run it.

All get action are recorded in results and get actions always concern whole case variables. It is difficult to report initial settings. Therefore all start values are collected, changed with initial settings (settings before the main simulation loop) and reported.

Parameters:

dump (str) – Optionally save the results as json file. None: do not save, ‘’: use default file name, str (with or without ‘.js5’): save with that file name