Skip to content

Commit

Permalink
Updated README instructions
Browse files Browse the repository at this point in the history
Included instructions for the executable version.

Updated solver installation instructions (e.g., cannot use conda for coincbc in Windows)
  • Loading branch information
rconcep authored Jun 2, 2019
1 parent bd5abc1 commit 13440d0
Showing 1 changed file with 34 additions and 12 deletions.
46 changes: 34 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,14 +53,29 @@ The software is designed to be used by anyone with an interest in performing ana
## Getting started
<a id="getting-started"></a>

### Requirements
### Installing from executable

#### Windows 10
For Windows 10 users, we will offer an executable version of QuESt. This version comes pre-packaged with its own Python environment (including Kivy) so no Python installation is required. Until further notice, you will still need to install a solver for Pyomo in order to solve optimization problems such as those in QuESt Valuation and QuESt BTM.

You can find the executable version with each release in the **Releases** section:
https://github.com/rconcep/snl-quest/releases

1. Download and extract the `.zip` that is *not* labeled "Source code."
2. Inside the extracted folder, there will be a lot of files and folders. Locate the `snl-quest-v{version number}.exe` file and run it.
3. A command prompt should open along with the QuESt GUI.

### Installing from source code

For all platforms, you can instead install QuESt using the codebase in this repository.

You will want to obtain the codebase for QuESt. You can do that by downloading a release version in a compressed archive from the "releases" tab on the GitHub repository page. Alternatively, you can clone this repository or download a compressed archive of it by clicking the "Clone or download" button on this page. We recommend keeping the QuESt files in a location where you have read/write permission. Once you have the codebase, follow the appropriate set of instructions for your operating system.

**Requirements**
* Python 3.6+
* Kivy 1.10.1+ and its dependencies
* Solver compatible with Pyomo

### Installation
You will want to obtain the codebase for QuESt. You can do that by downloading a release version in a compressed archive from the "releases" tab on the GitHub repository page. Alternatively, you can clone this repository or download a compressed archive of it by clicking the "Clone or download" button on this page. We recommend keeping the QuESt files in a location where you have read/write permission. Once you have the codebase, follow the appropriate set of instructions for your operating system.

#### Windows
1. Install Python, preferably via scientific distribution such as [Anaconda](https://www.anaconda.com/download/). Use the 64 or 32-Bit Graphical installer as appropriate.
2. Install Kivy. Check [here](https://kivy.org/docs/installation/installation-windows.html) for the latest instructions.
Expand All @@ -75,30 +90,37 @@ You will want to obtain the codebase for QuESt. You can do that by downloading a
``python setup.py develop`` This will check dependencies for QuESt and install them as needed.
4. Install a solver for Pyomo to use. See other sections for instructions on this.

#### Solvers for Pyomo
At least one solver compatible with Pyomo is required to solve optimization problems. For QuESt Valuation, a solver capable of solving linear programs is required.
### Solvers for Pyomo
At least one solver compatible with Pyomo is required to solve optimization problems. For QuESt Valuation, a solver capable of solving linear programs is required. GLPK is a suggested option.

##### Installing GLPK, IPOPT, or Coin CBC (via Anaconda)
#### Installing GLPK (for Windows via Anaconda)
If you've installed Python using Anaconda, you may be able to install several solvers through Anaconda's package manager with the following (according to Pyomo's [installation instructions](https://pyomo.readthedocs.io/en/latest/installation.html)):

``conda install -c conda-forge glpk ipopt coincbc``
``conda install -c conda-forge glpk``

##### Installing GLPK (for Windows)
#### Installing GLPK (for Windows)
1. Download and extract the executables for Windows linked [here](http://winglpk.sourceforge.net/).
2. The .dll and glpsol.exe files are in the `w32` and `w64` subdirectories for 32-Bit and 64-Bit Windows, respectively. These files need to be in the search path for Windows. The easiest way to do this is to move those files to the `C:\windows\system32` directory.
3. Try running the command ``glpsol`` in the command prompt (Windows) or terminal (OSX). If you receive a message other than something like "command not found," it means the solver is successfully installed.

##### Installing GLPK (for OSX)
#### Installing GLPK (for OSX)
You will need to either build GLPK from source or install it using the [homebrew](https://brew.sh/) package manager. This [blog post](http://arnab-deka.com/posts/2010/02/installing-glpk-on-a-mac/) may be useful.

#### Installing GLPK (for OSX via Anaconda)
If you've installed Python using Anaconda, you may be able to install several solvers through Anaconda's package manager with the following (according to Pyomo's [installation instructions](https://pyomo.readthedocs.io/en/latest/installation.html)):

``conda install -c conda-forge glpk``

##### Installing IPOPT (for Windows)
1. Download and extract the pre-compiled binaries linked [here](https://www.coin-or.org/download/binary/Ipopt/). Select the latest version appropriate for your system and OS.
2. Add the directory with the `ipopt.exe` executable file to your path system environment variable. For example, if you extracted the archive to `C:\ipopt`, then `C:\ipopt\bin` must be added to your path.
3. Try running the command ``ipopt`` in the command prompt (Windows) or terminal (OSX). If you receive a message other than something like "command not found," it means the solver is successfully installed.
Regardless of which solver(s) you install, remember to specify which of them to use in Settings within QuESt.

### Running QuESt
From the Anaconda Prompt or Command Prompt, run:
If you are using the executable version, simply run the `snl-quest-v{version number}.exe` file.

If you are running from the codebase, from the Anaconda Prompt or Command Prompt, run:
```
python main.py
```
Expand Down Expand Up @@ -245,4 +267,4 @@ No, but this is a known issue. The easiest workaround is to reset the entire wiz

> Sometimes the figures in the cost savings wizard report do not appear.
This is a known issue. You can try to generate the report again in order to fix it.
This is a known issue. You can try to generate the report again in order to fix it.

0 comments on commit 13440d0

Please sign in to comment.