flamapy 2.5.0.dev0__py3-none-any.whl → 2.6.0.dev0__py3-none-any.whl

flamapy/interfaces/python/flamapy_feature_model.py

@@ -1,5 +1,5 @@
 import logging
-from typing import List, Any, Union
+from typing import Any, Dict, Generator, List, Optional, Tuple, Union
 from flamapy.core.discover import DiscoverMetamodels
 from flamapy.metamodels.fm_metamodel.models import FeatureModel
 from flamapy.core.exceptions import FlamaException
@@ -15,19 +15,12 @@ class FLAMAFeatureModel:
         Any model in UVL, FaMaXML or FeatureIDE format are accepted
         """
         self.model_path = model_path
-        """
-        Creating the interface witht he flama framework
-        """
         self.discover_metamodel = DiscoverMetamodels()
-        """
-        We save the model for later ussage
-        """
         self.fm_model = self._read(model_path)
-        """
-        We create a empty sat model and a bdd model to avoid double transformations
-        """
         self.sat_model = None
         self.bdd_model = None
+        self.z3_model = None
+        self.diagnosis_model = None
 
     def _read(self, model_path: str) -> FeatureModel:
         return self.discover_metamodel.use_transformation_t2m(model_path, "fm")
@@ -40,6 +33,16 @@ class FLAMAFeatureModel:
         if self.bdd_model is None:
             self.bdd_model = self.discover_metamodel.use_transformation_m2m(self.fm_model, "bdd")
 
+    def _transform_to_z3(self) -> None:
+        if self.z3_model is None:
+            self.z3_model = self.discover_metamodel.use_transformation_m2m(self.fm_model, "z3")
+
+    def _transform_to_diagnosis(self) -> None:
+        if self.diagnosis_model is None:
+            self.diagnosis_model = self.discover_metamodel.use_transformation_m2m(
+                self.fm_model, "pysat_diagnosis"
+            )
+
     def atomic_sets(self) -> Union[None, List[List[Any]]]:
         """
         This operation is used to find the atomic sets in a model:
@@ -379,3 +382,286 @@ class FLAMAFeatureModel:
         except FlamaException as exception:
             logger.error("Error: %s", exception)
             return None
