semanticdltl 1.1.0__py3-none-any.whl

dltl/__init__.py

@@ -0,0 +1,39 @@
+# -----------------------------------------------------------------------------
+# SemanticDLTL: a DLTL model checker over finite traces
+#
+# Copyright (C) 2024-2026
+#   Joaquín Ezpeleta, Universidad de Zaragoza, Spain
+#   Javier Fabra, Universidad de Zaragoza, Spain
+#   María José Ibáñez, Universidad de La Rioja, Spain
+# Contact: semanticdltl@unizar.es
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This file is part of SemanticDLTL. It is free software: you can redistribute
+# it and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License,
+# or (at your option) any later version. See the LICENSE file for details.
+#
+# Based on: J. M. Couvreur, J. Ezpeleta, "A Linear Temporal Logic Model
+# Checking Method over Finite Words with Correlated Transition Attributes",
+# SIMPDA 2017, LNBIP vol. 340, Springer, 2019.
+# -----------------------------------------------------------------------------
+"""SemanticDLTL: a model checker for DLTL (data-aware LTL with freeze operators) over finite traces.
+
+Typical use as a library::
+
+    from dltl import Log, Session
+
+    session = Session(Log.load("examples/sample"))
+    session.check_formula('F x.(b & "(x)x[V] == 10")')
+    session.execute("_WRITE")
+"""
+__version__ = "1.1.0"
+
+from dltl.evaluator import Evaluator, results_statistics  # noqa: E402
+from dltl.log import I_ATOM, I_POS, Log  # noqa: E402
+from dltl.parser import parse_formula  # noqa: E402
+from dltl.session import CheckSummary, Session  # noqa: E402
+
+__all__ = ["I_ATOM", "I_POS", "CheckSummary", "Evaluator", "Log", "Session", "parse_formula",
+           "results_statistics", "__version__"]

dltl/__main__.py

@@ -0,0 +1,25 @@
+# -----------------------------------------------------------------------------
+# SemanticDLTL: a DLTL model checker over finite traces
+#
+# Copyright (C) 2024-2026
+#   Joaquín Ezpeleta, Universidad de Zaragoza, Spain
+#   Javier Fabra, Universidad de Zaragoza, Spain
+#   María José Ibáñez, Universidad de La Rioja, Spain
+# Contact: semanticdltl@unizar.es
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This file is part of SemanticDLTL. It is free software: you can redistribute
+# it and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License,
+# or (at your option) any later version. See the LICENSE file for details.
+#
+# Based on: J. M. Couvreur, J. Ezpeleta, "A Linear Temporal Logic Model
+# Checking Method over Finite Words with Correlated Transition Attributes",
+# SIMPDA 2017, LNBIP vol. 340, Springer, 2019.
+# -----------------------------------------------------------------------------
+import sys
+
+from dltl.cli import main
+
+sys.exit(main())

dltl/cli.py

