Installation guide for Mac OS

There are two installation methods on a Mac system (tested with macOS Mojave 10.14.6).

(1) From the Source: If you would like to develop CEA, this will be your method.
(2) As a Docker image: If you are not interested on developing CEA, this will be your method.

Choose the one that suits your needs!

(1) From the Source

Prerequisites

Download and install Homebrew. Upon finishing installing Homebrew, pay attention to the message reverted. You may also have to execute brew install node.
Download and install Github Desktop (64-bit).
Download and Install Micromamba. Upon finishing installing Micromamba, pay attention to the message reverted.

Installation

Fresh installation

Open GitHub Desktop from the start menu.
Clone the CEA repository with the following URL: https://github.com/architecture-building-systems/CityEnergyAnalyst
Clone the CEA GUI repository with the following URL: https://github.com/architecture-building-systems/CityEnergyAnalyst-GUI
Install CEA backend:
1. Open a Terminal console
2. Type cd ~/Documents/GitHub/CityEnergyAnalyst and press ENTER.
3. Type micromamba env create -n cea -f conda-lock.yml and press ENTER.
4. Type micromamba activate cea and press ENTER.
5. Type pip install -e . and press ENTER (mind the dot ‘.’!).
Build the CEA dashboard:
1. Type cd ~/Documents/GitHub/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 electron:build and press ENTER.
5. You will find the CEA dashboard in the folder /Users/your_name/Documents/GitHub/CityEnergyAnalyst-GUI/out/mac-*/CityEnergyAnalyst-GUI.app

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).

Update existing installation

These steps would only work if your current installation is installed using the steps above.

Update CEA backend:
1. Open a Terminal console
2. Type cd ~/Documents/GitHub/CityEnergyAnalyst and press ENTER.
3. Type git pull and press ENTER.
4. Type micromamba env remove -n cea and press ENTER.
5. Type micromamba env create -n cea -f conda-lock.yml and press ENTER.
6. Type micromamba activate cea and press ENTER.
7. Type pip install -e . and press ENTER (mind the dot ‘.’!).
Update the CEA Dashboard:
1. Type cd ~/Documents/GitHub/CityEnergyAnalyst-GUI and press ENTER.
2. Type git pull and press ENTER.
3. Type yarn and press ENTER.
4. Type yarn electron:build and press ENTER.
5. You will find the new CEA dashboard in the folder /Users/your_name/Documents/GitHub/CityEnergyAnalyst-GUI/out/mac-*/CityEnergyAnalyst-GUI.app

Interfaces

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

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

The command line interface and dashboard interface are included during the installation of CEA. Other interfaces require a few additional steps to get them up and running.

Running the CEA dashboard

In order to launch the CEA dashboard, you will need to do the following each time:

Open the Terminal
Type micromamba activate cea and press ENTER.
Type cea dashboard and press ENTER.
Wait for start socketio.run to appear (This might 3 min the first time)
Navigate your Finer to this location (/Users/your_name/Documents/GitHub/CityEnergyAnalyst-GUI/out/CityEnergyAnalyst-GUI-darwin-*)
Double click on the CEA Icon (CityEnergyAnalyst-GUI.app)
Wait for the CEA Dashboard to launch

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

Running CEA on 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:

Download and install Pycharm Community edition (64-bit) OR your own favorite editor.
Open PyCharm from the start menu and open project CityEnergyAnalyst (stored where you downloaded CityEnergyAnalyst).
Open File>Settings>Project:CityEnergyAnalyst>Project Interpreter>Project Interpreter.
Click on the settings button (it looks like a wheel) next to the current interpreter path, and click Add.
Click Conda Environment from the left hand list and select existing environment.
Point to the location of your conda environment. It should look something like /Users/your_name/mamba/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.
Click apply changes.

(2) As a 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.

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!
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:
  
  Press Cmd+Shift+O (clone repository) and select the URL tab.
  
  Paste the CEA GUI GitHub address: https://github.com/architecture-building-systems/CityEnergyAnalyst-GUI
  
  Click Clone, this will take ~ 5 minutes (Size 600MB).
5. Build the CEA dashboard GUI:
  
  Open a Terminal console (you can find it in your Mac’s Applications folder).
  
  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-*
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.

The command line interface: This is the command line to all the commands of CEA from your computer terminal
The dashboard: This a web-based interface to CEA, open source and developed by the CEA team.
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:

Open the Terminal (you can find it in your Mac’s Applications folder) and run the following command depending on your installation type:
Type docker run -t -p 5050:5050 -v path_to_your_cea_projects:/projects dockeruser/cea.
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.