MolSim Group F

The molecular dynamics SS24 code base of Group F.
This is a Particle Simulation program, which outputs data to be then visualized using ParaView.
You can find the doxygen documentation hosted on https://noahpy.github.io/MolSim-SS24/.
You can find a playlist of our simulations on Youtube.

Group members

Quickstart

Build instructions

To build the project, run the following commands:

mkdir build && cd build
cmake ..
make

To build without doxygen and benchmarks run

cmake .. -DGENERATE_DOC=OFF  -DBUILD_BENCH=OFF

instead.

Run instructions

To run the project (in general), run the following command:

src/MolSim ../input/<input_file> <program Arguments>

The program arguments can be specified as follows

-d, --delta_t=VALUE    Set the time step (default: 0.014)
-e, --end_time=VALUE   Set the end time for simulation (default: 2.8)
    --epsilon=VALUE    Set the depth of LJ potential well (default: 5)
    --sigma=VALUE      Set the Zero crossing of LJ potential (default: 1)
-l, --log_level=LEVEL  Set the logging level (default: 3, incompatible with -p)
      - 1                 trace
      - 2                 debug
      - 3                 info
      - 4                 warn
      - 5                 error
      - 6                 critical
      - 7                 off
-c                     Specify that the given input file describes clusters
-a                     Specify that the given input file is of type ascii art
-x                     Specify that the given input file is of type XML
-s, --simtype=VALUE    Specify simulation type (default: 0)
      - 0                 PlanetSimulation
      - 1                 LennardJonesSimulation
      - 2                 LinkedLennardJonesSimulation
      - 3                 LennardJonesDomainSimulation
      - 4                 MixedLJSimulation
      - 5                 MembraneSimulation
-w, --writetype=VALUE  Specify writer type (default: 0, incompatible with -p)
      - 0                 VTK-Writer
      - 1                 XYZ-Writer
      - 2                 XML-Writer
      - 3                 Empty i.e. no output
-p                     Run performance measurements (incompatible with -l, -w)
-P, --parallel         Specify parallel strategy
      - static
      - task
-h, --help             Display help message

For more information about arguments and default settings, type:

src/MolSim -h

or read the man page

Assignment 1 simulation

src/MolSim ../input/eingabe-sonne.txt -e 1000

See this YouTube video for our result.

Assignment 2 simulation

src/MolSim ../input/clusters.txt -c -s 1 -d 0.0002 -e 5

See this YouTube video for our result.

Assignment 3 simulation

Cuboid collision:

src/MolSim ../input/assign3.xml -x -s 3

See this YouTube video for our result.

Falling drop:

src/MolSim ../input/falling_drop.xml -x -s 3

See this YouTube video for our result.

Assignment 4 simulation

Big Rayleigh-Taylor instability:

src/MolSim ../input/big_rayleigh_taylor.xml -x -s 4

See this YouTube video for our result.

Falling drop:

src/MolSim ../input/falling_drop_after_equi.xml -x -s 4

See this YouTube video for a result of ours.

Assignment 5 simulation

Membrane:

src/MolSim ../input/membrane.xml -x -s 5

See this YouTube video for our result.

Rayleigh-Taylor instability in 3D:

src/MolSim ../input/reyleigh_3D.xml -x -s 4

See this YouTube video for our result.

Nano-scale flow simulation (base):

src/MolSim ../input/nano_scale_flow.xml -x -s 4

See this YouTube video for our result.

Nano-scale flow simulation (strong wall + rare thermostat update):

src/MolSim ../input/nano_scale_mods/nano_flow_stronger_wall_weak_thermo.xml -x -s 4

See this YouTube video for our result.

Nano-scale flow simulation (strong wall with nice profile result):

src/MolSim ../input/nano_scale_mods/nano_flow_stronger_wall.xml -x -s 4

See this YouTube video for our result.

Nano-scale flow simulation (with turbulence):

src/MolSim ../input/nano_scale_mods/nano_flow_turbulence.xml -x -s 4

See this YouTube video for our result.

Generate Doxygen documentation

To generate the Doxygen documentation, run the following command:

make doc_doxygen

This will generate the documentation into the folder doxys_documentation.

Run tests

To build the tests run:

cd build
make tests

To run the tests, run the following command:

tests/tests

Or alternatively with ctest:

ctest --test-dir tests

Run benchmarks

The benchmarks are run using Google benchmark. Build:

cd build
make benchmarks

Run:

bench/benchmarks

Format code

If your system has clang-format installed, the target clangformat will be created. You can then run:

make clangformat

to format the code.

Open man page

To see more details on how to use the program, you can look at our man page. Enter the project root and then run:

man ./.molsim.1

Documentation

Project structure

The project is structured as follows:

Note that this is not a perfect UML diagram, but rather a visualization of the broad structure of the project. The latest changes done within the scope of assignment 5 are highlighted in orange.

Simulation

Any kinds of a simulations are represented as a child class of the Simulation class
Any simulation instance defines the runSim() function, which uses the I/O classes (FileReader, FileWriter), the PhysicsStrategy class and the model variables passed to it to calculate the simulation through time.
Child simulations extend their parent simulation with new model variables.
- Multiple simulation classes have been added to allow for the functionality required for each assignment. See the following table for all functionality

	Simulation Type	Gravity	Lennard-Jones-Potential	Linked-Cell	Boundary Conditions	Analytics	Multiple different Particles	Thermostat	Molecules
PlanetSimulation	0	✅	❌	❌	❌	❌	❌	❌	❌
LennardJonesSimulation	1	❌	✅	❌	❌	❌	❌	❌	❌
LinkedLennardJonesSimulation	2	❌	✅	✅	❌	❌	❌	❌	❌
LennardJonesDomainSimulation	3	❌	✅	✅	✅	✅	❌	❌	❌
MixedLJSimulation	4	✅	✅	✅	✅	✅	✅	✅	❌
MembraneSimulation	5	✅	✅	✅	✅	✅	✅	✅	✅

Note on Run-time: Without the Linked-Cell algorithm the complexity scales in O(n²), otherwise in O(n).

PhysicsStrategy

Strategy interface allows for interchangable / compareable implementation of the physics
Realistically, velocities and positions are calculated according to Störmer-Verlet and are not changed (only parallelized later on)
Interchangeable are the force calculations -> Essentially each simulation has its own implementation of the forces

FileWriter

Template method class defining a common interface of different writers
There are XYZ and VTK writers available

FileReader

Template method class defining a common interface of different readers
Different input types can be specified (see here in section Input specification)

ParticleCluster

Represents a cluster of particles that can be used to initialize the simulation
Based on an abstract ParticleCluster class
Child classes include CuboidParticleCluster and SphereParticleCluster

CellGrid

The MD-Simulation uses the linked-cell algorithm starting from the LinkedLennardJonesSimulation
The algorithm scales in O(n) relative to the number of particles
Assumes a certain cutoff distance after which the forces are neglected

Thermostat

Used to cool / heat / maintain the temperature of the simulation
There are two thermostats available
The classical thermostat will reduce the temperature without regarding the mean velocity of the system, while the individual thermostat does

Analyzer

Can be used to analyze the simulation
It can produce the density and velocity profile of a simulation
Can be specified with dimensionality

ProgressLogger

Will log the progress of the simulation while it is running to inform the user about progress and ETA
Will update after each percent of the simulation has finished

Folder structure

This section describes the folder structure of this project (see UML-Diagram):

