From e577d4104b484537ed4ed68210b2b49df7b12fed Mon Sep 17 00:00:00 2001 From: Andreas <38031952+AnHeuermann@users.noreply.github.com> Date: Thu, 22 Jun 2023 13:49:32 +0200 Subject: [PATCH] Document backend and backenddaeinfo (#10876) --- OMCompiler/Compiler/Util/FlagsUtil.mo | 3 +- README.md | 4 +- doc/UsersGuide/source/compiler.rst | 141 ++++++++++++++++++++++ doc/UsersGuide/source/index.rst | 1 + doc/UsersGuide/source/simulationflags.rst | 9 +- doc/UsersGuide/source/solving.rst | 2 - 6 files changed, 151 insertions(+), 9 deletions(-) create mode 100644 doc/UsersGuide/source/compiler.rst diff --git a/OMCompiler/Compiler/Util/FlagsUtil.mo b/OMCompiler/Compiler/Util/FlagsUtil.mo index 429071551e8..5a3addf3b99 100644 --- a/OMCompiler/Compiler/Util/FlagsUtil.mo +++ b/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); diff --git a/README.md b/README.md index 9d2a884a83c..7d47bff6bcd 100644 --- a/README.md +++ b/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 diff --git a/doc/UsersGuide/source/compiler.rst b/doc/UsersGuide/source/compiler.rst new file mode 100644 index 00000000000..37923dde763 --- /dev/null +++ b/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 ` 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 ` and +:ref:`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`. + +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 diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst index 312b29f0583..668597a4b23 100644 --- a/doc/UsersGuide/source/index.rst +++ b/doc/UsersGuide/source/index.rst @@ -21,6 +21,7 @@ Generated on |date| at |time| packagemanager omedit plotting + compiler solving debugger porting diff --git a/doc/UsersGuide/source/simulationflags.rst b/doc/UsersGuide/source/simulationflags.rst index cbc26f9625c..1606fa087d7 100644 --- a/doc/UsersGuide/source/simulationflags.rst +++ b/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 ` as well as additional details of the :ref:`numerical integration methods `. .. _cruntime-simflags : -OpenModelica (C-runtime) Simulation Flags ------------------------------------------ +C Runtime Simulation Flags +-------------------------- .. include :: simoptions.inc - diff --git a/doc/UsersGuide/source/solving.rst b/doc/UsersGuide/source/solving.rst index 6670c9de5d5..cb834206fa5 100644 --- a/doc/UsersGuide/source/solving.rst +++ b/doc/UsersGuide/source/solving.rst @@ -3,8 +3,6 @@ Solving Modelica Models ======================= -.. TODO: Describe the Backend related modules. - .. _cruntime-integration-methods : Integration Methods