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

2 | P a g e

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

3 | P a g e

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

http://jogamp.org/jogl/www/http://www.oracle.com/technetwork/java/javase/tech/index-jsp-138252.htmlhttp://www.vtk.org/

4 | P a g e

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

Save the current

configuration to an

XML GenCase file

(once a filename has

been defined)

Close the currently

open file being edited

Exit the application

Save the current

configuration to an

XML GenCase file

(when a filename has

not yet been defined)

Opens the About dialogue

5 | P a g e

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.

6 | P a g e

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)

7 | P a g e

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.

Provide a unique name for the

geometry. This cannot be the

same as any geometry with the

same classification type

Set the geometry classification

Set the geometry type

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 supports

masking then the correct value

can be set here (see GenCase

documentation for further

details)

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

8 | P a g e

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.

If the geometry is a Fluid

then an initial velocity can

be set here

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 Specify the type of Model Element to create

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

9 | P a g e

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

10 | P a g e

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)