Fluidix: User Manual
© 2008 Adam MacDonald, Dr. David Pink, St. Francis Xavier University, OneZero Software
Introduction
Fluidix is a software package for modeling, simulating, and visualizing dynamic physical systems of
liquids and soft-matter objects. The package includes three executable programs:



Designer: graphical user interface for developing systems and visualizing simulation results.
Server: simulation control program which evolves the system through time.
Client: program which connects to the server using TCP/IP and calculates interaction forces
This document is a complete user reference manual of the software interface components and features.
Source code documentation and simulation process algorithms are not included. The main body of the
document is divided into four sections, each of which corresponds to a tab in the designer interface. Each
element of the software is documented in approximately the order which it appears in the interface, which is
also approximately the chronological order by which a user would utilize those elements when developing a
large, complex simulation.
This document is written with the assumption that the reader has a general understanding of dissipative
particle dynamics. For more information, read “Fundamentals of Dissipative Particle Dynamics,” available at
onezero.ca.
The designer software has three windows: the interface control window titled “Fluidix,” the display
window titled “OpenGL Display,” and the console output window titled “dpd.exe.” Any of these three windows
can be used to close the program using the “X” button in the top right corner. Minimizing the OpenGL display
window can have unexpected results, as well as using the Windows “Show Desktop” feature with this software.
The console output window contains debugging information which can be ignored by most users.
Section 1: Particles
Structures
A structure is a collection of particles which represent an object within the system. Initially, there is one
structure: the “World.” This structure refers to the finite boundaries of the system, and contains particles which
are always positioned randomly within the system.
Other structures can be created interactively, and multiple instances of a structure can be placed
independently within the system. During the simulation, particles will not be constrained within the boundaries
of the structures; these structures are used only for the purpose of building the simulation.
List
The list of structures contains all structures currently in the system. The current number of instances of
each structure is shown in parenthesis next to the structure name. When a structure is selected, the boundaries of
one instance will be represented by a box in the display window. Modifying the fields to the right of the list will
affect only the selected structure.
Add
The “Add” button will prompt the user for a structure file on disk, which was saved using the “Save to
.str” feature in the “Edit” panel. A new structure will be created using the information contained in the binary
file. Multiple structures can be added using the same file, and these structures can be edited or renamed once
they are in the system.
Remove
The “Remove” button will delete a structure and all of its instances from the system. The “World”
structure cannot be removed.
Color
The color of structures can be defined to easily identify them in the display window. The color of the
structure is used for the box shown when the structure is selected, all particles within the structure, and all
springs which are internal to the structure. Click the button containing the colored rectangle to open a dialog
box enabling the choice of a new color for the currently selected structure.
Name
All structures (including “World”) can be renamed by changing the text shown in the text box under the
“Add” and “Remove” buttons. The name of the structure does not affect the simulation in any way; it is only
used to identify the structure within the list. Multiple structures can have the same name.
Instances
The numerical spinner allows multiple instances of the currently selected structure to be created. Each
instance can be independently placed within the system. Initially, when the spinner is increased, new instances
are placed in the bottom corner (0, 0, 0) of the world. It is very important to ensure that multiple instances are
not left at the exact same location when the simulation is exported, because particles are not allowed to initially
exist at the same location and the simulation server will display an error message and not run.
Structures: Move One
Select
The numerical spinner labeled “Select” allows a single instance of the current structure to be selected for
movement within the world. The currently selected instance can be identified by a box in the display window.
Changes to the position and rotation spinners within the “Move One” panel affect only the currently selected
instance.
Position
The “X,” “Y,” and “Z” numerical spinners allow positioning the currently selected structure instance
within the world. The values of the spinners refer to the position of the origin corner, before any rotations are
performed. If any particle in the structure is placed outside of the world boundaries, and soft wall boundary
conditions are enabled on the dimension of the exceeded boundary, the simulation will not exported. If periodic
boundary conditions are enabled, the particle will be moved to the other side of the world when the simulation
is exported.
Rotation
The “~X,” “~Y,” and “~Z” numerical spinners refer to the rotation of the currently selected structure
instance. The values are given in radians, rotated about the axis through the center of the instance. Three
rotations are performed to achieve the final orientation: first X, then Y, then Z.
Structures: Place All
Apply To
The numerical spinners and checkboxes labeled “X,” “Y,” and “Z” are used by the four methods of
automated placement. Details of each method are described below. The checkbox for each spinner enables the
method to affect the labeled dimension, and the value of the spinner is used by each method.
Randomly
Clicking the “Randomly” button will cause all structure instances of the currently selected structure to
be placed in a random location within the defined volume. The origin corner of each instance will be placed at a
position greater than zero, and the opposite corners will be placed at a position less than the value of the
numerical spinners. For example, a structure of size 103 placed randomly in a world of size 503 would be placed
randomly such that its origin is less than (40, 40, 40).
After each structure is placed, it is rotated randomly. It is not guaranteed that each particle of each
instance will be placed within the defined volume, only that the instance boundaries before rotation will be.
However, particles are not allowed to be placed outside of the world boundaries. If after many attempts at
placing and rotating instances randomly, particles cannot be constrained within the world, than an error message
will be displayed and the current instance to be placed will be shown with particles exceeding the world
boundaries.
Evenly
Using this method, instances of the currently selected structure will be placed evenly throughout the
system. Instances are placed in consecutive order, starting at the world origin. First, the instances are placed in a
row along the X dimension, then Y, then Z, excluding the dimensions which are disabled by the checkboxes.
Each instance is placed in its new position by adding the value of the numerical spinners and the size of the
structure to the position of the previously placed instance. An exception to this is when the value of the spinner
is equal to the size of the world (the maximum), in which case a value of 0 is used (for convenience reasons).
For example, placing structure of size 103 with a spinner value of 0 will align each instance exactly
adjacent. Using a value of 1 will leave a space of size 1 between each instance. Using a value of -9 will place
the structure origins 1 unit apart, which causes a significant overlap (and is technically valid).
Translate
Using the “Translate” button will cause all instances of the currently selected structure to be translated
by the values specified in the numerical spinners. Translating does not affect the rotation of each instance. The
instances can be moved such that particles within them are outside of the world, but the instance boundaries
cannot be placed entirely outside of the world.
The “translate” function is very helpful when used in conjunction with the previous two placing
methods, because these methods operate using the origin of the world as a starting point. After instances are
placed randomly or evenly relative to the world, they can be moved to another location while retaining their
positions relative to each other.
Reset
The “Reset” button sets the position and rotation of each instance to zero. It applies only to the
dimensions which are enabled by the checkboxes. The “reset” function does not utilize the values in the
numerical spinners.
Structures: Edit
The “Edit” panel is home to one of the most important features in the simulation designer. When edit
mode is enabled by entering the “Edit” panel, the display focuses on the first instance of the currently selected
structure. Particles in this structure are displayed as spheres using the parameters specified in the “Particle
Types” section.
A small-scale simulation is run for only these particles, and real-time editing of the structure (and
implicitly all of its instances) is possible. Particles are constrained within the structure boundaries using simple
hard wall boundary conditions. Values specified in the “Particle Types,” “Relations,” “Particle Properties,”
“Springs,” and “Simulation Options” sections have an immediate effect on the observed simulation.
While edit mode is enabled, the “World” numerical spinners in the “Simulation Options” section are
used to modify the boundaries of the structure instead of the boundaries of the simulation world. Also, the
particle selected in the “Particle Properties” list is shown as a white and slightly larger sphere.
Run Simulation
The “Run Simulation” checkbox is used to start and stop the simulation. While the simulation is
stopped, changes to the structure are still reflected in the display window.
Reset Particles
The “Reset Particles” button causes all particles in the structure to be placed randomly within the
structure. The velocity of each particle is initialized to zero.
Import Data
The “Import Data” button will prompt the user for an ASCII text file which contains formatted
information about particle positions and spring definitions used to build this structure. Only particles which
already exist within the structure will be moved to the positions described in the file. If any spring definitions
exist more than once in the file, the user will be prompted to ignore or include these duplicate springs.
This function is very useful for creating complex structures where the particles must be positioned in a
particular way that is difficult to do by hand. A user may write a small program which output positions of
particles in the required format, and then import that file to build the structure in the designer.
A detailed description of the file format is provided in Appendix A.
Save Structure
The “Save Structure” button allows the user to save the structure definition to disk as a binary file.
These files can then be opened by the designer in the future to create a new structure using the “Add” button.
All parameters of the structure (electrostatic charges, particle types, relations, springs, etc.) are stored in the file.
Saving a structure to disk using this feature is much easier than importing a text file using “Import Data”
each time the structure is required. It is recommended to save structures in this way if they are to be reused in
other simulations. Alternatively, saving the project as a whole using the “Save Project” function will keep all of
the structures in that project intact, and individual structures can later be extracted.
Particle Types
“Particle Types” are a collection of particles which have the same radius and mass. Each structure in the
system has associated to it a set of particle types. Local interactions between particles (relations) are defined per
particle type pair, meaning that every particle of type 1 will interact with every particle of type 2 identically.
Also, in order for “Import Data” (structure) to work correctly there must enough particles and particle types
defined.
Particle types with the same name will be merged into a single particle type when the simulation is
exported. Having as few particle types as necessary in the system will help simulation performance. However,
keeping particle types separate may be convenient for identification purposes, since the simulation output data
files will not distinguish between merged particle types.
List
The particle type list contains the names of all particle types defined in the currently selected structure.
The number of particles in this particle type is shown in parenthesis. One particle type can be selected, and the
inputs to the right allow modification of the currently selected particle type.
Add
The “Add” button creates and selects a new particle type with default values.
Remove
The “Remove” button removes the currently selected particle type. The first particle type in the structure
cannot be removed.
Visible
The “Visible” checkbox allows enabling or disabling of particle in this particle type in the display
window. This checkbox is only present when not interactively editing a structure (edit mode).
Color
Click the colored button to choose a color for the particle type. This color only has an effect on spheres
and springs displayed when editing the structure. The color chooser is not accessible when not in edit mode.
Name
Enter a name for the selected particle type in the textbox labeled “Name.” The “Relations” section will
be updated immediately to show the effect of merging particle types. If a relation exists between two particle
types which are subsequently renamed and merged, that relation’s values are lost.
Count
The “Count” numerical spinner allows specification of the number of particles in this particle type.
When the value is increased, new particles are placed randomly within the structure. When the value is
decreased, particles and the springs connected to them are removed. The number of particles in a particle type
can be set up to 10 million, but only the first 10 000 can be individually accessed and modified within the
designer. The remaining particles will be placed randomly within the structure instance, and can be accessed
during the simulation (by a plugin) like any other particle.
Radius
The numerical spinner labeled “Rad” controls the radius of all particles in the currently selected particle
type. The particle’s radius is the maximum range of local interactions defined in the “Relations” section
(including imported force curves). For example, a particle of radius 1.0 and a particle of radius 1.5 will interact
when the distance between them is less than 2.5 (when the edges of their spheres are in contact).
Mass
The numerical spinner labeled “Mass” controls the mass of all particles in the currently selected particle
type. The mass of a particle determines how forces on the particle affect its acceleration (F=ma).
Relations
A “Relation” is the specification of the interaction between particles, defined as the conservative and
dissipative force strength for each pair of particle types, and an optional force curve (to replace the standard
linear repulsive interaction). For convenience, the relation also includes the angle straightening force, which
acts on a triplet of particles (three particles with two springs) to straighten them into a line.
Conservative
The “Conservative” numerical spinner controls to the maximum strength of the conservative force
between a pair of interacting particles. If a custom force curve is used, the forces are scaled by this value. If the
standard force is used, the repulsive force is equal to zero at the edge of the interaction range (when the two
spheres are adjacent) and equal to this value when they are in the exact same location (which is a very unlikely
and problematic scenario).
Dissipative
The “Dissipative” numerical spinner controls the multiplier of the velocity-dependent dissipative force
between a pair of interacting particles. When modeling a fluid, the dissipative force is proportional but not equal
to the viscosity of the fluid. The random force is also dependent on this value according to the FluctuationDissipation theorem. The dissipative force is also affected by an imported force curve, if one exists.
Show Overlay Plot
The “Show overlay plot” checkbox enables a graph of the force curve for the currently selected relation.
The graph is shown in the display window as a transparent overlay. The Y-axis of the graph is the force, and the
maximum is labeled as the “Conservative” value. The X-axis is the distance between the particles, shown as the
sum of the radii. When a custom force curve is imported, the graph will be updated to show the correct
interaction.
Import
The “Import” button prompts the user to select an ASCII file with data points which are used to build a
custom force curve for the currently selected relation. X values in the file must be within 0 and 1, and are then
scaled by the interaction range for the relation. Y values in the file must be within -1 and 1, and are scaled by
the “Conservative” value. Negative Y values correspond to an attraction force, and positive values to repulsion.
The complete force curve is built by sorting and interpolating between the data points found in the file, and also
adding the points (0,1) and (1,0) unless they exist in the file. A detailed description of the file format expected is
given in Appendix A.
Straightening
The “Straightening” numerical spinner controls the multiplier on the force used to constrain each group
of three spring-connected particles into a straight line for the currently selected relation. When the three
particles involved belong to two different relations, the lower straightening force is used.
Particle Properties
The “Particle Properties” section allows operations on a specific particle of a structure. Changes made
affect all instances of the selected structure.
List
The particle list displays all particles in all particle types of the currently selected structure. The name of
the particle type followed by the index of the particle is used to identify each particle. Multiple particles can be
selected by using the standard CTRL and SHIFT keys. Only information for the selected particle which is first
(closest to the top of the list) is shown, but changes to these values affect all selected particles. If only one
particle is selected, and edit mode (interactive structure editing) is enabled, that particle will appear slightly
larger and colored white in the display window.
Group Select
The “All” button selects all particles in the list. The “Type” button selects all particles with the same
particle type as the first, and does not deselect any other particles which are currently selected. The “Data”
button selects all particles with the same “Charge,” “Hold Position,” and “Mark for Output” values as the first,
and also does not deselect any other particles which are currently selected.
Charge
The “Charge” numerical spinner allows specification of an electrostatic charge to the currently selected
set of particles. The current charge on each particle is shown in the list as a number in parenthesis.
During simulation, electrostatic forces are calculated in parallel on the clients using an approximated
exponential function. The distance-dependent force is then multiplied by the product of the charges on each pair
of particles. A positive charge product will create a repulsive force, and a negative product will create an
attractive force. The electrostatic interaction is long range (30 units) and is designed with the assumption that 1
unit = 1 Angstrom.
Mark
The “Mark” numerical spinner allows an integer tag between 0 and 10 to be specified for each particle.
This value is only accessible from simulation plugins, and is useful for identifying a set of particles when
calculating custom interactions.
Hold
The “Hold” checkbox indicates whether or not the currently selected set of particles should be prevented
from moving. Particles held in place will interact with other particles, but not move as a result of forces applied
to them. Holding a large number of particles together is one way to create complex, static boundaries such as
tubes and solid objects. Particles will only be held in place during the simulation if “Use Particle Holds” is
enabled in the “Simulation Options” section.
Track
The “Track” checkbox indicates whether or not the currently selected particles’ positions should be
displayed repeatedly in the simulation output window. This is convenient when it is necessary to watch a small
set of particles, for example to determine when to stop the simulation.
Position
The “Position” numerical spinners are enabled when a single particle is selected, edit mode (interactive
structure editing) is enabled, and “Hold” is enabled for the selected particle. Changing these values allow the
user to independently move a single particle within the structure. This is very helpful when creating a complex
structure with many springs.
Section 2: Springs
Spring Forces
Springs are used to bind particles together over a long range. Each pair of particles connected by a
spring receives an attractive force which increases as the distance between them increases. A spring is defined
by the pair of particles it connects, the natural spring length, and the spring constant.
The software interface can be used to attach springs between pairs of particles in a number of ways.
While structure editing mode is enabled, springs can be added, removed, and modified in real-time as the
simulation progresses in the display window. Springs can also be used to interconnect adjacent structures,
which is a process called “welding.” If springs must be created in a way which is too complex using the
interface, then the “Import Data” feature of the structure section can be used to import spring specifications
from a file.
Select Particles
The four drop-down list boxes allow any two particles to be selected. The top two lists contain the name
and index of all structures in the system, including all instances of each structure. After selecting a structure, the
bottom two lists contain the particle type and index of each particle within that structure. While edit mode is
enabled, only particles from the currently selected structure can be chosen.
List
While edit mode is enabled, the list of springs (shown below the Spring Forces section in the interface)
contains only those springs internal to the selected structure. While edit mode is not enabled, the list shows all
other springs which were defined while edit mode was disabled (springs between structures or springs custom to
each structure instance).
Multiple springs can be selected in the list, and modification to the spring constant or natural length will
take effect on all selected springs. Also, multiple springs can be removed at once.
Spring Constant
The numerical spinner labeled “Spring Constant” controls the multiplier of the spring force for the
currently selected set of springs. As this value is modified, the list of springs below will update to reflect the
changes to the selected springs. When new springs are created, the initial spring constant is set to the value in
this numerical spinner.
Note that changing this value while springs exist will always modify at least one existing spring. It is a
common mistake to change this value in anticipation of adding new springs, without realizing that current
spring data is being modified inadvertently.
Natural Length
The numerical spinner labeled “Natural Length” controls the distance at which two particles must be for
the spring force to equal zero. If the distance decreases below this value, the spring force will repel the particles.
Modifying this value will change the spring length for all selected springs, and the new values will be displayed
in the below list.
It is important to remember that springs are a specification of an interaction between particles, and not a
physical object in the simulation. Particles are free to collide with and pass through the area between two
particles which are connected by a spring, if the particles are far apart. When creating a long chain of particles,
the natural length should be low enough such that the particles are slightly overlapped, to prevent the chain
from crossing over itself or through other objects in the simulation.
It is also a common misconception that the natural length of the spring between two particles is also the
equilibrium distance between those particles during the simulation. If the particles are overlapped, the standard
conservative force will cause repulsion and the particles will settle at a distance greater than the natural length
of the spring.
Add and Through Next
The “Add” button will create a spring between the two particles selected in the drop-down lists above.
The “Through Next” numerical spinner allows a series of springs to be created when the “Add” button is
clicked. The index of each of the two selected particles will increase by one as many times as the value of
“Through Next,” and a new spring will be created for each.
For example, if particle indices 1 and 5 were selected, and “Through Next” was set to 4, then four
springs would be created between particles (1,5), (2,6), (3,7), and (4,8). This is very helpful when creating a
large number of small objects, a flat sheet, or a round tube.
Poly
The “Poly” button causes a series of springs to be created between the indices of the two selected
particles. If the selected particles belong to different particle types, then no springs are created. For example, if
particle indices 1 and 5 were selected, then four springs would be created between particle (1,2), (2,3), (3,4),
and (4,5). This is very helpful when creating a long chain of interconnected particles.
Remove
The remove button will remove all springs which are currently selected.
Structure Welding
Select Structures
The two drop-down lists allow two structures to be selected. All instances of the selected structures will
be welded by springs when the “Weld” button is clicked.
Within Distance
The “Within Distance” numerical spinner controls the maximum distance threshold for welding particles
in the selected structures when the “Weld” button is clicked.
Weld
The “Weld” button causes all particles in all instances of the first selected structure to be connected by
springs with all particles of all instances of the second selected structure, but only if those particles are within
the maximum distance threshold (the value of “Within Distance”). If a structure is selected to be welded to
itself, then only pairs of particles in different instances of that structure will be considered for welding. All
springs created as a result of welding will be grouped into a single item in the spring list, and individual weld
springs can not be accessed or removed.
If used carefully, this feature can be very convenient when creating a large system of interconnected
structures. However, if an incredibly large number of springs are created, particles may collapse on themselves
or behave unpredictably due to high-energy competition between angle straightening forces.
Section 3: Simulation
Project
Save
The “Save” button will prompt the user to save a “.prj” file containing all data related to the system. A
saved project can be loaded using the “Open Project” button.
Open
The “Open” button will prompt the user to load a “.prj” file which was previously created with “Save
Project.”
Export Simulation
The “Export Simulation” button will create an executable simulation server program. When the system
is exported, all data relevant to computation will be stored in a “.sim” file. Structure instances and particle types
with the same name will be merged to increase efficiency of computation. While exporting, data is checked for
consistency, and an error may occur when any of the following is true:





The system has no particles
Two particle types with the same name have different radii or mass
Soft walls are enabled on the dimension that a particle exceeds the world boundary
Correct box widths are not possible for at least one particle type (see below)
An error occurred while compiling the plugin function
Parallelization of the simulation requires that the world can be divided at least three times into equally
sized boxes on each dimension. The width of these boxes must be an integer, and must be at least as large as the
particle diameter for each particle type. Box widths are chosen automatically to maximize efficiency, but if the
particle and world sizes are chosen such that correct box widths are not possible, an error message will be
displayed. The greater the number of possible box widths to choose from, the more efficiently the optimal box
width can be chosen. Therefore, it is recommended to choose world sizes which are highly divisible.
If electrostatic charges are being used, and a world dimension using periodic boundary conditions is less
than 120 units, a warning message will be displayed indicating that incorrect behavior may be observed. If the
world is too small, particles should be able to interact with each other more than once, due to the long range of
electrostatic forces. However, the simulation will only apply a force to particles based on the interaction of the
shortest distance.
If the export process is successful, two files will be created in addition to “.sim” file chosen by the user.
First, the “sim.f0” file contains the initial positions of all particles in the system. This binary file is of the same
format as a data file output during simulation, so it can be replaced by any of these files to “restart” the
simulation from any point.
Finally, a “.sim.exe” file is created which is the executable server. Simply running this program will
start the server on port 10000 (default) and create an output folder with the same name as the .sim file (without
the extension). These values can be passed as parameters to the server using the command line (for example,
“mytest.sim.exe outputfolder 12000”).
In order for the simulation to run, at least one client must be connected to the server. Running the client
program with no parameters will attempt to connect it to a server on the local IP address of 127.0.0.1, using port
10000. These values can be passed as parameters using the command line (for example, “client.exe 5.150.24.31
12000) so the client can connect to a server anywhere on the internet or network.
If the “Run Now” feature is enabled, the server and one client will be automatically executed once the
export process is complete.
Only as many clients can be connected as there are boxes in the X dimension. Boxes are created for each
particle type, using the automatically chosen box widths and the world X dimension. A system with a much
larger X dimension than Z will have the ability to accept more clients than the same world rotated 90 degrees.
Whether the X or Z dimension should be larger depends on a number of factors, including number of particles
and particle types in the simulation, and the number of clients available. The number of boxes created in the
simulation which clients can connect to is shown in the server’s output before computation begins. Connection
attempts from clients after the maximum number of clients exist will be ignored.
If a client is disconnected from the server, the simulation will stop immediately. Clients must be present
for work during the entire simulation. This event should definitely be avoided. If the simulation stops, it can be
restarted manually by replacing the “.sim.f0” file with any output data file.
Run Now
The “Run Now” checkbox controls whether or not to begin running the simulation immediately after the
simulation is exported. The server will be executed with default parameters, one client will be connected, and
calculation will begin immediately. When the simulation is complete, the server and client windows will both
be closed.
This feature is very convenient when exporting a very small simulation and results are needed quickly.
Since the “Analyzer” section will open the simulation automatically, visualization of the results can occur
quickly and seamlessly without leaving the software interface.
Simulation Plugin
The “Browse” button, displayed when no plugin has been opened, prompts the user to select a “.dpd”
file containing custom code to be used as a simulation plugin. The “Close” button is displayed when a plugin
exists, and clicking this button will remove the plugin from the simulation (the file will not be deleted from
disk).
The file contents are not stored in the project, only the file name. Because of this, plugin code will not
be stored when the project is saved using “Save Project.” When a project is opened that has a plugin, an attempt
will be made to open the file, and a warning message will be displayed if the plugin cannot be found. If changes
are made to the plugin file prior to exporting, the file does not have to be re-opened because the file contents are
not stored in the designer. However, once the simulation is exported, the file is compiled and linked into the
server executable and changes to the file will not have an effect on that simulation.
The plugin function must include the implementation of three functions: one which can be used to
specify the initial position and velocity of particles, as well as initialize any custom data structures, one which
allows forces to be applied to all particles and is executed once per time-step, and one which allows
modification of position and velocity of a single particle at a time, executed once for each particle. Only one
plugin can be selected for a simulation, but functions from other files can be included and called from the plugin
using standard C code.
Details regarding implementation of plugin functions are provided in “plugin.h.”
Simulation Options
World
The three numerical spinners labeled “X,” “Y,” and “Z” correspond to the size of the system in each
dimension. Each dimension of the world size must be an even integer, a multiple of all of the box widths chosen
automatically for each particle type, and at least three times each of the box widths. Even though the box width
selection is automatic, the simulation will be more efficient if the world extents chosen for each dimension are
multiples of many integers.
For example, given a system with particles of diameter 4, a box width of at least 4 must be used. If the
world size is 42x36x60, the box width chosen will be 6, since this is the only integer greater than or equal to 4
which divides evenly into each of 42, 36, and 60 at least three times. If the world sizes were modified to be
40x40x60, the set of possible box widths grows to 4, 5, and 10. The most efficient of these three widths will be
chosen depending on the number of particles in the system, which could decrease computation time by a factor
of 2.
Given a high density of particles, smaller box widths will be more efficient because fewer particles will
be considered for interactions that are far apart from each other. However, a system with a small number of
particles will benefit from the decreased overhead of a small number of boxes. Depending on the characteristics
of the system, the world size should be carefully chosen to allow the optimal box widths to be considered for
selection.
Boundary Conditions
The three drop-down lists allow selection of either periodic, hard-wall, or soft-wall boundary conditions
for each dimension of the world. Periodic boundaries will cause particles and their interaction ranges to wrap to
the opposite side of the world, simulating an infinite system. Hard-wall boundaries will reverse the velocity of
the particle when it reaches the boundary. Soft-wall boundaries cause particles to feel a repulsive force when
within 1.5 units of the boundary, which includes a dissipative and random component so the correct temperature
is maintained. If a particle penetrates the soft layer and reaches the world boundary, its velocity is reversed.
If electrostatic charges are used in conjunction with periodic boundary conditions, the world size on the
periodic dimensions should be at least 120 units. This prevents problems arising from the electrostatic
interaction affecting the same pair of particles more than once. The simulation will only apply forces to the
particles from the interaction which is associated with the smaller distance between the particles.
Custom boundary conditions can be created in addition to these using the simulation plugin functions.
The ability exists to explicitly place the particles anywhere in the system after the standard boundary conditions
are applied. The standard boundary conditions chosen from this list cannot be removed from the system, in
order to prevent particles from leaving the world accidentally.
Timestep
The numerical spinner labeled “Timestep” controls the Δt value used to integrate Newton’s equations of
motion. A high Δt value causes particles to move further during each step of the simulation, which decreases
accuracy but causes the simulation to progress through actual time more quickly. Δt should be chosen such that
the simulation progresses at a reasonable rate, and particle interactions remain stable.
When using small water particles or the background water model, larger particles require a much smaller
Δt parameter to prevent instability due to the magnitude of the drag force and number of interactions that occur.
To verify that a given Δt is sufficient, large particles should be tested using the structure editing mode.
Frames
The numerical spinner labeled “Frames” controls the number of steps performed by the simulation. This
value multiplied by the Δt value equals the actual time of the simulation which is used in the “Analysis” section
of the software.
Output Every
The numerical spinner labeled “Output Every” controls the number of simulation steps that will be
performed before particle data is output to a data file. When output files are created, they are numbered not by
the simulation step which they are associated to, but by the order in which they are actually written to disk. The
“Output Every” value is stored within the output data file so that the “Analyzer” portion of the software can
extract the actual simulation time without requiring the “.sim” file.
Background Water
The numerical spinner labeled “Background Water” controls the dissipative force which is used by the
model for background static viscous fluid. When this feature is enabled by the “Enable” checkbox adjacent to
the numerical spinner, a dissipative and random force is applied to each particle in the simulation which is
equivalent to that of a fluid comprised of a high density of actual particles. The value specified here represents
what would be the dissipative force strength of those particles. This value is proportional but not equal to the
viscosity of the fluid being modeled due to temperature dependence and other factors.
Temperature
The numerical spinner labeled “Temperature” controls the temperature of the system, given by a
temperature in Kelvin multiplied by Boltzmann’s constant. This value is used to scale the random force so that
the observed temperature in the system approaches this value due to the Fluctuation-Dissipation theorem.
Gravity
The numerical spinner labeled “Gravity” controls the acceleration in the negative Y direction that is
applied to every particle in the simulation. This feature could be very easily implemented in a simulation plugin,
but is available here so that it can be used when interactively editing a structure.
Soft Wall Strength
The numerical spinner labeled “Soft Wall Strength” disables the default adaptive soft-wall algorithm
that attempts to prevent high-density layering of particles at the edges of the world. The wall strength, which is
normally calculated dynamically using the density distribution of particles, will be set to the specified constant
value. By un-checking the associated “Enable” checkbox or setting the constant strength to zero, the override
will be disabled and the adaptive algorithm will be used. For a wall strength of zero, use the “Hard Wall”
boundary conditions.
Use Particle Holds
The checkbox labeled “Use Particle Holds” will enable or disable (for the final simulation only)
particles being held in place by the “Hold” checkbox in the “Particle Properties” section. This feature makes it
more convenient to hold certain particles in place while designing a structure, without prevent movement during
the actual simulation.
Server Options
Record Particle Velocities
This checkbox enables the inclusion of particle velocities in simulation output data files. Particle
velocity data is required for the “Temperature Distribution” built-in analysis function and the display of average
velocity and temperature in the analysis display window. Disabling this feature will decrease the file size of
output data.
Allow Data Transfer Between Clients
This checkbox enables the direct transfer of information between clients connected to the same
simulation. If this feature is enabled, clients will request particle information from other clients, which reduces
network transfer load on the server, and will usually result in higher performance for large simulations. This
feature will not work when any clients local to the simulation server are connected (same IP address).
Show Detailed Status
This checkbox enables the display of detailed information in the server output window. When this
feature is enabled, information for each frame will be displayed instead of only when a data output file is
written. Also, a form of “progress bar” will display which boxes are being calculated by clients in real-time.
Electrostatics Options
Enable Electrostatics
The checkbox labeled “Enable Electrostatics” will enable or disable the calculation of electrostatic
forces during the simulation. If disabled, particle charges will be ignored. Since electrostatics are often the
slowest part of the simulation execution, disabling this feature may greatly increase simulation performance and
can be convenient when testing and running non-final simulations.
Kappa
This value represents the Debye screening Kappa value used for electrostatic interactions. A larger value
of Kappa will decrease the effect of electrostatic forces at longer ranges, and smaller value requires a longer
interaction cut-off range to avoid accuracy problems.
Epsilon
This value represents the coefficient of the electrostatic interaction forces. This value can be used to
scale the electrostatic interactions to allow for non-integer charges on particles. Where 1 unit of charge equals
1.602 x 10-19 Coulombs, this value is 2.852 for a medium of water in energy units of 10-20 Joules and distance
units of 10-10 meters, and should be scaled accordingly.
Interaction Cut-off
This value represents the maximum distance that charged particles will experience electrostatic forces.
An acceptable cut-off range for most situations is 3/kappa.
Section 4: Analyzer
Simulation
Browse and Close
The “Browse” button, displayed when no simulation is opened, prompts the user to choose a “.sim”
exported simulation file for analysis. When a “.sim” file is opened, its filename is displayed to the right, and a
“Close” button is displayed. The current simulation must be closed using the “Close” button before opening a
new simulation.
When a simulation is exported, it is automatically opened by the “Analyzer.” If a frame sequence is
opened using the “Frame Sequence” section while no “.sim” file is currently loaded, data extracted from the
frames be used to partially fill the “Simulation” section and the “Close” button will be displayed.
Simulation: Particles
List
The list on the left of the “Particles” section displayed the names of the Particle types which exist within
the currently opened simulation. If a frame sequence is opened without a “.sim” file, the particle types will be
displayed as “Type #,” where # is the index of the particle type. The number of particles in the particle type is
shown in parenthesis. One item can be selected from the list. The data elements to the right of the list reflect
only the currently selected particle type.
Color
The “Color” button prompts the user to select a color for the currently selected particle type. Particle,
points, and springs for this particle type will be shown using this color in the display window.
Information
The four text labels following the “Color” button display the name, number of particles, radius, and
mass of the currently selected particle type. These values are correct when a frame sequence is opened without a
“.sim” file.
Show
The drop-down list labeled “Show” controls how particles of this particle type are displayed in the
display window. When a large number of particles exist, using the “Spheres” option can result in low display
performance.
Radius
The numerical spinner labeled “Radius” controls the visible size of the particle in the display window.
When viewing spheres, the radius of the sphere is directly controlled by this percentage. When viewing points,
the percentage controls the size of the point, but is not related to the actual particle radius.
Display Every
The numerical spinner labeled “Display Every” allows the display of only some of a large set of
particles. The display window will show, for each particle type, every nth particle, where n is the value of
“Display Every.” This allows a high density of particles to be represented by only a few, while the behaviour of
these particles can still be observed.
Simulation: Springs
List
The list in the “Springs” section shows all springs which currently exist in the simulation, grouped by
particle type of the connected pair of particles. The names of the two particle types are displayed, followed by
the number of springs in parenthesis. One item can be selected from this list.
Display
The “Display” checkbox controls whether or not the current selected group of springs are shown in the
display window.
Simulation: Information
The “Information” section displays other information about the simulation. The total number of
particles, total number of springs, dimensions of the world, boundary conditions, Δt timestep, temperature, and
gravity are displayed when a “.sim” file is opened. When a frame sequence is opened without a “.sim” file, only
the number of particles and dimensions of the world are shown.
Simulation: Display
Use Low-Resolution Spheres
This checkbox will cause all spheres to be drawn at a lower quality, increasing display performance.
When viewing simulations will large numbers of particles, it may be convenient to enable this feature instead of
viewing the particles as points.
Use White Background
This checkbox will change the color of the display window background to white for easier printing.
Hide World Boundaries
This checkbox will disable drawing of the world isolated section boundaries in the analyzer. This is
convenient when generating animations.
Show Static Meshes
This checkbox will enable drawing of static meshes which were created using the ‘mesh’ plug-in. These
include any meshes used as interacting boundaries or simply for placing particles, which were not made
dynamic.
Show Dynamic Meshes
This checkbox will enable drawing of dynamic meshes which were created using the ‘mesh’ plug-in.
These include any meshes which were made dynamic.
Show Mesh Wire-frames
This checkbox will enable drawing of meshes using only 3D wire-frames. The default is to show all
mesh polygons using a smoothed and globally illuminated fill color.
Frame Sequence
Sequence Folder
The “Sequence Folder” text field allows entry of the folder name which contains output data files from
the simulation. The “Open” button will open a frame sequence, and the “Close” button (displayed once a
sequence is opened) will close a frame sequence.
If a “.sim” file is not opened when opening a frame sequence, data will be extracted from the frames and
used to partially fill the “Simulation” section above. If a “.sim” file has been opened, the frames will be checked
to ensure that they are consistent with the opened simulation. If they are not consistent, the frame sequence will
not be opened.
Once a frame sequence has been opened, particles and springs (if applicable) are shown in the display
window. The following controls in this section are further enabled for use.
Start
The “Start” button navigates the display to the first frame in the sequence.
Prev
The “Prev” button navigates the display to the previous frame in the sequence, incremented down by the
value of the numerical spinner to the right.
Play and Stop
The “Play” button will open and display each frame in order, incremented by the value of the numerical
spinner to the right. While playing, many controls are disabled, and the “Stop” button is displayed. The “Stop”
button will stop playing the sequence at the current location. Display of particles occurs in parallel will opening
of the next frame for increased performance.
Next
The “Next” button navigates the display to the next frame in the sequence, incremented by the value of
the numerical spinner to the right.
Increment
The numerical spinner labeled “x” controls the increment amount used by “Play,” “Next,” and “Prev.” A
large value will cause frames to be skipped, resulting in a faster progression through the frame sequence.
Loop
The “Loop back to start at end of sequence” checkbox will, when play to the end of the sequence occurs,
cause the first frame to be displayed and play to continue. If this feature is disabled, when play reaches the final
frame in the sequence, the display will pause and continuously wait for the next frame to be created. This is
convenient when viewing a sequence for a simulation which is currently being executed. Once play reaches the
end of the sequence, frames will be displayed as they are created by the simulation.
Output Animated GIF
The “Output .gif” text field allows creation of an “Animated GIF” video using what is viewed in the
display window. A “.gif” file will be created using the value supplied in the text field to the right. When this
feature is enabled, the “Play” button will start recording of the video, and the “Stop” button will stop recording
and create the output file. The pixels actually viewable to the user within the display window will be used to
create the video frames, and behavior when the display window is not fully viewable is undefined.
The “Animated GIF” is a standard image format which contains multiple frames which are separately
compressed. The video may be opened by any web browser and most advanced image viewers (including the
Windows default viewer). When a small number of particles are displayed and each the image is mostly the
background color, the file size will be fairly small. However, complicated images will result in large file sizes
due to the nature of GIF compression. Using a third-party GIF utility, individual frames can be extracted from
the animation, and then these frames can then be used to create a higher quality video using other software.
Additional Object Display
Fluidix can overlay an additional set of lines or spheres into the analyzer display. Lines and spheres are
defined in separate text files specific to an individual frame of a frame sequence. This makes it possible for the
results of complicated analyses which produce 3D points or lines (such as velocity streamlines or particle paths)
to be displayed with the particles themselves, included in an animation, and visualized interactively with the
camera controls.
Each time a frame is displayed in the analyzer, Fluidix attempts to open from main Fluidix directory a
file called “[frame sequence]-[frame number]-lines.txt”, and displays any lines found in that file. For example, a
file named “mysim-50-lines.txt” would be read when frame 50 of “mysim” was first displayed. The exact
format of this file is described in Appendix A.
In addition, Fluidix will attempt to open a file called “[frame sequence]-[frame number]-spheres.txt”,
and displays any spheres found in that file. For example, a file named “mysim-50-spheres.txt” would be read
when frame 50 of “mysim” was first displayed. The exact format of this file is described in Appendix A.
Data Analysis
The “Data Analysis” section is very convenient for performing a quick analysis procedure on simulation
output data, especially when interested in only a small area or slice of system. One may determine visually an
area of interest, play the frame sequence to view the progression of the simulation within only this area, execute
an analysis function which operates on only this area, and immediately observe a plot of the results on the
display window which shows the current time as the sequence is played.
If velocities are present in the output data file currently viewed in the display window, then the average
velocity of all visible particle types within the selected volume will be shown, as well as the total temperature of
those particles.
This section is designed to be a helpful resource for a first look at the simulation results. One can easily
determine if the simulation results are as expected in order to make a quick decision for executing a new
simulation. More advanced mathematical analysis on the simulation output data can be performed using thirdparty software. Also, the analysis function can be used to create a custom data file containing information
relevant to a further analysis by interpreting and translating the binary simulation output files.
Selected Volume
The six numerical spinners labeled “X,” “Y,” and “Z” allow definition of a rectangular volume within
the system, by specifying a maximum and minimum on each dimension. The box created using these values
will be shown in yellow in the display window, and the viewpoint will focus on the center of this box instead of
the center of the world. Also, particles which lie outside of this box will not be displayed. Only particles in this
box will be analyzed by the built-in functions (temperature distribution, etc.).
Particles and springs within this volume will be marked using the appropriate arrays defined in
“analysis.h.”
Velocity Field
By selecting a particle type from the “Velocity Field” drop-down list, a vector field will be displayed
within the selected volume. Vector lengths are related to the average velocities of those particles near to each
vector’s origin, weighted by distance. The vector will fade out and disappear when its length is very small,
making it very easy to visualize in 3D which particles are moving and in what direction.
Temperature Distribution
The three checkboxes labeled “X,” “Y,” and “Z” enable analysis of the temperature of 100 slices of
particles (sliced along the specified axis) within the selected volume and the visible set of particle types, and the
results are plotted in the display window. The plot will update as data output files are viewed. This feature can
only be used when simulation data files include particle velocities (see “Record Particle Velocities”).
Density Distribution
The three checkboxes labeled “X,” “Y,” and “Z” enable analysis of the density of 100 slices of particles
(sliced along the specified axis) within the selected volume and the visible set of particle types, and the results
are plotted in the display window. The Y-axis of the plot represents the number of particles found within each
slice. The plot will update as data output files are viewed.
Pair-Correlation
This checkbox enables a pair-correlation test on the visible set of particle types within the selected
volume, and the results are plotted in the display window. The “Range” numerical spinner controls the
maximum distance from each particle to search, which is the maximum of the plot’s X-axis. The Y-axis of the
plot represents the number of particles found in each of 100 concentric spherical slices within “Range” of each
particle, divided by the volume of that slice. This gives an indication of how particles are arranged relative to
each other.
The two drop-down lists allow selection of the two particle types which will be analyzed, where
particles in the first particle type will be the centers of the spherical slices, and particles of the second type will
be counted.
Smooth Plots
The “Smooth plots by average data points” checkbox enables smoothing of the data produced by the
above built-in analyses. Each data point will be set to the average of it and its two adjacent points, providing a
smoother curve and allowing data trends to be more evident.
Browse and Execute
The “Browse” button prompts the user for a “.ana” file which contains a custom analysis function. When
the “Execute” button is clicked, this file is compiled into an analysis program and then executed. The output
from this program is displayed. When analysis is complete, the analysis output window will prompt the user to
press any key, which will then close the window.
For more information about implementation of the analysis function, see “analysis.h.”
Overlay Plot
The “Browse” button prompts the user for a formatted ASCII data file which contains information used
to generate a translucent overlay plot on the display window. The file may include any number of data series’,
which will each be represented on the plot simultaneously.
The X-axis of the plot represents the actual simulation time, scaled by the minimum and maximum
values found in the file. A white slider will be displayed at the current time when the current frame in the
sequence is associated with a time within the plot. The Y-axis of the plot is scaled by the minimum and
maximum values found in the file.
A detailed description of the file format is provided in Appendix A.
Appendix A: File Formats
Structure Data
The “Import Data” feature of the Structure section requires an ASCII text file containing particle
position, charge, and spring information. There must be exactly as many particles in the file as there are
particles in the structure. This file must be formatted correctly or an error message will be displayed when the
file is imported. The format of the file is as follows:
x1
x2
...
xn
pti1
pti2
...
ptim
y1
y2
z1
z2
c1
c2
yn
pi1
pi2
zn
ptj1
ptj2
cn
pj1
pj2
k1
k2
pim
ptjm
pjm
km
There should be one line of three floating point values for each particle in the structure followed by the
integer charge on the particle, representing the position and charge on each particle in order. All particles of the
first particle type should be listed first, followed by all particles in the second particle type, etc. After all
particles in the structure have been listed, any number of springs can be defined. Five integers should exist on
each line, which represent the particle type of the first particle in the spring, the index of this particle, the
particle type of the second particle in the spring, the index of that particle, and finally the spring constant. The
natural length of the created spring will be set exactly to the distance between the two particles.
Relation Force Curve
Any arbitrary curve can be imported into the “Relations” section to shape the force-distance interaction.
The values imported in the ASCII file will be multiplied by the interaction range and the conservative force
value specified for the relation. The values will also be sorted on the X dimension (distance) and interpolated
linearly to determine intermediate values. The format of the file is as follows:
x1
x2
...
xn
y1
y2
yn
One line should exist for each point which contains two floating point values. The X values must range
between 0 and 1, and the Y values must range between -1 and 1. There are only 1000 points in the final
interpolated interaction, so creating a function by specifying more than 1000 points will not provide higher
accuracy. The points (0,1) and (1,0) are automatically added to the plot but points explicitly specified within the
file take precedence.
Analysis Overlay Plot
The overlay plot in the “Analysis” section can be created using any ASCII file with appropriately
formatted data. In order for the time slider to function properly, the X axis of the plot must reflect the actual
simulation time. Y values are scaled within the plot by the maximum and minimum values in the file, and the
axes are labeled accordingly. The format of the file is as follows:
t1
t2
...
tn
y1-1
y1-2
y2-1
y2-2
...
...
ym-1
ym-2
y1-n
y2-n
...
ym-n
Each column in the data file corresponds to a data series, except the first column, which is the simulation
time. Each data series will be displayed on the overlay plot as a line which connects each of the points provided.
Each line in the data file represents one of these points for each data series. There must be the same number of
columns in every line of the data file.
Additional Line Display
The analyzer will overlay lines defined in a file specific to each frame of a frame sequence. The file
name must be of the following format:
[frame sequence]-[frame number]-lines.txt
This file should consist of a list of lines, where each is a set of floating-point positions that will be
connected in series by line segments, followed by the red, green, and blue component of the color of that line
segment (range 0 to 1). A line in the text file with an x-coordinate less than zero indicates the end of a line
series. The format is as follows:
x1
x2
...
xn
-1
x1
x2
...
xm
-1
...
y1
y2
z1
z2
r1
r2
g1
g2
b1
b2
yn
0
y1
y2
zn
0
z1
z2
rn
0
r1
r2
gn
0
g1
g2
bn
0
b1
b2
ym
0
zm
0
rm
0
gm
0
bm
0
For example, the following would be acceptable:
2.5
5.7
-1
2.8
2.4
2.2
2.1
-1
7.4
2.5
0
1.2
1.4
1.8
2.6
0
6.2
9.1
0
0.5
1.0
2.5
7.0
0
0.8
0.5
0
0.15
0.75
0.85
0.25
0
0.1
0.2
0
0.15
0.75
0.5
0.25
0
0.3
0.8
0
0.3
0.75
0.5
0.1
0
Using this example would result in Fluidix displaying two connected series of two and four points.
Additional Sphere Display
The analyzer will display spheres defined in a file specific to each frame of a frame sequence. The file
name must be of the following format:
[frame sequence]-[frame number]-spheres.txt
This file should consist of a list of floating-point positions which define the center of each sphere, the
radius of each sphere to be drawn, and the color (3 components ranged 0 to 1). The format is as follows:
x1
x2
...
xn
y1
y2
z1
z2
rad1
rad2
r1
r2
g1
g2
b1
b2
yn
zn
radn
rn
gn
bn
For example, the following would be acceptable:
7.5
5.7
2.2
2.1
7.3
2.5
1.8
2.6
7.2
9.1
2.5
7.0
1.0
1.2
1.5
0.75
0.8
0.2
0.85
0.25
0.1
0.75
0.5
0.25
0.3
0.7
0.5
1.0
Using this example would result in Fluidix displaying four spheres.