Commit f10aa06c authored by Hannes Fuchs's avatar Hannes Fuchs
Browse files


parent c4e021d9
# easyWave
easyWave is an application that is used to simulate tsunami generation and propagation in the context of early warning. It makes use of GPU acceleration to speed up the calculations. easyWave is licensed under the [EUPL]( (v1.1 or later), complemented with the following provision: For the scientific transparency and verification of results obtained and communicated to the public after using a modified version of the work, You (as the recipient of the source code and author of this modified version, used to produce the published results in scientific communications) commit to make this modified source code available in a repository that is easily and freely accessible for a duration of five years after the communication of the obtained results.
# Download
The latest CPU version supports multi-threading on shared memory systems using OpenMP.
* [easywave_r34_omp_i386.tar.gz](bin/r34/easywave_r34_omp_i386.tar.gz)
* [easywave_r34_omp_x64.tar.gz](bin/r34/easywave_r34_omp_x64.tar.gz)
* [easywave_r34_src.tar.gz](bin/r34/easywave_r34_src.tar.gz)
You can download one of the following packages to use the single-threaded version or a pre-compiled GPU binary instead.
* [easywave_r17_gpu_i386.tar.gz](bin/r17/easywave_r17_gpu_i386.tar.gz)
* [easywave_r17_gpu_x64.tar.gz](bin/r17/easywave_r17_gpu_x64.tar.gz)
* [easywave_r17_i386.tar.gz](bin/r17/easywave_r17_i386.tar.gz)
* [easywave_r17_x64.tar.gz](bin/r17/easywave_r17_x64.tar.gz)
* [easywave_r17_src.tar.gz](bin/r17/easywave_r17_src.tar.gz)
# Getting started
The following sections will explain how to install and use easyWave. The guide is written for Unix-based systems and assumes that a bash shell is used. Other shells may require little modifications.
## Installation
You can install easyWave in three different ways:
1. Download a pre-built binary package appropriate for your system.
2. Download a source file archive and compile on your own.
3. Check out a development branch via git
In the following all the possibilities are described.
### 1. Using binaries
1. [Download](#Download) a suitable package according to your platform into some folder DIR.
2. Extract the package with an archive manager. Therefore open a terminal, browse to the download directory and run the following command:
tar -xzf <package>.tar.gz
3. You can now use easyWave by specifying the absolute path /DIR/easywave/bin/easywave. However you can also add the bin-folder of easyWave to your `$PATH` variable like that:
export PATH=$PATH:$PWD/easywave/bin
Note: To make the change permanent add the above command to your .bashrc.
Afterwards you can run easyWave simply by its program name:
The installation is complete. You can now continue with the [Examples](#Examples ) section.
### 2. From a source archive
1. [Download](#Download) the source archive to an arbitrary directory in your file system.
2. Open a terminal, browse to the selected directory and unpack the downloaded archive:
tar -xzf <source>.tar.gz
This will create a directory named `easywave` that contains all sources that are necessary to build the executables.
3. Change to this directory and build the sources:
cd easywave
The `configure` script will search your system for compatible tools to compile the source code. It will also set some default options for the installation process. You can customize these options on the command line. To get a list of options type `./configure --help`. If the above steps have been successfully completed all binary files have been created.
4. You could now install easyWave to the specified installation directory (default: `/usr/local/easywave`) by typing:
make install
Note: If the installation directory is not writable by the current user, you have to run the above command as root.
After that easyWave was successfully installed and is ready to use. We recommend to add the installation's bin-directory to the `$PATH` variable to use easyWave from any location.
### 3. From the git repository
You can download the latest development state or any custom branch of easyWave directly from the `git` repository. For this, you need `git` installed on your system.
1. Open a terminal and browse to a directory where you want to place a copy of easyWave.
2. Check out the trunk:
git clone
3. Run the following instructions:
cd easyWave/code
make install
For details see ...
The git clone will also include some contents that is not part of the distributed tar.gz archive. Especially the tests/ directory can be useful to ensure program functionality. For details see section [Test](#Test).
## Examples
To get familiar with easyWave we provide some example input files that can be used to run certain simulations. In the following we will give the instructions for getting started with easyWave.
1. Create a directory on your file system where the example files should be placed.
2. Download the [archive](data/examples.tar.gz) that contains the examples into the newly created directory.
3. Open a terminal, browse to the selected directory and unpack the downloaded archive:
tar -xzf examples.tar.gz
This will create a directory named `examples` that contains all example files.
Note: In the following we will assume that you have added easyWave to your `$PATH` and thus it can simply be called by its name. Otherwise you have to add the full path when calling easywave.
4. Now you can run your first simulation with the following command:
easywave -grid examples/e2Asean.grd -source examples/BengkuluSept2007.flt -time 120
easyWave will simulate the tsunami generation and propagation from the given source according to the underlying grid file for a duration of 120 minutes. This can take a moment. However the progress is shown at run time. If the calculation is finished the following files have been created:
* `eWave.2D.sshmax`: Contains the maximum wave heights.
* `eWave.2D.XXXXX.ssh`: Contains the wave heights after XXXXX seconds of simulation.
* `eWave.2D.time`: Contains the estimated arrival times.
* `easywave.log`: Contains log messages.
To visualize the results you can use the scripts supplied with the easyWave installation. To show the maximum wave heights run the following command:
```shell -grd examples/e2Asean.grd
This will create a file named `eWave.2D.png`. You can open this file with your default image viewer.
You can also visualize the wave propagation at a particular time. Simply run:
```shell -grd examples/e2Asean.grd 03600
This again generates an image file that in this case is named `eWave.2D.03600.png`. It contains the wave propagation after 3600 seconds (= 1 hour).
Furthermore you can display the given points of interests if easyWave was started with a corresponding POI file:
```shell -grd examples/e2Asean.grd examples/poiIndonesia.poi
## Tests
The `tests/` directory contains some python scripts that can be used to compare different easyWave versions with each other. You should always perform tests if you have made changes. This makes sure that your version still yields satisfying results.
To invoke a test run you mainly need to call ``. To obtain the test cases two configuration files were used. You can specify them with the arguments `--instances` (`-i`) and `--scenarios` (`-s`). The file given by `--instances` should include paths to easyWave instances that should be compared to each other. Each line should contain exactly two instances separated by a semicolon. For example:
@../src/easywave; @../src/easywave -gpu
This leads to a comparison of the CPU and GPU version of an easyWave instance located in the `src/` directory. The @ sign should be included everywhere you want to specify a path relative to the `tests/` directory. It will be expanded automatically.
The file given by `--scenarios` should contain all parameters that should be added to the both compared easyWave instances, thus creating a scenario. You can set multiple scenarios (one per line) which are processed in order. For example:
-grid @grids/e2Asean.grd -source @faults/BengkuluSept2007.flt -time 300
-grid @grids/g08Japan.grd -source @faults/uz.Tohoku11.grd -time 300
The `tests/` directory already includes two default configuration files (`instances.cfg` and `scenarios.cfg`) which can be used to run a large test. However you need some additional files which must be downloaded first. To do so, simply type:
Note: This will download some large grid-files.
Afterwards you can run `` without passing any parameter. In this case the default configuration from `instances.cfg` and `scenarios.cfg` is used.
## Additional material
The links below refer to some additional documentation about easyWave. Parts of them may be out of date, so you should always consult this page to get the latest information.
* [easyWave_About.pdf](doc/easyWave_About.pdf)
* [easyWave_StartingGuide.pdf](doc/easyWave_StartingGuide.pdf)
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment