search

lukeshope / hipims-ocl

The high-performance integrated modelling system, for hydraulic and hydrological simulations
GNU General Public License v3.0
21 stars 10 forks source link

readme

HiPIMS OpenCL

The high-performance integrated modelling system, for hydraulic and hydrological simulations (HiPIMS), is a suite of tools designed to run on a range of modern computing platforms including CPUs, GPUs and distributed systems (MPI).

In short, this software simulates river, tidal and pluvial (direct rainfall) flooding over large areas such as a city or region. It can take rainfall or river levels etc. as input, and produce raster files of depth and velocity at different times. If you're lucky enough to have a supercomputer then this software will scale to take advantage of all the hardware you have.

Associated tools

You might want to look at these.

Background

This software was created for use in academic research. It is now licensed under the GNU General Public Licence (GPL) allowing you to use the code and further develop it. We stress that is trivial to use any hydraulic modelling software to create a model that is in no way representative of the real world, and that you should validate any models against real-world observations.

Download

You probably want the HiPIMS binaries for Windows, and perhaps the tests to give you an idea of what a configuration file looks like.

Your system will need the Visual Studio 2013 runtime, but it is quite likely you already have this.

There is no graphical interface supplied with HiPIMS; this is a console-only application. We did start developing an interface, but as most of our applications ran on high-performance servers without a graphical interface, it never reached maturity.

HiPIMS console view

Use

You will need a system which can run OpenCL. This includes most modern Intel CPUs and APUs, AMD GPUs and CPUs, and NVIDIA GPUs. Your graphics card drivers may already include the OpenCL runtime. If you do not already have an OpenCL runtime, you should try downloading:

You may also find that some overzealous anti-virus software blocks OpenCL code from running, because some runtimes will compile code on the fly and run it from the temporary directory.

Model configuration

Models are defined using an XML file similar to the one below, and using CSV and GIS formats to define the model domain. GDAL is used for reading and writing all spatial data, with available formats and their codes listed here.

All paths in the configuration are relative to the XML file.

<?xml version="1.0"?>
<!DOCTYPE configuration PUBLIC "HiPIMS Configuration Schema 1.1" "http://www.lukesmith.org.uk/research/namespace/hipims/1.1/"[]>
<configuration>
    <metadata>
        <name>A model</name>
        <description>A dead good model.</description>
    </metadata>
    <execution>
        <executor name="OpenCL">
            <parameter name="deviceFilter" value="GPU" />
        </executor>
    </execution>
    <simulation>
        <parameter name="duration" value="7200" />
        <parameter name="outputFrequency" value="600" />
        <parameter name="floatingPointPrecision" value="double" />
        <domainSet>
            <domain type="cartesian" deviceNumber="1">
                <data sourceDir="newcastle-centre/topography/" 
                      targetDir="newcastle-centre/output/">
                    <dataSource type="constant" value="manningCoefficient" source="0.030" />
                    <dataSource type="raster" value="structure,dem" source="NewcastleCentreDEM_2m.img" />
                    <dataTarget type="raster" value="depth" format="HFA" target="depth_%t.img" />
                </data>
                <scheme name="Godunov">
                    <parameter name="courantNumber" value="0.50" />
                    <parameter name="groupSize" value="32x8" />
                </scheme>
                <boundaryConditions sourceDir="newcastle-centre/">
                    <domainEdge edge="north" treatment="closed" />
                    <domainEdge edge="south" treatment="closed" />
                    <domainEdge edge="east" treatment="closed" />
                    <domainEdge edge="west" treatment="closed" />
                    <timeseries type="atmospheric" 
                                name="Drainage" 
                                value="loss-rate" 
                                source="boundaries/drainage.csv" />
                    <timeseries type="atmospheric" 
                                name="Rainfall" 
                                value="rain-intensity" 
                                source="boundaries/rainfall.csv" />
                </boundaryConditions>
            </domain>
        </domainSet>
    </simulation>
</configuration>

Command-line arguments

Arguments are mostly the same for the Linux and Windows builds of HiPIMS. Short form arguments have a space preceding the value, while the long form uses an equals sign.

Short form Long form Description Default
-c --config-file=... XML file to use for the model configuration. Required
-l --log-file=... Log file which mirrors the console output. _model.log
-s --quiet-mode Disable any points where user feedback is required, such as on model completion. false
-n --disable-screen On Linux, disables NCurses for console output. false
-m --mpi-mode Forces only first MPI instance to output to the console. false
-x --code-dir=... On Linux, sets base directory for OpenCL code files. Binary path

Building from source

HiPIMS has a number of dependencies you need to provide first.

A Visual Studio 2013 project is provided for building on Windows, and a Makefile for Linux. You should launch the VS project using the supplied open-vs batch file, after modifying it to provide the paths to Boost and GDAL. Other dependency paths should be determined from environment variables set during their install.

On Linux, a simple make command should suffice to build the binaries once the dependencies are installed.

Test cases

These are a work in progress, because we do not own the copyright for the data used in many of the test cases HiPIMS was developed using. See the tests folder for information. We will provide new test cases using open data.

Detailed information

Information on the underlying numerical schemes and previous applications was provided in journal publications. Where possible, these publications are provided in LaTeX format in docs/papers.