 |
|
|
|
This feature is still in development, so the documentation is meant for developers only. However, anyone is welcome to give it a try.
MercuryCG is a new implementation of the coarse graining toolbox fstatistics, and will replace this toolbox in the near future.
MercuryCG is a postprocessing tool: it takes an existing data set, consisting of a restart and one or more data and fstat files, and applies the coarse-graining formulation to it. The output is stored in a stat file, which can then be read by gnuplot or Matlab (via the readMercuryCG.m file in Drivers/MercuryCG/) to be visualised.
This document details how to use MercuryCG as a post-processing tool. Note, coarse graining can also be applied during a MercuryDPM simulation, analysing the data while the simulation is still running; to do this, see the CGHandler documentation.
First, we provide the basic syntax, then show some examples. Finally, more complex operations are introduced.
Assume you want to analyse the output files of the Driver's code NewtonsCradleSelfTest, located in the folder Drivers/MercuryCG. To create the file, run the simulation using make SquarePackingSelfTest && ./SquarePackingSelfTest in said folder). The simulation produces two output files that MercuryCG needs: SquarePackingSelfTest.data and SquarePackingSelfTest.fstat. To analyse this data,
Drivers/MercuryCG/ in the build directory,Note: If the data is in another folder than Drivers/MercuryCG/, you have to prepend the file path to the file name. For example, to analyse the output files of LeesEdwardsSelfTest in the folder MercurySimple demos, use the command
With the above arguments, MercuryCG outputs spatially-averaged continuum fields for each time step in the data/fstat files into a file named 'SquarePackingSelfTest.stat`. For a quick check of the output, the spatially-averaged results from the last written timestep are outputted to the screen
Note that MercuryCG returns the momentum instead of the velocity, as momentum has a primary definition as a coarse-grained variable ( \(\vec{j}=\sum_i m_i\vec{v}_i\phi_i\)), while velocity is computed by dividing two "primary" coarse-grained fields (momentum and density, \(\vec{V}=\vec{j}/\rho\)). Generally, MercuryCG only outputs primary coarse-grained variables, as they are well-defined even if no particles are present. The primary fields are also the most relevant for any macroscopic theory based on conservation principles, as they have well-defined averaging properties (they can be thought of as the density of a microscopic quantity). Secondary fields like velocity can be constructed by combining the primary fields. The script readMercuryCG.m reads the primary variables into Matlab and constructs several secondary variables (velocity, kinetic stress, temperature, etc).
The output file consists of a two-line header followed by several lines of data. For the example above, the output is:
The first line outputs a few properties you need to interpret the remaining file output:
CG: the standard CG class was used, which evaluates each time step separately (see also TimeAveragedCG and TimeSmoothedCG)Nu, bulk density Density and the three momentum components MomentumX MomentumY MomentumZ.min 0 0 -0.5 max 5 5 0.5: the spatial domainn 1 1 1: a 1x1x1 mesh of values was used, which is the only option for spatially averaged statistics.width 1: the coarse-graining widthLucy: the type of coarse-graining function (see Gaussian, Lucy, Linear and Heaviside)cutoff 1: the coarse-graining widthThe second line specifies the time/space coordinates and fields computed by MercuryCG and the respective columns.
The remaining lines contains the coordinates and the values of the continuum fields at these coordinates.
MercuryCG can do much more than return global averages of the continuum fields. In particular, it can extract local continuum fields at specific spatial coordinates. The behavior of MercuryCG is controlled via command line arguments; the most commonly used options are discussed in more detail below.
The output file can be modified by adding additional arguments to the command line. E.g. you can use the -timeaverage command:
This tells MercuryCG to time-average. The output file now looks like this:
The coarse-graining formulations can extract local continuum fields, whose value depends on the spatial coordinate. You can extract spatially resolved fields using the arguments -coordinates XYZ -n 2 -timeaverage. This creates a 2x2x2 grid of values over the domain and evaluates the continuum fields at each of those points. Note, the grid is not part of the cg formulation itself: CG returns field values at all points in space; but numerically we can only evaluate the continuum fields at a final number of points. The output file now contains 8 lines of data, one for each z-value:
You can also choose to spatially resolve only specific spatial coordinates and average over the remaining ones. Use the arguments '-coordinates [O,X,Y,Z,XY,XZ,YZ,XYZ]' to modify this behaviour.
By default, the code uses the coarse-graining width 1, and a Lucy coarse-graining function. Use the arguments -function [Gaussian,Lucy,Linear,Heaviside] and -w [double] to change these defaults. For an explanation of what a kernel function is, please see the section on the maths of coarse-graining.
The following command produces z-resolved data using a Lucy kernel with a narrow cutoff radius of 0.5 (one particle radius).
We can now visualise this data using e.g. gnuplot:
The result is a density field with peaks at the particle centre and vanishing at a distance of 0.5 from the particle centre: 
Alternatively, you can visualise the data in Matlab:
You can obtain a full list of command line options by typing the -help command:
1.9.1