Add simulation process overview and input file format details

ManuelLerchner · Jan 9, 2024 · 44edafa · 44edafa
1 parent 84871cb
commit 44edafa
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -18,9 +18,19 @@ This repo contains the code for the practical course **PSE: Molecular Dynamics**
 
 <!-- markdownlint-disable MD033 -->
 <a href="https://github.com/ManuelLerchner/MolSim-WS23-24/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=ManuelLerchner/MolSim-WS23-24" />
+  <img src="https://contrib.rocks/image?repo=ManuelLerchner/MolSim-WS23-24" alt="Contributors"/>
 </a>
 
+## Simulation Process
+
+The simulation is designed in a modular way. The following diagram shows the main components of the simulation and how they interact with each other.
+
+<img style="background-color: white;" src="./docs/images/simulation_overview.svg" alt="Simulation Overview"/>
+
+- **Recursive Subsimulations:** The simulations can be run recursively when loading initial particle configurations from files. This allows to simulate complex systems with multiple particle types and different initial conditions inside a single simulation.
+- **Interceptor Pattern:** The simulation is designed to be easily extensible. This is achieved by using the interceptor pattern. This allows to add new features to the simulation without having to change the core simulation code. A Intercepor is a class that implements a certain interface and is registered in the simulation. The simulation then calls the interceptor at certain points during the simulation.
+- **Flexible Input File Format:** The simulation can be specified via a XML file. This allows to specify all the simulation parameters at once and makes it easy to run the same simulation multiple times with different parameters. The XML file format can be looked up in the [Input File Formats](@ref InputFileFormats) section.
+
 ## Submissions and Presentations
 
 All the submissions for the individual sheets, the presentation slides and the project documentation is automatically deployed to [GitHub Pages](https://manuellerchner.github.io/MolSim-WS23-24) and can be accessed via the following links:

diff --git a/docs/InputFileFormats.md b/docs/InputFileFormats.md
@@ -17,47 +17,81 @@ In the following sections, the file formats are explained in detail.
 
 The `.xml` file format can be used to specify all the input parameters for the simulation at once. Therefore, it is preferred over the other file formats.
 
-Its definition is based on the [simulation_schema.xsd](simulation_schema.xsd) file, which is used to validate the input file. The file contains a single root element `<configuration>` with the following child elements:
+Its definition is based on the [simulation_schema.xsd](simulation_schema.xsd) file, which is used to validate the input file. The file contains a single root element `<configuration>` and can contain the following elements:
 
-- Simulation Settings:
-  - `<fps>`: The number of frames per second to be rendered
-  - `<video_length>`: The length of the video in seconds
+- Settings:
   - `<delta_t>`: The time step size
   - `<end_time>`: The time at which the simulation should end
   - `<particle_container>` Which particle container implementation should be used
+
+- Forces:
+  - `<LennardJones>`: The Lennard-Jones force
+  - `<Harmonic>`: The harmonic force used between linked particles
+  - `<Gravity>`: The gravity force between particles
+  - `<GlobalGravity>`: The gravity force acting on all particles
+  - ...
+
+- Interceptors:
+  - `<FrameWriter>`: Writes the simulation state to a file at a specified frame rate
+  - `<ParticleUpdateCounter>`: Counts the number of particle updates
+  - `<RadialDistributionFunction>`: Calculates the radial distribution function of the particles
+  - `<Thermostats>`: Applies a thermostat to the particles
+  - ...
 
 - Particle Data:
   - `<cuboid_spawner>`: Input data for a cuboid spawner, which generates particles in a cuboid shape (2 or 3 dimensional)
   - `<sphere_spawner>`: Input data for a sphere spawner, which generates particles in a spherical shape (2 or 3 dimensional)
   - `<single_particle_spawner>`: Input data for a single particle, which is placed at the specified position
+  - `<subsimulations>`: Input data for a subsimulation, which is run recursively and then copied into the main simulation
+  - ...
 
 An example file could look like this:
 
 ```xml
 <?xml version="1.0"?>
 <configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="simulation_schema.xsd">
+    xsi:noNamespaceSchemaLocation="../simulation_schema.xsd">
 
     <settings>
-        <fps>24</fps>
-        <video_length>10</video_length>
-        <delta_t>0.014</delta_t>
-        <end_time>10.0</end_time>
+        <delta_t>0.0005</delta_t>
+        <end_time>20.0</end_time>
+        <third_dimension>false</third_dimension>
         <particle_container>
-            <directsum_container />
+            <linkedcells_container>
+                <domain_size>
+                    <x>180</x>
+                    <y>90</y>
+                    <z>3</z>
+                </domain_size>
+                <cutoff_radius>3.0</cutoff_radius>
+                <boundary_conditions>
+                    <left>Outflow</left>
+                    <right>Outflow</right>
+                    <bottom>Outflow</bottom>
+                    <top>Outflow</top>
+                    <back>Outflow</back>
+                    <front>Outflow</front>
+                </boundary_conditions>
+            </linkedcells_container>
         </particle_container>
+        <forces>
+            <LennardJones />
+        </forces>
+        <interceptors>
+            <FrameWriter output_format="vtu" fps="24" video_length_s="30" />
+        </interceptors>
     </settings>
 
-    <particles>
+    <particle_source>
         <cuboid_spawner>
             <lower_left_front_corner>
-                <x>0.0</x>
-                <y>0.0</y>
-                <z>0.0</z>
+                <x>20.0</x>
+                <y>20.0</y>
+                <z>1.5</z>
             </lower_left_front_corner>
             <grid_dim>
-                <x>40</x>
-                <y>8</y>
+                <x>100</x>
+                <y>20</y>
                 <z>1</z>
             </grid_dim>
             <grid_spacing>1.1225</grid_spacing>
@@ -69,8 +103,10 @@ An example file could look like this:
                 <z>0.0</z>
             </velocity>
             <type>0</type>
+            <epsilon>1.0</epsilon>
+            <sigma>1.2</sigma>
         </cuboid_spawner>
-    </particles>
+    </particle_source>
 
 </configuration>
 ```