Quickstart

This tutorial provides a brief step-by-step tutorial on how to download, set up PRIMO on your machine and run the examples provided. For a more detailed overview or for developers wishing to contribute to the PRIMO source code, please refer to sections Getting Started, Workflow and Examples.

The quickstart process is summarized by the following graphic and detailed in the subsequent sections.

_images/primo_quickstart.svg

We recognize that not every user has access to the required IT permissions on their machines to carry out the installation steps described below. For such users, we have made PRIMO available via a free and public service through Binder. This allows anyone to access, experiment with and run PRIMO from a web browser with no installation needed. For more details, please see: Using PRIMO on Binder.

Step 1: Download the source code from GitHub

  • Navigate to the GitHub Repository.

  • Click on the Green Code button and select Download Zip as shown here.

_images/download_zip.png

Fig. 2 Downloading code from GitHub

  • Save the zip in a preferred location and extract the contents. In example below, the code is stored at “C:\codes\primo-optimizer”

_images/location.png

Fig. 3 Extracted source code on Windows

Step 2: Install Python

  • Download installer from Anaconda .

  • Install Anaconda using the downloaded installer.

Step 3: Install PRIMO and required dependencies

  • Open the Anaconda prompt.

_images/anaconda.png

Fig. 4 Opening Anaconda prompt from Start Menu on Windows

  • Navigate to the directory where PRIMO source code is extracted. The path to this directory can be copy-pasted from Windows Explorer.

_images/path.png

Fig. 5 Obtaining the path where PRIMO source code is downloaded from Windows Explorer

  • Change active directory in Anaconda prompt with the following command. Please replace the <path> below with the location of the directory copied in the previous step.

    cd "<path>"
    
_images/cd.png

Fig. 6 Changing active directory

  • Create a new “primo” environment with all dependencies installed as follows:

    conda env create -f conda-env.yml
    
_images/environment.png

Fig. 7 Creating a new ‘primo’ environment

  • Activate the newly created “primo” environment as follows. Note that the command prompt says (primo) on the left instead of (base) once the environment is successfully activated:

    conda activate primo
    
_images/activate.png

Fig. 8 Activating the new ‘primo’ environment

  • PRIMO can also utilize other free or commercial optimization solvers if you have access to other solvers already.

Step 4: Run Examples in Jupyter Notebook

  • Launch Jupyter Notebook using the command below. A new window in your favorite internet browser should automatically open. You can also navigate to the notebook by going to one of the links that are displayed after running the command.

    jupyter notebook
    
_images/jupyter.png

Fig. 9 Launching Jupyter Notebook

_images/jupyter_window.png

Fig. 10 Jupyter Notebook Window in Browser

  • Navigate to “primo/demo” folder and open “PRIMO - Example_1.ipynb” by clicking on it.

_images/example.png

Fig. 11 Launching the example Notebook

  • Run all cells in the Jupyter Notebook.

_images/jupyter_run_all.png

Fig. 12 Run all cells in the Jupyter Notebook

  • The Notebook takes a few minutes to execute. On successful execution, a new file “PRIMO_Example_1_projects_results.xlsx” will be generated in the “primo\demo\PRIMO_Example_1_output” folder. PRIMO is now successfully installed and configured on your machine.

_images/results.png

Fig. 13 Output file generated on successful execution of the Notebook

Step 5: (Optional) Configure .env file with credentials

The Notebook “PRIMO - Example.ipynb” relies on randomized data for illustrative purposes. When working with real data sets and if desired, PRIMO can utilize external APIs such as the Bing Maps API and the US Census API . Please sign up for API keys by visiting the respective websites.

These API Keys can be utilized by providing them in a .env file. A .env file is a text file at the root folder of the project formatted as follows:

BING_API_KEY="My Bing maps key"
CENSUS_KEY="My census key"

For more details, please see API Keys.

_images/env_file.png

Fig. 14 .env file to provide API credentials

Note

The .env file has extension .env and no name. If you run into errors, please confirm the file is not accidentally named .env.txt.