flodym: A Python package for dynamic material flow analysis
flodym: A Python package for dynamic material flow analysis - Published in JOSS (2026)
Science Score: 87.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
○codemeta.json file
-
○.zenodo.json file
-
✓DOI references
Found 1 DOI reference(s) in JOSS metadata -
✓Academic publication links
Links to: joss.theoj.org -
○Committers with academic emails
-
○Institutional organization owner
-
✓JOSS paper metadata
Published in Journal of Open Source Software
Keywords from Contributors
Repository
library for material flow analysis models
Basic Info
- Host: GitHub
- Owner: pik-piam
- License: mit
- Language: Python
- Default Branch: main
- Homepage: https://flodym.readthedocs.io
- Size: 18.1 MB
Statistics
- Stars: 23
- Watchers: 2
- Forks: 6
- Open Issues: 19
- Releases: 14
Metadata Files
README.md
flodym
The flodym (Flexibe Open Dynamic Material Systems Model) library provides key functionality for building material flow analysis models, including
- the class MFASystem acting as a template (parent class) for users to create their own material flow models
- the class FlodymArray handling mathematical operations between multi-dimensional arrays
- different classes representing stocks accumulation, in- and outflows based on age cohort tracking and lifetime distributions. Those can be integrated in the MFASystem.
- different options for data input and export, as well as visualization
Thanks
flodym (flexible ODYM) is an adaptation of:
ODYM
Copyright (c) 2018 Industrial Ecology
author: Stefan Pauliuk, Uni Freiburg, Germany
https://github.com/IndEcol/ODYM
We gratefully acknowledge funding from the TRANSIENCE project, grant number 101137606, funded by the European Commission within the Horizon Europe Research and Innovation Programme, from the Kopernikus-Projekt Ariadne through the German Federal Ministry of Education and Research (grant no. 03SFK5A0-2), and from the PRISMA project funded by the European Commission within the Horizon Europe Research and Innovation Programme under grant agreement No. 101081604 (PRISMA).
Installation
flodym dependencies are managed with pip.
To install as a user: run python -m pip install flodym
To install as a developer:
- Clone the flodym repository using git.
- From the project main directory, run
pip install -e ".[tests,docs,examples]"to obtain all the necessary dependencies, including those for running the tests, making the documentation, and running the examples.
Note that it is advisable to do this within a virtual environment.
Why choose flodym?
MFA models mainly consist on mathematical operations on different multi-dimensional arrays.
For example, the generation of different waste types waste might be a 3D-array defined over the dimensions time $t$, region $r$ and waste type $w$, and might be calculated from multiplying end_of_life_products (defined over time, region, and product type $p$) with a waste_share mapping from product type to waste type.
In numpy, the according matrix multiplication can be carried out nicely with the einsum function, were an index string indicates the involved dimensions:
waste = np.einsum('trp,pw->trw', end_of_life_products, waste_share)
flodym uses this function under the hood, but wraps it in a data type FlodymArray, which stores the dimensions of the array and internally manages the dimensions of different arrays involved in mathematical operations.
With this, the above example reduces to
waste[...] = end_of_life_products * waste_share
This gives a flodym-based MFA models the following properties:
- Flexibility: When changing the dimensionality of any array in your code, you only have to apply the change once, where the array is defined, instead of adapting every operation involving it. This also allows, for example, to add or remove an entire dimension from your model with minimal effort.
- Simplicity: Since dimensions are automatically managed by the library, coding array operations becomes much easier. No knowledge about the einsum function, about the dimensions of each involved array or their order are required.
- Versatility: We offer different levels of flodym use: Users can choose to use the standard methods implemented for data read-in, system setup and visualization, or only use only some of the data types like
FlodymArray, and custom methods for the rest. - Robustness: Through the use of Pydantic, the setup of the system is type-checked, highlighting errors early-on. The data read-in performs extensive checks on data sorting and completeness.
- Performance: The use of numpy ndarrays ensures low model runtimes compared with dimension matching through pandas dataframes.
How to contribute
If you'd like to contribute, the issues page lists possible extensions and improvements. If you wish to contribute your own, just create a fork and open a PR!
To run the tests locally, install the package with test dependencies (pip install -e ".[tests]") and run:
pytest
Reporting problems & support
If you encounter a bug or unexpected behaviour, please open an issue on GitHub.
For questions and general support, use GitHub Discussions or contact jakob[dot]duerrwaechter[at]pik-potsdam.de.
<!-- stop parsing here on readthedocs -->
Documentation
See our readthedocs page for documentation!
The notebooks in the examples folder provide usage examples of the code.
Owner
- Name: Potsdam Integrated Assessment Modelling (PIAM)
- Login: pik-piam
- Kind: organization
- Location: Potsdam Institute for Climate Impact Research (PIK), Germany
- Website: https://www.pik-potsdam.de/
- Repositories: 50
- Profile: https://github.com/pik-piam
Tools developed for use with data and models related to PIK's research.
JOSS Publication
flodym: A Python package for dynamic material flow analysis
Authors
Potsdam Institute for Climate Impact Research, Energy Transition Lab, Potsdam, Germany
Potsdam Institute for Climate Impact Research, Energy Transition Lab, Potsdam, Germany
Potsdam Institute for Climate Impact Research, Energy Transition Lab, Potsdam, Germany
Potsdam Institute for Climate Impact Research, Energy Transition Lab, Potsdam, Germany, Interdisciplinary Transformation University, Energy Transition and Climate Futures, Linz, Austria
Editor
Marlin Arnz
Tags
material flow analysis (MFA) substance flow analysis (SFA) dynamic stock modelling industrial ecologyGitHub Events
Total
- Release event: 6
- Delete event: 7
- Pull request event: 61
- Fork event: 3
- Issues event: 11
- Watch event: 12
- Issue comment event: 8
- Push event: 79
- Pull request review comment event: 6
- Gollum event: 1
- Pull request review event: 32
- Create event: 13
Last Year
- Release event: 1
- Delete event: 5
- Pull request event: 28
- Fork event: 1
- Issues event: 1
- Watch event: 11
- Issue comment event: 6
- Push event: 46
- Pull request review comment event: 4
- Pull request review event: 23
- Create event: 7
Committers
Last synced: 8 days ago
Top Committers
| Name | Commits | |
|---|---|---|
| Jakob Duerrwaechter | j****r@p****e | 166 |
| pre-commit-ci[bot] | 6****] | 90 |
| Sally Dacie | s****a@p****e | 51 |
| Bennet Weiss | b****s@p****e | 31 |
| Merjo | m****k@p****e | 15 |
| copilot-swe-agent[bot] | 1****t | 13 |
| Sally Dacie | s****a@L****e | 4 |
| Gergo Suto | g****o@p****e | 2 |
| SallyDa | s****e@g****m | 1 |
| Leonie Schweiger | l****r@p****e | 1 |
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 12 days ago
All Time
- Total issues: 9
- Total pull requests: 55
- Average time to close issues: 5 months
- Average time to close pull requests: 6 days
- Total issue authors: 4
- Total pull request authors: 7
- Average comments per issue: 0.67
- Average comments per pull request: 0.2
- Merged pull requests: 38
- Bot issues: 0
- Bot pull requests: 10
Past Year
- Issues: 5
- Pull requests: 38
- Average time to close issues: 7 months
- Average time to close pull requests: 9 days
- Issue authors: 3
- Pull request authors: 6
- Average comments per issue: 0.6
- Average comments per pull request: 0.29
- Merged pull requests: 23
- Bot issues: 0
- Bot pull requests: 8
Top Authors
Issue Authors
- JakobBD (4)
- bennet21 (2)
- TimoDiepers (2)
- MagnusBoKarlsson (1)
Pull Request Authors
- JakobBD (36)
- pre-commit-ci[bot] (10)
- bennet21 (5)
- Copilot (1)
- Merjo (1)
- gergosuto (1)
- leonieschweiger (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 1
-
Total downloads:
- pypi 319 last-month
- Total dependent packages: 0
- Total dependent repositories: 0
- Total versions: 14
- Total maintainers: 1
pypi.org: flodym
- Documentation: https://flodym.readthedocs.io/
- License: mit
-
Latest release: 0.7.0
published 21 days ago
Rankings
Maintainers (1)
Dependencies
- PyYAML ^6.0
- matplotlib ^3.7.1
- numpy ^1.25.0
- pandas ^2.0.2
- pickle4 ^0.0.1
- plotly ^5.18.0
- python >=3.10,<3.13
- scipy ^1.11.0
- actions/checkout v4 composite
- actions/setup-python v3 composite
- Faker ==30.8.0
- PyYAML ==6.0.2
- annotated-types ==0.7.0
- attrs ==24.2.0
- charset-normalizer ==3.4.0
- colorama ==0.4.6
- contourpy ==1.3.0
- cycler ==0.12.1
- docformatter ==1.7.5
- et-xmlfile ==1.1.0
- fastjsonschema ==2.20.0
- fonttools ==4.54.1
- iniconfig ==2.0.0
- jsonschema ==4.23.0
- jsonschema-specifications ==2024.10.1
- jupyter_core ==5.7.2
- kiwisolver ==1.4.7
- matplotlib ==3.9.2
- nbformat ==5.10.4
- numpy ==2.1.2
- openpyxl ==3.1.5
- packaging ==24.1
- pandas ==2.2.3
- pickle4 ==0.0.1
- pillow ==11.0.0
- platformdirs ==4.3.6
- plotly ==5.24.1
- pluggy ==1.5.0
- polyfactory ==2.17.0
- pydantic ==2.9.2
- pydantic_core ==2.23.4
- pyparsing ==3.2.0
- pytest ==8.3.3
- python-dateutil ==2.9.0.post0
- pytz ==2024.2
- pywin32 ==308
- referencing ==0.35.1
- rpds-py ==0.20.0
- scipy ==1.14.1
- setuptools ==75.2.0
- six ==1.16.0
- tenacity ==9.0.0
- traitlets ==5.14.3
- typing_extensions ==4.12.2
- tzdata ==2024.2
- untokenize ==0.1.1