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.
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.

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

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.

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.

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>"

Fig. 6 Changing active directory
Create a new “primo” environment with all dependencies installed as follows:
conda env create -f conda-env.yml

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

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

Fig. 9 Launching Jupyter Notebook

Fig. 10 Jupyter Notebook Window in Browser
Navigate to “primo/demo” folder and open “PRIMO - Example_1.ipynb” by clicking on it.

Fig. 11 Launching the example Notebook
Run all cells in the Jupyter Notebook.

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.

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.

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.