flamapy-bdd 2.6.0.dev11__tar.gz → 2.9.0.dev0__tar.gz

flamapy_bdd-2.9.0.dev0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: flamapy-bdd
+Version: 2.9.0.dev0
+Summary: bdd-plugin for the automated analysis of feature models
+Author-email: Flamapy <flamapy@us.es>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/flamapy/bdd_metamodel
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flamapy-fw~=2.9.0.dev0
+Requires-Dist: flamapy-fm~=2.9.0.dev0
+Requires-Dist: dd~=0.6.0
+Requires-Dist: graphviz~=0.20
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: prospector; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: flamapy-sat~=2.9.0.dev0; extra == "test"
+Dynamic: license-file
+
+# flamapy-bdd
+
+BDD-based analysis for [flamapy](https://flamapy.org) feature models, built on
+the [dd](https://github.com/tulip-control/dd) library.
+
+**Documentation:** https://docs.flamapy.org/framework/plugins/bdd_plugin
+
+## Installation
+
+```bash
+pip install flamapy-bdd
+```
+
+`pip install dd` provides dd's pure-Python engine. For larger models, build dd against
+[CUDD](https://github.com/ivmai/cudd), which is much faster and enables dynamic variable
+reordering:
+
+```bash
+pip install cython
+DD_FETCH=1 DD_CUDD=1 pip install --force-reinstall --no-deps --no-build-isolation --no-binary dd "dd==0.6.0"
+```
+
+## How the BDD is built
+
+`FmToBDD` conjoins the clauses of the feature model one at a time over a static
+variable order inspired by Logic2BDD. With the CUDD engine it also reorders variables
+dynamically while building. Every option can be passed to `FmToBDD(...)` or set with an
+environment variable; explicit arguments take precedence.
+
+| Option | Environment variable | Values (default first) |
+|--------|----------------------|------------------------|
+| `builder` | `FLAMAPY_BDD_BUILDER` | `python`; `native` and `auto` are experimental and need a native package that is not released yet |
+| `build` | `FLAMAPY_BDD_BUILD` | `incremental`, `monolithic` (the whole formula at once) |
+| `var_order` | `FLAMAPY_BDD_VAR_ORDER` | `tree` (feature-tree pre-order), `force` (FORCE heuristic), `model` |
+| `clause_order` | `FLAMAPY_BDD_CLAUSE_ORDER` | `minspan`, `minmax`, `model` |
+| `reorder` | `FLAMAPY_BDD_REORDER` | `auto` (on with CUDD, off otherwise), `1`, `0` |
+
+The options only change how the BDD is built, never the configurations it represents.
+
+With dd's pure-Python engine, building and walking a BDD recurses once per variable, so the
+plugin raises Python's recursion limit (to about 1,000 + 4 per variable) when it builds or loads
+a BDD. The limit applies to the whole process and is not lowered afterwards, because the
+operations on the BDD need it too; keep it in mind when flamapy-bdd runs inside a server or in
+Pyodide. See
+`flamapy/metamodels/bdd_metamodel/models/utils/ordering.py` and `benchmarks/`.

flamapy_bdd-2.9.0.dev0/README.md

@@ -0,0 +1,45 @@
+# flamapy-bdd
+
+BDD-based analysis for [flamapy](https://flamapy.org) feature models, built on
+the [dd](https://github.com/tulip-control/dd) library.
+
+**Documentation:** https://docs.flamapy.org/framework/plugins/bdd_plugin
+
+## Installation
+
+```bash
+pip install flamapy-bdd
+```
+
+`pip install dd` provides dd's pure-Python engine. For larger models, build dd against
+[CUDD](https://github.com/ivmai/cudd), which is much faster and enables dynamic variable
+reordering:
+
+```bash
+pip install cython
+DD_FETCH=1 DD_CUDD=1 pip install --force-reinstall --no-deps --no-build-isolation --no-binary dd "dd==0.6.0"
+```
+
+## How the BDD is built
+
+`FmToBDD` conjoins the clauses of the feature model one at a time over a static
+variable order inspired by Logic2BDD. With the CUDD engine it also reorders variables
+dynamically while building. Every option can be passed to `FmToBDD(...)` or set with an
+environment variable; explicit arguments take precedence.
+
+| Option | Environment variable | Values (default first) |
+|--------|----------------------|------------------------|
+| `builder` | `FLAMAPY_BDD_BUILDER` | `python`; `native` and `auto` are experimental and need a native package that is not released yet |
+| `build` | `FLAMAPY_BDD_BUILD` | `incremental`, `monolithic` (the whole formula at once) |
+| `var_order` | `FLAMAPY_BDD_VAR_ORDER` | `tree` (feature-tree pre-order), `force` (FORCE heuristic), `model` |
+| `clause_order` | `FLAMAPY_BDD_CLAUSE_ORDER` | `minspan`, `minmax`, `model` |
+| `reorder` | `FLAMAPY_BDD_REORDER` | `auto` (on with CUDD, off otherwise), `1`, `0` |
+
+The options only change how the BDD is built, never the configurations it represents.
+
+With dd's pure-Python engine, building and walking a BDD recurses once per variable, so the
+plugin raises Python's recursion limit (to about 1,000 + 4 per variable) when it builds or loads
+a BDD. The limit applies to the whole process and is not lowered afterwards, because the
+operations on the BDD need it too; keep it in mind when flamapy-bdd runs inside a server or in
+Pyodide. See
+`flamapy/metamodels/bdd_metamodel/models/utils/ordering.py` and `benchmarks/`.

flamapy_bdd-2.9.0.dev0/flamapy/metamodels/bdd_metamodel/__init__.py

@@ -0,0 +1,49 @@
+from flamapy.core.manifest import OperationCapability, PluginManifest
+from flamapy.core.models.language_level import LanguageLevel, MajorLevel, MinorLevel
+
+# Costs are estimated milliseconds from the 2026-11-06 calibration with the pure-Python dd
+# engine (what 2.9 ships): betty synthetic models at 1% and 30% constraint density plus
+# JHipster and busybox, worst case of the two densities, never decreasing. Compiling the BDD is
+# the wall, and it is erratic: 0.2 s for both 200-feature models, 0.4 s for the sparse
+# 500-feature model but more than 5 minutes for the dense one, 1.7 s / 32 s at 1,000, and
+# busybox (1,108 features) did not compile in 10 minutes. The journal benchmark with the same
+# engine (300 s cap, real UVLHub models) compiled 29 of 41 models of 501-1,000 features and 2
+# of 120 beyond, hence the 1,000-feature ceiling. Once compiled, every query is cheap (counting
+# 29 ms, core/dead 140 ms, false-optional 300 ms at 1,000 features). The experimental native
+# builder (flamapy-cudd, not released) is opt-in and not reflected here.
+_MAX_FEATURES = 1000
+
+MANIFEST = PluginManifest(
+    name='bdd',
+    calibration='2026-11-06',
+    extension='bdd',
+    supported_level=LanguageLevel(MajorLevel.BOOLEAN, {MinorLevel.GROUP_CARDINALITY}),
+    # Every operation needs the compiled BDD, so the ceiling is plugin-wide.
+    max_features=_MAX_FEATURES,
+    transformation_cost_curve=((50, 11), (100, 23), (200, 200), (1000, 300000)),
+    operations={
+        'satisfiable': OperationCapability(cost=1),
+        'satisfiable_configuration': OperationCapability(cost=1),
+        'configurations_number': OperationCapability(
+            cost_curve=((100, 1), (200, 4), (500, 9), (1000, 29))),
+        # Two counts: all the products and those that include the configuration.
+        'commonality': OperationCapability(
+            cost_curve=((100, 2), (200, 8), (500, 18), (1000, 58))),
+        'core_features': OperationCapability(
+            cost_curve=((100, 1), (200, 20), (500, 33), (1000, 130))),
+        'dead_features': OperationCapability(
+            cost_curve=((100, 1), (200, 20), (500, 30), (1000, 140))),
+        'false_optional_features': OperationCapability(
+            cost_curve=((50, 2), (100, 3), (200, 42), (500, 72), (1000, 300))),
+        # Uniform random sampling over the compiled BDD.
+        'sampling': OperationCapability(
+            cost_curve=((50, 2), (100, 3), (200, 29), (500, 57), (1000, 200))),
+        # Listing is bounded by the number of configurations, not by the BDD: about 3 us and
+        # 1 KB per configuration (measured 2026-11-08 on 16 UVLHub models of 1e3-1.5e6
+        # configurations), so a million already takes ~1 GB. Using the exact counts of the SoSyM
+        # benchmark (rq2_bdd_final), the share of UVLHub models with at most a million
+        # configurations is 100% up to 30 features, 76% at 31-50, 36% at 51-75 and under 25%
+        # beyond; with the same ~70% rule as the compilation ceiling, the limit is 50 features.
+        'configurations': OperationCapability(max_features=50),
+    },
+)

{flamapy_bdd-2.6.0.dev11 → flamapy_bdd-2.9.0.dev0}/flamapy/metamodels/bdd_metamodel/models/bdd_model.py

@@ -1,6 +1,8 @@
+import importlib
 import logging
+import sys
 from enum import Enum
-from typing import Any, Optional
+from typing import Any, Iterable, Optional
 
 try:
     from dd.cudd import BDD
@@ -11,6 +13,77 @@ from flamapy.core.models import VariabilityModel
 
 logger = logging.getLogger(__name__)
 
+# The dd engine in use: 'cudd' (C extension, only when dd is built against CUDD) or the
+# pure-Python 'autoref' that a plain `pip install dd` provides.
+DD_BACKEND = BDD.__module__.rsplit('.', 1)[-1]
+_reorder = importlib.import_module(BDD.__module__).reorder  # sifting, in both engines
+
+# Dynamic reordering while building (see BDDModel.build_bdd_incremental): sift once the
+# manager holds REORDER_MIN_NODES nodes, then again each time it grows by REORDER_GROWTH
+# since the last reordering. Small BDDs are never reordered: sifting thousands of variables
+# costs more than it saves on a BDD that stays small.
+REORDER_MIN_NODES = 50_000
+REORDER_GROWTH = 2.0
+
+# The pure-Python engine recurses once per BDD level (and the node-walking operations too),
+# so Python's recursion limit must grow with the number of variables.
+_RECURSION_BASE = 1_000
+_RECURSION_PER_VARIABLE = 4
+
+
+def exact_count(bdd: Any, node: Any, nvars: int) -> int:
+    """Exact model count of `node` over `nvars` variables, with Python integers.
+
+    Works on any dd engine with complement edges: the nodes of the support are counted
+    bottom-up (without recursion) over the levels of the support, and the variables outside
+    the support double the count.
+    """
+    def regular(edge: Any) -> Any:
+        return ~edge if edge.negated else edge
+
+    nodes: list[Any] = []
+    seen: set[Any] = set()
+    top = regular(node)
+    stack = [top] if top.var is not None else []
+    while stack:
+        current = stack.pop()
+        if current in seen:
+            continue
+        seen.add(current)
+        nodes.append(current)
+        for edge in (current.low, current.high):
+            child = regular(edge)
+            if child.var is not None and child not in seen:
+                stack.append(child)
+    level = {var: bdd.level_of_var(var) for var in {n.var for n in nodes}}
+    rank = {var: i for i, var in enumerate(sorted(level, key=level.__getitem__))}
+    n_support = len(rank)
+    counts: dict[Any, int] = {}
+
+    def edge_count(edge: Any, parent_rank: int) -> int:
+        """Models of `edge` over the support variables below `parent_rank`."""
+        if edge.var is None:
+            value, child_rank = (0 if edge.negated else 1), n_support
+        else:
+            child_rank = rank[edge.var]
+            value = counts[regular(edge)]
+            if edge.negated:
+                value = 2 ** (n_support - child_rank) - value
+        return value * 2 ** (child_rank - parent_rank - 1)
+
+    for current in sorted(nodes, key=lambda n: rank[n.var], reverse=True):
+        current_rank = rank[current.var]
+        counts[current] = (edge_count(current.low, current_rank)
+                           + edge_count(current.high, current_rank))
+    return edge_count(node, -1) * 2 ** max(nvars - n_support, 0)
+
+
+def ensure_recursion_limit(n_variables: int) -> None:
+    """Raise Python's recursion limit, if needed, for BDDs over `n_variables` variables."""
+    needed = _RECURSION_BASE + _RECURSION_PER_VARIABLE * n_variables
+    if sys.getrecursionlimit() < needed:
+        sys.setrecursionlimit(needed)
+
 
 class BDDModel(VariabilityModel):
     """A Binary Decision Diagram (BDD) representation of the feature model.
@@ -39,12 +112,43 @@ class BDDModel(VariabilityModel):
 
     def build_bdd(self, expression: str, variables: list[str]) -> None:
         """Built a BDD from an expression representing a logical formula."""
+        ensure_recursion_limit(len(variables))
         self.bdd.configure(reordering=False)  # Disable dynamic reordering for consistency
         for var in variables:
             self.bdd.declare(var)  # Declare variables in the BDD manager
         self.vars_order = variables  # The order is crucial to detect skipped variables
         self.root = self.bdd.add_expr(expression)  # Build the logical formula (root node)
 
+    def build_bdd_incremental(self,
+                              clauses: Iterable[str],
+                              variables: list[str],
+                              reorder: bool = False) -> None:
+        """Build a BDD as the conjunction of `clauses`, one clause at a time.
+
+        The variables are declared in the given order (the first one is the top level).
+        Conjoining clause by clause keeps the intermediate BDDs small when the clauses are
+        scheduled well, instead of parsing one huge expression. With `reorder`, the variables
+        are sifted between clauses when the BDD grows (REORDER_MIN_NODES, REORDER_GROWTH);
+        the engine's own automatic reordering stays disabled so that levels never change in
+        the middle of an operation, and `vars_order` is set to the final level order.
+        """
+        ensure_recursion_limit(len(variables))
+        self.bdd.configure(reordering=False)
+        for var in variables:
+            self.bdd.declare(var)
+        threshold = REORDER_MIN_NODES
+        root = self.bdd.true
+        for clause in clauses:
+            root = root & self.bdd.add_expr(clause)
+            if root == self.bdd.false:
+                break  # The model is void: further clauses cannot change the result
+            if reorder and len(self.bdd) >= threshold:
+                _reorder(self.bdd)
+                threshold = max(REORDER_MIN_NODES, int(REORDER_GROWTH * len(self.bdd)))
+        self.root = root
+        # Operations rely on vars_order[i] being the variable at level i.
+        self.vars_order = sorted(variables, key=self.bdd.level_of_var)
+
     def get_expression(self) -> str:
         """ Converts the BDD to a readable Boolean expression string."""
         return self.bdd.to_expr(self.root)
@@ -55,7 +159,19 @@ class BDDModel(VariabilityModel):
 
     def count_solutions(self) -> int:
         """Count the number of valid configurations (SAT)."""
-        return self.bdd.count(self.root, len(self.vars_order))  # count(node, n_vars)
+        return self.count_models(self.root, len(self.vars_order))
+
+    def count_models(self, node: Any, nvars: int) -> int:
+        """Exact number of assignments of `nvars` variables (a superset of the support of
+        `node`) that satisfy `node`.
+
+        dd's pure-Python engine counts with Python integers; the CUDD engine counts with
+        floating point, which is approximate beyond 2**53 and overflows beyond ~1e308, so for
+        CUDD the count is computed here with integers.
+        """
+        if DD_BACKEND != "cudd":
+            return int(self.bdd.count(node, nvars))
+        return exact_count(self.bdd, node, nvars)
 
     def dump_structure(self) -> None:
         """Prints the structure of the BDD for debugging purposes."""
@@ -102,6 +218,7 @@ class BDDModel(VariabilityModel):
     def load_bdd(path: str, vars: Optional[list[str]] = None) -> 'BDDModel':
         bdd_model = BDDModel()
         if vars is not None:
+            ensure_recursion_limit(len(vars))
             for var in vars:
                 bdd_model.bdd.declare(var)
         roots = bdd_model.bdd.load(path)
@@ -112,6 +229,7 @@ class BDDModel(VariabilityModel):
         else:
             bdd_model.root = roots
         all_vars = list(bdd_model.bdd.vars)
+        ensure_recursion_limit(len(all_vars))
         sorted_vars = sorted(all_vars, key=bdd_model.bdd.level_of_var)
         bdd_model.vars_order = sorted_vars
         bdd_model.vars_features = {var: var for var in bdd_model.vars_order}

flamapy_bdd-2.9.0.dev0/flamapy/metamodels/bdd_metamodel/models/utils/logic2bdd_writer.py

@@ -0,0 +1,125 @@
+"""Write a feature model as Logic2BDD input (a variable file and an expression file).
+
+Logic2BDD (D. Fernández-Amorós, UNED) reads the variables, one order, from the variable file
+and one constraint per line from the expression file. Its grammar has some traps that this
+writer avoids:
+
+* `<->` binds tighter than `and`/`or`, so every binary operation is written in parentheses.
+* Operators must be separated by spaces (`a->b` would be read as one symbol).
+* `and`, `or`, `not`, `xor`, `mux`, `if`... are keywords, so variables are written with
+  neutral names (`v0`, `v1`, ...) and the mapping to the real names is returned.
+* Every line, the last one included, ends with a newline and there are no blank lines.
+
+Groups use Logic2BDD's n-ary operators: `mux(...)` (at most one) for alternative and mutex
+groups, which CUDD builds directly instead of from pairwise clauses.
+"""
+import itertools
+from dataclasses import dataclass, field
+
+from flamapy.core.models.ast import ASTOperation, Node
+from flamapy.metamodels.fm_metamodel.models import Constraint, FeatureModel, Relation
+
+
+@dataclass
+class Logic2BDDInput:
+    """Logic2BDD input files and the mapping between their names and the variables."""
+    variables: list[str]                     # variable names (the model's), in order
+    names: dict[str, str]                    # Logic2BDD name -> variable name
+    expressions: list[str] = field(default_factory=list)
+
+    @property
+    def var_text(self) -> str:
+        to_l2b = {var: name for name, var in self.names.items()}
+        return " ".join(to_l2b[var] for var in self.variables) + "\n"
+
+    @property
+    def exp_text(self) -> str:
+        return "".join(f"{line}\n" for line in self.expressions)
+
+
+def feature_model_to_logic2bdd(feature_model: FeatureModel,
+                               order: list[str]) -> Logic2BDDInput:
+    """Translate `feature_model` (with sanitized names) using the variable order `order`."""
+    names = {f"v{index}": var for index, var in enumerate(order)}
+    to_l2b = {var: name for name, var in names.items()}
+    result = Logic2BDDInput(variables=list(order), names=names)
+    if feature_model.root is None:
+        return result
+    result.expressions.append(to_l2b[feature_model.root.name])
+    for feature in feature_model.get_features():
+        for relation in feature.get_relations():
+            result.expressions.extend(_relation_lines(relation, to_l2b))
+    for constraint in feature_model.get_logical_constraints():
+        result.expressions.append(_constraint_line(constraint, to_l2b))
+    return result
+
+
+def _or(items: list[str]) -> str:
+    return items[0] if len(items) == 1 else "(" + " or ".join(items) + ")"
+
+
+def _relation_lines(relation: Relation, to_l2b: dict[str, str]) -> list[str]:
+    parent = to_l2b[relation.parent.name]
+    children = list(dict.fromkeys(to_l2b[child.name] for child in relation.children))
+    at_most_one = [f"mux({', '.join(children)})"] if len(children) > 1 else []
+    lines: list[str] = []
+    if relation.is_mandatory():
+        lines = [f"({parent} <-> {children[0]})"]
+    elif relation.is_optional():
+        lines = [f"({children[0]} -> {parent})"]
+    elif relation.is_or():
+        lines = [f"({parent} <-> {_or(children)})"]
+    elif relation.is_alternative():
+        lines = [f"({parent} <-> {_or(children)})", *at_most_one]
+    elif relation.is_mutex():
+        lines = [*(f"({child} -> {parent})" for child in children), *at_most_one]
+    elif relation.is_cardinal():
+        lines = _cardinality_lines(parent, children, relation.card_min, relation.card_max)
+    return lines
+
+
+def _cardinality_lines(parent: str, children: list[str], card_min: int,
+                       card_max: int) -> list[str]:
+    """The same constraints as PLModel, not the same clauses: every selection outside
+    [min, max] under the parent is forbidden, and "no child without its parent" is one
+    ``child -> parent`` line per child where PLModel enumerates the subsets."""
+    card_max = len(children) if card_max == -1 else card_max
+    lines = [f"({child} -> {parent})" for child in children]
+    for size in range(len(children) + 1):
+        if card_min <= size <= card_max:
+            continue
+        for selected in itertools.combinations(children, size):
+            literals = [f"(not {parent})"]
+            literals += [f"(not {child})" if child in selected else child for child in children]
+            lines.append(_or(literals))
+    return lines
+
+
+_BINARY = {
+    ASTOperation.AND: "and",
+    ASTOperation.OR: "or",
+    ASTOperation.IMPLIES: "->",
+    ASTOperation.REQUIRES: "->",
+    ASTOperation.EQUIVALENCE: "<->",
+}
+
+
+def _constraint_line(constraint: Constraint, to_l2b: dict[str, str]) -> str:
+    return _node_text(constraint.ast.root, to_l2b)
+
+
+def _node_text(node: Node, to_l2b: dict[str, str]) -> str:
+    if not node.is_op():
+        return to_l2b[str(node.data)]
+    operation = node.data
+    if operation == ASTOperation.NOT:
+        return f"(not {_node_text(node.left, to_l2b)})"
+    left = _node_text(node.left, to_l2b)
+    right = _node_text(node.right, to_l2b)
+    if operation == ASTOperation.EXCLUDES:
+        return f"({left} -> (not {right}))"
+    if operation == ASTOperation.XOR:
+        return f"(({left} or {right}) and (not ({left} and {right})))"
+    if operation in _BINARY:
+        return f"({left} {_BINARY[operation]} {right})"
+    raise ValueError(f"Operation {operation} is not supported by Logic2BDD.")

flamapy_bdd-2.9.0.dev0/flamapy/metamodels/bdd_metamodel/models/utils/ordering.py

@@ -0,0 +1,130 @@
+"""Static variable orders and clause schedules for building a BDD clause by clause.
+
+The size of a BDD depends heavily on the variable order, and the cost of building it
+clause by clause depends on the order in which clauses are conjoined. These heuristics follow
+the ideas of Logic2BDD (D. Fernández-Amorós, R. Heradio et al.) adapted to feature models:
+
+Variable orders
+    ``model``  the order of `FeatureModel.get_features()`.
+    ``tree``   depth-first pre-order of the feature tree (a feature followed by its subtree).
+    ``force``  the FORCE hypergraph heuristic (Aloul, Markov and Sakallah, 2003), seeded with
+               the tree order: variables that share clauses are pulled together, which shortens
+               the span of cross-tree constraints.
+
+Clause schedules
+    ``model``    the order in which the clauses were generated.
+    ``minspan``  clauses with a smaller span (distance between their first and last variable
+                 in the order) first; ties broken by the position of their first variable.
+    ``minmax``   clauses whose deepest variable is higher in the order first.
+
+All functions are pure and deterministic: the same inputs always give the same result.
+"""
+from typing import Sequence
+
+from flamapy.core.exceptions import FlamaException
+from flamapy.metamodels.bdd_metamodel.models.utils.pl_model import PLClause
+
+
+class BDDOptionError(FlamaException, ValueError):
+    """An invalid BDD build option (argument or FLAMAPY_BDD_* variable). A FlamaException like
+    every other invalid transformation option; also a ValueError, as it was before 2.9."""
+
+
+VARIABLE_ORDERS = ("model", "tree", "force")
+CLAUSE_ORDERS = ("model", "minspan", "minmax")
+
+FORCE_MAX_ITERATIONS = 50
+
+
+def variable_order(variables: Sequence[str],
+                   clauses: Sequence[PLClause],
+                   strategy: str = "tree",
+                   model_order: Sequence[str] = ()) -> list[str]:
+    """Return the variables in the order given by `strategy`.
+
+    `variables` must be in feature-tree pre-order (as `PLModel.variables`); `model_order` is
+    only used by the ``model`` strategy.
+    """
+    if strategy == "tree":
+        return list(variables)
+    if strategy == "model":
+        ordered = [var for var in model_order if var in set(variables)]
+        seen = set(ordered)
+        return ordered + [var for var in variables if var not in seen]
+    if strategy == "force":
+        return force_order(variables, [clause.support for clause in clauses])
+    raise BDDOptionError(f"Unknown variable order '{strategy}'. Use one of {VARIABLE_ORDERS}.")
+
+
+def total_span(order: Sequence[str], supports: Sequence[Sequence[str]]) -> int:
+    """Sum over the clauses of the distance between their first and last variable."""
+    position = {var: index for index, var in enumerate(order)}
+    span = 0
+    for support in supports:
+        levels = [position[var] for var in support if var in position]
+        if len(levels) > 1:
+            span += max(levels) - min(levels)
+    return span
+
+
+def force_order(initial: Sequence[str], supports: Sequence[Sequence[str]]) -> list[str]:
+    """FORCE: move every variable to the mean centre of gravity of its clauses, repeat.
+
+    Each iteration computes the centre of gravity of every clause (the mean position of its
+    variables), places every variable at the mean of the centres of the clauses it belongs
+    to, and re-sorts. The best order found (smallest total span) is returned; ties keep the
+    previous position, so the result is deterministic.
+    """
+    order = list(initial)
+    edges = [tuple(dict.fromkeys(var for var in support if var in set(order)))
+             for support in supports]
+    edges = [edge for edge in edges if len(edge) > 1]
+    if not edges:
+        return order
+    var_edges: dict[str, list[int]] = {var: [] for var in order}
+    for index, edge in enumerate(edges):
+        for var in edge:
+            var_edges[var].append(index)
+
+    best_order = order
+    best_span = total_span(order, edges)
+    for _ in range(FORCE_MAX_ITERATIONS):
+        position = {var: index for index, var in enumerate(order)}
+        centres = [sum(position[var] for var in edge) / len(edge) for edge in edges]
+        target = {
+            var: (sum(centres[i] for i in var_edges[var]) / len(var_edges[var])
+                  if var_edges[var] else float(position[var]))
+            for var in order
+        }
+        order = sorted(order, key=lambda var: (target[var], position[var]))
+        span = total_span(order, edges)
+        if span >= best_span:
+            break
+        best_order, best_span = order, span
+    return best_order
+
+
+def clause_order(clauses: Sequence[PLClause],
+                 order: Sequence[str],
+                 strategy: str = "minspan") -> list[PLClause]:
+    """Return the clauses in the order given by `strategy` for the variable order `order`."""
+    if strategy == "model":
+        return list(clauses)
+    position = {var: index for index, var in enumerate(order)}
+
+    def bounds(clause: PLClause) -> tuple[int, int]:
+        levels = [position[var] for var in clause.support if var in position] or [0]
+        return min(levels), max(levels)
+
+    indexed = list(enumerate(clauses))
+    if strategy == "minspan":
+        def span_key(item: tuple[int, PLClause]) -> tuple[int, int, int]:
+            low, high = bounds(item[1])
+            return (high - low, low, item[0])
+        return [clause for _, clause in sorted(indexed, key=span_key)]
+    if strategy == "minmax":
+        def max_key(item: tuple[int, PLClause]) -> tuple[int, int, int]:
+            low, high = bounds(item[1])
+            return (high, low, item[0])
+        return [clause for _, clause in sorted(indexed, key=max_key)]
+    raise BDDOptionError(f"Unknown clause order '{strategy}'. Use one of {CLAUSE_ORDERS}.")