Merge pull request #34 from motrieu/feature/finalComments/nina

add comments

Author: simongrether

src/computation/computationParallel.cpp

@@ -112,6 +112,7 @@ void ComputationParallel::applyBCOnDirichletBoundary()
 
     if (partitioning_.ownPartitionContainsBottomBoundary())
     {
+        // shiftIBeginV and shiftIEndV handle priority of boundary conditions
         int shiftIBeginV = 0;
         int shiftIEndV = 0;
         if (!partitioning_.ownPartitionContainsLeftBoundary())
@@ -126,6 +127,7 @@ void ComputationParallel::applyBCOnDirichletBoundary()
 
     if (partitioning_.ownPartitionContainsTopBoundary())
     {
+        // shiftIBeginV and shiftIEndV handle priority of boundary conditions
         int shiftIBeginV = 0;
         int shiftIEndV = 0;
         if (!partitioning_.ownPartitionContainsLeftBoundary())
@@ -196,6 +198,7 @@ void ComputationParallel::applyBCInHaloCellsAtDirichletBoundary()
 
     if (partitioning_.ownPartitionContainsBottomBoundary())
     {
+        // shiftIBeginU and shiftIEndU handle priority of boundary conditions
         int shiftIBeginU = 0;
         int shiftIEndU = 0;
         if (!partitioning_.ownPartitionContainsLeftBoundary())
@@ -213,6 +216,7 @@ void ComputationParallel::applyBCInHaloCellsAtDirichletBoundary()
 
     if (partitioning_.ownPartitionContainsTopBoundary())
     {
+        // shiftIBeginU and shiftIEndU handle priority of boundary conditions
         int shiftIBeginU = 0;
         int shiftIEndU = 0;
         if (!partitioning_.ownPartitionContainsLeftBoundary())
@@ -235,19 +239,21 @@ void ComputationParallel::receiveAndSendDiagonalPressureFromAndToOtherProcess()
 
     std::vector<double> diagonalPBuffer(1);
 
+    // if the current rank has a lower-left neighbour, the own p(1,1)-value is sent to that neighbour
     if ((!partitioning_.ownPartitionContainsLeftBoundary()) && (!partitioning_.ownPartitionContainsBottomBoundary()))
     {
         diagonalPBuffer[0] = (*discretization_).p(1,1);
 
         MPI_Isend(diagonalPBuffer.data(), 1, MPI_DOUBLE, partitioning_.bottomNeighbourRankNo()-1, 0, MPI_COMM_WORLD, &diagonalRequest);
     }
 
+    // if the current rank has an upper-right neighbour, the current rank receives the p(1,1)-value from that neighbour
     if ((!partitioning_.ownPartitionContainsRightBoundary()) && (!partitioning_.ownPartitionContainsTopBoundary()))
     {
         MPI_Irecv(diagonalPBuffer.data(), 1, MPI_DOUBLE, partitioning_.topNeighbourRankNo()+1, 0, MPI_COMM_WORLD, &diagonalRequest);
     }
 
-
+    // the received p-value is then stored at p(N+1,N+1)
     if ((!partitioning_.ownPartitionContainsRightBoundary()) && (!partitioning_.ownPartitionContainsTopBoundary()))
     {
         MPI_Wait(&diagonalRequest, MPI_STATUS_IGNORE);
@@ -264,6 +270,9 @@ void ComputationParallel::receiveAndSendVelocitiesFromAndToOtherProcesses()
     MPI_Request upperRequest;
 
     std::vector<double> leftUVBuffer(2*nCellsY_);
+
+    // if current rank does not contain left Dirichlet boundary, 
+    // then u and v need to be communicated between the current rank and its left neighbour rank
     if (!partitioning_.ownPartitionContainsLeftBoundary())
     {
         for (int j = 1; j < nCellsY_+1; j++)
@@ -278,6 +287,9 @@ void ComputationParallel::receiveAndSendVelocitiesFromAndToOtherProcesses()
     }
 
     std::vector<double> rightUVBuffer(2*nCellsY_);
+
+    // if current rank does not contain right Dirichlet boundary, 
+    // then u and v need to be communicated between the current rank and its right neighbour rank
     if (!partitioning_.ownPartitionContainsRightBoundary())
     {
         for (int j = 1; j < nCellsY_+1; j++)
@@ -292,6 +304,9 @@ void ComputationParallel::receiveAndSendVelocitiesFromAndToOtherProcesses()
     }
 
     std::vector<double> lowerUVBuffer(2*nCellsX_);
+
+    // if current rank does not contain bottom Dirichlet boundary, 
+    // then u and v need to be communicated between the current rank and its lower neighbour rank
     if (!partitioning_.ownPartitionContainsBottomBoundary())
     {
         for (int i = 1; i < nCellsX_+1; i++)
@@ -306,6 +321,9 @@ void ComputationParallel::receiveAndSendVelocitiesFromAndToOtherProcesses()
     }
 
     std::vector<double> upperUVBuffer(2*nCellsX_);
+
+    // if current rank does not contain top Dirichlet boundary, 
+    // then u and v need to be communicated between the current rank and its upper neighbour rank
     if (!partitioning_.ownPartitionContainsTopBoundary())
     {
         for (int i = 1; i < nCellsX_+1; i++)
@@ -319,6 +337,8 @@ void ComputationParallel::receiveAndSendVelocitiesFromAndToOtherProcesses()
         MPI_Irecv(upperUVBuffer.data(), 2*nCellsX_, MPI_DOUBLE, partitioning_.topNeighbourRankNo(), 0, MPI_COMM_WORLD, &upperRequest);
     }
 
+    // received values are now written to the right place
+
     if (!partitioning_.ownPartitionContainsLeftBoundary())
     {
         MPI_Wait(&leftRequest, MPI_STATUSES_IGNORE);
@@ -359,13 +379,14 @@ void ComputationParallel::receiveAndSendVelocitiesFromAndToOtherProcesses()
         }  
     }
 
-
+    // diagonal communication
     MPI_Request leftUpperDiagonalRequest;
     MPI_Request rightLowerDiagonalRequest;
 
     std::vector<double> leftUpperDiagonalBuffer(1);
     std::vector<double> rightLowerDiagonalBuffer(1);
 
+    // if current rank has an upper-left neighbour, v(1,nCellsY_) needs to be communicated since it is needed in the donor cell scheme
     if (!partitioning_.ownPartitionContainsLeftBoundary() && !partitioning_.ownPartitionContainsTopBoundary())
     {
         leftUpperDiagonalBuffer[0] = (*discretization_).v(1,nCellsY_);
@@ -375,6 +396,7 @@ void ComputationParallel::receiveAndSendVelocitiesFromAndToOtherProcesses()
         MPI_Irecv(leftUpperDiagonalBuffer.data(), 1, MPI_DOUBLE, partitioning_.topNeighbourRankNo()-1, 0, MPI_COMM_WORLD, &leftUpperDiagonalRequest);
     }
 
+    // if current rank has a lower-right neighbour, u(nCellsX_,1) needs to be communicated since it is needed in the donor cell scheme
     if (!partitioning_.ownPartitionContainsRightBoundary() && !partitioning_.ownPartitionContainsBottomBoundary())
     {
         rightLowerDiagonalBuffer[0] = (*discretization_).u(nCellsX_,1);
@@ -461,6 +483,7 @@ void ComputationParallel::receiveAndSendPreliminaryVelocitiesFromAndToOtherProce
     std::vector<double> sendRightFBuffer(nCellsY_);
     std::vector<double> sendUpperGBuffer(nCellsX_);
 
+    // if current rank does not have a right Dirichlet boundary, then F on the local right boundary is sent to the right neighbour
     if (!partitioning_.ownPartitionContainsRightBoundary())
     {
         for (int j = 1; j < nCellsY_+1; j++)
@@ -469,6 +492,7 @@ void ComputationParallel::receiveAndSendPreliminaryVelocitiesFromAndToOtherProce
         MPI_Isend(sendRightFBuffer.data(), nCellsY_, MPI_DOUBLE, partitioning_.rightNeighbourRankNo(), 0, MPI_COMM_WORLD, &rightRequest);
     }
 
+    // if current rank does not have a top Dirichlet boundary, then G on the local top boundary is sent to the upper neighbour
     if (!partitioning_.ownPartitionContainsTopBoundary())
     {
         for (int i = 1; i < nCellsX_+1; i++)
@@ -477,11 +501,13 @@ void ComputationParallel::receiveAndSendPreliminaryVelocitiesFromAndToOtherProce
         MPI_Isend(sendUpperGBuffer.data(), nCellsX_, MPI_DOUBLE, partitioning_.topNeighbourRankNo(), 0, MPI_COMM_WORLD, &upperRequest);
     }
 
+    // if current rank does not have a left Dirichlet boundary, then F on the local left boundary is received from the left neighbour
     if (!partitioning_.ownPartitionContainsLeftBoundary())
     {
         MPI_Irecv(receiveLeftFBuffer.data(), nCellsY_, MPI_DOUBLE, partitioning_.leftNeighbourRankNo(), 0, MPI_COMM_WORLD, &leftRequest);
     }
 
+    // if current rank does not have a bottom Dirichlet boundary, then G on the local bottom boundary is received from the bottom neighbour
     if (!partitioning_.ownPartitionContainsBottomBoundary())
     {
         MPI_Irecv(receiveLowerGBuffer.data(), nCellsX_, MPI_DOUBLE, partitioning_.bottomNeighbourRankNo(), 0, MPI_COMM_WORLD, &lowerRequest);
@@ -522,6 +548,7 @@ void ComputationParallel::computePressure()
 
 void ComputationParallel::computeVelocities()
 {
+    // shift parameters determine whether new velocities u and v also need to be calculated at local boundary of the current rank
     int shiftIEndU = 0;
     int shiftJEndV = 0;
     if (!partitioning_.ownPartitionContainsRightBoundary())

src/computation/computationParallel.h

@@ -11,30 +11,76 @@
 class ComputationParallel : public Computation
 {
 public:
+    /// @brief solves the Navier-Stokes equations by partitioning the domain and therefore calculating parallelly
+    ///        the algorithm loops over time and calculates for each time step the updated velocities u and v, the
+    ///        pressure p based on the checker board scheme, the preliminary velocities F and G and the right hand side of the pressure Poisson problem (rhs)
     void runSimulation();
+   
+    /// @brief initializes all objects needed in order to solve the Navier-Stokes equations parallelly
+    ///        reads in the parameters from the given parameter file
+    ///        decides based on parameter file which discretization scheme to choose
+    /// @param argc number of arguments parsed in the command line, must be equal to 2
+    /// @param argv the arguments parsed in the command line, contains the file name of the parameter file
     void initialize(int argc, char *argv[]);
 
 private:
+    /// @brief checks if current rank contains Dirichlet boundary
+    ///        sets boundary conditions of u and v on the local boundary based on given Dirichlet conditions
+    ///        handles priority of boundary conditions by introducing shifting parameters for v
     void applyBCOnDirichletBoundary();
+
+    /// @brief checks if current rank contains Dirichlet boundary
+    ///        sets boundary conditions of f and g on the local boundary based on given Dirichlet conditions
     void applyPreliminaryBCOnDirichletBoundary();
+
+    /// @brief checks if current rank contains Dirichlet boundary
+    ///        sets boundary conditions of u and v in halo cells based on given Dirichlet conditions and inner cell values
+    ///        handles priority of boundary conditions by introducing shifting parameters for u
     void applyBCInHaloCellsAtDirichletBoundary();
 
-    //for output
+    /// @brief diagonal pressure communication for interpolate function and output 
+    ///        if the current rank has a lower-left neighbour, the own p(1,1)-value is sent to that neighbour
+    ///        if the current rank has an upper-right neighbour, the current rank receives the p(1,1)-value from that neighbour
     void receiveAndSendDiagonalPressureFromAndToOtherProcess();
+
+    /// @brief u and v communication
+    ///        checks if current rank contains Dirichlet boundary
+    ///        if current rank does not contain a certain Dirichlet boundary, then the calculated u and v need to be communicated with the corresponding neighbour
+    ///        function also computes diagonal communication of u and v needed for donor cell scheme
     void receiveAndSendVelocitiesFromAndToOtherProcesses();
+
+    /// @brief computes common time step width for all processes by using serial computeTimeStepWidth()-function
+    ///        finds the minimum of all possible time step widths via MPI-function MPI_Allreduce and the operation MPI_MIN
     void computeTimeStepWidthParallel();
+
+    /// @brief computes preliminary velocities F and G
+    ///        if current rank does not have a right Dirichlet boundary, then F is also calculated on the right boundary of that rank
+    ///        if current rank does not have a top Dirichlet boundary, then G is also calculated on the upper boundary of that rank
     void computePreliminaryVelocities();
+
+    /// @brief F and G communication
+    ///        checks if current rank contains Dirichlet boundaries
+    ///        if current rank does not contain Dirichlet boundary, then F or G need to be sent or received from one of its neighbours
     void receiveAndSendPreliminaryVelocitiesFromAndToOtherProcesses();
+
+    /// @brief computes pressure by using the selected parallel pressure solver SOR-algorithm with checker board pattern
     void computePressure();
+
+    /// @brief computes new velocities u and v
+    ///        depending on whether current rank contains Dirichlet boundary or not, the new velocities u and v are also computed on the local boundary of that rank
+    ///        this is handled by parameters called shiftIEndU and shiftJEndV
     void computeVelocities();
 
-
+    /// @brief shared pointer to the parallel pressure solver (SOR)
     std::unique_ptr<PressureSolverParallel> pressureSolverParallel_;
 
+    /// @brief unique pointer to the parallel output writer which produces vtk-output
     std::unique_ptr<OutputWriterParaviewParallel> outputWriterParaviewParallel_;
 
+    /// @brief unique pointer to the parallel output writer which produces readable txt-files
     std::unique_ptr<OutputWriterTextParallel> outputWriterTextParallel_;
 
+    /// @brief contains information about the partition of the physical domain needed for MPI
     Partitioning partitioning_;
 
     /// @brief number of elements in x direction for this process (halo cells not included)

src/pressure_solver/pressureSolverParallel.cpp

@@ -32,12 +32,15 @@ void PressureSolverParallel::setDiagonalBoundaryValuesOnDirichletParallelForOutp
     // handles upper-left corner
     if (partitioning_.ownPartitionContainsLeftBoundary())
         (*discretization_).p(pIBegin_-1,pJEnd_) = (*discretization_).p(pIBegin_,pJEnd_);
+
     // handles lower-left corner
     if ((partitioning_.ownPartitionContainsLeftBoundary()) && (partitioning_.ownPartitionContainsBottomBoundary()))
         (*discretization_).p(pIBegin_-1,pJBegin_-1) = (*discretization_).p(pIBegin_,pJBegin_);
+
     // handles lower-right corner
     if (partitioning_.ownPartitionContainsBottomBoundary())
         (*discretization_).p(pIEnd_,pJBegin_-1) = (*discretization_).p(pIEnd_,pJBegin_);
+        
     // handles upper-right corner
     if (partitioning_.ownPartitionContainsRightBoundary())
         (*discretization_).p(pIEnd_,pJEnd_) = (*discretization_).p(pIEnd_-1,pJEnd_);

src/pressure_solver/pressureSolverParallel.h

@@ -15,6 +15,7 @@ class PressureSolverParallel : public PressureSolver
     /// @param partitioning contains information about the partition of the physical domain needed for MPI
     PressureSolverParallel(std::shared_ptr<Discretization> discretization, double epsilon, int maximumNumberOfIterations, Partitioning partitioning);
 
+    /// @brief handles pressure values in the corner halo cells when Dirichlet boundary exists (needs to be done for output)
     void setDiagonalBoundaryValuesOnDirichletParallelForOutput();
 
 protected:
@@ -103,5 +104,6 @@ class PressureSolverParallel : public PressureSolver
     /// @brief number of elements in y direction for this process (halo cells not included)
     int nCellsY_;
 
+    /// @brief number of global cells
     double numberOfValuesGlobal_;
 };