preonlab 2.2.1 user guide - fifty2 technologyfifty2.eu/preonlab/preonlabmanual_v2_2_1.pdf ·...

PreonLab 2.2.1User Guide

Get support via:m http://help.preonlab.eu/B [email protected] +49 (0) 761 45 89 23 81Mo-Fr: 9am-5pm (CET)

September 2017 FIFTY2 Technology GmbH

http://help.preonlab.eu/mailto:[email protected]

Contents

1 About 1

2 General 22.1 Installation / Update 22.2 Licensing 32.3 User Interface overview 42.4 Known issues and workarounds 6

3 Object Tools 73.1 Translate 73.2 Rotate 73.3 Scale 73.4 Placement tool 73.5 Measure tool 8

4 Connections 94.1 Using the connection editor 104.2 Grouping objects 104.3 Transform connections 10

5 Keyframing 125.1 Keyframe editor 125.2 Shortcuts 145.3 Best practices 15

6 Scene and basic objects 166.1 User Preferences 166.2 Scene 166.3 Scene UI Settings 176.4 Transform groups 186.5 Point 18

7 Common properties 197.1 General 197.2 Appearance 197.3 Transformation 207.4 Statistics 21

8 Fluids 228.1 Preon solver 22

Contents i

8.2 Preon mesher 28

9 Sources 319.1 Square source and circle source 319.2 Area source 319.3 Flat jet source 329.4 Volume source 339.5 Rain source 35

10 Boundary Domains and Conditions 3610.1 Box and cylindrical domain 3610.2 Maximum velocity condition 38

11 Force Fields 3911.1 Gravity 3911.2 Drag Force 3911.3 Air Flow 41

12 Solid Objects 4412.1 Rigid body simulation 4512.2 Visualization of solid objects 4612.3 Primitive shapes 4712.4 Mesh 4812.5 Alembic Mesh 4912.6 Porous Rigid 5012.7 Changing the pivot / center-of-mass 5112.8 Rotating around a custom axis 51

13 Rendering 5213.1 Cameras 5213.2 Clipping object 5313.3 Lights 5413.4 Preon renderer 5513.5 Materials 5813.6 Best practises 59

14 Sensors 6314.1 Sensor color legend 6314.2 Distance sensor 6314.3 Volume sensor 6414.4 Wetting sensor 6414.5 Force sensor 6614.6 Pathlines 6714.7 Sensor plane 6914.8 Projection fields 7114.9 Air flow visualizer 7114.10 Plots 72

15 Import & Export 7415.1 Save as portable 7415.2 Archiving and reducing disk space consumption 74

Contents ii

15.3 Import Adams data 7415.4 Import VDAFS data 7515.5 Import Alembic file 7615.6 Import Airflow 7615.7 Export Alembic file 7715.8 Export particle data 7715.9 Export to EnSight 7715.10 Export video 78

16 PreonLab CLI 8016.1 Simulating a scene 8016.2 Running a Python script 8016.3 Optional start parameters 80

17 Python API 8217.1 Installation as Python package 8217.2 Usage 85

Contents iii

1 About

PreonLab is a physically-based simulation framework which is developed to simulatefree-surface flows as fast as possible.

We believe that this is influenced by three main factors: efficiency, usability, and re-liability.

Efficiency: PreonLab is powered by our point-based fluid simulation kernel PREON .The key idea behind PREON is to avoid artificial and specialized models to capturespecific properties of real-world fluids. Instead, PREON solves the fundamentalphysical equations that govern the flow of fluids in a very fast and resource efficientway, allowing simulation in unprecedented resolutions. This opens a completely newrange of simulation possibilities revealing new insights in the early stages of engi-neering development and design.

Reliability: Reliability is crucial for professional software. For us, this does not onlymean that we have tomeet our own high standards in terms of security and softwarequality, but most of all delivering solid simulations that meet the expectations of theengineer. Reproducible simulation results and validation are in the focus of our dailywork and throughout our internal quality requirements.

Usability: We believe that simulation tools can be user friendly and should not beoverloaded with hundreds of options and parameters to set. Our goal is to con-dense the options as much as possible, so that your workflow is optimized, while thechances ofmisconfiguration isminimized. PreonLab drastically reduces your prepro-cessing effort and provides strong postprocessing capabilities.

About 1

2 General

2.1 Installation / Update

2.1.1 Windows

PreonLab runs on Windows 7 and higher versions. Please note, that you will needadministrative privileges in order to install, update or uninstall PreonLab on Win-dows. Therefore, we recommend to right-click onto the respective file and selectRun as administrator to launch the process.

Installation: PreonLab is provided to you as an installer program, e.g. PreonLabIn-staller.exe. The graphical installer will lead you through the installation process.

Update: PreonLab automatically checks for updates during the startup process, ifa network connection is established. If a new version is found, you will be informedabout the changes of the new version. You can alsomanually check for updates usingPreonLabMaintenance.

Uninstallation: You can uninstall PreonLab using PreonLabMaintenance. You can alsouse the Programs and Features tool from your system settings and choose Preon-Lab for uninstallation.

2.1.2 Linux

Installation: PreonLab is provided to you as an executable, e.g. PreonLabInstaller. Itmay be necessary to setup Execute file permission to the installer file in a terminalwindow:

chmod +x PreonLabInstaller

The graphical installer will lead you through the installation process.

Update: PreonLab automatically checks for updates during the startup process, ifa network connection is established. If a new version is found, you will be informedabout the changes of the new version. You can alsomanually check for updates usingPreonLabMaintenance.

Uninstallation: You can uninstall PreonLab using PreonLabMaintenance. You can alsojust delete the complete folder containing PreonLab, e.g /opt/PreonLab.

General 2

2.1.3 preonpy

The Python API preonpy is integrated into PreonLab and PreonLabCLI, but it is alsoavailable as a regular Python package. See Section 17.1.4 for further instructions onhow to install it into an existing Python 3.5 or 2.7 installation. Also see Chapter 16 forinformation about PreonLabCLI and Section 17.2 about general usage of the preonpyAPI.

2.1.4 Systems without graphics

PreonLab requires a graphical desktop environment and a graphics card, that sup-ports at least OpenGL 3.3. The command line version PreonLabCLI as well as thePython package do not require graphics. It can be used to run simulations or exe-cute Python scripts, that utilize the preonpy API.

For RHEL6 and RHEL7, there are separate downloads available that only contain Pre-onLabCLI and can simply be installed and used on a system without graphical desk-top environment by unpacking the provided zip-files. preonpy can be installed as aPython package using common Python tools (see Section 17.1.4).

2.2 Licensing

Figure 1: Licensing dialog.

When you start PreonLab for the first time, you will be asked for a valid product li-cense. PreonLab uses the Reprise License Manager (RLM). We allow two differentlicense types:

Workstation license: This license is node-locked to a single computer and will notwork on any other computer. It can be provided to PreonLab as a local license file or

General 3

via the RLM license server. If this is your type of license, we have sent you a singlelicense file (e.g. license.lic).

Floating license: A license which is served by an RLM license server. If this is yourcurrent licensing model, your IT administrator has received both, a license file andthe specific FIFTY2 server settings from us. If your license server is within your LAN,it will automatically be found by PreonLab.

If you have not yet imported any license, PreonLab will let you choose between dif-ferent options for licensing. You can either import a local license file, or enter theaddress of the RLM license server, if this is not automatically broadcasted in your net-work. Reprise provides an extensive manual for license administrator and users thatcan be found at http://www.reprisesoftware.com/admin/software-licensing.php

2.2.1 Installation of an RLM license server

1. Please install an RLM server on the computer with the MAC-address for whichthe license was created. You can download the RLM server from here:

http://www.reprisesoftware.com/admin/software-licensing.php.

2. Download two more files from our transfer server. The link has been sent toyou via email along with the license file. On Linux, download the files fifty2 andfifty2.set from the RHEL 6:7 folder. On Windows, the files fifty2.exe and fifty2.setare found in theWindows folder.

3. Put your license file (ends with .lic and was sent to you by email) and the twofiles described above into the installation folder of the RLM server you haveinstalled. Afterward, the server has to be started and should then be ready touse.

4. Now, when starting PreonLab on a computer inside your LAN, PreonLab shouldautomatically find the license server. If this does not work, try to enter the ad-dress of the license server when prompted.

2.3 User Interface overview

The user interface is exemplified in Figure 2.

2.3.1 Navigating in the graphics window

Control What it does

left mouse button click Select object under mouse pointer.

CTRL pressed + leftmouse button clicks

Select multiple objects.

General 4

http://www.reprisesoftware.com/admin/software-licensing.phphttp://www.reprisesoftware.com/admin/software-licensing.php

left mouse buttonpressed + move mouse

Select multiple objects which are within the drawn rectangle.

