Getting started

Installing

First steps

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.

SynxFlow also needs NVIDIA GPUs which support CUDA to run the simulations, therefore you need a GPU and the CUDA Toolkit. The CUDA Toolkit can be downloaded from the NVIDIA website. Please follow their websites about installation of CUDA Toolkit.

Installing from binary wheels (on Windows and Linux)

If you have a Linux or Windows (version >= 10) machine, with Python 3.9 or 3.10, and CUDA 11.3 or newer. Then synxflow can be installed by

pip install synxflow

Now you should have synxflow successfully installed on your computer.

Installing from source code (on Linux)

You may wish to install by compiling directly from the source code. Note this method is only tested for Linux machines. Before installing synxflow in this way, you would need to install Cmake, NVIDIA CUDA Toolkit and the C++ compiler. The C++ compiler ‘GCC’ is usually on the system as default. Cmake can be simply installed by

pip install cmake

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-11.3

Once the aforementioned dependencies have been properly installed. Installing synxflow is straightforward, simple type in the following in your terminal

pip install git+https://github.com/SynxFlow/SynxFlow.git

Running a simulation with the example

The flood simulation engine can be imported by

from synxflow import flood

The IO package for processing inputs and outputs can be imported by

from synxflow 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 synxflow.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())