### Setup Initial Conditions

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Configures particles and simulation parameters before the solver starts.

```cpp
void setupInitialConditions() override {
	createSpecies();
	//Particle 1
	SphericalParticle p0;
	p0.setSpecies(speciesHandler.getObject(0));
	p0.setPosition(Vec3D(0,0,0));
	p0.setVelocity(Vec3D(0,0,0));
	p0.setRadius(0.5 + 0.1 * studyNum[1]);
	particleHandler.copyAndAddObject(p0);
	//Particle 2
	SphericalParticle p1;
	p1.setSpecies(speciesHandler.getObject(0));
	p1.setPosition(Vec3D(1,0,0));
	p1.setVelocity(Vec3D(0,0,0));
	p1.setRadius(0.5);
	particleHandler.copyAndAddObject(p1);
}
```

--------------------------------

### Copy Example Configuration Files

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/USER/jmft2/Fingering/CMakeLists.txt

Copies example configuration files to the destination directory.

```cmake
#Part 2 : Copy example config file
#########################################
file(COPY exampleMaserFingeringConfigFiles DESTINATION .)
```

--------------------------------

### Main Function: Setup and Tests

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

The main function includes setup parameters and tests for collision time and restitution coefficient. Use Paraview to produce visualizations.

```cpp
int main(int argc, char *argv[]) {
    // Setup parameters
    MerdpmBase
    base.setGravity(Vec3(0.0, 0.0, -9.81));
    base.setDomain(Vec3(0.0, 0.0, 0.0), Vec3(1.0, 1.0, 1.0));
    base.setNumPart(1000);
    base.setBoxSize(Vec3(1.0, 1.0, 1.0));
    base.setParticleDimensions(Vec3(1.0, 1.0, 1.0));
    base.setZMin(0.0);
    base.setZMax(1.0);
    base.setNumSpecies(1);
    base.setSpecies(0,
        [&]() {
            auto species = new DpmBase::Species;
            species->setMass(1.0);
            species->setStiffness(1.0);
            species->setCharge(0.0);
            species->setRadius(0.01);
            species->setDistribution(0.0, 0.01);
            species->setName("dpm");
            return species;
        }());

    // Tests for valid collision time and restitution coefficient
    base.setTimeStep(1e-6);
    base.setTimeMax(10.0);
    base.solve();

    // Note: To produce the pictures as shown, you can use Paraview.
    return 0;
}
```

--------------------------------

### Install qt5 and ncurses

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Install the qt5-default package for Qt5 support and libncurses5-dev, which provides the ccmake command.

```shell
$ sudo apt install qt5-default
$ sudo apt install libncurses5-dev (ccmake command will also be created)
```

--------------------------------

### Download, build, and install cmake

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Download the desired CMake version, extract it, configure the build with Qt GUI and system curl support, compile, and install. Restart bash afterwards.

```shell
$ wget https://cmake.org/files/v3.10/cmake-3.10.0.tar.gz #Download cmake: https://cmake.org/download
$ tar xf cmake-3.10.0.tar.gz
$ cd cmake-3.10.0
$ ./bootstrap --qt-gui --system-curl && make && sudo make install
$ bash # restart bash such that it doesn't look for cmake in the old location
```

--------------------------------

### Install git and pkg-config

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Install git for version control and pkg-config, which is needed to help the build system find libraries for Paraview.

```shell
$ sudo apt install git pkg-config #needed to make ParaView
```

--------------------------------

### Install Python dependencies

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/PreCICE/README.md

Install the required Python bindings for preCICE using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Setup Gravity in Tutorial 2

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Snippet for configuring gravity in the negative z-direction.

```cpp
snippet Drivers/Tutorials/Tutorial2_ParticleUnderGravity.cpp T2:problemSetup
```

--------------------------------

### Add preCICE Example Test Cases

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/PreCICE/CMakeLists.txt

Defines test cases for preCICE examples, including setup, execution, and verification steps. It configures test properties like working directory and environment variables.

```cmake
set(_examples rayleigh-kothe)
foreach(example IN LISTS _examples)
  add_test(NAME precice.example.${example}.setup
    COMMAND clean.sh
    FIXTURE_SETUP ${example})
  add_test(NAME precice.example.${example}
    COMMAND run.sh
    FIXTURE_REQUIRES ${example})
  add_test(NAME precice.example.${example}.verify
           COMMAND ${CMAKE_COMMAND}
                   -DEXPECTED_GLOB=*.vtu
                   -P ${CMAKE_SOURCE_DIR}/CMakeModules/VerifyFileExists.cmake
           FIXTURE_REQUIRES ${example})
  set_tests_properties(precice.example.${example}.verify
                       PROPERTIES DEPENDS precice.example.${example})

  if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.22)
    set_tests_properties(precice.example.${example} precice.example.${example}.setup precice.example.${example}.verify
      PROPERTIES
      WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/Drivers/PreCICE"
      ENVIRONMENT_MODIFICATION "PATH=path_list_append:${CMAKE_BINARY_DIR}/Drivers/PreCICE"
      LABELS example
      RUN_SERIAL ON
      TIMEOUT 300)
  else()
    set_tests_properties(precice.example.${example} precice.example.${example}.setup precice.example.${example}.verify PROPERTIES
        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/Drivers/PreCICE"
        ENVIRONMENT       "PATH=${CMAKE_BINARY_DIR}/Drivers/PreCICE${_path_sep}$ENV{PATH}"
        LABELS            example
        RUN_SERIAL        ON
        TIMEOUT           300)
  endif()
endforeach()
```

