Installing PITLAKQ#

A Python Program#

PITLAKQ is written in Python and FORTRAN. It includes CE-QUAL-W2, a public domain code for hydrodynamics and water quality of lakes and reservoirs version 2.0. The latter is implemented in FORTRAN. Therefore, you need to install Python. You don’t need to know how to program in Python in order to use PITLAKQ. However, it can be very useful to have some basic Python knowledge. There is no need to understand FORTRAN because the FORTRAN source code is complied into Python extension.

PITLAKQ works on Microsoft Windows, Mac OS X, and Linux. Due to available dependencies, the most recent version works with Python 3.12. It is packaged as a conda package. There are several way how to install conda packages. If you already use conda oder mamba, which is a faster alternative to conda, you can use your existing installation. Add the channel hydrocomputing to your conda configuration and install pitlakq. Otherwise, the recommended way is to use Pixi. Alternatives are Miniforge, Miniconda, or Anaconda.

Alternative 1: Using Pixi#

Installing Pixi#

Please follow the instructions how to install Pixi. After installing Pixi, the command pixi should be available in a terminal window.

Creating a Pixi workspace#

You need to create a Pixi workspace. This can be done either by typing in a terminal window:

pixi init pitlakq_project
cd pitlakq_project

Now the directory pitlakq_project contains a file named pixi.toml that contains the configuration. You need to add the channel hydrocomputing to your Pixi workspace. This can be done either by typing in a terminal window:

pixi workspace channel add --prepend hydrocomputing

or by editing the file pixi.toml, modifying the key channels in the section [workspace] from:

[workspace]

channels = ["conda-forge"]

to:

[workspace]

channels = ["hydrocomputing", "conda-forge"]

Installing PITLAKQ#

Now you can install PITLAKQ by typing:

pixi add pitlakq

Alternative 2: Using Conda with Miniforge, Miniconda, or Anaconda#

Alternatives to using Pixi are Miniforge, Miniconda, or Anaconda. Miniforge is a minimal conda installer with the conda-forge channel as the default channel.

Anaconda is a Python distribution with many Python packages. Miniconda is a much smaller version of the Anaconda Distribution with a few packages. Make sure the Anaconda license works for you before using this option. Otherwise, use Miniforge, or our recommendation Pixi.

After installing Miniconda or Anaconda, the command conda should be available in a terminal window:

conda
usage: conda [-h] [-v] [--no-plugins] [-V] COMMAND ...

conda is a tool for managing and deploying applications, environments and packages.

Installing PITLAKQ#

In a terminal window type:

conda config --add channels conda-forge
conda config --add channels msys2
conda config --add channels hydrocomputing

Create a conda environment by typing:

conda create -n pitlakq312 python=3.12

Answer “Yes” to the question(s) and type enter.

Next, type:

activate pitlakq312

On Linux or Mac this needs to be:

source activate pitlakq312

Note

There might be pitlakq packages for different Python versions. To find out, type:

conda search pitlakq

You should see an answer like this:

pitlakq   1.7.8    py312_0  hydrocomputing/win-64

This means version 1.7.8 of pitlakq is available for Python 3.12. If it would say py39_x, you should create an environment for Python 3.9. For example:

conda create -n pitlakq39 python=3.9

and activate accordingly:

activate pitlakq39

You can choose a different name but you need to be consistent. Here we use pitlakq312.

The prompt should change to (pitlakq312).

Type:

conda install pitlakq

Answer “Yes” to the question(s) and type enter.

This will take a while.

Testing the installation#

After the installation with Pixi or conda, you can check if pitlakq is properly installed by typing:

pitlakq

You should see something like this:

usage: run_pitlakq.py [-h] [-v] {init,run,create,introspect} ...

positional arguments:
  {init,run,create,introspect}
    init                initialize PITLAKQ and create `.pitlakq`
    run                 start the calculation of a model
    create              creates a new project folder with empty sub folders
    introspect          find out internals of PITLAKQ or your projects

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show version info and exit

Initializing PITLAKQ#

PITLAKQ needs to know about two directories:

  1. A path for the models

  2. A temporary path to copy internal files during model execution

The easiest way to do let PITLAKQ know is to run:

pitlakq init

This will create a file named .pitlakq in your home directory. It will contain content like this:

model_path:
    C:\Users\<user_name>\pitlakq_work\models

ram_path:
    C:\Users\<user_name>\pitlakq_work\RAM

resources_path:
    <install_dir>\pitlakq\resources

template_path:
    <install_dir>\pitlakq\templates

Where <user_name> is your user name and <install_dir> is the directory pitlakq is installed in. You can change these paths, forcing PITLAKQ to look into a different directory for models (model_path) of using a different directory for temporary files (ram_path). This is an advanced technique and not needed for normal use.

You can place .pitlakq somewhere else. Just choose a directory and set the environmental variable PITLAKQHOME pointing this path.

Check if it runs#

You can find out what projects are available with:

pitlakq introspect --projects

If the are no projects, you get an according message:

Projects:
Currently no projects.

Copy one or more projects, i.e. directories, from the provided tutorial projects into this path.

Now

pitlakq introspect --projects

should show you the projects you can run:

Projects:
     pitlakq_tut
     pitlakq_tut_gwh
     pitlakq_tut_loadin
     pitlakq_tut_qual

Choose a name from this list and run the model with:

pitlakq run pitlakq_tut

This should produce a lot of screen output. The model might run several minutes or longer. You can always stop a model run with the key combination <Ctrl><C>.