Feature Reference - DualSPHysics/DesignSPHysics GitHub Wiki

This page contains a feature reference for DesignSPHysics. Here you can found an extensive feature description and usage for the software.

Each section is documented as a tutorial. This document is updated to the version 0.20a, so if you are using a higher version expect changes.

Installing

For installing DesignSPHysics is recommended to check out the Installation page. It contains information on the way to install it in Microsoft Windows and GNU/Linux.

Starting DesignSPHysics

To execute DesignSPHysics you need to have it Installation and your FreeCAD version shoud be 0.17 or higher.

First of all, open FreeCAD. You should see an start page with no projects opened. Click on the 'Execute Macro' button to open a dialog.

In the dialog that appears, select DesignSPHysics and press 'Execute'.

DesignSPHysics will load and when a side panel appears, you're ready to go.

Configuring DesignSPHysics

The first time you execute DesignSPHysics you'll see a warning informing you that some of the executables are not correct. This won't happen if you installed DesignSPHysics bundled with DualSPHysics, as it will be automatically configured.

In the case you get the warning dialog, this happens because DesignSPHysics needs to use GenCase, DualSPHysics and several post-processing tools, and you need to provide this binaries for your own.

Click the 'Setup Plugin' button at the right toolbar (by default) to open a Setup dialog, in which you can set the path to the needed binaries.

Click the '...' button in each section to select the right binary file. If a file is not correct, DesignSPHysics should spawn a warning dialog.

Once you set the binaries, push Ok and the information will be saved on disk, so the next time you execute DesignSPHysics you'll not need to do this again.

Creating a Case

Creating a case opens a FreeCAD Document specifically modified to work with this software. Note that creating a new FreeCAD document with the 'File' menu will not create a correct DSPH-compatible file.

To create a case just press 'New Case' in the right side of the screen (by default). An default setting will be opened in FreeCAD. You will see a 'DSPH_Case' in the object tree, with only one element inside: 'Case_Limits'. This object will represent the boundaries of the case simulation, and everything outside that volume will be ignored.

That's it! You have a new case created.

Configuring a Case constants

A DSPH case has 2 main variable definition: A Case constants and execution parameters. This section covers the constant definition.

To define the constants of the open case, click the 'Define Constants' button in the right side of the screen (by default). A window will pop with data.

Each field of the constants definition can be edited but, by default, all data will be filled with optimal values.

Some of the most relevant things to change is the fluid reference density or the gravity.

Configuring a Case execution parameters

Similar to constant definition, execution parameters covers the case variables that define execution.

To define the execution parameters, click the 'Execution Parameters' button in the right side of the screen (by default). A window will pop with data.

Each field of the execution parameters can be edited but, by default, all the data will be filled with optimal values.

Some of the most relevant things to change is the time of simulation, viscosity or max parts out allowed, as well as enabling periodicity conditions for the case boundaries.

Loading a Case

Loading a case opens a previously DesignSPHysics compatible case. DesignSPHysics opens *.dsphdata files A bare bones case must be inside a folder and contain a ''casedata.dsphdata'' file and a ''DSPH_Case.FCStd'' file. The name of the folder containing this elements will be the name of the case.

To load a case, press the 'Load Case' button at the right side of the screen (by default). In the file selector that pops in, select the *.dsphdata file that you want to open.

The case will be opened as a FreeCAD document with all of the previously modified data set.

Saving a Case

Saving a case does multiple things:

• Creates a folder with the name of the case
• Saves a FreeCAD document inside the created folder
• Saves a *.dsphdata file containing DSPH specific data for this macro
• Exports an XML file with the case details, for using with GenCase
• Exports to STL all needed non-compatible geometry
• Creates a Microsoft Windows compatible batch script for simulating in command line
• Creates a Bash compatible batch script for simulating in command line
• Tries to execute GenCase with the provided data.

As you can see, the saving feature does a really big chunk of the total work in a simulation.

To save, press the 'Save Case' button. If everything went well, a dialog will pop up indicating how many particles GenCase exported and a button to check the complete output of GenCase.

If GenCase can't be found, it will only save the case data and FreeCAD document.

Generating a Case to simulate

If you want to generate a case to simulate, you just need to check how to save, as it does it automatically.

Check out how to

Simulating a Case

Simulating a Case will take the case generated previously to DualSPHysics. Simulating is usually a time consuming step, so make sure your case is correctly defined first.

To simulate a case make sure you saved your case, so the info in disk is accurate. Then, select the preferred processing for simulating:

