Getting started
Installing
You will have to set up your Python environment as a first step. There are several ways of doing it, but Anaconda is a highly recommended way.
Before installing pypims, you also need to install Cmake, NVIDIA CUDA Toolkit and the C++ compiler. Cmake can be simply installed by
pip install cmake
Pypims needs NVIDIA GPUs which support CUDA to run the simulations, therefore you need the GPU and the CUDA Toolkit. The CUDA Toolkit can be downloaded from the NVIDIA website. If you use Linux system, the C++ compiler ‘GCC’ is usually on the system as default. If you use windows, you should download and install Visual Studio.
Installing on Linux
You may need to define the CUDAToolkit_ROOT environmental varialble first if there exists several different versions of CUDA Toolkits on your system. This can be done by
export CUDAToolkit_ROOT=<path to your cuda directory>
For example
export CUDAToolkit_ROOT=/usr/local/cuda-10.1
Once the aforementioned dependencies have been properly installed. Installing pypims is straightforward, simple type in the following in your terminal
pip install pypims
Installing on Windows
Installing on Windows is slightly less straightforward than on Linux. The steps below are tested with Windows 10, Visual Studio 2019 and Python 3.7. You need to firstly manually install the dependency packages inculding ‘GDAL’, ‘rasterio’ and ‘fiona’.
Taking GDAL as an example, firstly download the wheel from here. You need to choose the wheel for the right platform and python version, for example ‘GDAL‑3.4.2‑cp37‑cp37m‑win_amd64.whl’, which corresponds to amd64 platform and Python 3.7. Then GDAL can be installed in the commandline tool as
python -m pip install <path to downloaded wheel>
‘rasterio’ and ‘fiona’ need to be installed following similar steps.
The next step is to download the source code of pypims from Github. This can also be done by
git clone https://github.com/pypims/pypims.git
After finishing downloading, go to the folder of the pypims source code and run the following command
python setup.py install
Now you should have pypims successfully installed on your computer.
Running a simulation with the example
The flood simulation engine can be imported by
from pypims import flood
The inputs can be prepared by hipims-io. This package has already been included as part of pypims, you can import it by
from pypims import IO
A quick demonstration to prepare input files with attached sample data contaning the following files:
DEM.gz/.asc/.tif (essential file, in projected crs, map unit:m)
rain_mask.gz/.asc/.tif (optional file for setting rainfall, having the same crs with DEM)
rain_source.csv (optional file for setting rainfall rate in timeseries, unit:m/s]
landcover.gz/.asc/.tif (optional file for setting landcover-based parameters, having the same crs with DEM)
import os
from pypims.IO.demo_functions import demo_input
obj_in = demo_input() # create input object
obj_in.write_input_files() # create all input files
Once the inputs have all been prepared, the simulations can be started by
flood.run(obj_in.get_case_folder())