MolSim-SS24
├── bench                           Code to benchmark simulation
│   └── results                     Measurements from g-bench runs
│       └── google_benchmark_plot   Result plots
├── cmake
│   └── modules                     Files to find and load packages
├── docs
│   ├── presentation                The latex-files for the presentations
│   ├── report                      The latex-files for the reports
│   └── res                         Images for the documentation
├── input                           Input files used in the assignments
├── libs
│   └── libxsd                      Code for the xsd library
├── results                         Some density-profiles to plot
├── scripts
│   ├── batch-scripts               Scripts to run our simulations on cluster
│   ├── paraview                    Scripts used to help paraview
│   └── plots                       Scripts to create plots
├── src
│   ├── analytics                   Code for ProgressLogger & Analyzer
│   ├── io
│   │   ├── argparse                Code to parse arguments
│   │   ├── fileReader              Code to read input files
│   │   ├── fileWriter              Code to write output files
│   │   ├── xmlparse                Code to parse xml input
│   │   └── xsd                     Code for xsd (xml input)
│   ├── models
│   │   ├── generators              Code to generate clusters
│   │   ├── linked_cell             Code for the linked-cell data structure
│   │   │   └── cell                Code for the cells in the data structure
│   │   └── molecules               Code to generate molecules
│   ├── physics
│   │   ├── boundaryConditions      Code to do boundary conditions
│   │   ├── forceCal                Code to calculate forces
│   │   ├── locationCal             Code to calculate positions
│   │   ├── thermostat              Code for the thermostats
│   │   └── velocityCal             Code to calculate velocities
│   ├── simulation                  Code for the different simulations
│   └── utils                       Utils code (ArrayUtils, ...)
└── tests
    ├── analytics                   Tests for the Analyzer
    ├── data                        Input for the tests
    ├── io                          Tests for IO
    ├── models
    │   ├── generators              Tests for the clusters
    │   └── linkedcell              Tests for the linked-cell Algorithm
    └── physics                     Tests for the physics codes
        └── boundaryConditions      Tests for the boundary conditions

src/MolSim.cpp: Is the core file holding the main function

Input specification

Compatibility overview

Input type vs. what can be specified in it

	Clusters	Single Points	Ascii Art	Program Arguments (s.a. start, end, ...)	Different particle types
XYZ	❌	✅	❌	❌	❌
Cluster	✅	♻️	❌	❌	❌
Ascii Art	❌	♻️	✅	❌	❌
XML	✅	✅	❌	✅	✅

Note: ♻️ means you technically can, but probably shouldn't

Cluster (-c)

A cluster file can only code for clusters. By specifying clusters of size 1, a single point could be created
Lines that start with a # are disregarded as comments
Each line can specify one cluster
The input can be written to a .txt file
The format is as follows:

# For Cuboid Clusters:
C <posx> <posy> <posz> <width> <height> <depth> <spacing> <mass> <meanVel> <vx> <vy> <vz> <Dim. of Brownian motion (2/3)>
# For Sphere Clusters:
S <posx> <posy> <posz> <radius> <sphereDimensions (2/3)> <mass> <meanVel> <vx> <vy> <vz> <Dim. of Brownian motion (2/3)>

Where the specified position is the back, left, bottom corner of the cuboid or center of the sphere

Cluster Input Example

# Sphere
S 0.0 0.0 0.0 4 2 1.1225 1 0.1 -30 0 0 2
# Cluster:
C 35 15 0 8 8 1 1.125 1 1 10 0 0 2

Ascii-Art (-a)

An ascii-Art input file is a .txt file
It specifies a 2D shape of particles i.e. creates particles in the shape of ascii art
One can use any character in the ascii art as long as it is listed
The format is as follows:

<posx> <posy> <posz>
<vx> <vy> <vz> <mass> <spacing> <meanVel>
<first char to represent particle> <second char to represent particle> ...
<Shape>

Ascii-Art Input Example

0 0 0
0 -10 0 1 1.125 0.1
+ . : - =
++++++++++++++++++++++++++++++++++-         :+++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++-         :+++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++-         :+++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++-         :+++++++++++++++++++++++++++++++++++++++++++++
........:++++++++:........++++++++-         :++++++++:........:++++++++-.........-++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++-         :++++++++          ++++++++:         -++++++++
        .++++++++.        ++++++++===========++++++++          ++++++++:         -++++++++
        .++++++++.        +++++++++++++++++++++++++++          ++++++++:         -++++++++
        .++++++++.        +++++++++++++++++++++++++++          ++++++++:         -++++++++
        .++++++++.        +++++++++++++++++++++++++++          ++++++++:         -++++++++

XML (-x)

The XML input file is the recommended input format as it allows for the must broad input specification
The input must be stored as .xml files
Note: Not all parameters that can be specified work with all simulation types. Please refer to the overview in the project structure
The input specification is as follows:

Scaffold

<?xml version="1.0" encoding="UTF-8"?>
<simulation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...
</simulation>

Simulation parameters