mouse wheel click If mouse pointer is over an object, the camera pivot is set suchthat the camera canbe rotated around the corresponding pointon the object.

mouse wheel, or rightmouse button pressed+ mouse move

Zoom in and out.

control key pressed+ left mouse buttonpressed + mouse move

Rotate the camera. By default, the control key is SHIFT. This canbe customized, see Section 6.1.

control key pressed +mouse wheel pressed +mouse move

Translate the camera (panning). By default, the control key isSHIFT. This can be customized, see Section 6.1.

Table 1: Controls for navigating in the graphics window.

2.3.2 Keyboard shortcuts

Key What it does

w Enters / leaves translation mode.

e Enters / leaves scale mode.

r Enters / leaves rotation mode.

p Enters / leaves placement mode (if available).

CTRL + d Duplicates the selected object.

DEL Deletes the selected object(s).

CTRL + h Toggle between the render modes of the selected object.

CTRL + k Creates a transformation keyframe (position, orientation,scale) at the current frame for the selected object using linearinterpolation.

CTRL + l Creates a transformation keyframe for the selected object atthe current frame using sinus interpolation.

CTRL + s Save current scene.

CTRL + n Create a new scene.

CTRL + o Open a scene.

CTRL + q Close PreonLab.

CTRL + c Copy the selected object(s) into your clipboard. These objectscan be pasted into the same or another PreonLab instance.

CTRL + v Pastes previously copied objects.

Table 2: List of keyboard shortcuts.

General 5

Figure 2: PreonLab user-interface.

2.4 Known issues and workarounds

2.4.1 OpenGL

On some Linux-based systems, PreonLabmay show various artifacts when displayinglines. This canusually be fixedby starting PreonLabwith the option --noGeometryShaders.The only restriction of using this flag is that all lines will have a width of one pixel.

2.4.2 Display resolution

Changing the resolution of your displaywhile PreonLab is runningmight lead to someinconsistencies in the user-interface. This is fixed when PreonLab is restarted.

General 6

3 Object Tools

PreonLab contains multiple tools to move, rotate and scale objects in space, and tomeasure a distance between any two points on objects in the scene. The tools canbe accessed using the toolbar at the top. You can read about their hotkeys/shortcutsin Section 2.3.2.

3.1 Translate

Shows a dragger tool to translate the currently selected object(s). You can togglebetween moving along the unit axis or along the local rotated axis by toggling theLocal button in the toolbar.

3.2 Rotate

Shows a dragger tool to rotate the currently selected object(s). You can toggle be-tween rotating around the unit axis or around the local rotated axis by toggling theLocal button in the toolbar.

3.3 Scale

Shows a dragger tool to scale the currently selected object(s).

3.4 Placement tool

The placement tool places the currently selected spatial object onto another spatialobject on a left mouse button click. This tool can only be activated and is only shownif exactly one object is selected. If the mouse cursor is not hovering over any spatialobject on click, or if the mouse was moved between pressing and releasing the leftmouse button, no action is performed.

Object Tools 7

3.5 Measure tool

The measure tool allows you to measure the distance between two points in thescene. When activated, every two left mouse button clicks on spatial objects or fluidparticles will show the distance between the two defined points on the screen overlayunder Measure tool. When both these measure points are set, an additional buttonappears allowing to save the current measurement. Saving a measurement resultsin both measure points appearing in the scene inspector, connected to a new dis-tance sensor, while the Transform output of the spatial object(s) where the pointswere placed on is also automatically connected to the points. This simplifies the pro-cedure described in 14.2.

Object Tools 8

4 Connections

Figure 3: Connection editor.

A connection establishes a relation between two objects. Connections are alwaysdirected, they start from one object and end in another object. Figure 3 shows con-nections after inserting a fluid solver, a circle source, a sensor plane and a mesherinto an empty scene. The default gravity is connected to the solver via the ForceFieldslot which ensures that the fluid simulated by the solver is subject to gravity. Thecircle source is connected to the solver via the ParticleEmitter slot, so that the fluidparticles generated by the source are simulated by the solver. In turn, the fluid par-ticles simulated by the solver feed into the sensor plane and the mesher object. Allthese connections were created automatically by PreonLab when inserting the ob-jects. However, there are cases in which it is necessary to create connections man-

Connections 9

ually, for instance when using multiple fluid solvers or sensors on geometries. An-other use case for manual connections are Transform connections that are discussedin Section 4.3.

4.1 Using the connection editor

The connection editor shows all objects in the scene and their connections, while theselected ones are highlighted. You can limit the displayed objects using the optionsin the top left of the editor to the currently selected objects or those together withits neighbors. To center the selected objects in the view, you can use the button onthe top right. For each object, the connection editor displays all available input andoutput slots. Input slots are located on the left, while output slots are located onthe right. To view all available slots for an object, expand the object by clicking onthe white arrow to the left of the object name. New connections can be created byclicking on an output slot and releasing the mouse on an input slot of another object.Existing connections can be deleted by clicking on the connection and pressing thedelete key.

4.2 Grouping objects

To gain better overview and perform multiple connection task on a set of objects,you can use the grouping feature. To use it, select similar objects by left-clicking anddrawing a rectangle around them. All contained objects will then be merged intoa group. Common connections are displayed as a single edge. You can add andremove connections from groups as you would do with regular objects. This cor-responds to adding/removing connections to/from all contained objects separately.Note that only those slots are available, that all contained objects have in common.If connections are not shared by all objects, a dashed edge is displayed. Those canbe deleted or a new edge can be drawn over it, to unify the group. Moving a groupbox translates the position of the contained object boxes.

4.3 Transform connections

The Transform connection allows you to combine the transformation of one objectwith the transformation of another object. In general, this can be used to specify thetransformation of one object relative to the transformation of another. A simple usecase is to move multiple objects synchronously by keyframing a single parent object.If there is an Transform connection from an object A to an object B, we say that objectB derives its transformation from object A and that object A is the parent of object B.Note that only position and orientation are derived, while scale is not.

Connections 10

4.3.1 Relative transformations

Be aware that once an object derives its position and orientation fromanother object,themeaning of the position and orientation displayed in the property editor changes.These properties are now relative to their parent and do not state the global positionand orientation of the object. This also has consequences when creating a Transformconnection. Lets consider an object A located at position (10, 0, 0) and an object Blocated at (0, 0, 0). Now a Transform connection is created from object A to object B.Youmay notice that while object B remains at the same place, its position displayed inthe property editor changes to (10, 0, 0). PreonLab does this automatically to keepthe object at the same global position. In general, PreonLab always preserves theglobal position and orientation of an object when creating or removing a transformconnection and changes local position and orientation if necessary.

Connections 11

5 Keyframing

The keyframing mechanism is used to implement object properties that change overtime. For instance, keyframing the position of an object can be used to move theobject over time. Keyframing works by defining a sequence of keys, whereat eachkey specifies the value of the keyframed property at a certain point in time. Thesequence of keys defines a function that maps from time to values of the property.

5.1 Keyframe editor

Figure 4: Keyframe editor.

The keyframeeditor canbeopenedby selecting anobject and clicking on the Keyframesbutton in the toolbar. The keyframe editor displays all properties of the object thatcan be keyframed in a list. Selecting a property shows all keyframes for this prop-

Keyframing 12

erty and a plot of the corresponding function mapping time to values. The keys arevisualized as small dots on the graph. Time is plotted on the x-axis while functionvalues are plotted on the y-axis. Right above the plotting area, information about thecurrent mouse cursor position is shown. time displays the current time at the mousecursor position, value displays the value at the mouse position and f(time) displaysthe value of the keyframing function at the current time.

A new key can be created by double clicking in the plotting area. Keys can be movedby dragging them using the mouse and removed by pressing the delete key. You canzoom in and out using the mouse wheel and shift the plotting area by pressing themouse wheel and moving the mouse. Pressing Fit to curvewill reset the zoom so thatall keys are visible, while Fit to timeline ensures that the time interval of the plottingarea matches the interval displayed in the timeline.

By default, values between keys are interpolated using linear interpolation, whichresults in straight lines between keys. This can be changed by choosing a differentCurve Type (see the top right of the keyframe editor). The curve type of a key deter-mines how the segment between this key and the next key is interpolated. This way,it is possible to achieve non-linear graphs as in Figure 4.

In the top center of the keyframe editor, you will find tabs named Selected keyframeand New keyframe. If you select the first tab, time and value of a selected key will beshown. These values can be edited and will be directly applied to the selected key.If you select the second tab, you will be able to define time and value for a new key.The key will be added after clicking the Add button.

At the bottom, you will find a check box labeled with Update time on click. By defaultit is unchecked or disabled, meaning that a click on the graph will not update thecurrent time. If enabled, the current time will be updated and everything related tothe new point in time will be loaded, even in the main window.

