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.

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 outputs are producing reasonable results.

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.