--------------------------------

### Install ParaView on Ubuntu

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Analysing.dox

Use this command to install ParaView on Ubuntu systems. Ensure you have the necessary permissions.

```bash
sudo apt-get install paraview
```

--------------------------------

### Download, build, and install curl

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Download the curl source code, extract it, configure the build with SSL support, compile, and install it. This ensures you have a compatible version of curl.

```shell
$ wget https://curl.haxx.se/download/curl-7.56.1.tar.bz2
$ tar xf curl-7.56.1.tar.bz2
$ cd curl-7.56.1
$ ./configure --with--ssl && make && sudo make install
$ cd .. # you can now remove the folder curl-7.56.1
$ curl --version # check curl is installed
```

--------------------------------

### Example Output Format

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/CG.dox

Example of the output file structure when time-averaging is disabled.

```text
VolumeFraction Density MomentumX MomentumY MomentumZ ...
w 0.5 ...
0
0.5 0.5 2.5 0.5235987755982988 0.9999999999999978 0 0 0 ...
0.1
0.5 0.5 2.5 0.5235987755982988 0.9999999999999978 0 0 -0.00443464845260919 ...
0.2
0.5 0.5 2.5 0.5235987755982988 0.9999999999999978 0 0 -0.0002324913042918475 ...
...
```

--------------------------------

### Accessing MercuryCG help and usage

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/CG.dox

Display command line options and usage examples.

```bash
./MercuryCG -help
```

```bash
./MercuryCG name -coordinates O
```

```bash
./MercuryCG name -coordinates XYZ -n 10
```

--------------------------------

### Install necessary packages for curl

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Install zlib1g, zlib1g-dev, and libssl-dev, which are required for building and installing curl with SSL support.

```shell
$ sudo apt install zlib1g zlib1g-dev libssl-dev
```

--------------------------------

### Install gcc-6

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

If your system's GCC version is older than 6, you need to install gcc-6. This involves adding a specific PPA and then installing the package.

```shell
$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo apt install gcc-6
```

--------------------------------

### Install Ansible

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Deployment/README.md

Installs the required Ansible version. Ensure you have pip available.

```bash
  $ pip install ansible>=6.3.0
```

--------------------------------

### Install Doxygen on Ubuntu

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/DoxygenDocumentationForDummies.dox

Use this command in a terminal to install the Doxygen package.

```bash
sudo apt-get install doxygen
```

--------------------------------

### Example Stat-File Output

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/CG.dox

This is an example of the output generated in a stat-file by the TutorialCG0.cpp example. It shows spatially averaged statistics, including time, volume fraction, density, momentum, momentum flux, contact stress, and interaction force density.

```text
::::::::::::::
TutorialCG0.0.stat
::::::::::::::
CG n 1 1 1 width 1 timeMin 0.1601 min 0 0 0 max 9.92738 9.92738 9.92738 Lucy cutoff 1
time 2:volumeFraction 3:density 4-6:momentum 7-12:momentumFlux 13-21:contactStress 22-24:interactionForceDensity
0.1601 0.535174 1.02211 3.11529e-17 6.62723e-17 -1.38841e-17 0.000348305 9.52371e-06 -6.18274e-06 0.000314944 -1.0499
```

--------------------------------

### Setup initial conditions for 3D study

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Configure particle properties for the initial state of the simulation.

```cpp
\snippet Drivers/MercurySimpleDemos/ParameterStudy3DDemo.cpp PAR_SIM3D:setupInit
```

--------------------------------

### Configure Output and General Specifications

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Creating.dox

Set the simulation name and file output type. Gravity is set to zero for this example.

```cpp
setName("PingPong")
setFileType(FileType::ONE_FILE);
setGravity(Vec3D(0.0, 0.0,0.0));

```

--------------------------------

### Build and install Paraview superbuild

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Compile the Paraview superbuild using make. You can use the -j flag to speed up the build process by utilizing multiple cores. Then, install it.

```shell
$ make && sudo make install #or make -j4 && sudo make install
```

--------------------------------

### Calibration Output Example

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/Calibration/README.md

This output shows the configuration and progress of a calibration run. It details the parameters being identified, their ranges, the experimental data, and the commands used to build and run simulations. Pay attention to the output directory and file creation messages.

