Quick Start

Installing Software Elements

Temoa is implemented in Pyomo, which is in turn written in Python. Consequently, Temoa will run on Linux, Mac, Windows, or any operating system that Pyomo supports. There are several open source software elements required to run Temoa.

Using pip:

The standard way to install Temoa:

First, it is highly recommended to use a Python virtual environment to manage dependencies:

# Linux / macOS
$ python -m venv temoa_env
$ source temoa_env/bin/activate

# Windows (Command Prompt)
> python -m venv temoa_env
> temoa_env\Scripts\activate

# Windows (PowerShell)
PS> python -m venv temoa_env
PS> .\temoa_env\Scripts\Activate.ps1

Then, install Temoa:

# Install from PyPI
$ pip install temoa

# Get started
$ python -m temoa tutorial my_first_model
$ python -m temoa run my_first_model.toml

Using uv (Alternative):

For faster dependency resolution:

# Install uv (Linux / macOS)
$ curl -LsSf https://astral.sh/uv/install.sh | sh

# Install uv (Windows)
PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Create a uv initialized virtual environment
$ uv init <dir_name>
$ cd <dir_name>

# add Temoa from PyPI to pyproject.toml
$ uv add temoa

# Get started
$ uv run temoa tutorial my_first_model
$ uv run temoa run my_first_model.toml

For Contributors (Development Installation):

If you want to contribute to Temoa or modify the code:

# Clone the repository
$ git clone TemoaProject/temoa.git
$ cd temoa

# Install in development mode with uv (recommended)
$ uv sync --all-extras --dev

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

For detailed contribution guidelines, see CONTRIBUTING.md in the repository.

Solvers

A few notes for on the choice of solvers. Different solvers have widely varying solution times. If you plan to run Temoa with large datasets and/or conduct uncertainty analysis, you may want to consider installing commercial linear solvers such as CPLEX or Gurobi. Both offer free academic licenses.

For smaller models, Temoa has been tested with the HiGHS solver. HiGHS is automatically available when you install Temoa and requires no additional setup.

Running Temoa

To run the model, a configuration (config) file is needed. An example config file called config_sample.toml resides within the data_files/my_configs folder. Running the model with a config file allows the user to (1) use a sqlite database for storing input and output data, (2) create a formatted Excel output file, (2) specify the solver to use, (3) return the log file produced during model execution, (4) return the lp file utilized by the solver, and (5) to execute several of the modeling extensions.

$ temoa run config.toml

For general help, use –help:

$ temoa --help
  usage: temoa [-h] [--version] [--how-to-cite] COMMAND ...

  Tools for Energy Model Optimization and Analysis (Temoa)

  options:
    -h, --help       show this help message and exit
    --version        Show version information
    --how-to-cite    Show citation information

  commands:
    COMMAND
      run            Run a Temoa model
      validate       Validate a configuration file
      check-units    Check unit consistency in a database
      migrate        Migrate a database to the latest schema
      tutorial       Create tutorial files