# {{ project_name }}

[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![MATER](https://img.shields.io/badge/framework-MATER-orange.svg)](https://isterre-dynamic-modeling.gricad-pages.univ-grenoble-alpes.fr/mater-project/mater)
[![UV](https://img.shields.io/badge/managed_by-UV-blue.svg)](https://docs.astral.sh/uv/)
[![License](https://img.shields.io/badge/license-LGPLv3-blue.svg)](LICENSE)


**Generated MATER simulation project for {{ project_name }} using [init-mater-project](https://pypi.org/project/init-mater-project/).**

## Quick Start

```bash
# Install dependencies
uv sync

# Run example simulation
uv run mater-cli simulation run --example

# Visualise output
uv run mater-cli simulation serve --example
```

> 💡 Tip: All commands at any level support --help flag (_i.e._, `uv run mater-cli --help`, `uv run mater-cli simulation --help` or `uv run mater-cli simulation run --help`).

## CLI Documentation

Have access to an auto-generated documentation for all `mater-cli` commands:

```bash
# Build documentation once
make html

# Use live-reload during development
make livehtml
```

Documentation will be available at `docs/_build/html/index.html`

> **Note:** Documentation is auto-generated from CLI code using Sphinx and sphinx-click. Any changes to commands, options, or help text will automatically appear in the docs.

## Usage

### Configuration
Start by completing project configuration: open `config.toml` and update `[provider]` and `[metadata]` sections with your informations.

### Logging and Debugging

All operations are automatically logged in`logs/` folder to help diagnose bugs and errors.

### Data Pipeline
Add your datasets to `data/raw/`.

Generate transformation notebooks:  
```bash
uv run mater-cli data generate
```

> 💡 Tip: The interactive Jupyter notebooks are in `transforms/datasets/` : one notebook is generated by dataset.

Edit the generated notebooks to:

- Map your columns to MATER format
- Set correct `time`, `value`, `variable`, `unit`, `scenario`
- Define `dimensions_values`

Build your MATER-ready data by executing the whole notebook.

> 💡 Tip: The generated JSON files are in `data/input/` : one file is generated by notebook.

### Dimensions Pipeline  

#### (optional) Project dimensions

Create your own project dimensions reference, combining local and reference values.

A notebook template is proposed at `transforms/dimensions/project_dimensions.ipynb`.

Edit it to:  

- Import your dimensions files
- Map to MATER format
- Set correct `name`, `value`, `equivalence`, `parents_values`

Build your MATER-ready dimensions by executing the whole notebook.

> 💡 Tip: The generated JSON file is in `data/dimensions/`.

#### Simulation dimensions

Set in `config.toml` the reference to use: most likely `data/references/dimensions.json` or `data/dimensions/project_dimensions.json`.

Map input data dimensions to MATER references:  
```bash
uv run mater-cli dimensions map
```

Modify the mapping file, removing TODOs and defining your parent hierarchy.

Validate and resolve edits:  
```bash
uv run mater-cli dimensions map --mode resolve
```

Build your dimensions hierarchy:  
```bash
uv run mater-cli dimensions build
```

### Simulations Run 
Run a simulation with your data:  
```bash
uv run mater-cli simulation run
```

View variables and dimensions linked to the simulation:  
```bash
uv run mater-cli simulation list-variables
uv run mater-cli simulation list-dimensions
```

### Outputs Visualisation
Locally visualise your simulations outputs: 
```bash
uv run mater-cli simulation serve
```

## Project Structure

```
{{ project_name }}/
├── README.md                     # Quick Start Instructions
├── config.toml                   # Main configuration
├── data/
│   ├── raw/                      # Your original datasets
│   ├── input/                    # MATER-ready data
│   ├── dimensions/               # Dimensions-related files
│   └── references/               # Reference data provided by MATER Team
├── transforms/
│   └── datasets/                 # Interactive transformation notebooks
├── src/                          # Generated application code (CLI & app)
├── outputs/                      # Simulation results
└── examples/                     # Example data & outputs
```

## Configuration

All settings in `config.toml` - see inline comments for details.

Key sections:
- `[simulation]` - Time range, scenario, frequency
- `[paths]` - File and directory paths  
- `[provider]` - Your contact information
- `[metadata]` - Dataset source and project info

## Documentation

- **[Detailed Documentation](link-to-come)** — MkDocs with configuration, user guide, developer guide, testing, deployment, architecture
- **[License](LICENSE)** — LGPLv3 License details
