Code for conducting direct numerical simulations for droplet impact onto spring-supported plates using Basilisk. Used in producing the results for our recent paper Droplet impact onto a spring-supported plate: analysis and simulations in the Journal of Engineering Mathematics.
Contributors: Michael Negus, Radu Cimpeanu, Matthew Moore, James Oliver
- A recent installation of Basilisk is required to run the simulations, see here for installation instructions for Basilisk.
- The additional packages for visualisation are also required if you wish to produce movies of the simulations, however this option can be turned off if you do not wish to install the additional packages.
- An installation of gfsview is also recommended for visualising the gfs_output files.
- Most of the data analysis files are written in MATLAB, however the data output of the Basilisk scripts are in a general form that any data analysis toolset can be used.
These simulations take place within an axisymmetric framework with coordinates (r, z). In Basilisk, the axisymmetric coordinates are given by x = z, y = r, so within the code keep in mind that, counter-intuitively, the vertical direction is given by x and the radial by y.
In addition, the time coordinates in the paper are scaled such that t = 0 at the
time of impact. Within the simulations, the droplet is initialised at a height
given by INITIAL_DROP_HEIGHT
at t = 0
, so the impact time is at t = INITIAL_DROP_HEIGHT
.
This means when comparing the computational and analytical solutions, the
computational time will need to be adjusted by this amount.
Below we give a brief tutorial as to how to run a simulation. Although not strictly required, familiarity with Basilisk (at least up until the point you can run the tutorial) is very useful.
As an example, the code in the example_run
directory is immediately ready to be
run. In the command line, enter the directory example_run/code
and run the command
./run_simulation droplet_impact_plate
After a bunch of text initialising the Makefiles, you should eventually see
[droplet_impact_plate.tst]
which indicates the code is running! This example will run the simulation for
a maximum refinement level of 6, with plate parameters ALPHA = 2
, BETA = 0
and
GAMMA = 500
up until t = 0.8
. During run-time, the output will be in a directory
called droplet_impact_plate
, and if you want to check how things are going then
open the file named log
, which will output various quantities for t += 1e-4
.
Calling the above command will run the code on one core only, which is very
slow! To run the code on N
cores, you need to run
./run_simulation droplet_impact_plate N
It is recommended to make N
a power of 2 (e.g. 2, 4, 8, 16, ...) for optimal
load balancing. The time it takes to run will depend on your computational setup,
but for 4 cores you can expect the run to take around 20 minutes. Because of this,
it is wise to make the simulation run in the background, to prevent losing your
progress if you close the terminal window. To do this, run the command
nohup ./run_simulation droplet_impact_plate N &
Here the command nohup
sends what would have been outputted to the command line
into a file called nohup.out
, and the &
sign suppresses the terminal output. This
means that the code is running in the background and you can safely close all
terminal windows. When you run this command, you'll get a command line message
that looks something like
[1] 22791
nohup: ignoring input and appending output to 'nohup.out'
In this case, the PID of the process is 22791. It is worth noting this down, as if you wish to end the process early, you'll need to use the command
kill 22791
where of course replace the 22791 with the PID you were given.
At the end of the simulation, all of the output will be moved into a directory
called raw_data
in the example_run directory, so the contents of example_run are
the code and the raw_data
directories. We'll discuss what to do with this data
in the following sections.
The example code runs the code with a relatively coarse grid (with MAXLEVEL = 6
,
while the results in the paper have MAXLEVEL = 13
). In order to change parameters
such as the maximum refinement level, you need to edit the values in the parameters.h
file found in the utility_scripts
directory. This script contains all of the
parameters used in the code, both physical parameters like the properties of the
plate, and computational parameters like the refinement level.
In its current form, the parameters script is set up with the values that were
used to produce the results in the paper. In terms of computational options such
as the refinement level, things should be kept the same. However note that with
MAXLEVEL = 13
, the code takes about 8 hours to run on 8 cores, so this may want
to be reduced while getting to grips with the code.
The main parameters that you'd want to change are the plate parameters ALPHA
,
BETA
and GAMMA
, as these change the properties of the plate as seen in the figures
in the paper. As well as these, it is also important to run the control case, where
the plate is held stationary. In this case, you'd set the CONST_ACC
flag to 1,
which will set the acceleration of the plate to the constant value given by
PLATE_ACC
. If PLATE_ACC = 0
(as it is by default), then the plate will be
stationary and this will provide the parameters for the test case.
Apart from these, feel free to look at the other parameters listed in parameters.h
,
and find out how they're used in the droplet_impact_plate.c
script.
Once you've set the parameters as desired in parameters.h
, you'd want to run the
code! First, you'll need to copy the scripts into a different directory on your
system (preferably one with plenty of disk space). Say you want to run your
code in a folder called myRun
inside a parent directory called parentDir
; then
enter the utility_scripts
directory and run the command
./code_copy.sh ../droplet_impact_plate parentDir myRun
This will create a directory called myRun
inside parentDir
, and inside myRun
there will be a sub-directory called code containing the scripts: droplet_impact_plate.c
,
Makefile
, parameters.h
and run_simulation.sh
. This is the exact setup that
was in your original example_run/code
directory. This script is ready to be
run in the exact way you did for the example, and running
nohup ./run_simulation droplet_impact_plate N &
inside the code
directory should kick off the simulation!
The simulations produce a lot of data output, and on their own they can be
confusing and disorganised! Once the simulation has finished, all of these output
files are left in the raw_data
directory. Here we detail what these files are:
- log
The log file outputs the relevant global quantities fort += 1e-4
. Specifically, these are:F
: The unfiltered force on the plate at timet
force_term
: The force term after filteringavg
: The average force over the lastPEAK_LAG
timestepsstd
: The standard deviation of the force over the lastPEAK_LAG
timestepss
: The plate positionds_dt
: The first time derivative of the plate positiond2s_dt2
: The second time derivative of the plate position The log file is in a readable form, but will need to be cleaned to use in post-processing (see later in this section).
- mp4 files
If you've chosen to output movies, then movies of the process will be produced in a bunch of mp4 files. These are the easiest ways to visualise the simulation. - gfs files
The files with a.gfs
extension are files that can be opened using gfsview (if you have installed it). I.e. to open thegfs_output_1.gfs
, callgfsview2D gfs_output_1.gfs
. See the Gerris website for more details on how to work gfsview. - interface_N.txt
At regular intervals, the interface of the droplet is outputted into theinterface_N.txt
files, where N is incrememented. These files contain the start and end points coordinates of each line segment along the interface. This can either be used to visualise the interface in a "smart" way by drawing the line segments, or just producing a scatter plot out of all of the points. - plate_output_N.txt
At regular time intervals, these files output the pressurep
and viscous stressstrss
along the plate at x = 0 (i.e. z) for various y (i.e. r). In its raw form these are in a human-readable format, and after cleaning these can be used to visualise the evolution pressure and viscous stress in post-processing.
As mentioned, the log
and plate_output_N.txt
files are in a human-readable
form, which is no good for post-processing. You can clean these scripts by going
into the utility_scripts
directory and
running the command
./output_clean.sh dir
where dir
is the address to the directory where the code
and raw_data
directories are. To try this out, you can run this command for the example run.
This command will move some of the data from the raw_data
directory into new
directories that make it easier to access, such as moving the mp4 files into the
movies
directory and the gfs files into a gfs_files
directory, and move the
log
file into the parent directory. It also creates a new cleaned_data
directory, where the file output.txt
is the log
file after removing all of
the non-numeric text, and similarly the plate_outputs
directory contains
cleaned versions of all of the plate_output_N.txt
files. These are less human-readable,
but are in a form where you can use post-processing. For example, you can
call MATLAB's readmatrix
function directly onto any of these files to get a
matrix with the same rows and columns as these text files.
After cleaning the data, you should be ready to analysis the data in post-processing.
There are many scripts for this in the data_analysis
directory, however these
currently have not been organised very well. It may instead be best to write your
own post-processing scripts with your language of choice, as this is the best way
to get to grips with the output, however if you get stuck then exploring the
contents of data_analysis
may help.
If you get stuck at any point, then please do reach out via email, where my address is given on my GitHub profile. Otherwise the Basilisk website has plenty of documentation and an active forum page that are always happy to help. Good luck!