Merge branch '11-comment-and-error-handling' into 'hannes-philipp'

Resolve "comment and error handling"

See merge request naaice/tug!10

include/tug/Boundary.hpp

@@ -1,3 +1,9 @@
+/**
+ * @file Boundary.hpp
+ * @brief 
+ * 
+ * 
+ */
 #ifndef BOUNDARY_H_
 #define BOUNDARY_H_
 
@@ -20,71 +26,168 @@ enum BC_SIDE {
     BC_SIDE_BOTTOM
 };
 
+/**
+ * This class defines the boundary conditions of individual boundary elements.
+ * These can be flexibly used and combined later in other classes.
+ * The class serves as an auxiliary class for structuring the Boundary class.
+ */
 class BoundaryElement {
     public:
         // bc type closed
-        BoundaryElement();
+      /**
+       * @brief Construct a new Boundary Element object for the closed case.
+       *        The boundary type is here automatically set to the type
+       *        BC_TYPE_CLOSED, where the value takes NaN.
+       */
+      BoundaryElement();
 
-        // bc type constant
+      /**
-        BoundaryElement(double value);
+       * @brief Construct a new Boundary Element object for the constant case.
+       *        The boundary type is automatically set to the type
+       * BC_TYPE_CONSTANT.
+       *
+       * @param value Value of the constant concentration to be assumed at the
+       *              corresponding boundary element. 
+       */
+      BoundaryElement(double value);
 
-        void setType(BC_TYPE type);
+      /**
+       * @brief Allows changing the boundary type of a corresponding
+       *        BoundaryElement object.
+       *
+       * @param type Type of boundary condition. Either BC_TYPE_CONSTANT or
+                     BC_TYPE_CLOSED. 
+       */
+      void setType(BC_TYPE type);
+      
+      /**
+       * @brief Sets the value of a boundary condition for the constant case.
+       * 
+       * @param value Concentration to be considered constant for the 
+       *              corresponding boundary element.
+       */
+      void setValue(double value);
 
-        void setValue(double value);
+      /**
+       * @brief Return the type of the boundary condition, i.e. whether the
+       *        boundary is considered closed or constant.
+       *
+       * @return BC_TYPE Type of boundary condition, either BC_TYPE_CLOSED or
+                 BC_TYPE_CONSTANT.
+       */
+      BC_TYPE getType();
 
-        BC_TYPE getType();
+      /**
-
+       * @brief Return the concentration value for the constant boundary condition.
-        double getValue();
+       * 
+       * @return double Value of the concentration.
+       */
+      double getValue();
 
     private:
         BC_TYPE type;
         double value;
 };
 
-class BoundaryWall {
-    public: 
-        BoundaryWall(int length);
-
-        void setWall(BC_TYPE type, double value = NAN);
-
-        vector<BoundaryElement> getWall();
-
-        void setBoundaryElement(int index, BC_TYPE type, double value = NAN);
-
-        BoundaryElement getBoundaryElement();
-
-    private:
-        BC_SIDE side;
-        int length;
-        vector<BoundaryElement> wall;
-
-};
 
