bw-functional 0b79__tar.gz

bw_functional-0b79/LICENSE

@@ -0,0 +1,12 @@
+Copyright 2024 Chris Mutel
+Copyright 2025 Leiden University
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bw_functional-0b79/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: bw-functional
+Version: 0b79
+Summary: Code for handling multifunctional activities in Brightway
+Author-email: Chris Mutel <cmutel@gmail.com>, Marin Visscher <m.r.visscher@cml.leidenuniv.nl>
+Maintainer-email: Marin Visscher <m.r.visscher@cml.leidenuniv.nl>
+Project-URL: source, https://github.com/brightway-lca/multifunctional
+Project-URL: homepage, https://github.com/brightway-lca/multifunctional
+Project-URL: tracker, https://github.com/brightway-lca/multifunctional/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: blinker
+Requires-Dist: bw2data>=4.0.1
+Requires-Dist: bw2io>=0.9.1
+Requires-Dist: bw_processing>=0.9.6
+Requires-Dist: numpy<2
+Provides-Extra: testing
+Requires-Dist: bw-functional; extra == "testing"
+Requires-Dist: bw2calc>=2.0.1; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-loguru; extra == "testing"
+Requires-Dist: python-coveralls; extra == "testing"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-randomly; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Dynamic: license-file
+
+# bw-functional
+
+[![PyPI](https://img.shields.io/pypi/v/bw-functional.svg)][pypi status]
+[![Status](https://img.shields.io/pypi/status/bw-functional.svg)][pypi status]
+[![Python Version](https://img.shields.io/pypi/pyversions/bw-functional)][pypi status]
+[![License](https://img.shields.io/pypi/l/bw-functional)][license]
+
+[![Read the documentation at https://multifunctional.readthedocs.io/](https://img.shields.io/readthedocs/multifunctional/latest.svg?label=Read%20the%20Docs)][read the docs]
+[![Tests](https://github.com/mrvisscher/bw-functional/actions/workflows/python-test.yml/badge.svg)][tests]
+[![Codecov](https://codecov.io/gh/brightway-lca/multifunctional/branch/main/graph/badge.svg)][codecov]
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
+
+[pypi status]: https://pypi.org/project/multifunctional/
+[read the docs]: https://multifunctional.readthedocs.io/
+[tests]: https://github.com/brightway-lca/multifunctional/actions?workflow=Tests
+[codecov]: https://app.codecov.io/gh/brightway-lca/multifunctional
+[pre-commit]: https://github.com/pre-commit/pre-commit
+[black]: https://github.com/psf/black
+
+Adding functions to Brightway processes
+
+## Installation
+
+You can install _bw-functional_ via [pip] from [PyPI]:
+
+```console
+$ pip install bw-functional
+```
+
+[//]: # (It is also available on `anaconda` using `mamba` or `conda` at the `cmutel` channel:)
+
+[//]: # ()
+[//]: # (```console)
+
+[//]: # (mamba install -c conda-forge -c cmutel multifunctional)
+
+[//]: # (```)
+
+## Usage
+
+Multifunctional activities can lead to linear algebra problems which don't have exactly one solution. Therefore, we commonly need to apply a handling function to either partition such activities, or otherwise manipulate their data such that they allow for the creation of a square and non-singular technosphere matrix.
+
+This library is designed around the following workflow:
+
+Users create and register a `bw_functional.FunctionalSQLiteDatabase`. Registering this database must include the database metadata key `default_allocation`, which refers to an allocation strategy function present in `bw_functional.allocation_strategies`.
+
+```python
+import bw_functional
+mf_db = bw_functional.FunctionalSQLiteDatabase("emojis FTW")
+mf_db.register()
+```
+
+Multifunctional process(es) are created and written to the `FunctionalSQLiteDatabase`. A multifunctional process is any process with multiple "functions", either outputs (products) and/or input (reducts).
+
+```python
+mf_data = {
+    ("emojis FTW", "😼"): {
+        "type": "product",
+        "name": "meow",
+        "unit": "kg",
+        "processor": ("emojis FTW", "1"),
+        "properties": {
+            "price": {'unit': 'EUR', 'amount': 7, 'normalize': True},
+            "mass": {'unit': 'kg', 'amount': 1, 'normalize': True},
+        },
+    },
+    ("emojis FTW", "🐶"): {
+        "type": "product",
+        "name": "woof",
+        "unit": "kg",
+        "processor": ("emojis FTW", "1"),
+        "properties": {
+            "price": {'unit': 'EUR', 'amount': 12, 'normalize': True},
+            "mass": {'unit': 'kg', 'amount': 4, 'normalize': True},
+        },
+    },
+    ("emojis FTW", "1"): {
+        "name": "process - 1",
+        "location": "somewhere",
+        "exchanges": [
+            {
+                "type": "production",
+                "input": ("emojis FTW", "😼"),
+                "amount": 4,
+            },
+            {
+                "type": "production",
+                "input": ("emojis FTW", "🐶"),
+                "amount": 6,
+            },
+        ],
+    }
+}
+```
+LCA calculations can then be done as normal. See `dev/basic_example.ipynb` for a simple example.
+
+### Substitution
+
+_WORK IN PROGRESS_
+
+### Built-in allocation functions
+
+`bw-functional` includes the following built-in allocation functions:
+
+* `manual_allocation`: Does allocation based on the "allocation" field of the Product. Doesn't normalize by amount of production exchange.
+* `equal`: Splits burdens equally among all functional edges.
+
+You can also do property-based allocation by specifying the property label in the `allocation` field of the Process.
+
+## Technical notes
+
+### Process-specific allocation strategies
+
+Individual processes can override the default database allocation by specifying their own `allocation`:
+
+```python
+import bw2data as bd
+node = bd.get_activity(database="emojis FTW", code="1")
+node["allocation"] = "mass"
+node.save()
+```
+
+## How does it work?
+
+Recent Brightway versions allow users to specify which graph nodes types should be used when building matrices, and which types can be ignored. We create a multifunctional process node with the type `multifunctional`, which will be ignored when creating processed datapackages. However, in our database class `FunctionalSQLiteDatabase` we change the function which creates these processed datapackages to load the multifunctional processes, perform whatever strategy is needed to handle multifunctionality, and then use the results of those handling strategies (e.g. monofunctional processes) in the processed datapackage.
+
+We also tell `MultifunctionalDatabase` to load a new `ReadOnlyProcess` process class instead of the standard `Activity` class when interacting with the database. This new class is read only because the data is generated from the multifunctional process itself - if updates are needed, either that input process or the allocation function should be modified.
+
+## Contributing
+
+Contributions are very welcome.
+To learn more, see the [Contributor Guide][Contributor Guide].
+
+## License
+
+Distributed under the terms of the [BSD 3 Clause license][License],
+_multifunctional_ is free and open source software.
+
+## Issues
+
+If you encounter any problems,
+please [file an issue][Issue Tracker] along with a detailed description.
+
+
+<!-- github-only -->
+
+[command-line reference]: https://multifunctional.readthedocs.io/en/latest/usage.html
+[License]: https://github.com/brightway-lca/multifunctional/blob/main/LICENSE
+[Contributor Guide]: https://github.com/brightway-lca/multifunctional/blob/main/CONTRIBUTING.md
+[Issue Tracker]: https://github.com/brightway-lca/multifunctional/issues
+
+
+## Building the Documentation
+
+You can build the documentation locally by installing the documentation Conda environment:
+
+```bash
+conda env create -f docs/environment.yml
+```
+
+activating the environment
+
+```bash
+conda activate sphinx_multifunctional
+```
+
+and [running the build command](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#sphinx-build):
+
+```bash
+sphinx-build docs _build/html --builder=html --jobs=auto --write-all; open _build/html/index.html
+```

bw_functional-0b79/README.md

@@ -0,0 +1,173 @@
+# bw-functional
+
+[![PyPI](https://img.shields.io/pypi/v/bw-functional.svg)][pypi status]
+[![Status](https://img.shields.io/pypi/status/bw-functional.svg)][pypi status]
+[![Python Version](https://img.shields.io/pypi/pyversions/bw-functional)][pypi status]
+[![License](https://img.shields.io/pypi/l/bw-functional)][license]
+
+[![Read the documentation at https://multifunctional.readthedocs.io/](https://img.shields.io/readthedocs/multifunctional/latest.svg?label=Read%20the%20Docs)][read the docs]
+[![Tests](https://github.com/mrvisscher/bw-functional/actions/workflows/python-test.yml/badge.svg)][tests]
+[![Codecov](https://codecov.io/gh/brightway-lca/multifunctional/branch/main/graph/badge.svg)][codecov]
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
+
+[pypi status]: https://pypi.org/project/multifunctional/
+[read the docs]: https://multifunctional.readthedocs.io/
+[tests]: https://github.com/brightway-lca/multifunctional/actions?workflow=Tests
+[codecov]: https://app.codecov.io/gh/brightway-lca/multifunctional
+[pre-commit]: https://github.com/pre-commit/pre-commit
+[black]: https://github.com/psf/black
+
+Adding functions to Brightway processes
+
+## Installation
+
+You can install _bw-functional_ via [pip] from [PyPI]:
+
+```console
+$ pip install bw-functional
+```
+
+[//]: # (It is also available on `anaconda` using `mamba` or `conda` at the `cmutel` channel:)
+
+[//]: # ()
+[//]: # (```console)
+
+[//]: # (mamba install -c conda-forge -c cmutel multifunctional)
+
+[//]: # (```)
+
+## Usage
+
+Multifunctional activities can lead to linear algebra problems which don't have exactly one solution. Therefore, we commonly need to apply a handling function to either partition such activities, or otherwise manipulate their data such that they allow for the creation of a square and non-singular technosphere matrix.
+
+This library is designed around the following workflow:
+
+Users create and register a `bw_functional.FunctionalSQLiteDatabase`. Registering this database must include the database metadata key `default_allocation`, which refers to an allocation strategy function present in `bw_functional.allocation_strategies`.
+
+```python
+import bw_functional
+mf_db = bw_functional.FunctionalSQLiteDatabase("emojis FTW")
+mf_db.register()
+```
+
+Multifunctional process(es) are created and written to the `FunctionalSQLiteDatabase`. A multifunctional process is any process with multiple "functions", either outputs (products) and/or input (reducts).
+
+```python
+mf_data = {
+    ("emojis FTW", "😼"): {
+        "type": "product",
+        "name": "meow",
+        "unit": "kg",
+        "processor": ("emojis FTW", "1"),
+        "properties": {
+            "price": {'unit': 'EUR', 'amount': 7, 'normalize': True},
+            "mass": {'unit': 'kg', 'amount': 1, 'normalize': True},
+        },
+    },
+    ("emojis FTW", "🐶"): {
+        "type": "product",
+        "name": "woof",
+        "unit": "kg",
+        "processor": ("emojis FTW", "1"),
+        "properties": {
+            "price": {'unit': 'EUR', 'amount': 12, 'normalize': True},
+            "mass": {'unit': 'kg', 'amount': 4, 'normalize': True},
+        },
+    },
+    ("emojis FTW", "1"): {
+        "name": "process - 1",
+        "location": "somewhere",
+        "exchanges": [
+            {
+                "type": "production",
+                "input": ("emojis FTW", "😼"),
+                "amount": 4,
+            },
+            {
+                "type": "production",
+                "input": ("emojis FTW", "🐶"),
+                "amount": 6,
+            },
+        ],
+    }
+}
+```
+LCA calculations can then be done as normal. See `dev/basic_example.ipynb` for a simple example.
+
+### Substitution
+
+_WORK IN PROGRESS_
+
+### Built-in allocation functions
+
+`bw-functional` includes the following built-in allocation functions:
+
+* `manual_allocation`: Does allocation based on the "allocation" field of the Product. Doesn't normalize by amount of production exchange.
+* `equal`: Splits burdens equally among all functional edges.
+
+You can also do property-based allocation by specifying the property label in the `allocation` field of the Process.
+
+## Technical notes
+
+### Process-specific allocation strategies
+
+Individual processes can override the default database allocation by specifying their own `allocation`:
+
+```python
+import bw2data as bd
+node = bd.get_activity(database="emojis FTW", code="1")
+node["allocation"] = "mass"
+node.save()
+```
+
+## How does it work?
+
+Recent Brightway versions allow users to specify which graph nodes types should be used when building matrices, and which types can be ignored. We create a multifunctional process node with the type `multifunctional`, which will be ignored when creating processed datapackages. However, in our database class `FunctionalSQLiteDatabase` we change the function which creates these processed datapackages to load the multifunctional processes, perform whatever strategy is needed to handle multifunctionality, and then use the results of those handling strategies (e.g. monofunctional processes) in the processed datapackage.
+
+We also tell `MultifunctionalDatabase` to load a new `ReadOnlyProcess` process class instead of the standard `Activity` class when interacting with the database. This new class is read only because the data is generated from the multifunctional process itself - if updates are needed, either that input process or the allocation function should be modified.
+
+## Contributing
+
+Contributions are very welcome.
+To learn more, see the [Contributor Guide][Contributor Guide].
+
+## License
+
+Distributed under the terms of the [BSD 3 Clause license][License],
+_multifunctional_ is free and open source software.
+
+## Issues
+
+If you encounter any problems,
+please [file an issue][Issue Tracker] along with a detailed description.
+
+
+<!-- github-only -->
+
+[command-line reference]: https://multifunctional.readthedocs.io/en/latest/usage.html
+[License]: https://github.com/brightway-lca/multifunctional/blob/main/LICENSE
+[Contributor Guide]: https://github.com/brightway-lca/multifunctional/blob/main/CONTRIBUTING.md
+[Issue Tracker]: https://github.com/brightway-lca/multifunctional/issues
+
+
+## Building the Documentation
+
+You can build the documentation locally by installing the documentation Conda environment:
+
+```bash
+conda env create -f docs/environment.yml
+```
+
+activating the environment
+
+```bash
+conda activate sphinx_multifunctional
+```
+
+and [running the build command](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#sphinx-build):
+
+```bash
+sphinx-build docs _build/html --builder=html --jobs=auto --write-all; open _build/html/index.html
+```

bw_functional-0b79/bw_functional/__init__.py

@@ -0,0 +1,65 @@
+__all__ = (
+    "__version__",
+    "allocation_strategies",
+    "generic_allocation",
+    "Process",
+    "Product",
+    "MFExchange",
+    "MFExchanges",
+    "FunctionalSQLiteDatabase",
+    "property_allocation",
+)
+# import os
+__version__ = "0.0.2"
+
+from logging import getLogger
+
+from bw2data import labels
+from bw2data.subclass_mapping import DATABASE_BACKEND_MAPPING, NODE_PROCESS_CLASS_MAPPING
+
+from .allocation import allocation_strategies, generic_allocation, property_allocation
+from .database import FunctionalSQLiteDatabase
+from .node_classes import Process, Product
+from .edge_classes import MFExchange, MFExchanges
+
+log = getLogger(__name__)
+
+DATABASE_BACKEND_MAPPING["functional_sqlite"] = FunctionalSQLiteDatabase
+NODE_PROCESS_CLASS_MAPPING["functional_sqlite"] = FunctionalSQLiteDatabase.node_class
+
+
+if "waste" not in labels.node_types:
+    labels.lci_node_types.append("waste")
+if "nonfunctional" not in labels.node_types:
+    labels.other_node_types.append("nonfunctional")
+
+# make sure allocation happens on parameter changes
+def _init_signals():
+    from bw2data.signals import on_activity_parameter_recalculate
+
+    on_activity_parameter_recalculate.connect(_check_parameterized_exchange_for_allocation)
+
+def _check_parameterized_exchange_for_allocation(_, name):
+    import bw2data as bd
+    from bw2data.parameters import ParameterizedExchange
+    from bw2data.backends import ExchangeDataset
+
+    databases = [k for k, v in bd.databases.items() if v["backend"] == "functional_sqlite"]
+
+    p_exchanges = ParameterizedExchange.select().where(ParameterizedExchange.group==name)
+    exc_ids = [p_exc.exchange for p_exc in p_exchanges]
+    exchanges = ExchangeDataset.select(ExchangeDataset.output_database, ExchangeDataset.output_code).where(
+        (ExchangeDataset.id.in_(exc_ids)) &
+        (ExchangeDataset.type == "production") &
+        (ExchangeDataset.output_database.in_(databases))
+    )
+    process_keys = set(exchanges.tuples())
+
+    for key in process_keys:
+        process = bd.get_activity(key)
+        if not isinstance(process, Process):
+            log.warning(f"Process {key} is not an instance of Process, skipping allocation check.")
+            continue
+        process.allocate()
+
+_init_signals()

bw_functional-0b79/bw_functional/allocation.py

@@ -0,0 +1,142 @@
+from functools import partial
+from typing import Callable, List
+from logging import getLogger
+
+from .node_classes import Process, Product
+
+log = getLogger(__name__)
+
+
+def generic_allocation(
+    process: Process,
+    getter: lambda function: float(),
+) -> None:
+    """
+    Perform allocation for a multifunctional process using a specified getter function.
+
+    This function calculates allocation factors for each product in a multifunctional process
+    based on the values returned by the `getter` function. The allocation factor for each product
+    is determined by dividing the value returned by the `getter` function for that function by the
+    sum of all values returned by the `getter` function for all product in the process.
+
+    Args:
+        process (Process): The process object to allocate. Must be an instance of the `Process` class.
+        getter (Callable): A function that takes a `Product` object and returns a float value
+            used for allocation calculations.
+
+    Raises:
+        ValueError: If the `process` is not an instance of the `Process` class.
+        ZeroDivisionError: If the sum of allocation factors is zero.
+
+    Notes:
+        - Products with a positive `substitution_factor` and a non-zero `allocation_factor` will
+          have their `allocation_factor` reset to 0.0 and will not be included in the allocation.
+        - Products with a non-positive `substitution_factor` are included in the allocation.
+    """
+    # Ensure the process is a valid Process instance
+    if not isinstance(process, Process):
+        raise ValueError("Activity must be a Process instance")
+
+    # Return none if the process is not multifunctional
+    if not process.multifunctional:
+        return
+
+    # Collect products eligible for allocation (functions that are not subsituted)
+    products = []
+    for product in process.products():
+        if product.get("substitution_factor", 0) > 0 and product["allocation_factor"] > 0:
+            # Reset allocation factor for products with positive substitution factor
+            product["allocation_factor"] = 0.0
+            product.save()
+        elif product.get("substitution_factor", 0) <= 0:
+            # Include functions with non-positive substitution factor
+            products.append(product)
+
+    # Calculate the total value for allocation
+    total = sum([getter(product) for product in products])
+
+    # Raise an error if the total is zero to avoid division by zero
+    if not total:
+        raise ZeroDivisionError("Sum of allocation factors is zero")
+
+    # Calculate and assign allocation factors for each product
+    for i, product in enumerate(products):
+        factor = getter(product) / total
+        product["allocation_factor"] = factor
+        product.save()
+
+
+def get_property_value(
+    product: Product,
+    property_label: str,
+) -> float:
+    """
+    Retrieve the value of a specified property from a given function.
+
+    This function extracts the value of a property identified by `property_label` from the
+    `properties` dictionary of the provided `Product` object. If the property is marked
+    as normalized, the value is calculated by multiplying the `amount` in the processing
+    edge with the `amount` of the property.
+
+    Args:
+        product (Product): The product object from which the property value is retrieved.
+            Must be an instance of the `Product` class.
+        property_label (str): The label of the property to retrieve.
+
+    Returns:
+        float: The value of the specified property.
+
+    Raises:
+        ValueError: If the provided `product` is not an instance of the `Product` class.
+        KeyError: If the `properties` dictionary is missing or the specified property
+            is not found in the `properties` dictionary.
+
+    Notes:
+        - If the property is stored as a float (legacy format), a warning is logged.
+        - If the property is normalized, the value is calculated as:
+          `product.processing_edge["amount"] * prop["amount"]`.
+    """
+    if not isinstance(product, Product):
+        raise ValueError("Passed non-function for allocation")
+
+    props = product.get("properties")
+
+    if not props:
+        raise KeyError(f"Product {product} from process {product.processor} doesn't have properties")
+
+    prop = props.get(property_label)
+
+    if not prop:
+        raise KeyError(f"Product {product} from {product.processor} missing property {property_label}")
+
+    if isinstance(prop, float):
+        log.warning("Property using legacy float format")
+        return prop
+
+    if prop.get("normalize", False):
+        return abs(product.processing_edge["amount"]) * prop["amount"]
+    else:
+        return prop["amount"]
+
+
+def property_allocation(property_label: str) -> Callable:
+    """
+    Create a partial function for allocating a process based on a specific property.
+
+    This function generates a callable that performs allocation for a multifunctional process
+    using a getter function that retrieves the value of the specified property.
+
+    Args:
+        property_label (str): The label of the property to be used for allocation.
+
+    Returns:
+        Callable: A partial function that performs allocation using the specified property.
+    """
+    getter = partial(get_property_value, property_label=property_label)
+    return partial(generic_allocation, getter=getter)
+
+
+allocation_strategies = {
+    "equal": partial(generic_allocation, getter=lambda x: 1.0),
+    "manual": partial(generic_allocation, getter=lambda x: x.get("allocation_factor", 1)),
+}