```text
Running on 40 core(s) on node(s) 01
Material: MaterialA
Parameters to be identified: restitutionCoefficient, slidingFriction, rollingFriction, relativeCohesionStiffness
Parameter ranges: [0.2, 1.0], [0.0, 1.0], [0.0, 1.0], [0.0, 2.0]
Executables: ShearCellBu
Data values: [770.0, 532.0, 327.0]
Weights: [1.0, 1.0, 1.0]
Command line parameters: -speciesType MaterialA -restitutionCoefficient %s -slidingFriction %s -rollingFriction %s -relativeCohesionStiffness %s -normalStress 1027 827 527 226
Build directory for executables: Drivers/Calibration
Covariance: 1
Goal for effective sample size: 0.500000
Number of Gaussian components: 2
Number of samples: 40
Prior weight: 0.500000

Creating smcTable_MaterialA_0.txt.
Output will be written to MaterialA/Sim0/.
Preparing simulations. After simulations have finished, rerun this script to continue.
Running make in the build directory /storage1/usr/people/weinhartt/Code/Lab/build/Drivers/USER/MercuryLab/Butterball/Calibration
Number of commands 40, per script 2, number of scripts: 20
Adjusting script for msm3
1) cd '/storage1/usr/people/weinhartt/Code/Lab/Drivers/USER/MercuryLab/Butterball/Calibration/py/MaterialA/Sim0/'
2) Adjust node numbers run.sh.
3) Execute 'source ./run.sh'
   Runs started. Rerun this script for analysis.

```

--------------------------------

### Chute Initial Conditions Setup

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Internal implementation of the Chute class for setting up boundaries and particle insertion.

```cpp
void Chute::setupInitialConditions() {
  if (speciesHandler.getNumberOfObjects() == 0) {
    logger(ERROR, "Chute::setupInitialConditions: No species defined");
  }
  setSideWalls();
  SphericalParticle p(speciesHandler.getObject(0));
  ChuteInsertionBoundary* b = boundaryHandler.copyAndAddObject(ChuteInsertionBoundary());
  b->set(&p, 0, Vec3D(getXMin(), getYMin(), getZMin()), Vec3D(getXMax(), getYMax(), getZMax()), minInflowParticleRadius_, maxInflowParticleRadius_, fixedParticleRadius_, inflowVelocity_, inflowVelocityVariance_);
  setRoughBottom();
}
```

--------------------------------

### Setup Initial Conditions for 2D Study

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Configuration of particle properties dependent on the second parameter dimension.

```cpp
\snippet Drivers/MercurySimpleDemos/ParameterStudy2DDemo.cpp PAR_SIM2D:setupInit
```

--------------------------------

### Xb2 Script Call Example

Source: https://github.com/mercurydpm/mercurydpm/blob/master/XBalls/xballs.txt

This shows how to call the Xb2 script with a data file and other options. Xb2 visualizes spheres in an X-window with four subwindows.

```bash
Xb2 -f datafile [-other options]
```

--------------------------------

### Setup Initial Conditions for Axisymmetric Walls

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Overrides the setupInitialConditions function to define walls, particle species, and initial particle distribution.

```cpp
void setupInitialConditions(double time) override {
    // Add cylinder and prism walls
    wallHandler.copy(cylinder);
    wallHandler.copy(prism);
    wallHandler.copy(flatSurface);

    // Add particle species
    Species* species = new Species;
    species->setMass(1.0);
    species->setRadius(0.01, 0.02);
    species->setDistribution(0.01, 0.02, 3);
    species->setStochasticNormalComponent(0.0);
    particleHandler.setSpecies(species, 0);

    // Distribute particles randomly
    particleHandler.distributeInitial(0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
}
```

--------------------------------

### Execute simulation components

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/PreCICE/README.md

Commands to manually start the Python participant and the MercuryDPM participant.

```bash
python3 rayleigh-kothe-function.py
```

```bash
RayleighKothe
```

--------------------------------

### Specify Grid Domain and Resolution

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/MercuryCG/MercuryCG.txt

This example demonstrates how to specify the domain and number of elements for the spatial grid. Fields are evaluated at the midpoints of each element.

```bash
# For example, for '-x 0 10 -nx 5', the cg fields will be evaluated at x=1,3,5,7,9.
```

--------------------------------

### SolidBeamDemo.cpp Example

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/OomphCoupling.dox

This C++ driver code demonstrates running uncoupled oomph-lib simulations within MercuryDPM. It includes the #SolidProblem class for elastic body simulations and uses a steady-state solver.

```cpp
#include "SolidProblem.h"
#include "RefineableQDPVDElement.h"

int main(int argc, char *argv[]) {
  SolidProblem<RefineableQDPVDElement<3,2>> problem(argc, argv);
  problem.solveSteady();
  return 0;
}
```

--------------------------------

### Execute fstatistics on a Demo Dataset

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Analysing.dox

Example command for running fstatistics against a specific simulation output directory.

```bash
~/MercuryDPM/MercuryBuild/Drivers/MercuryCG/fstatistics Drivers/ChuteDemos/ChuteDemo
```

--------------------------------

### Define Simulation Class and Setup

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Derive a custom class from Mercury3D and override setupInitialConditions to define particle properties.

```cpp
class Tutorial1 : public Mercury3D
```

```cpp
void setupInitialConditions() override
```

```cpp
SphericalParticle p0;
p0.setRadius(0.01);
p0.setPosition(Vec3D(0.1, 0.1, 0.1));
p0.setVelocity(Vec3D(0.1, 0.0, 0.0));
particleHandler.copyAndAddObject(p0);
```

--------------------------------

### Launch ParaView

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Analysing.dox

Start the ParaView application from the terminal. This command assumes ParaView is in your system's PATH.

```bash
paraview
```

--------------------------------

### Implementing Restart-Ready DPMBase Driver

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Restart.dox

