flamapy-fm 2.5.0.dev0__tar.gz → 2.6.0__tar.gz

flamapy_fm-2.6.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: flamapy-fm
+Version: 2.6.0
+Summary: flamapy-fm is a plugin to Flamapy module
+Author-email: Flamapy <flamapy@us.es>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/flamapy/fm_metamodel
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flamapy-fw~=2.6.0
+Requires-Dist: uvlparser~=2.5.0
+Requires-Dist: afmparser~=1.0.3
+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"
+Requires-Dist: antlr4-tools; extra == "dev"
+Dynamic: license-file
+
+# flamapy-fm
+
+The feature model metamodel plugin for [flamapy](https://flamapy.org): the
+feature model classes plus readers and writers for many formats (UVL,
+FeatureIDE, Glencoe, AFM, SPLOT, JSON, …).
+
+**Documentation:** https://docs.flamapy.org/framework/plugins/feature_model_plugin
+
+## Installation
+
+```bash
+pip install flamapy-fm
+```
+
+## Operations
+
+Beyond the metrics/analysis operations (core/dead features, atomic sets, branching factor, …),
+this plugin includes a **random feature-model generator**:
+
+- `GenerateRandomFeatureModel` — builds a random synthetic `FeatureModel` object directly
+  (random tree of mandatory/optional/or/alternative groups plus random cross-tree constraints;
+  an optional `void` flag makes it unsatisfiable). Useful for benchmarking, testing, and building
+  corpora for learning-based operations. Serialize it to UVL (or any format) with the writer
+  transformations if you need text.
+
+```python
+from flamapy.metamodels.fm_metamodel.operations import GenerateRandomFeatureModel
+
+op = GenerateRandomFeatureModel()
+op.set_num_features(20)
+op.set_max_constraints(5)
+op.set_seed(0)
+fm = op.execute().get_result()   # -> FeatureModel
+```

flamapy_fm-2.6.0/README.md

@@ -0,0 +1,34 @@
+# flamapy-fm
+
+The feature model metamodel plugin for [flamapy](https://flamapy.org): the
+feature model classes plus readers and writers for many formats (UVL,
+FeatureIDE, Glencoe, AFM, SPLOT, JSON, …).
+
+**Documentation:** https://docs.flamapy.org/framework/plugins/feature_model_plugin
+
+## Installation
+
+```bash
+pip install flamapy-fm
+```
+
+## Operations
+
+Beyond the metrics/analysis operations (core/dead features, atomic sets, branching factor, …),
+this plugin includes a **random feature-model generator**:
+
+- `GenerateRandomFeatureModel` — builds a random synthetic `FeatureModel` object directly
+  (random tree of mandatory/optional/or/alternative groups plus random cross-tree constraints;
+  an optional `void` flag makes it unsatisfiable). Useful for benchmarking, testing, and building
+  corpora for learning-based operations. Serialize it to UVL (or any format) with the writer
+  transformations if you need text.
+
+```python
+from flamapy.metamodels.fm_metamodel.operations import GenerateRandomFeatureModel
+
+op = GenerateRandomFeatureModel()
+op.set_num_features(20)
+op.set_max_constraints(5)
+op.set_seed(0)
+fm = op.execute().get_result()   # -> FeatureModel
+```

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/models/__init__.py

@@ -10,11 +10,13 @@ from .feature_model import (
     FeatureType,
     AttributeType
 )
+from .clause_set import ClauseSet
 
 __all__ = [
     'Attribute',
     'AttributeType',
     'Cardinality',
+    'ClauseSet',
     'Constraint',
     'Domain',
     'Feature',

flamapy_fm-2.6.0/flamapy/metamodels/fm_metamodel/models/clause_set.py

@@ -0,0 +1,201 @@
+"""A solver-agnostic CNF (clause set) of a feature model.
+
+`ClauseSet` is a lightweight data holder — the clauses plus the variable/feature maps — that any
+plugin can build from a feature model without depending on a SAT solver. It is deliberately NOT a
+``VariabilityModel`` (it is not a discoverable metamodel) and the encoder lives here as a
+classmethod builder rather than as a transformation (flamapy transformations are m2m/t2m/m2t).
+
+The SAT plugin (`FmToPysat`) and the compilation/counting plugins (sdd, dnnf, sharpsat) all build
+their representation from this single encoding.
+"""
+import itertools
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from flamapy.core.exceptions import FlamaException
+
+from flamapy.metamodels.fm_metamodel.models.feature_model import (
+    FeatureModel,
+    Feature,
+    Relation,
+    Constraint,
+)
+
+
+@dataclass
+class ClauseSet:
+    """CNF encoding of a feature model as signed-integer clauses plus name/id maps."""
+
+    clauses: list[list[int]] = field(default_factory=list)
+    variables: dict[str, int] = field(default_factory=dict)   # feature name -> variable id
+    features: dict[int, str] = field(default_factory=dict)    # variable id -> feature name
+    auxiliary_variables: set[int] = field(default_factory=set)  # Tseytin aux ids (non-feature)
+    original_model: Optional[FeatureModel] = None
+    # Provenance: the clauses grouped by their source (root feature / relation / constraint),
+    # labelled by ``str(source)``. Needed by diagnosis (clause → constraint mapping); ignored by
+    # consumers that only want the flat clause list.
+    clause_groups: list[tuple[str, list[list[int]]]] = field(default_factory=list)
+
+    def feature_variables(self) -> list[int]:
+        """Variable ids that correspond to features (excludes Tseytin auxiliaries)."""
+        return list(self.features.keys())
+
+    @classmethod
+    def from_feature_model(
+        cls, feature_model: FeatureModel, cnf_method: str = 'distributive'
+    ) -> 'ClauseSet':
+        """Encode ``feature_model`` into CNF.
+
+        ``cnf_method`` controls only how cross-tree constraints are turned into clauses:
+        ``'distributive'`` (default) expands them directly, ``'tseytin'`` introduces auxiliary
+        variables for a compact, model-count-preserving encoding.
+        """
+        return _Encoder(cnf_method).encode(feature_model)
+
+
+class _Encoder:
+    """Ported ~1:1 from the SAT plugin's FmToPysat so the produced clauses are identical."""
+
+    def __init__(self, cnf_method: str) -> None:
+        self.cnf_method = cnf_method
+        self.counter = 1
+        self.variables: dict[str, int] = {}
+        self.features: dict[int, str] = {}
+        self.clauses: list[list[int]] = []
+        self.auxiliary_variables: set[int] = set()
+        self.clause_groups: list[tuple[str, list[list[int]]]] = []
+
+    def encode(self, feature_model: FeatureModel) -> ClauseSet:
+        for feature in feature_model.get_features():
+            self._add_feature(feature)
+        self._add_root(feature_model.root)
+        for relation in feature_model.get_relations():
+            self._add_relation(relation)
+        for constraint in feature_model.get_logical_constraints():
+            self._add_constraint(constraint)
+        return ClauseSet(
+            clauses=self.clauses,
+            variables=self.variables,
+            features=self.features,
+            auxiliary_variables=self.auxiliary_variables,
+            original_model=feature_model,
+            clause_groups=self.clause_groups,
+        )
+
+    def _get_variable(self, name: str) -> int:
+        if name not in self.variables:
+            raise FlamaException(f'Feature {name} is not in the model')
+        return self.variables[name]
+
+    def _add_feature(self, feature: Feature) -> None:
+        if feature.name not in self.variables:
+            self.variables[feature.name] = self.counter
+            self.features[self.counter] = feature.name
+            self.counter += 1
+
+    def _add_root(self, feature: Feature) -> None:
+        clause = [self._get_variable(feature.name)]
+        self.clauses.append(clause)
+        self.clause_groups.append((str(feature), [clause]))
+
+    def _add_mandatory_relation(self, relation: Relation) -> list[list[int]]:
+        parent = self._get_variable(relation.parent.name)
+        child = self._get_variable(relation.children[0].name)
+        return [[-parent, child], [-child, parent]]
+
+    def _add_optional_relation(self, relation: Relation) -> list[list[int]]:
+        parent = self._get_variable(relation.parent.name)
+        child = self._get_variable(relation.children[0].name)
+        return [[-child, parent]]
+
+    def _add_or_relation(self, relation: Relation) -> list[list[int]]:
+        parent = self._get_variable(relation.parent.name)
+        alt = [-parent] + [self._get_variable(c.name) for c in relation.children]
+        clauses = [alt]
+        for child in relation.children:
+            clauses.append([-self._get_variable(child.name), parent])
+        return clauses
+
+    def _add_alternative_relation(self, relation: Relation) -> list[list[int]]:
+        parent = self._get_variable(relation.parent.name)
+        alt = [-parent] + [self._get_variable(c.name) for c in relation.children]
+        clauses = [alt]
+        for i, _ in enumerate(relation.children):
+            for j in range(i + 1, len(relation.children)):
+                if i != j:
+                    clauses.append([
+                        -self._get_variable(relation.children[i].name),
+                        -self._get_variable(relation.children[j].name),
+                    ])
+            clauses.append([-self._get_variable(relation.children[i].name), parent])
+        return clauses
+
+    def _add_constraint_relation(self, relation: Relation) -> list[list[int]]:
+        parent = self._get_variable(relation.parent.name)
+        card_min = relation.card_min
+        card_max = relation.card_max if relation.card_max != -1 else len(relation.children)
+        clauses = []
+        for val in range(len(relation.children) + 1):
+            if val < card_min or val > card_max:
+                for combination in itertools.combinations(relation.children, val):
+                    cnf = [-parent]
+                    for feat in relation.children:
+                        if feat in combination:
+                            cnf.append(-self._get_variable(feat.name))
+                        else:
+                            cnf.append(self._get_variable(feat.name))
+                    clauses.append(cnf)
+        for val in range(1, len(relation.children) + 1):
+            for combination in itertools.combinations(relation.children, val):
+                cnf = [parent]
+                for feat in relation.children:
+                    if feat in combination:
+                        cnf.append(-self._get_variable(feat.name))
+                    else:
+                        cnf.append(self._get_variable(feat.name))
+                clauses.append(cnf)
+        return clauses
+
+    def _add_relation(self, relation: Relation) -> None:
+        if relation.is_mandatory():
+            clauses = self._add_mandatory_relation(relation)
+        elif relation.is_optional():
+            clauses = self._add_optional_relation(relation)
+        elif relation.is_or():
+            clauses = self._add_or_relation(relation)
+        elif relation.is_alternative():
+            clauses = self._add_alternative_relation(relation)
+        else:
+            clauses = self._add_constraint_relation(relation)
+        self.clauses.extend(clauses)
+        self.clause_groups.append((str(relation), clauses))
+
+    def _allocate_auxiliary(self, aux_names: list[str]) -> dict[str, int]:
+        aux_map: dict[str, int] = {}
+        for name in aux_names:
+            var = self.counter
+            self.counter += 1
+            aux_map[name] = var
+            self.auxiliary_variables.add(var)
+        return aux_map
+
+    def _add_constraint(self, ctc: Constraint) -> None:
+        if self.cnf_method == 'tseytin':
+            clauses, aux_names = ctc.ast.get_clauses_with_aux(method='tseytin')
+            aux_map = self._allocate_auxiliary(aux_names)
+        else:
+            clauses = ctc.ast.get_clauses()
+            aux_map = {}
+
+        def term_to_variable(term: Any) -> int:
+            negated = term.startswith('-')
+            name = term[1:] if negated else term
+            var = aux_map[name] if name in aux_map else self._get_variable(name)
+            return -var if negated else var
+
+        group = []
+        for clause in clauses:
+            resolved = [term_to_variable(term) for term in clause]
+            self.clauses.append(resolved)
+            group.append(resolved)
+        self.clause_groups.append((str(ctc), group))

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/models/feature_model.py

@@ -3,7 +3,7 @@ from functools import total_ordering
 from enum import Enum
 
 from flamapy.core.exceptions import FlamaException
-from flamapy.core.models import AST, VariabilityModel, VariabilityElement, ASTOperation
+from flamapy.core.models import AST, VariabilityModel, VariabilityElement, ASTOperation, NodeType
 from flamapy.core.models.ast import LOGICAL_OPERATORS, ARITHMETIC_OPERATORS, AGGREGATION_OPERATORS
 from flamapy.core.models.ast import simplify_formula, propagate_negation, to_cnf
 
@@ -247,7 +247,11 @@ class Constraint:
         self._ast = ast
 
     def get_features(self) -> list[str]:
-        """List of features' names involved in the constraint."""
+        """List of features' names involved in the constraint.
+
+        Uses node_type information when available (set by readers that support it).
+        Falls back to heuristics for nodes without explicit type info.
+        """
         features = set()
         stack = [self.ast.root]
         while stack:
@@ -255,9 +259,15 @@ class Constraint:
             if node is None:
                 continue
             if node.is_unique_term():
-                if (isinstance(node.data, (int, float)) or node.data.startswith("'")):
-                    continue
-                features.add(node.data)
+                if node.node_type is not None:
+                    if node.node_type == NodeType.FEATURE:
+                        features.add(node.data)
+                    # NodeType.LITERAL: skip
+                # Fallback heuristics for nodes without explicit type (backward compatibility)
+                elif not isinstance(node.data, (int, float)) and not (
+                    isinstance(node.data, str) and node.data.startswith("'")
+                ):
+                    features.add(node.data)
             elif node.is_unary_op():
                 stack.append(node.left)
             elif node.is_binary_op():
@@ -281,8 +291,7 @@ class Constraint:
         """Return true if the constraint is a single feature or its negation."""
         root_op = self._ast.root
         return (root_op.is_term() or
-                (root_op.data == ASTOperation.NOT and
-                (root_op.left.is_term() or root_op.right.is_term())))
+                (root_op.data == ASTOperation.NOT and root_op.left.is_term()))
 
     def is_simple_constraint(self) -> bool:
         """Return true if the constraint is a simple constraint (requires or excludes)."""

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/operations/__init__.py

@@ -8,6 +8,7 @@ from .fm_estimated_configurations_number import FMEstimatedConfigurationsNumber
 from .fm_atomic_sets import FMAtomicSets
 from .fm_metrics import FMMetrics
 from .fm_generate_random_attribute import GenerateRandomAttribute
+from .fm_generate_random_feature_model import GenerateRandomFeatureModel
 from .fm_variation_points import FMVariationPoints
 from .fm_language_level import FMLanguageLevel, LanguageLevel, MajorLevel, MinorLevel
 
@@ -25,6 +26,7 @@ __all__ = [
            'FMMetrics',
            'FMVariationPoints',
            'GenerateRandomAttribute',
+           'GenerateRandomFeatureModel',
            'LanguageLevel',
            'MajorLevel',
            'MinorLevel'

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/operations/fm_atomic_sets.py

@@ -1,11 +1,25 @@
-from typing import cast
+from typing import Any, cast
 
 from flamapy.core.models import VariabilityModel
 from flamapy.core.operations.atomic_sets import AtomicSets
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.fm_metamodel.models import FeatureModel, Feature
 
 
+def _atomic_sets_result(result: Any) -> Any:
+    return [[feature.name for feature in atomic_set] for atomic_set in result]
+
+
 class FMAtomicSets(AtomicSets):
+    facade = OperationDescriptor(
+        doc=(
+            'This operation is used to find the atomic sets in a model: It returns the\n'
+            'atomic sets if they are found in the model. If the model does not follow the\n'
+            'UVL specification, an exception is raised and the operation returns False.'
+        ),
+        returns='Union[None, List[List[Any]]]',
+        name='atomic_sets', operation='FMAtomicSets', result_adapter=_atomic_sets_result
+    )
 
     def __init__(self) -> None:
         self.result: list[set[Feature]] = []

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/operations/fm_average_branching_factor.py

@@ -2,6 +2,7 @@ from typing import cast
 
 from flamapy.core.models import VariabilityModel
 from flamapy.core.operations import AverageBranchingFactor
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.fm_metamodel.models.feature_model import FeatureModel
 
 
@@ -11,6 +12,18 @@ class FMAverageBranchingFactor(AverageBranchingFactor):
     The number of branches is the number of features that have at least one child.
     """
 
+    facade = OperationDescriptor(
+        doc=(
+            'This refers to the average number of child features that a parent feature has\n'
+            "in a feature model. It's calculated by dividing the total number of child\n"
+            'features by the total number of parent features. A high average branching\n'
+            'factor indicates a complex feature model with many options, while a low\n'
+            'average branching factor indicates a simpler model.'
+        ),
+        returns='Union[None, float]',
+        name='average_branching_factor', operation='FMAverageBranchingFactor'
+    )
+
     def __init__(self) -> None:
         self.result: float = 0
 

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/operations/fm_count_leafs.py

@@ -2,11 +2,22 @@ from typing import cast
 
 from flamapy.core.models import VariabilityModel
 from flamapy.core.operations import CountLeafs
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.fm_metamodel.models import FeatureModel
 
 
 class FMCountLeafs(CountLeafs):
 
+    facade = OperationDescriptor(
+        doc=(
+            'This operation counts the number of leaf features in a feature model. Leaf\n'
+            'features are those that do not have any child features. They represent the\n'
+            'most specific options in a product line.'
+        ),
+        returns='Union[None, int]',
+        name='count_leafs', operation='FMCountLeafs'
+    )
+
     def __init__(self) -> None:
         self.result = 0
 

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/operations/fm_estimated_configurations_number.py

@@ -4,6 +4,7 @@ from typing import Optional, cast
 from flamapy.core.models import VariabilityModel
 from flamapy.core.exceptions import FlamaException
 from flamapy.core.operations import EstimatedConfigurationsNumber
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.fm_metamodel.models import FeatureModel, Feature, Relation
 
 
@@ -15,6 +16,18 @@ class FMEstimatedConfigurationsNumber(EstimatedConfigurationsNumber):
     and thus, the number is an upper limit of the real number of products.
     """
 
+    facade = OperationDescriptor(
+        doc=(
+            'This is an estimate of the total number of different products that can be\n'
+            "produced from a feature model. It's calculated by considering all possible\n"
+            'combinations of features. This can be a simple multiplication if all features\n'
+            'are independent, but in most cases, constraints and dependencies between\n'
+            'features need to be taken into account.'
+        ),
+        returns='Union[None, int]',
+        name='estimated_number_of_configurations', operation='FMEstimatedConfigurationsNumber'
+    )
+
     def __init__(self) -> None:
         self.result = 0
         self.feature_model: Optional[FeatureModel] = None

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/operations/fm_feature_ancestors.py

@@ -1,17 +1,40 @@
-from typing import Optional
+from typing import Any, Optional
 
 from flamapy.core.models import VariabilityModel
 from flamapy.core.exceptions import FlamaException
 from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor, Input
 from flamapy.metamodels.fm_metamodel.models import Feature
 
 
+def _feature_ancestors_inputs(operation: Any, facade: Any, kwargs: dict[str, Any]) -> None:
+    operation.set_feature(facade.fm_model.get_feature_by_name(kwargs['feature_name']))
+
+
+def _feature_ancestors_result(result: Any) -> Any:
+    return [feature.name for feature in result]
+
+
 class FMFeatureAncestors(Operation):
     """
     This operation returns the list of ancestors of a given feature
     (i.e., all parents recursively up to the root feature).
     """
 
+    facade = OperationDescriptor(
+        doc=(
+            'These are the features that are directly or indirectly the parent of a given\n'
+            'feature in a feature model. Ancestors of a feature are found by traversing up\n'
+            'the feature hierarchy. This information can be useful to understand the\n'
+            'context and dependencies of a feature.'
+        ),
+        returns='Union[None, List[str]]',
+        name='feature_ancestors', operation='FMFeatureAncestors',
+        inputs=(Input('feature_name', str, required=True),),
+        input_adapter=_feature_ancestors_inputs,
+        result_adapter=_feature_ancestors_result,
+    )
+
     def __init__(self) -> None:
         self.result: list[Feature] = []
         self.feature: Optional[Feature] = None

{flamapy_fm-2.5.0.dev0 → flamapy_fm-2.6.0}/flamapy/metamodels/fm_metamodel/operations/fm_generate_random_attribute.py

@@ -3,6 +3,7 @@ from typing import Any, cast
 
 from flamapy.core.models import VariabilityModel
 from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor, Input
 from flamapy.core.exceptions import FlamaException
 from flamapy.metamodels.fm_metamodel.models import (
     FeatureModel,
@@ -12,12 +13,37 @@ from flamapy.metamodels.fm_metamodel.models import (
 )
 
 
+def _generate_random_attribute_inputs(operation: Any, facade: Any, kwargs: dict[str, Any]) -> None:
+    operation.set_name(kwargs['name'])
+    operation.set_domain(Domain([Range(kwargs['min_value'], kwargs['max_value'])], None))
+    operation.set_only_leaf_features(bool(kwargs.get('only_leaf_features', False)))
+
+
 class GenerateRandomAttribute(Operation):
     """
     This operation generate random values for a given attribute and set the attribute for all
     features in the model.
     """
 
+    facade = OperationDescriptor(
+        doc=(
+            'Augments the feature model with a randomly-valued numeric attribute on its\n'
+            'features and returns the modified model. ``name`` is the attribute name, values are\n'
+            'drawn from the ``[min_value, max_value]`` range, and ``only_leaf_features`` limits\n'
+            'it to leaf features. Useful before attribute_optimization or feature bounds.'
+        ),
+        returns='FeatureModel',
+        name='generate_random_attribute', operation='GenerateRandomAttribute',
+        kind='transformer',
+        inputs=(
+            Input('name', str, required=True),
+            Input('min_value', int, default=0),
+            Input('max_value', int, default=100),
+            Input('only_leaf_features', bool, default=False),
+        ),
+        input_adapter=_generate_random_attribute_inputs,
+    )
+
     def __init__(self) -> None:
         self.result: FeatureModel
         self._attribute_name: str = ''