By using the check box labeled with Snap to frame time, the cursor position is snappedto the nearest frame timeon the time axis. Thus, keyframes that are added via doubleclick are automatically snapped to the nearest frame time position. This applies tomoving an existing keyframe, too. The checkbox is enabled by default.

It is possible to lock a property and, thus, prevent further editing of its keyframes.Whether a property is locked or unlocked is illustrated via an icon left of the prop-erty name. Only keyed properties are lockable. By right-clicking on a property, acontext menu will give you the following options: a) Lock or Unlock, if an unlockedor locked property is selected, respectively b) Lock all keyed properties and c) Unlockall keyed properties. The last two options (lock or unlock all keyed properties) appearregardless of the current selection. For a locked property, its keyframes can still beinspected via selection of their nodes or curve intervals.

5.1.1 Copy and paste keyframes

Pressing the Copy keys button in the top center of the keyframe editor copies thekeyframes of the selected properties to the clipboard. Multiple properties can be

Keyframing 13

selected by pressing and holding the CTRL or SHIFT key and clicking on the respectiveproperty names. The copied keyframes can be pasted to another object by selectingthis object in the scene inspector and then pressing the Paste keys button in the topcenter of the keyframe editor. When pastingmultiple properties, the property nameshave to match exactly for keyframes to be pasted. When pasting the keyframes of asingle property to one selected property, pasting works as long as the data types ofthe two properties are compatible and will print an info message otherwise.

Hint: The copy and paste functionality for keyframes works across scene instances,too.

5.1.2 CSV import / export

Using the buttons in the top left of the keyframe editor, you can import and exportall keyframes using the CSV file format, whereat semicolons are used as separators.For instance, a file with two position keys may look like this:

Time;positionX;positionY;positionZ0;0;0;02.0;1.5;2.0;3.5

The CSV import can be useful to import sequences created in other applications. An-other possible application of the export and import is to transfer the keys from oneobject to another. If you try to generate a CSV file using another application, youneed to know how the properties are identified internally by PreonLab (for instance,position x is positionX internally). The safest way to find it out is to export a CSV filecontaining keys for the given property and inspect it using a text editor. Note that im-ported keyframes cannot bemanipulated by default, since the properties they belongto will be locked after the import process. These locks can be manually overridden,as described above.

5.2 Shortcuts

The keyframe editor is not the only way to create keyframes. Pressing CTRL + k willcreate or overwrite a position, orientation and scale key (referred to as transforma-tion key) for the selected object at the current time and object transformation. Press-ing CTRL + l does the same thing, but sets the curve type of the new key to Sinusoidal.

It is also possible to create a new key using the property editor. Right click on a prop-erty that can be keyframed and click on Set key to create or overwrite a key for thisproperty at the current time. You can also click on Show curve to open the propertyeditor and view all keyframes for the property.

Keyframing 14

5.3 Best practices

Setting up a hierarchy of objects using the Transform connection can often simplifykeyframing greatly. Consider a car that consists of many objects like wheels, engineand so on. The basic movement of the car could be keyframed using a single trans-form group that is connected to all parts of the car. Note that the objects could stillbe keyframed individually, for example to achieve spinning wheels.

5.3.1 Make the camera follow an object

The simplest way to keyframe a camera so that it follows a moving object is to usederived transformations. Just position the camera so that it looks on the object andconnect the Transform slot of the object to the Transform slot of the camera using theconnection editor. The camera will now move synchronously with the object. It willalso rotate around the object if it rotates. If you need to avoid this, dont keyframe theposition of the object directly. Instead, keyframe the position of a Transform groupand connect it to the camera and to the object.

Another possibility to control the rotation of the camera is the Lookat connection slot.You can connect the Transform slot of any object into the Lookat slot of the cameraand the camera will always look towards this object.

Keyframing 15

6 Scene and basic objects

6.1 User Preferences

The User Preferences can be found under the menu Settings in the task bar (see Fig-ure 2). They allow you to specify several preferences that are used when creating anew scene, as well as amaximum number of threads used by PreonLab. These prefer-ences are saved to your disk and restored when starting PreonLab. While the defaultvalues specified here are assigned to newly created scenes, they still can bemodifiedper scene later.

Preference What it does

default scene directory The directory where new scenes are created.

default video export di-rectory

For new scenes, videos will be exported to this directory by de-fault.

maximum number ofthreads

The number of CPU threads used by PreonLab will never ex-ceed this maximum number. This correlates with individual#threads and #threads for this scene in the scene properties, i.e.,a lower number of threads may be specified per scene.

default up axis The up axis (either z-axis or y-axis) used for new scenes.

show grid by default Defines whether the orientation grid should be drawn by de-fault in newly created scenes.

default backgroundcolor

New scenes will be created with this background color.

OSD background color The background color of the OSD overlay.

control key The key that needs to be pressed and held to access additionalactions, e.g. camera control (see Table 1). The default is SHIFT.

Table 3: The user preferences to define.

6.2 Scene

With the User Preferences, you can define a set of default values, so you do not haveto redefine your desired preferences every time you create a new scene. However,the scene properties initialized with the User Preferences can still be modified later.

Scene and basic objects 16

Scene properties are always saved and restored per scene.

Property What it does

cache directory PreonLabwrites its simulation data to this path and reads exist-ing data from it. The data path is relative to the location wherethe scene file is stored. By default, this is set so, that the simula-tion data is read from and written to the same folder as wherethe scene file is located. However, it can be adapted for exam-ple to read and write from a network location.

up axis Defines whether the z-axis or the y-axis is used as up axis. Perdefault the z-axis is up. Note that if you prefer to have the y-axis as up axis you probably want to adjust the gravity vector topoint in negative y-direction. Other changes are not required.

simulation frame rate The simulation frame rate decides how often the simulationdata is saved to disk. It also governs the maximal time step touse. The time step can never be larger than the frame rate. It ispossible to keyframe the simulation frame rate in order to re-solve several parts of the simulation with different frame rates.Thereby, only the step interpolation function is available.

view frame rate The view frame rate specifies the frame rate for post-processing operations like sensor measuring or rendering. Bydefault, the view frame rate and simulation frame rate are setto the same value. However, there are also many applicationsfor separate simulation and view frame rates. For instance, itallows you to process a 50 fps simulation at 25 fps, discardingevery second frame and thereby saving performance. Like thesimulation frame rate, the view frame rate can be keyframed.

individual #threads If enabled, this allows you to specify an individual number ofthreads to be used for the related scene in #threads for thisscene.

#threads for this scene The number of CPU threads used by PreonLab if individual#threads is enabled. Note that any number greater than themaximum number of threads specified in User Preferences willnot affect the actual number of threads used by PreonLab.

Table 4: Properties for scene object.

6.3 Scene UI Settings


save frames For recording animations you can save the content of thegraphics window (including all overlay text). The frames arerecorded to the subfolder Visualization/OpenGL/[CameraName]of your scene data.

color Changes the background color of the graphics window.

show axes Draws the orientation axes as an overlay in the graphics win-dow.


show grid Renders a grid at the origin of the scene. Each square has aside length of 1m.

show osd If switched on, statistics and timings are printed as overlay textin the graphics window. For Recording you might want to turnthis off.

Table 5: Properties to set for Scene UI Settings.

6.4 Transform groups

A transform group is an invisible object with a position and an orientation. Other ob-jects can be connected to a transform group via the Transform slot using the connec-tion editor, whereat the connection arc must start from the transform group. Con-nected child objects will inherit the position and orientation of the transform group.The individual position and orientation of a child is interpreted as a local transforma-tion relative to the parent transform group. Note that this feature is not limited totransform groups (any object can act as a transform parent for other objects).

6.5 Point

A point is like a transform group without a rotation. Points are mainly used to specifyseed points for the volume source (see 9.4). Also, a point can be useful together withthe placement tool and a distance sensor to measure distances in the scene (see14.2).


7 Common properties

In this chapter, some common properties are explained that are shared by manyobject types.

7.1 General


behavior Controls the behavior of the object during simulation and play-back. activemeans that the object is part of the simulation andwill save simulation data to disk when simulating. inactive isthe opposite, the object will be completely ignored during sim-ulation and playback. cache means that the behavior of theobject is determined by data read from disk. Cached objectswill therefore never be influenced by other objects, but theycan influence other simulated (active) objects.

Table 6: Properties in group General.

7.2 Appearance

The following properties are shared by many objects that are visualized, includingrigids and fluids.


render mode Changes the way the object is displayed. smoothShaded is thedefault setting and will enable smooth per-pixel lighting. wire-frame is only available for meshes and displays the wireframerendering of the mesh triangles. invisible will hide the objectcompletely.

color The color of the object. Note that depending on the object andits properties, this color may be overridden by another visual-ization, for example when visualizing the fluid velocity using acolor gradient.

