DualSPHysics Guidelines for Earth Scientists

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.

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.

Guidelines

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.

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.