Example of a class inheriting from DPMBase that includes the actionsOnRestart override and uses solve(argc, argv) in the main function.

```cpp
#include "DPMBase.h"
#include "Walls/InfiniteWall.h"
#include "Species/LinearViscoelasticSpecies.h"

class FreeFall : public DPMBase{
public:

    // Set species, particles, boundaries, walls here
    void setupInitialConditions() override
	{
        LinearViscoelasticSpecies s;
        s.setStiffness(1e5);
        s.setDissipation(0.01);
        s.setDensity(2e3);
        auto sp = speciesHandler.copyAndAddObject(s);

        InfiniteWall w0;
        w0.setSpecies(speciesHandler.getObject(0));
        w0.set(Vec3D(0,0,-1), Vec3D(0, 0, 0));
		wallHandler.copyAndAddObject(w0);

		SphericalParticle p0;
        p0.setSpecies(speciesHandler.getObject(0));
		p0.setPosition(Vec3D(0,0,getZMax()-1e-3));
		p0.setRadius(1e-3);
		particleHandler.copyAndAddObject(p0);
    }

    //this function replaces setupInitialConditions in case of a restart
    //if you have problem-specific variables, set them here
    void actionsOnRestart() override
    {
    }

};

int main(int argc, char *argv[])
{
	//Start off my solving the default problem
	FreeFall dpm;

    //set FreeFall-specific parameters here
    dpm.setName("FreeFallRestart");
    dpm.setSaveCount(1000);
    dpm.setTimeStep(1e-6);
    dpm.setTimeMax(0.5);
    dpm.setDomain(Vec3D(-1e-3,-1e-3,0e-3),Vec3D(1e-3,1e-3,10e-3));
    dpm.setGravity(Vec3D(0,0,-9.8));

    //restart and run until final time 1, using command line arguments:
    // ./freeFallRestart -r -tmax 1
    dpm.solve(argc,argv);
    return 0;
}
```

--------------------------------

### Setup Periodic Boundaries in X-direction

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

This C++ snippet demonstrates how to set up periodic boundaries in the X-direction using the PeriodicBoundary class. An instance 'b0' is created and added to the BoundaryHandler.

```cpp
auto b0 = BoundaryHandler.Boundary.
            create("Periodic");
            b0->set(Vec3D(1.0,0.0,0.0), 0.0, 1.0);
            BoundaryHandler.Boundary.copyAndAdd(b0);

```

--------------------------------

### Run ParaView for Tutorial 1

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Command to visualize the output of the first tutorial using ParaView.

```bash
paraview --script=Tutorial1.py   # re-plot
```

--------------------------------

### Compile and Run Tutorial 2

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Commands to compile and execute the particle under gravity simulation.

```bash
cd ~/MercuryDPM/MercuryBuild/Drivers/Tutorials/
make                             # compile
./Tutorial2_ParticleUnderGravity # run
```

--------------------------------

### CoupledBeamDemo.cpp Example

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/OomphCoupling.dox

This C++ driver code demonstrates surface coupling between MercuryDPM and oomph-lib. It utilizes the #SCoupledSolidProblem class, derived from #SolidProblem, to solve coupled elastic body simulations.

```cpp
#include "SCoupledSolidProblem.h"
#include "RefineableQDPVDElement.h"

int main(int argc, char *argv[]) {
  SCoupledSolidProblem<RefineableQDPVDElement<3,2>> problem(argc, argv);
  problem.solveSteady();
  return 0;
}
```

--------------------------------

### Load Restart and Data Files

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Demonstrates how to create, write, and read restart and data files for resuming simulations.

```cpp
writeRestartFile("restart.rst");
writeDataFile("data.data");
readRestartFile("restart.rst");
readDataFile("data.data");
```

--------------------------------

### Initialize 1D Parameter Study

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Entry point for the 1D parameter study demonstration.

```cpp
\snippet Drivers/MercurySimpleDemos/ParameterStudy1DDemo.cpp PAR_SIM1D:main
```

--------------------------------

### Initialize Problem and Parameters

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Instantiate the simulation class and configure global parameters, species properties, and output settings.

```cpp
Tutorial1 problem;
```

```cpp
problem.setName("Tutorial1");
problem.setGravity(Vec3D(0, 0, 0));
problem.setTimeMax(1.0);
problem.setSystemDimensions(3);
problem.setXMinMax(0, 0.2);
problem.setYMinMax(0, 0.2);
problem.setZMinMax(0, 0.2);
```

```cpp
LinearViscoelasticSpecies species;
species.setDensity(2000);
species.setStiffness(1000);
problem.speciesHandler.copyAndAddObject(species);
```

```cpp
problem.setSaveCount(100);
problem.dataFile.setFileType(FileType::ONE_FILE);
problem.restartFile.setFileType(FileType::ONE_FILE);
problem.fStatFile.setFileType(FileType::ONE_FILE);
```

```cpp
problem.writeVTKFiles(true);
```

```cpp
problem.solve();
```

--------------------------------

### Access fstatistics Help Documentation

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Analysing.dox

Run the executable with the -help flag to view available command-line options.

```bash
./fstatistics -help
```

--------------------------------

### Example Data for Format 8

