Add a technical details chapter with MATv4 format

UsersGuide/.gitignore

@@ -47,3 +47,22 @@ source/testmodel.pdf
 source/testmodel.png
 source/testmodel.svg
 source/tracreleases.inc
+source/__pycache__/
+source/media/mdt-build-prompt.pdf
+source/media/mdt-create-project.pdf
+source/media/systemoverview.pdf
+source/omnotebook-closed-loop.pdf
+source/omnotebook-closed-loop.png
+source/omnotebook-closed-loop.svg
+source/omnotebook-drcontrol-imgposroots.pdf
+source/omnotebook-drcontrol-imgposroots.png
+source/omnotebook-drcontrol-imgposroots.svg
+source/omnotebook-drcontrol-negroots.pdf
+source/omnotebook-drcontrol-negroots.png
+source/omnotebook-drcontrol-negroots.svg
+source/omnotebook-open-loop.pdf
+source/omnotebook-open-loop.png
+source/omnotebook-open-loop.svg
+source/testmodel-plotall.pdf
+source/testmodel-plotall.png
+source/testmodel-plotall.svg

UsersGuide/source/index.rst

@@ -40,6 +40,7 @@ Generated on |date| at |time|
   scripting_api
   omchelptext
   simulationflags
+  technical_details
   faq
 
 .. toctree::

UsersGuide/source/technical_details.rst

@@ -0,0 +1,63 @@
+.. _tech_details :
+
+Technical Details
+=================
+
+This chapter gives an overview of some implementation details that might
+be interesting when building tools around OpenModelica.
+
+The MATv4 Result File Format
+----------------------------
+
+The default result-file format of OpenModelica is based on MATLAB level
+4 MAT-files as described in the `MATLAB documentation <https://www.mathworks.com/help/pdf_doc/matlab/matfile_format.pdf>`__.
+This format can be read by tools such as MATLAB, `https://www.gnu.org/software/octave/ <Octave>`__, `https://www.scilab.org/ <Scilab>`__, and `SciPy <https://www.scipy.org/>`__.
+OpenModelica will write the result-files in a particular way that can be read by tools such as `https://pypi.python.org/pypi/DyMat <DyMat>`__ and `Dymola <https://www.3ds.com/products-services/catia/products/dymola/>`__ (OpenModelica can also read files generated by Dymola since the used format is the same).
+
+The variables stored in the MAT-file are (in the order required by OpenModelica):
+
+Aclass
+  - ``Aclass(1,:)`` is always ``Atrajectory``
+  - ``Aclass(2,:)`` is ``1.1` in OpenModelica
+  - ``Aclass(3,:)`` is empty
+  - ``Aclass(4,:)`` is either ``binTrans`` or ``binNormal``
+  The most important part of the variable is ``Aclass(4,:)`` since there are
+  two main ways the result-file is stored: transposed or not.
+  For efficiency, the result-file is written time-step by time-step during
+  simulation. But the best way to read the data for a single variable
+  is if the variables are stored variable by variable.
+  If ``Aclass(4,:)`` is ``binTrans``, all matrices need to be transposed since
+  the file was not transposed for efficient reading of the file. Note that
+  this affects all matrices, even matrices that do not change during
+  simulation (such as name and description).
+
+name
+  Is an n x m character (int8) matrix, where n is the number of variables stored in the
+  result-file (including time). m is the length of the longest variable.
+  OpenModelica stores the trailing part of the name as NIL bytes (\0) whereas
+  other tools use spaces for the trailing part.
+
+description
+  Is an n x m character (int8) matrix containing the comment-string corresponding to the
+  variable in the name matrix.
+
+dataInfo
+  Is an n x 4 integer matrix containing information for each variable (in the
+  same order as the name and description matrices).
+
+  - ``dataInfo(i,1)`` is ``1`` or ``2``, saying if variable i is stored in the data_1 or data_2 matrix. If it is ``0`, it is the abscissa (time variable).
+  - ``dataInfo(i,2)`` contains the index in the data_1 or data_2 matrix.
+    The index is 1-based and may contain several variables pointing to the same row (alias variables).
+    A negative value means that the variable is a negated alias variable.
+  - ``dataInfo(i,3)`` is 0 to signify linear interpolation. In other tools the value is the number of times differentiable this variable is, which may improve plotting.
+  - ``dataInfo(i,4)`` is ``-1`` in OpenModelica to signify that the value is not defined outside the time range. ``0` keeps the first/last value when going outside the time range and ``1`` performs linear interpolation on the first/last two points.
+
+data_1
+  If it is an n x 1 matrix it contains the values of parameters.
+  If it is an n x 2 matrix, the first and second column signify start
+  and stop-values.
+
+data_2
+  Each row contains the values of a variable at the sampled times.
+  The corresponding time stamps are stored in ``data_2(1,:)`` so ``data_2(2,1)``
+  is the value of a variable at time ``data_2(1,1)``.