Document backend and backenddaeinfo (#10876)

OMCompiler/Compiler/Util/FlagsUtil.mo

@@ -1486,11 +1486,12 @@ protected
 algorithm
   Print.clearBuf();
   s := "OpenModelica Compiler Flags";
+  Print.printBuf("\n.. _openmodelica-compiler-flags :\n\n");
   Print.printBuf(s);
   Print.printBuf("\n");
   Print.printBuf(sum("=" for e in 1:stringLength(s)));
   Print.printBuf("\n");
-  Print.printBuf(System.gettext("Usage: omc [Options] (Model.mo | Script.mos) [Libraries | .mo-files]\n\n* Libraries: Fully qualified names of libraries to load before processing Model or Script.\n  The libraries should be separated by spaces: Lib1 Lib2 ... LibN.\n"));
+  Print.printBuf(System.gettext("Usage: omc [Options] (Model.mo | Script.mos) [Libraries | .mo-files]\n\n* Libraries: Fully qualified names of libraries to load before processing Model or Script.\n  The libraries should be separated by spaces: Lib1 Lib2 ... LibN.\n\n"));
   Print.printBuf("\n.. _omcflags-options :\n\n");
   s := System.gettext("Options");
   Print.printBuf(s);

README.md

@@ -187,6 +187,8 @@ See [OSMC-License.txt](OSMC-License.txt).
 
 See the [CITATIONS](CITATION.cff) file for information on how to cite OpenModelica in
 any publications reporting work done using OpenModelica.
+For a complete list of all publications related to OpenModelica see
+[doc/bibliography/openmodelica.bib](./doc/bibliography/openmodelica.bib).
 
 ------------
-Last updated: 2023-05-26
+Last updated: 2023-06-21

doc/UsersGuide/source/compiler.rst

@@ -0,0 +1,141 @@
+.. _openmodelcia-compiler :
+
+OpenModelica Compiler
+=====================
+
+The OpenModelica Compiler (OMC) consists of a frontend, backend, code generation and the
+runtimes.
+
+
+#. **Lexical Analysis**
+
+   Keywords, operators and identifiers are extracted from the model.
+
+#. **Parsing**
+
+   An abstract syntax tree represented in Meta-Modelica is created from the operators and
+   identifiers.
+
+#. **Semantic Analysis**
+
+   The abstract syntax tree gets tested for semantic errors.
+
+#. **Intermediate Representation**
+
+   Translation of the abstract syntax tree to an intermediate representation called SCode
+   in MetaModelica.
+   This is further processed by the frontend producing DAE intermediate representation
+   code.
+
+#. **Symbolic Optimization Backend**
+
+   The intermediate representation gets optimized and preprocessed.
+
+#. **Code Generation**
+
+   Executable code gets generated from the low level intermediate representation.
+
+For more details see :cite:`openmodelica.org:fritzson:mic:2020`.
+A full list of compiler flags can be found in :ref:`openmodelica-compiler-flags`.
+
+
+.. TODO: Describe the Frontend related modules.
+
+.. _frontend-modules :
+
+Frontend Modules
+----------------
+
+.. _backend-modules :
+
+Backend Modules
+---------------
+
+#. **Pre-Optimization**
+
+   - Partitioning
+   - Alias removal
+
+#. **Causalization**
+
+   - Matching
+   - Sorting
+   - Index reduction
+
+#. **Post-Optimization**
+
+   - Tearing
+   - Jacobian
+
+.. _backend-modules-backend-info :
+
+Backend DAE Info
+~~~~~~~~~~~~~~~~
+
+With compiler debug flag :ref:`backenddaeinfo <omcflag-debug-backenddaeinfo>` it is
+possible to get additional information from the Backend modules.
+
+  - Number of equations / variables
+  - Number of states
+  - Information about initialization and simulation system
+
+    - Equation types
+    - Equation system details (linear and non-linear)
+
+The output of `backenddaeinfo` can be expanded by using additional compiler debug flags
+:ref:`stateselection <omcflag-debug-stateselection>` and
+:ref:`discreteinfo <omcflag-debug-discreteinfo>`.
+
+**Example**
+
+.. omc-mos::
+
+  loadFile(getInstallationDirectoryPath() + "/share/doc/omc/testmodels/BouncingBall.mo")
+  setCommandLineOptions("-d=backenddaeinfo,stateselection,discreteinfo")
+  translateModel(BouncingBall)
+
+.. _code-generation :
+
+Code generation
+---------------
+
+From the low level intermediate representation from the backend code will be generated.
+The default code generation target is C and offers the largest model coverage.
+An alternative is the C++ (`Cpp`) which can produce significant faster executables in some
+cases.
+
+The target language can be changed with compiler flag
+:ref:`--simCodeTarget<omcflag-simCodeTarget>`.
+
+Depending on the target the compiler will write code and compile everything into a single
+simulation executable.
+
+.. _simulation-runtimes :
+
+Simulation Runtimes
+-------------------
+
+The generated code is linked with the appropriate runtime.
+
+.. _c-runtime :
+
+C Runtime
+~~~~~~~~~
+
+In :ref:`solving` the methods implemented in the C runtime are described.
+In :ref:`cruntime-simflags` the runtime flags are documented.
+
+.. TODO: Describe the C ++Runtimes
+.. _cpp-runtime :
+
+C++ Runtime
+~~~~~~~~~~~
+
+Solver methods and runtime flags are currently undocumented.
+Refer to the source code 
+
+References
+~~~~~~~~~~
+.. bibliography:: openmodelica.bib extrarefs.bib
+  :cited:
+  :filter: docname in docnames

doc/UsersGuide/source/index.rst

@@ -21,6 +21,7 @@ Generated on |date| at |time|
   packagemanager
   omedit
   plotting
+  compiler
   solving
   debugger
   porting

doc/UsersGuide/source/simulationflags.rst

@@ -1,13 +1,12 @@
-Small Overview of Simulation Flags
-==================================
+Simulation Runtime Flags
+========================
 
 This chapter contains a :ref:`short overview of simulation flags <cruntime-simflags>`
 as well as additional details of the :ref:`numerical integration methods <cruntime-integration-methods>`.
 
 .. _cruntime-simflags :
 
-OpenModelica (C-runtime) Simulation Flags
------------------------------------------
+C Runtime Simulation Flags
+--------------------------
 
 .. include :: simoptions.inc
-

doc/UsersGuide/source/solving.rst

@@ -3,8 +3,6 @@
 Solving Modelica Models
 =======================
 
-.. TODO: Describe the Backend related modules.
-
 .. _cruntime-integration-methods :
 
 Integration Methods