feat: documentation

advection/src/AdvectionKernel.h

@@ -7,8 +7,19 @@
 
 #define DT 50
 
+/*
+ * Implement this class for every integration method.
+ */
 class AdvectionKernel {
 public:
+    /**
+     * This function must take a time, latitude and longitude of a particle and must output
+     * a new latitude and longitude after being advected once for DT time as defined above.
+     * @param time Time since the beginning of the data
+     * @param latitude Latitude of particle
+     * @param longitude Longitude of particle
+     * @return A pair of latitude and longitude of particle.
+     */
     virtual std::pair<double, double> advect(int time, double latitude, double longitude) const = 0;
 };
 

advection/src/EulerAdvectionKernel.h

@@ -4,6 +4,14 @@
 #include "AdvectionKernel.h"
 #include "UVGrid.h"
 
+/**
+ * Implementation of AdvectionKernel.
+ * The basic equation is:
+ * new_latitude = latitude + u*DT
+ * new_longitude = longitude + v*DT
+ *
+ * Uses bilinear interpolation as implemented in interpolate.h
+ */
 class EulerAdvectionKernel: public AdvectionKernel {
 private:
     std::shared_ptr<UVGrid> grid;

advection/src/RK4AdvectionKernel.h

@@ -5,6 +5,11 @@
 #include "AdvectionKernel.h"
 #include "UVGrid.h"
 
+/**
+ * Implementation of Advection kernel using RK4 integration
+ * See https://en.wikipedia.org/wiki/Runge%E2%80%93Kutta_methods for more details.
+ * Uses bilinear interpolation as implemented in interpolate.h
+ */
 class RK4AdvectionKernel: public AdvectionKernel {
 private:
     std::shared_ptr<UVGrid> grid;

advection/src/UVGrid.h

@@ -13,6 +13,9 @@ private:
 public:
     UVGrid();
 
+    /**
+     * The matrix has shape (timeSize, latSize, lonSize)
+     */
     size_t timeSize;
     size_t latSize;
     size_t lonSize;
@@ -35,6 +38,12 @@ public:
      */
     int timeStep() const;
 
+    /**
+     * times, lats, lons are vector of length timeSize, latSize, lonSize respectively.
+     * The maintain the following invariant:
+     * grid[timeIndex,latIndex,lonIndex] gives the u,v at the point with latitude at lats[latIndex],
+     * with longitude at lons[lonIndex], and with time at times[timeIndex].
+     */
     std::vector<int> times;
     std::vector<double> lats;
     std::vector<double> lons;
@@ -45,6 +54,11 @@ public:
      */
     const Vel& operator[](size_t timeIndex, size_t latIndex, size_t lonIndex) const;
 
+    /**
+     * Streams a slice at timeIndex t of the matrix to the outstream given by os
+     * @param os outstream
+     * @param t index with which to slice matrix
+     */
     void streamSlice(std::ostream &os, size_t t);
 };
 

advection/src/main.cpp

@@ -11,7 +11,10 @@ using namespace std;
 
 template <typename AdvectionKernelImpl>
 void advectForSomeTime(const UVGrid &uvGrid, const AdvectionKernelImpl &kernel, double latstart, double lonstart) {
+
+    // Require at compile time that kernel derives from the abstract class AdvectionKernel
     static_assert(std::is_base_of<AdvectionKernel, AdvectionKernelImpl>::value, NotAKernelError);
+
     double lat1 = latstart, lon1 = lonstart;
     for(int time = 100; time <= 10000; time += DT) {
         cout << "lat = " << lat1 << " lon = " << lon1 << endl;
@@ -24,7 +27,6 @@ void advectForSomeTime(const UVGrid &uvGrid, const AdvectionKernelImpl &kernel,
 
 int main() {
     std::shared_ptr<UVGrid> uvGrid = std::make_shared<UVGrid>();
-//    uvGrid->streamSlice(cout, 100);
 
     EulerAdvectionKernel kernelEuler = EulerAdvectionKernel(uvGrid);