Assertion¶

class sim_explorer.assertion.Assertion(imports: dict[str, list[str]] | None = None)¶

Bases: object

Defines a common Assertion object for checking expectations with respect to simulation results.

The class uses eval/exec, where the symbols are

the independent variable t (time)
all variables defined as variables in cases file,
functions from any loaded module

These can then be combined to boolean expressions and be checked against single points of a data series (see assert_single() or against a whole series (see assert_series()).

Single assertion expressions are stored in the dict self._expr with their key as given in cases file. All assertions have a common symbol basis in self._symbols. time ‘t’ is pre-registered

Parameters:: imports (dict) – Dictionary of default imports which then can be used in expressions {package : [symbol1, symbol2,…], …}

__init__(imports: dict[str, list[str]] | None = None) → None¶

Methods

`__init__`([imports])
`assertions`(key, *[, res, details, case_name])	Get or set an assertion result.
`description`(key[, descr])	Get or set a description.
`do_assert`(key, result[, case_name])	Perform assert action 'key' on data of 'result' object.
`do_assert_case`(result)	Perform all assertions defined for the case related to the result object.
`eval_series`(-> tuple[int \| float, ...)	Perform assertion on a (time) series.
`eval_single`(key, args, *kwargs)	Perform assertion of 'key' on a single data point.
`expr`(key[, ex])	Get or set an expression.
`expr_get_symbols_functions`(expr)	Get the symbols used in the expression.
`info`(sym[, typ])	Retrieve detailed information related to the registered symbol 'sym'.
`make_locals`(local_ns)	Amend the passed in local namespace with a controlled set of allowed symbols.
`register_vars`(variables)	Register the variables in varnames as symbols.
`report`([case])	Report on all registered asserts.
`symbol`(name)	Get or set a symbol.
`syms`(key)	Get the symbols of the expression 'key'.
`temporal`(key[, typ, args])	Get or set a temporal instruction.

assertions(key: str, *, res: bool | None = None, details: str | None = None, case_name: str | None = None) → dict[str, Any]¶: Get or set an assertion result.

description(key: str, descr: str | None = None) → str¶: Get or set a description.

do_assert(key: str, result: Results, case_name: str | None = None) → bool¶: Perform assert action ‘key’ on data of ‘result’ object.

do_assert_case(result: Results) → list[int]¶: Perform all assertions defined for the case related to the result object.

Perform assertion on a (time) series.

Parameters:

key (str) – Expression identificator
data (tuple) – data table with arguments as columns and series in rows, where the independent variable (normally the time) shall be listed first in each row. All required variables for the evaluation shall be listed (columns) The names of variables correspond to self._syms[key], but is taken as given here.
ret (str) –
Determines how to return the result of the assertion:

float : Linear interpolation of result at the given float time bool : (time, True/False) for first row evaluating to True. bool-list : (times, True/False) for all data points in the series A : Always true for the whole time-series. Same as ‘bool’ F : Eventually True at some point in the time series. Callable : run the given callable on times, expr(data) None : Use the internal ‘temporal(key)’ setting

Results:: tuple of (time(s), value(s)), depending on ret parameter.

eval_single(key: str, *args: Any, **kwargs: Any) → int | float | bool¶

Perform assertion of ‘key’ on a single data point.

Parameters:

key (str) – The identifier of the expression to be evaluated
*args – Positional arguments used in the expression, as a list or tuple.
**kwargs – Keyword arguments used in the expression, as a dict.

Return type:

(bool) result of assertion

expr(key: str, ex: str | None = None) → str | CodeType¶

Get or set an expression.

Parameters:

key (str) – the expression identificator
ex (str) – Optional expression as string. If not None, register/update the expression as key

Returns: the sympified expression

expr_get_symbols_functions(expr: str) → tuple[list[str], list[str]]¶

Get the symbols used in the expression.

Symbol as listed in expression and function body. In general <instant>_<variable>[<index>]
Argument as used in the argument list of the function call. In general <instant>_<variable>
Fully qualified symbol: (<instant>, <variable>, <index>|None)

If there is only a single instance, it is allowed to skip <instant> in 1 and 2

Returns:

where symbols is a dict {<instant>_<variable> : fully-qualified-symbol tuple, …}

functions is a list of functions used in the expression.

Return type:

tuple of (symbols, functions),

info(sym: str, typ: str = 'instance') → str | int¶: Retrieve detailed information related to the registered symbol ‘sym’.

make_locals(local_ns: dict[str, Any]) → dict[str, Any]¶: Amend the passed in local namespace with a controlled set of allowed symbols.

register_vars(variables: dict[str, dict[str, Any]]) → None¶

Can be used directly from Cases with varnames = tuple( Cases.variables.keys())

report(case: Case | None = None) → Iterator[AssertionResult]¶: Report on all registered asserts. If case denotes a case object, only the results for this case are reported.

symbol(name: str) → str¶

Get or set a symbol.

Parameters:

key (str) – The symbol identificator (name)
length (int) – Optional length. 1,2,3 allowed. Vectors are registered as <key>#<index> + <key> for the whole vector

Returns: The symbol name

syms(key: str) → list[str]¶: Get the symbols of the expression ‘key’.

Get or set a temporal instruction.

Parameters:

key (str) – the assert key
typ (str) – optional temporal type