DualSPHysics Pre-processing Interface Documentation

Version 1.2
January 2014
Dr Stephen Longshaw and Dr Benedict Rogers
The School of Mechanical, Aerospace & Civil Engineering, The University of Manchester

Contents

1.0 Installation & Execution ........................................................................................... 3

1.1 Installation .......................................................................................................... 3
1.2 Execution ............................................................................................................ 3
1.2.1 Execution under Windows ............................................................................... 4
1.2.2 Execution under Linux .................................................................................... 4
2.0 Application Usage .................................................................................................... 4
2.1 The Menu Bar...................................................................................................... 4
2.2 The Constants Tab ................................................................................................ 5
2.3 The Geometry Tab ................................................................................................ 6
2.3.1 The Geometry Addition Dialogue ..................................................................... 7
2.4 The Parameters Tab ............................................................................................. 9
2.5 Visual Feedback Interaction ................................................................................. 10

2|Page

1.0 Installation & Execution

This section describes the steps necessary to install and execute the DualSPHysics Pre-processing
Interface application on either a Windows or Linux based platform.
Please Note for Mac OS (and other operating systems): As this program is written entirely in
Java, it will operate under Mac OS or other operating environments, however as it makes use of the
JOGL1.1.1a (reference a), Java3D 1.5.1 (reference b) and VTK 5.8 (reference c) libraries to provide
OpenGL and VTK support, it is necessary to provide access to the natively compiled binaries for
each of these. The application includes native binaries for both 32 and 64 bit Windows and Linux,
in order to gain functionality under Mac OS X or other Java enabled operating systems it will be
necessary to modify the bash script found in the Linux packages so that the variable 'Djava.library.path' is set to point to the location of the native JOGL, Java3D and VTK binaries on
the system. This software has only been tested under a Gnome based Linux environment and
Windows XP/Vista/7/8.
a: http://jogamp.org/jogl/www/
b: http://www.oracle.com/technetwork/java/javase/tech/index-jsp-138252.html
c: http://www.vtk.org/
1.1 Installation
This application has been written entirely in the Java programming language, as such installation is
as simple as extracting the contents of the archive correct for your architecture to a folder that has
both read and write access (under Linux) and executing the provided batch file (Windows) or Bash
script (Linux).
The software system requirements are as follows:

32 or 64 bit Windows or Linux Operating System.

