MATER

Scientific Python library for dynamic stock-flow modelling in the MATER ecosystem.

MATER (Multi-regional Assessments of Technologies, Energy and Resources) is an open-source Python library for building dynamic stock-flow models of socioeconomic systems.

MATER is designed to support:

• dynamic Material Flow Analysis (dMFA);
• dynamic Input-Output Analysis (dIOA);
• biophysical assessments of technologies, infrastructures, resources, materials and pollutants;
• modelling of constrained transition scenarios.

The package is organized around:

• multidimensional pandas variables;
• documented systems of equations called implementations;
• validated variable specifications;
• input and output adapters;
• a ports-and-adapters software architecture.

MATER is currently under active development. Equations, data examples and taxonomies may evolve in future versions.

Requirements

• Python 3.11 or higher

We recommend using one virtual environment per Python project to manage dependencies and maintain isolation.

You can use uv or pip.

Installation

Install MATER with uv:

uv add mater

Or with pip:

pip install mater

Versioning

MATER 0.15.0 is a major restructuring release.

It introduces a new package architecture, a new public input API based on run_from_dict, validated variable specifications, documented default equations, and a clearer separation between implementations, adapters, application services and core services.

MATER 0.15.x is the current development line.

Projects based on 0.14.x should not assume direct compatibility with 0.15.x. Only the latest minor of the current major is actively maintained; older releases remain available for reproducibility but do not normally receive fixes.

If you are starting a new project, use 0.15.x.

If your project already depends on 0.14.x, pin that version for reproducibility while planning an explicit migration.

Public input API

The recommended public input API of MATER is a dictionary mapping variable names to pandas objects:

dict[str, pd.Series | pd.DataFrame | None]

Each key is the name of a variable expected by the selected model implementation.

Each value can be:

• pd.Series for one simulation time step;
• pd.DataFrame for a full time series;
• None for variables that are not initialized yet and will be computed later.

When a variable is represented as a pd.DataFrame, its columns must be a pd.DatetimeIndex.

The selected model implementation validates the variables before the simulation starts.

Quick start: run from pandas variables

Create a Python script named simulate.py:

"""
MATER simulation script.
"""

from mater.main import run_from_dict

# These variables must be pandas Series or DataFrames following the
# specifications of the selected model implementation.
#
# For the default implementation, see:
# mater.implementations.mater_default.variable_specs

variables = {
    "stock": stock,
    "flow_balance": flow_balance,
    "process_capacity_assignment": process_capacity_assignment,
    "process_ref_capacity": process_ref_capacity,
    "allocation_input": allocation_input,
    "life_time_mean_value": life_time_mean_value,
    "reference_stock_input": reference_stock_input,
    "process_input": process_input,
}

run_from_dict(
    variables=variables,
    simulation_name="run0",
    implementations_name="mater_default",
    simulation_start_time=1901,
    simulation_end_time=2100,
)

Run the script:

uv run python simulate.py

By default, outputs are written to:

outputs/run0/

Convenience usage: run from Excel

MATER also provides an Excel input adapter as a convenience loader.

This is useful for examples, tests and manual input files. However, the recommended public API is run_from_dict.

"""
MATER simulation script using an Excel input file.
"""

from mater.main import run_from_excel

run_from_excel(
    file_path="input.xlsx",
    simulation_name="run0",
    implementations_name="mater_default",
    simulation_start_time=1901,
    simulation_end_time=2100,
)

Run the script:

uv run python simulate.py

The Excel adapter reads an Excel file and converts it into the same dictionary format expected by run_from_dict.

Default model implementation

The default model implementation is:

"mater_default"

It defines the default MATER variables, equations and validation rules.

It is implemented in:

mater.implementations.mater_default

Important modules include:

mater.implementations.mater_default.variable_specs
mater.implementations.mater_default.variables
mater.implementations.mater_default.equations

The default equations include:

• reference_stock_computation
• theoretical_flow_computation
• process_computation
• flow_computation
• transport_computation
• end_of_life_computation
• stock_computation

Outputs

Simulation outputs are written by the configured repository adapter.

By default, MATER uses a Parquet repository and writes results to:

outputs/<simulation_name>/

A typical output structure is:

outputs/
└── run0/
    ├── manifest.json
    └── observations/
        ├── stock/
        │   └── part-0.parquet
        ├── flow/
        │   └── part-0.parquet
        └── process/
            └── part-0.parquet

This is the versioned Parquet Dataset layout defined by mater-interface. MATER writes bounded batches during the simulation and creates the manifest once the simulation completes.

Reading outputs

Outputs can be loaded with pandas or with MATER repository utilities.

A simple pandas-based example:

from pathlib import Path

import matplotlib.pyplot as plt
import pandas as pd

stock = pd.read_parquet(Path("outputs") / "first_run" / "stock" / "data")

stock.unstack("time")["value"].loc[:, :, :, "in_use", :].T.plot()
plt.show()

The exact loading strategy depends on the repository adapter used for the simulation.

Documentation

The online documentation is available here:

https://isterre-dynamic-modeling.gricad-pages.univ-grenoble-alpes.fr/mater-project/mater/

The documentation follows the Diátaxis framework:

• tutorials for guided learning;
• how-to guides for practical modelling tasks;
• reference material for data formats and the Python API;
• explanations of the scientific model and software design.

Component-local architecture decisions and contribution guidance are provided as complementary sections.

For cross-project architecture, shared data contracts, governance and common conventions, see the MATER Ecosystem documentation. Those ecosystem-wide concerns are maintained separately from this library's scientific concepts, usage guidance and Python API reference.

Citation

If you use MATER in academic work, please cite the associated thesis and the software version used.

The scientific framework behind MATER is associated with:

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 provided in codemeta.json.

License

MATER is distributed under the terms of the GNU Lesser General Public License v3.0 or later.

SPDX identifier:

LGPL-3.0-or-later

Contributing

Contributions are welcome.

Please refer to the CONTRIBUTING.md file for development guidelines, testing instructions and contribution rules.

Development

Clone the repository:

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-dynamic-modeling/mater-project/mater.git
cd mater

Install dependencies:

uv sync

Install just (cross-platform via uv):

uv tool install just-bin

Or download the binary directly from the official releases page.

If you see a PATH warning, run uv tool update-shell and restart your terminal.

Run the test suite:

just test

Build the documentation locally:

just docs-build