2. Installation¶

2.1. Using a Terminal¶

To install GridPath, you will need to use a command-line interface. On Windows, you can use cmd.exe, Windows PowerShell, or another command-line interface (we test using cmd.exe, so recommend using that). You can search for cmd.exe from the Start menu. On Mac, you can use the Terminal application. Search for it with Spotlight by clicking the magnifying glass icon in the upper-right corner of the menu bar, or by pressing Command-Space bar.

2.2. Requirements¶

2.2.1. Python¶

Running GridPath requires a Python 3 installation. GridPath is tested nightly in Python 3.9, 3.10, and 3.11. You can get Python here.

2.2.2. Python Virtual Environment¶

You must set up a Python virtual environment for GridPath to ensure that the appropriate packages are installed and avoid interfering with the requirements of other Python programs you may be using. Below are instructions for how to set up a virtual environment using Python’s venv module or with Anaconda. Make sure to keep track of where your virtual environment directory is located, as you will need to locate it if you are using the GridPath user interface. We will refer to the GridPath Python environment directory as PATH/TO/PYTHON/ENV.

venv¶

The venv package is part of the Python 3 standard library and is a lightweight method for managing virtual environments. Once you have installed Python 3, you can create the virtual environment for GridPath by running:

python3 -m venv PATH/TO/PYTHON/ENV

This will create the virtual environment in the PATH/TO/PYTHON/ENV directory.

On Windows, you can activate the virtual environment by running appropriate activation script from inside the Scripts directory of the virtual environment directory.

From cmd.exe:

C:\> PATH\TO\PYTHON\ENV\Scripts\activate.bat

On Linux-based systems including MacOS, use:

source PATH/TO/PYTHON/ENV/bin/activate

2.2.3. Solver¶

You will need a solver to get optimization results. GridPath assumes you will be using Cbc (Coin-or branch and cut) by default, but you can specify a different solver as long as it is supported by Pyomo, e.g. GLPK, CPLEX, Gurobi, etc.

You can find the latest instructions for installing Cbc here. GridPath allows you to specify the location of the solver executable; to get it to be recognized, automatically, you can also add it to your PATH system variables (see instructions for Windows here).

2.3. Installing GridPath¶

Before installing, make sure to activate your :ref:`GridPath virtual environment <python-virtual-env-section-ref>`.

2.3.1. Installation from PyPi¶

You can download and install the latest version of GridPath from PyPi with:

pip install GridPath

To get a specific version, e.g., v0.16.0, use:

pip install GridPath==0.16.0

Note that GridPath versions before 0.16.0 are not available on PyPi.

2.3.2. Installation from Source¶

GridPath’s source code is stored in a GitHub repository. You can find the latest GridPath release here. Download the source code zip file and extract it. We will refer to the directory where the code is extracted to as the PATH/TO/GRIDPATH directory.

Most users should install GridPath by navigating to the GridPath directory PATH/TO/GRIDPATH with cd PATH/TO/GRIDPATH and running:

pip install .

Developer extras¶

You may need to install additional packages if you plan to edit the GridPath code and, for example, build the documentation from source, use the Black code formatter, or check test coverage.

To install all packages, run:

pip install -e .[all]

GridPath’s developer extras can be installed individually. See the setup.py file in the repository.

If you would like to edit the user-interface code, you will also need Node.js in addition to Python and will be required to install various node packages. See the User Interface section for more info.

Testing Your Installation¶

To test the GridPath codebase, use the unittest module as follows from the PATH/TO/GRIDPATH directory:

python -m unittest discover tests

This command will use the python unittest module to test all functions in the ./tests folder. Testing includes both simple unittests as well as integration tests that run small example problems (for which you will need a solver).

2.4. Database¶

While not strictly required – you can generate TAB-delimited scenario input files any way you like – GridPath includes support for input and output data management via an SQLite database. We recommend that you store data in the database and use GridPath’s built-in tools for loading input data into the database, creating scenarios and generating scenario input files, and importing scenario results into the database. Using the GridPath user interface requires that data be stored in a database.

We recommend SQLite Studio as an SQLite database GUI.

We have implemented various tools to help you build your database. See the Database Structure section of the documentation for more information.