• CPU: Executes a simulation in all possible CPU threads. Useful for light simulations or non GPU-equipped computers.
• GPU: Executes a simulation in all CUDA cores of the most powerful GPU installed in the system. This feature only works if your graphics card supports CUDA (tipically NVIDIA GPU's)

Once selected, you have 2 options: To set additional parameters, with the 'Additional parameters' button, or simulate pressing 'Simulate Case'

During simulation, a window will pop with useful simulation data, such as the case name, the processor selected, the total number of particles, the particles that went out of case, and the estimated date of completion.

Execution post-processing tools

The simulation process generates binary data for post-processing, but it is not suitable to represent in a software for visually checking results. Also, it does not help to measure magnitudes.

To allow that, you can execute a series of post-processing tools.

To execute a post-processing tool, you can do it so in any state of the case simulation. Take note that in cancelled simulations or currently running ones you won't get a complete export. Just use one of the post-processing buttons in its respective section (at the bottom of the main DesignSPHysics panel) and fill the corresponding parameters to export.

A window with a progress bar will show during post-processing, in which you can cancel the progress. When the exporting finishes, the window will close automatically.

Inside the case folder, in the name_Out folder, post-processing output files will be created, that you can open with a compatible software for checking results.

Case construction

This section defines how to make case geometry and change its properties for simulation. Although most of the case making is based on FreeCAD common usage, there are some DSPH-specific features that are explained here.

It's important to be somewhat used to FreeCAD to use this tool, so is recommended to check out the Tutorials section of the FreeCAD official Wiki

Modifying the Case Limits

The Case Limits represents the space in which the simulation will take place. For example, if you place a cube half in the limits and half out, when you process the case (with GenCase) only the inner half remaining cube will be considered for simulation.

That behaviour allows you to create slicings of some object or change an entire scene based on positioning the limits.

To edit the case limits you will need to have a DualSPHysics case opened. You should see a box in red wireframe. To edit it, treat it like a FreeCAD common object, so click in it in the object tree and edit its properties (size, position) to suit your needs.

That's it, remember to ensure that the case limits contains all the elements in the simulation.

Modifying inter-particle distance

The inner-particle distance, or dp, is a unit of metres that sets the space separating each particle generated in the case. Modifying this value automatically increases or reduces the quantity of particles in the final simulation.

Note that a higher number of particles (lower inner-particle distance) will result in a high fidelity simulation (but pretty load-heavy) and vice-versa.

To change the inner-particle distance just change the value in its respective input field, on the right side of the screen (by default), below 'Execution Parameters'. To see how many particles will be in the simulation, just save and let GenCase do its job.

Creating objects

Creating objects is simple. Just do it like in FreeCAD.

For example, for creating a cube, make sure the 'Part' workbench is selected (in the top of the screen by default) and click the cube icon (also in the top bar by default).

Be sure to experiment with FreeCAD first, as it is pretty easy to make 3D scenes.

Adding objects to simulate

Even though you could create FreeCAD geometry wherever you want, maybe you don't want it in the simulation, just as a helper or a test object. So for adding an object to a simulation you need to do one more step.

If one of your objects is suitable to be in the simulation, just click in it and a 'Add to DSPH Simulation' button will appear at the left side of the screen (by default) when an object is selected. Pushing that button and you can see the object selected is now included in the simulation objects table, at the lower right side of the screen (by default).

As simple as that, you have an object included in your simulation.

Setting objects as fluids or bounds

Once an object is added to the simulation, you can change its properties, including the object type. To change the type of an object click in it and its properties will appear at the left side of the screen (by default). If not, make sure your object is in the simulation. Change the 'Type of object' property to Fluid or Bound.

You will see how the selected object changes color, representing that it is a fluid (semi-transparent blue) or a solid (opaque gray).

Changing an object MK Group

The simulation objects are grouped on 2 MK groups: MKBound and MKFluid.

For each bound object, you can make it belong to a certain MKBound for further editing (make the group float, for example). The same works with fluids.

Another interesting feature of grouping by MK is object discrimination at the time of seeing simulation results, as the MK Group will be saved in the final VTK format, and allows you to change the colour of the entire group or even hide it from the view in most visualization programs.

To change an object MK Group simply click in it and, in the property table at the left side of the screen (by default), change the MKBound/MKFluid property to the value you want. Bear in mind that the total mkbound number is 240 and the total mkfluid is 10.

Changing an object fill mode

The fill mode of an object represents the way in which the particles of an object will be created.

You can set 4 diferent modes for each object:

• Full: Fills the inside of the body with particles and also generates an outer frame in the object.
• Solid: Fill the inside of the body with particles but does not generate an outer frame (useful for adjacent objects)
• Face: Generates only an encasing for the body, leaving the inside hollow. Useful for making containers
• Wire: Generates only the wireframe of the 3D object.

To set an object fill mode just click in it and change the 'Fill mode' property on the left side of the screen (by default).

Take note that complex objects can only be created as 'Face'. This is a limitation of GenCase, but you can use a FillBox to fill a complex object with bound material.

Adding fillboxes

You can make objects by creating cubes, spheres, cylinders... but with complex objects you can only create particles on the faces. So another way of creating objects is filling a volume with particles. Fill boxes do exactly that.

A Fill Box is an object consisting of 2 components:

• Fill Limit: A cube that delimits the maximum area to fill
• Fill Point: The seed point of the particles from whom the object will start spawning.

To create a Fill Box you need to click in the 'Add fillbox' button at the right side of the screen (by default).

A Fill Box is represented in FreeCAD by a group of the 2 components, so you need to add the group to the simulation, but edit the discrete components to modify the fill box behaviour.

Changing the export order

The export order is a crucial step on a simulation. The way of creating particles in the case is incremental, so, to explain this behaviour, let's give an example:

Imagine simple case with 2 cubes, one bigger than the other, both solid. The small one is inside the bigger one.

So let's say you want the small cube be a fluid inside the big one. If the object order is:

• Small cube
• Big cube

The final case will show only a big solid cube, and no fluid will be present. That's because of the way the particles generate. The big cube particles share space with the smaller one, so if the big cube generates in second place, the already generated fluid particles will be overwritten.

To make the case as we want, we should set the order as:

• Big cube
• Small cube

So the already solid particles created by the big cube will be overwritten by the fluid particles of the small cube.

To change the export order click the up and down arrow buttons that appear in the order table (at the right side of the screen by default) when multiple objects are added to simulation.

Make sure that the order of the object is coherent with what you want.

Configuring float state on an object

The bound objects of a simulation can be still, but also can be floating. If you want an object to be floating you have to configure its float state.

To do that, press the 'Configure' button on the float state property that appears when you have an object selected.

A window will appear to configure the floating. Make sure 'Set floating' is set to True if you want the object to float. The rest of parameters define how will it float.

Bear in mind that the floating properties apply to all objects with the same MKBound. So if you want only one object to float make sure its the only one with the specific MKBound you are editing. DesignSPHyiscs will alert the user of this behaviour once floating properties are changed.

Configure initial velocity of a fluid

The fluids of the case can have a custom velocity vector applied at start. This will result in all fluid particles of an MK group moving at the start of the simulation.

To achieve this, you will need to add an object and configure it as a fluid. Once done that, the initials property of the object will appear active.

Click on the Configure button for the initials property, and in the window that opens set it to true. Then, input the velocity vector and press Ok.

Note that changing this will make that all fluids with the selected mk will have this initial velocity!

Configure object motion

Solid objects can have a motion applied. This allows to create pistons and movement bodies to check what happens to fluids around them.

To make an object move you have to enable it in its properties. Select the desired object and click the Configure button at the Motion property (by default in the left side of the screen).

Before starting, take into account that the movement will be applied to all objects with the same MKBound, so if you only want one object to move be sure to put an MKBound value that doesn't repeat in any other object.

Once the Motion configuration window is open, you can enable or disable movement for that object setting the 'Set motion' option to True.

This would allow you to create and edit movements, and use them for that MKBound.

The movements that you create and configure will not be removed from there even if you don't apply them to the object. This happens because defining movements can be difficult and you could want to share the same movement to multiple MKBound groups. Also, this allows you to test different movements easily.

To create a new movement use the 'Create New' button in the current window. You can also check the dropdown menu of that button to see different kind of movements.

When a movement is created it will be selected to use by default. This can cause other ones to be disabled because incompatibility, so check that.

You can combine multiple common movements in one MKBound, but all the other movements (wave generators or movements from a file) are exclusive.

To edit a movement click in its name (you can change its name double-clicking on it) and you should see a Timeline for the movement at the center of the screen.

These are the different possibilities:

For regular movements

One created, if you click in the regular movement you should see an empty timeline at the center of the window. You can add different actions for the movement (such as delay, rectilinear motions, etc) with the buttons at the right side.

Just click in the ones you want to add and edit its properties and order with the timeline controls at the center of the window.

You can also loop a movement by checking the 'loop' property at the left.

For wave generators

With regular and irregular wave generators you can only edit its properties, and not add actions to the timeline.

These are special movements and cannot be looped, at they are automatically looped by nature.

For movements from a file

File movements are similar to wave generators as only its properties can be edited and no actions can be added to the timeline.

To set a motion from a file make sure to input a path to the external file in the 'File name' field, by typing it or using the browse button.

Importing custom STL files

Since FreeCAD does not support scaling for external STL files, a functionality to do so is included into DesignSPHysics.

You can use it with the 'Import STL' button in the pre-processing section. Just select an STL file and edit its scale factor. Also, you can change it name. Press import and use it as another object for your case.

Seeing a summary of the case

To see a summary with all the case constants, parameters etc just use the 'Case summary' button in the pre-processing section.

You can see in there a lot of information there in one place to easy check how a case is defined.

Changing between 2D and 3D case definition

A DesignSPHysics case can be 3D (by default) or 2D. To change the case to a 2D definition use the button 'Change 3D/2D'. While changing to 2D mode a dialog should appear asking you where to slice the case in the y coordinate. Input the desired value (you can move the case limits later, too) and press OK.

You have now a 2D case. This means the case limits is now a plane and can't be resized in the Y coordinate.

To continue defining the case do it like if it were a 3D one.