opacity Value between 0 and 1 determining the opacity of the object.Note that if you want to hide the object completely, it is recom-mend to set render mode accordingly for better performance.

Common properties 19

Table 7: Common properties in group Appearance.

7.3 Transformation


position control mode Determines how the position for the object is specified. Thedefault is position, which lets you specify the position directly.It is also possible to control the position using its derivatives bychoosing velocity or acceleration.

position The local position of the object in x, y and z coordinates. Onlyavailable if position control mode is set to position. Localmeans that the position is always relative to the transform par-ent. If there is no transform parent, it is equal to the globalposition (see below)

global position The global position of the object in x, y and z coordinates. Thisis a read-only property and it is mainly used to make the globalposition of objects available to the python system for scriptingpurposes.

velocity The local velocity of the object. Only available if position con-trol mode is set to velocity.

start position The local position of the object at time 0. Only available if posi-tion control mode is set to velocity or acceleration.

acceleration The local acceleration of the object. Only available if positioncontrol mode is set to acceleration.

start velocity The local velocity of the object at time 0. Only available if posi-tion control mode is set to acceleration.

orientation controlmode

Determines how the orientation for the object is specified. Youcan either enter the rotation as euler angles (choose eulerAn-gles) or as a rotation around an axis (choose revolution). Youcan also specify rotations per second around an axis by choos-ing revolutions_PerSecond.

revolution axis The local axis around which the object should rotate. Onlyavailable if orientation control mode is set to revolution orrevolutions_PerSecond.

revolution Sets the rotation around the chosen axis. Zero means no ro-tation, one means one full revolution (360 degree), 0.5 meansrotation of 180 degrees and so on. Only available if orientationcontrol mode is set to revolution.

revolutions per second Sets the revolutions per second around the chosen axis.Only available if orientation control mode is set to revolu-tions_PerSecond.

revolution start Sets the state of the revolution around the chosen axis at time0. Only available if orientation control mode is set to revolu-tions_PerSecond.


euler angles The local orientation of the object expressed in rotation aroundthe x-axis (phi), rotation around the y-axis (theta) and rotationaround the z-axis (psi). All rotations are in degrees. Only avail-able if orientation control mode is set to eulerAngles.

scale The scale of the object as a three-dimensional vector.

inheritance mode Specifies whether the object inherits position, orientation orboth (all) from its parent. This setting is only relevant if the ob-ject has a transform parent.

Table 8: Properties in group Transformation.

7.4 Statistics

Objects in PreonLab can gather various statistics during simulation or post-processing. Plots for these statistics can be viewed using the Plot dialog. Addtion-ally, objects may display statistics for the current time in the on-screen-display (osd).The following properties control whether and how statistics are gathered, stored anddisplayed.


track statistics Enables or disables gathering of statistics during simulationand playback. You should only turn this off if you are sure thatyou dont need statistics for this object and you experience per-formance problems caused by statistics gathering.

osd position Specifies where the statistics for this objects are displayed inthe osd.

show sim statistics Specifies whether statistics (except for performance timings)are displayed in the osd.

show timings Specifies whether performance timings are displayed in theosd.

show osd in video Specifieswhether the statistics for this objects are also includedin OpenGL frames written to disk.

record statistics Specifies whether statistics are written to disk whenever a newframe is reached during simulation or playback.

live csv export Specifieswhether statistics arewritten to disk in the CSV formatwhenever a new frame is reached during simulation or play-back.

csv file (read-only) The location of the csv file in which statistics are stored if livecsv export is enabled.

Table 9: Common properties in group Statistics.


8 Fluids

8.1 Preon solver

The Preon solver is an implicit, point-based solver of the compressible Navier-Stokesequation. This formulation adds an extra term to the incompressible formulationwhich takes the current compression into account. The current compression in thefluid might stem from the initial setup or numerical errors from the previous simu-lation step. This compressible formulation enhances volume preservation even fornumerically challenging simulations.

The solver update can be coarsely grouped into three steps: (i) velocity prediction,(ii) pressure projection and (iii) advection. For the prediction of the velocity field, allforces except the pressure force are computed, explicitly. These forces comprise vis-cosity, cohesion, and body forces. For simulating drag effects, e.g., from air to Preonsolver, a drag force has to be addedmanually. Based on these forces, the velocity anddensity field for the next time step are predicted. In the second step, the pressuresolver computes pressure forces which result in a quasi incompressible state. Thetolerated compression can be specified by the user. Finally, the advection step up-dates the positions of the sample points (particles). The neighborhood information(sample point connectivity) is updated by the so called Collider. This is automaticallyperformed in an efficient way by PreonLab.

8.1.1 General settings

Property Unit/Type What it does

spacing m The spacing controls the resolution of the fluid.The volume of a fluid particle is spacing3.

dimension - The default is ThreeDimensional which meansthat PreonLab simulates in 3D. If this propertyis set to TwoDimensional or OneDimensional,particle movements are restricted to two di-mensions or one dimension.

rest density kg/m3 The density of the fluid.

viscosity model - Two different viscosity models are imple-mented. The Laminar_Morris and PreonVis-cosity models. The models are explained inmore detail in Section 8.1.3.

Fluids 22

viscosity kg/(sm) The dynamic viscosity of the fluid.

cohesion model - There are two models implemented to com-pute cohesive forces: (i) PairwiseForce and (ii)the legacy PreonCohesion. The models are ex-plained in more detail in Section 8.1.4.

Table 10: Solver properties.

8.1.2 Pressure-solver settings

The pressure solver enforces a compression below the user-defined density errorvalue. The solver automatically stops eitherwhen the compression is below this valueor after a user-defined maximum number of iterations.


min. iterations - The solver always does at least this number ofiterations in each simulation step. The densityerror gets smaller with more iterations.

max. iterations - The maximum number of iterations the solverdoes in each simulation step.

DI stopping criterion - The stopping criterion for solving the linear sys-temof equations by the pressure solver. If set toDensityErrorAvg, the pressure solver does iter-atively solve for the pressure field until the aver-age density error is below the user defined value(see density error). If set to DensityErrorCom-bined, themaximumdensity error of single par-ticles is also taken into account with respect tothe properties high density threshold andmaxhigh density particles.

density error % The tolerated volume compression given in per-centage.

high density threshold % Particles with a higher density deviation thanthe given threshold are classified as high den-sity particles.

max high density parti-cles

% If the stopping criterion is set to DensityError-Combined the pressure solver will iterate untilthe percentage of high density particles is belowthis value and the tolerated volume compres-sion is below the specified density error.

Table 11: Solver properties in group Physics Pressure Solver.

Fluids 23

8.1.3 Viscosity

Laminar_Morris: This experimental model was introduced in PreonLab 2.1 and is in-tended for small-scale resolutions below 1mm. It implements the discretization ofthe viscous term with SPH similar to Morris et al.1 using a Taylor series approxima-tion. As discussed byMonaghan2, additional stabilization is required tomodel higherReynolds numbers which is currently added if the property artificial viscosity is set.

PreonViscosity: The PreonViscosity is the default viscosity model. It discretizes theviscous term in the same way as Laminar_Morris, but uses a more conservative sta-bilization technique for particle spacings of 5mm higher. Please note that for thismodel the stabilization can not be switched off.

8.1.4 Surface tension

PairwiseForce: The PairwiseForce models cohesive forces as an inter-particle forcecomputed between a particle and its neighboring particles. Thismodel also known aspairwise force model (PF) has been originally proposed by Tartakovsky and Meakin3.The model computes the phenomenon of surface tension by computing pairwise at-traction forces between particles based on their distance. Thereby, the force acts inthe direction of the density gradient which creates surface tension. For a given fluid,themagnitude of this force depends on the distance between particles and the cohe-sion parameter. The total particle-particle interaction force acting on the fluid parti-cles is non-zero only near fluid surfaces. The advantage of the pairwise force modelover the continuous surface force model is that it perfectly conserves momentum,and that it is insensitive to the quality of the computed surface normals. Further-more, the parameter does not change with the dynamics of the fluid (opposed to thecontact angle). However, the analytical relationship between the pairwise forces andthe continuum hydrodynamic parameters has not been established, yet. A recentwork in this direction is presented by Tartakovsky et al.4.

The pairwise force model implemented in PreonLab has been calibrated and vali-dated for water by the TU Dresden5. The default parameter of 1matches water. Theforce is designed to be invariant with respect to the resolution.


cohesion - Controls the cohesion (surface tension) of thefluid. Higher values result in larger forces. Zeromeans no cohesion.

1J. Morris, P. Fox, Y. Zhu: Modeling low reynolds number incompressible flows. Journal of Computa-tional Physics, 136(1):214-226, 1997

2J. Monaghan: Smoothed particle hydrodynamics. Institute of Physics Publishing, School of MathematicalSciences, Monash University, Australia