<params>
  <delta_t>yourDeltaT</delta_t>
  <end_time>yourEndTime</end_time>
  <output>NameOfOutputFile</output>
  <frequency>FrequencyOfPlotting</frequency>
  <!-- Domain params -->
  <domainOrigin> <!-- Back-Bottom-Left corner of Domain -->
    <x>xCoord</x>
    <y>yCoord</y>
    <z>zCoord</z>
  </domainOrigin>
  <domainSize>
    <x>sizeInXDirection</x>
    <y>sizeInXDirection</y>
    <z>sizeInZDirection</z> <!-- Set to 0 for 2D domain -->
  </domainSize>
  <cutoff>YourCutoffForLinkedCell</cutoff>
  <!-- Boundary params -> Choose periodic, soft_reflective, outflow -->
  <boundaries>
    <!-- For 2D Domain use bound_four tag -->
    <bound_four>yourBoundary</bound_four> <!-- Left Boundary -->
    <bound_four>yourBoundary</bound_four> <!-- Right Boundary -->
    <bound_four>yourBoundary</bound_four> <!-- Top Boundary -->
    <bound_four>yourBoundary</bound_four> <!-- Bottom Boundary -->
    <!-- For 3D Domain use bound_six tag -->
    <bound_six>yourBoundary</bound_six> <!-- Left Boundary -->
    <bound_six>yourBoundary</bound_six> <!-- Right Boundary -->
    <bound_six>yourBoundary</bound_six> <!-- Top Boundary -->
    <bound_six>yourBoundary</bound_six> <!-- Bottom Boundary -->
    <bound_six>yourBoundary</bound_six> <!-- Front Boundary -->
    <bound_six>yourBoundary</bound_six> <!-- Back Boundary -->
  </boundaries>
  <!-- Thermostat params -->
  <thermostat>
      <initialTemp>yourStartingTemperatureInKelvin</initialTemp>
      <thermoFreq>FrequencyOfThermostatApplication</thermoFreq>
      <maxTempDelta>MaximalChangeInTemperatureInKelvin</maxTempDelta>
      <type>ThermostatType</type> <!-- Choose between individual or classic -->
  </thermostat>
  <!-- Gravity params -->
  <gravity>YourGravity</gravity> <!-- F = gravity * particleMass -->
  <!-- Analyzer params -->
  <analysisName>OutPutNameOfAnalysisFiles</analysisName>
  <analysisFreq>FrequencyOfRunningAnalyzer</analysisFreq>
</params>

Clusters

Scaffold:

<clusters>
  ...
</clusters>

Sphere:

<sphere>
  <center>
    <x>XCoordOfCenter</x>
    <y>YCoordOfCenter</y>
    <z>ZCoordOfCenter</z>
  </center>
  <vel>
    <x>InitialVelInXDirection</x>
    <y>InitialVelInYDirection</y>
    <z>InitialVelInZDirection</z>
  </vel>
  <radius>RadiusOfSphereInParticles</radius>
  <mass>MassOfParticles</mass>
  <sphereDim>DimensionalityOfSphere(2/3)</sphereDim>
  <spacing>MinimalSpacingBetweenParticles</spacing>
  <brownVel>MeanBrownianVelocity</brownVel>
  <brownDim>DimensionalityToApplyBrownianMotionTo</brownDim>
  <ptype>TypeOfTheParticles</ptype>
</sphere>

Cuboid:

<cuboid>
  <pos> <!-- Lower-Left-Bottom Corner -->
    <x>CornerXCoordinate</x>
    <y>CornerXCoordinate</y>
    <z>CornerZCoordinate</z>
  </pos>
  <vel>
    <x>InitialVelInXDirection</x>
    <y>InitialVelInYDirection</y>
    <z>InitialVelInZDirection</z>
  </vel>
  <dim>
    <x>NumberOfParticlesWidth</x>
    <y>NumberOfParticlesHight</y>
    <z>NumberOfParticlesDepth</z>
  </dim>
  <mass>MassOfParticle</mass>
  <spacing>SpacingBetweenParticles</spacing>
  <brownVel>MeanBrownianVelocity</brownVel>
  <brownDim>DimensionsOfBrownianMotion(2/3)</brownDim>
  <ptype>TypeOfParticle</ptype>
