flamapy-fm 2.6.0.dev7__tar.gz → 2.6.0.dev11__tar.gz

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flamapy-fm
-Version: 2.6.0.dev7
+Version: 2.6.0.dev11
 Summary: flamapy-fm is a plugin to Flamapy module
 Author-email: Flamapy <flamapy@us.es>
 License-Expression: GPL-3.0-or-later
@@ -8,7 +8,7 @@ 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.dev5
+Requires-Dist: flamapy-fw~=2.6.0.dev11
 Requires-Dist: uvlparser~=2.5.0
 Requires-Dist: afmparser~=1.0.3
 Provides-Extra: dev
@@ -33,3 +33,24 @@ FeatureIDE, Glencoe, AFM, SPLOT, JSON, …).
 ```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.dev11/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.6.0.dev7 → flamapy_fm-2.6.0.dev11}/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.dev11/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.6.0.dev7 → flamapy_fm-2.6.0.dev11}/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.6.0.dev7 → flamapy_fm-2.6.0.dev11}/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.6.0.dev7 → flamapy_fm-2.6.0.dev11}/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.6.0.dev7 → flamapy_fm-2.6.0.dev11}/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.6.0.dev7 → flamapy_fm-2.6.0.dev11}/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.6.0.dev7 → flamapy_fm-2.6.0.dev11}/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 = ''

flamapy_fm-2.6.0.dev11/flamapy/metamodels/fm_metamodel/operations/fm_generate_random_feature_model.py

@@ -0,0 +1,223 @@
+import random
+from typing import Optional
+
+from flamapy.core.models import VariabilityModel
+from flamapy.core.models.ast import AST, ASTOperation, Node, NodeType
+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,
+    Feature,
+    FeatureType,
+    Relation,
+    Constraint,
+    Attribute,
+    Domain,
+    Range,
+)
+
+# Minimum children an or/alternative group needs (and minimum features for a cross-tree constraint).
+_MIN_GROUP_MEMBERS = 2
+
+# UVL language levels this generator can target.
+_LANGUAGE_LEVELS = ('boolean', 'arithmetic', 'typed')
+# Non-boolean feature types used for the 'typed' level.
+_TYPED_FEATURE_TYPES = (FeatureType.INTEGER, FeatureType.REAL, FeatureType.STRING)
+# Name of the numeric attribute added to features for the 'arithmetic' level.
+_ARITHMETIC_ATTRIBUTE = 'value'
+
+
+class GenerateRandomFeatureModel(Operation):
+    """Generate a random synthetic feature model as a :class:`FeatureModel` object.
+
+    The model is built directly from feature-model objects (features, relations and cross-tree
+    constraints) — no serialization is involved. Serialize it to UVL (or any format) afterwards
+    with the corresponding writer transformation if needed. Useful to build corpora for
+    benchmarking, testing, or training learning-based operations.
+
+    ``language_level`` selects the UVL expressiveness of the generated model: ``'boolean'`` (tree +
+    requires/excludes constraints), ``'arithmetic'`` (features gain a numeric attribute and the
+    model gets arithmetic cross-tree constraints such as ``F1.value + F2.value > 40``), or
+    ``'typed'`` (some features are typed Integer/Real/String). When ``void`` is set, a contradictory
+    boolean constraint is added so the resulting model is unsatisfiable.
+
+    The operation produces a model, so ``execute`` ignores its (optional) input model.
+    """
+
+    facade = OperationDescriptor(
+        doc=(
+            'Generates a random synthetic feature model and returns it as a FeatureModel.\n'
+            '``num_features`` (>= 2) sizes the tree, ``max_constraints`` bounds the number of\n'
+            'cross-tree constraints, ``seed`` makes it reproducible, ``void=True`` forces an\n'
+            'unsatisfiable model, and ``language_level`` picks the UVL level to target:\n'
+            "'boolean', 'arithmetic' (numeric attributes + arithmetic constraints) or 'typed'\n"
+            '(Integer/Real/String features). Useful for building corpora, testing, or training.'
+        ),
+        returns='FeatureModel',
+        name='generate_random_feature_model', operation='GenerateRandomFeatureModel',
+        kind='producer',
+        inputs=(
+            Input('num_features', int, default=10, setter='set_num_features'),
+            Input('max_constraints', int, default=3, setter='set_max_constraints'),
+            Input('seed', int, default=0, setter='set_seed'),
+            Input('void', bool, default=False, setter='set_void'),
+            Input('language_level', str, default='boolean', setter='set_language_level'),
+        ),
+    )
+
+    def __init__(self) -> None:
+        self.result: FeatureModel
+        self._num_features: int = 10
+        self._max_constraints: int = 3
+        self._seed: int = 0
+        self._void: bool = False
+        self._language_level: str = 'boolean'
+
+    def get_result(self) -> FeatureModel:
+        return self.result
+
+    def set_num_features(self, num_features: int) -> None:
+        self._num_features = max(2, num_features)
+
+    def set_max_constraints(self, max_constraints: int) -> None:
+        self._max_constraints = max(0, max_constraints)
+
+    def set_seed(self, seed: int) -> None:
+        self._seed = seed
+
+    def set_void(self, void: bool) -> None:
+        self._void = void
+
+    def set_language_level(self, language_level: str) -> None:
+        level = language_level.lower()
+        if level not in _LANGUAGE_LEVELS:
+            raise FlamaException(
+                f"Unknown language level '{language_level}'. "
+                f"Choose from {list(_LANGUAGE_LEVELS)}.")
+        self._language_level = level
+
+    def _build_tree(self, rng: random.Random) -> Feature:
+        names = [f'F{i}' for i in range(self._num_features)]
+        features = {name: Feature(name, is_abstract=(index == 0))
+                    for index, name in enumerate(names)}
+
+        assignments: dict[str, list[str]] = {name: [] for name in names}
+        for name in names[1:]:
+            parent = rng.choice(names[: names.index(name)])
+            assignments[parent].append(name)
+
+        for parent_name, kids in assignments.items():
+            if not kids:
+                continue
+            parent = features[parent_name]
+            kid_features = [features[kid] for kid in kids]
+            for kid in kid_features:
+                kid.parent = parent
+            group = rng.choice(['mandatory', 'optional', 'or', 'alternative'])
+            if group in ('or', 'alternative') and len(kids) < _MIN_GROUP_MEMBERS:
+                group = 'optional'
+            if group == 'mandatory':
+                parent.relations.extend(Relation(parent, [kid], 1, 1) for kid in kid_features)
+            elif group == 'optional':
+                parent.relations.extend(Relation(parent, [kid], 0, 1) for kid in kid_features)
+            elif group == 'or':
+                parent.relations.append(Relation(parent, kid_features, 1, len(kid_features)))
+            else:  # alternative
+                parent.relations.append(Relation(parent, kid_features, 1, 1))
+        return features[names[0]]
+
+    def _apply_types(self, root: Feature, rng: random.Random) -> None:
+        """Give a random subset of non-root features a non-boolean type (=> TYPE level)."""
+        candidates = [feature for feature in _descendants(root) if feature is not root]
+        if not candidates:
+            return
+        count = max(1, len(candidates) // 3)
+        for feature in rng.sample(candidates, min(count, len(candidates))):
+            feature.feature_type = rng.choice(_TYPED_FEATURE_TYPES)
+
+    def _apply_attributes(self, root: Feature, rng: random.Random) -> None:
+        """Add a numeric attribute to non-root features for arithmetic constraints to reference."""
+        for feature in _descendants(root):
+            if feature is root:
+                continue
+            domain = Domain([Range(0, 100)], None)
+            feature.add_attribute(
+                Attribute(_ARITHMETIC_ATTRIBUTE, domain, rng.randint(0, 100)))
+
+    def _build_boolean_constraints(
+        self, non_root: list[str], rng: random.Random
+    ) -> list[Constraint]:
+        constraints: list[Constraint] = []
+        if len(non_root) >= _MIN_GROUP_MEMBERS and self._max_constraints > 0:
+            for index in range(rng.randint(1, self._max_constraints)):
+                left, right = rng.sample(non_root, 2)
+                operation = rng.choice([ASTOperation.REQUIRES, ASTOperation.EXCLUDES])
+                constraints.append(
+                    Constraint(f'ctc{index}',
+                               AST.create_simple_binary_operation(operation, left, right))
+                )
+        return constraints
+
+    def _build_arithmetic_constraints(
+        self, non_root: list[str], rng: random.Random
+    ) -> list[Constraint]:
+        """Constraints like ``F1.value + F2.value > 40`` (=> ARITHMETIC level). At least one."""
+        constraints: list[Constraint] = []
+        if len(non_root) < _MIN_GROUP_MEMBERS:
+            return constraints
+        arithmetic_ops = [ASTOperation.ADD, ASTOperation.SUB, ASTOperation.MUL]
+        comparisons = [ASTOperation.GREATER, ASTOperation.LOWER, ASTOperation.GREATER_EQUALS,
+                       ASTOperation.LOWER_EQUALS, ASTOperation.EQUALS]
+        for index in range(rng.randint(1, max(1, self._max_constraints))):
+            left, right = rng.sample(non_root, 2)
+            expression = Node(
+                rng.choice(arithmetic_ops),
+                Node(f'{left}.{_ARITHMETIC_ATTRIBUTE}', node_type=NodeType.FEATURE),
+                Node(f'{right}.{_ARITHMETIC_ATTRIBUTE}', node_type=NodeType.FEATURE))
+            comparison = Node(
+                rng.choice(comparisons), expression,
+                Node(rng.randint(1, 200), node_type=NodeType.LITERAL))
+            constraints.append(Constraint(f'arithmetic_ctc{index}', AST(comparison)))
+        return constraints
+
+    def _build_void_constraints(
+        self, root: Feature, non_root: list[str], rng: random.Random
+    ) -> list[Constraint]:
+        # Force a feature to be present (required by the always-selected root) and absent.
+        forced = rng.choice(non_root)
+        return [
+            Constraint('void_requires',
+                       AST.create_simple_binary_operation(
+                           ASTOperation.REQUIRES, root.name, forced)),
+            Constraint('void_excludes',
+                       AST.create_simple_unary_operation(ASTOperation.NOT, forced)),
+        ]
+
+    def _build_constraints(self, root: Feature, rng: random.Random) -> list[Constraint]:
+        non_root = [feature.name for feature in _descendants(root) if feature is not root]
+        constraints = self._build_boolean_constraints(non_root, rng)
+        if self._language_level == 'arithmetic':
+            constraints.extend(self._build_arithmetic_constraints(non_root, rng))
+        if self._void and non_root:
+            constraints.extend(self._build_void_constraints(root, non_root, rng))
+        return constraints
+
+    def execute(self, model: Optional[VariabilityModel] = None) -> 'GenerateRandomFeatureModel':
+        rng = random.Random(self._seed)
+        root = self._build_tree(rng)
+        if self._language_level == 'typed':
+            self._apply_types(root, rng)
+        elif self._language_level == 'arithmetic':
+            self._apply_attributes(root, rng)
+        constraints = self._build_constraints(root, rng)
+        self.result = FeatureModel(root, constraints)
+        return self
+
+
+def _descendants(feature: Feature) -> list[Feature]:
+    collected = [feature]
+    for relation in feature.relations:
+        for child in relation.children:
+            collected.extend(_descendants(child))
+    return collected

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/flamapy/metamodels/fm_metamodel/operations/fm_language_level.py

@@ -4,6 +4,7 @@ from typing import cast
 
 from flamapy.core.models import VariabilityModel, ASTOperation
 from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
 
 from flamapy.metamodels.fm_metamodel.models import FeatureModel, Constraint
 
@@ -34,6 +35,14 @@ class LanguageLevel:
 class FMLanguageLevel(Operation):
     """Operation to calculate the maximum language level of a feature model."""
 
+    facade = OperationDescriptor(
+        doc=(
+            'Return the UVL language level.'
+        ),
+        returns='Union[None, Any]',
+        name='language_level', operation='FMLanguageLevel'
+    )
+
     def __init__(self) -> None:
         self.result: LanguageLevel = LanguageLevel(MajorLevel.BOOLEAN, set())
 

flamapy_fm-2.6.0.dev11/flamapy/metamodels/fm_metamodel/operations/fm_leaf_features.py

@@ -0,0 +1,47 @@
+from typing import Any, cast
+
+from flamapy.core.models import VariabilityModel
+from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
+from flamapy.metamodels.fm_metamodel.models import FeatureModel, Feature
+
+
+def _leaf_features_result(result: Any) -> Any:
+    return [feature.name for feature in result]
+
+
+class FMLeafFeatures(Operation):
+    """
+    This operation returns the list of features that are leaves of the feature model tree
+    (i.e., they have not children).
+    """
+
+    facade = OperationDescriptor(
+        doc=(
+            'This operation is used to find leaf features in a model: It returns the leaf\n'
+            'features if they are found in the model. If the model does not follow the UVL\n'
+            'specification, an exception is raised and the operation returns False.\n'
+            '\n'
+            'Traditionally you would use the flama tool by features =\n'
+            "discover_metamodel.use_operation_from_file('OperationString', model) however,\n"
+            'in this tool we know that this operation is from the fm metamodel, so we avoid\n'
+            'to execute the transformation if possible'
+        ),
+        returns='Union[None, List[str]]',
+        name='leaf_features', operation='FMLeafFeatures', result_adapter=_leaf_features_result
+    )
+
+    def __init__(self) -> None:
+        self.result: list[Feature] = []
+
+    def get_result(self) -> list[Feature]:
+        return self.result
+
+    def execute(self, model: VariabilityModel) -> 'FMLeafFeatures':
+        fm_model = cast(FeatureModel, model)
+        self.result = get_leaf_features(fm_model)
+        return self
+
+
+def get_leaf_features(feature_model: FeatureModel) -> list[Feature]:
+    return [f for f in feature_model.get_features() if len(f.get_relations()) == 0]

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/flamapy/metamodels/fm_metamodel/operations/fm_max_depth_tree.py

@@ -2,6 +2,7 @@ from typing import cast
 
 from flamapy.core.models import VariabilityModel
 from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.fm_metamodel.models import FeatureModel
 from flamapy.metamodels.fm_metamodel.operations.fm_feature_ancestors import get_feature_ancestors
 from flamapy.metamodels.fm_metamodel.operations.fm_leaf_features import get_leaf_features
@@ -10,6 +11,16 @@ from flamapy.metamodels.fm_metamodel.operations.fm_leaf_features import get_leaf
 class FMMaxDepthTree(Operation):
     """This operation returns the maximum depth of the feature model tree."""
 
+    facade = OperationDescriptor(
+        doc=(
+            'This operation is used to find the max depth of the tree in a model: It\n'
+            'returns the max depth of the tree. If the model does not follow the UVL\n'
+            'specification, an exception is raised and the operation returns False.'
+        ),
+        returns='Union[None, int]',
+        name='max_depth', operation='FMMaxDepthTree'
+    )
+
     def __init__(self) -> None:
         self.result = 0
 

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/flamapy/metamodels/fm_metamodel/operations/fm_metrics.py

@@ -4,6 +4,7 @@ import statistics
 from flamapy.core.exceptions import FlamaException
 from flamapy.core.models.variability_model import VariabilityModel
 from flamapy.core.operations.metrics_operation import Metrics
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.fm_metamodel.models import FeatureModel, Feature
 from flamapy.metamodels.fm_metamodel.operations import FMAverageBranchingFactor
 
@@ -26,6 +27,15 @@ def metric_method(func: Callable[..., dict[str, Any]]) -> Callable[..., dict[str
 
 class FMMetrics(Metrics):  # pylint: disable=too-many-instance-attributes
 
+    facade = OperationDescriptor(
+        doc=(
+            'Returns a collection of structural metrics for the feature model, such as\n'
+            'number of features, constraints, relations, and complexity indicators.'
+        ),
+        returns='Union[None, List[Dict[str, Any]]]',
+        name='metrics', operation='FMMetrics'
+    )
+
     def __init__(self) -> None:
         super().__init__()
         self.model: Optional[FeatureModel] = None

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/flamapy/metamodels/fm_metamodel/operations/fm_variation_points.py

@@ -1,11 +1,27 @@
-from typing import cast
+from typing import Any, cast
 
 from flamapy.core.models import VariabilityModel
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.fm_metamodel.operations.interfaces import VariationPoints
 from flamapy.metamodels.fm_metamodel.models import FeatureModel, Feature
 
 
+def _variation_points_result(result: Any) -> Any:
+    return {vp.name: [variant.name for variant in variants] for vp, variants in result.items()}
+
+
 class FMVariationPoints(VariationPoints):
+    facade = OperationDescriptor(
+        doc=(
+            'Returns the variation points of the feature model. A variation point is a\n'
+            'feature that has at least one non-mandatory child, representing a decision\n'
+            'point in the model. The result maps each variation point name to the list of\n'
+            'its variant feature names.'
+        ),
+        returns='Union[None, Dict[str, List[str]]]',
+        name='variation_points', operation='FMVariationPoints',
+        result_adapter=_variation_points_result,
+    )
 
     def __init__(self) -> None:
         self.result: dict[Feature, list[Feature]] = {}

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/flamapy_fm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flamapy-fm
-Version: 2.6.0.dev7
+Version: 2.6.0.dev11
 Summary: flamapy-fm is a plugin to Flamapy module
 Author-email: Flamapy <flamapy@us.es>
 License-Expression: GPL-3.0-or-later
@@ -8,7 +8,7 @@ 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.dev5
+Requires-Dist: flamapy-fw~=2.6.0.dev11
 Requires-Dist: uvlparser~=2.5.0
 Requires-Dist: afmparser~=1.0.3
 Provides-Extra: dev
@@ -33,3 +33,24 @@ FeatureIDE, Glencoe, AFM, SPLOT, JSON, …).
 ```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.dev7 → flamapy_fm-2.6.0.dev11}/flamapy_fm.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 setup.py
 flamapy/metamodels/fm_metamodel/__init__.py
 flamapy/metamodels/fm_metamodel/models/__init__.py
