DualSPHysics Guidelines for Earth Scientists

Nick Richmond, University of Maine

History

DualSPHysics¹ is a Smoothed Particle Hydrodynamics (SPH) solver used to solve the fundamental equations of fluid dynamics, the Navier-Stokes equations. Among the modern SPH solvers available, there are many advantages to choosing DualSPHysics, most notably the optimization of the code for GPU parallel processing. Running the DualSPHysics code on a GPU vastly decreases solution times, thereby allowing high-resolution and/or large-domain cases to be executed efficiently. Researchers in the UMaine School of Earth and Climate Sciences and Climate Change Institute began using DualSPHysics v3.1 in 2014 to investigate the kinematics of icebergs. Since then, the DualSPHysics development team has added many useful features to the code which broaden the scope of scientific questions we can address using the SPH method. In particular, the addition of new boundary conditions, liquid + sediment physics, and fluid-structure interaction with Discrete Element Method systems have created research opportunities in the earth sciences.

Structure of DualSPHysics

The DualSPHysics project represents a collection of codes which can be broken up into three sections:

1. Pre-processing

   GenCase is the program used to set up the geometry and physics of a DualSPHysics model.

2. Processing

   DualSPHysics is the program used to calculate the motions, etc. of particles within the model domain. This program takes in information from GenCase and outputs binary (.bi4) files. You can't read the binary files directly; they are the inputs for the post-processing codes.

3. Post-processing

   There are a litany of post-processing codes in the DualSPHysics project. This allows you to take a modular approach to data generation. Some of them, such as PartVTK, you will use in almost every use case imaginable. Others are more specialized. For example, if you want to calculate the forces exerted on a solid object in your domain, you can use ComputeForces4.

Any given model typically employs GenCase, DualSPHysics, PartVTK, and a handful of other post-processing tools depending on the desired outcome.

Resources

First things first, let's establish where you ought to look for answers to your DualSPHysics questions.

1. The DualSPHysics Wiki on GitHub

   In 2018, the DualSPHysics project was moved to a GitHub repository. The Wiki section of the repository should be your go-to resource for all aspects of DualSPHysics, with the exception of model design. At the time of writing (March 2019), the preprocessing section of the Wiki lacks the detail of the XML_v4.0_GUIDE.

2. XML_v4.0_GUIDE

   In addition to being made available on this wiki (click the heading link), this PDF is included in the DualSPHysics package, and it provides many (but not all) details of the functionality of GenCase, the program used to set up the geometry and physics of a DualSPHysics model.

3. DualSPHysics FAQ

   The DualSPHysics website has a very helpful FAQ section which is updated regularly and addresses a broad range of common questions. Reading through these early on in your DualSPHysics experience will save you time and angst.

4. doc > xml_format

   Within the DualSPHysics package there is a doc directory containing all sorts of useful documentation. For a deep dive into the full functionality of GenCase, refer to the XML documents in the xml_format directory.

General Pointers

The following guidelines are based on my experience working with the DualSPHysics code. My hope is that the points presented here will allow you to succeed in creating models which faithfully represent the systems you want to model, with minimal frustration.

• It's wise to familiarize yourself with the example models which ship with the DualSPHysics package. The examples directory contains a litany of example models which are categorized in terms of the features they highlight. If you want a high-level overview of these examples without exploring the model results first-hand, you may refer to the Testcases section of the DualSPHysics wiki.
• Once you're familiar with the example models, you're ready to start experimenting with your own model design. Start by considering which physics (e.g., fluid + fixed structure, fluid + fixed structure + floating objects, fluid + sediment, etc.) and which boundary conditions (e.g., closed system, periodic boundary conditions, open boundary conditions, etc.) will be necessary for your model. From there you can copy an example model which is closest to the system you want to model and adapt it to your needs.
• In the early stages of model design, it's best to start with a simple design which is fast to generate. Often the fastest route to a working model is by first running only GenCase, visualizing the outputs in ParaView, and then modifying your case design (XML) file until the geometry is as you would like it to be. From there, you can run DualSPHysics and shift your focus to the quality of the physics simulation. It's usually fastest to run the model at coarse resolution (higher inter-particle distance, or dp), increasing resolution only when the simulation is producing reasonable results.
• If working with complex geometries or geospatial data derived from LiDAR, Structure from Motion, or similar, it's best to import the geometry as an STL file. The process for this depends entirely on the type of data you're working with, but there are some established routes for distinct use cases:
  • Blender is an excellent program for creating simple or complex surfaces and objects. If I want to create a realistic boulder or a synthetic landscape such as an idealized knickpoint, I would reach for Blender.
  • phstl is a Python utility which produces an STL from raster files (GeoTIFFs).
  • xyz2stl is a standalone MATLAB app (you don't need MATLAB to run it) that I wrote in 2017 which produces an STL from x,y,z coordinates (such as in a CSV file).
  • Global Mapper is commercial GIS software which can produce an STL from raster files (GeoTIFFs) using a graphical user interface. This is a good option if you aren't comfortable with something like phstl. Global Mapper is installed on all of the machines in the Computer Cluster on the 2^nd floor of Bryand Global Sciences Center.

  There are many more open source and commercial options for producing the same results. I can personally attest to the utility of the tools listed here, but you might find that software such as Surfer or MeshLab might best fit your needs.

Customizing DualSPHysics

At the 4th Annual DualSPHysics Users Workshop in Lisbon, Portugal, Orlando García-Feal of University of Vigo delivered an outstanding presentation in which he described the process of customizing DualSPHysics with clarity and detail. You can find the PDF version of his presentation on our wiki: Customizing DualSPHysics.

I think of Orlando's presentation as the definitive template for adding functionality to DualSPHysics, and the code he produced is an official branch of the DualSPHysics repository. This now allows for temperature to be a physical property held by moving fluid particles, with the added benefit of thermal boundary conditions.

References Cited

¹Crespo, A.J.C., Domínguez, J.M., Rogers, B.D., Gómez-Gesteira, M., Longshaw, S., Canelas, R., Vacondio, R., Barreiro, A., and García-Feal, O., 2015, DualSPHysics: Open-source parallel CFD solver based on Smoothed Particle Hydrodynamics (SPH): Computer Physics Communications, v. 187, p. 204–216, doi: 10.1016/j.cpc.2014.10.004.