diff --git a/include/tug/Boundary.hpp b/include/tug/Boundary.hpp index b38024a..98d0181 100644 --- a/include/tug/Boundary.hpp +++ b/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(); - - double getValue(); + /** + * @brief Return the concentration value for the constant boundary condition. + * + * @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 getWall(); - - void setBoundaryElement(int index, BC_TYPE type, double value = NAN); - - BoundaryElement getBoundaryElement(); - - private: - BC_SIDE side; - int length; - vector 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 - * - * @param grid - */ - Boundary(Grid grid); + /** + * @brief Sets all elements of the specified boundary side to the boundary + * condition closed. + * + * @param side Side to be set to closed, e.g. BC_SIDE_LEFT. + */ + 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 Contains the boundary conditions as BoundaryElement objects. + */ + vector getBoundarySide(BC_SIDE side); - vector 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); - - double getBoundaryElementValue(BC_SIDE side, int index); + /** + * @brief Returns the concentration value of a corresponding + * 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; diff --git a/include/tug/Simulation.hpp b/include/tug/Simulation.hpp index 3d123b7..6ec69c4 100644 --- a/include/tug/Simulation.hpp +++ b/include/tug/Simulation.hpp @@ -1,3 +1,7 @@ +/** + * @file Simulation.hpp + * @brief + */ #include "Boundary.hpp" #include @@ -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 - * - * @param grid - * @param bc - * @param aproach - */ - Simulation(Grid &grid, Boundary &bc, APPROACH approach); + /** + * @brief Set the option to output the results to a CSV file. + * + * + * @param csv_output Valid output option. The following options can be set + * here: + * - CSV_OUTPUT_OFF: do not produce csv output + * - 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 - * - * @param csv_output - */ - void setOutputCSV(CSV_OUTPUT csv_output); + /** + * @brief Set the options for outputting information to the console. + * + * @param console_output Valid output option. The following options can be set + * here: + * - 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 - * - * @param console_output - */ - void setOutputConsole(CONSOLE_OUTPUT console_output); + /** + * @brief Set the Time Measure object + * + * @param time_measure + */ + void setTimeMeasure(TIME_MEASURE time_measure); - /** - * @brief Set the Time Measure object - * - * @param time_measure - */ - void setTimeMeasure(TIME_MEASURE time_measure); + /** + * @brief Setting the time step for each iteration step. Time step must be + * greater than zero. + * + * @param timestep Valid timestep greater than zero. + */ + void setTimestep(double timestep); - /** - * @brief Set the Timestep object - * - * @param timetstep - */ - void setTimestep(double timetstep); + /** + * @brief Currently set time step is returned. + * + * @return double timestep + */ + double getTimestep(); - /** - * @brief Get the Timestep object - * - */ - double getTimestep(); + /** + * @brief Set the desired iterations to be calculated. A value greater + * than zero must be specified here. + * + * @param iterations Number of iterations to be simulated. + */ + void setIterations(int iterations); - /** - * @brief Set the Iterations object - * - * @param iterations - */ - void setIterations(int iterations); + /** + * @brief Return the currently set iterations to be calculated. + * + * @return int Number of iterations. + */ + int getIterations(); - /** - * @brief Get the Iterations object - * - * @return auto - */ - int getIterations(); + /** + * @brief Outputs the current concentrations of the grid on the console. + * + */ + void printConcentrationsConsole(); - /** - * @brief Print the current concentrations of the grid to standard out. - * - */ - void printConcentrationsConsole(); + /** + * @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: + * + + + +.csv + * + * @return string Filename with given simulation parameter. + */ + string createCSVfile(); - /** - * @brief - * - * @return string - */ - string createCSVfile(); + /** + * @brief Writes the currently calculated concentration values of the grid + * into the CSV file with the passed filename. + * + * @param filename Name of the file to which the concentration values are + * to be written. + */ + void printConcentrationsCSV(string filename); - void printConcentrationsCSV(string filename); - - /** - * @brief - * - * @return Grid - */ - void run(); + /** + * @brief Method starts the simulation process with the previously set + * parameters. + */ + void run(); private: diff --git a/src/Boundary.cpp b/src/Boundary.cpp index 87752ea..da3a3e4 100644 --- a/src/Boundary.cpp +++ b/src/Boundary.cpp @@ -1,3 +1,4 @@ +#include "TugUtils.hpp" #include "tug/BoundaryCondition.hpp" #include #include @@ -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(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(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 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(); } diff --git a/src/Simulation.cpp b/src/Simulation.cpp index 5fd552c..91deee8 100644 --- a/src/Simulation.cpp +++ b/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; } diff --git a/test/testBoundary.cpp b/test/testBoundary.cpp new file mode 100644 index 0000000..47ca1fa --- /dev/null +++ b/test/testBoundary.cpp @@ -0,0 +1,68 @@ +#include +#include +#include +#include +#include +#include + +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 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()); + } +} \ No newline at end of file diff --git a/test/testSimulation.cpp b/test/testSimulation.cpp index aaac3fa..70ad0cf 100644 --- a/test/testSimulation.cpp +++ b/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); + } +} +