+flamapy/metamodels/fm_metamodel/models/clause_set.py
 flamapy/metamodels/fm_metamodel/models/feature_model.py
 flamapy/metamodels/fm_metamodel/operations/__init__.py
 flamapy/metamodels/fm_metamodel/operations/fm_atomic_sets.py

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/flamapy_fm.egg-info/requires.txt

@@ -1,4 +1,4 @@
-flamapy-fw~=2.6.0.dev5
+flamapy-fw~=2.6.0.dev11
 uvlparser~=2.5.0
 afmparser~=1.0.3
 

{flamapy_fm-2.6.0.dev7 → flamapy_fm-2.6.0.dev11}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flamapy-fm"
-version = "2.6.0.dev7"
+version = "2.6.0.dev11"
 description = "flamapy-fm is a plugin to Flamapy module"
 readme = "README.md"
 license = "GPL-3.0-or-later"
 authors = [{ name = "Flamapy", email = "flamapy@us.es" }]
 requires-python = ">=3.11"
 dependencies = [
-    "flamapy-fw~=2.6.0.dev5",
+    "flamapy-fw~=2.6.0.dev11",
     "uvlparser~=2.5.0",
     "afmparser~=1.0.3",
 ]

flamapy_fm-2.6.0.dev7/README.md

@@ -1,13 +0,0 @@
-# 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
-```

flamapy_fm-2.6.0.dev7/flamapy/metamodels/fm_metamodel/operations/fm_generate_random_feature_model.py

@@ -1,100 +0,0 @@
-import os
-import random
-import tempfile
-from typing import Optional
-
-from flamapy.core.models import VariabilityModel
-from flamapy.core.operations import Operation
-from flamapy.metamodels.fm_metamodel.models import FeatureModel
-from flamapy.metamodels.fm_metamodel.transformations import UVLReader
-
-# Minimum children an or/alternative group needs (and minimum features for a cross-tree constraint).
-_MIN_GROUP_MEMBERS = 2
-
-
-class GenerateRandomFeatureModel(Operation):
-    """Generate a random synthetic feature model.
-
-    A random feature tree (mandatory/optional/or/alternative groups) plus random cross-tree
-    constraints are emitted as UVL and parsed back into a :class:`FeatureModel`. Useful to build
-    corpora for benchmarking, testing, or training learning-based operations. When ``void`` is
-    set, a contradictory constraint is added so the resulting model is unsatisfiable.
-
-    The operation produces a model, so ``execute`` ignores its (optional) input model.
-    """
-
-    def __init__(self) -> None:
-        self.result: FeatureModel
-        self._num_features: int = 10
-        self._max_constraints: int = 3
-        self._seed: int = 0
-        self._void: bool = False
-
-    def get_result(self) -> FeatureModel:
-        return self.result
-
-    def set_num_features(self, num_features: int) -> None:
-        self._num_features = max(2, num_features)
-
-    def set_max_constraints(self, max_constraints: int) -> None:
-        self._max_constraints = max(0, max_constraints)
-
-    def set_seed(self, seed: int) -> None:
-        self._seed = seed
-
-    def set_void(self, void: bool) -> None:
-        self._void = void
-
-    def _emit_uvl(self, rng: random.Random) -> str:
-        names = [f'F{i}' for i in range(self._num_features)]
-        root = names[0]
-        lines = ['features', f'    {root} {{abstract}}']
-
-        children: dict[str, list[str]] = {name: [] for name in names}
-        for name in names[1:]:
-            parent = rng.choice(names[: names.index(name)])
-            children[parent].append(name)
-
-        def emit(parent: str, depth: int) -> None:
-            kids = children[parent]
-            if not kids:
-                return
-            indent = '    ' * (depth + 1)
-            group = rng.choice(['mandatory', 'optional', 'or', 'alternative'])
-            if group in ('or', 'alternative') and len(kids) < _MIN_GROUP_MEMBERS:
-                group = 'optional'
-            lines.append(f'{indent}{group}')
-            lines.extend(f'{indent}    {kid}' for kid in kids)
-            for kid in kids:
-                emit(kid, depth + 2)
-
-        emit(root, 1)
-
-        constraints = []
-        non_root = names[1:]
-        if len(non_root) >= _MIN_GROUP_MEMBERS and self._max_constraints > 0:
-            for _ in range(rng.randint(1, self._max_constraints)):
-                left, right = rng.sample(non_root, 2)
-                constraints.append(
-                    rng.choice([f'{left} => {right}', f'!{left} | {right}', f'!{left} | !{right}'])
-                )
-        if self._void and non_root:
-            forced = rng.choice(non_root)
-            constraints.append(f'{root} => {forced}')
-            constraints.append(f'!{forced}')
-        if constraints:
-            lines.append('constraints')
-            lines.extend(f'    {constraint}' for constraint in constraints)
-        return '\n'.join(lines) + '\n'
-
-    def execute(self, model: Optional[VariabilityModel] = None) -> 'GenerateRandomFeatureModel':
-        rng = random.Random(self._seed)
-        uvl = self._emit_uvl(rng)
-        handle, path = tempfile.mkstemp(suffix='.uvl')
-        try:
-            with os.fdopen(handle, 'w') as file:
-                file.write(uvl)
-            self.result = UVLReader(path).transform()
-        finally:
-            os.remove(path)
-        return self

flamapy_fm-2.6.0.dev7/flamapy/metamodels/fm_metamodel/operations/fm_leaf_features.py

@@ -1,27 +0,0 @@
-from typing import cast
-
-from flamapy.core.models import VariabilityModel
-from flamapy.core.operations import Operation
-from flamapy.metamodels.fm_metamodel.models import FeatureModel, Feature
-
-
-class FMLeafFeatures(Operation):
-    """
-    This operation returns the list of features that are leaves of the feature model tree
-    (i.e., they have not children).
-    """
-
-    def __init__(self) -> None:
-        self.result: list[Feature] = []
-
-    def get_result(self) -> list[Feature]:
-        return self.result
-
-    def execute(self, model: VariabilityModel) -> 'FMLeafFeatures':
-        fm_model = cast(FeatureModel, model)
-        self.result = get_leaf_features(fm_model)
-        return self
-
-
-def get_leaf_features(feature_model: FeatureModel) -> list[Feature]:
-    return [f for f in feature_model.get_features() if len(f.get_relations()) == 0]