Installation guide for Mac OS

Working with the CityEnergyAnalyst (CEA) on a Mac OS system is a little bit messier than on Windows and requires using the Terminal to launch CEA. But don’t worry - it works!

There are two installation methods, you can either: (1) use the CEA source code from GitHub, or (2) use the CEA Docker image. The former option gives you full access to CEA but is significantly more cumbersome to install as it involves running a lot of commands on Terminal. The latter option is much easier to install but working in a virtual container on Docker takes some getting used to. Both options are perfectly suited for users, but only the full installation is suitable for developers.

Choose the one that suits your needs!

(1) Use the CEA source code from GitHub

If you would like to develop CEA, this will be your method. Follow these instructions to install the CityEnergyAnalyst (CEA) on a Mac system (tested with macOS Mojave 10.14.6) from the source

Attention

We advise to follow the guide precisely:

  • Be sure to USE conda env create NOT conda create familiar to experienced conda users. This command not only creates an environment, but also reads the environment.yml file, containing a list of packages (and versions) to install, as well as a definition of the channels to check.
  • If you need to create a conda environment for the CEA that has a specific name (the default is cea) then use the name parameter: conda env create --name your-env-name-here
  • CONDA_SUBDIR=osx-64 will be used when creating the CEA conda environment to support both Intel and Apple Silicon Macs (this will be removed once all dependencies have been ported to ARM). Instructions below will indicate where it is being used.
  • (Only applicable for Apple Silicon Macs) If at any point during installation or running CEA and it prompts you to install Rosetta, click install.
  • This guide SHOULD work for both Intel and Apple Silicon Macs. If you encounter any issues when installing on either, help us report it as an issue on our GitHub page.

Prerequisites

  • Download and install Homebrew.
  • (Optional) Download and install Github Desktop (64-bit). Only required if you are unfamiliar with using Terminal and/or git commands.
  • (Optional) Install Mamba. This will help to speed up the creation of the CEA conda environment.

Installation of the code base

Excluding the above software, CEA installation requires approximately 13 GB of storage (depending on your existing Python library) and 1 hour of your time.

Note

(Experimental) We have a script that can automate the process below. Just open a Terminal console and enter /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/architecture-building-systems/CityEnergyAnalyst/update-mac-installation/install/mac_installation.sh)" Continue on the next section to find out how to interact with CEA.

  1. Open GitHub Desktop from the start menu.
  2. Clone the CEA repository:
    1. Press Cmd+Shift+O (clone repository) and select the URL tab.
    2. Paste the CEA GitHub address: https://github.com/architecture-building-systems/CityEnergyAnalyst
    3. Click Clone, this will take ~ 5-10 minutes (Size 1.65 GB).
  3. Clone the CEA GUI repository:
    1. Press Cmd+Shift+O (clone repository) and select the URL tab.
    2. Paste the CEA GUI GitHub address: https://github.com/architecture-building-systems/CityEnergyAnalyst-GUI
    3. Click Clone, this will take ~ 5 minutes (Size 600MB).
  4. Install CEA:
    1. Open a Terminal console (you can find it in your Mac’s Applications folder).
    2. Type cd Documents/GitHub/CityEnergyAnalyst and press ENTER.
    3. Type CONDA_SUBDIR=osx-64 conda env create --name cea and press ENTER. (If mamba is installed, replace conda in command to mamba. i.e. CONDA_SUBDIR=osx-64 mamba env create --name cea.)
    4. Grab a cup of tea and some toast, this will take ~45 minutes.
    5. Type conda activate cea and press ENTER.
    6. Type pip install -e . and press ENTER (mind the dot ‘.’ included in this command!).
  5. Build the CEA dashboard GUI:
    1. Type cd .. and press ENTER, then type cd CityEnergyAnalyst-GUI and press ENTER.
    2. Install Yarn by typing brew install yarn and press ENTER.
    3. Type yarn and press ENTER.
    4. Type yarn package and press ENTER.
    5. You will find the CEA application in the folder /Users/your_name/Documents/GitHub/CityEnergyAnalyst-GUI/out/CityEnergyAnalyst-GUI-darwin-*
  6. Running CEA:
    • You can run CEA a few different ways (see Mac Interfaces below).
    • If you are familiar with running CEA on a Windows computer, please note that there are a few additional steps when running the dashboard on a Mac!

Attention

In order to run CEA on Mac, you will need to select the correct Daysim binaries:

  • If you are running the Building Solar radiation tool using the dashboard, make sure the parameter daysim-bin-directory (under Advanced) points to the correct Daysim binary folder (by default, this should be /Users/your_name/Documents/GitHub/CityEnergyAnalyst/setup/Dependencies/Daysim/mac).
  • If you are using the command line interface or Pycharm, you will need to modify the same parameter (i.e., config.radiation.daysim_bin_directory) in the config file (usually located in /Users/your_name/cea.config, where your_name represents your user name on your Mac).

Mac Interfaces