3A. Tartakovsky, P. Meakin: Modeling of surface tension and contact angles with smoothed particlehydrodynamics. Physical Review E72, 2(26301), 2005

4A. Tartakovsky, A. Panchenko: Pairwise force smoothed particle hydrodynamicsmodel formultiphaseflow: Surface tension and contact lines, Journal of Computational Physics, Volume 305, pp. 1119-1146, 2016.

5Sprinkling simulation with PreonLab by TU Dresden.

Fluids 24

https://www.fifty2.eu/wp-content/uploads/2017/02/TUDresden-WhitePaper.pdf

Table 12: Property for PairwiseForce cohesion.

PREON cohesion: The PREON cohesion is a legacy version of the PairwiseForcemodel which is sensitive to changes in the resolution. For new scenes, please use thePairwiseForcemodel.

8.1.5 Solid-fluid interaction

The interaction of fluid with solid objects is handled in a unified particle-based man-ner. Therefore, solid objects are automatically sampledwith particleswhich are trans-formed with the object by PreonLab. Boundary particles take part in the pressurecomputation, realizing a no-slip boundary condition. Explicit forces, like adhesionand viscosity are computed similar to fluid-fluid particle interaction using the respec-tive model set for the fluid solver.


mirror pressure on/off If switched on, the pressure value of a fluidparticle is mirrored onto boundary particles inclose proximity while the velocity is set to thecorresponding solid velocity at that position.Thereby, realizing a no-slip boundary condi-tion as, e.g., proposed by Hu and Adams6. Ifswitched off, the pressure of the boundary par-ticles is explicitly computed, leading to a moreprecise computation of the pressure gradientat the boundary. Note that this method addsa computational overhead. The benefit of ex-plicitly computing boundary pressures is moresignificant in closed-domain problems. For free-surface problems like a wading simulation thedifference of the simulation resultsmight not bethat significant.

no gap on/off If switched off, fluid particles are kept in a dis-tance to solid walls (geometries) of the length ofparticle spacing. This results in a visible gap inthe size of half the particle spacing and a thick-ening of geometries reducing the inner void vol-ume. By switching, the no gap property to on,the gap is eliminated. As the fluid particles dis-tance to the geometry is reduced, the CFL timestep is also smaller. Furthermore, more bound-ary samples are generated when the no gap op-tion is onwhichmight increase the computationtime and memory consumption.

6X.Y. Hu, N.A. Adams: A multi-phase SPH method for macroscopic and mesoscopic flows. Journal ofComputational Physics, 213(2):844-861, 2006

Fluids 25

Table 13: Solver properties in group Physics Boundary handling.

Figure 5: Solid-fluid interaction. Left: A tomato is washed under a water faucet. In the begin-ning the outflow is low. Cohesion effects are clearly visible at the concave water jet and thedroplets beneath the tomato. Due to the established adhesion model (see Section 8.1.4 andChapter 12), the water flows around the tomato before dropping off. Right: With increasingflow rate, this effect is replaced by the water splashing off of the tomato on contact.

8.1.6 Deletion criteria

In very rare instances, the solver may choose to delete individual particles in orderto keep the overall simulation stable. The settings in the property group Deletioncriteria specify the thresholds above which particles may be deleted. We highly rec-ommend to not change these settings. If you experience a significant loss of volume,it is usually a better way to decrease the time step and check the overall simulationsetup.


on CFL violation This property specifies what happens with particles that violatethe CFL condition due to numerically challenging settings. Ig-nore does not adjust the particles. DeleteParticles deletes allparticles violating the CFL condition and AdaptTimestep indi-vidually adapts the time step for each particle so they meet theCFL condition.

stuck prevention Enables or disables the stuck prevention whichmay delete par-ticles based on their density.

predefined stuck values Enables or disables user-specified stuck thresholds.

density threshold Specifies a density threshold abovewhich particles are deleted.The density is given as a normalized value (1 refers to the restdensity).

stuck threshold Specifies a density threshold above which particles stuck be-tween solid objects are deleted. For this density, only solidobjects are considered, while other fluid particles are ignored.The density is given as a normalized value (1 refers to the restdensity).

Table 14: Properties in group Deletion criteria.

Fluids 26

8.1.7 Rendering of particles

The particles represent partial volumes of the fluid which are rendered as volumetricspheres. Most field values carried by the particles, e.g., velocity (default) or pres-sure, can be mapped as a color onto the particle. Rendering-related properties ofthe solver are listed in group Appearance.


render mode Particle rendering can be set to smoothShaded or invisible.

color The base color of particles if the coloring is not set to any fieldvariable None.

opacity Controls the opacity of the particles. If 1, the particles are com-pletely opaque. If 0, they are completely transparent.

render scripted parti-cles

Enables or disables the visualization of scripted particles. Thisis only relevant in combination with simulation boundary do-mains that script particles.

Coloring Lists a variety of propertieswhich control the field variable usedfor coloring the particles, the value range, and the respectivecolors for minimum, medium, and maximum value.

Table 15: Properties in group Appearance.

8.1.8 Serialization

The properties in the group Serialization control how fluid data is written to disk ineach frame. You can save disk space by enabling compression. You can also savedisk space by disabling the storage of certain fluid attributes if you dont need themfor your intended post-processing.


use compression Enables or disables particle compression. Compression savesdisk space, but can be computationally demanding.

max compression error The maximum allowed compression error as a factor of thespacing. Higher compression errors allow more efficient com-pression. This is only relevant when compression is enabled.

serialize ID Enables or disables the serialization of particle identifiers. Par-ticle identifiers are required for all applications that require thetracking of particles over time such as pathlines.

serialize Velocity Enables or disables the serialization of particle velocities. Parti-cle velocities are required in post-processing for most sensors.

serialize Density Enables or disables the serialization of particle densities. Parti-cle densities are required in post-processing for sensor planes.

serialize Pressure Enables or disables the serialization of particle pressures. Par-ticle pressures are required in post-processing if you want toplot pressure on a sensor plane or on meshes using the forcesensor.

Fluids 27

Table 16: Properties in group Serialization.

8.2 Preon mesher

Figure 6: Generating a surface mesh from particles.

The Preon mesher creates a triangle mesh that represents the surface of the fluid.

8.2.1 First steps

Insert a Preon mesher. If there are multiple fluids in the scene, you need to connectthe Particles slot of the fluid to be meshed to the Particles slot of the mesher usingthe connection editor. If there is only a single fluid, the mesher is already connectedto the fluid by default.

Right click on the mesher in the scene inspector and clickMesh frame to generate themesh for the current frame. To save the mesh to disk, right click and choose Savemesh. To mesh a sequence of frames, right click and chooseMesh sequence. A dialogwill pop up, asking you for the start and end frame of the sequence. Clicking Ok willstart the meshing process.

By default, the mesher will also generate and save meshes when simulating. If themesher should be used as a post-process, it is recommended to set the behaviorproperty of the mesher to cache. This will disable meshing during the simulation.

8.2.2 Parameters explained

The properties of the Preon mesher are explained per group in the following tables.Note that it is usually not required to change any parameters.

Fluids 28


LOD max error multi-plier

Sets the maximal allowed error during mesh simplification asa multiplier of the particle radius. Higher errors will result inmore adaptive, but possibly also less detailedmeshes. The rec-ommended range for this parameter is between 0.1 (high visualquality) and 0.5 (smaller meshes). Note that increasing this pa-rameter has no effect when simplifications are prevented byLOD max normal deviation.

LOD max normal devia-tion

Sets the maximal allowed deviation between surface normalsduring mesh simplification. Higher values will result in moreadaptive, but possibly also less detailed meshes. The recom-mended range for this parameter is between 0.001 (high visualquality) and 0.01 (smaller meshes). Note that increasing thisparameter has no effect when simplifications are prevented byLOD max error multiplier.

Mesh export format Set the mesh export format. Note that choosing a text-basedformat like .obj will result in much bigger file sizes.

Live Preview Enables or disables live previewafter changing parameters. Forperformance reasons, this is only recommended for small ormedium-sized fluids.

Table 17: Properties in groupMeshing.


Isosurface thresholdmultiplier

Higher multipliers will result in thicker fluid meshes. A valuebetween 1 and 1.5 is recommended.

Minimal cell size multi-plier

Influences the level of detail of the mesh. Lesser multiplierswill lead to more detailed meshes, but will also require morememory and computational power. A value between 0.5 and 2is recommended (1 being the default).

Smoothing radius mul-tiplier

Controls the smoothness of the generated mesh. A value be-tween 4 and 6 is recommended. Higher multipliers will resultin smoother meshes, but will also require more computationalpower.

Table 18: Properties in group Distance field.

8.2.3 Common issues

Resulting meshes have too many triangles

