FAQ: Frequently asked questions

1. What do I need to use DualSPHysics? What are the hardware and software requirements?

DualSPHysics can be executed either on CPU or GPU. In order to use DualSPHysics code on a GPU, you need a CUDA-enabled Nvidia GPU card on your machine (http://developer.nvidia.com/cuda-gpus). If you want to run GPU simulations (i.e. not develop the source code) the latest version of the driver for your graphics card must be installed. If no source code development is required, there is no need to install any compiler to run the binary of the code, only the driver must be updated. If you also want to compile the code you must install the nvcc compiler and a C++ compiler. The nvcc compiler is included in the CUDA Toolkit that can be downloaded from the Nvidia website and must be installed on your machine.

DualSPHysics is compiled with CUDA 9.2, so only GPUs starting from Kepler generation (compute capability 3.x) are supported. More information in: https://en.wikipedia.org/wiki/CUDA

2. Why DualSPHysics binary is not running?

If you are trying to run the executable GPU version on a CUDA-enabled Nvidia GPU card, the error message: Exception (JSphGpuSingle::SelecDevice). Text: Failed getting devices info. (CUDA error: CUDA driver version is insufficient for CUDA runtime version) can be solved by installing the latest version of the driver for the GPU card.

3. How can I compile the code with different environments/compilers?

The provided source files in this release can be compiled for linux using a ‘makefile’ along with gcc and nvcc compilers, and for windows using a project for Visual Studio (both VS2013 and VS2015 are provided). In case you use another compiler or other environment, you can adjust the contents of the makefile or you can also use CMAKE.

4. How many particles can I simulate with the GPU code?

The amount of particles that can be simulated depends on (i) the memory space of the GPU card and (ii) the options of the simulation.

5. How should I start looking at the source code?

Section 6 of the guide introduces the source files including some call graphs for a better understanding.

6. How can I create my own geometry?

Users can follow the provided example cases in the package. Those input XML files can be modified following XML_GUIDE_v4.2.pdf. Different input formats of real geometries can be converted using ExternalModelsConversion_GUIDE.pdf.

A new option is to use our new Graphical User Interface DesignSPHysics

7. How can I contribute to the project?

You can contribute to the DualSPHysics project by reporting bugs, suggesting new improvements, citing DualSPHysics (See the answer to Question 24) in your paper if you use it, submitting your modified codes together with examples.

8. How can I modify the code of the precompiled libraries?

Some code is provided in precompiled libraries to reduce the number of source files and to facilitate the comprehension of only the SPH algorithms by the users. These precompiled code covers secondary aspects during SPH simulations that are only used in specific simulations so they are not used in most of the cases. If the user wants to modify some of the codes included in the precompiled libraries, he can just replace that library by his own implementation.

9. How does the code define the limits of the domain?

In the input XML file, the parameters pointmin and pointmax only define the domain to create particles beyond these limits fluid or boundary particles will not be created. The limits of the computational domain are computed at the beginning of the DualSPHysics simulation and use the initial minimum and maximum positions of the particles that were already created with GenCase. In order to modify the limits automatically computed by DualSPHysics, different execution parameters can be used:

-domain_particles[:xmin,ymin,zmin,xmax,ymax,zmax]

-domain_particles_prc:xmin,ymin,zmin,xmax,ymax,zmax

-domain_fixed:xmin,ymin,zmin,xmax,ymax,zmax

so that the limits can be specified instead of using initial particle positions.

10. How can I define the movement of boundaries?

Examples of the different type of movements that can be described with DualSPHysics are addressed in directory examples\motion. Different kind of movements can be defined such as rectilinear, rotational, sinusoidal or circular motion and they can be uniform or accelerated, with pauses or with hierarchy of movements. And a final option is to load the movement from an external file with a prescribed movement (info of time, X-position, Y-position, Z-position and velocities) or with rotational movement (info of time, angle) that will be interpolated at each time step during the simulation (see examples\main\05_SloshingTank\CaseSloshingMotion).

11. How can I include a new type of movement?

A new movement can be always defined by using an external file with mvfile or mvrotfile where the desired movement can be computed in advance and loaded from that file. However if a user wants to create a new type of movement in the source code, this should be implemented in the functions JSphCpu::RunMotion() for CPU or JSphGpu::RunMotion() for GPU.

12. How do I prevent the boundary particles from going outside of the domain limits when applying motion?

As explained in the previous question, the limits of the computational domain are computed starting from the initial minimum and maximum positions of the particles. Since these values use the initial configuration, any movement of boundaries that implies positions beyond these limits will give us the error ‘boundary particles out the domain’. The solutions to solve this problem and to avoid creating larger tanks or domains are:

(i) the use of “drawpoint” to define boundary points at the minimum and maximum positions that the particles are expected to reach during the simulation. The option “drawpoint”will create a particle at the given location x,y,z.

(ii) using the parameters of DualSPHysics execution mentioned in the answer to Question 9.

13. Why do I observe a gap between boundaries, floating bodies and fluid in the solution?

The gap is a result of pressure overestimation across density discontinuities. It is inherent to the boundary formulation used in DualSPHysics. The forces exerted by the boundary particles create a small gap between them and fluid particles (1.5 times “h”). Note that by increasing the resolution (i.e. using a smaller “dp”) the gap is reduced however new boundary conditions are being developed and should be available in future releases [Domínguez et al., 2015].

14. How do I prevent the fluid particles from penetrating inside floating bodies?

Validation of floating using experimental data from [Hadzic et al., 2005], as shown in http://dual.sphysics.org/index.php/validation/wavesfloatings/, has been performed only for floating objects with particles created in the faces of the object and inside the object so no particle penetration will be observed.

15. How do I numerically compute the motion and rotations of floating bodies?

The new code FloatingInfo allows to obtain different variables of interest of the floating objects during the simulation; positions of the center, linear velocity, angular velocity, motions (surge, sway and heave) and angles of rotation (pitch, roll and yaw).

The testcases in examples\main\12_FloatingWaves include experimental data to validate with [Hadzic et al., 2005 & Ren et al., 2015].

16. When are fluid particles excluded from the simulation?

Fluid particles are excluded during the simulation: (i) if their positions are outside the limits of the domain, (ii) when density values are out of a range (700-1300 by default), (iii) when particles moves beyond 0.9 times the cell size during one time step.

17. How do I create a 2-D simulation?

DualSPHysics can also perform 2-D simulations. To generate a 2-D configuration you only have to change the XML file, imposing the same values in the Y-direction to define the limits of the domain where particles are created (pointmin.y=0 and pointmax.y=0).

18. How can I solve the error “Constant ‘b’ cannot be zero”?

Constant ‘b’ appears in the equation of state (Eq. 14). Constant ‘b’ is zero when fluid height (hswl) is zero (or fluid particles were not created) or if gravity is zero.

First, you should check that fluid particles have been created. Possible errors can appear in 2-D simulations when the seed point of the option “fillbox” is not located at the correct y-position. Other solution is to specify the value of ‘hswl’ with hswl value=”0.8″ auto=”false”. When using gravity zero, the value of ‘b’ needs to be specified in b value=”1.1200e+05″ auto=”false” as occurs in examples\main\03_MovingSquare\CaseMovingSquare.

19. How can I create a case without gravity?

When using gravity zero, the value of ‘b’ needs to be specified in (b value=”1.1200e+05″ auto=”false”) as occurs in examples\main\03_MovingSquare\CaseMovingSquare. Otherwise, ‘b’ is zero and gives the error shown in Question 18.

20. How can I define the speed of sound?

By default, the speed of sound (speedofsound=coefsound*speedsystem) is calculated as 10∙sqrt(g*hswl). In order to calculate a more suitable ‘speedofsound‘ for a particular case requires the user to set the parameters ‘coefsound‘ and ‘speedsystem‘.

21. What is the recommended alpha value in artificial viscosity?

The value of α=0.01 has proven to give the best results in the validation of wave flumes to study wave propagation and wave loadings exerted onto coastal structures [Altomare et al., 2015; Altomare et al., 2017]. For further details on SPH parameters setting for wave generation and propagation, refer also to [Rota-Roselli et al., 2018]. However in the simulation of other cases such as dam-breaks, the interaction between fluid and boundaries during dam propagation becomes more relevant and the value of α should be changed according to the resolution (“dp”) to obtain accurate results.

22. How can I define new properties of the particles?

The file format XML offers several resources to define new general parameters or specific properties for different type of particles. In order to load parameters from the section <parameters>, the user can mimic how this is also carried out by DualSPHysics. If different properties will be defined for different fluid volumes, section <properties> can be used (that is also explained in the XML guide).

23. How can I store new properties of the particles (e. g. Temperature)?

The new file format (.bi4) and the post-processing tools have been designed to include new properties defined by the user for its own implementation. The function JSph::SavePartData() already includes an example of how to store new particle data. Then, the post-processing codes will automatically manage all variables included in the .bi4 files.

24. How must I cite the use of the code in my paper?

Please refer to the code if you use it in a paper with reference [Crespo et al., 2015].

25. How can I start running the examples provided in the package?

The user can start running cases just by using the scripts wCase.bat in windows and xCase.sh in linux. Use the version CPU or GPU depending on your execution device.

26. How many particles should I use for wave tanks?

In the works of [Altomare et al., 2017; Rota-Rosselli et al., 2018] It was shown that using 10 particles per wave height (H) provides a good balance between computation runtime and accuracy. This means that H/dp=10 being “dp” the initial particle distance.

27. How should I create the floating objects in DualSPHysics?

After several validations conducted using experimental data of a floating box under the action of waves (09_FloatingWaves contains two cases with experimental data to compare with) it was found that floating objects should be created filled of particles. The mass of the object is distributed between the particles that form the floating object, thus using particles only in the faces leads to very high mass of those particles, so that, a higher gap between the surrounding fluid and the floating object. In the case of using external geometries (STL, VTK, PLY) it is recommended to fill the object (using the filling options of XML) with floating particles of the same MK since the 3D models only contain information of the faces and particles are only created in those faces by default.

28. How can I create the file of external forces applied to a set of particles if I know the time series of the movement?

The file “FromMotionToAcc.txt” included in examples/main/05_SloshingTank explains the procedure.

29. How do I numerically compute inflow and outflow in a given domain?

The new post-processing tool FlowTool allows computing the number of fluid particles that enters or leaves domains defined by the user. The average velocity of the particles in that domain is also computed at each output time. With the number of particles in the domain, the volume can be easily calculated by multiplying the volume of one particle by the number of particles. Therefore, the volume of fluid in some defined domains can be used to determine the inflow and outflow by dividing it with the interval time (output time). This post-processing tool is therefore very useful to compute discharges or overtopping in the case of coastal protection (an example is included in examples\main\10_WavesPistonAWAS)

30. How can I see the different functionalities of the post-processing tools?

In the folder doc/help, you can find several text files named “Code_Help.out” that contains the information of the execution parameters of the codes with description of each one and with examples to build the execution line.

31. How can I restart a simulation that was incomplete?

There is an option in DualSPHysics that allows the user to restart a simulation (-partbegin:). The new package also includes an example of how to use this option in examples/others/Restart.

32. How can I simulate a large number of floating or solid objects?

DualSPHysics was not conceived to simulate thousands of floating bodies or solid objects

The limit in the number of solid objects is related with the type of data for the label that is used along the code to identify them. The increase of this number implies a general loss of performance and higher memory consumption. Since there are few cases where users need to simulate a large number of solid bodies, this number is limited to 2,000. But compiling the code in a special way, up to 65,000 bodies can be simulated (but with performance loss).

Regarding GenCase, a 3-D Cartesian lattice is used to defined nodes where particles can be created. The type of data to label each node can be 1 or 2 bytes. This limits the number of valid labels (“mk” values) to 256 (for 1 byte) and to 65536 (for 2 bytes). Therefore, the use of 2 bytes means duplicating the memory consumption (and execution time will drastically increase), which can be a problem when generating cases of large resolution (too many particles). That is why a basic GenCase is provided (using 1 byte for labels) and a special GenCase (named GenCake_MkWord with labels of 2 bytes).

As result, if you want to simulate up to 2000 boundary or floating objects you have to use GenCase.exe and if you want to simulate more than 2000 and up to 65000 then you have to use GenCase_Mk_Word.exe and DualSPHysics compiled with an special option (activate or comment the code line #define CODE_SIZE4 in Types.h).

You can find an example using 2000 floating objects in examples/main/14_DEM.

33. Where can I download the DualSPHysics code?

The new package will be available in the usual link but also in GITHUB.

GITHUB only contains the source code of v4.2, some tools and one example, while the full package in the Downloads section of our website contains more files, more examples, codes and documentation. However GITHUB will be employed for often updates of the code with new functionalities and fixed bugs.

34. How to compute a magnitude of interest at a location that is moving during simulation?

Using BoundaryVTK, the user can save the position of a moving point using a new parameter (-saveposmotion:Mk:x:y:z) that creates a CSV file with the movement of that initial position x,y,z but using the motion applied to that Mk. This CSV file can be then loaded by MeasureTool (-pointspos file.csv).

35. How to compute different interesting magnitudes during the execution of DualSPHysics?

The XML section allows the user to compute different magnitudes during the SPH execution. This functionality can be very useful to obtain information on the fly. In this way free surface elevation can be obtained along any defined line (this option is used in AWAS) or velocity can be computed at a given position. Examples can be found in examples\others\GaugeSystem.

36. How can I modify the content of the output files for my applications?

The release includes not only the source files of DualSPHysics v4.2 but also the source files of a code named “ToVtk”. This code is provided to show how to load and interpret particle data, how to read .bi4 files and how to create .vtk or .csv files.

37. What is the new license of the open-source files of DualSPHysics?

The new license is LGPL v2.1- GNU Lesser General Public License (LGPL):
i) Software can be incorporated into both free software and proprietary software
ii) Developers and companies can integrate LGPL software into their software without being required to release the source code of their own software-parts
iii) Libraries linked to DualSPHysics can be closed source
iv) LGPL can be used in commercial applications