Source: https://github.com/mercurydpm/mercurydpm/blob/master/XBalls/xballs.txt

This is an example data block for format 8, which includes particle coordinates, velocities, radius, and other information.

```plaintext
 3  .12900      .00000E+00  .00000E+00  .20200E-01  1.0000
 .50335E-03 .50175E-03 .47702E-01 -.30767E-01 .5E-03  5.8478 .0  1
 .15089E-02 .50100E-03 .20248E-01 -.72583E-02 .5E-03 -.27826 .0  2
 .25207E-02 .50170E-03 -.39642E-01 .22503E-02 .5E-03 -2.0506 .0  3
```

--------------------------------

### Generate HTML Documentation

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/DoxygenDocumentationForDummies.dox

Execute this command in the build directory to compile the documentation into HTML format.

```bash
make doc
```

--------------------------------

### fstatistics Output Example

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/CG.dox

Example output from fstatistics showing time- and space-averaged continuum fields like VolumeFraction, Density, and Momentum.

```text
Averages: VolumeFraction 0.523599, Density 1, Momentum 0 0 -4.96752e-05, ...
```

--------------------------------

### Remove cmake and curl

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Before installing a newer version of CMake, remove existing installations of cmake, cmake-curses-gui, cmake-qt-gui, and curl. This prevents conflicts.

```shell
$ sudo apt remove cmake curl
```

--------------------------------

### Main Function for 2D Demo

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Entry point to instantiate and solve the simulation.

```cpp
int main() {
    FreeCooling2DinWallsDemo problem;
    problem.setN(100);
    problem.setBoxWidth(1.0);
    problem.setTimeStep(1e-4);
    problem.setTimeMax(1.0);
    problem.setSaveCount(100);
    problem.solve();
    return 0;
}
```

--------------------------------

### Spatially-Resolved Output Format

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/CG.dox

Example of the output file structure for z-resolved data.

```text
VolumeFraction Density MomentumX MomentumY MomentumZ ...
w 0.5 ...
0 8
0.5 0.5 0.025 0.2722069474489637 0.5198769747655011 0 0 -1.065287345058795e-05 ...
0.5 0.5 0.075 0.2991469265707014 0.5713285448937040 0 0 -1.175249212167385e-05 ...
0.5 0.5 0.125 0.3257896653109658 0.6222124277099292 0 0 -1.285889210570773e-05 ...
...
```

--------------------------------

### Configure Include Directories and Build Executables

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/USER/Kit/3dVibeCodes/CMakeLists.txt

Sets up include paths and iterates over .cpp files to create and link executables.

```cmake
include_directories(${MercuryDPM_SOURCE_DIR}/Kernel
	                    ${MercuryDPM_BINARY_DIR}/Kernel)

#Part 1 : All cpp files will be made to exec files
#########################################
#Collect all the names of the cpp, note at the moment limited to demos, but will be fixed later
file(GLOB CPPFILES  "*.cpp")
#for every cpp found
foreach(CPPFILE ${CPPFILES})
	#extract the actually file name
	get_filename_component(FILENAME ${CPPFILE} NAME)
	#extract the filename minus the cpp. This will be the name of exe file
	get_filename_component(EXECNAME ${CPPFILE} NAME_WE)
	#Make the exe
	add_executable(${EXECNAME} ${FILENAME})
	#All cpp folder and linked against DPMBase
	target_link_libraries(${EXECNAME}  MercuryBase)
endforeach()
```

--------------------------------

### xml_attribute::next_attribute

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/SerializedDriver/cereal/external/rapidxml/manual.html

Gets the next attribute, optionally matching a specific name.

```APIDOC
## function xml_attribute::next_attribute

### Synopsis
`xml_attribute<Ch>* next_attribute(const Ch *name=0, std::size_t name_size=0, bool case_sensitive=true) const;`

### Description
Gets next attribute, optionally matching attribute name.

### Parameters

name
Name of attribute to find, or 0 to return next attribute regardless of its name; this string doesn't have to be zero-terminated if name_size is non-zero

name_size
Size of name, in characters, or 0 to have size calculated automatically from string

case_sensitive
Should name comparison be case-sensitive; non case-sensitive comparison works properly only for ASCII characters

### Returns
Pointer to found attribute, or 0 if not found.
```

--------------------------------

### Include Headers for 2D Walls Demo

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Required headers for the FreeCooling2DinWallsDemo simulation.

```cpp
#include "Mercury2D.h"
#include "Species/LinearViscoelasticSpecies.h"
#include "Walls/InfiniteWall.h"
```

--------------------------------

### Include Headers for Tutorial 3

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Snippet for including necessary headers in the bouncing ball simulation.

```cpp
snippet Drivers/Tutorials/Tutorial3_BouncingBallElastic.cpp T3:headers
```

--------------------------------

### xml_attribute::previous_attribute

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/SerializedDriver/cereal/external/rapidxml/manual.html

Gets the previous attribute, optionally matching a specific name.

