INTRODUCTION

This repository contains code and example files for the SWITCH power system
planning model. To use this model, you will need to install several things:

Python v2.7
    We have not tested this on version 3, and do not have immediate plans
    to do so. We have verified our code works with v2.7.9 and 2.7.10. We
    had some difficulties with our testing framework on v2.7.3.

A solver such as GLPK, Cbc [https://projects.coin-or.org/Cbc], cplex or gurobi.
    The solver performs the raw numerical computations needed to solve each
    model. GLPK is an established open source solver that is easy to install 
    on most platforms. We have andecdotal reports that Cbc tends to
    be significantly faster, but have had difficulties installing it
    on some platforms. Cplex tends to be fast, but is proprietary and
    expensive for non-academics. It is free for registered academics who
    use it for teaching or research.

git software (optional)
    This is useful for downloading SWITCH, upgrading to the latest version, 
    or contributing your changes back to the main project.
    
Python code for SWITCH and its dependencies

The instructions below show you how to install these components on a Linux, Mac
or Windows computer. We recommend that you use the Anaconda scientific
computing environment to install and run SWITCH. This provides an easy,
cross-platform way to install most of the resources that SWITCH needs, and it
avoids interfering with your system's built-in Python installation (if
present). The instructions below assume you wiil use the Anaconda distribution.
If you prefer to use a different distribution, you will need to adjust the
instructions accordingly.


INSTALL CONDA AND PYTHON

Download and install Anaconda from https://www.continuum.io/downloads or 
Miniconda from http://conda.pydata.org/miniconda.html . Make sure to select the
option to install Python 2.7. (SWITCH is not yet compatible with Python 3.x.).
These install a similar environment, but Anaconda installs more packages by 
default and Miniconda installs them as needed.

Note that you do not need administrator privileges to install the Conda 
environment or add packages to it. However, your firewall will need to allow 
external network access to add packages as described below.


INSTALL AN OPEN-SOURCE SOLVER

You can solve small models, including the SWITCH examples, using the open-source 
glpk solver. This can be installed as follows:

1. Open Terminal.app (OS X) or an Anaconda command prompt (Start -> Anaconda -> 
Anaconda Prompt)

2. Type this command and then press Enter or return:

conda install -c conda-forge glpk

Follow the prompts to install glpk.

In some cases, you may find the open-source coincbc solver is a little faster 
than glpk. You can install coincbc via the following command (currently only
provides packages for Linux and Mac OS X):

conda install -c conda-forge coincbc


INSTALL A PROPRIETARY SOLVER (OPTIONAL)

To solve larger models, you will need to install the cplex or gurobi solvers,
which are an order of magnitude faster than glpk or coincbc. Both of these have
free trials available, and are free long-term for academics. You can install
one of these now or after you install SWITCH. More information on these solvers
can be found at the following links:

cplex: 
https://www.ibm.com/developerworks/community/blogs/jfp/entry/free_cplex_trials?lang=en

gurobi: 
http://www.gurobi.com/downloads/download-center

INSTALL GIT SOFTWARE (OPTIONAL)

Open a Terminal window or Anaconda command prompt, as discussed earlier, then
run this command and follow the prompts:

conda install git


INSTALL SWITCH MODEL CODE AND DEPENDENCIES

Open a Terminal window or Anaconda command prompt. Then use the 'cd' and
'mkdir' commands to create and/or enter the directory where you would like to
store the SWITCH model code and examples. Once you are in that directory, run
the following commands (don't type the comments that start with '#'):

# download SWITCH
git clone https://github.com/switch-model/switch.git

# (If you didn't install git, just download a .zip file from 
# https://github.com/switch-model/switch, then unzip it to a folder called
# switch in the appropriate location.)

# install the SWITCH model code that you downloaded, and any required Python packages
cd switch
pip install --upgrade --editable .

The 'pip install command' adds the switch_mod package to your Python
installation. It also installs the Pyomo Python package, which SWITCH uses to
define and solve optimization models. (SWITCH uses Pyomo to define a model,
then Pyomo passes the model to the solver and receives the solution, then
SWITCH retrieves the solution from Pyomo.)

If you want to use certain advanced features of SWITCH, you should install the
"advanced" dependencies. These extra packages are used by the advanced demand
response system (in the hawaii package) and the progressive hedging examples.
You can install the advanced dependencies via the command below (you can use
this instead of the command above, or run it later to add these packages):

pip install --upgrade --editable .[advanced]


RUN TESTS

To test your installation, you can run "python run_tests.py".


SOLVE MODELS

At this point, you can solve example models or your own power system models.
See README for more information.


UPDATE TO LATEST VERSION OF SWITCH

You can pull the latest version of the SWITCH code and examples from github.com
at any time by launching a Terminal window or Anaconda prompt, then cd'ing into
the 'switch' directory and running this command:

git pull

This will attempt to merge your local changes with changes in the main
repository. If there are any conflicts, you should follow the instructions given
by the git command to resolve them.
