- Formatting

- Applied suggestions from review

README.md

@@ -7,45 +7,56 @@
 Codebase for the ARIADNA Study between TU Munich and ESA's Advanced Concepts Team. A more detailed project description can be found on the [Advanced Concept Team's webpage](https://www.esa.int/gsp/ACT/projects/debris_hpc/).
 
 ## Requirements
-* CMake >= 3.19
-* make (build-essentials, or equivalent)
-* A C++17 Compiler (recommended: gcc >=7 or clang >=8, only clang-10 is tested)
-* OpenMP >= 4.5
-* git (for fetching dependencies)
-* [TBB](https://github.com/oneapi-src/oneTBB) (Breakup-Model needs this)
+
+- CMake >= 3.19
+- make (build-essentials, or equivalent)
+- A C++17 Compiler (recommended: gcc >=7 or clang >=8, only clang-10 is tested)
+- OpenMP >= 4.5
+- git (for fetching dependencies)
+- [TBB](https://github.com/oneapi-src/oneTBB) (Breakup-Model needs this)
 
 ### Optional
-* Doxygen
-* clang-format-9
-* MPI
+
+- Doxygen
+- clang-format-9
+- MPI
 
 ## Important Dependencies
+
 The following codes play an important role in this project. They are downloaded and managed via CMake at configure time:
-* [AutoPas](https://github.com/AutoPas/AutoPas)
-* [NASA Breakup Model](https://github.com/esa/NASA-breakup-model-cpp)
-* [Orbit Propagator](https://github.com/FG-TUM/OrbitPropagator)
+
+- [AutoPas](https://github.com/AutoPas/AutoPas)
+- [NASA Breakup Model](https://github.com/esa/NASA-breakup-model-cpp)
+- [Orbit Propagator](https://github.com/FG-TUM/OrbitPropagator)
 
 ## Building
+
 ```bash
 mkdir build && cd build
 CC=clang CXX=clang++ ccmake ..  # Set Variables according to your preferences
 make -j12                       # choose number according to your CPU
 ```
 
 ## Testing
+
 Testing is done with help of [GoogleTest](https://github.com/google/googletest), which is downloaded by CMake.
+
 ```bash
 cmake -DLADDS_BUILD_TESTS=ON .. # Should be enabled by default
 make ladds_tests -j12
 ctest -j12
 ```
 
 ## Running
+
 The simulation requires one `yaml` file as argument which specifies the necessary options.
+
 ```bash
 ./ladds myInput.yaml
 ```
+
 or with MPI and e.g. 42 ranks:
+
 ```bash
 mpiexec -n 42 ./ladds myInput.yaml
 ```
@@ -55,71 +66,84 @@ a default value which is used when they are left unspecified. The full configura
 values, is shown in the console output when executing the simulation.
 
 ### Checkpoints
+
 LADDS features a checkpoint mechanic where a simulation can be restarted from an HDF5 file.
 To create a checkpoint the simulation just needs to write an HDF5 file.
 This is done via the following part of the configuration:
+
 ```yaml
 io:
   csv:
-    fileName: initial_population.csv  # = input
+    fileName: initial_population.csv # = input
   hdf5:
-    fileName: checkpointFile.h5       # = output
-    writeFrequency: 100               # how often LADDS writes to HDF5  
+    fileName: checkpointFile.h5 # = output
+    writeFrequency: 100 # how often LADDS writes to HDF5
 ```
 
 The next simulation, which starts from `checkpointFile.h5` then needs to have the following:
+
 ```yaml
 io:
   hdf5:
     checkpoint:
-      file: checkpointFile.h5         # = input AND output
-      iteration: 99                   # Iteration where to start from. Will use last if not given.
-    writeFrequency: 100               # how often LADDS writes to HDF5  
+      file: checkpointFile.h5 # = input AND output
+      iteration: 99 # Iteration where to start from. Will use last if not given.
+    writeFrequency: 100 # how often LADDS writes to HDF5
 ```
-LADDS will append any new data to the checkpoint file. This will load iteration 99 (which is the 100th iteration) 
+
+LADDS will append any new data to the checkpoint file. This will load iteration 99 (which is the 100th iteration)
 from the checkpoint and start the simulation with iteration 100. Note that no `io/csv/fileName` or differing `io/hdf5/fileName` should be provided when loading a checkpoint.
 
 **IMPORTANT**: All file paths are relative to the [`data`](data/) directory!
 
 ## Simulating Breakups
-The code is capable to simulate fatal collisions between two bodies via the 
+
+The code is capable to simulate fatal collisions between two bodies via the
 [NASA Breakup Model](https://github.com/esa/NASA-breakup-model-cpp). This feature can be activated in
 the `yaml` file via:
+
 ```yaml
 sim:
   breakup:
     enabled: true
 ```
 
 ## Calibrating AutoPas
+
 By default, some robust but static configuration is set by LADDS. You can change this by specifying the
 algorithmic options AutoPas is allowed to use in the YAML file. If more than one configuration can be built
 from these options AutoPas will tune over them at run time.
 
 ### Enable Auto Tuning
+
 If you are unsure what algorithmic configuration you want to use for AutoPas just let AutoPas guide you.
 For this, the following needs be activated in the `yaml` file:
+
 ```yaml
 autopas:
   tuningMode: true
 ```
+
 In this mode, the simulation is only executed for one AutoPas tuning-phase. At the end of this phase, a copy
 of the full configuration is created, which contains the algorithm configuration that AutoPas deemed to be
 the fastest. This configuration can then be used to run the actual simulation at optimal speed.
 
 ### Analyzing AutoPas Configurations
-AutoPas can be compiled to dump information about the performance of the algorithms it uses to `.csv` files. 
-For this set the CMake variables:  `AUTOPAS_LOG_TUNINGDATA=ON` and `AUTOPAS_LOG_TUNINGRESULTS=ON`.
-* `AutoPas_tuningData.csv` contains the timing data of all samples AutoPas collected.
-* `AutoPas_tuningResults.csv` contains the result of each tuning phase.
 
-## Processing TLE Input 
+AutoPas can be compiled to dump information about the performance of the algorithms it uses to `.csv` files.
+For this set the CMake variables: `AUTOPAS_LOG_TUNINGDATA=ON` and `AUTOPAS_LOG_TUNINGRESULTS=ON`.
+
+- `AutoPas_tuningData.csv` contains the timing data of all samples AutoPas collected.
+- `AutoPas_tuningResults.csv` contains the result of each tuning phase.
+
+## Processing TLE Input
+
 Data on current satellites etc. is often found [online](https://www.space-track.org/) in the [TLE format](https://en.wikipedia.org/wiki/Two-line_element_set). We include a Jupyter notebook which can be used to process TLE data with pykep to create and analyze suitable datasets. Detailed instructions can be found in the notebook in `notebooks/Data Processing.ipynb`.
 
 ## Generating and including Constellations
+
 Satellite constellations (e.g. Starlink, OneWeb) are usually described by a list of orbital shells.
-An orbital shell is described by a 4-tuple with information about `altitude`, `inclination`, `number of
-planes`, and `number of satellites` per plane. We provide a notebook
+An orbital shell is described by a 4-tuple with information about `altitude`, `inclination`, `number of planes`, and `number of satellites` per plane. We provide a notebook
 [`notebooks/ConstellationGeneration/ConstellationGeneration.ipynb`](notebooks/ConstellationGeneration/ConstellationGeneration.ipynb) that can be used
 
 ### How constellation satellites are inserted into the simulation
@@ -134,10 +158,11 @@ and linearly over time.
 
 In the configuration file for the simulation, include the constellation(s) by
 defining the following fields:
-*  `constellationList`: Semicolon (`;`) separated list of constellation names. E.g. `Astra;Starlink;OneWeb`
-* `constellationFrequency`: Number of timesteps between constellation insertions.
-* `constellationCutoff`: Satellites are inserted with a delay, if there is an object within this range.
-* `altitudeSpread`: `[km]` Three times the standard deviation of the normal distribution describing
+
+- `constellationList`: Semicolon (`;`) separated list of constellation names. E.g. `Astra;Starlink;OneWeb`
+- `constellationFrequency`: Number of timesteps between constellation insertions.
+- `constellationCutoff`: Satellites are inserted with a delay, if there is an object within this range.
+- `altitudeSpread`: `[km]` Three times the standard deviation of the normal distribution describing
   the imprecision of orbital insertion. ~99.74% of satellites deviate by less than this value from the
   mean altitude.
 
@@ -146,22 +171,31 @@ defining the following fields:
 LADDS has multiple options for output that can be (de)activated mostly independent of each other via YAML. See [`cfg/default_cfg.yaml`](cfg/default_cfg.yaml) for relevant options.
 
 ### VTK
+
 #### Particles
+
 `.vtu` files in XML/ASCII layout that can be loaded into [Paraview](https://www.paraview.org/) for visualization. They contain all particles positions and (most of) their properties.
 There will be one `vtu` file per rank and visualization step, as well as one `pvtu` file per step, which links to all files of the same step.
 
 #### MPI Decomposition
+
 If the selected MPI decomposition supports it, `vts` and `pvts` files are created similar to those for particles.
 These however, contain information to visualize the spacial MPI decomposition in [Paraview](https://www.paraview.org/).
 
 ### HDF5
+
 A single `.h5` containing particle and conjunction data from a full simulation run with the following structure:
+
 ```
 /
 ├── CollisionData
 │   └── <IterationNr>
 │       └── (Dataset) Collisions
 │           idA idB distanceSquared
+├── EvasionData
+│   └── <IterationNr>
+│       └── (Dataset) Evasions
+│           idA idB distanceSquared
 └── ParticleData
     └── <IterationNr>
     │   └── Particles
@@ -174,14 +208,16 @@ A single `.h5` containing particle and conjunction data from a full simulation r
          id cosparId mass radius bcInv activityState
 ```
 
-Collision data is tracked every iteration, particle data only in intervals that are defined in the YAML file.
-`ConstantProperties` contains properties of all particles that existed over the course of the simulation. 
-Due to burn ups or breakups the number of particles in any iteration might differ but `id`s are unique! 
+Collision and evasion data is tracked every iteration, particle data only in intervals that are defined in the YAML file.
+`ConstantProperties` contains properties of all particles that existed over the course of the simulation.
+Due to burn ups or breakups the number of particles in any iteration might differ but `id`s are unique!
 To keep file size reasonable compression is supported.
 
 If MPI is used one HDF5 file per rank is written.
 `ParticleData` contains the information of all particles that at any point passed through this rank.
 `CollisionData` contains all collisions that happened in this rank.
+`EvasionData` contains all evasions (i.e. an active particle evading a conjunction) that happened in this rank.
 
 ### CSV
-If HDF5 output is disabled entirely, collision data is written in a `.csv` file in ASCII layout.
+
+If HDF5 output is disabled entirely, collision and evasion data is written in a `.csv` file in ASCII layout.

cfg/default_cfg.yaml

@@ -1,17 +1,17 @@
 sim:
-  logLevel: info    # Available levels are off, critical, err, warn, info, debug, trace
+  logLevel: info # Available levels are off, critical, err, warn, info, debug, trace
   iterations: 32000 # Number of simulation iterations
   timeout: # timeout for the simulation. The simulation stops when either the specified number of iterations is hit or the timeout reached.
-    seconds: 0  # whole seconds
+    seconds: 0 # whole seconds
     minutes: 0. # as floating points
-    hours: 0.   # as floating points
-    days: 0.    # as floating points
+    hours: 0. # as floating points
+    days: 0. # as floating points
   referenceTime: 2022-01-01 # calendar day associated with simulation start at iteration 0 (yyyy/mm/dd)
   maxAltitude: 10000 # Maximum satellite altitude above earth core. This number times two is the simulation box length. [km]
   minAltitude: 150 # Everything below this altitude above ground will be considered burning up [km]
   deltaT: 10.0 # [s]
   collisionDistanceFactor: 1.0 # Factor multiplied with the sum of radii to over approximate collision distances.
-  # CDMcutoffInKM: 0.1 # Distance at which even evaded conjunctions are tracked (in a separate out file)
+  # evasionTrackingCutoffInKM: 0.1 # Distance at which even evaded conjunctions are tracked (in a separate out file)
   timestepsPerCollisionDetection: 1
   # decompositionType: Altitude   # Determines the MPI decomposition type. Options: "Altitude" are spherical shells, "RegularGrid" standard cartesian grid.
 
@@ -24,7 +24,7 @@ sim:
     useLUNComponent: false # Lunar gravitational pull
     useSRPComponent: true # Solar radiation pressure
     useDRAGComponent: true # Atmospheric drag
-    coefficientOfDrag: 2.2  # c_D for the drag component used in all objects where no BSTAR is available
+    coefficientOfDrag: 2.2 # c_D for the drag component used in all objects where no BSTAR is available
 
   breakup:
     enabled: false # (de-)activate the breakup mechanic
@@ -34,14 +34,14 @@ sim:
 io:
   csv:
     # propagatorOutput: propagator.csv # Output file for the propagator. Currently, nothing is written.
-    fileName: initial_population.csv  # CSV file containing all data to initialize the full satellite population
+    fileName: initial_population.csv # CSV file containing all data to initialize the full satellite population
   #progressOutputFrequency : 50 # Frequency of writing iteration number and encounter info to std::out.
   vtk:
     writeFrequency: 0 # Frequency of writing vtk files [iterations]
   hdf5:
-#    checkpoint:
-#      file: hdf5ReloadTestCheckpoint.h5
-#      iteration: 0 # Iteration to be loaded. If omitted, the last iteration in the file will be loaded.
+    #    checkpoint:
+    #      file: hdf5ReloadTestCheckpoint.h5
+    #      iteration: 0 # Iteration to be loaded. If omitted, the last iteration in the file will be loaded.
     fileName: simulationData.h5
     writeFrequency: 1000 # Frequency of writing to the hdf5 file [iterations]
     compressionLevel: 4 # Valid Levels: 0 (no compression) - 9 (max compression)
@@ -55,8 +55,8 @@ autopas:
   logLevel: off
   cutoff: 80.0 # Cutoff for autopas force interaction
   # For the following parameters sensible defaults are chosen by LADDS. Only set them here if you know what you are doing!
-#  rebuildFrequency: 1 # Number of iterations before internal data structure is rebuilt. Increases collision search radius!
-#  desiredCellsPerDimension: 25 # Desired number of cells per dimension
+  #  rebuildFrequency: 1 # Number of iterations before internal data structure is rebuilt. Increases collision search radius!
+  #  desiredCellsPerDimension: 25 # Desired number of cells per dimension
   tuningMode: false # can be used to obtain good values for  the following four parameters
 #  Newton3: "enabled, disabled"
 #  DataLayout: "AoS, SoA"

src/ladds/CollisionFunctor.cpp

@@ -15,14 +15,17 @@
 #include "ladds/utils/DistanceApproximation.h"
 
 namespace LADDS {
-CollisionFunctor::CollisionFunctor(
-    double cutoff, double dt, double collisionDistanceFactor, double minDetectionRadius, double CDMcutoffInKM)
+CollisionFunctor::CollisionFunctor(double cutoff,
+                                   double dt,
+                                   double collisionDistanceFactor,
+                                   double minDetectionRadius,
+                                   double evasionTrackingCutoffInKM)
     : Functor(cutoff),
       _cutoffSquare(cutoff * cutoff),
       _dt(dt),
       _collisionDistanceFactor(collisionDistanceFactor / 1000.),  // also imply conversion from m to km
       _minDetectionRadius(minDetectionRadius),
-      _squaredCDMcutoffInKM(CDMcutoffInKM * CDMcutoffInKM) {
+      _squaredEvasionTrackingCutoffInKM(evasionTrackingCutoffInKM * evasionTrackingCutoffInKM) {
   _threadData.resize(autopas::autopas_get_max_threads());
 }
 
@@ -84,7 +87,7 @@ void CollisionFunctor::AoSFunctor(Particle &i, Particle &j, bool newton3) {
   // For evaded collisions we collect them at this point
   // and store pointers to colliding pair
   if (wasEvaded) {
-    if (distanceSquare_lines < _squaredCDMcutoffInKM) {
+    if (distanceSquare_lines < _squaredEvasionTrackingCutoffInKM) {
       return;
     }
     // compute potential collision point as middle between the two particles

src/ladds/CollisionFunctor.h

@@ -28,10 +28,13 @@ class CollisionFunctor final : public autopas::Functor<Particle, CollisionFuncto
    * @param collisionDistanceFactor See CollisionFunctor::_collisionDistanceFactor.
    * @param minDetectionRadius All particles with a larger radius are assumed to be detectable by radar.
    *        Thus collisions with particles that are Particle::ActivityState::evasive will not be considered.
-   * @param CDMcutoffInKM Absolute cutoff we consider for CDMs , that is tracking of evaded conjunctions.
+   * @param evasionTrackingCutoffInKM Absolute cutoff we consider for CDMs , that is tracking of evaded conjunctions.
    */
-  CollisionFunctor(
-      double cutoff, double dt, double collisionDistanceFactor, double minDetectionRadius, double CDMcutoffInKM);
+  CollisionFunctor(double cutoff,
+                   double dt,
+                   double collisionDistanceFactor,
+                   double minDetectionRadius,
+                   double evasionTrackingCutoffInKM);
 
   [[nodiscard]] bool isRelevantForTuning() final {
     return true;
@@ -122,7 +125,7 @@ class CollisionFunctor final : public autopas::Functor<Particle, CollisionFuncto
    * Squared of cutoff we consider for conjunction detection messages (CDMs) , that determines
    * whether we are tracking them as evaded conjunctions.
    */
-  const double _squaredCDMcutoffInKM;
+  const double _squaredEvasionTrackingCutoffInKM;
 };
 
 }  // namespace LADDS

src/ladds/Simulation.cpp

@@ -209,10 +209,10 @@ Simulation::collisionDetection(AutoPas_t &autopas,
                                double deltaT,
                                double collisionDistanceFactor,
                                double minDetectionRadius,
-                               double CDMcutoffInKM) {
+                               double evasionTrackingCutoffInKM) {
   // pairwise interaction
   CollisionFunctor collisionFunctor(
-      autopas.getCutoff(), deltaT, collisionDistanceFactor, minDetectionRadius, CDMcutoffInKM);
+      autopas.getCutoff(), deltaT, collisionDistanceFactor, minDetectionRadius, evasionTrackingCutoffInKM);
   bool stillTuning = autopas.iteratePairwise(&collisionFunctor);
   return {collisionFunctor.getCollisions(), collisionFunctor.getEvadedCollisions(), stillTuning};
 }
@@ -239,7 +239,7 @@ size_t Simulation::simulationLoop(AutoPas_t &autopas,
         logger.get(), "sim/timestepsPerCollisionDetection is {} but must not be <1!", timestepsPerCollisionDetection);
   }
   const auto minDetectionRadius = config.get<double>("sim/minDetectionRadius", 0.05);
-  const auto CDMcutoffInKM = config.get<double>("sim/CDMcutoffInKM", 0.1);
+  const auto evasionTrackingCutoffInKM = config.get<double>("sim/evasionTrackingCutoffInKM", 0.1);
   const auto minAltitude = config.get<double>("sim/minAltitude", 150.);
   std::vector<Particle> delayedInsertion;
 
@@ -345,7 +345,7 @@ size_t Simulation::simulationLoop(AutoPas_t &autopas,
                                                                     8.,
                                                                     collisionDistanceFactor,
                                                                     minDetectionRadius,
-                                                                    CDMcutoffInKM);
+                                                                    evasionTrackingCutoffInKM);
 
     timers.collisionDetectionImmigrants.stop();
 
@@ -392,7 +392,7 @@ size_t Simulation::simulationLoop(AutoPas_t &autopas,
                              deltaT * static_cast<double>(timestepsPerCollisionDetection),
                              collisionDistanceFactor,
                              minDetectionRadius,
-                             CDMcutoffInKM);
+                             evasionTrackingCutoffInKM);
       timers.collisionDetection.stop();
       totalConjunctions += collisions.size();
       if (collisions.size() > 0) {