Multiple parameters influence the triangle count of the final mesh. Increasing Min-imal cell size multiplier will reduce the mesh size, however it will also decrease thevisual quality. Increasing LODmax error multiplier and LODmax normal deviation

Fluids 29

are another way to tune the tradeoff between mesh size and quality (see the tableabove).

A great way to reduce the mesh size without decreasing visual quality is to increasethe Smoothing radius multiplier. This will lead to smoother meshes that can usuallybe represented with less triangles. However, it will also increase meshing time andtends to shrink meshes a bit. The shrinking can be countered by increasing Isosur-face threshold multiplier carefully. It is recommended to tune meshing parametersfor a single mesh before meshing an entire sequence. Also note that the defaultparameters are not a bad choice for most cases and should only be changed if nec-essary.

Fluids 30

9 Sources

There are two types of sources, continuous and one-time. Continuous sources emitfluid over time, whereas one-time sources emit fluid at one specified point in time.

9.1 Square source and circle source

The square source and the circle source emit fluid continuously over time. The squaresource emits a rectangular stream of fluid, while the circle source emits a circularstream. Rotate the source to specify the direction of the generated fluid stream.


finite volume Enables / disables the generation of a finite amount of fluid vol-ume controlled by the volume property.

volume Sets the total volume that is emitted by the source (m3). Thisonly has an effect if finite volume is enabled.

inflow unit Sets the unit to be used for the inflow. By default, this is set tovelocity and can be changed to volume flow rate. The magni-tude of the selected unit will not be updated if you change thescale of the source.

velocity The initial velocity of generated particles (ms1). Only relevantif set as inflow unit.

volume flow rate The input fluid volume generated by the source per second(m3 s1). Only relevant if set as inflow unit.

Table 19: Properties of square / circle source in group Settings.

9.2 Area source

Like the square and the circle source, an area source emits fluid continuously overtime either given an outflow velocity or given a volume flow rate. However, an areasource emits fluid from an area enclosed by solids in the scene. Without solids inter-secting the source, the behavior is identical to the square source. Otherwise, fluid isonly emitted from the area that can be reached from the center of the source with-out going through solid boundary. Thereby, only solids connected to the area source

Sources 31

Figure 7: In this example, the emit area is bounded by a cylinder and a plane.

via the TriangleMesh connection are considered. By default, all solids are connected.Figure 7 shows an example in which the area is limited by a cylinder and a plane.

9.3 Flat jet source

A flat jet source emits fluid in a defined angle. It has the same basic properties asa square or circle source (see Table 19) and additionally the properties described inTable 20. The y- and z-scale of the flat jet source can be manipulated via the scaledragger. While the y-scale defines the emission radius, the z-scale defines the thick-ness of the flat jet.

Figure 8: A flat jet source emitting fluid in an angle of 70 degree.


fan angle The spray angle of the source in degree. Has to be a value be-tween 0 and 180 degree.

emission radius The fluid is emitted at this radius from the center of the source.The larger the radius, the more particles are generated for thegiven fan angle.

Table 20: Additional properties of flat jet source in group Settings.

Sources 32

9.4 Volume source

The volume source is used to fill a user-specified volume with particles.


source spacing Distance between generated particles. This has no influenceon the solver spacing.

fill type Defines the volume in which particles are generated. In anycase, particles are never generated outside the source box. Filltype all will fill the source box completely with particles. Filltype inside will generate particles only inside of objects. Thisonly works properly with volumetric and closed meshes. Formeshes that contain holes or self-intersections, it may give un-expected results. The same applies to fill type outside, whichgenerates particles outside of objects. Finally, fill type seed-point can be used to fill all regions that can be reached fromone or multiple user-specified seedpoints. Read more aboutseedpoints in Section 9.4.2.

fill method Specifies how the volume is sampled with particles. Fill methoduniform will generate particles aligned in a uniform grid. Fillmethod hexagonal will align the particles in a hexagonal grid.This method is optimized for filling a box and generates onelayer of particles at the top that is not strictly located withinthe volume. Fill method poisson_hybrid is only recommendedwhen filling objects using fill type inside or seedpoint and aimsto capture the surface of filled objects as accurately as possi-ble. It first samples the surface using maximal poisson disk setsampling and then fills the rest of the volume using uniformsampling. poisson_full uses poisson disk set sampling not onlyfor the surface, but for the whole volume. This is usually notrecommended, because it requires a lot of time to computeand results in a low density compared to other fill methods. Fi-nally, poisson_surface only samples the surface and generatesno other particles.

manual border size Enables or disables manual specification of the border size. Bydefault, this is disabled and the border size will be set auto-matically to ensure that generated fluid does not overlap withgeometries.

border size Specifies a border between the surface of objects and parti-cles generated by the source. This has no effect if fill type allis used. The border size is typically used to avoid collisions be-tween fluid and boundary particles when starting the simula-tion. In this case, it should be set to the spacing of the fluid.When using the no-gap option in the fluid solver, it should beset to half the spacing of the fluid.

Table 21: Properties of volume source.

Sources 33

9.4.1 Alignment

The volume source is internally rasterized using a grid. By default, the position ofthe volume source defines the alignment of particles, i.e., determines the particlepositions relative to the volume source. It is also possible to specify an alignmentindependent from the position of the source by connecting an object to the Volumesource via the Align slot. For instance, the Box offers an Align output slot that ensuresan optimal alignment of particles inside the box. It is also possible to specify amanualalignment by connecting a Point to the Volume source via the Align slot. The positionof the point will now determine the particle alignment.

Note that alignment has no effect when using poisson particle sampling. When play-ing around with alignment, make sure you have the preview particles property ofthe volume source switched on to get instant feedback.

9.4.2 Filling containers with a volume source

Figure 9: Top: Seedpoint (orange dot) placed in a box with obstacle in the middle. Bottom:Box filled with particles.

Seedpoints are a powerful tool to fill arbitrary containers with fluid. The volumesource will fill all regions that can be reached from the seedpoints without passingthrough an obstacle or the boundaries of the volume source itself. Figure 9 shows abox filled with fluid using seedpoint filling.

To activate filling from seedpoints, set the fill type property to seedpoint. If no cus-tom seedpoint is connected to the volume source, a single implicit seedpoint locatedin the middle of the source is used for filling. To insert a custom seed point, click

Sources 34

Add Transform Point. If there is a single volume source in the scene, insertedseedpoints are connected automatically to it. Otherwise, you need to setup the con-nection manually using the connection editor (slot Seedpoint).

Important: In order to avoid strong collision responses when starting the simulation,it is necessary to leave a small border between generated fluid particles and rigidobjects. This can be achieved using the border size property of the volume source.Setting the border size to the spacing of the fluid ensures that there is no overlapbetween fluid and boundary particles.

Make the volume source ignore geometries: The volume source takes also inactivegeometries (solids) into account. You can make the volume source ignore certain ge-ometries bymanually deleting the connection TriangleMesh from geometry to volumesource which is per default automatically added by PreonLab.

Special notes on box filling: To ensure optimal filling of a Box, make sure to followthese rules:

The size of the box should align with the particle spacing. Right-click on the boxin the scene inspector and choose Adjust scale to spacing in order to round thescale to the next aligned value.

Connect the Align slot of the box to the volume source to ensure optimal particlealignment.

Use hexagonal filling to avoid splashes during the first simulation steps.

9.5 Rain source

The rain source mimics a rain like inflow.


precipitation height You can specify the precipitation height in mm per min whichequals L per m2 per min. This parameter defines the amountof volume generated per square meter. Note that for inflowslike 30mmmin1 or below you have to use a particle spacing of2mmor smaller to get a dense particle distribution. For coarserresolutions, single particles already represent too much vol-ume, thus, only few particles are generated with big gaps inbetween.

velocity You can specify an initial velocity of particles, i.e., particle ve-locity at time of their generation. Note that this value does notchange the volume flow rate. In order to mimic real rain, youshould use the terminal velocity of a rain drop (2mm radius)which is 9ms1.

Table 22: Properties of rain source.

Sources 35

10 Boundary Domains and Conditions

PreonLab offers possibilities to define a boundary domain, i.e., a domain where thebehavior of fluid particles or boundary particles is prescribed by the user.

10.1 Box and cylindrical domain

The Box domain defines a box-shaped boundary domain, while the Cylindrical do-main defines a cylindrical-shaped domain. Except for the shape, both domains be-have identically. There exist two control types: deletion of fluid or rigid particles orscripting the velocity of fluid particles.

The user can define whether this condition holds inside or outside the boundary do-main. The color indicates which region is set for the domain. A green color meansthat the simulation domain is inside the boundary domain, particles outside are han-dled by the boundary domain, while a red color indicates that particles inside thedomain are treated by the boundary domain.

A typical use case for these objects is to define a simulation domain. For example, byusing a Box domain with region set to outside and type set to deleteFluidParticles,the user restricts the simulation domain to the extend of the Box domain.