38. Why some cases only provide accurate results if high resolution is used?

One of the reasons for the need of high resolution in DualSPHysics is related to the employed boundary conditions here. The use of dynamic boundaries (DBC) leads to a gap between fluid and boundary particles of the order of 1.5 times the smoothing length (“h”). This gap has an important effect in the interaction between the fluid and the particles of the floating or solid object when solving the continuity equation (density evolution) with low resolution. Hence, it is necessary to increase the spatial resolution when solving density driven phenomena. Higher resolution implies higher accuracy because; i) the smoothing length is reduced, thus the fluid-boundary gap is reduced, ii) the number of particles of the boundary particle interacting with surrounding fluid particles increases. On the other hand, DBC were employed to simulate problems with floating bodies in [Barreiro et al., 2016] and [Canelas et al., 2015] where numerical results reproduce the experimental data with accuracy. In addition, complex geometries (wind turbine and boat) can be easily handled using DBC as also shown in [Barreiro et al., 2016], which is an important advantage comparing with other boundary conditions.

39. How can I generate waves in DualSPHysics?

Waves in DualSPHysics are generated by moving a set of boundary particles that form the wavemaker. The motion of the wavemaker can be defined by:

i) reading an external file with postions along time (examples/main/07_WavemakerFile)

ii) using the predefiend motions such as the sinusolidal (examples/main/06_Wavemaker)

iii) using the automatic generation with flap- or piston-type wavemaker (examples/main/08-10)