flodym

The Flexibe Open Dynamic Material Systems Model library provides key functionality for building material flow analysis models.
https://github.com/pik-piam/flodym

Category: Industrial Ecology
Sub Category: Life Cycle Assessment

Last synced: about 2 hours ago
JSON representation

Repository metadata

library for material flow analysis models

Host: GitHub
URL: https://github.com/pik-piam/flodym
Owner: pik-piam
License: mit
Created: 2024-07-31T12:30:43.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2026-07-27T20:44:59.000Z (2 days ago)
Last Synced: 2026-07-27T22:13:46.962Z (2 days ago)
Language: Python
Homepage: https://flodym.readthedocs.io
Size: 27.3 MB
Stars: 29
Watchers: 3
Forks: 7
Open Issues: 19
Releases: 16
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff

flodym

PyPI - Version

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

flodym is based on the concepts of the Open Dynamic Material Systems Model ODYM
(Pauliuk & Heeren, 2020). It is a re-implementation with a fundamentally overhauled API, internal dimension management, dynamic stock model integration, and other added features. As a result, flodym enables users to write customized, flexible MFAs, designed for maintainability and future extension.

Installation

flodym is published on PyPI and can be installed with your preferred Python package installer.

For example, with pip run python -m pip install flodym.

To install as a developer:

Install uv.
Clone the flodym repository using git.
From the project root, run uv sync to create a virtual environment and install all development dependencies.

This workflow uses a project-local virtual environment (.venv) managed by uv.

Dimension Management

MFA models mainly consist of 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 cite

If you use this software in publications, please cite our article in the Journal of Open Source Software:

@article{
    Duerrwaechter2026,
    author = {Dürrwächter, Jakob and Hosak, Merlin and Weiss, Bennet and Ueckerdt, Falko},
    title = {flodym: A Python package for dynamic material flow analysis},
    journal = {Journal of Open Source Software},
    year = {2026},
    doi = {10.21105/joss.10105},
    url = {https://doi.org/10.21105/joss.10105},
    publisher = {The Open Journal},
    volume = {11},
    number = {119},
    pages = {10105}
}

flodym is based on the concepts of ODYM.
Please consider also citing the according publication: Pauliuk & Heeren, 2020.

Contributing

Contribution instructions and development setup is documented in CONTRIBUTING.md.

How to report problems and get 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.

Acknowledgements

We thank Stefan Pauliuk and the other contributors to ODYM, which forms the conceptual basis for flodym.

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).

Documentation

See our readthedocs page for documentation!

The notebooks in the examples folder provide usage examples of the code.

Citation (CITATION.cff)

cff-version: "1.2.0"
authors:
- family-names: Dürrwächter
  given-names: Jakob
  orcid: "https://orcid.org/0000-0001-8961-5340"
- family-names: Dacie
  given-names: Sally
- family-names: Hosak
  given-names: Merlin
  orcid: "https://orcid.org/0009-0005-7965-1846"
- family-names: Weiss
  given-names: Bennet
  orcid: "https://orcid.org/0009-0009-9859-9683"
- family-names: Ueckerdt
  given-names: Falko
  orcid: "https://orcid.org/0000-0001-5585-030X"
contact:
- family-names: Dürrwächter
  given-names: Jakob
  orcid: "https://orcid.org/0000-0001-8961-5340"
doi: 10.5281/zenodo.19064877
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Dürrwächter
    given-names: Jakob
    orcid: "https://orcid.org/0000-0001-8961-5340"
  - family-names: Hosak
    given-names: Merlin
    orcid: "https://orcid.org/0009-0005-7965-1846"
  - family-names: Weiss
    given-names: Bennet
    orcid: "https://orcid.org/0009-0009-9859-9683"
  - family-names: Ueckerdt
    given-names: Falko
    orcid: "https://orcid.org/0000-0001-5585-030X"
  date-published: 2026-03-30
  doi: 10.21105/joss.10105
  issn: 2475-9066
  issue: 119
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 10105
  title: "flodym: A Python package for dynamic material flow analysis"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.10105"
  volume: 11
