temoa 4.0.0a1

Tools for Energy Model Optimization and Analysis

TEMOA Version 4.0.0a1

Overview

TEMOA (Tools for Energy Model Optimization and Analysis) is a sophisticated energy systems optimization framework that supports various modeling approaches including perfect foresight, myopic planning, uncertainty analysis, and alternative generation.

Quick Start

Using uv (Recommended)

The fastest way to get started with Temoa:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

Bleeding-edge nightly development installation:

In a directory initialized with uv (e.g., uv init .) run:

uv add temoa --default-index https://pypi.temoaproject.org/simple/ --index https://pypi.org/simple/

# or

pip install --index-url https://temoaproject.github.io/temoa-nightlies/simple/ temoa --extra-index-url https://pypi.org/simple/

Or clone the repository and install in development mode:

# Clone and setup development environment
git clone https://github.com/TemoaProject/temoa.git
cd temoa
uv sync --all-extras --dev

# Run your first model
uv run temoa tutorial my_first_model
uv run temoa run my_first_model.toml

Standard Installation

# Install from PyPI (not yet available)
pip install temoa

# Or install from source
pip install -e .

Get Started in 30 Seconds

# Create tutorial files
temoa tutorial quick_start

# Run the model
temoa run quick_start.toml

Package Structure

The Temoa package is organized into clear modules:

• temoa.core - Public API for end users (TemoaModel, TemoaConfig, TemoaMode)
• temoa.cli - Command-line interface and utilities
• temoa.components - Model components and constraints
• temoa.data_io - Data loading and validation
• temoa.extensions - Optional extensions for different modeling approaches
  • modeling_to_generate_alternatives - MGA analysis
  • method_of_morris - Sensitivity analysis
  • monte_carlo - Uncertainty quantification
  • myopic - Sequential decision making
• temoa.model_checking - Model validation and integrity checking
• temoa.data_processing - Output analysis and visualization
• temoa.utilities - Helper scripts and migration tools

Installation & Setup

Development Installation

For users who want to contribute or modify Temoa should install in development mode using uv:

# Clone repository
git clone https://github.com/TemoaProject/temoa.git
cd temoa

# Setup development environment with uv
uv sync --all-extras --dev

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

# Run type checking
uv run mypy

Command Line Interface

Temoa provides a modern, user-friendly CLI built with Typer:

Basic Commands

Run a model:

temoa run config.toml
temoa run config.toml --output results/
temoa run config.toml --build-only  # Build without solving

Validate configuration:

temoa validate config.toml
temoa validate config.toml --debug

Database migration:

temoa migrate old_database.sql --output new_database.sql
temoa migrate old_database.db --type db
temoa migrate old_database.sqlite --output migrated_v4.sqlite

Generate tutorial files:

temoa tutorial                    # Creates tutorial_config.toml and tutorial_database.sqlite
temoa tutorial my_model my_db     # Custom names

Global Options

temoa --version                   # Show version information
temoa --how-to-cite              # Show citation information
temoa --help                     # Full help

Using with uv

When working with the source code, use uv run to ensure you're using the correct dependencies:

uv run temoa run config.toml      # Run with project dependencies
uv run temoa validate config.toml # Validate configuration
uv run temoa tutorial my_first_model # Create tutorial files

Programmatic Usage

You can use Temoa as a Python library:

import temoa
from pathlib import Path
from temoa import TemoaModel, TemoaConfig, TemoaMode

# Create configuration
config = TemoaConfig(
    scenario="my_scenario",
    scenario_mode=TemoaMode.PERFECT_FORESIGHT,
    input_database=Path("path/to/input.db"),
    output_database=Path("path/to/output.db"),
    output_path=Path("path/to/output"),
    solver_name="appsi_highs"
)

# Build and solve model
model = TemoaModel(config)
result = model.run()  # Equivalent to: temoa run config.toml

# Check if run was successful
if result:
    print("Model solved successfully!")
else:
    print("Model failed to solve")

Database Setup

Quick Setup with Tutorial

The fastest way to get started:

temoa tutorial

This creates:

• tutorial_config.toml - Configuration file with example settings
• tutorial_database.sqlite - Sample database for learning

Migration from older versions:

# Migrate from v3.1 to v4
temoa migrate old_database_v3.1.sql --output new_database_v4.sql

# or for SQLite databases
temoa migrate old_database_v4.sqlite --output new_database_v4.sqlite

Configuration Files

A configuration file is required to run the model. The tutorial command creates a complete example:

scenario = "tutorial"
scenario_mode = "perfect_foresight"
input_database = "tutorial_database.sqlite"
output_database = "tutorial_database.sqlite"
solver_name = "appsi_highs"

Configuration Options

Field	Notes
Scenario Name	Name used in output tables (cannot contain '-' symbol)
Temoa Mode	Execution mode (PERFECT_FORESIGHT, MYOPIC, MGA, etc.)
Input/Output DB	Source and output database paths
Price Checking	Run pricing analysis on built model
Source Tracing	Verify commodity flow network integrity
Plot Network	Generate HTML network visualizations
Solver	Solver executable name (appsi_highs, cbc, gurobi, cplex, etc.)
Save Excel	Export core output to Excel files
Save LP	Save LP model files for external solving

Supported Modes

Perfect Foresight

Solves the entire model at once. Most common mode for optimization.

Myopic

Sequential solving through iterative builds. Required for stepwise decision analysis.

MGA (Modeling to Generate Alternatives)

Explores near cost-optimal solutions for robustness analysis.

SVMGA (Single Vector MGA)

Two-solve process focusing on specific variables in the objective.

Method of Morris

Limited sensitivity analysis of user-selected variables.

Build Only

Builds model without solving. Useful for validation and troubleshooting.

Typical Workflow

1. Setup: Create configuration and database files:

   temoa tutorial my_project
   

2. Configure: Edit the configuration file to match your scenario

3. Validate: Check configuration before running:

   temoa validate my_project_config.toml
   

4. Run: Execute the model:

   temoa run my_project_config.toml
   

5. Review: Check results in output_files/YYYY-MM-DD_HHMMSS/

6. Iterate: Modify configuration and run again

Advanced Features

Extensions

Temoa includes optional extensions for advanced analysis:

• Monte Carlo: Uncertainty quantification
• Stochastic Programming: Scenario-based optimization
• Method of Morris: Sensitivity analysis

Data Processing

• Excel output generation
• Graphviz network visualization
• Interactive network diagrams

Model Validation

• Built-in validation checks
• Commodity flow verification
• Price consistency analysis

Solver Dependencies

TEMOA requires at least one optimization solver:

• Free: HiGHS

  • Included via the highspy Python package (automatically installed with Temoa)
  • Default solver for tutorial and testing

• Free: CBC

  • Requires separate installation (see CBC documentation)
  • Alternative free solver option

• Commercial: Gurobi, CPLEX, or Xpress

  • Requires separate license and installation
  • See individual solver documentation

Troubleshooting

Solver Issues

If you encounter solver errors:

# For commercial solvers (Gurobi, CPLEX)
pip install ".[solver]"  # Include specific solver packages

# For free solver
temoa run config.toml --debug  # Get detailed error information

Documentation & Support

• Full Documentation: Built by following docs/README.md
• API Reference: See temoa.core module for public API
• GitHub Issues: Report bugs and request features
• Tutorials: Run temoa tutorial for guided examples

Code Style & Quality

For contributors:

• Ruff: Code formatting and linting
• mypy: Type checking
• pytest: Testing framework
• Pre-commit: Automated quality checks

See CONTRIBUTING.md for detailed development guidelines.

Citation

If you use Temoa in your research, please cite:

@article{hunter2013modeling,
  title={Modeling for insight using Tools for Energy Model Optimization and Analysis (Temoa)},
  journal={Energy Economics},
  volume={40},
  pages={339--349},
  year={2013},
  doi={10.1016/j.eneco.2013.07.014}
}

Or use: temoa --how-to-cite