+/**
+ * This class implements the functionality and management of the boundary
+ * conditions in the grid to be simulated.
+ * This class implements the functionality and management of the boundary
+ * conditions in the grid to be simulated.
+ */
 class Boundary {
     public:
+      /**
+       * @brief Creates a boundary object based on the passed grid object and
+       *        initializes the boundaries as closed.
+       *
+       * @param grid Grid object on the basis of which the simulation is to take place.
+       */
+      Boundary(Grid grid);
 
-        /**
+      /**
-         * @brief Construct a new Boundary object
+       * @brief Sets all elements of the specified boundary side to the boundary
-         * 
+       *        condition closed.
-         * @param grid 
+       *
-         */
+       * @param side Side to be set to closed, e.g. BC_SIDE_LEFT.
-        Boundary(Grid grid);
+       */
+      void setBoundarySideClosed(BC_SIDE side);
 
-        void setBoundarySideClosed(BC_SIDE side);
+      /**
+       * @brief Sets all elements of the specified boundary side to the boundary
+       *        condition constant. Thereby the concentration values of the
+       *        boundaries are set to the passed value.
+       *
+       * @param side Side to be set to constant, e.g. BC_SIDE_LEFT.
+       * @param value Concentration to be set for all elements of the specified page.
+       */
+      void setBoundarySideConstant(BC_SIDE side, double value);
 
-        void setBoundarySideConstant(BC_SIDE side, double value);
+      /**
+       * @brief Specifically sets the boundary element of the specified side
+       *        defined by the index to the boundary condition closed.
+       *
+       * @param side Side in which an element is to be defined as closed.
+       * @param index Index of the boundary element on the corresponding
+       *              boundary side. Must index an element of the corresponding side.
+       */
+      void setBoundaryElementClosed(BC_SIDE side, int index);
 
-        void setBoundaryElementClosed(BC_SIDE side, int index);
+      /**
+       * @brief Specifically sets the boundary element of the specified side
+       *        defined by the index to the boundary condition constant with the
+                given concentration value.
+       * 
+       * @param side Side in which an element is to be defined as constant.
+       * @param index Index of the boundary element on the corresponding
+       *              boundary side. Must index an element of the corresponding side.
+       * @param value Concentration value to which the boundary element should be set.
+       */
+      void setBoundaryElementConstant(BC_SIDE side, int index, double value);
 
-        void setBoundaryElementConstant(BC_SIDE side, int index, double value);
+      /**
+       * @brief Returns the boundary condition of a specified side as a vector
+       *        of BoundarsElement objects.
+       *
+       * @param side Boundary side from which the boundaryconditions are to be returned.
+       * @return vector<BoundaryElement> Contains the boundary conditions as BoundaryElement objects.
+       */
+      vector<BoundaryElement> getBoundarySide(BC_SIDE side);
 
-        vector<BoundaryElement> getBoundarySide(BC_SIDE side);
+      /**
+       * @brief Returns the boundary condition of a specified element on a given side.
+       * 
+       * @param side Boundary side in which the boundary condition is located.
+       * @param index Index of the boundary element on the corresponding
+       *              boundary side. Must index an element of the corresponding side.
+       * @return BoundaryElement Boundary condition as a BoundaryElement object.
+       */
+      BoundaryElement getBoundaryElement(BC_SIDE side, int index);
 
-        BoundaryElement getBoundaryElement(BC_SIDE side, int index);
+      /**
+       * @brief Returns the type of a boundary condition, i.e. either BC_TYPE_CLOSED or
+                BC_TYPE_CONSTANT.
+       * 
+       * @param side Boundary side in which the boundary condition type is located.
+       * @param index Index of the boundary element on the corresponding
+       *              boundary side. Must index an element of the corresponding side.
+       * @return BC_TYPE Boundary Type of the corresponding boundary condition.
+       */  
+      BC_TYPE getBoundaryElementType(BC_SIDE side, int index);
 
-        BC_TYPE getBoundaryElementType(BC_SIDE side, int index);
+      /**
-
+       * @brief Returns the concentration value of a corresponding
-        double getBoundaryElementValue(BC_SIDE side, int index);
+       *        BoundaryElement object if it is a constant boundary condition.
+       *
+       * @param side Boundary side in which the boundary condition value is
+       *             located.
+       * @param index Index of the boundary element on the corresponding
+       *              boundary side. Must index an element of the corresponding
+       *              side.
+       * @return double Concentration of the corresponding BoundaryElement object.
+       */
+      double getBoundaryElementValue(BC_SIDE side, int index);
 
     private:
         Grid grid;

include/tug/Simulation.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file Simulation.hpp
+ * @brief  
+ */
 #include "Boundary.hpp"
 #include <ios>
 
@@ -27,87 +31,118 @@ enum TIME_MEASURE {
     TIME_MEASURE_VERBOSE // print time measures after each iteration
 };
 
+/**
+ * @brief The class forms the interface for performing the diffusion simulations
+ * and contains all the methods for controlling the desired parameters, such as
+ * time step, number of simulations, etc.
+ *
+ */
 class Simulation {
     public:
+      /**
+       * @brief Set up a runnable simulation environment with the largest stable
+       *        time step and 1000 iterations by passing the required parameters.
+       *
+       * @param grid Valid grid object
+       * @param bc Valid boundary condition object
+       * @param approach Approach to solving the problem. Either FTCS or BTCS.
+       */
+      Simulation(Grid &grid, Boundary &bc, APPROACH approach);
 
-        /**
+      /**
-         * @brief Construct a new Simulation object
+       * @brief Set the option to output the results to a CSV file.
-         * 
+       *
-         * @param grid 
+       *
-         * @param bc 
+       * @param csv_output Valid output option. The following options can be set
-         * @param aproach 
+       *                   here:
-         */
+       *                     - CSV_OUTPUT_OFF: do not produce csv output
-        Simulation(Grid &grid, Boundary &bc, APPROACH approach);
+       *                     - CSV_OUTPUT_ON: produce csv output with last
+       *                       concentration matrix
+       *                     - CSV_OUTPUT_VERBOSE: produce csv output with all
+       *                       concentration matrices
+       *                     - CSV_OUTPUT_XTREME: produce csv output with all
+       *                       concentration matrices and simulation environment
+       */
+      void setOutputCSV(CSV_OUTPUT csv_output);
 
-        /**
+      /**
-         * @brief 
+       * @brief Set the options for outputting information to the console.
-         * 
+       *
-         * @param csv_output 
+       * @param console_output Valid output option. The following options can be set
-         */
+       *                       here:
-        void setOutputCSV(CSV_OUTPUT csv_output);
+       *                        - CONSOLE_OUTPUT_OFF: do not print any output to console
+       *                        - CONSOLE_OUTPUT_ON: print before and after concentrations to console
+       *                        - CONSOLE_OUTPUT_VERBOSE: print all concentration matrices to console
+       */
+      void setOutputConsole(CONSOLE_OUTPUT console_output);
 
-        /**
+      /**
-         * @brief Set the Output Console object
+       * @brief Set the Time Measure object
-         * 
+       *
-         * @param console_output 
+       * @param time_measure
-         */
+       */
-        void setOutputConsole(CONSOLE_OUTPUT console_output);
+      void setTimeMeasure(TIME_MEASURE time_measure);
 
-        /**
+      /**
-         * @brief Set the Time Measure object
+       * @brief Setting the time step for each iteration step. Time step must be
-         * 
+       *        greater than zero.
-         * @param time_measure 
+       *
-         */
+       * @param timestep Valid timestep greater than zero. 
-        void setTimeMeasure(TIME_MEASURE time_measure);
+       */
+      void setTimestep(double timestep);
 
-        /**
+      /**
-         * @brief Set the Timestep object
+       * @brief Currently set time step is returned.
-         * 
+       * 
-         * @param timetstep 
+       * @return double timestep
-         */
+       */
-        void setTimestep(double timetstep);
+      double getTimestep();
 
-        /**
+      /**
-         * @brief Get the Timestep object
+       * @brief Set the desired iterations to be calculated. A value greater
-         * 
+       *        than zero must be specified here.
-         */
+       *
-        double getTimestep();
+       * @param iterations Number of iterations to be simulated.
+       */
+      void setIterations(int iterations);
 
-        /**
+      /**
-         * @brief Set the Iterations object
+       * @brief Return the currently set iterations to be calculated.
-         * 
+       * 
-         * @param iterations 
+       * @return int Number of iterations.
-         */
+       */
-        void setIterations(int iterations);
+      int getIterations();
 
-        /**
+      /**
-         * @brief Get the Iterations object
+       * @brief Outputs the current concentrations of the grid on the console.
-         * 
+       *
-         * @return auto 
+       */
-         */
+      void printConcentrationsConsole();
-        int getIterations();
 
-        /**
+      /**
-         * @brief Print the current concentrations of the grid to standard out. 
+       * @brief Creates a CSV file with a name containing the current simulation
-         * 
+       *        parameters. If the data name already exists, an additional counter is
-         */
+       *        appended to the name. The name of the file is built up as follows:
-        void printConcentrationsConsole();
+       *        <approach> + <number rows> + <number columns> + <number of iterations>+<counter>.csv 
+       *
+       * @return string Filename with given simulation parameter.
+       */
+      string createCSVfile();
 
-        /**
+      /**
-         * @brief 
+       * @brief Writes the currently calculated concentration values of the grid
-         * 
+       *        into the CSV file with the passed filename.
-         * @return string 
+       *
-         */
+       * @param filename Name of the file to which the concentration values are
-        string createCSVfile();
+       *                 to be written.
+       */
+      void printConcentrationsCSV(string filename);
 
-        void printConcentrationsCSV(string filename);
+      /**
-
+       * @brief Method starts the simulation process with the previously set
-        /**
+       *        parameters.
-         * @brief 
+       */
-         * 
+      void run();
-         * @return Grid 
-         */
-        void run();
 
     private:
 

src/Boundary.cpp

@@ -1,3 +1,4 @@
+#include "TugUtils.hpp"
 #include "tug/BoundaryCondition.hpp"
 #include <iostream>
 #include <omp.h>
@@ -7,6 +8,7 @@
 using namespace std;
 
 BoundaryElement::BoundaryElement() {
+    
     this->type = BC_TYPE_CLOSED;
     this->value = NAN;
 }
@@ -21,6 +23,14 @@ void BoundaryElement::setType(BC_TYPE type) {
 }
 
 void BoundaryElement::setValue(double value) {
+    if(value < 0){
+        throw_invalid_argument("No negative concentration allowed.");
+    }
+    if(type == BC_TYPE_CLOSED){
+      throw_invalid_argument(
+          "No constant boundary concentrations can be set for closed "
+          "boundaries. Please change type first.");
+    }
     this->value = value;
 }
 
@@ -51,35 +61,76 @@ Boundary::Boundary(Grid grid) : grid(grid) {
 }
 
 void Boundary::setBoundarySideClosed(BC_SIDE side) {
+    if(grid.getDim() == 1){
+        if((side == BC_SIDE_BOTTOM) || (side == BC_SIDE_TOP)){
+          throw_invalid_argument(
+              "For the one-dimensional trap, only the BC_SIDE_LEFT and "
+              "BC_SIDE_RIGHT borders exist.");
+        }
+    }
     this->boundaries[side] = vector<BoundaryElement>(grid.getRow(), BoundaryElement());
 }
 
 void Boundary::setBoundarySideConstant(BC_SIDE side, double value) {
+    if(grid.getDim() == 1){
+        if((side == BC_SIDE_BOTTOM) || (side == BC_SIDE_TOP)){
+          throw_invalid_argument(
+              "For the one-dimensional trap, only the BC_SIDE_LEFT and "
+              "BC_SIDE_RIGHT borders exist.");
+        }
+    }
     this->boundaries[side] = vector<BoundaryElement>(grid.getRow(), BoundaryElement(value));
 }
 
 void Boundary::setBoundaryElementClosed(BC_SIDE side, int index) {
+    // tests whether the index really points to an element of the boundary side.
+    if((boundaries[side].size() < index) || index < 0){
+        throw_invalid_argument("Index is selected either too large or too small.");
+    }
     this->boundaries[side][index].setType(BC_TYPE_CLOSED);
 }
 
 void Boundary::setBoundaryElementConstant(BC_SIDE side, int index, double value) {
+    // tests whether the index really points to an element of the boundary side.
+    if((boundaries[side].size() < index) || index < 0){
+        throw_invalid_argument("Index is selected either too large or too small.");
+    }
     this->boundaries[side][index].setType(BC_TYPE_CONSTANT);
     this->boundaries[side][index].setValue(value);
 }
 
 vector<BoundaryElement> Boundary::getBoundarySide(BC_SIDE side) {
+    if(grid.getDim() == 1){
+        if((side == BC_SIDE_BOTTOM) || (side == BC_SIDE_TOP)){
+          throw_invalid_argument(
+              "For the one-dimensional trap, only the BC_SIDE_LEFT and "
+              "BC_SIDE_RIGHT borders exist.");
+        }
+    }
     return this->boundaries[side];
 }
 
 BoundaryElement Boundary::getBoundaryElement(BC_SIDE side, int index) {
+    if((boundaries[side].size() < index) || index < 0){
+        throw_invalid_argument("Index is selected either too large or too small.");
+    }
     return this->boundaries[side][index];
 }
 
 BC_TYPE Boundary::getBoundaryElementType(BC_SIDE side, int index) {
+    if((boundaries[side].size() < index) || index < 0){
+        throw_invalid_argument("Index is selected either too large or too small.");
+    }
     return this->boundaries[side][index].getType();
 }
 
 double Boundary::getBoundaryElementValue(BC_SIDE side, int index) {
+    if((boundaries[side].size() < index) || index < 0){
+        throw_invalid_argument("Index is selected either too large or too small.");
+    }
+    if(boundaries[side][index].getType() != BC_TYPE_CONSTANT){
+        throw_invalid_argument("A value can only be output if it is a constant boundary condition.");
+    }
     return this->boundaries[side][index].getValue();
 }
 

src/Simulation.cpp

@@ -65,6 +65,9 @@ void Simulation::setTimeMeasure(TIME_MEASURE time_measure) {
 
 void Simulation::setTimestep(double timestep) {
     //TODO check timestep in FTCS for max value
+    if(timestep <= 0){
+        throw_invalid_argument("Timestep has to be greater than zero.");
+    }
     this->timestep = timestep;
 }
 
@@ -73,6 +76,9 @@ double Simulation::getTimestep() {
 }
 
 void Simulation::setIterations(int iterations) {
+    if(iterations <= 0){
+        throw_invalid_argument("Number of iterations must be greater than zero.");
+    }
     this->iterations = iterations;
 }
 

test/testBoundary.cpp

@@ -0,0 +1,68 @@
+#include <stdio.h>
+#include <doctest/doctest.h>
+#include <tug/Boundary.hpp>
+#include <string>
+#include <typeinfo>
+#include <iostream>
+
+TEST_CASE("BoundaryElement"){
+
+    SUBCASE("Closed case"){
+        BoundaryElement boundaryElementClosed = BoundaryElement();
+        CHECK_NOTHROW(BoundaryElement());
+        CHECK_EQ(boundaryElementClosed.getType(), BC_TYPE_CLOSED);
+        CHECK_EQ(isnan(boundaryElementClosed.getValue()), isnan(NAN));
+        CHECK_THROWS(boundaryElementClosed.setValue(0.2));
+    }
+
+    SUBCASE("Constant case"){
+        BoundaryElement boundaryElementConstant = BoundaryElement(0.1);
+        CHECK_NOTHROW(BoundaryElement(0.1));
+        CHECK_EQ(boundaryElementConstant.getType(), BC_TYPE_CONSTANT);
+        CHECK_EQ(boundaryElementConstant.getValue(), 0.1);
+        CHECK_NOTHROW(boundaryElementConstant.setValue(0.2));
+        CHECK_EQ(boundaryElementConstant.getValue(), 0.2);
+    }
+}
+
+TEST_CASE("Boundary Class"){
+    Grid grid1D = Grid(10);
+    Grid grid2D = Grid(10, 12);
+    Boundary boundary1D = Boundary(grid1D);
+    Boundary boundary2D = Boundary(grid2D);
+    vector<BoundaryElement> boundary1DVector(1, BoundaryElement(1.0));
+
+    SUBCASE("Boundaries 1D case"){
+        CHECK_NOTHROW(Boundary boundary(grid1D));
+        CHECK_EQ(boundary1D.getBoundarySide(BC_SIDE_LEFT).size(), 1);
+        CHECK_EQ(boundary1D.getBoundarySide(BC_SIDE_RIGHT).size(), 1);
+        CHECK_EQ(boundary1D.getBoundaryElementType(BC_SIDE_LEFT, 0), BC_TYPE_CLOSED);
+        CHECK_THROWS(boundary1D.getBoundarySide(BC_SIDE_TOP));
+        CHECK_THROWS(boundary1D.getBoundarySide(BC_SIDE_BOTTOM));
+        CHECK_NOTHROW(boundary1D.setBoundarySideClosed(BC_SIDE_LEFT));
+        CHECK_THROWS(boundary1D.setBoundarySideClosed(BC_SIDE_TOP));
+        CHECK_NOTHROW(boundary1D.setBoundarySideConstant(BC_SIDE_LEFT, 1.0));
+        CHECK_EQ(boundary1D.getBoundaryElementValue(BC_SIDE_LEFT, 0), 1.0);
+        CHECK_THROWS(boundary1D.getBoundaryElementValue(BC_SIDE_LEFT, 2));
+        CHECK_EQ(boundary1D.getBoundaryElementType(BC_SIDE_LEFT, 0), BC_TYPE_CONSTANT);
+        CHECK_EQ(boundary1D.getBoundaryElement(BC_SIDE_LEFT, 0).getType(), boundary1DVector[0].getType());
+    }
+
+    SUBCASE("Boundaries 2D case"){
+        CHECK_NOTHROW(Boundary boundary(grid1D));
+        CHECK_EQ(boundary2D.getBoundarySide(BC_SIDE_LEFT).size(), 10);
+        CHECK_EQ(boundary2D.getBoundarySide(BC_SIDE_RIGHT).size(), 10);
+        CHECK_EQ(boundary2D.getBoundarySide(BC_SIDE_TOP).size(), 12);
+        CHECK_EQ(boundary2D.getBoundarySide(BC_SIDE_BOTTOM).size(), 12);
+        CHECK_EQ(boundary2D.getBoundaryElementType(BC_SIDE_LEFT, 0), BC_TYPE_CLOSED);
+        CHECK_NOTHROW(boundary2D.getBoundarySide(BC_SIDE_TOP));
+        CHECK_NOTHROW(boundary2D.getBoundarySide(BC_SIDE_BOTTOM));
+        CHECK_NOTHROW(boundary2D.setBoundarySideClosed(BC_SIDE_LEFT));
+        CHECK_NOTHROW(boundary2D.setBoundarySideClosed(BC_SIDE_TOP));
+        CHECK_NOTHROW(boundary2D.setBoundarySideConstant(BC_SIDE_LEFT, 1.0));
+        CHECK_EQ(boundary2D.getBoundaryElementValue(BC_SIDE_LEFT, 0), 1.0);
+        CHECK_THROWS(boundary2D.getBoundaryElementValue(BC_SIDE_LEFT, 12));
+        CHECK_EQ(boundary2D.getBoundaryElementType(BC_SIDE_LEFT, 0), BC_TYPE_CONSTANT);
+        CHECK_EQ(boundary2D.getBoundaryElement(BC_SIDE_LEFT, 0).getType(), boundary1DVector[0].getType());
+    }
+}

test/testSimulation.cpp

@@ -63,3 +63,41 @@ TEST_CASE("equality to reference matrix") {
     Grid grid = setupSimulation();
     CHECK(checkSimilarity(reference, grid.getConcentrations(), 0.1) == true);
 }
+
+TEST_CASE("Initialize environment"){
+    int rc = 12;
+    Grid grid(rc, rc);
+    Boundary boundary(grid);
+
+    CHECK_NOTHROW(Simulation sim(grid, boundary, FTCS_APPROACH));
+    }
+
+TEST_CASE("Simulation environment"){
+    int rc = 12;
+    Grid grid(rc, rc);
+    Boundary boundary(grid);
+    Simulation sim(grid, boundary, FTCS_APPROACH);
+
+    SUBCASE("default paremeters"){
+        CHECK_EQ(sim.getIterations(), 1000);
+    }
+
+    SUBCASE("set iterations"){
+        CHECK_NOTHROW(sim.setIterations(2000));
+        CHECK_EQ(sim.getIterations(), 2000);
+        CHECK_THROWS(sim.setIterations(-300));
+    }
+
+    SUBCASE("set timestep"){
+        CHECK_NOTHROW(sim.setTimestep(0.1));
+        CHECK_EQ(sim.getTimestep(), 0.1);
+        CHECK_THROWS(sim.setTimestep(-0.3));
+    }
+
+    SUBCASE("filename"){
+        string s1 = sim.createCSVfile();
+        string s2 = "FTCS_12_12_1000";
+        CHECK_EQ(s1.find(s2) != std::string::npos, true);
+    }   
+}
+