title: "flodym: A Python package for dynamic material flow analysis"

Owner metadata

Name: Potsdam Integrated Assessment Modelling (PIAM)
Login: pik-piam
Email:
Kind: organization
Description: Tools developed for use with data and models related to PIK's research.
Website: https://www.pik-potsdam.de/
Location: Potsdam Institute for Climate Impact Research (PIK), Germany
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/29039634?v=4
Repositories: 50
Last ynced at: 2023-02-27T11:50:27.848Z
Profile URL: https://github.com/pik-piam

GitHub Events

Total

Release event: 6
Delete event: 8
Pull request event: 62
Fork event: 3
Issues event: 11
Watch event: 12
Issue comment event: 8
Push event: 93
Pull request review comment event: 6
Gollum event: 1
Pull request review event: 34
Create event: 15

Last Year

Delete event: 1
Pull request event: 10
Watch event: 9
Issue comment event: 4
Push event: 40
Pull request review comment event: 2
Pull request review event: 10
Create event: 6

Committers metadata

Last synced: 3 days ago

Total Commits: 422
Total Committers: 11
Avg Commits per committer: 38.364
Development Distribution Score (DDS): 0.576

Commits in past year: 151
Committers in past year: 7
Avg Commits per committer in past year: 21.571
Development Distribution Score (DDS) in past year: 0.589

Name	Email	Commits
Jakob Duerrwaechter	j**r@p**e	179
pre-commit-ci[bot]	6****]	99
Sally Dacie	s**a@p**e	51
Bennet Weiss	b**s@p**e	47
Merjo	m**k@p**e	15
copilot-swe-agent[bot]	1****t	13
Tobias Diez	c**e@t**m	10
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:

Issue and Pull Request metadata

Last synced: 5 days ago

Total issues: 9
Total pull requests: 81
Average time to close issues: 5 months
Average time to close pull requests: 11 days
Total issue authors: 4
Total pull request authors: 8
Average comments per issue: 0.67
Average comments per pull request: 0.36
Merged pull request: 55
Bot issues: 0
Bot pull requests: 12

Past year issues: 4
Past year pull requests: 52
Past year average time to close issues: N/A
Past year average time to close pull requests: 17 days
Past year issue authors: 3
Past year pull request authors: 7
Past year average comments per issue: 0.25
Past year average comments per pull request: 0.54
Past year merged pull request: 31
Past year bot issues: 0
Past year bot pull requests: 7

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/pik-piam/flodym

Top Issue Authors

JakobBD (4)
bennet21 (2)
TimoDiepers (2)
MagnusBoKarlsson (1)

Top Pull Request Authors

JakobBD (37)
tobiasdiez (16)
pre-commit-ci[bot] (12)
bennet21 (12)
Copilot (1)
Merjo (1)
gergosuto (1)
leonieschweiger (1)

Top Issue Labels

discussion (2)
enhancement (2)

Top Pull Request Labels

autorelease: pending (1)

Package metadata

Total packages: 1
Total downloads:
- pypi: 309 last-month
Total dependent packages: 0
Total dependent repositories: 0
Total versions: 16
Total maintainers: 1

pypi.org: flodym

Homepage:
Documentation: https://flodym.readthedocs.io/
Licenses: mit
Latest release: 0.8.1 (published 3 months ago)
Last Synced: 2026-07-24T19:19:23.142Z (5 days ago)
Versions: 16
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 309 Last month
Rankings:
- Dependent packages count: 9.761%
- Average: 32.353%
- Dependent repos count: 54.946%
Maintainers (1)
- JakobBD

Dependencies

pyproject.toml pypi

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

.github/workflows/main_actions.yml actions

actions/checkout v4 composite
actions/setup-python v3 composite

requirements.txt pypi

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

Score: 12.005668581185454

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

flodym

Repository metadata

README.md

flodym

Installation

Dimension Management

How to cite

Contributing

How to report problems and get support

Acknowledgements

Documentation

Citation (CITATION.cff)

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Package metadata

pypi.org: flodym

Dependencies