dasshydro / dassflow1d

Data Assimilation for Free Surface Flows : 1D Shallow-Water like systems for river network dynamics.

DassFlow1D

This git repository contains the development version of DassFlow1D.

Table of Contents

1. General Information.
2. Repository organisation.
3. Requirements.
4. Install project.
5. Compile and install the adjoint code.
6. First steps and Website.

1. General information

WARNING: For the moment, dassflow1d and other versions work on Linux only (might work on some MacOS installations, no warranty).

You can clone this project to your own machine using the following command:

git clone http://github.com/DassHydro-dev/dassflow1d

2. Repository organisation

• build:
  • obj: contains the binaries after installation / compilation.
  • api: contains the application programming interface.
  • tap: contains the Tapenade files used to generate and execute the adjoint code.
• cases: contains up-to-date and validated test cases.
• doc: contains several documentations for DassFlow1D.
• libs: contains external libraries that the software uses.
• src: contains all Fortran source codes.
• unit_tests: contains unitary tests used to validate DassFlow1D features.

3. Requirements

3.1 Operating System

The DassFlow1D software is dedicated for Linux or Unix systems.

3.2 Compilers

One of these two compilers must be installed:

• The GNU Fortran compiler: gfortran
• The INTEL Fortran compiler: ifort

3.3 Python environment

• Python >= 3.6
• matplotlib >= 2.0
• numpy >= 1.10
• scipy >= 1.3
• f90wrap = 0.1.4 (mandatory version)

Note: you can use a conda environment to setup this environment. In your terminal, type the following command (in your repository directory):

conda env create -f doc/conda_env_dassflow-1d.yml

To activate or deactivate the conda environment, you can use respectively conda activate dassflow-1d or conda deactivate.

4. Install project

1. Make sure all the requirements are met.
2. Make sure the conda environment is activated using conda activate dassflow-1d.
3. Open a terminal at the root of your repository.
4. Compile and install the required libraries:
   

   make alllibs
   

5. Install DassFlow1D ^[1]:

   make
   

^[1] if you wish to use the adjoint code, see Compile and install the adjoint code before you install using the make command.

5. Compile and install the adjoint code

5.1 Install Tapenade

To use the adjoint code for DassFlow1D, you need an Automatic Differentiation (AD) tool. Follow this tutorial to download and install Tapenade and add the following lines to your ~/.bashrc to add tapenade to your PATH:

alias tapenade="tapenade_dir/bin/tapenade"
TAPENADE_HOME=tapenade_dir/bin
export PATH=$PATH:$TAPENADE_HOME
export PATH=$PATH:$"tapenade_dir"

Note: tapenade_dir is the absolute path to the directory containing the tapenade files you just downloaded.

5.2 Compile and install DassFlow1D with the adjoint code

1. First, make sure all the requirements are met.
2. Modify the Makefile.inc file to have ADJOINT = 1 (to tell the Makefile it needs to install the adjoint code for DassFlow1D).
3. Then, generate the adjoint code by entering the following command (in your repository directory):

   make generate_adjoint
   

4. Install DassFlow1D:

   make
   

6. First steps and Website

6.1 Test your DassFlow1D installation

To try and test your DassFlow1D installation, you can try to run a test case by entering the following commands in your terminal (in your repository directory):

conda activate dassflow-1d
. build/api/env.sh
cd cases/osse/strickler_inference/channel_powerlaw_spatial_fields
python run_osse_without_noise.py

Note: If it works, last printed line should contain CONVERGENCE: REL_REDUCTION_OF_F_<=_FACTR*EPSMCH.

6.2 Website

You can visit the DassHydro Website for more information on DassFlow1D and other versions.