region Specifies whether particles outside (the default) or inside thebox should be removed.

types Specifies the type of the boundary condition. You can deletefluid and / or rigid particles or define a constant fluid velocity.

Table 23: Properties of the Box domain and Cylindrical domain.


fluid velocity Specifies the velocity of fluid particles controlled by the domain.This velocity is given as global value independent of the rotationor Transform parents of the domain.

Boundary Domains and Conditions 36

Table 24: Properties in the group Velocity Condition. This group is only shown if the controltype is set to scriptFluidVelocity.

10.1.1 Using multiple domains

PreonLab follows the following rules when combining the conditions of multiple do-mains:

A particle is deleted if it is inside a deleting domain with region inside or if itsvelocity is above the threshold of any maximum velocity condition.

A particle is also deleted if it is outside a deleting domain with region outsideand not inside a deleting domain with region outside.

A particle is never scripted if it is deleted.

A particle is scripted if it is inside a scripting domain with region inside. If thisis true for multiple domains with different scripting velocities, the resulting ve-locity is undefined.

A particle is also scripted if it is outside a scripting domain with region outsideand not inside a scripting domain with region outside. If this is true for multipledomains with different scripting velocities, the resulting velocity is undefined.

10.1.2 Using boundary domains to improve performance

A box domain scripting the velocity of fluid particles can not only be used to achieve aspecific fluid behavior, it can also be used to improve performance in certain scenes.This is possible because scripted particles require almost no simulation effort by thesolver and are therefore processed very efficiently. Whenever there are parts of yoursimulation where fluid particles move with a constant velocity or do not move at all,there may be an opportunity to speed up the simulation using a boundary domain.To make optimal use of the domain, it may be necessary to keyframe its scale and /or position.

Example

Consider a simulation in which a car drives through water on a street. If you areonly interested in the water interacting with the car, you can restrict the simulationto a box around the car. To achieve this, insert a box domain and set its type toscriptFluidVelocity and its region to Outside. Then connect the IOTransform slot of thecar to the corresponding slot of box domain and position and scale the box domainso that it contains the car. Now, only fluid in the box surrounding the car will besimulated by the solver. Note that particles leaving the box will be frozen, which


leads to unrealistic results for water behind the car. You can disable the visualizationof these particles by turning the solver property render scripted particles (locatedin the Appearance group) off. If you need a full drive-through simulation includingwater behind the car, you can still get a speedup using boundary domains by scriptingfluid in front of the car.

Figure 10: Use-case for simulating a restricted domain around a car to save memory and in-crease performance. Comparison of unrestricted (left) to restricted simulation domain (right).

10.2 Maximum velocity condition

The maximum velocity condition deletes fluid particles based on their velocity andnot based on their position. This can be used to remove very fast particles from thesimulation in order to improve performance and stability.


velocity magnitude Specifies the maximum velocity magnitude, fluid particlesabove that will be deleted.

Table 25:Maximum velocity condition.


11 Force Fields

11.1 Gravity

The gravity object applies a force to all objects it is connected to based on a con-stant and global acceleration defined by the property gravity. By default, each scenecontains a gravity object that is automatically connected to all physical objects includ-ing fluids and rigids. Its gravity property is always in the global reference frame. Bydefault, it is set to 9.81ms2 directed into the negative z-direction to approximateearths gravity. You need to change this direction if the z axis is not your up-axis orobjects will fall to the side and not down.

11.2 Drag Force

The interaction between a fluid and the surrounding air phase is in reality normallynot visible but can influence the overall flow of the fluid significantly. Especially thepath and terminal velocity of single fluid droplets is dependent on the surroundingair velocity. By default, the air phase is not simulated in PreonLab. In order to approx-imate the effects of the air onto the fluid, a drag force can be used. The drag forceobject is used to simulate air resistance acting on fluids. It has no effect on rigid ob-jects. The drag force allows to specify a single global air flow velocity. If you want tospecify an air flow field where the air velocities differ in space, see Section 11.3.

Be aware that if you insert a drag force aswell as an air flow force fieldwithout restrict-ing their area of effect, both force fields will act on the fluid, resulting in a doublingof the force. This is probably incorrect for your scene. See Section 11.3.5 for moreinformation.

The force applied to a fluid particle depends on the relative velocity difference be-tween the air and the particle at this position. Furthermore, for each fluid particle, itsarea exposed to the air is computed. This means that the drag force does not affectparticles that are located inside a fluid volume but only these on the surface. A typicaleffect of the drag force on fluid simulations is a reduction of splashes.

Force Fields 39


velocity The velocity of the air in the local coordinate system. Note thatthe zero vector is a perfectly valid choice, because the appliedforce depends on the velocity difference between fluid and airand not only on the air velocity.

apply force everywhere Defines if the force should be applied everywhere or just in thedefined box region.

drag model Specifies how the drag coefficient and the (unobstructed) par-ticle area is calculated. The different options are discussed inmore detail in the subsections below.

Cd The constant drag force coefficient. Only relevant if dragmodel is set to Constant.

terminal velocity Specifies the terminal velocity a single fluid particle shouldachieve. Only relevant if dragmodel is set to TerminalVelocity.

force factor Factor multiplied to the resulting drag force. This is only shownand applied when as drag model either Constant, TerminalVe-locity or AutomaticViaTerminalVelocity is selected.

density Density of the air modeled by the drag force. This is only rel-evant and shown in the Liu Model Settings group when dragmodel is set to LiuModel.

Table 26: Properties for the Drag force.

In the following subsections, the different drag models are discussed in more detail.

11.2.1 Constant

If this drag model is selected, the used drag coefficient is given by the user. The basearea of the fluid particle is assumed to be the squared spacing.

11.2.2 Terminal Velocity

The user can specify a terminal velocity a single fluid particle should reach in free fall.Depending on this, a constant (independent of the relative velocity or other factors)drag coefficient is computed. The base area of the fluid particle is assumed to be thesquared spacing.

11.2.3 Automatic Terminal Velocity

A formula is used to compute the terminal velocity based on the particle spacing. Thisterminal velocity is then used as described in the TerminalVelocitymodel to computea constant drag coefficient. The base area of the fluid particle is assumed to be thesquared spacing.

Force Fields 40

Figure 11: Fluid spray for a wheel rotating with a speed corresponding to 20 kmh1 displayedusing path lines. In the left image no drag force is enabled while in the right image the LiuModel is used. The result from the right image matches experiments.

11.2.4 Liu Model

This drag model is based on a paper by Liu et al.1 In this model, the deformationof a single fluid particle is taken into account. Depending on the relative velocitybetween air and fluid, the fluid particle is modeled to deform. This influences thedrag coefficient as well as the cross-sectional area of a particle.

11.3 Air Flow

The Air Flow field is an extension of the drag force and inherits most of its proper-ties. However, instead of specifying a single global velocity, velocities are stored in a3D grid and are interpolated during the simulation. The purpose of this object is tocouple PreonLab fluid simulations with air flow fields simulated in another software.

11.3.1 Import

PreonLab can import an air flow field represented by csv data. Each line in the csvfile should contain position and velocities for one sample point. The first line shouldcontain a text per column which describes the corresponding value. The order ofposition and velocity values is not important and can be adjusted when importing thedata. Any additional data will be ignored. To import your csv data, click File ImportImport Airflow. You can select your csv file by setting the path. PreonLabwill then tryto automatically detect the correct separator and fill the drop down lists for positionand velocity components. If the order is not correct, you can reassign it, such thatthe order matches your csv data. PreonLab will convert the csv file into a binary filewith the file-ending .prairflow. You have to specify the path to the location where youwant to store the converted file.

When you click the import button, PreonLab will parse the csv file, then convert thefile to the binary .prairflow format and finally create an air flow force field.

1Modeling the Effects of Drop Drag and Breakup on Fuel Sprays, Liu A., Mather D., Reitz R., 1993

Force Fields 41

11.3.2 Viewing the air flow field

You can view the imported sample vectors by enabling the show sample points prop-erty. It will simply display the imported samples as colored arrows. Be careful though,because for very large data sets this visualizationmay require toomuchGPUmemoryfor your system. Another way to visualize the air flow field is the Air flow visualizerobject which displays air flow velocities projected on a plane. This visualization doesnot show you the raw samples, but the interpolated data that is used by PreonLabduring simulations. Only this visualization allows you to tune properties like cell size.For further information, see Section 14.9.

11.3.3 Air flow parameters


air flow path Sets the path to the .prairflow file created by PreonLab thatstores the sample points in binary form.

velocity offset This allows to add an offset to all imported velocity samples.This is for example helpful if the air flow was computed in amoving reference frame (moving objects are kept at the sameposition) and in PreonLab the reference frame is fixed (objectsmove).