```APIDOC
## function xml_attribute::previous_attribute

### Synopsis
`xml_attribute<Ch>* previous_attribute(const Ch *name=0, std::size_t name_size=0, bool case_sensitive=true) const;`

### Description
Gets previous attribute, optionally matching attribute name.

### Parameters

name
Name of attribute to find, or 0 to return previous attribute regardless of its name; this string doesn't have to be zero-terminated if name_size is non-zero

name_size
Size of name, in characters, or 0 to have size calculated automatically from string

case_sensitive
Should name comparison be case-sensitive; non case-sensitive comparison works properly only for ASCII characters

### Returns
Pointer to found attribute, or 0 if not found.
```

--------------------------------

### Get Parse Error Description

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/SerializedDriver/cereal/external/rapidxml/manual.html

Retrieves the human-readable description of the parse error.

```cpp
virtual const char* what() const;
```

--------------------------------

### Main Function Execution

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Initializes the simulation object, sets parameters, and executes the solver.

```cpp
int main() {
    FreeCooling3DinWallsDemo problem;
    problem.setNParticles(100);
    problem.setBoxWidth(10.0);
    problem.setTimeStep(0.001);
    problem.setTimeMax(10.0);
    problem.solve();
    return 0;
}
```

--------------------------------

### Open Documentation in Browser

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/DoxygenDocumentationForDummies.dox

View the generated documentation by opening the index file in a web browser.

```bash
[YOUR_WEB_BROWSER] index.html
```

--------------------------------

### Visualizing MercuryCG data

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/CG.dox

Examples for generating and visualizing data using gnuplot and Matlab.

```bash
./MercuryCG SquarePacking -coordinates Z -n 100 -function Lucy -w 0.5
```

```gnuplot
gnuplot> p 'SquarePackingSelfTest.stat' u 2:4 w l
gnuplot> p 'SquarePackingSelfTest.stat' u 2:4 w l
gnuplot> p 'SquarePackingSelfTest.stat' u 2:4 w l
```

```matlab
$ data = readMercuryCG('SquarePackingSelfTest.stat')
$ plot(data.z,data.Density)
```

--------------------------------

### Set Up Initial Conditions for Simple Shear

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Sets up system dimensions, timestepping, gravity, and inserts particles using CubeInsertionBoundary. Configures StressStrainControlBoundary and periodic boundaries.

```cpp
setSystemDimensions(3);
setTimeStep(1.0e-6);
setGravity({0.0, 0.0, 0.0});

CubeInsertionBoundary cube;
cube.set(Vec3(0.0, 0.0, 0.0), Vec3(0.5, 0.5, 0.5), 96);
addBoundary(&cube);

StressStrainControlBoundary b
b.set(targetStress_, strainRate_, gainFactor_, isStrainRateControlled_);
addBoundary(&b);

setXMinPeriodic(true);
setYMinPeriodic(true);
setZMinPeriodic(true);
```

--------------------------------

### Read/Set Interactions

Source: https://github.com/mercurydpm/mercurydpm/blob/master/releaseNotes1.0.0.Alpha.md

Get or set the read interactions flag. Methods available in DPMBase.

```cpp
getReadInteractions()
```

```cpp
setReadInteractions()
```

--------------------------------

### Get Diagonal Matrix Elements

Source: https://github.com/mercurydpm/mercurydpm/blob/master/releaseNotes1.0.0.Alpha.md

Extracts the diagonal elements of a matrix. Added to Kernel/Math/Matrix.

```cpp
diag
```

--------------------------------

### xml_base::name_size

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/SerializedDriver/cereal/external/rapidxml/manual.html

Gets the size of the node's name in characters, excluding any terminator.

```APIDOC
## function xml_base::name_size

### Synopsis
`std::size_t name_size() const;`

### Description
Gets size of node name, not including terminator character. This function works correctly irrespective of whether name is or is not zero terminated.

### Returns
Size of node name, in characters.
```

--------------------------------

### Set Up Initial Conditions for Pure Shear

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Sets up system dimensions, timestepping, gravity, and inserts particles using CubeInsertionBoundary. It then configures the StressStrainControlBoundary with user inputs and sets periodic boundaries.

```cpp
const int n = 96;
const Real cubeVolume = 1.0;
const Real maxValue = pow(n / (4.0 * PI / 3.0) * cubeVolume, 1.0/3.0);

setSystemDimensions(FiniteBox3D(-maxValue, maxValue, -maxValue, maxValue, -maxValue, maxValue));
setTimeStep(1e-4);
setGravity(Vec3(0.0, 0.0, 0.0));

CubeInsertionBoundary b; 
b.set(Vec3(0.0), Vec3(1.0), n);
insertBoundaryParticles(b);

StressStrainControlBoundary sb;
const Real targetStress[3][3] = {{0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}};
const Real strainRate[3][3] = {{0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}};
const Real gainFactor[3][3] = {{0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}};
const bool isStrainRateControlled = true;

sb.set(targetStress, strainRate, gainFactor, isStrainRateControlled);
addBoundary(sb);

setBoundary(1, PeriodicBoundary());
setBoundary(2, PeriodicBoundary());
setBoundary(3, PeriodicBoundary());

```

--------------------------------

### Configure MercuryDPM for OpenMP

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/Papers/OSBenchmark/README.md

Use this cmake flag during installation to enable OpenMP parallelization for benchmarking.

```bash
-DMERCURYDPM_USE_OpenMP=ON
```

--------------------------------

### Define Doxygen Page Metadata

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/DoxygenDocumentationForDummies.dox

