From 6d73e74b0c58a2bcbcd7f7c952d2a3287203cfdd Mon Sep 17 00:00:00 2001 From: Matthias Fripp Date: Tue, 13 Aug 2019 15:54:43 -1000 Subject: [PATCH] Prefer simple conda installation in INSTALL.md --- CHANGELOG.txt => CHANGELOG.md | 28 +++++ INSTALL | 202 ---------------------------------- INSTALL.md | 154 ++++++++++++++++++++++++++ 3 files changed, 182 insertions(+), 202 deletions(-) rename CHANGELOG.txt => CHANGELOG.md (89%) delete mode 100644 INSTALL create mode 100644 INSTALL.md diff --git a/CHANGELOG.txt b/CHANGELOG.md similarity index 89% rename from CHANGELOG.txt rename to CHANGELOG.md index 9a31f5b6f..55d79ca81 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.md @@ -1,3 +1,31 @@ +------------------------------------------------------------------------------- +Switch 2.0.5 +------------------------------------------------------------------------------- +This release standardizes all inputs and outputs as .csv files. + +As usual, when you first solve an older model, Switch will prompt to backup and +upgrade the inputs directory. If you accept, it will convert the existing +tab-delimited *.tab files and most ampl-format *.dat files to comma-delimited +*.csv files. It is recommended that you update your model data preparation +scripts to create .csv files directly. Note that non-indexed parameters should +now be stored in .csv files with a header row listing the parameter names and a +single data row showing their values. + +All multi-value outputs from Switch are also now in comma-delimited .csv files, +instead of a mix of .csv, .tab and .txt files. (total_cost.txt is unchanged) + +This release also includes includes the following minor updates: + +- Updated installation instructions +- Switch version number and website are now shown in the startup banner when + running with --verbose flag; solve messages have also been improved slightly +- Some parsing errors for *.tab files have been fixed in the upgrade scripts; + this may cause errors during the upgrade process for input files that use + spaces instead of tabs and were previously upgraded by Switch, producing + malformed files. +- Fixed several bugs in the documentation and execution of the stochastic + examples that use the PySP module of the Pyomo package + ------------------------------------------------------------------------------- Switch 2.0.4 ------------------------------------------------------------------------------- diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 4e32e857f..000000000 --- a/INSTALL +++ /dev/null @@ -1,202 +0,0 @@ -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 -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. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..fdef517a9 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,154 @@ +# INTRODUCTION + +This repository contains code and example files for the Switch power system +planning model. Switch is written in the Python language and several other +open-source projects (notably Pyomo, Pandas and glpk). 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 will 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 possibly git. + + +# INSTALL CONDA AND PYTHON + +Download and install Miniconda from +https://docs.conda.io/en/latest/miniconda.html or Anaconda from +https://www.anaconda.com/distribution . We recommend using the 64-bit version +with Python 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 Windows Conda +environment or add packages to it if you select the option to install "just for +me". + +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 SWITCH AND ITS DEPENDENCIES + +After installing Anaconda or Miniconda, open an Anaconda Command Prompt +(Windows) or Terminal.app (Mac) and type the following command: + + conda install -c conda-forge switch_model + +This will install the `switch` command line utility, along with various software +used by Switch (the Pyomo optimization framework, Pandas data manipulation +framework and glpk numerical solver). + +If you would also like to enable automatic output graphs, run this command: + + conda install -c conda-forge ggplot + +If you would like to try the coincbc solver instead of glpk, you can run this +command: + + conda install coincbc + +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 + +At this point, you can solve example models or your own power system models. +See README for more information. + + +# 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: + +Professional: +https://www.gurobi.com/products/gurobi-optimizer/ +https://www.ibm.com/products/ilog-cplex-optimization-studio/pricing + +Academic: +https://www.gurobi.com/academia/ +https://developer.ibm.com/docloud/blog/2019/07/04/cplex-optimization-studio-for-students-and-academics/ + +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 or community versions (typically 1000 variables and constraints) +will not be enough for any realistic model. + + +# VIEW EXAMPLES + +If you want to view the Switch 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. + + +# DEVELOPER INSTALLATION (optional) + +Many people find it useful to browse and edit a "live" installation of Switch +that they also use to solve models. This supports a number of activities: + +- reading the documentation built into the switch_model modules +- reading the source code of the modules to understand the details of how Switch + works +- updating Switch or fixing bugs to meet local needs or contribute to the main + repository +- setting breakpoints for debugging +- switching between different versions of Switch +- trying pre-release branches of Switch + +To work this way, first install Switch as described above (this will install all +the Switch dependencies, even though you will later reinstall Switch itself). +Then, in a terminal window or Anaconda command prompt Anaconda command prompt, +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 to a directory called `switch`. + git clone https://github.com/switch-model/switch.git + + # Uninstall the previous copy of Switch and tell Python to use this one + # instead. 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 + 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.