@@ -0,0 +1,181 @@
+# -----------------------------------------------------------------------------
+# SemanticDLTL: a DLTL model checker over finite traces
+#
+# Copyright (C) 2024-2026
+#   Joaquín Ezpeleta, Universidad de Zaragoza, Spain
+#   Javier Fabra, Universidad de Zaragoza, Spain
+#   María José Ibáñez, Universidad de La Rioja, Spain
+# Contact: semanticdltl@unizar.es
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This file is part of SemanticDLTL. It is free software: you can redistribute
+# it and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License,
+# or (at your option) any later version. See the LICENSE file for details.
+#
+# Based on: J. M. Couvreur, J. Ezpeleta, "A Linear Temporal Logic Model
+# Checking Method over Finite Words with Correlated Transition Attributes",
+# SIMPDA 2017, LNBIP vol. 340, Springer, 2019.
+# -----------------------------------------------------------------------------
+"""
+Command-line interface of the model checker.
+
+    dltl-mc --log-file <model> [--init-file F] [--formula-file F]
+            [--no-interactive] [--multi-line] [--propositions F.py]
+
+The legacy ``key=value`` syntax is also accepted:
+
+    python MC.py log-file=<model> init-file=F formula-file=F interactive=false
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import re
+import sys
+import time
+from collections.abc import Iterator
+from types import ModuleType
+from typing import TextIO
+
+from dltl import __version__
+from dltl.log import Log
+from dltl.session import Session
+
+PROMPT = "DLTL -> "
+MULTI_LINE_END = '$'
+
+_LEGACY_ARG = re.compile(
+    r'(log-file|init-file|formula-file|interactive|multi-line|propositions)=(.*)')
+
+
+def normalize_legacy_argv(argv: list[str]) -> list[str]:
+    """Translate ``key=value`` arguments into their ``--key value`` form."""
+    out: list[str] = []
+    for arg in argv:
+        m = _LEGACY_ARG.fullmatch(arg)
+        if not m:
+            out.append(arg)
+            continue
+        key, value = m.groups()
+        if key == 'interactive':
+            out.append('--no-interactive' if value.strip().lower() == 'false' else '--interactive')
+        elif key == 'multi-line':
+            if value.strip().lower() == 'true':
+                out.append('--multi-line')
+        else:
+            out += [f'--{key}', value]
+    return out
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="dltl-mc",
+        description="Model checker for DLTL formulas over the traces of a .mod file.",
+        epilog="The legacy syntax key=value (e.g. log-file=model interactive=false) "
+               "is also accepted.")
+    p.add_argument('--log-file', required=True, metavar='MODEL',
+                   help="trace model, with or without the .mod suffix")
+    p.add_argument('--init-file', metavar='FILE',
+                   help="file with commands executed before reading formulas")
+    p.add_argument('--formula-file', metavar='FILE',
+                   help="file with the formulas to check (default: standard input)")
+    p.add_argument('--propositions', metavar='FILE.py',
+                   help="Python file with the user propositions available as PROP "
+                        "(default: dltl.propositions)")
+    p.add_argument('--interactive', action=argparse.BooleanOptionalAction, default=True,
+                   help="show a prompt when reading formulas from standard input")
+    p.add_argument('--multi-line', action='store_true',
+                   help=f"formulas may span several lines and end with '{MULTI_LINE_END}'")
+    p.add_argument('--version', action='version', version=f"%(prog)s {__version__}")
+    return p
+
+
+# ---------------------------------------------------------------------------
+# input readers
+
+def read_lines(stream: TextIO, prompt: str = "", multi_line: bool = False) -> Iterator[str]:
+    """Yield formulas/commands from ``stream``, one per line or, in multi-line
+    mode, joining lines until one containing ``$``."""
+    buffer: list[str] = []
+    while True:
+        if prompt:
+            print(prompt, end='', flush=True)
+        line = stream.readline()
+        if line == '':  # EOF
+            if buffer:
+                yield ''.join(buffer)
+            if prompt:
+                print("EOF found when reading formula", file=sys.stderr)
+            return
+        line = line.rstrip('\n')
+        if not multi_line:
+            yield line
+        elif MULTI_LINE_END in line:
+            buffer.append(line.split(MULTI_LINE_END)[0])
+            yield ''.join(buffer)
+            buffer = []
+        else:
+            buffer.append(line)
+
+
+def read_file(path: str, multi_line: bool = False) -> Iterator[str]:
+    with open(path) as f:
+        yield from read_lines(f, multi_line=multi_line)
+
+
+def load_propositions(path: str | None) -> ModuleType:
+    if path is None:
+        from dltl import propositions
+        return propositions
+    spec = importlib.util.spec_from_file_location("user_propositions", path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load propositions from '{path}'")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else list(argv)
+    parser = build_parser()
+    if not argv:
+        parser.print_help(sys.stderr)
+        return 2
+    args = parser.parse_args(normalize_legacy_argv(argv))
+
+    for path in (args.init_file, args.formula_file, args.propositions):
+        if path is not None:
+            try:
+                open(path).close()
+            except OSError as e:
+                print(f"Error: cannot read '{path}': {e.strerror}", file=sys.stderr)
+                return 1
+
+    try:
+        props = load_propositions(args.propositions)
+        start = time.time()
+        log = Log.load(args.log_file)
+        loading_time = time.time() - start
+    except (OSError, ValueError, ImportError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    session = Session(log, props)
+    if args.interactive:
+        print(f"Loading time: {loading_time:.4f} seconds")
+    print(log.info())
+
+    if args.init_file and not session.run(read_file(args.init_file)):
+        return 0
+
+    if args.formula_file:
+        lines = read_file(args.formula_file, multi_line=args.multi_line)
+    else:
+        prompt = PROMPT if args.interactive else ""
+        lines = read_lines(sys.stdin, prompt=prompt, multi_line=args.multi_line)
+    session.run(lines)
+    return 0

dltl/evaluator.py

@@ -0,0 +1,393 @@
+# -----------------------------------------------------------------------------
+# SemanticDLTL: a DLTL model checker over finite traces
+#
+# Copyright (C) 2024-2026
+#   Joaquín Ezpeleta, Universidad de Zaragoza, Spain
+#   Javier Fabra, Universidad de Zaragoza, Spain
+#   María José Ibáñez, Universidad de La Rioja, Spain
+# Contact: semanticdltl@unizar.es
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This file is part of SemanticDLTL. It is free software: you can redistribute
+# it and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License,
+# or (at your option) any later version. See the LICENSE file for details.
+#
+# Based on: J. M. Couvreur, J. Ezpeleta, "A Linear Temporal Logic Model
+# Checking Method over Finite Words with Correlated Transition Attributes",
+# SIMPDA 2017, LNBIP vol. 340, Springer, 2019.
+# -----------------------------------------------------------------------------
+"""
+Evaluation of DLTL formulas over a finite trace.
+
+The evaluation is bottom-up and per trace: ``Evaluator.eval_formula`` returns a
+list with one (partially evaluated) node per event, the node at position ``i``
+being the value of the formula at event ``i``. When a formula contains no free
+freeze variables that node is simply ``TRUE()`` or ``FALSE()``.
+
+Model checker based on the DLTL logic and algorithm in:
+    J. M. Couvreur, J. Ezpeleta, "A Linear Temporal Logic Model Checking
+    Method over Finite Words with Correlated Transition Attributes",
+    SIMPDA 2017, LNBIP vol. 340, Springer, 2019.
+"""
+from __future__ import annotations
+
+import re
+import sys
+import traceback
+from types import ModuleType
+from typing import Any
+
+from dltl.formula import AND, FALSE, NOT, OR, TRUE, e1, e2, is_false, is_true, t, v
+from dltl.log import I_ATOM, I_POS
+
+# Name under which the current trace is visible inside data expressions after
+# the freeze variables have been substituted ("x[V]" -> "THE_TRACE[3][V]").
+TRACE_NAME = 'THE_TRACE'
+
+_UNARY_OPS = frozenset({'atom', '!', 'X', 'G', 'F', 'Y', 'H', 'O'})
+_BINARY_OPS = frozenset({'&', '|', 'U', 'S'})
+
+
+class Evaluator:
+    """Evaluates formulas over traces of a given model.
+
+    ``column_index`` maps attribute names to positions in the event tuple (see
+    :class:`dltl.log.Log`), and ``props`` is the module exposed as ``PROP``
+    inside data expressions. Both, together with the current trace, form the
+    namespace in which data expressions are ``eval``'d.
+    """
+
+    def __init__(self, column_index: dict[str, int], props: ModuleType | None = None):
+        if props is None:
+            from dltl import propositions as props
+        self._ns: dict[str, Any] = {**column_index,
+                                    'COL': dict(column_index),
+                                    'I_POS': I_POS,
+                                    'I_ATOM': I_ATOM,
+                                    'PROP': props,
+                                    TRACE_NAME: ()}
+        self._cases = {
+            'X': self.eval_X, 'U': self.eval_U, 'F': self.eval_F, 'G': self.eval_G,
+            'Y': self.eval_Y, 'S': self.eval_S, 'O': self.eval_O, 'H': self.eval_H,
+            'True': self.eval_True_False, 'False': self.eval_True_False,
+            '!': self.eval_Not, '&': self.eval_AND, '|': self.eval_OR,
+            'fvar': self.eval_fvar, 'exp': self.eval_exp, 'atom': self.eval_atom,
+        }
+
+    def add_module(self, name: str, module: ModuleType) -> None:
+        """Make ``module`` available as ``name`` inside data expressions (``_LOAD``)."""
+        self._ns[name] = module
+
+    # ------------------------------------------------------------------
+    def eval_formula(self, exp, trace) -> list:
+        """Evaluate ``exp`` at every event of ``trace``; one node per event."""
+        self._ns[TRACE_NAME] = trace
+        try:
+            return self._cases[exp[t]](exp, trace)
+        except Exception as e:  # noqa: BLE001 - report and keep the session alive
+            print(f"An error occurred: {e}", file=sys.stderr)
+            print("\n--- Full Traceback ---", file=sys.stderr)
+            traceback.print_exc(file=sys.stderr)
+            print("returning FALSE value\n", file=sys.stderr)
+            print("----------------------\n", file=sys.stderr)
+            return [FALSE() for _ in trace]
+
+    def _eval_data(self, expression: str):
+        return eval(expression, self._ns)  # noqa: S307 - data expressions are user code by design
+
+    # ------------------------------------------------------------------
+    def replace(self, traza, i, exp, var):
+        """Substitute freeze variable ``var`` by event ``i`` in ``exp``.
+
+        ``var[#]`` becomes the (1-based) position of the event and any other
+        occurrence of ``var`` becomes ``THE_TRACE[i]``. Data expressions left
+        without free variables are evaluated on the spot.
+        """
+        # everything that depends only on (i, var) is computed once per call
+        var_set = frozenset({var})
+        position = str(i + 1)              # first event position is 1, not 0
+        trace_ref = f"{TRACE_NAME}[{i}]"
+        var_hash = f"{var}[#]"
+        pattern = re.compile(rf'\b{re.escape(var)}\b')
+
+        stack = [(exp, False)]
+        resultMap = {}
+
+        while stack:
+            theForm, visited = stack.pop()
+            form_id = id(theForm)
+            if form_id in resultMap:
+                continue
+
+            vars = theForm[v]
+            op = theForm[t]
+
+            if var not in vars or is_false(theForm) or is_true(theForm):
+                resultMap[form_id] = theForm
+                continue
+
+            if visited:  # descendant results are already in resultMap
+                new_vars = vars - var_set
+                if op in _UNARY_OPS:
+                    resultMap[form_id] = [new_vars, op, resultMap[id(theForm[e1])]]
+                elif op in _BINARY_OPS:
+                    resultMap[form_id] = [new_vars, op,
+                                          resultMap[id(theForm[e1])],
+                                          resultMap[id(theForm[e2])]]
+                elif op == 'fvar':
+                    resultMap[form_id] = [new_vars, op, theForm[e1], resultMap[id(theForm[e2])]]
+                elif op == 'exp':
+                    newFormula = theForm[e1].replace(var_hash, position)
+                    newFormula = pattern.sub(trace_ref, newFormula)
+                    if not new_vars:
+                        resultMap[form_id] = [new_vars, str(self._eval_data(newFormula))]
+                    else:
+                        resultMap[form_id] = [new_vars, op, newFormula]
+            else:
+                # postorder: reinsert with visited=True and process descendants
+                stack.append((theForm, True))
+                if op in _UNARY_OPS:
+                    stack.append((theForm[e1], False))
+                elif op in _BINARY_OPS:
+                    stack.append((theForm[e1], False))
+                    stack.append((theForm[e2], False))
+                elif op == 'fvar':
+                    stack.append((theForm[e2], False))
+
+        return resultMap[id(exp)]
+
+    # ------------------------------------------------------------------
+    def eval_formula_in_event(self, exp, i, traza):
+        """Simplify ``exp`` at event ``i`` as far as its free variables allow."""
+        # (exp, False): children not yet processed
+        # (exp, True): children already resolved and their value stored in resultMap
+        stack = [(exp, False)]
+        resultMap = {}
+
+        while stack:
+            theForm, visited = stack.pop()
+
+            if id(theForm) in resultMap:
+                continue
+
+            vars = theForm[v]
+            op = theForm[t]
+
+            # true or false, or non-evaluable because of the vars
+            if len(vars) != 0 or is_false(theForm) or is_true(theForm):
+                resultMap[id(theForm)] = theForm
+                continue
+
+            if visited:
+                if op == 'exp':
+                    val = theForm[e1]
+                    try:
+                        val_str = str(self._eval_data(str(val)))
+                    except Exception as ex:  # noqa: BLE001
+                        print(f"Eval error in 'exp': {ex}", file=sys.stderr)
+                        val_str = "False"
+                    resultMap[id(theForm)] = [set(), val_str]
+                elif op == 'atom':
+                    resultMap[id(theForm)] = TRUE() if theForm[e1] in traza[i][I_ATOM] else FALSE()
+                elif op == '&':
+                    ev1 = resultMap[id(theForm[e1])]
+                    ev2 = resultMap[id(theForm[e2])]
+                    if is_false(ev1) or is_false(ev2):
+                        resultMap[id(theForm)] = FALSE()
+                    elif is_true(ev1) and is_true(ev2):
+                        resultMap[id(theForm)] = TRUE()
+                    elif is_true(ev1):
+                        resultMap[id(theForm)] = ev2
+                    elif is_true(ev2):
+                        resultMap[id(theForm)] = ev1
+                    else:
+                        resultMap[id(theForm)] = [ev1[0] | ev2[0], '&', ev1, ev2]
+                elif op == '|':
+                    ev1 = resultMap[id(theForm[e1])]
+                    ev2 = resultMap[id(theForm[e2])]
+                    if is_true(ev1) or is_true(ev2):
+                        resultMap[id(theForm)] = TRUE()
+                    elif is_false(ev1):
+                        resultMap[id(theForm)] = ev2
+                    elif is_false(ev2):
+                        resultMap[id(theForm)] = ev1
+                    else:
+                        resultMap[id(theForm)] = [ev1[0] | ev2[0], '|', ev1, ev2]
+                elif op == '!':
+                    ev = resultMap[id(theForm[e1])]
+                    if len(ev[0]) == 0:
+                        resultMap[id(theForm)] = FALSE() if ev[1] == 'True' else TRUE()
+                    else:
+                        resultMap[id(theForm)] = [ev[0], '!', ev]
+                elif op == 'fvar':
+                    new_exp = self.replace(traza, i, theForm[e2], theForm[e1])
+                    stack.append((new_exp, False))
+                    stack.append((theForm, True))  # cannot be resolved yet
+            else:
+                stack.append((theForm, True))
+                # preorder: descendants first
+                if op in {'&', '|'}:
+                    stack.append((theForm[e2], False))
+                    stack.append((theForm[e1], False))
+                elif op == '!':
+                    stack.append((theForm[e1], False))
+                # 'fvar' is handled in the post-processing step; 'atom'/'exp' have no children
+
+        return resultMap[id(exp)]
+
+    # ------------------------------------------------------------------
+    # future operators
+    def eval_X(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        # "X false" is the idiom for "last event": it holds only there
+        res[n - 1] = TRUE() if is_false(exp[e1]) else FALSE()
+        eval_exp = self.eval_formula(exp[e1], traza)
+        for i in reversed(range(n - 1)):
+            res[i] = eval_exp[i + 1]
+        return res
+
+    def eval_U(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        res_f = self.eval_formula(exp[e1], traza)
+        res_g = self.eval_formula(exp[e2], traza)
+        res[n - 1] = res_g[n - 1]
+        for i in reversed(range(n - 1)):
+            res[i] = self.eval_formula_in_event(
+                OR(res_g[i], AND(res_f[i], res[i + 1])), i, traza)
+        return res
+
+    def eval_F(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        res_parcial = self.eval_formula(exp[e1], traza)
+        res[n - 1] = self.eval_formula_in_event(res_parcial[n - 1], n - 1, traza)
+        already_true = is_true(res[n - 1])
+        for i in reversed(range(n - 1)):
+            if already_true:  # F f holds at i+1, hence at every earlier event
+                res[i] = TRUE()
+            else:
+                res[i] = self.eval_formula_in_event(OR(res_parcial[i], res[i + 1]), i, traza)
+                already_true = is_true(res[i])
+        return res
+
+    def eval_G(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        res_parcial = self.eval_formula(exp[e1], traza)
+        res[n - 1] = self.eval_formula_in_event(res_parcial[n - 1], n - 1, traza)
+        already_false = is_false(res[n - 1])
+        for i in reversed(range(n - 1)):
+            if already_false:  # G f fails at i+1, hence at every earlier event
+                res[i] = FALSE()
+            else:
+                res[i] = self.eval_formula_in_event(AND(res_parcial[i], res[i + 1]), i, traza)
+                already_false = is_false(res[i])
+        return res
+
+    # past operators
+    def eval_Y(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        # "Y false" is the idiom for "first event": it holds only there
+        res[0] = TRUE() if is_false(exp[e1]) else FALSE()
+        res_exp = self.eval_formula(exp[e1], traza)
+        for i in range(1, n):
+            res[i] = res_exp[i - 1]
+        return res
+
+    def eval_S(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        res_f = self.eval_formula(exp[e1], traza)
+        res_g = self.eval_formula(exp[e2], traza)
+        res[0] = res_g[0]
+        for i in range(1, n):
+            res[i] = self.eval_formula_in_event(
+                OR(res_g[i], AND(res_f[i], res[i - 1])), i, traza)
+        return res
+
+    def eval_O(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        res_f = self.eval_formula(exp[e1], traza)
+        res[0] = self.eval_formula_in_event(res_f[0], 0, traza)
+        already_true = is_true(res[0])
+        for i in range(1, n):
+            if already_true:  # O f holds at i-1, hence at every later event
+                res[i] = TRUE()
+            else:
+                res[i] = self.eval_formula_in_event(OR(res_f[i], res[i - 1]), i, traza)
+                already_true = is_true(res[i])
+        return res
+
+    def eval_H(self, exp, traza):
+        n = len(traza)
+        res = [None] * n
+        res_f = self.eval_formula(exp[e1], traza)
+        res[0] = self.eval_formula_in_event(res_f[0], 0, traza)
+        already_false = is_false(res[0])
+        for i in range(1, n):
+            if already_false:  # H f fails at i-1, hence at every later event
+                res[i] = FALSE()
+            else:
+                res[i] = self.eval_formula_in_event(AND(res_f[i], res[i - 1]), i, traza)
+                already_false = is_false(res[i])
+        return res
+
+    # propositional operators and leaves
+    def eval_True_False(self, exp, traza):
+        return [[set(), exp[t]] for _ in traza]
+
+    def eval_Not(self, exp, traza):
+        res_f = self.eval_formula(exp[e1], traza)
+        return [self.eval_formula_in_event(NOT(res_f[i]), i, traza) for i in range(len(traza))]
+
+    def eval_AND(self, exp, traza):
+        res_f1 = self.eval_formula(exp[e1], traza)
+        res_f2 = self.eval_formula(exp[e2], traza)
+        return [self.eval_formula_in_event(
+                    [res_f1[i][0] | res_f2[i][0], '&', res_f1[i], res_f2[i]], i, traza)
+                for i in range(len(traza))]
+
+    def eval_OR(self, exp, traza):
+        res_f1 = self.eval_formula(exp[e1], traza)
+        res_f2 = self.eval_formula(exp[e2], traza)
+        return [self.eval_formula_in_event(
+                    [res_f1[i][0] | res_f2[i][0], '|', res_f1[i], res_f2[i]], i, traza)
+                for i in range(len(traza))]
+
+    def eval_fvar(self, exp, traza):
+        n = len(traza)
+        freezeVar = exp[e1]
+        newRow = self.eval_formula(exp[e2], traza)
+        newRow = [self.replace(newRow, i, newRow[i], freezeVar) for i in range(n)]
+        return [self.eval_formula_in_event(newRow[i], i, traza) for i in range(n)]
+
+    def eval_exp(self, exp, traza):
+        return [self.eval_formula_in_event(exp, i, traza) for i in range(len(traza))]
+
+    def eval_atom(self, exp, traza):
+        return [TRUE() if exp[e1] in event[I_ATOM] else FALSE() for event in traza]
+
+
+# ---------------------------------------------------------------------------
+
+def results_statistics(res) -> tuple[int, int, int, float]:
+    """Summarise the per-event results of a formula over one trace.
+
+    Returns ``(holds, true_count, false_count, ratio)`` where ``holds`` is 1
+    when the formula is true at the first event (the classic model checking
+    answer) and ``ratio`` is the fraction of events where it is true.
+
+    Raises ``ValueError`` if some event was left with an unresolved node.
+    """
+    n = len(res)
+    trueCount = sum(1 for r in res if is_true(r))
+    falseCount = sum(1 for r in res if is_false(r))
+    if trueCount + falseCount != n:
+        raise ValueError(f"unresolved evaluation: {trueCount + falseCount} != {n}")
+    return (1 if is_true(res[0]) else 0), trueCount, falseCount, trueCount / n