# {{ 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://mater-framework.org)
[![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 run --example

# View results in examples/example_outputs/
```

> 💡 Tip: All commands support --help flag as well as --example flag to work with minimal example data. 

## Usage

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

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

Modify the scripts to transform your raw data to MATER-formatted input data.

Build your input data from the scripts:  
```bash
uv run mater-cli data build
```

### Dimensions Pipeline  
Map your 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
```

## Project Structure

```
{{ project_name }}/
├── config.toml                   # Main configuration
├── data/
│   ├── raw/                      # Your original datasets
│   ├── input/                    # MATER-formatted data
│   ├── dimensions_hierarchy/     # Dimensions mapping
│   └── references/               # Reference data provided by KER Team
├── transforms/
│   └── datasets/                 # Transformation scripts
├── 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