num lod levels Imported air flow fields may be sampled adaptively. To in-terpret the imported adaptive point cloud correctly, PreonLabneeds to know the number of detail levels. Note: A high num-ber of levels will result in slower grid construction time.

discard samples Sets whether samples should be rejected if they are classifiedas outliers.

maximal deviation This parameter is only visible if standard deviation is selectedfor discarding samples. It sets the maximal allowed deviationof a sample from the mean.

max. vel. length This parameter is only visible if fixed value is selected for dis-carding samples. It sets the threshold abovewhich sampleswillbe discarded.

Table 27: Properties in group Point cloud import.


cell size Sets the minimal cell size in the airflow grid.

Table 28: Properties in group Air Flow Grid Settings.

Force Fields 42


air velocity Sets the velocity that is used in areas where the grid stores nodata.

Table 29: Properties in group General.


show sample points When enabled, sample points from the .prairflow file will be vi-sualized.

Table 30: Properties in group Appearance.

11.3.4 Air Flow box

By default, the air flow will determine its size automatically based on the input data.The air flow box lets you specify the box covered by the air flow field manually. Note,that the air flow box is only useful if your input data contains samples you want toignore. Only consider using the air flow box if you cannot correct the original inputdata. To use the air flow box, just insert one and position it as required. Note thatthe air flow object will not update itself automatically. You need to trigger the updatemanually by right clicking on the air flow object in the scene inspector and choosingResample grid.

11.3.5 Best practices

If you insert an air flow force field, you typically do not need an additional drag force.By default the Air Flow applies a drag force based on the imported velocities in theregions where the imported velocities are given and additionally a drag force basedon the user-defined velocity in all other regions. Thismeans that adding an additionalDrag Force is not needed andwould double the applied force. If you dowant to applythe force fromanAir Flow orDrag Force only in a specific region you can either togglethe property apply force everywhere or, for air flows, you can use an Air Flow box(see Section 11.3.4).

Force Fields 43

12 Solid Objects

Solid objects can be addedusing the AddSolid. There are different standard geome-tries implemented, e.g., cuboid, box, sphere. Arbitrary geometries can be importedeither via AddSolidMesh or per drag-and-drop.

PreonLab automatically samples the solids with particles in the resolution of thePreon solver (spacing). The sampled surface of the solid acts as an interface to thefluid, i.e., the sample points define a boundary conditionwhich is included in the pres-sure system. The velocity of the solid particles matches the velocity of the solid at thecorresponding position. The Preon solver computes inter-particle forces (adhesionand friction) between the solid interface and the fluid particles in proximity.


particle limit Sets the maximum number of generated boundary particles toprevent allocation of too much RAM. The maximum is given inmega particles, so that a limit of 1 means 1 million particles.If this limit is exceeded, a warning will be printed to the mes-sage window. In this case, you either need to increase the fluidspacing or increase this limit to ensure a correct simulation.

cull rigid particles Enables / disables the culling of rigid particles based on sim-ulation boundary domains. This saves memory and improvesthe simulation performance. Please note that PreonLab will ig-nore this setting if the rigid moves in relation to the boundaryto avoid costly resampling in each time step.

Table 31: Properties of solid objects in group General.


rigid type Defines whether the solid acts as scripted (animated) object,or as dynamic in which case the physics of the object are com-puted, i.e., gravity acts on the solid, and it collides with othersolid objects. The solid can also be defined as stationary. Inthis case, the solid does not move in world space, but you canpre-scribe a velocity for the object. The object will interact withthe fluid according to this pre-scribed velocity. In this way, mov-ing objects can be simulated without really moving them.

Solid Objects 44

roughness Defines the roughness of the solid surface. If this parameteris 1 (default), the viscosity computed between the virtual fluidfilm and the fluid particles matches the viscosity of fluid-fluidinteraction. By setting the roughness to larger values, surfaceswith larger frictional effects can be modeled, e.g., a felt seal.The inter-particle force used to compute the force is definedby the viscosity model of the fluid solver (see Section 8.1).

adhesion Controls the adhesion effect of the rigid onto the fluid. Theemployed model for computing the force is defined by the co-hesion model of the fluid solver. The default value of 0.65 hasbeen calibrated empirically in various experiments performedby TU Dresden1 were it gave good results for most materi-als using the PairwiseForce model which is explained in Sec-tion 8.1.4. By increasing the adhesion value the hydrophilicityof the geometry is increased.

Table 32: Properties of solid objects in group Physics.

12.1 Rigid body simulation

PreonLab uses the open-source Bullet library for rigid body simulation.2 Tables 33and 34 show the basic properties of rigid objects related to the rigid body simulation.For mesh-based rigid objects, more information can be found in Section 12.4.


linear velocity The linear velocity of the object. For animated objects usingkeyframes, this value is automatically computed. For dynamicobjects, the user-defined linear velocity is the initial linear ve-locity of the object. For stationary objects, the linear velocity istaken as the linear velocity of the solid (boundary).

angular velocity The angular velocity of the object. For animated objects usingkeyframes, this value is automatically computed. For dynamicobjects, the user-defined angular velocity is the initial angularvelocity of the object. For stationary objects, the angular veloc-ity is taken as the angular velocity of the solid (boundary).

rigid friction The friction coefficient of the rigid relevant for interactions withother rigids.

bounciness Physical bounciness of the object. The resulting bounce is de-pendent on the bounciness of both colliding rigids.

Table 33: Properties of solid objects in group Bullet Settings.

1Sprinkling simulation with PreonLab by TU Dresden.2Bullet Physics Library

Solid Objects 45

https://www.fifty2.eu/wp-content/uploads/2017/02/TUDresden-WhitePaper.pdfhttp://www.bulletphysics.org/


two-way coupling Defines whether the object is influenced by fluids.

density The density of the object. Together with the volume, this de-fines the mass.

volume Shows the current volume of the object.

mass Shows the current mass of the object.

Constrain DOF These properties allow you to restrict forces applied to the ob-ject by Bullet. You can freeze movement along the three unitaxis and you can freeze rotation around unit axis. Note thatthis usually results in unphysical behavior.

Table 34: Properties of solid objects in group Dynamic Settings (only relevant for dynamicrigids).

General settings related to the Bullet simulation can be accessed over themenu entrySettingsBullet. The available settings are described in Table 35.


substep size This is the time step size of a single sub step done by the Bul-let solver. The size of this time step should always be chosensmaller than a single simulation time step done by PreonLab.Furthermore, this value times nr sub steps should be largerthan a single simulation time step.

nr sub steps This is the maximum number of sub steps the Bullet solverdoes. This number times the substep size should always belarger than a single simulation time step by PreonLab or other-wise the dynamic rigid simulation will probably be incorrect.

split impulse If on, the Bullet solver solves positional and velocity constrainsseparately. Contact handling is usually more accurate whenenabled.

split impulse threshold Only relevant when split impulse is on. When enabled, the splitimpulse position correction is only used when the penetrationis larger than this value, otherwise the regular velocity/positionconstraint coupling is used.

solver iterations Maximum number of iterations the Bullet constraint solverdoes.

Table 35: Bullet settings.

12.2 Visualization of solid objects

Solid Objects 46


transparent Toggles transparent rendering for the rigid. Note that Preon-Lab currently only supports a basic form of transparency, inwhich transparent objects behind other transparent objectsare not displayed correctly.

show particles Enables / disables visualization of the boundary particles of therigid used by the PREON fluid solver.

two-sided lighting Enables / disables two-sided lighting for the rigid.

Coloring The properties of this property subgroup control the coloringof the rigid boundary particles. They work just like the coloringfor sensors explained in Section 14.1 by specifying three keycolors and values. Note: Use coloring typeWettingFilmBasedto visualize the wetting film of this solid (if you have definedthe respective properties to allow for the evolution of a wettingfilm).

Table 36: Properties of solid objects in group Appearance.

12.3 Primitive shapes

PreonLab includes some common geometric shapes including cuboid, sphere, cap-sule and cylinder. Another simple object provided by PreonLab is the Box which isusually employed to quickly setup a basin for fluid. These objects have few specialparameters - just scale them to get the shape you want.


segments Sets the number of horizontal and vertical segments for thesphere. Higher values will result in a smoother surface. A valuebetween 18 and 50 is recommended.

Table 37: Properties for sphere.


top cap Disabling this property will remove the cap at the top of thecylinder.

bottom cap Disabling this property will remove the cap at the bottom of thecylinder.

Table 38: Properties for cylinder.

Solid Objects 47

12.4 Mesh

Using the mesh object, you can integrate arbitrary geometries into your simulation.You can add meshes either using the Ad

preonlab 2.2.1 user guide - fifty2 technologyfifty2.eu/preonlab/preonlabmanual_v2_2_1.pdf ·...

Documents