MATER

MATER simulates how the stocks of a society change year after year: vehicles, buildings, factories, materials, energy, natural resources. You describe a system in a spreadsheet, one sheet per variable, with the level that each stock should reach. MATER computes how much each process must run to bring each stock towards that level, and writes every stock, flow and activity, year by year.

MATER (Multi-regional Assessment of Technologies, Energy and Resources) is an open-source framework, written in Python, for dynamic material flow analysis (dMFA), dynamic input-output analysis and biophysical assessments of technologies, energy and resources. Its central principle: a stock gap, the difference between a stock and its reference (the level it should reach), activates processes, and these processes change the stocks through the flow balance.

Install

New to Python? The installation guide takes you from nothing to a working MATER on Windows, macOS or Linux, with uv, which installs Python for you.

With uv, in a project: uv add mater. With pip, in a virtual environment of Python 3.11 or later: pip install mater.

Run a model

Download the example workbook mater_example.ods, a car value chain. Save these lines as simulate.py beside it:

import mater

mater.run_from_excel(
    "mater_example.ods",
    simulation_name="first_run",
    simulation_start_time=2021,
    simulation_end_time=2100,
)

Then run the script from a terminal opened in that folder:

uv run python simulate.py

The results are written to outputs/first_run. The tutorial Run your first simulation opens them in a spreadsheet and explains them.

Documentation

The documentation has five parts: Get started (installation and tutorials), the User guide (one page per task), The model (concepts and equations), the Reference (variables, formats, Python API) and Development. The data formats shared with the other tools of MATER are documented by the MATER ecosystem.

Versions

MATER is in the 0.x series: a new minor version may change how a model is written or what it computes, and its changes are listed in the CHANGELOG and the upgrade guides of the documentation. Pin the version you use for a study. Only the latest minor version receives fixes. MATER 0.17 runs on a new engine; models of 0.16 need the steps of the guide "Upgrade from 0.16 to 0.17".

Cite MATER

If you use MATER in academic work, cite the software version you used (HAL record hal-05614380) and the thesis that introduced the framework:

François Verzier. Modélisation du métabolisme de la société et de ses trajectoires de transition biophysique. 2025. DOI: 10.70675/89172c3czbb2bz45abz8b5fza3bb49f30f92

Machine-readable software metadata are in codemeta.json.

License

MATER is distributed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later).

Contributing

Contributions are welcome: see CONTRIBUTING.md. To work on MATER itself:

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-dynamic-modeling/mater-project/mater.git
cd mater
uv sync --all-groups
uv tool install just-bin
just test
just docs-build