All aboard the Open Climate Workbench train... lets begin
Introduction
The following guide will help you setup the recommended working environment for OCW power users.
This guide will focus on setup for OS X 10.8.x or newer (with Developer Tools already installed) and Ubuntu 12.04. It assumes you are familiar using a terminal.
For *nix Users
If you run some *nix variant you shouldn't have too much trouble following the guide.
Windows Users
If you're on Windows, please let us know what sort of troubles you run into so we can hopefully provide help for future users.
Get the Open Climate Workbench Source Code
There are a few possible ways to get the code.
Get the latest release
Grab the latest official release from Apache OCW website.
Early Releases
Recommended Release
Grab the latest code from the ASF (User)
If you're a user and you don't plan on contributing code back to the project you should pull the code from the primary project's git repository. You can download it into ~/climate with:
git clone http://git-wip-us.apache.org/repos/asf/climate.git
Grab the latest code from the ASF (Developer)
If you plan to help out the project and send in a patch (thanks by the way!) then you should fork the project on Github. After doing that you can clone the code into ~/climate with:
git clone https://github.com/<your Github username>/climate.git
Dependency Installation
Using Easy-OCW
Easy OCW is designed to make installing the necessary dependencies for OCW work as easy as possible. If you plan to use Easy-OCW please follow the instructions on the Easy-OCW page for further guidance.
Manually Installing Dependencies
If you decide that you want to manually install the necessary dependencies you can follow the below steps. If you're on a system that Easy-OCW doesn't support, writing a script for your installation process would be a good place to start contributing to the project!
Install VirtualEnv and VirtualEnvWrapper
virtualenv is a tool for creating isolated Python environments and virtualenvwrapper makes using virtualenv super easy. You can install both by running the following commands:
pip install virtualenv pip install virtualenvwrapper
If you don't have pip installed, you should check the pip documentation for guidance.
Now that we have this installed we need to create an environment into which we will install our dependencies.
We will create an environment called ocw that you should work on whenever you want to run the toolkit.
This makes sure that we don't clobber anything important on your system and keeps everything nicely separated.
mkvirtualenv ocw
When you are done using OCW you should run deactivate to deactivate the virtual environment. Later, if you want to use OCW you should run workon ocw to activate the virtual environment. Make sure you have it activated before you continue with the following steps!
Install Conda Dependencies
Option 1: Install Anaconda and various other dependencies
Install the Anaconda Scientific Python Distribution from Continuum Analytics.
The installation is very simple and the Continuum Analytics site should have all the information you need to get started. Be sure to allow the installation to update your PATH for you.
Install GEOS, Basemap, and other potentially missing dependencies
Basemap and its dependency GEOS aren't automatically included in Anaconda. However, it does include conda which makes installing things much easier. Run the following to install Basemap and all the necessary dependencies for it to work on your system. This will also check and install any other missing dependencies that Anaconda didn't provide you
cd $CLIMATE_ROOT/easy-ocw conda install --file ocw-conda-dependencies.txt
Option 2: Install conda manually instead of using Anaconda
Anaconda can be a bit bloated since we don't need a large majority of the packages that it includes. You can easily accomplish the same thing by manually installing conda, the package manager that Anaconda uses and installing the dependencies with that.
cd $CLIMATE_ROOT/easy-ocw pip install conda conda init conda install --file ocw-conda-dependencies.txt
If you didn't allow Anaconda to update your PATH, you may be told that the conda command cannot be found. Instead, you'll need to explicitly reference conda from the Anaconda install directory (default is ~/anaconda/bin) or update your PATH manually.
Install Additional Dependencies
There are a few more dependencies that you should install with pip.
cd $CLIMATE_ROOT/easy-ocw pip install -r ocw-pip-dependencies.txt
Make Everything Easier
The last thing we're going to do is make our ocw virtual environment a bit more helpful. Edit ~/.virtualenvs/postactivate in your favorite editor and add the following:
if [ $VIRTUAL_ENV == "$HOME/.virtualenvs/ocw" ] then # You want this to point to where ever you installed Anaconda. By default, this should work. PATH="$HOME/anaconda/bin":$PATH # This makes sure OCW is loaded properly when running python. Unfortunately the toolkit is # not installable at the moment so this step is necessary for the time being. export PYTHONPATH="$HOME/climate/:$HOME/climate/ocw/:$PYTHONPATH fi
This makes sure that whenever you are using the ocw virtual environment that the Anaconda Python is used (where all the awesome dependencies are installed!) and that your PYTHONPATH is set properly so the toolkit is loaded whenever you use Python.
Don't worry though, when you deactivate the virtual environment your original variable values will be reset, so none of this will clobber your other work!
Test Your Installation
The easiest way to test your installation is to run one of the example scripts in $HOME/climate/examples.
cd $HOME/climate/examples python simple_model_to_model_bias.py
If everything runs successfully you should see a plot similar to the one below in the examples folder.
Installing the OCW UI
If you would like to install and use the OCW-UI for running simple evaluations through your web browser, check the Open Climate Workbench User Interface Installation and Overview guide to get started.
Using the OCW VM
If you want to get up and running with OCW quickly and with minimal overhead consider using the OCW VM. You can read about how to build the VM on the OCW VM - A Self Contained OCW Environment page. The OCW VM gives you an isolated VM environment with OCW pre-setup for you so you can get up and running without installing dependencies or configuring your system.