The required syntax for starting a new documentation page file.

```text
\page [KEYWORD] [TITLE]
```

--------------------------------

### Configure Walls for 2D Demo

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Sets up the four infinite walls defining the 2D simulation box.

```cpp
wallHandler.clear();
wallHandler.copyAndAddWall(InfiniteWall(Vec3D(-1, 0, 0), Vec3D(-boxWidth, 0, 0), species));
wallHandler.copyAndAddWall(InfiniteWall(Vec3D(1, 0, 0), Vec3D(boxWidth, 0, 0), species));
wallHandler.copyAndAddWall(InfiniteWall(Vec3D(0, -1, 0), Vec3D(0, -boxWidth, 0), species));
wallHandler.copyAndAddWall(InfiniteWall(Vec3D(0, 1, 0), Vec3D(0, boxWidth, 0), species));
```

--------------------------------

### Create Particle in Tutorial 2

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Snippet for defining the particle in the Tutorial 2 simulation.

```cpp
snippet Drivers/Tutorials/Tutorial2_ParticleUnderGravity.cpp T2:createParticle
```

--------------------------------

### Implement set and get functions for 3D study

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Extend accessors to incorporate the third dimension.

```cpp
\snippet Drivers/MercurySimpleDemos/ParameterStudy3DDemo.cpp PAR_SIM3D:setgetFunc
```

--------------------------------

### Implement Set and Get Functions

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Provides access to private member variables for public functions.

```cpp
void setStudyNum(std::vector<int> studyNum) {this->studyNum = studyNum;}
std::vector<int> getStudyNum() {return studyNum;}
void setDim1(int dim1) {dim1_ = dim1;}
int getDim1() {return dim1_;}
```

--------------------------------

### Configure Include Directories

Source: https://github.com/mercurydpm/mercurydpm/blob/master/CMakeModules/oomph/demo_drivers/solid/CMakeLists.txt

Sets up include paths for source and external directories by scanning the OOMPH_DIR structure.

```cmake
FILE(GLOB ALL_FILES ${OOMPH_DIR}/src/*)
FOREACH(DIR ${ALL_FILES})
	IF(EXISTS "${DIR}/CMakeLists.txt")
		include_directories(${DIR})
	ENDIF()
ENDFOREACH()
include_directories(${OOMPH_DIR}/src/)
include_directories(${OOMPH_DIR}/external_src/)
```

--------------------------------

### Load Configuration File

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/USER/jmft2/Fingering/Summary.html

Loads the Exp.config file when the document is ready. Ensure Exp.config exists in the same directory or provide a correct path.

```javascript
$(document).ready(function(){ $("#config_txt").load("Exp.config") });
```

--------------------------------

### Get Momentum and Angular Momentum

Source: https://github.com/mercurydpm/mercurydpm/blob/master/releaseNotes1.0.0.Alpha.md

Retrieve the total momentum and angular momentum of particles. Added to DPMBase.

```cpp
DPMBase::getMomentum()
```

```cpp
DPMBase::getAngularMomentum()
```

--------------------------------

### Provision Workers

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Deployment/README.md

Provisions worker instances by installing dependencies, setting up directories, cloning the repository, and building MercuryBase.

```bash
  $ ansible-playbook -i hosts --private-key=$KEY provision.yml
```

--------------------------------

### Include Headers for 3D Demo

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Required headers for the 3D free cooling simulation.

```cpp
#include <Mercury3D.h>
#include <Species/LinearViscoelasticSpecies.h>
#include <Walls/InfiniteWall.h>
```

--------------------------------

### View Spatial Averages Output

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/CG.dox

Example of the terminal output showing spatially-averaged results for the last written timestep.

```text
Spatial averages: VolumeFraction 0.785398 Density 1 Momentum 0 -5.6968e-07 0 ...
```

--------------------------------

### Include Headers for Simple Shear Demo

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Includes the necessary headers for the REVSimpleShearDemo.cpp file, which are standard for other REV tutorials.

```cpp
#include "Mercury3D.h"
#include "Boundaries/CubeInsertionBoundary.h"
#include "Boundaries/StressStrainControlBoundary.h"
#include "Species/RoughSphere.h"

```

--------------------------------

### Run Driver with Custom Repository and Version

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Deployment/README.md

Allows specifying a custom repository and version when running a driver simulation. Defaults to building from the HEAD of the trunk.

```bash
  $ ansible-playbook -i hosts --private-key=$KEY runjob.yml \
        -e repository="https://bitbucket.org/you/your_fork.git" \
        -e version="fe5264c"
```

--------------------------------

### Get Parse Error Location

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Drivers/SerializedDriver/cereal/external/rapidxml/manual.html

Retrieves a pointer to the character data within the source text where the error occurred.

```cpp
Ch* where() const;
```

--------------------------------

### Visualize Tutorial 2 in ParaView

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Command to visualize the particle falling under gravity.

```bash
paraview --script=Tutorial2.py
```

--------------------------------

### Formatted Logger Output Example

Source: https://github.com/mercurydpm/mercurydpm/blob/master/releaseNotes1.0.0.Alpha.md

Use the logger function with formatting specifiers for width and precision. By default, output is left-aligned.

