add sphinx documentation

docs_sphinx/Boundary.rst

@@ -0,0 +1,4 @@
+Boundary
+========
+
+.. doxygenclass:: Boundary

docs_sphinx/Grid.rst

@@ -0,0 +1,4 @@
+Grid
+====
+
+.. doxygenclass:: Grid

docs_sphinx/Simulation.rst

@@ -0,0 +1,4 @@
+Simulation
+==========
+
+.. doxygenclass:: Simulation

docs_sphinx/conf.py

@@ -0,0 +1,98 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+from sphinx.builders.html import StandaloneHTMLBuilder
+import subprocess, os
+
+# Doxygen
+subprocess.call('doxygen Doxyfile.in', shell=True)
+
+# -- Project information -----------------------------------------------------
+
+project = 'TUG'
+copyright = 'MIT'
+author = 'Philipp Ungrund, Hannes Signer'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx_sitemap',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx_sitemap',
+    'breathe'
+]
+
+html_baseurl = "/index.html"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+highlight_language = 'c++'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'canonical_url': '',
+    'analytics_id': '',  #  Provided by Google in your dashboard
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': False,
+    
+    'logo_only': False,
+
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
+# html_logo = ''
+# github_url = ''
+# html_baseurl = ''
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Breathe configuration -------------------------------------------------
+
+breathe_projects = {
+	"Tug": "_build/xml/"
+}
+breathe_default_project = "Tug"
+breathe_default_members = ('members', 'undoc-members')

docs_sphinx/developper.rst

@@ -0,0 +1,2 @@
+Developper API
+==============

docs_sphinx/examples.rst

@@ -0,0 +1,62 @@
+Examples
+========
+
+At this point, some typical commented examples are presented to illustrate how Tug works.
+In general, each simulation is divided into three blocks:
+    - the initialization of the grid, which is to be simulated
+    - the setting of the boundary conditions
+    - the setting of the simulation parameters and the start of the simulation
+
+Two dimensional grid with constant boundaries and FTCS method
+-------------------------------------------------------------
+**Initialization of the grid**
+
+For example, the initalization of a grid with 20 by 20 cells and a domain size (physical extent of the grid) of 
+also 20 by 20 length units can be done as follows. The setting of the domain is optional here and is set to the 
+same size as the number of cells in the standard case. As seen in the code, the cells of the grid are set to an 
+initial value of 0 and only in the upper left corner (0,0) the starting concentration is set to the value 20.
+
+.. code-block:: cpp
+    
+    int row = 20
+    int col = 20;
+    Grid grid = Grid(row,col);
+    grid.setDomain(row, col);
+    MatrixXd concentrations = MatrixXd::Constant(row,col,0);
+    concentrations(0,0) = 20;
+    grid.setConcentrations(concentrations);
+
+**Setting of the boundary conditions**
+
+First, a boundary class is created and then the corresponding boundary conditions are set. In this case, all four sides
+of the grid are set as constant edges with a concentration of 0.
+
+.. code-block:: cpp
+
+    Boundary bc = Boundary(grid);
+    bc.setBoundarySideConstant(BC_SIDE_LEFT, 0);
+    bc.setBoundarySideConstant(BC_SIDE_RIGHT, 0);
+    bc.setBoundarySideConstant(BC_SIDE_TOP, 0);
+    bc.setBoundarySideConstant(BC_SIDE_BOTTOM, 0);
+
+**Setting of the simulation parameters and simulation start**
+In the last block, a simulation class is created and the objects of the grid and the boundary conditions are passed. The solution
+method is also specified (either FCTS or BTCS). Furthermore, the desired time step and the number of iterations are set. The penultimate
+parameter specifies the output of the simulated results in a CSV file. In the present case, the result of each iteration step is written
+one below the other into the corresponding CSV file.
+
+.. code-block:: cpp
+    
+    Simulation simulation = Simulation(grid, bc, FTCS_APPROACH);
+    simulation.setTimestep(0.1);
+    simulation.setIterations(1000);
+    simulation.setOutputCSV(CSV_OUTPUT_VERBOSE);
+    simulation.run();
+
+
+
+
+
+
+Setting special boundary conditions on individual cells
+-------------------------------------------------------

docs_sphinx/index.rst

@@ -0,0 +1,37 @@
+.. Tug documentation master file, created by
+   sphinx-quickstart on Mon Aug 14 11:30:23 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Tug's documentation!
+===============================
+Welcome to the documentation of the TUG project, a simulation program 
+for solving one- and two-dimensional diffusion problems with heterogeneous diffusion coefficients, more 
+generally, for solving the following differential equation
+
+.. math::
+   \frac{\partial C}{\partial t} = \alpha_x \frac{\partial^2 C}{\partial x^2} + \alpha_y \frac{\partial^2 C}{\partial y^2}.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+
+Table of Contents
+^^^^^^^^^^^^^^^^^
+.. toctree::    
+   
+    :maxdepth: 2
+    self
+    installation
+    theory
+    user
+    developper
+    examples

docs_sphinx/installation.rst

@@ -0,0 +1,3 @@
+Installation
+============
+

docs_sphinx/theory.rst

