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.
Installing of Miniconda or Anaconda¶
PITLAKQ relies on many external packages. Therefore, you need to install either Miniconda or Anaconda. Anaconda is a Python distribution with about 200 Python packages. It is a download of about 400 to 500 MB and will take about 2 GB on your hard drive. Miniconda is much much smaller and is therefore the preferred option. Both allow the comfortable installation of further packages as well as creating of so called environments. We will take advantage of both features.
PITLAKQ works on Microsoft Windows, Mac OS X, and Linux. It is packaged as a conda package.
Please download Miniconda.
Please choose the right version for your operating system and take
Python 3.9 (or higher, if available.)
Install, following the instructions on the download web site.
Please install only for you, with your user rights,
not for all, which would require administrator rights.
You can check if the installation was successful by opening a new terminal
window.
On Windows this can be achieved by typing Anaconda Prompt
while hovering
with the cursor over the Windows start button (lower left on a standard install)
and clicking on the entry Anaconda Prompt
.
On Mac OS X and Linux a normal terminal window should work.
Now type:
python
You should see a response and >>>
with a blinking curses.
Type:
>>> exit()
to terminate this Python session. You can also identify the installed Python version with:
python --version
Installing PITLAKQ¶
In a terminal window type:
conda config --add channels conda-forge
conda config --add channels msys2
conda config --add channels hydrocomputing
Currently, PITLAKQ is available for Python 3.9. If you have an installed Python with the same version (see above for finding out the current Python version), you may skipp the following steps that create a new environment. However, creating a new environment can be useful even if you already have the right Python version, because it allows to separate the Python installation for PITLAKQ from potential other Python applications. There are many more interesting details about conda environments.
Creating a conda environment¶
Type:
conda create -n pitlakq39 python=3.9
Answer “Yes” to the question(s) and type enter.
Next, type:
activate pitlakq39
On Linux or Mac this needs to be:
source activate pitlakq39
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.6 py39_0 hydrocomputing/win-64
This means version 1.6 of pitlakq
is available for Python 3.9.
If it would say py36_x
, you should create an environment for Python 3.6.
For example:
conda create -n pitlakq36 python=3.6
and activate accordingly:
activate pitlakq36
You can choose a different name but you need to be consistent.
Here we use pitlakq39
.
The prompt should change to (pitlakq39)
.
Installing PITLAKQ¶
Type:
conda install pitlakq
Answer “Yes” to the question(s) and type enter.
This will take a while.
After this is finished, 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:
A path for the models
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>
.