Documentation/Application Guide/Examples and Wiki

[lvanfretti]

@MaximeBaudette I think we should enable the wiki in the same way you did for RaPId.

There we can add the best practices, validation procedure, application guide, training materials, documentation of test systems, papers and thesis from KTH, scripts (e.g. linearization with OM)...

Can you start with this?

We should use this issue also to discuss how the structure of the Wiki needs to be, and what else we will include.

[itesla]

Wiki is already enabled but restricted to collaborators of the repo. Are we ok with that?

[MaximeBaudette]

@itesla Yes!

[lvanfretti]

@MaximeBaudette @itesla NO, the point of using the wiki is to be able to add all of the possible information for users in different forms.

In fact, already @dietmarw is asking about documentation...

[dietmarw]

My 2 cents, it is normally better to keep the documentation inside the library. Modelica offers the nice way of documenting everything inside via HTML. So only one place to maintain as it travels literally with the code.

Wiki pages might be a nice addon but I would not rely on that as primary source of documentation.

[lvanfretti]

@dietmarw I agree, we can add the application guide and test networks within the library... but I'm not sure how to keep other stuff there.
There are many things (e.g. papers, pdf's, reference models from other SW, etc) that are part of the "documentation" - my intention is that we set up the Wiki to deal with this.

[dietmarw]

I see. Well without knowing the exact content you can of course start with the wiki and one can still decide what can perhaps be included directly in the library. PDFs are very easy to combine by way of putting the files, e.g., under iPSL/Resources/Documentation and then linking to them from User's Guide classes (Resources/ being the recommended location for all non-Modelica code bits in a library). Also references can be organised in a very nice way. The FCSys library for example found an innovative way of including references by (mis)using classes.

[MaximeBaudette]

@dietmarw
I agree that model documentation should reside in the Modelica code. However, our work so far has mainly been of implementing components using other software as reference. Documentation has, thus, not been the priority and I recommended that we simply redirect the user by mentioning the original name of the component and which software documentation to look at.
This can of course be changed in the future as the library mature.
The Wiki was, in my opinion mostly interesting for providing additional info on how to contribute, extended description of the library, and also include documentation on the model validation work that has been done. So far we have mostly done this work in the form of publications, but we have prepared a template document for people to contribute validation report, but I saw it hasn't been uploaded yet in the repository. I'll have a look at it, and will probably put it in the Wiki, instead of the repository as originally intended.
In short, I would like to see the main Readme strongly reduced in the repository and transfer some of its content to the wiki.
@lvanfretti @itesla The idea of keeping the Wiki restricted to collaborators, is, in my opinion, necessary in a first step until we have fully established an architecture and fully documented how we intend to use it.

[MaximeBaudette]

@dietmarw
Another question. I am aware about the HTML-like documentation of Modelica, but so far I have mainly faced issues in using it with Dymola, having to constantly go in the HTML code and fix it manually. The behaviour is also very unstable with what I've experienced, and some of my colleagues have faced the same issues.
Do you have any Modelica editor to recommend for documentation tasks?

[dietmarw]

@MaximeBaudette As long as you avoid the WYSIWY(wishto)G editor of Dymola you are on the safe side. I personally edit HTML in source (using emacs) which works fine and does not give you any nasty surprises (even the Dymola HTML editor works fine as far as I can tell). There is an actively developed Atom.io plugin for Modelica with HTML preview mode available.

[lvanfretti]

I have added a video with the application guide example in youtube: https://www.youtube.com/watch?v=nKOCulNiy3o
We still need to clean it up a little bit before we go further in this.

[sorrento]

So, do we have any consensus on this? Any device well documented to use as reference?

[lvanfretti]

@MaximeBaudette @dietmarw @sorrento

Gentleman, at the time being we are finishing the iTesla project and as of the end of March I am not sure if my team will directly contribute to the iPSL, or if we create our own fork or complete new reimplementation.

So, for the time being, we will not yet prioritized documentation and making more tutorials.

There are both technical and financial issues:

Technical:

• the library needs some relevant clean up, and given the work required to adopt a good OO design, and other relevant changes that seem to be required for better performance as Francesco has outlined, I think we should start an implementation from scratch.
• In addition, the implementation should be more consistent with the CIM models (UML definitions), because as of now in our work to generate from CIM to Modelica there is a need for mapping only specific parameters. This would make the future work on modeling a little annoying, so having consistency with CIM is very important in order to have industry adoption.
• The library should be designed also in order to make multi-time domain, multi-physics, and cps analysis. In its current form, it would be challenging to have for example a 3-phase breaker definition from where we can get a topology and simulate, whereas CIM for EMT will be developed soon. Multi-time domain would require that we either select the same model with more or less granularity, while CPS will require that we have a better concept of time (e.g. as in the Synchronous library).
• Because iPSL will be part of a general OSS release of the iTesla platform, the release times will become really long, which is not suitable for us working on research.
• There is still the issue of dealing with the steady state computation (aka power flow), and it's use for initialization. If we adopt compliance to CIM we get this for free from the SV in the snapshots, however, the solution might not be accurate enough for the initialization in Modelica, so we still need to have something to deal with this as a tool part of the library (i.e. a power flow engine compatible with CIM and our Modelica models) or something that could be done directly on Modelica or MetaModelica (which we don't know how to use).

Economical: Given the fact that almost 90% of the library is from our contribution, and given the fact that I will not have sufficient funding to support relevant contributors of this team; I am reconsidering the approach that we should take on contributing in an OSS in the long term.
I am quite sure that this work is being used, and will be used, for commercial purposes, and it is not so nice that we can't at least get support to pay for student salaries for development and maintenance.
To strike a balance between sharing and the use of our work, I think that if we are going to make any further developments, I want them to released using a non-commerical license. Dual licensing might be an option for the future, but perhaps this is something to be discussed next week @dietmarw

I think that this is a fair approach to my team, and you, @dietmarw and @sorrento, as our main non-itesla contributors.
I think we will have to make a plan in April about further developments were we can independently, (and hopefully with the help of @dietmarw and @sorrento ) be a little bit more free on how we want to work with this.

@dietmarw this should give you some insight on what things we can discuss in our meeting next week, but as you see, in order to be able to develop something that would be (A) easy to adopt in industry, and (B) that allows us to further research, we need to do a good design.

Maybe we can involve our colleagues, Francesco, and the people in Linköping after the initial meeting, but I think we need to think more long term in investing on a project that can be maintained in a fair way.

[lvanfretti]

Oh, @sorrento , I can also say that we can't put certain documentation online as it is copyrighted. We can, however, point users to the original documentation from the reference tool.

That being said, there are a lot of special things that we had to find out that are not in the documentation, and I guess that should be documented in the future.

In the mean time, you can take a look at the PSSE models and the PSSE documentation. This is the best implementations I think we have.

In addition, the models from PSAT are also well implemented, and their documentation can be found online.

[lvanfretti]

I will no longer follow up on iPSL; so I'm closing this issue.