@@ -0,0 +1,15 @@
+Theoretical Foundations
+=======================
+
+=====================
+The Diffusion Problem
+=====================
+
+================
+Numerical Solver
+================
+
+**Backward Time-Centered Space (BTCS) Method**
+
+
+**Forward Time-Centered Space (BTCS) Method**

docs_sphinx/user.rst

@@ -0,0 +1,9 @@
+User API
+========
+
+.. toctree::    
+   
+    :maxdepth: 2
+    Grid
+    Boundary
+    Simulation

examples/profiling_openmp.cpp

@@ -0,0 +1,51 @@
+#include <tug/Simulation.hpp>
+#include <iostream>
+#include <fstream>
+
+int main(int argc, char *argv[]) {
+
+    int n[4] = {10, 20, 50, 100};
+    int iterations[1] = {100};
+    int repetition = 10;
+
+    ofstream myfile;
+    myfile.open("time_measure_experiment_openmp_thread_6.csv");
+
+    for (int i = 0; i < size(n); i++){
+        cout << "Grid size: " << n[i] << " x " << n[i] << endl << endl;
+        myfile << "Grid size: " << n[i] << " x " << n[i] << endl << endl;
+        for(int j = 0; j < size(iterations); j++){
+            cout << "Iterations: " << iterations[j] << endl;
+            myfile << "Iterations: " << iterations[j] << endl;
+            for (int k = 0; k < repetition; k++){
+                cout << "Wiederholung: " << k << endl;
+                Grid grid = Grid(n[i], n[i]);
+                grid.setDomain(n[i], n[i]);
+
+                MatrixXd concentrations = MatrixXd::Constant(n[i], n[i], 0);
+                concentrations(5,5) = 1;
+                grid.setConcentrations(concentrations);
+                MatrixXd alpha = MatrixXd::Constant(n[i], n[i], 0.5);
+
+                Boundary bc = Boundary(grid);
+
+                Simulation sim = Simulation(grid, bc, FTCS_APPROACH);
+
+
+                sim.setTimestep(0.001);
+                sim.setIterations(iterations[j]);
+                sim.setOutputCSV(CSV_OUTPUT_OFF);
+
+                auto begin = std::chrono::high_resolution_clock::now();
+                sim.run();
+                auto end = std::chrono::high_resolution_clock::now();
+                auto milliseconds = std::chrono::duration_cast<std::chrono::milliseconds>(end - begin);
+                myfile << milliseconds.count() << endl;
+            }
+        }
+        cout << endl;
+        myfile << endl;
+
+    }
+    myfile.close();
+}

src/FTCS.cpp

@@ -11,6 +11,8 @@
 #include <iostream>
 #include <omp.h>
 
+#define NUM_THREADS 6
+
 using namespace std;
 
 
@@ -269,7 +271,7 @@ static void FTCS_2D(Grid &grid, Boundary &bc, double &timestep) {
 	// inner cells
 	// these are independent of the boundary condition type
 	// omp_set_num_threads(10);
-#pragma omp parallel for
+#pragma omp parallel for num_threads(NUM_THREADS)
 	for (int row = 1; row < rowMax-1; row++) {
 	    for (int col = 1; col < colMax-1; col++) {
 		concentrations_t1(row, col) = grid.getConcentrations()(row, col) 
@@ -289,7 +291,7 @@ static void FTCS_2D(Grid &grid, Boundary &bc, double &timestep) {
 	// left without corners / looping over rows
 	// hold column constant at index 0
 	int col = 0;
-#pragma omp parallel for
+#pragma omp parallel for num_threads(NUM_THREADS)
 	for (int row = 1; row < rowMax-1; row++) {
 	    concentrations_t1(row, col) = grid.getConcentrations()(row,col)
 		+ timestep / (deltaCol*deltaCol) 
@@ -306,7 +308,7 @@ static void FTCS_2D(Grid &grid, Boundary &bc, double &timestep) {
 	// right without corners / looping over rows
 	// hold column constant at max index
 	col = colMax-1;
-#pragma omp parallel for
+#pragma omp parallel for num_threads(NUM_THREADS)
 	for (int row = 1; row < rowMax-1; row++) {
 	    concentrations_t1(row,col) = grid.getConcentrations()(row,col)
 		+ timestep / (deltaCol*deltaCol) 
@@ -324,7 +326,7 @@ static void FTCS_2D(Grid &grid, Boundary &bc, double &timestep) {
 	// top without corners / looping over columns
 	// hold row constant at index 0
 	int row = 0;
-#pragma omp parallel for
+#pragma omp parallel for num_threads(NUM_THREADS)
 	for (int col=1; col<colMax-1;col++){
         concentrations_t1(row, col) = grid.getConcentrations()(row, col)
             + timestep / (deltaRow*deltaRow) 
@@ -341,7 +343,7 @@ static void FTCS_2D(Grid &grid, Boundary &bc, double &timestep) {
 	// bottom without corners / looping over columns
 	// hold row constant at max index
 	row = rowMax-1;
-#pragma omp parallel for
+#pragma omp parallel for num_threads(NUM_THREADS)
 	for(int col=1; col<colMax-1;col++){
 	    concentrations_t1(row, col) = grid.getConcentrations()(row, col)
 		+ timestep / (deltaRow*deltaRow)