32 or 64 bit Java VM (Virtual Machine), version 1.6 or greater.
Java system PATH or JAVA_HOME variables to be set (i.e. typing 'java' at the command
line (Windows) or console (Linux) executes the Java binary irrespective of the current
directory.
A graphics adaptor capable of supporting OpenGL 1.1 or above.
A screen resolution of at least 1024 x 768 pixels.

1.2 Execution
The application is provided in the form of an executable JAR archive and is packaged along with
the native binary libraries required to allow operation on the platform each archive is specified for.
In order to ease use, a batch file (Windows) or bash script (Linux) is provided as a means to
initialise the application. This assumes that JVM PATH variables are set (see the above section
regarding software system requirements).

3|Page

1.2.1 Execution under Windows

The batch file DPI.bat' can be executed either directly from its icon in an explorer window or by
typing its name at the command line.
1.2.2 Execution under Linux
The bash script DPI' can be executed from the console by typing 'sh dsi' or ./dsi or by double
clicking on the script in a file explorer and choosing to run the file.

2.0 Application Usage

This section provides an overview of the technical aspects of the applications usage. Generally
speaking the application has been designed to be self-explanatory, in most cases simply hovering
the mouse over an element of the interface will bring up a detailed 'tool-tip' that provides insight
into its meaning.
2.1 The Menu Bar
Opens the File menu

Open an existing XML GenCase file

Opens the Help menu

Opens the About dialogue

Save the current

configuration to an
XML GenCase file
(once a filename has
been defined)

Save the current

configuration to an
XML GenCase file
(when a filename has
not yet been defined)

Close the currently

open file being edited

Exit the application

4|Page

2.2 The Constants Tab

Set the values of each of the

simulation constants. These values
are automatically limited to stop
choices that are invalid for GenCase
being made.

5|Page

2.3 The Geometry Tab

Set the global geometrical

properties

Define the simulation as

2D or 3D

Reset the current view to

the default settings

A preview of the current state of

the simulation geometries. See
section 2.5 for an overview of the
available interaction methods.
Please Note: More complex
shapes (such as input files or a
prism) are represented as a
bounding box only. Less
complex shapes (such as a
triangle or sphere) are
represented realistically

A list of currently defined

geometries. Use the respective
buttons to add (see section 2.3.1)
new or remove existing geometries.
Double clicking on an existing
geometry will allow some of its
properties to be edited.
Please Note: Just because a
geometry exists here does not
mean it will be saved to the XML
file, that only occurs once the
geometry has been used in the
Model Definition. Any geometry
added but not used will be lost
once the application is closed or a
new file opened

A list of the currently defined Model Elements. These may

include fluid/boundary/void geometries defined in the
Individual Geometries section or they may be conceptual
elements such as Fill Areas or geometrical transformations. The
respective buttons may be used to either add (see section 2.3.2)
new elements or remove existing elements. Selecting an item
here (single click) will highlight it in the visual feedback area
(where appropriate) while double clicking will allow some of
its properties to be edited.
Please Note: The order that items appear in this list dictates
the order that they will be written to the XML GenCase file.
This becomes important to consider when transformation
or matrix resets are included as a transformation will affect
all appropriate elements that follow them (until a matrix
reset is included)

6|Page

2.3.1 The Geometry Addition Dialogue

The geometry addition dialogue automatically modified its contents to reflect the Geometry Shape
type currently specified. The example shown here reflects the addition of an external file
(STL/VTK/PLY). In the case of others different information will be requested. In all cases checks
take place to ensure that 'OK' can only be pressed once enough information has been provided to
define the chosen geometry type.
Once a geometry has been defined it will appear in the Individual Geometries list but will not
appear anywhere else. For it to show in the visual feedback area it first needs to be added as a
model element.
Set the geometry classification

Provide a unique name for the

geometry. This cannot be the
same as any geometry with the
same classification type

Set the geometry type

If the geometry supports

masking then the correct value
can be set here (see GenCase
documentation for further
details)

Set the drawing mode for this

geometry (see GenCase
documentation for further
details)
If the geometry is a Boundary
then it can be set to be
considered as floating, this also
means that the physical
parameters in Floating Body
Properties can be set

If the geometry is a Fluid then

it can be given an initial
velocity here

This area modified its content depending on

the selected geometry type. It allows
important details such as the file path (in the
example case) or vertex information to be
set

7|Page

2.3.2 The Model Element Addition Dialogue

The model element addition dialogue allows you to create the logical definition of the simulation.
The order that these elements appear in the interface dictates the order that they will appear in the
GenCase input XML created. Where appropriate, model elements will show in the visual feedback
section of the Geometry tab. In the case of more complex geometries (such as external files or a
prism) then a bounding box is shown, in cases of simpler geometries (such as a line or a triangle)
the actual geometry is shown. Transformations are automatically applied to the visual output as they
would be by the GenCase application.

Specify the type of Model Element to create

In the case of a geometry (Boundary/Fluid/Void) being

specified as the Element Type, the appropriate drop-down
list will enable and allow the correct geometry to be
selected according to the unique name entered during its
creation

When appropriate, a colour can be

selected here that is reflected in the
visual feedback area to allow this
Model Element to be differentiated

This area automatically changes to allow the necessary

information to be entered to define the chosen Model
Element type. The example shown here is of a Fill Area
being defined, however this area would appear different if
it was a geometry or transformation being entered

8|Page

2.4 The Parameters Tab

The simulation parameters can be set here. In each case

the value defined is checked for validity and provides
detailed information in the form of a tool-tip if the mouse
is hovered over the area

This area allows custom parameters to be added to the

XML file. A custom parameter consists of a key (the
reference read in by the DualSPHysics software), a value
(the value that is then associated with the key) and a
comment (which can be blank, however providing a
description here can be useful when distributing the
resulting XML to others). A parameter is added by
entering at least a key and value and then pressing the Add
button. Existing parameters can be removed by
highlighting them in the list and pressing the Remove
button

9|Page

2.5 Visual Feedback Interaction

The visual feedback area provided in the Geometry tab is interactive. It provides the following
functionality:

Model rotation (left-click and hold and the model will follow mouse movement)
Model translation (right-click and hold and the model will translate with mouse
movement)
Model scaling/zooming (zooming in can be achieved by moving the mouse-wheel
upwards, zooming out can be achieved by moving the mouse-wheel downwards)

10 | P a g e