👨🏼‍🏭 Kit Quick Start Guide

The following set-up instructions should be followed each time you are setting up a new Recap or Resolve project (or any model that uses the kit framework).

One-time Setup

This setup guide assumes you have already set up Python, Anaconda, and have a Github account.

Each time you set up a new AWS instance you will have to set up Python and Anaconda for your account on that machine. If you need help, please contact Pete at [email protected].

Follow this 🐍 E3 Python set up guide if do not yet have these set up.

Setup Steps

The core Resolve and Recap codebases are written in Python and hosted on GitHub as part of the E3 New Modeling Toolkit (kit) framework. Follow the steps below to get a copy of the codebase and set up the model in your project folder:

0. Optional Set up a project-specific AWS instance

this guide and talk to Roderick for how to set up an AWS instance for your project.

After that, place your project files in the shared drive across AWS instances (FSx) – instructions in the same guide above.

Note that you don’t need an AWS instance for running the quick start examples in this user guide.

1. 😸🔨 Pulling kit from GitHub

Click the green “Code” tab on top of the repository, then copy the link presented under “Clone” (it should be the same URL you are on).’

Navigate to your project folder and open a command line by typing cmd in the navigation bar. Then clone the repository with the command git clone [repo_url_you_copied].

Note

Note that kit is a private repository, so you will need a certificated GitHub account to access and clone it.
To authenticate your account and link with Okta, please contact Roderick for help.

2. 🌱🔨 Setting Up the Project’s Anaconda Environment

We will use the conda command to create an isolated environment for kit to run within, without disturbing any other Python packages you may have already installed (see the conda documentation for more details on conda environments).

  • Make sure you have downloaded a version of Anaconda or Miniconda on your computer or on the AWS instance. Refer to this link for Anaconda installation guide.

  • Now install the environment by opening a Command Prompt window in the “kit” directory by typing cmd in the address bar and use the following command: conda env create -f environment.yml --n [your project name] ( where [your project name] is unique and does not include any spaces, e.g., nve-Recap-kit).

Note

Developers should use the environment-dev.yml file instead of environment.yml, which will install several additional dependencies (e.g., pytest, sphinx). See the “Development Guide” section for more details.

3. 🔑🔨Getting a Gurobi license

this guide, then copy the license to your master kit directory.

A new Gurobi pool (and license) should be used for each new project.

4. 💻🔨 Configuring xlwings in the UI

Aside from the codebase, kit has Excel-based User Interfaces (UIs) for users to (1) create correctly formatted input & settings files and (2) run the model code without needing to directly interact with a command line.

These UIs rely on the xlwings package.

Open the appropriate UI (./Recap-Resolve Scenario Tool.xlsm or ./Resolve Scenario Tool.xlsm) and navigate to “Cover & Configuration” tab. You will need to set the correct Python Path and Data Folder.

The Data Folder is the full path to the kit\data folder (example provided in UI).

For the Python Path follow the instructions below.

  • For Windows: Users will need to set the Python Path (you can use the where python command in Command Prompt, with your project conda environment activated, to get this path) and Data Folder. Examples provided in the UI.

    • If you get an error that says “Your conda version seems too old…”, fill in the Interpreter_Win cell. You can find the the correct interpreter by activating kit environment, then using the where python command in Command Prompt. The path should look something like C:\Users\[username]\Anaconda3\envs\kit\python.exe.

  • For macOS: Users will need to set the Interpreter_Mac, which is similar to Conda Path but the path to the Python executable within the corresponding conda environment. You can find the the correct interpreter by activating the kit environment, then using the which python command in Terminal; this should give you a path that looks something like /Users/[username]/.../anaconda3/envs/kit/bin/python

    • Users will also be prompted the first time they try to run any of the xlwings-based buttons in the Scenario Tool to allow xlwings to control your system. You must allow control for xlwings to be able to read/write from the Scenario Tool.