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 2.7 or 3.7
    Switch has been tested with Python 2.7.9 - 2.7.16 and 3.7.3. We expect it
    to work with later versions, and it may work with versions that are not too
    much earlier.

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 and Cbc are established open source solvers. CPLEX and Gurobi
    are 3-100 times faster, but are proprietary and expensive for
    non-academics. They are free for registered academics who use them for
    teaching or research.

Python packages that Switch depends on

Python code for Switch itself

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. In particular, it is possible to install Switch and
most of its dependencies using the pip package manager if you have that
installed and working well, but you will need to do additional work to install
glpk or coincbc and git.


INSTALL CONDA AND PYTHON

Download and install Anaconda from https://www.continuum.io/downloads or
Miniconda from http://conda.pydata.org/miniconda.html . You can install either
Python 2.7 or 3.7+. Anaconda and Miniconda 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.

If you want, this is a good point to create an Conda environment specifically
for using or testing Switch. See here for more details:
https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html


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 glpk

Follow the prompts to install glpk.

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

conda install -c conda-forge coincbc

Switch uses the glpk solver by default, but you can use the Cbc solver by
specifying '--solver cbc' on the 'switch solve' command line or in options.txt
(see README for more details).

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

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

For any meaningful-sized problem, you will need the unlimited-size versions of
these solvers, which will require either purchasing a license, using a
time-limited trial version, or using an academic-licensed version. The
small-size free versions (typically 1000 variables and constraints) will not be
enough for any realistic model.


INSTALL SWITCH DEPENDENCIES

Switch depends on several other packages to do its work. In particular, Switch
uses the Pyomo Python package to define the power system optimization model, and
then Pyomo passes the model to the solver and receives the solution, which is
then used by Switch.

These packages can easily be installed with the conda tool. First open a
Terminal window or Anaconda command prompt, as discussed earlier, and run the
command(s) below to install these dependencies.

All users should open a terminal window or Anaconda command prompt as discussed
above, then use these commands and follow the prompts to install the required
packages:

conda install -c conda-forge pyomo pint
conda install pandas testfixtures pip

If you want to generate annual summary plots, you should also install ggplot:

conda install -c conda-forge ggplot

If you plan to run the the progressive hedging examples, you will need to run
this command:

conda install sympy

If you plan to use the iterative demand response model with a custom, nonlinear
demand system, then you should add these packages:

conda install rpy2 scipy

If you will be using switch_model.hawaii.scenario_data to access the Hawaii data
warehouse (requires login credentials from Matthias Fripp at the University of
Hawaii), then you should add this:

conda install psycopg2-binary


INSTALL SWITCH (MINIMAL)

There are two ways to install the Switch software itself. The simplest way is
to open an Anaconda prompt or Terminal window and run this command:

pip install switch_model

If you use this method, Switch will be installed without any examples or tests.
If you want to view the source code and examples, you can find them at
https://github.com/switch-model/switch. You can also find the source code on
your computer in  $CONDA_PREFIX/lib/python3.7/site-packages/switch_model or
$CONDA_PREFIX/lib/python2.7/site-packages/switch_model.

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


INSTALL SWITCH (COMPLETE)

The other way of installing Switch takes some extra steps, but makes it easy to
view and edit the source code and examples. This is also recommended for users
who may want to contribute their changes back to the Switch project.

First, 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 '#'):

# Install git software manager.
conda install git

# Download Switch.
git clone https://github.com/switch-model/switch.git

# Tell Python where to find the switch_model package.
# Note that Python will always load switch_model directly from this directory,
# so you can edit it as needed and Python will see the changes.
cd switch
pip install --upgrade --editable .

# Run tests (optional)
python run_tests.py

# View switch_model code (optional)
cd switch_model
ls
cd ..

# View or run examples (optional)
cd examples
ls
cd <example dir>
switch solve

After this, you can pull the latest version of the Switch code and examples from
the main Switch repository 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 with changes in the main
repository. If there are any conflicts, you should follow the instructions given
by the git command to resolve them.

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