FAQ: Frequently asked questions
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.
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.
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.
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.
Section 6 of the guide introduces the source files including some call graphs for a better understanding.
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
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.
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.
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:
so that the limits can be specified instead of using initial particle positions.
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).
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.
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.
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].
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.
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).
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.
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).
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.
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.
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‘.
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.
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).
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.
Please refer to the code if you use it in a paper with reference [Crespo et al., 2015].
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.
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.
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.
The file “FromMotionToAcc.txt” included in examples/main/05_SloshingTank explains the procedure.
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)
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.
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.
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_Mk_Word.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.
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.
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).
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.
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.
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
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.
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)