DualSPHysics Interface Documentation

Transcription

1 DualSPHysics Interface Documentation Version 1.1 (05/07/2013) S. M. Longshaw & B. D. Rogers Smoothed Particle Hydrodynamics Expert Group, The University of Manchester 1 P a g e

2 Contents 1.0 Installation & Execution Installation Execution Execution under Windows Execution under Linux Application Usage The Menu Bar The Constants Tab The Geometry Tab The Geometry Addition Dialogue The Model Element Addition Dialogue The Parameters Tab Visual Feedback Interaction P a g e

3 1.0 Installation & Execution This section describes the steps necessary to install and execute the DualSPHysics 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 JOGL 1.1.1a (reference a), Java3D (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 is packaged as x86 and x64 releases of the application and include binaries for Windows and Linux, in order to gain functionality under Mac OS or other operating systems it will be necessary to modify the bash script found in the Linux package 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. Please note: this software has only been tested under a Gnome based Linux environment and Windows XP/Vista/7/8. a: b: c: 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 (specifically under Linux) and executing the provided batch file (Windows) or Bash script (Linux). The software system requirements are as follows: 32/64 bit Windows or Linux Operating System. Java VM (Virtual Machine) 1.6 or greater that is suitable for the OS s architecture. Java PATH or 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, or JAVA_HOME is set.) 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 P a g e

4 1.2.1 Execution under Windows The batch file 'dsi.bat' can be executed either directly from its icon in an explorer window or by typing its name at the command line Execution under Linux The bash script dsi' 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 Save the current configuration to an XML GenCase file (when a filename has not yet been defined) Opens the About dialogue Exit the application 4 P a g e

5 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 P a g e

6 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 P a g e

7 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 drawing mode for this geometry (see GenCase documentation for further details) Set the geometry type If the geometry supports masking then the correct value can be set here (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 modifies 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 P a g e

8 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 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 When appropriate, a colour can be selected here that is reflected in the visual feedback area to allow this Model Element to be differentiated 8 P a g e

9 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 P a g e

10 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