This page contains a feature refence 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.

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.

To execute DesignSPHysics you need to have it installed and your FreeCAD version shoud be 0.16 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 DSPH.py and press 'Execute'.

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

The first time you execute DesignSPHysics you'll see a warning informing you that some of the executables are not correct. This happens because DesignSPHysics needs to use GenCase, DualSPHysics and PartVTK, 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 3 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 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.

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

To define de 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.

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.

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 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.

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 save 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.

The simulation process generates binary data for postprocessing, but it is not suitable to represent in a software for visually checking results. To allow that, you can export the simulation data to VTK files, that can be opened with ParaView, for example.

To export data, just make sure you simulated the case you want to export, and press the 'Export data to VTK' button at the right side of the screen (by default).

You can also click in the Options button to set additional export parameters.

A window with a progress bar will show during exporting, 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, a list of PartAll_X.vtk will be created, that you can open with a compatible software for checking results.

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.

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.

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 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.

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). Push 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.

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.

Note that you cannot set complex objects to a fluid type. For that you need to use a Fill Box

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

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 reference (make the group float, for example). The same works with fluids.

Another interesting feature of grouping 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.

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.

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:

1. Full: Fills the inside of the body with particles and also generates an outer frame in the object.
2. Solid: Fill the inside of the body with particles but does not generate an outer frame (useful for adjacent objects)
3. Face: Generates only an encasing for the body, leaving the inside hollow. Useful for making containers
4. 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).

You can make fluid objects by creating cubes, spheres, cylinders… but not with complex objects. So another way of creating fluid is filling a volume with it. 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 fluid from whom the fluid 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), just below the save button.

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.

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:

1. Small cube
2. 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:

1. Big cube
2. 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 'Move up' and 'Move down' 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.

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.

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!