There are different ways in which you can interact with the code of CEA.

  1. The command line interface: This is the command line to all the commands of CEA from your computer terminal
  2. The dashboard: This a web-based interface to CEA, open source and developed by the CEA team.
  3. The Pycharm interface: this interface provides access to all the source code of CEA.

Command line interface

You can run the command line interface by on the Terminal by running the command conda activate cea.

That’s it! You can run the CEA command interface normally.

Dashboard (GUI)

In order to run the dashboard, you will need to do the following each time you want to start the dashboard:

  1. Open the Terminal (you can find it in your Mac’s Applications folder) and run the following command depending on your installation type:
  2. Type conda activate cea and press ENTER, then type cea dashboard and press ENTER.
  3. Wait for start socketio.run to appear in the Terminal before proceeding to the next step. (This might take a while if you are running this for the first time, around 3-5 min)
  4. Run the CEA dashboard application you created in the last step of the installation above (/Users/your_name/Documents/GitHub/CityEnergyAnalyst-GUI/out/CityEnergyAnalyst-GUI-darwin-*).

You can now run the CEA dashboard interface normally!

Here you can find a series of blog posts to help you get started!

Pycharm

The Pycharm interface can be helpful if you would like to contribute to CEA, but it requires a few steps to get it up and running. In order to access and work on the source code of CEA from pycharm do:

  1. Download and install Pycharm Community edition (64-bit) OR your own favorite editor.
  2. Open PyCharm from the start menu and open project CityEnergyAnalyst (stored where you downloaded CityEnergyAnalyst).
  3. Open File>Settings>Project:CityEnergyAnalyst>Project Interpreter>Project Interpreter.
  4. Click on the settings button (it looks like a wheel) next to the current interpreter path, and click Add.
  5. Click Conda Environment from the left hand list and select existing environment.
  6. Point to the location of your conda environment. It should look something like /Users/your_name/Miniconda2/envs/cea/python.exe or /Users/your_name/AppData/Local/conda/conda/envs/cea/python.exe where your_name represents your user name on your Mac.
  7. Click apply changes.

(2) Use the CEA docker image

If you would like using docker containers, follow these instructions to run CEA on a Mac OS system (tested with Mac OS Catalina). This method is suitable for users, but not developers. For developers, please refer to the second method below.

  1. Install Docker and run CEA:
    1. You can find instructions on how to do that here.
    2. If you only plan to run CEA from the command line interface, you’re done!
  2. If you would like to use the CEA dashboard, you will need to download and build it manually:
    1. Download and install Github Desktop (64-bit).
    2. Download and install Miniconda(64-bit) for Python 3.8.
    3. Download and install Homebrew.
    4. Clone the CEA GUI repository:
      1. Press Cmd+Shift+O (clone repository) and select the URL tab.
      2. Paste the CEA GUI GitHub address: https://github.com/architecture-building-systems/CityEnergyAnalyst-GUI
      3. Click Clone, this will take ~ 5 minutes (Size 600MB).
    5. Build the CEA dashboard GUI:
      1. Open a Terminal console (you can find it in your Mac’s Applications folder).
      2. Type cd Documents/GitHub/CityEnergyAnalyst-GUI and press ENTER.
    6. Install Yarn by typing brew install yarn and press ENTER.
    7. Type yarn and press ENTER.
    8. Type yarn package and press ENTER.
    9. You will find the CEA application in the folder /Users/your_name/Documents/GitHub/CityEnergyAnalyst-GUI/out/CityEnergyAnalyst-GUI-darwin-*
  3. Running CEA:
    • You can run CEA a couple of different ways (see Docker Interfaces below).
    • If you are familiar with running CEA on a Windows computer, please note that there are a few additional steps when running the dashboard on a Mac!

Docker Interfaces

There are different ways in which you can interact with the code of CEA.

  1. The command line interface: This is the command line to all the commands of CEA from your computer terminal
  2. The dashboard: This a web-based interface to CEA, open source and developed by the CEA team.
  3. The Pycharm interface: this interface provides access to all the source code of CEA.

Command line interface

In order to run the command line interface in Docker, you will need to run the following command instead: docker run --name cea_container -v path_to_your_cea_projects:/projects dockeruser/cea cea workflow --workflow /projects/workflow.yml

That’s it! You can run the CEA command interface normally.

Dashboard

In order to run the dashboard, you will need to do the following each time you want to start the dashboard:

  1. Open the Terminal (you can find it in your Mac’s Applications folder) and run the following command depending on your installation type:
  2. Type docker run -t -p 5050:5050 -v path_to_your_cea_projects:/projects dockeruser/cea.
  3. Run the CEA dashboard application you created in the last step of the installation above.

You can now run the CEA dashboard normally… well, mostly. You will need to pay attention to a few details, described below.

Since you will not be running CEA directly on your computer, you will need to select a project on your Docker container. So if your project is located, for example, in the directory /Users/username/Documents/CEA_projects/my_project you will need to select /projects/my_project as your project in the CEA Dashboard.

Also, note that your jobs in the dashboard might be listed as “pending” even when they have finished. If you would like to check if your job has finished, you can check the Terminal - it’s still running in the background.