chore: release 2.6.0

Author: jagalindo

.github/workflows/release.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Install dependencies
         run: |

README.md

@@ -1,198 +1,12 @@
-# BDD plugin for flamapy
-- [BDD plugin for flamapy](#bdd-plugin-for-flamapy)
-  - [Description](#description)
-  - [Requirements and Installation](#requirements-and-installation)
-  - [Functionality and usage](#functionality-and-usage)
-    - [Load a feature model in UVL and create the BDD](#load-a-feature-model-in-uvl-and-create-the-bdd)
-    - [Save the BDD in a file](#save-the-bdd-in-a-file)
-    - [Load the BDD from a file](#load-the-bdd-from-a-file)
-    - [Analysis operations](#analysis-operations)
-  - [Contributing to the BDD plugin](#contributing-to-the-bdd-plugin)
+# flamapy-bdd
 
+BDD-based analysis for [flamapy](https://flamapy.org) feature models, built on
+the [dd](https://github.com/tulip-control/dd) library.
 
-## Description
-This plugin supports Binary Decision Diagrams (BDDs) representations for feature models.
+**Documentation:** https://docs.flamapy.org/framework/plugins/bdd_plugin
 
-The plugin is based on [flamapy](https://github.com/flamapy/core) and thus, it follows the same architecture:
+## Installation
 
-<p align="center">
-  <img width="750" src="doc/bdd_plugin.png">
-</p>
-
-The BDD plugin relies on the [dd](https://github.com/tulip-control/dd) library to manipulate BDDs.
-The complete documentation of such library is available [here](https://github.com/tulip-control/dd/blob/main/doc.md).
-
-The following is an example of feature model and its BDD using complemented arcs.
-
-<p align="center">
-  <img width="750" src="doc/fm_example.png">
-</p>
-
-<p align="center">
-  <img width="750" src="doc/bdd_example.svg">
-</p>
-
-## Requirements and Installation
-- Python 3.9+
-- This plugin depends on the [flamapy core](https://github.com/flamapy/core) and on the [Feature Model plugin](https://github.com/flamapy/fm_metamodel).
-
-```
-pip install flamapy flamapy-fm flamapy-bdd
-```
-
-We have tested the plugin on Linux, but Windows is also supported.
-
-
-## Functionality and usage
-The executable script [test_bdd_metamodel.py](https://github.com/flamapy/bdd_metamodel/blob/master/tests/test_bdd_metamodel.py) serves as an entry point to show the plugin in action.
-
-The following functionality is provided:
-
-
-### Load a feature model in UVL and create the BDD
-```python
-from flamapy.metamodels.fm_metamodel.transformations import UVLReader
-from flamapy.metamodels.bdd_metamodel.transformations import FmToBDD
-
-# Load the feature model from UVL
-feature_model = UVLReader('models/uvl_models/pizzas.uvl').transform()
-# Create the BDD from the feature model
-bdd_model = FmToBDD(feature_model).transform()
-```
-
-
-### Save the BDD in a file
-```python
-from flamapy.metamodels.bdd_metamodel.transformations import PNGWriter, DDDMPv3Writer
-# Save the BDD as an image in PNG
-PNGWriter(path='my_bdd.png', bdd_model).transform()
-# Save the BDD in a .dddmp file
-DDDMPv3Writer(f'my_bdd.dddmp', bdd_model).transform()
-```
-Writers available: DDDMPv3 ('dddmp'), DDDMPv2 ('dddmp'), JSON ('json'), Pickle ('p'), PDF ('pdf'), PNG ('png'), SVG ('svg').
-
-### Load the BDD from a file
-```python
-from flamapy.metamodels.bdd_metamodel.transformations import JSONReader
-# Load the BDD from a .json file
-bdd_model = JSONReader(path='path/to/my_bdd.json').transform()
-```
-Readers available: JSON ('json'), DDDMP ('dddmp'), Pickle ('p').
-
-*NOTE:* DDDMP and Pickle readers are not fully supported yet.
-
-### Analysis operations
-
-- Satisfiable
-
-    Return whether the model is satisfiable (valid):
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDSatisfiable
-    satisfiable = BDDSatisfiable().execute(bdd_model).get_result()
-    print(f'Satisfiable? (valid?): {satisfiable}')
-    ```
-
-- Configurations number
-
-    Return the number of configurations:
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDConfigurationsNumber
-    n_configs = BDDConfigurationsNumber().execute(bdd_model).get_result()
-    print(f'#Configurations: {n_configs}')
-    ```
-
-- Configurations
-
-    Enumerate the configurations of the model:
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDConfigurations
-    configurations = BDDConfigurations().execute(bdd_model).get_result()
-    for i, config in enumerate(configurations, 1):
-        print(f'Config {i}: {[feat for feat in config.elements if config.elements[feat]]}')
-    ```
-
-- Sampling
-
-    Return a sample of the given size of uniform random configurations with or without replacement:
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDSampling
-    sampling_op = BDDSampling()
-    sampling_op.set_sample_size(5)
-    sampling_op.set_with_replacement(False)  # Default False
-    sample = sampling_op.execute(bdd_model).get_result()
-    for i, config in enumerate(sample, 1):
-        print(f'Config {i}: {[feat for feat in config.elements if config.elements[feat]]}')
-    ```
-
-- Product Distribution
-
-    Return the number of products (configurations) having a given number of features:
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDProductDistribution
-    dist = BDDProductDistribution().execute(bdd_model).get_result()
-    print(f'Product Distribution: {dist}')
-    ```
-
-- Feature Inclusion Probability
-
-    Return the probability for a feature to be included in a valid configuration:
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDFeatureInclusionProbability
-    prob = BDDFeatureInclusionProbability().execute(bdd_model).get_result()
-    for feat in prob.keys():
-        print(f'{feat}: {prob[feat]}')
-    ```
-
-- Core features
-
-    Return the core features (those features that are present in all the configurations):
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDCoreFeatures
-    core_features = BDDCoreFeatures().execute(bdd_model).get_result()
-    print(f'Core features: {core_features}')
-    ```
-
-- Dead features
-
-    Return the dead features (those features that are not present in any configuration):
-    ```python
-    from flamapy.metamodels.bdd_metamodel.operations import BDDDeadFeatures
-    dead_features = BDDDeadFeatures().execute(bdd_model).get_result()
-    print(f'Dead features: {dead_features}')
-    ```
-
-Most analysis operations support also a partial configuration as an additional argument, so the operation will return the result taking into account the given partial configuration. For example:
-
-```python
-from flamapy.core.models import Configuration
-# Create a partial configuration
-elements = {'Pizza': True, 'Big': True}
-partial_config = Configuration(elements)
-# Calculate the number of configuration from the partial configuration
-configs_number_op = BDDConfigurationsNumber()
-configs_number_op.set_partial_configuration(partial_config)
-n_configs = configs_number_op.execute(bdd_model).get_result()
-print(f'#Configurations: {n_configs}')
+```bash
+pip install flamapy-bdd
 ```
-
-
-## Contributing to the BDD plugin
-To contribute in the development of this plugin:
-
-1. Fork the repository into your GitHub account.
-2. Clone the repository: `git@github.com:<<username>>/bdd_metamodel.git`
-3. Create a virtual environment: `python -m venv env`
-4. Activate the virtual environment: `source env/bin/activate`
-5. Install the plugin dependencies: `pip install flamapy flamapy-fm`
-6. Install the BDD plugin from the source code: `pip install -e bdd_metamodel`
-
-Please try to follow the standards code quality to contribute to this plugin before creating a Pull Request:
-
-- To analyze your Python code and output information about errors, potential problems, convention violations and complexity, pass the prospector with:
-
-    `make lint`
-
-- To analyze the static type checker for Python and find bugs, pass the Mypy:
-
-    `make mypy`
-

flamapy/metamodels/bdd_metamodel/models/bdd_model.py

@@ -55,7 +55,7 @@ def get_all_paths(self) -> list[dict[str, bool]]:
 
     def count_solutions(self) -> int:
         """Count the number of valid configurations (SAT)."""
-        return self.bdd.count(self.root, len(self.vars))  # count(node, n_vars)
+        return self.bdd.count(self.root, len(self.vars_order))  # count(node, n_vars)
 
     def dump_structure(self) -> None:
         """Prints the structure of the BDD for debugging purposes."""

flamapy/metamodels/bdd_metamodel/models/utils/pl_model.py

@@ -89,21 +89,20 @@ def _get_alternative_formula(self, relation: Relation) -> str:
         return f" {and_str} ".join(f"({f})" for f in formula)
 
     def _get_mutex_formula(self, relation: Relation) -> str:
-        formula = []
-        parent = relation.parent.name
-        children = {child.name for child in relation.children}
         equiv_str = self.logic_connectives['EQUIVALENCE']
         and_str = self.logic_connectives['AND']
         not_str = self.logic_connectives['NOT']
         or_str = self.logic_connectives['OR']
+        parent = relation.parent.name
+        children = {child.name for child in relation.children}
+
+        one_child_formula = []
         for child in children:
-            children_negatives = children - {child}
-            neg_children = f" {and_str} ".join(not_str + cn for cn in children_negatives)
-            formula.append(f"{child} {equiv_str} ({neg_children} {and_str} {parent})")
-        formula_str = f" {and_str} ".join(f"({f})" for f in formula)
-        children_or = f" {or_str} ".join(child for child in children)
-        left = f"({parent} {equiv_str} {not_str} ({children_or}))"
-        return f"{left} {or_str} ({formula_str})"
+            other_children_or = f" {or_str} ".join(c for c in children - {child})
+            one_child_formula.append(f"({not_str} {child} {equiv_str} ({other_children_or}))")
+        one_child_str = f" {and_str} ".join(f for f in one_child_formula)
+        no_child_str = f" {and_str} ".join(f"{not_str} {c}" for c in children)
+        return f"({no_child_str}) {or_str} (({one_child_str}) {and_str} {parent})"
 
     def _get_cardinality_formula(self, relation: Relation) -> str:
         parent = relation.parent.name
@@ -112,11 +111,13 @@ def _get_cardinality_formula(self, relation: Relation) -> str:
         and_str = self.logic_connectives['AND']
         or_str = self.logic_connectives['OR']
 
+        card_min = relation.card_min
+        card_max = relation.card_max if relation.card_max != -1 else len(children)
         all_clauses = []
 
         # 1. If the parent is active, prohibit combinations outside the range [min..max]
         for val in range(len(children) + 1):
-            if val < relation.card_min or val > relation.card_max:
+            if val < card_min or val > card_max:
                 for combination in itertools.combinations(children, val):
                     # To prohibit an exact combination: (NOT parent OR NOT child1 OR child2...)
                     clause_parts = [f"{not_str}{parent}"]

flamapy/metamodels/bdd_metamodel/operations/bdd_configurations_with_n_features.py

@@ -2,14 +2,30 @@
 
 from flamapy.core.models import VariabilityModel
 from flamapy.core.operations import Operation
+from flamapy.core.operations.descriptor import OperationDescriptor, Input
 from flamapy.metamodels.configuration_metamodel.models import Configuration
 from flamapy.metamodels.bdd_metamodel.models import BDDModel
 from flamapy.metamodels.bdd_metamodel.operations.bdd_product_distribution import DistributionEngine
 
 
+def _configurations_with_n_features_result(result: Any) -> Any:
+    return list(result)
+
+
 class BDDConfigurationsWithNFeatures(Operation):
     """Operation to get all configurations with exactly n selected features from a BDD model."""
 
+    facade = OperationDescriptor(
+        doc=(
+            'Returns all valid configurations that have exactly n features selected.'
+        ),
+        returns='Union[None, List[Configuration]]',
+        name='configurations_with_n_features', operation='BDDConfigurationsWithNFeatures',
+        default_backend='bdd',
+        inputs=(Input('n', int, required=True, setter='set_n_features'),),
+        result_adapter=_configurations_with_n_features_result,
+    )
+
     def __init__(self) -> None:
         self._result: Generator[Configuration, None, None]
         self.n_features: int = 0

flamapy/metamodels/bdd_metamodel/operations/bdd_false_optional_features.py

@@ -9,7 +9,7 @@
 from flamapy.metamodels.bdd_metamodel.models import BDDModel
 
 
-LOGGER = logging.getLogger('PySATFalseOptionalFeatures')
+LOGGER = logging.getLogger('BDDFalseOptionalFeatures')
 
 
 class BDDFalseOptionalFeatures(FalseOptionalFeatures):
@@ -25,11 +25,11 @@ def get_result(self) -> list[Any]:
 
     def execute(self, model: VariabilityModel) -> 'BDDFalseOptionalFeatures':
         bdd_model = cast(BDDModel, model)
-        try:
-            feature_model = cast(FeatureModel, model.original_model)
-        except FlamaException:
-            LOGGER.exception("The transformation didn't attach the source model, "
-                             "which is required for this operation.")
+        original_model = getattr(model, 'original_model', None)
+        if original_model is None:
+            raise FlamaException("The transformation didn't attach the source model, "
+                                 "which is required for this operation.")
+        feature_model = cast(FeatureModel, original_model)
         self._result = get_false_optional_features(bdd_model, feature_model)
         return self
 

flamapy/metamodels/bdd_metamodel/operations/bdd_feature_inclusion_probability.py

@@ -1,6 +1,7 @@
 from typing import Any, Optional, cast
 
 from flamapy.core.models import VariabilityModel
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.configuration_metamodel.models.configuration import Configuration
 from flamapy.metamodels.bdd_metamodel.models import BDDModel
 from flamapy.metamodels.bdd_metamodel.operations.interfaces import FeatureInclusionProbability
@@ -14,6 +15,17 @@ class BDDFeatureInclusionProbability(FeatureInclusionProbability):
     (https://doi.org/10.1109/ICSE.2019.00091)]
     """
 
+    facade = OperationDescriptor(
+        doc=(
+            'Returns a mapping from each feature name to its inclusion probability: the\n'
+            'fraction of valid configurations in which that feature is selected. Core\n'
+            'features have probability 1.0 and dead features have probability 0.0.'
+        ),
+        returns='Union[None, Dict[str, float]]',
+        name='feature_inclusion_probability', operation='BDDFeatureInclusionProbability',
+        default_backend='bdd',
+    )
+
     def __init__(self) -> None:
         self._result: dict[Any, float] = {}
         self._partial_configuration: Optional[Configuration] = None

flamapy/metamodels/bdd_metamodel/operations/bdd_homogeneity.py

@@ -1,13 +1,24 @@
 from typing import cast
 
 from flamapy.core.models import VariabilityModel
+from flamapy.core.operations.descriptor import OperationDescriptor
 from flamapy.metamodels.configuration_metamodel.models.configuration import Configuration
 from flamapy.metamodels.bdd_metamodel.models import BDDModel
 from flamapy.metamodels.bdd_metamodel.operations.interfaces import Homogeneity
 from flamapy.metamodels.bdd_metamodel.operations import BDDCommonalityFactor
 
 
 class BDDHomogeneity(Homogeneity):
+
+    facade = OperationDescriptor(
+        doc=(
+            'Measures how similar the products of the feature model are to each other. It\n'
+            'is computed as the average commonality factor across all features. A value of\n'
+            '1.0 means all products are identical; lower values indicate more diversity.'
+        ),
+        returns='Union[None, float]',
+        name='homogeneity', operation='BDDHomogeneity', default_backend='bdd'
+    )
     def __init__(self) -> None:
         self._result: float = 0.0
 

flamapy/metamodels/bdd_metamodel/operations/bdd_metrics.py

@@ -52,7 +52,7 @@ def calculate_metamodel_metrics(self, model: VariabilityModel) -> list[dict[str,
         self.model = cast(BDDModel, model)
 
         # Do some basic calculations to speedup the rest
-        self._features = list(self.model.features_variables.keys())
+        self._features = list(self.model.features_vars.keys())
         self._configurations_number = (
             bdd_operations.BDDConfigurationsNumber().execute(self.model).get_result()
         )