From ba90442d496db911da5e45a99c342415f07841ff Mon Sep 17 00:00:00 2001 From: TimoDiepers Date: Tue, 30 Apr 2024 19:23:46 +0200 Subject: [PATCH 1/2] readme restructure --- README.md | 38 +++-- docs/content/data/example_ab_dark.svg | 128 +++++++++++++++ docs/content/data/example_ab_light.svg | 218 +++++++++++++++++++++++++ docs/content/theory.rst | 60 +++---- docs/index.md | 2 +- 5 files changed, 392 insertions(+), 54 deletions(-) create mode 100644 docs/content/data/example_ab_dark.svg create mode 100644 docs/content/data/example_ab_light.svg diff --git a/README.md b/README.md index 6521b95..75e3ac0 100644 --- a/README.md +++ b/README.md @@ -10,27 +10,31 @@ [![Conda Version](https://img.shields.io/conda/v/diepers/timex_lca?label=conda)](https://anaconda.org/diepers/timex_lca) ![Conda - License](https://img.shields.io/conda/l/diepers/timex_lca) -> ℹ️ *This package is still under development and some functionalities may change in the future.* +> ℹ️ _This package is still under development and some functionalities may change in the future._ -This is a python package for __time-explicit Life Cycle Assessment (LCA)__, building on top of the [Brightway](https://docs.brightway.dev/en/latest) LCA framework. +This is a python package for time-explicit Life Cycle Assessment that helps you assess the environmental impacts of products and processes over time. `timex_lca` builds on top of the [Brightway LCA framework](https://docs.brightway.dev/en/latest). -Time-explicit LCA aims to treat time more coherently in LCA, by __streamlining dynamic LCI and LCIA with prospective LCI databases__. As such, `timex_lca` enables the consideration of both the __timing of processes and emissions__ (e.g., end-of-life treatment occurs 20 years after construction), as well as the __changing state__ of the production system (e.g., increasing shares of renewable electricity in the future). +## Features +This package enables you to account for: +- **Timing of processes** throughout the supply chain (e.g., end-of-life treatment occurs 20 years after construction) +- **Variable** and/or **evolving** supply chains & technologies (e.g., increasing shares of renewable electricity in the future) +- **Timing of emissions** (by applying dynamic characterization functions) -Users can define the timing of process and emission exchanges as *temporal distributions*. `timex_lca` automatically propoagates the temporal information through the supply chain and sources the LCI data from the corresponding time explicit database. As the timing of each emission is recorded, `timex_lca` supports __dynamic LCIA methods__, which are provided for the climate change metrics radiative forcing and global warming potential. +You can define temporal distributions for process and emission exchanges, which are then *automatically* propagated through the supply chain and mapped to corresponding time-explicit databases. The resulting time-explicit LCI reflects the current technology status within the production system at the actual time of each process. Also, `timex_lca` keeps track of the timing of emissions which means that you can apply dynamic characterization functions. -Time explicit LCA can provide more representative LCA results for use cases, such as: -- products with variable or evolving production systems -- long-lived products -- products with biogenic carbon +## Use cases: +`timex_lca` is ideal for cases with: +- **Variable** or strongly **evolving production systems** +- **Long-lived** products +- **Biogenic** carbon -### Quick links: -All [documentation](https://timex.readthedocs.io/en/latest/), including detailed description of `timex_lca`. +## Documentation and Resources: +- [Full Documentation](https://timex.readthedocs.io/en/latest/) +- [Installation Guide](https://timex.readthedocs.io/en/latest/content/installation.html) +- [Example Notebook](https://github.com/TimoDiepers/timex/blob/main/notebooks/example_setac.ipynb) -[Installation instructions](https://timex.readthedocs.io/en/latest/content/installation.html) - -[Example notebook](https://github.com/TimoDiepers/timex/blob/main/notebooks/example_setac.ipynb) - - -### Questions and remarks: -For suggestions of improvements or reporting of bugs, please open an issue on the Github page, send a pull request or directly contact the maintainers. +### Contributing: +We welcome contributions! If you have suggestions or want to fix a bug, please: +- [Open an Issue](https://github.com/TimoDiepers/timex/issues) +- [Send a Pull Request](https://github.com/TimoDiepers/timex/pulls) \ No newline at end of file diff --git a/docs/content/data/example_ab_dark.svg b/docs/content/data/example_ab_dark.svg new file mode 100644 index 0000000..81f13bb --- /dev/null +++ b/docs/content/data/example_ab_dark.svg @@ -0,0 +1,128 @@ + + + + + + + B + + + A + „A + consumes + 2 + x + + 20% + of + B + at + t + A + and 2 + x + + 80% at + t + A + +1” + 2 + e + mission X + 5 + + t = + t + A + : 20% + t = t + A + +1: 80% + + t = + t + B + : 60% + t = t + B + +1: 40% + „B + emits + 5 + x + + 60% + of + X at + t + B + and 5 + x + + 40% at + t + B + +1” + + + + \ No newline at end of file diff --git a/docs/content/data/example_ab_light.svg b/docs/content/data/example_ab_light.svg new file mode 100644 index 0000000..6a2bbfa --- /dev/null +++ b/docs/content/data/example_ab_light.svg @@ -0,0 +1,218 @@ + + + + + + + + B + + + + + A + + + „A + + + consumes + + + 2 + + + x + + + 20% + + + of + + + B + + + at + + + t + + + A + + + and 2 + + + x + + + 80% at + + + t + + + A + + + +1” + + + 2 + + + e + + + mission X + + + 5 + + + + t = + + + t + + + A + + + : 20% + + + t = t + + + A + + + +1: 80% + + + + t = + + + t + + + B + + + : 60% + + + t = t + + + B + + + +1: 40% + + + „B + + + emits + + + 5 + + + x + + + 60% + + + of + + + X at + + + t + + + B + + + and 5 + + + x + + + 40% at + + + t + + + B + + + +1” + + + + + \ No newline at end of file diff --git a/docs/content/theory.rst b/docs/content/theory.rst index 5fa2e5b..9454616 100644 --- a/docs/content/theory.rst +++ b/docs/content/theory.rst @@ -1,16 +1,16 @@ Theory ======== -Here's a flow chart of how ``timex_lca`` works: +This section explains some of the theory behind ``timex_lca``. Check out the flow chart below for a quick overview of how it all comes together, and you'll find more detailed explanations of each step in the following subsections. .. image:: data/method_dark.svg :class: only-dark - :height: 500px + :height: 450px :align: center .. image:: data/method_light.svg :class: only-light - :height: 500px + :height: 450px :align: center User input @@ -20,34 +20,14 @@ User input 1. a static foreground system model with 2. temporal information using the attribute ``temporal_distribution`` on technosphere or biosphere exchanges in the foreground system modeel, and -3. a set of background databases, which must have a reference in time.` - -.. raw:: html - -
- - ℹ️ - More info on inputs - -
-
    -
  • The foreground system must have exchanges linked to one of the background databases. These exchanges at the intersection between foreground and background databases will be relinked by timex_lca.
    • -
  • Temporal distributions can occur at technosphere and biosphere exchanges and can be given in various forms, see BW Temporalis documentation, including absolute (e.g. 2024-03-18) or relative (e.g. 3 years before) nature and can have different temporal resolution (down to seconds but later aggregation supports resolutions down to hours).
    • -
  • Temporal distributions are optional. If none are provided, no delay between producing and consuming process is assumed and the timing of the consuming process is adopted also for the producing process.
    • -
-
-
- - +3. a set of background databases, which must have a reference in time. + +.. dropdown:: ℹ️ More info on inputs + + - The foreground system must have exchanges linked to one of the background databases. These exchanges at the intersection between foreground and background databases will be relinked by `timex_lca`. + - Temporal distributions can occur at technosphere and biosphere exchanges and can be given in various forms, see `bw_temporalis `__, including absolute (e.g. 2024-03-18) or relative (e.g. 3 years before) nature and can have different temporal resolution (down to seconds but later aggregation supports resolutions down to hours). + - Temporal distributions are optional. If none are provided, no delay between producing and consuming process is assumed and the timing of the consuming process is adopted also for the producing process. + Graph traversal ---------------- @@ -67,11 +47,19 @@ We recommend aligning ``temporal_grouping``, which defaults to 'year', to align For a simple example that consists of the following system: a process A that consumes an exchange b from a process B, which emits an emission x and both the exchange b and the emission x occur at a certain point in time - (add flowchart dummy system) - the timeline would look like this: + .. image:: data/example_ab_dark.svg + :class: only-dark + :height: 300px + :align: center - + .. image:: data/example_ab_light.svg + :class: only-light + :height: 300px + :align: center + + | + The resulting timeline looks like this: +-------+-----------+----------+-----------------+ | time | producer | consumer | amount | @@ -90,8 +78,8 @@ Available matching strategies are: closest database or linear interpolation betw Modified matrices ------------------ -.. _`BW_processing`: https://github.com/brightway-lca/bw_processing?tab=readme-ov-file -``timex_lca`` now modifies the technopshere and biosphere matrices using ``datapackages`` from `BW_processing`_. +.. _`bw_processing`: https://github.com/brightway-lca/bw_processing?tab=readme-ov-file +``timex_lca`` now modifies the technopshere and biosphere matrices using ``datapackages`` from `bw_processing`_. Technosphere matrix modifications: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/index.md b/docs/index.md index 05bf899..a8e8df5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -> ⚠️ This is a work in progress. Please refer to the [Timex Readme on GitHub](https://github.com/TimoDiepers/timex) for now. +> ⚠️ This package is still under development and some functionalities may change in the future. # `timex_lca` From 8fb354f3c0f3bdbd5d0224f8f5d68172236c2152 Mon Sep 17 00:00:00 2001 From: Timo Diepers <90762029+TimoDiepers@users.noreply.github.com> Date: Tue, 30 Apr 2024 19:24:41 +0200 Subject: [PATCH 2/2] Update README.md --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 75e3ac0..bcf057b 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,7 @@ You can define temporal distributions for process and emission exchanges, which - [Installation Guide](https://timex.readthedocs.io/en/latest/content/installation.html) - [Example Notebook](https://github.com/TimoDiepers/timex/blob/main/notebooks/example_setac.ipynb) -### Contributing: - +## Contributing: We welcome contributions! If you have suggestions or want to fix a bug, please: - [Open an Issue](https://github.com/TimoDiepers/timex/issues) -- [Send a Pull Request](https://github.com/TimoDiepers/timex/pulls) \ No newline at end of file +- [Send a Pull Request](https://github.com/TimoDiepers/timex/pulls)