Merge pull request #128 from esa/featureSchedule

Feature schedule

README.md

@@ -113,40 +113,27 @@ Data on current satellites etc. is often found [online](https://www.space-track.
 ## 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 
-`notebooks/ConstellationGeneration/ConstellationGeneration.ipynb` that can be used 
-to generate constellation data from orbital shell parameters.
+planes`, and `number of satellites` per plane. We provide a notebook
+[`notebooks/ConstellationGeneration/ConstellationGeneration.ipynb`](notebooks/ConstellationGeneration/ConstellationGeneration.ipynb) that can be used
 
-### Generating a constellation (quick guide):
-* Initialize the constellation by executing the first cell and providing metadata in the second cell (1)
-* Create a shell by providing the 4 shell arguments, and further parameters (extra params) if necessary (2.1).
-Store the temporary shell data by executing the cell (2.2)
-* Turn satellites into position and velocity vectors by executing cell (3)
-* Write the files by executing cell (4) and save them by executing cell (5)
+### How constellation satellites are inserted into the simulation
 
-A more detailed guide is included in the notebook.
-
-### Including the constellation data in simulation (`io` section):
-
-* In the configuration file for the simulation, include the constellation(s) by
-defining `constellationList` and assigning the constellation name(s); Syntax: 
-{name;}name ; e.g. Astra;Starlink;OneWeb
-* `constellationFrequency` (=interval for constellation insertion)
-* `constellationCutoff` (satellites are inserted with a delay, if there is an object within this range)
-* `altitudeSpread` ([km] ~99.74% of satellites with normally distributed altitude deviate
-by less than this value from the mean altitude [altitudeSpread = 3*sigma])
-
-### How constellation satellites are inserted to the simulation
-
-The insertion of a constellation takes as long as specified by the `duration` 
-parameter in the respective .yaml file. The time it takes to insert one shell of 
-a constellation depends on the percentage of satellites the shell contributes to 
-the constellation. Satellites of each orbital shell are inserted plane by plane 
+The insertion of a constellation takes as long as specified by the `duration`
+parameter in the respective .yaml file. The time it takes to insert one shell of
+a constellation depends on the percentage of satellites the shell contributes to
+the constellation. Satellites of each orbital shell are inserted plane by plane
 and linearly over time.
 
+### Including the constellation data in simulation (`io` section):
 
-
-
+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
+  the imprecision of orbital insertion. ~99.74% of satellites deviate by less than this value from the
+  mean altitude.
 
 ## Output
 
@@ -181,6 +168,4 @@ Due to burn ups or breakups the number of particles in any iteration might diffe
 To keep file size reasonable compression is supported.
 
 ### 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 data is written in a `.csv` file in ASCII layout.

cfg/default_cfg.yaml

@@ -6,6 +6,7 @@ sim:
     minutes: 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]
@@ -43,7 +44,7 @@ io:
     writeFrequency: 1000 # Frequency of writing to the hdf5 file [iterations]
     compressionLevel: 4 # Valid Levels: 0 (no compression) - 9 (max compression)
 
-  #constellationList: AstraPhase2 # ';'-seperated constellations consisting of path (to constellation directory), start time, duration
+  #constellationList: AstraPhase2 # ';'-separated constellations consisting of path (to constellation directory)
   constellationFrequency: 10 # Frequency of adding satellites to simulation [iterations]
   constellationCutoff: 0.1 # satellites of constellations are only inserted when there is no object within constellationCutoff range
   altitudeSpread: 1.0 # [km] normal distributed altitude deviations are usually smaller than this value (~99.74% chance)

data/.gitattributes

@@ -1,5 +1,4 @@
 initial_population.csv filter=lfs diff=lfs merge=lfs -text
 */pos_*.csv filter=lfs diff=lfs merge=lfs -text
 */v_*.csv filter=lfs diff=lfs merge=lfs -text
-*/shells_*.txt filter=lfs diff=lfs merge=lfs -text
-*/xparams_*.txt filter=lfs diff=lfs merge=lfs -text
+*/shells_*.yaml filter=lfs diff=lfs merge=lfs -text

notebooks/ConstellationGeneration/ConstellationGeneration.ipynb

@@ -13,14 +13,23 @@
    "id": "6ef7e733",
    "metadata": {},
    "source": [
+    "## Quick guide:\n",
+    "* Initialize the constellation by executing the first cell and providing metadata in the second cell (1)\n",
+    "* Create a shell by providing the 4 shell arguments, and further parameters (extra params) if necessary (2.1).\n",
+    "Store the temporary shell data by executing the cell (2.2)\n",
+    "* Turn satellites into position and velocity vectors by executing cell (3)\n",
+    "* Write the files by executing cell (4) and save them by executing cell (5)\n",
+    "\n",
+    "The following guide contains more detail\n",
+    "\n",
     "## Detailed guide:\n",
     "\n",
     "### 0. Execute the first cell to import libraries and initialize variables\n",
     "\n",
     "### 1. Initialize Constellation and reset planet_list and other lists\n",
     "Provide the constellation name, the time of launch `startTime` as well as\n",
     "the time it takes to fully deploy the constellation `duration` and execute the cell. \n",
-    "`startTime` can be specified as a date string with the format \"YYYY/MM/DD\". `duration` is specified as a string that contains a number of days followed by the 'd' character. If the variables are assigned plain integers, the values will be interpreted as simulation iterations.\n",
+    "`startTime` can be specified as a date string with the format \"YYYY-MM-DD\". `duration` is specified as a string that contains a number of days followed by the 'd' character. If the variables are assigned plain integers, the values will be interpreted as simulation iterations.\n",
     "### 2.1 Generate shell = ( altitude, inclination, nPlanes, nSats )\n",
     "The execution of this cell creates one temporary shell (each satellite is described by orbital elements) that is not yet a part of the constellation. It is possible to visualize the generated satellites by executing the cell `Plot current shell` before adding it to the constellation. Append the shell to the constellation by executing cell `2.2`. Each time the code of `2.1` is run, the temporary data is overridden by the new data.\n",
     "\n",
@@ -34,7 +43,7 @@
     "\n",
     "In some cases it is necessary to specify more parameters: `offsetM`, `argPeriapsis`,\n",
     "`startingW`, and `W_area`. It is best to modify them only if necessary and to use\n",
-    "the default values otherwise. Refer to the end of the description to see their usage\n",
+    "the default values otherwise. Refer to the end of the notebook to see their usage\n",
     "information (additional parameters).\n",
     "\n",
     "### 2.2 Append to elements_list and other\n",
@@ -53,44 +62,7 @@
     "Create a directory with the same name that was specified in `1` in the variable\n",
     "`constellation_name` in the `data` directory of the project. It contains three\n",
     "files: Two .csv files with positions and velocities and a .yaml file with the\n",
-    "metadata of the constellation.\n",
-    "\n",
-    "---\n",
-    "\n",
-    "### Additional parameters\n",
-    "### offsetM\n",
-    "`offsetM` is the step size for an offset that is added to each satellite's mean anomaly. The offset accumulates, meaning it increases by `offsetM` each time a new plane is generated. In a Walker Constellation, \n",
-    "which is a typical model for constellations, the parameter is assigned a value of the following form:\n",
-    "\n",
-    "`offsetM = F * 360 / (nPlanes*nSats)` \n",
-    "\n",
-    "Note: F is a natural number: F is element of {0, ... , nPlanes - 1}\n",
-    "\n",
-    "Note: the property of a set phasing difference\n",
-    "between neighboring planes gets lost if the shell is added over time (`duration` > 0)\n",
-    "\n",
-    "\n",
-    "\n",
-    "### argPeriapsis\n",
-    "`argPeriapsis` corresponds to the orbital element \"argument of periapsis\". Choosing an irrational number\n",
-    "prevents satellites from two symmetrical planes to have the same position.\n",
-    "\n",
-    "### startingW\n",
-    "`startingW` is the base value for the shell's longitude of ascending node (W). The parameter can be utilized if planes of different shells overlap. This occurs if shells have the same altitude and the same or similar inclination.\n",
-    "\n",
-    "The shells should follow the formula:\n",
-    "\n",
-    "`(360/G)*(i/N)`\n",
-    "\n",
-    "Note: G stands for the smallest common denominator of the nPlanes parameters of\n",
-    "each shell\n",
-    "\n",
-    "Note: N is the number of shells overlapping\n",
-    "\n",
-    "Note: i is an index in {0,...,N-1}. each shell should have a distinct i\n",
-    "\n",
-    "### W_area\n",
-    "this parameter determines which degree the planes of the shell span. The longitudes of ascending node are distributed in the range \\[startingW , startingW + W_area\\]."
+    "metadata of the constellation."
    ]
   },
   {
@@ -382,12 +354,45 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "c2328ea2",
+   "cell_type": "markdown",
+   "id": "19cfec21",
    "metadata": {},
-   "outputs": [],
-   "source": []
+   "source": [
+    "### Additional parameters\n",
+    "### offsetM\n",
+    "`offsetM` is the step size for an offset that is added to each satellite's mean anomaly. The offset accumulates, meaning it increases by `offsetM` each time a new plane is generated. In a Walker Constellation, \n",
+    "which is a typical model for constellations, the parameter is assigned a value of the following form:\n",
+    "\n",
+    "`offsetM = F * 360 / (nPlanes*nSats)` \n",
+    "\n",
+    "Note: F is a natural number: F is element of {0, ... , nPlanes - 1}\n",
+    "\n",
+    "Note: the property of a set phasing difference\n",
+    "between neighboring planes gets lost if the shell is added over time (`duration` > 0)\n",
+    "\n",
+    "\n",
+    "\n",
+    "### argPeriapsis\n",
+    "`argPeriapsis` corresponds to the orbital element \"argument of periapsis\". Choosing an irrational number\n",
+    "prevents satellites from two symmetrical planes to have the same position.\n",
+    "\n",
+    "### startingW\n",
+    "`startingW` is the base value for the shell's longitude of ascending node (W). The parameter can be utilized if planes of different shells overlap. This occurs if shells have the same altitude and the same or similar inclination.\n",
+    "\n",
+    "The shells should follow the formula:\n",
+    "\n",
+    "`(360/G)*(i/N)`\n",
+    "\n",
+    "Note: G stands for the smallest common denominator of the nPlanes parameters of\n",
+    "each shell\n",
+    "\n",
+    "Note: N is the number of shells overlapping\n",
+    "\n",
+    "Note: i is an index in {0,...,N-1}. each shell should have a distinct i\n",
+    "\n",
+    "### W_area\n",
+    "this parameter determines which degree the planes of the shell span. The longitudes of ascending node are distributed in the range \\[startingW , startingW + W_area\\]."
+   ]
   }
  ],
  "metadata": {

src/ladds/Simulation.cpp

@@ -224,9 +224,12 @@ size_t Simulation::simulationLoop(AutoPas_t &autopas,
 
   const auto [hdf5WriteFrequency, hdf5Writer, conjuctionWriter] = initWriter(config);
 
+  // set constellation particle IDs and fetch maxExistingParticleId
+  const size_t maxExistingParticleId = setConstellationIDs(autopas, constellations);
   // only add the breakup model if enabled via yaml
   const std::unique_ptr<BreakupWrapper> breakupWrapper =
-      config.get<bool>("sim/breakup/enabled") ? std::make_unique<BreakupWrapper>(config, autopas) : nullptr;
+      config.get<bool>("sim/breakup/enabled") ? std::make_unique<BreakupWrapper>(config, autopas, maxExistingParticleId)
+                                              : nullptr;
 
   const auto timeout = computeTimeout(config);
 
@@ -362,6 +365,25 @@ std::vector<Particle> Simulation::checkedInsert(autopas::AutoPas<Particle> &auto
   return delayedInsertion;
 }
 
+size_t Simulation::setConstellationIDs(autopas::AutoPas<Particle> &autopas,
+                                       std::vector<Constellation> &constellations) {
+  size_t nextBaseId = 0;
+  // 1. find highest existing particle id
+  // Particles are not sorted by id and might neither be starting by 0 nor be consecutive (e.g. due to burn-ups)
+  // therefore we have to go through all of them
+  for (const auto &p : autopas) {
+    nextBaseId = std::max(nextBaseId, p.getID());
+  }
+  nextBaseId += 1;
+  // 2. distribute globally unique ids for constellation satellites
+  for (auto &constellation : constellations) {
+    constellation.moveConstellationIDs(nextBaseId);
+    nextBaseId += constellation.getConstellationSize();
+  }
+  // 3. return new maxExistingParticleId
+  return nextBaseId - 1;
+}
+
 void Simulation::run(ConfigReader &config) {
   timers.total.start();
 

src/ladds/Simulation.h

@@ -127,6 +127,14 @@ class Simulation {
                                       const std::vector<Particle> &newSatellites,
                                       double constellationCutoff);
 
+  /**
+   * Distributes global IDs for all constellation particles and returns the resulting maxExistingParticleId.
+   * @param autopas
+   * @param constellations
+   * @return size_t maxExistingParticleId
+   */
+  size_t setConstellationIDs(autopas::AutoPas<Particle> &autopas, std::vector<Constellation> &constellations);
+
   /**
    * Remove all particles below a certain altitude from the particle container.
    * @param autopas

src/ladds/io/SatelliteLoader.cpp

@@ -84,20 +84,12 @@ void SatelliteLoader::loadSatellites(AutoPas_t &autopas, ConfigReader &config, c
 
 std::vector<Constellation> SatelliteLoader::loadConstellations(ConfigReader &config, const Logger &logger) {
   std::vector<Constellation> constellations;
-  auto coefficientOfDrag = config.get<double>("sim/prop/coefficientOfDrag");
   auto constellationList = config.get<std::string>("io/constellationList", "", true);
-  // altitudeSpread = 3 * sigma , altitudeDeviation = sigma (= standardDeviation)
-  auto altitudeDeviation = config.get<double>("io/altitudeSpread", 0.0) / 3.0;
   if (not constellationList.empty()) {
     const auto insertionFrequency = config.get<int>("io/constellationFrequency", 1);
     auto constellationDataStr = config.get<std::string>("io/constellationList");
     // count constellation by counting ';'
-    int nConstellations = 1;
-    for (char con : constellationDataStr) {
-      if (con == ';') {
-        nConstellations++;
-      }
-    }
+    int nConstellations = std::count(constellationDataStr.begin(), constellationDataStr.end(), ';') + 1;
 
     // parse constellation info
     constellations.reserve(nConstellations);
@@ -109,8 +101,7 @@ std::vector<Constellation> SatelliteLoader::loadConstellations(ConfigReader &con
       ConfigReader constellationConfig =
           ConfigReader(std::string(DATADIR) + constellationDir + "/shells_" + constellationDir + ".yaml", logger);
 
-      constellations.emplace_back(
-          Constellation(constellationConfig, insertionFrequency, altitudeDeviation, coefficientOfDrag));
+      constellations.emplace_back(Constellation(constellationConfig, config));
       if (i != nConstellations - 1) {
         constellationDataStr.erase(0, offset + 1);
       }
@@ -125,6 +116,16 @@ std::vector<Constellation> SatelliteLoader::loadConstellations(ConfigReader &con
                        "{} more particles will be added from {} constellations",
                        constellationTotalNumSatellites,
                        nConstellations);
+
+    for (const auto &c : constellations) {
+      SPDLOG_LOGGER_INFO(
+          logger.get(),
+          "{}: insertion starts at iteration: {}, is fully deployed within {} iterations, inserts {} satellites",
+          c.getConstellationName(),
+          c.getStartTime(),
+          c.getDuration(),
+          c.getConstellationSize());
+    }
   }
   return constellations;
 }