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 GridPath Python virtual environment.
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 Building the Database section of the documentation for more information.