Merge pull request #5 from MarcusWalther/master

Textupdate for C++ Runtime documentation

.gitignore

@@ -1,2 +1,7 @@
 SimulationRuntime/cpp/CMakeFiles
 SimulationRuntime/cpp/Doc
+SimulationRuntime/cpp/Makefile
+SimulationRuntime/cpp/CMakeCache.txt
+SimulationRuntime/cpp/cmake_install.cmake
+SimulationRuntime/cpp/CppRuntimeDoc.config
+SimulationRuntime/cpp/Images/OMLogo.svg

SimulationRuntime/cpp/CodingStyle.dox

@@ -0,0 +1,9 @@
+/*!
+  \page CodingStyle
+  There are some rules that should be considered if a contribution to the runtime is made.
+
+  - use 2 spaces instead of tabs
+  - all function-names should start with a lower letter and multiple words should be combined in camel case (e.g. getName)
+  - member variables start with an underscore, multiple words are combined in camel case as well (e.g. _isActive)
+  - use the Doxygen JavaDoc/C - notation to document your code (this notation starts with a slash followed by 2 stars)
+ */

SimulationRuntime/cpp/EventHandling.dox

@@ -0,0 +1,26 @@
+/*!
+  \page Eventhandling
+  This page describes the basic workflow of event handling, which is performed by the solver in the c++ simulation runtime. There are two
+  important classes that are part of the workflow.
+    - Solver (e.g. CVode): Will estimate the step width and call the evaluation of state derivatives and zero crossing conditions
+    - Model: Implements the evaluation of state derivatives and zero crossings
+
+  \image html EventHandling.jpg "The image should visualize the basic principle of event handling. The numbers next to the circles indicate the order of execution."
+
+  Consider a model with a variable x and a condition x > 0. The behavior of x is shown in the figure above. At an arbitrary point of the simulation, 
+  the solver will evaluate the state derivatives and zero crossing conditions, shown as blue circles. As long as the condition x > 0 will stay the same, no event handling
+  is performed (steps 1 - 4). At step 5 the condition has changed from true to false, so the detailed event-point must be found. The solver will now start to evaluate all 
+  equations that are required to analyze the condition x > 0 for various points in time. These calculation are displayed as orange circles. Note that it's not necessary to
+  calculate the state derivatives at these evaluation points, because the solver can approximate the states out of the already known values. Now the solver will hopefully find the 
+  point in time that triggered the event (green circle).
+
+  For the implementation, the following functions are important:
+    - Blue Circle:
+      - evaluateODE
+      - evluateZeroFunc
+    - Orange Circle:
+      - setStates
+      - evaluateZeroFunc
+    - Green Circle:
+      - evaluateConditions
+ */

SimulationRuntime/cpp/Flags.dox

@@ -9,7 +9,7 @@
   - -help                                                             | Produce the help message                                                                                 |
   -R \<PATH\>                                                         | Path to the cpp runtime libraries (required)                                                             |
   -M \<PATH\>                                                         | Path to the modelica system library (required)                                                           |
-  -r \<NAME\>                                                         | Name of the results file (required)                                                                      |
+  -F \<NAME\>                                                         | Name of the results file (required)                                                                      |
   -S \<VALUE\>                                                        | Simulation start time (default: 0.0)                                                                     |
   -E \<VALUE\>                                                        | Simulation stop time (default: 1.0)                                                                      |
   -H \<VALUE\>                                                        | Simulation step size (default: 0.0)                                                                      |
@@ -18,7 +18,26 @@
   -I \[\"euler\"\|\"peer\"\|\"rtrk\"\|\"ida\"\|\"cvode\"\|\"dassl\"\] | Time integration algorithm that should be used (default: \"euler\")                                      |
   -L \[\"umfpack\"\|\<NONLINEARSOLVER\>\]                             | Solver for linear equation systems that should be used (default: \"kinsol\")                             |
   -N \[\"newton\"\|\"kinsol\"\|\"hybrj\"\]                            | Solver for non linear equation systems that should be used (default: \"kinsol\")                         |
-  -V \<VALUE\>                                                        | LOGGER SETTINGS MISSING                                                                                  |
+  -V \<VALUE\>                                                        | This flag can be added multiple times. Pass a key=value pair as argument. See the description below.     |
   -A \<VALUE\>                                                        | Timeout in seconds for the simulation (default: 360)                                                     |
-  -O \["all"\|"step"|"none"\]                                         | The time points that should be written to the result file (default: all)                                 |
+  -O \[\"all\"\|\"step\"\|\"none\"\]                                  | The time points that should be written to the result file (default: all)                                 |
+  --nls-continue                                                      | The non linear solver will continue if it does not reach the given accuracy                              |
+
+  There are several settings available to control the behavior of the logger. You can specify multiple key-value-pairs to set the log-output for several log-categories. All key-value-pairs have the form LOG_CATEGORY=LOG_LEVEL. The following categories are available:
+   - \b init logger messages related to the initialization phase
+   - \b nls output of the non linear solver
+   - \b ls output of the linear solver
+   - \b solv messages related to the time integration algorithm
+   - \b output information related to the output algorithm (e.g. matfile writer)
+   - \b event logger messages that belong to the event handling part of the simulation
+   - \b model output of the model equations etc. 
+   - \b other messages that belong to other parts, not specified by the categories above
+
+  All logger messages belong to a log level. If a category is set to a certain level, all messages are written that have the given level or a higher one.
+   - \b error One critical errors are displayed.
+   - \b warning Contains messages that can influence the simulation performance or simulation results
+   - \b info Just some information, e.g. the number of steps the time integration algorithm took
+   - \b debug Output related to debug information like function invocations etc.
+
+  To set a specific level for all categories, use all=LOG_LEVEL.
 */

SimulationRuntime/cpp/Mainpage.dox

@@ -1,13 +1,8 @@
 /**
 \mainpage Overview
 
-This is the documentation of the C++ Simulation-Runtime, which is delivered as part of OpenModelica. Besides the source code documentation, there are some further informations given in this documentation.
+This is the documentation of the C++ Simulation-Runtime, which is delivered as part of OpenModelica. Besides the source code documentation, there are some further informations given in this documentation. Please take a look into the related pages, to get some information about the flags and the coding style.
 
 There are some open things TODO!
 \todo The linaer solver is set to "kinsol", but lapack is used instead
-
-<ul>
-  <li> <a href="_flags.html">Available flags</a></li>
-  <li> Using the logger </li>
-</ul>
 */