Dear all,

I started recently to learn the Modelica language. I have quite a solid expertise with the following programming languages: C, C++, LabView, Matlab, Python. Nevertheless (or maybe exactly for this) I struggled quite a bit to write (and run correctly) even the simplest model using the Fluid library. Probably, most of my problems are just due by my ignorance of the library, however I have the feeling that the learning curve of Modelica, and the Fluid library in particular, is steeper than it could be. I hope you will find my comment and questions below useful for improving the OpenModelica IDE.

So, here is the comment.

I have found understanding the behaviour of the components in the Fluid library very difficult. That because I had the need to look at the source code many times and when I did it I couldn't do it in a proper manner as:
1. Key, fundamental variables of the underlying physical model are mixed up with ancillary variables or parameter used to make the model more flexible;
2. Key, fundamental variables are scattered in several partial classes;
3. The source code is bloated with annotations, making it impossible to focus on important lines.
I am not criticising the wonderful job done by the architects of the library, clearly all the choices have been done for specific reasons and beautiful solutions have been found to difficult problems (e.g. the stream connectors). Documentation for the user is written clearly and I appreciate the effort of making the library as versatile and re-usable as possible. Moreover point 3 has been solved in the latest version of the IDE, where you can hide away annotation. However, considering my application, I think I should not be, and I would be very happy to avoid having to, looking at such details. Yet I could not avoid doing it, that is the problem. In fact, it is extremely simple for a beginner like me to create a model which doesn't compile, translate or run properly and when this happens, often it is not even clear why. looking at the source code was my last resort to see what could I have done wrong.

Delving in the source code of the fluid library I have found myself dreaming of a tool which would have greatly simplified my job. It is a tabular representation of the SYMBOLS (variables, parameters, constants, types) and EQUATIONS in the flattened model organised by classes in the derivation tree. To make an example, I mean something like this with the recursive inclusion of the components and equations inherited from the parents. Ideally I would expect a table for the components, one for the equations, one for the algorithms one for the initial equations and one for the initial algorithms, each one organised in sections telling which component, equation etc. is derived from which class. Also, having access the tree of the derivation/inclusions would have been useful, to make an example, something like the attached picture [sorry, uploading attachment doesn't seem to work]. In the past I used DoxyGenDoxygen to generate the sort of documentation with the hyperlinks I am dreaming of.

Having said this, here are the questions. Do you know if such tool already exists? If it doesn't exist, can you point me in the right direction to start building one? How are the maintainer of the building library generating the documentation at the above link? Do you think a clever student of Computer Science or Automation Engineering could complete the task of writing such a tool for the Master degree?

Sincerely,