```cpp
logger(INFO, "%10.12", normalForce)
```

--------------------------------

### Re-run Tutorial 2 with Modifications

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Commands to edit, recompile, and re-plot the simulation after modifying the source code.

```bash
vi ~/MercuryDPM/MercurySource/Drivers/Tutorials/Tutorial2_ParticleUnderGravity.cpp #edit the source file
rm Tutorial2*.*                  # remove old output files
make                             # re-compile
./Tutorial2_ParticleUnderGravity # re-run
paraview --script=Tutorial2.py   # re-plot
```

--------------------------------

### Create and Stage a New User Driver Directory

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/DevelopersGuide.dox

Set up a new directory for custom MercuryDPM drivers. This involves copying a template, staging it with git, and then entering the new directory.

```bash
MercurySource/Drivers/USER$ cp Template Marlin  # There is a template folder with a TemplateDriver.cpp, CMakeLists.txt files and a Scripts folder with a README file
git add Marlin  # This command stages the new folder Marlin and all the files within it for commit.
```

--------------------------------

### Time Measurement for Simulations

Source: https://github.com/mercurydpm/mercurydpm/blob/master/releaseNotes1.0.0.Alpha.md

Measures simulation time using clock_.tic() to start and clock_toc() to end the measurement. Integrated into DPMBase.

```cpp
clock_.tic()
```

```cpp
clock_toc()
```

--------------------------------

### Implement Set and Get Functions for 2D Study

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Accessor methods updated to handle the second dimension of the parameter space.

```cpp
\snippet Drivers/MercurySimpleDemos/ParameterStudy2DDemo.cpp PAR_SIM2D:setgetFunc
```

--------------------------------

### Main Function for Isotropic Compression

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Entry point defining tensors, initializing the StressStrainControl object, and executing the solve method.

```cpp
REV_ISO:main
```

--------------------------------

### Get Momentum and Angular Momentum for BaseParticle

Source: https://github.com/mercurydpm/mercurydpm/blob/master/releaseNotes1.0.0.Alpha.md

Automates the computation of momentum and angular momentum for BaseParticle objects. Added to Kernel/Particles/BaseParticle.

```cpp
BaseParticle::getMomentum()
```

```cpp
BaseParticle::getAngularMomentum()
```

--------------------------------

### Tutorial 12: PrismWalls constructor (C++)

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Tutorials.dox

Constructor for the PrismWalls class in Tutorial 12. This sets up the simulation environment for prismatic walls.

```cpp
void Tutorial12_PrismWalls::setupInitialConditions(double t, ParticleGeneratorShape* pg)
{
	setGravity(Vec3(0.0,0.0,0.0));
	//addParticle(Vec3(0.0,0.0,0.0),0.01);
	pg->generateParticles(this);
	setSpecies(0.001,1.0,0.0);
	setInteractionRestitution(0.5);
	setTimeMax(10.0);
	setSaveCount(100);
	setName("PrismWalls");
	setXMax(1.0);
	setYMax(1.0);
	setZMax(1.0);
	setBoundary(1,-1.0,1.0);
	setBoundary(2,-1.0,1.0);
	setBoundary(3,-1.0,1.0);
	std::vector<Vec3> points;
	points.push_back(Vec3(0.5,0.0,0.0));
	points.push_back(Vec3(0.0,0.5,0.0));
	points.push_back(Vec3(-0.5,0.0,0.0));
	points.push_back(Vec3(0.0,-0.5,0.0));
	wallHandler.addPrismaticWalls(points,0.0,1.0);
}
```

--------------------------------

### Build ChuteDemo

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/Analysing.dox

If the ChuteDemo does not run, it may need to be built first. Use this command to compile the demo.

```bash
make ChuteDemo
```

--------------------------------

### Extract Directory Name in CMake

Source: https://github.com/mercurydpm/mercurydpm/blob/master/CMakeModules/oomph/src/solid/CMakeLists.txt

Use this command to get the name of the current directory, which is often used for naming libraries or headers.

```cmake
get_filename_component(dir ${CMAKE_CURRENT_SOURCE_DIR} NAME)
```

--------------------------------

### Configure Paraview superbuild with CMake

Source: https://github.com/mercurydpm/mercurydpm/blob/master/Documentation/Pages/ParaviewSuperbuild.dox

Create a build directory, navigate into it, and use CMake to configure the superbuild. Enable Qt5 and Python support. Use cmake-gui for debugging if errors occur.

```shell
$ mkdir Build
$ cd Build
$ cmake ../Source -DENABLE_qt5=TRUE ../Source -DENABLE_qt5=TRUE -DENABLE_python=TRUE # use cmake-gui to debug if you encounter errors
```

--------------------------------

### Set/Get Initial Volume and Flow Rate

Source: https://github.com/mercurydpm/mercurydpm/blob/master/releaseNotes1.0.0.Alpha.md

Set and get the initial volume and constant volume flow rate for particle insertion. Methods in Kernel/Boundaries/InsertionBoundary.

```cpp
setInitialVolume(Mdouble initialVolume)
```

```cpp
getInitialVolume()
```

```cpp
setVolumeFlowRate_(Mdouble volumeFlowRate)
```

```cpp
getVolumeFlowRate_()
```