Install CEA from source

This is recommended for advanced users and developers who want to contribute to the codebase.

The steps below will describe how to setup an environment for CEA by installing the required dependencies in a conda environment.

Note

Due to the complex dependencies of CEA, we currently do not support installing using pip directly from PyPI.

Prerequisites

  • Git

    Required to clone the CEA source code from GitHub. You can use Github Desktop if you are not comfortable with the command line.

  • Conda

    We recommend using Micromamba. It supports parallel downloading of package files using multi-threading and it natively supports conda-lock to skip the solving of dependencies (it saves a lot of time!).

    Attention

    If you are planning to use CEA in PyCharm, we recommend using the other ones listed below, since micromamba environments are not natively supported by PyCharm.

    However, you can use any other conda package manager that you might already have (e.g. Anaconda, Miniconda or Miniforge), we will install conda-lock in the following steps.

Installation

  1. Clone the CEA repository with the URL: https://github.com/architecture-building-systems/CityEnergyAnalyst

    Using the command line:

    git clone https://github.com/architecture-building-systems/CityEnergyAnalyst.git

    This will create a directory called CityEnergyAnalyst in your current directory.

  2. Install conda-lock to manage the dependencies of CEA:

    Skip this step if you are using micromamba or already have conda-lock installed.

    Using the command line:

    conda install --channel=conda-forge --name=base conda-lock

  3. Create CEA conda environment:

    We will be creating a conda environment called cea for the purpose of installing CEA.

    Using the conda-lock.yml file found in the root directory of the CEA repository, the environment will be created without having to solve for the dependencies.

    Using the command line (micromamba):

    micromamba create --name cea --file ./CityEnergyAnalyst/conda-lock.yml

    Using the command line (Conda):

    conda lock install --name cea --file ./CityEnergyAnalyst/conda-lock.yml

    Note

    If you are using Windows, the path separator would be \ instead of /

    e.g. .\CityEnergyAnalyst\conda-lock.yml instead of ./CityEnergyAnalyst/conda-lock.yml

  4. Install CEA in the cea environment:

    Activate the newly created environment and install CEA in the environment in editable mode (i.e. using the -e flag) using the path of the cloned repository.

    Using the command line (micromamba):

    micromamba activate cea
pip install -e ./CityEnergyAnalyst

    Using the command line (Conda):

    conda activate cea
pip install -e ./CityEnergyAnalyst

Now you should have a working installation of CEA!

You should be able to run the following command to see the help message:

Note

Remember to activate the cea environment before running any cea commands.

cea --help

usage: cea SCRIPT [OPTIONS]
   to run a specific script
usage: cea --help SCRIPT
    to get additional help specific to a script

To use it in Pycharm, see Access CEA using the Pycharm Interface.