+
+    # FM-based operations
+
+    def metrics(self) -> Union[None, List[Dict[str, Any]]]:
+        """
+        Returns a collection of structural metrics for the feature model, such as number of
+        features, constraints, relations, and complexity indicators.
+        """
+        try:
+            return self.discover_metamodel.use_operation(
+                self.fm_model, "FMMetrics"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def variation_points(self) -> Union[None, Dict[str, List[str]]]:
+        """
+        Returns the variation points of the feature model. A variation point is a feature that
+        has at least one non-mandatory child, representing a decision point in the model.
+        The result maps each variation point name to the list of its variant feature names.
+        """
+        try:
+            raw = self.discover_metamodel.use_operation(
+                self.fm_model, "FMVariationPoints"
+            ).get_result()
+            return {vp.name: [v.name for v in variants] for vp, variants in raw.items()}
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    # SAT-based operations
+
+    def backbone(self) -> Union[None, Dict[str, List[Any]]]:
+        """
+        Returns the backbone of the feature model: the set of features that must always be
+        selected (core) and those that must never be selected (dead) across all valid
+        configurations, grouped under 'core' and 'dead' keys.
+        """
+        try:
+            self._transform_to_sat()
+            return self.discover_metamodel.use_operation(
+                self.sat_model, "PySATBackbone"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    # BDD-based operations
+
+    def homogeneity(self) -> Union[None, float]:
+        """
+        Measures how similar the products of the feature model are to each other. It is
+        computed as the average commonality factor across all features. A value of 1.0 means
+        all products are identical; lower values indicate more diversity.
+        """
+        try:
+            self._transform_to_bdd()
+            return self.discover_metamodel.use_operation(
+                self.bdd_model, "BDDHomogeneity"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def product_distribution(self) -> Union[None, List[int]]:
+        """
+        Returns the distribution of products by number of activated features. The value at
+        index i is the count of valid configurations that have exactly i features selected.
+        """
+        try:
+            self._transform_to_bdd()
+            return self.discover_metamodel.use_operation(
+                self.bdd_model, "BDDProductDistribution"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def variability(self) -> Union[None, Tuple[float, float]]:
+        """
+        Returns a tuple of (total_variability, partial_variability). Total variability is the
+        ratio of valid configurations to the theoretical maximum; partial variability is the
+        ratio relative to only the variant features.
+        """
+        try:
+            self._transform_to_bdd()
+            return self.discover_metamodel.use_operation(
+                self.bdd_model, "BDDVariability"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def variant_features(self) -> Union[None, List[str]]:
+        """
+        Returns the features that are neither core nor dead — they appear in some but not all
+        valid configurations. These are the features that actually vary across products.
+        """
+        try:
+            self._transform_to_bdd()
+            return self.discover_metamodel.use_operation(
+                self.bdd_model, "BDDVariantFeatures"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def unique_features(self) -> Union[None, List[str]]:
+        """
+        Returns features that appear in exactly one valid configuration. These features
+        uniquely identify a single product in the product line.
+        """
+        try:
+            self._transform_to_bdd()
+            return self.discover_metamodel.use_operation(
+                self.bdd_model, "BDDUniqueFeatures"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def pure_optional_features(self) -> Union[None, List[str]]:
+        """
+        Returns features with a feature inclusion probability of exactly 0.5, meaning they
+        are selected in exactly half of the valid configurations. These are the most
+        unconstrained optional features.
+        """
+        try:
+            self._transform_to_bdd()
+            return self.discover_metamodel.use_operation(
+                self.bdd_model, "BDDPureOptionalFeatures"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def feature_inclusion_probability(self) -> Union[None, Dict[str, float]]:
+        """
+        Returns a mapping from each feature name to its inclusion probability: the fraction
+        of valid configurations in which that feature is selected. Core features have
+        probability 1.0 and dead features have probability 0.0.
+        """
+        try:
+            self._transform_to_bdd()
+            return self.discover_metamodel.use_operation(
+                self.bdd_model, "BDDFeatureInclusionProbability"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def configurations_with_n_features(self, n: int) -> Union[None, List[Configuration]]:
+        """
+        Returns all valid configurations that have exactly n features selected.
+        """
+        try:
+            self._transform_to_bdd()
+            operation = self.discover_metamodel.get_operation(
+                self.bdd_model, "BDDConfigurationsWithNFeatures"
+            )
+            operation.set_n_features(n)
+            operation.execute(self.bdd_model)
+            return list(operation.get_result())
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def sampling(
+        self, size: int, with_replacement: bool = False
+    ) -> Union[None, List[Configuration]]:
+        """
+        Returns a random sample of valid configurations of the given size. When
+        with_replacement is True, the same configuration may appear more than once.
+        """
+        try:
+            self._transform_to_bdd()
+            operation = self.discover_metamodel.get_operation(self.bdd_model, "BDDSampling")
+            operation.set_sample_size(size)
+            operation.set_with_replacement(with_replacement)
+            operation.execute(self.bdd_model)
+            return operation.get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    # Z3-based operations
+
+    def all_feature_bounds(self) -> Union[None, Dict[str, Dict[str, Any]]]:
+        """
+        Returns the value bounds for all typed (Integer, Real, String) attribute features in
+        the model. Each entry maps a feature name to a dict with 'min', 'max', and 'bounded'
+        keys. Requires the z3 metamodel plugin.
+        """
+        try:
+            self._transform_to_z3()
+            return self.discover_metamodel.use_operation(
+                self.z3_model, "Z3AllFeatureBounds"
+            ).get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def feature_bounds(self, variable_name: str) -> Union[None, Dict[str, Any]]:
+        """
+        Returns the value bounds for a specific typed attribute feature. The result dict
+        contains 'min', 'max', and 'bounded' keys. Requires the z3 metamodel plugin.
+        """
+        try:
+            self._transform_to_z3()
+            operation = self.discover_metamodel.get_operation(self.z3_model, "Z3FeatureBounds")
+            operation.set_variable_name(variable_name)
+            operation.execute(self.z3_model)
+            return operation.get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    # Diagnosis-based operations
+
+    def diagnosis(
+        self,
+        configuration_path: str,
+        test_case_path: str,
+        max_diagnoses: Optional[int] = None,
+    ) -> Union[None, List[str]]:
+        """
+        Returns a list of diagnoses explaining why a given configuration does not satisfy
+        the test case constraints. Each diagnosis is a minimal set of constraints whose
+        removal would resolve the inconsistency. Requires the pysat_diagnosis plugin.
+        """
+        try:
+            self._transform_to_diagnosis()
+            configuration = self.discover_metamodel.use_transformation_t2m(
+                configuration_path, "configuration"
+            )
+            test_case = self.discover_metamodel.use_transformation_t2m(
+                test_case_path, "configuration"
+            )
+            operation = self.discover_metamodel.get_operation(
+                self.diagnosis_model, "PySATDiagnosis"
+            )
+            operation.set_configuration(configuration)
+            operation.set_test_case(test_case)
+            if max_diagnoses is not None:
+                operation.set_max_diagnoses(max_diagnoses)
+            operation.execute(self.diagnosis_model)
+            return operation.get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None
+
+    def conflict(
+        self,
+        configuration_path: str,
+        test_case_path: str,
+        max_conflicts: Optional[int] = None,
+    ) -> Union[None, List[str]]:
+        """
+        Returns a list of conflict sets: minimal subsets of the model constraints that are
+        inconsistent with the given configuration and test case. Requires the pysat_diagnosis
+        plugin.
+        """
+        try:
+            self._transform_to_diagnosis()
+            configuration = self.discover_metamodel.use_transformation_t2m(
+                configuration_path, "configuration"
+            )
+            test_case = self.discover_metamodel.use_transformation_t2m(
+                test_case_path, "configuration"
+            )
+            operation = self.discover_metamodel.get_operation(
+                self.diagnosis_model, "PySATConflict"
+            )
+            operation.set_configuration(configuration)
+            operation.set_test_case(test_case)
+            if max_conflicts is not None:
+                operation.set_max_conflicts(max_conflicts)
+            operation.execute(self.diagnosis_model)
+            return operation.get_result()
+        except FlamaException as exception:
+            logger.error("Error: %s", exception)
+            return None

flamapy-2.6.0.dev0.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: flamapy
+Version: 2.6.0.dev0
+Summary: Flamapy feature model is a distribution of the flama framework containing all plugins required to analyze feature models. It also offers a richer API and a complete command line interface and documentation.
+Author-email: Flamapy <flamapy@us.es>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/flamapy/flamapy-feature-model
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flamapy-fw~=2.6.0.dev0
+Requires-Dist: flamapy-fm~=2.6.0.dev0
+Requires-Dist: flamapy-sat~=2.6.0.dev0
+Requires-Dist: flamapy-bdd~=2.6.0.dev0
+Requires-Dist: flamapy-z3~=2.6.0.dev0
+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"
+Dynamic: license-file
+
+# flamapy
+
+The flamapy feature-model distribution: a meta-package that installs the
+framework and the feature-model analysis plugins, and provides the command-line
+interface and the easy-to-use Python facade (`FLAMAFeatureModel`).
+
+**Documentation:** https://docs.flamapy.org
+
+## Installation
+
+```bash
+pip install flamapy
+```

flamapy-2.6.0.dev0.dist-info/RECORD

@@ -0,0 +1,9 @@
+flamapy/commands/__init__.py,sha256=np1430SLtfuyxNTAFPFNGrB0OunU-KMrOnwWYcwa0VY,6550
+flamapy/interfaces/python/__init__.py,sha256=NVQH1l6O9ElD8YvUVBXJN0Y_ETmu3AbyQBZJJ9qiuoU,86
+flamapy/interfaces/python/flamapy_feature_model.py,sha256=RxUHwn0Wy3QSsrfrDaNuUHjfwCwZWXmdCH8MKxbjW-s,27727
+flamapy-2.6.0.dev0.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+flamapy-2.6.0.dev0.dist-info/METADATA,sha256=dHRVwXKXLRDI1Wg0rwMKgHIkQdnJs8jCa3pcUeJP2Fw,1264
+flamapy-2.6.0.dev0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+flamapy-2.6.0.dev0.dist-info/entry_points.txt,sha256=CS_W4K9LW9xOf-7ymWD58KklNHBnhMHm0RXAZ9JLgVo,57
+flamapy-2.6.0.dev0.dist-info/top_level.txt,sha256=2YBI9dg4GVk28AJuyNu6dldi5Riwt5SP0zpNe2lSU5M,8
+flamapy-2.6.0.dev0.dist-info/RECORD,,

{flamapy-2.5.0.dev0.dist-info → flamapy-2.6.0.dev0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.0)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

flamapy-2.5.0.dev0.dist-info/METADATA

@@ -1,104 +0,0 @@
-Metadata-Version: 2.4
-Name: flamapy
-Version: 2.5.0.dev0
-Summary: Flamapy feature model is a distribution of the flama framework containing all plugins required to analyze feature models. It also offers a richer API and a complete command line interface and documentation.
-Author-email: Flamapy <flamapy@us.es>
-License-Expression: GPL-3.0-or-later
-Project-URL: Homepage, https://github.com/flamapy/flamapy-feature-model
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: flamapy-fw~=2.5.0.dev0
-Requires-Dist: flamapy-fm~=2.5.0.dev0
-Requires-Dist: flamapy-sat~=2.5.0.dev0
-Requires-Dist: flamapy-bdd~=2.5.0.dev0
-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"
-Dynamic: license-file
-
-<div align="center">
-
-  <a href="">[![Pytest Testing Suite](https://github.com/flamapy/flamapy/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/flamapy/flamapy/actions/workflows/tests.yml)</a>
-  <a href="">[![Commits Syntax Checker](https://github.com/flamapy/flamapy/actions/workflows/commits.yml/badge.svg?branch=main)](https://github.com/flamapy/flamapy/actions/workflows/commits.yml)</a>
-  <a href="">![PyPI](https://img.shields.io/pypi/v/flamapy?label=pypi%20package)
-  <a href="">![PyPI - Downloads](https://img.shields.io/pypi/dm/flamapy)
-</div>
-
-# 
-
-<div id="top"></div>
-<br />
-<div align="center">
-
-  <h3 align="center">FLAMAPY</h3>
-
-  <p align="center">
-    A new and easy way to use FLAMA
-    <br />
-    <a href="https://github.com/flamapy/flamapy/issues">Report Bug</a>
-    ·
-    <a href="https://github.com/flamapy/flamapy/issues">Request Feature</a>
-  </p>
-</div>
-<!-- ABOUT THE PROJECT -->
-
-# About The Project
-FLAMAPY Feature model distribution provides an easier way of using FLAMAPY when analysing feature models. It packs the most used plugins for analyis of feature models adding a layer of convenience to use the framework or integrate it. If some other operations are required please see in the [documentation](flamapy.github.io/docs) if its supported in the ecosystem though the Python interface. 
-
-Feature Model Analysis has a crucial role in software product line engineering, enabling us to understand, design, and validate the complex relationships among features in a software product line. These feature models can often be complex and challenging to analyze due to their variability, making it difficult to identify conflicts, dead features, and potential optimizations. This is where this distribution comes in.
-
-# Using the CMD
-```bash
-flamapy --help #This will show the commands available
-flamapy satisfiable <path to file> to check if a model is valid
-...
-```
-# Using the Python interface
-This is simple, Flama FM dist in hosted in pypi, therefore simply add the package flama-fm-dist to your requirements file and call the API as follows:
-
-```python
-from flamapy.interfaces.python.flama_feature_model import FLAMAFeatureModel
-
-fm = FLAMAFeatureModel("path/to/feature/model")
-print(fm.valid())
-```
-# Operations available:
-Currently this distribution offers a subset of the operations available in the ecosystem, in the case of the feature mdoel distribution, we provide those operations that are well tested and used by the community. Nonetheless, If other more complex operations are required you can rely on the python interface of the framework to execute them all. 
-
-* atomic_sets: This operation is used to find the atomic sets in a model: It returns the atomic sets if they are found in the model. If the model does not follow the UVL specification, an exception is raised and the operation returns False.
-
-* average_branching_factor:This refers to the average number of child features that a parent feature has in a feature model. It's calculated by dividing the total number of child features by the total number of parent features. A high average branching factor indicates a complex feature model with many options, while a low average branching factor indicates a simpler model.
-
-* commonality: This is a measure of how often a feature appears in the products of a product line. It's usually expressed as a percentage. A feature with 100 per cent commonality is a core feature, as it appears in all products.
-
-* configurations: These are the individual outcomes that can be produced from a feature model. Each product is a combination of features that satisfies all the constraints and dependencies in the feature model.
-
-* configurations_number: This is the total number of different full configurations that can be produced from a feature model. It's calculated by considering all possible combinations of features, taking into account the constraints and dependencies between features.
-
-* core_features: These are the features that are present in all products of a product line. In a feature model, they are the  features that are mandatory and not optional. Core features define the commonality among all products in a product line. This call requires sat to be called, however, there is an implementation within flamapy that does not requires sat, please use the framework in case of needing it.
-
-* count_leafs: This operation counts the number of leaf features in a feature model. Leaf features are those that do not have any child features. They represent the most specific options in a product line.
-* dead_features: These are features that, due to the constraints and dependencies in the feature model, cannot be included in any valid product. Dead features are usually a sign of an error in the feature model.
-
-* estimated_number_of_configurations: This is an estimate of the total number of different products that can be produced from a feature model. It's calculated by considering all possible combinations of features. This can be a simple multiplication if all
-features are independent, but in most cases, constraints and dependencies between features need to be taken into account.
-
-* false_optional_features: These are features that appear to be optional in the feature model, but due to the constraints and dependencies, must be included in every valid product. Like dead features, false optional features are usually a sign of an error in the feature model.
-
-* feature_ancestors: These are the features that are directly or indirectly the parent of a given feature in a feature model. Ancestors of a feature are found by traversing up the feature hierarchy. This information can be useful to understand the context and dependencies of a feature.
-
-* filter: This operation selects a subset of the products of a product line based on certain criteria. For example, youmight filter the products to only include those that contain a certain feature.
-
-* leaf_features: This operation is used to find leaf features in a model: It returns the leaf features if they are found in themodel. If the model does not follow the UVL specification, an exception is raised and the operation returns False.
-
-* max_depth: This operation is used to find the max depth of the tree in a model: It returns the max depth of the tree. If the model does not follow the UVL specification, an exception is raised and the operation returns False.
-
-* satisfiable: In the context of feature models, this usually refers to whether the feature model itself satisfies all the
-constraints and dependencies. A a valid feature model is one that does encodes at least a single valid product.
-
-* satisfiable_configuration: This is a product that is produced from a valid configuration of features. A valid product satisfies all the constraints and dependencies in the feature model.
-

flamapy-2.5.0.dev0.dist-info/RECORD

@@ -1,9 +0,0 @@
-flamapy/commands/__init__.py,sha256=np1430SLtfuyxNTAFPFNGrB0OunU-KMrOnwWYcwa0VY,6550
-flamapy/interfaces/python/__init__.py,sha256=NVQH1l6O9ElD8YvUVBXJN0Y_ETmu3AbyQBZJJ9qiuoU,86
-flamapy/interfaces/python/flamapy_feature_model.py,sha256=lNjKO-1VQCw0s7QT0uWcfwVvCM7h2eISSfMbSL7BLhE,15918
-flamapy-2.5.0.dev0.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
-flamapy-2.5.0.dev0.dist-info/METADATA,sha256=mu_DJDpFhEbEc3Lp0Y23t4nCfTUD4WLduq31-7o-7HI,7733
-flamapy-2.5.0.dev0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
-flamapy-2.5.0.dev0.dist-info/entry_points.txt,sha256=CS_W4K9LW9xOf-7ymWD58KklNHBnhMHm0RXAZ9JLgVo,57
-flamapy-2.5.0.dev0.dist-info/top_level.txt,sha256=2YBI9dg4GVk28AJuyNu6dldi5Riwt5SP0zpNe2lSU5M,8
-flamapy-2.5.0.dev0.dist-info/RECORD,,