</cuboid>

Single Particles

This follows the VTK structure

<particles>
  <PointData dim="3">
    xOfFirst yOfFirst zOfFirst xOfSecond yOfSecond zOfSecond ...
  </PointData>

  <VelData dim="3">
    xVelOfFirst yVelOfFirst zVelOfFirst xVelOfSecond yVelOfSecond zVelOfSecond ...
  </ValData>

  <ForceData dim="3">
    xForceOfFirst yForceOfFirst zForceOfFirst xForceOfSecond yForceOfSecond zForceOfSecond ...
  </ForceData>

  <OldForceData dim="3">
    xOldForceOfFirst yOldForceOfFirst zOldForceOfFirst xOldForceOfSecond yOldForceOfSecond zOldForceOfSecond ...
  </OldForceData>

  <MassData dim="1">
    massOfFirst massOfSecond ...
  </MassData>

  <TypeData dim="1">
    typeOfFirst typeOfSecond ...
  </TypeData>
</particles>

Molecules

Currently there is only the membrane available as molecule

Scaffold:

<molecules>
  ...
</molecules>

Membrane:

<membrane>
  <pos> <!-- Lower-Left-Bottom Corner -->
    <x>CornerXCoordinate</x>
    <y>CornerXCoordinate</y>
    <z>CornerZCoordinate</z>
  </pos>
  <vel>
    <x>InitialVelInXDirection</x>
    <y>InitialVelInYDirection</y>
    <z>InitialVelInZDirection</z>
  </vel>
  <dim>
    <x>NumberOfParticlesWidth</x>
    <y>NumberOfParticlesHight</y>
    <z>NumberOfParticlesDepth</z>
  </dim>
  <mass>MassOfParticle</mass>
  <spacing>SpacingBetweenParticles</spacing>
  <brownVel>MeanBrownianVelocity</brownVel>
  <brownDim>DimensionsOfBrownianMotion(2/3)</brownDim>
  <ptype>TypeOfParticle</ptype>
  <equiDist>r0ForMembrane</equiDist>
  <springConst>SpringConstantK</springConst>
</membrane>

Different Particles

Scaffold:

<ptypes>
  ...
</ptypes>

Specify different particle types and their LJ params + fixing them:

<ptype type="Particle Type">
    <sigma>SigmaValue</sigma>
    <epsilon>EpsilonValue</epsilon>
    <immobile>TrueWillFixateParticleAndNotMoveIt</immobile>
</ptype>

For Examples see Input files

Name		Name	Last commit message	Last commit date
Latest commit History 174 Commits
.github/workflows		.github/workflows
bench		bench
cmake/modules		cmake/modules
docs		docs
input		input
libs/libxsd		libs/libxsd
results		results
scripts		scripts
src		src
tests		tests
.clang-format		.clang-format
.clangd		.clangd
.gitignore		.gitignore
.gitmodules		.gitmodules
.molsim.1		.molsim.1
CMakeLists.txt		CMakeLists.txt
Doxyfile		Doxyfile
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MolSim Group F

Table of Contents

Group members

Quickstart

Build instructions

Run instructions

Assignment 1 simulation

Assignment 2 simulation

Assignment 3 simulation

Assignment 4 simulation

Assignment 5 simulation

Generate Doxygen documentation

Run tests

Run benchmarks

Format code

Open man page

Documentation

Project structure

Folder structure

Input specification

Compatibility overview

Cluster (-c)

Cluster Input Example

Ascii-Art (-a)

Ascii-Art Input Example

XML (-x)

Performance

About

Releases

Packages

Languages

noahpy/MolSim-SS24

Folders and files

Latest commit

History

Repository files navigation

MolSim Group F

Table of Contents

Group members

Quickstart

Build instructions

Run instructions

Assignment 1 simulation

Assignment 2 simulation

Assignment 3 simulation

Assignment 4 simulation

Assignment 5 simulation

Generate Doxygen documentation

Run tests

Run benchmarks

Format code

Open man page

Documentation

Project structure

Folder structure

Input specification

Compatibility overview

Cluster (-c)

Cluster Input Example

Ascii-Art (-a)

Ascii-Art Input Example

XML (-x)

Performance

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages