MATER

Model-generation framework for stock-regulated socioeconomic metabolism, implemented as a Python library, in the MATER ecosystem.

MATER (Multi-regional Assessments of Technologies, Energy and Resources) is an open-source model-generation framework for stock-regulated socioeconomic metabolism, implemented as a Python library. A model is declared by data: the values given to the framework's variables decide its objects, processes and stocks, and how each stock is controlled.

Its central principle: a stock gap, the difference between a stock and its reference, activates processes, and these processes change the stocks through the flow balance.

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:

• labelled pandas inputs at the application boundary;
• one flat NumPy vector per variable in the simulation loop, over a generic engine that knows no model name;
• composable, documented equation extensions;
• checked inputs, kept at their given years, and outputs in the units of the inputs;
• 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 is in the 0.x series: a minor version may contain incompatible changes, which the CHANGELOG and the migration guides of the documentation list. Only the latest minor version is actively maintained; older releases remain available for reproducibility but do not normally receive fixes. Pin the version you use for reproducible work.

MATER 0.17 runs on a new engine (ADR-0011): a step of 365.25 days, outputs in the units of the inputs, explicit rules for absent values, preparation checks, and a new extension API. See the migration guide "Migrate from 0.16 to 0.17" in the documentation, from the 0.16.0 release or from the dev branch.

Projects based on 0.14.x should not assume compatibility with later versions: the variables of the model changed in 0.15, and no tool converts a project automatically yet. Pin 0.14.x while planning an explicit migration (the migration guide's section "Coming from 0.14").

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 composed implementation.

Each value can be:

• pd.Series for a constant input;
• pd.DataFrame for an input given at several dates, interpolated between them;
• None for an input that is not given (every input is optional).

When a variable is represented as a pd.DataFrame, its columns must be a pd.DatetimeIndex. The index levels are the variable's dimensions, and attrs["units"] holds its unit (one text, or a pd.Series with one unit per row).

MATER checks the inputs before the simulation starts: an input that no selected extension declares, a row given twice or a row without any value is an error that names it.

Quick start: run from pandas variables

Create a Python script named simulate.py:

"""
MATER simulation script.
"""

import mater

# These variables must be pandas Series or DataFrames following the
# declarations of the open-loop base and selected extensions.
#
# For the default model, see:
# mater.implementations.mater_default.definition.VARIABLES

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,
}

mater.run_from_dict(
    variables=variables,
    simulation_name="run0",
    extensions=("regulation", "capital_dynamics"),
    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 a workbook

MATER also reads workbooks, OpenDocument (.ods) or Excel (.xlsx), 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 a workbook.
"""

import mater

mater.run_from_excel(
    file_path="mater_example.ods",
    simulation_name="run0",
    extensions=("regulation", "capital_dynamics"),
    simulation_start_time=2021,
    simulation_end_time=2100,
)

Run the script:

uv run python simulate.py

The workbook adapter converts the workbook into the same dictionary format expected by run_from_dict. mater_example.ods, the example model of the first-simulation tutorial, is in docs/source/tutorials/data.

Advanced APIs

Ordinary users only need imports from mater. Two deliberately separate modules expose advanced features:

• mater.io contains typed adapter descriptions such as ParquetOutput, ExcelInput and ParquetDatasetInput;
• mater.extensions contains the expert contract for declaring variables, relations and equations on NumPy vectors.

run_from_dict, run_from_excel and run_simulation also accept interpolation= (a method per input), on_step= (a function called after each step) and converged= (solve feedback loops within the step). mater.prepare, mater.load_prepared and mater.run_prepared prepare a model once, save it, and run it several times.

Keeping those objects out of the package root makes the common workflow small without hiding the customization points.

Default scientific composition

Every simulation starts from:

"mater_open_loop"

This base is the open loop, trade included: the flows of process activities, trade and end of life change the stocks. The default run then composes regulation (feedback control: stock gaps activate processes) and capital_dynamics (capital dynamics: the reference of capacity-providing stocks follows the activities that need them); the latter computes reference_stock and overlays the exogenous reference_stock_input.

It is implemented in:

mater.implementations.mater_default

Important modules include:

mater.implementations.mater_default.definition  # variables and the three extensions
mater.implementations.mater_default.equations  # relations, masks and equations

The default equations are:

• reference_stock (capital_dynamics)
• theoretical_flow and process (regulation)
• flow, transport_flow, end_of_life and stock (mater_open_loop)

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. Values are in the units of the inputs, rates per year, and each row carries its unit. MATER writes bounded batches during the simulation and creates the manifest once the simulation completes.

Reading outputs

Outputs are standard mater-interface Parquet Datasets. Read their metadata and validated Arrow batches with mater-interface:

from mater_interface.serializers.parquet import read_parquet

metadata, batches = read_parquet("outputs/first_run")
for batch in batches:
    print(batch.num_rows, batch.schema.names)

Convert individual Arrow batches to pandas only when a downstream analysis needs it.

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