mater 0.15.0

Multi-regional Assessment of Technologies, Energy and Resources

MATER

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 Mass 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 presets;
• 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.10 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

---

Version status

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 presets, adapters, application services and core services.

MATER 0.15.x should be considered the new main development line.

Projects based on 0.14.x should not assume direct compatibility with 0.15.x. The 0.14.x series is treated as a legacy maintenance line for existing projects.

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

If your project already depends on 0.14.x, either stay on the 0.14.x maintenance line or plan an explicit migration.

---

Public input API

The stable public input contract 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 preset.

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 preset 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 preset.
#
# For the default preset, see:
# mater.presets.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",
    preset_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 stable 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",
    preset_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 preset

The default preset is:

"mater_default"

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

The default preset is implemented in:

mater.presets.mater_default

Important modules include:

mater.presets.mater_default.variable_specs
mater.presets.mater_default.variables
mater.presets.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/
    ├── stock/
    │   ├── metadata.json
    │   └── data/
    ├── flow/
    │   ├── metadata.json
    │   └── data/
    └── process/
        ├── metadata.json
        └── data/

Each variable folder contains:

• metadata.json, with variable-level metadata such as name and unit;
• a data/ folder containing repository-specific data files.

With the default Parquet repository, data are stored as .mater files.

---

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 includes:

• getting started guide;
• user guide;
• modelling concepts;
• default preset variables and equations;
• API reference;
• developer guide.

---

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

Run the test suite:

uv run pytest

Build the documentation locally:

uv run sphinx-build -b html docs/source docs/build/html