OMJulia api docu: sample code should work right away

[olivleno]

The introduction to OMJulia is nice but still not straight forward with stumbling blocks for new users.
For instance the example code:

using OMJulia
mod = OMJulia.OMCSession()
ModelicaSystem(mod,"BouncingBall.mo","BouncingBall")

doesn't work unless you have the mo file in the proper place.

A new user should be able to run the code just like that.
I'd suggest to provide the required models for download or use a model from the MSL and document all prerequisites, like path to the MSL and so on, such that everybody is able to reproduce the results without being confronted with error messages after executing the code examples and having to trouble shoot all kind of things (e.g. figure out the path to the MSL) that could be easily documented or integrated in the code.

[AnHeuermann]

We could switch from the Sphinx documentation from OpenModelica to Documenter.jl and only refer to that documentation from the OpenModelica User's Guide.

It's possible to make all examples inside the documentation test, so we can ensure they are always working as intended and also test them on different OS (Windows and Linux).
Adding it is not too much work, but someone would need to do it.

Regarding your issue: The Readme.md provides an example using the MSL.
We could also use the shipped version of BouncingBall.mo, but it makes the example very hard to understand:

using OMJulia
mod = OMJulia.OMCSession()
sendExpression(mod, "loadFile(getInstallationDirectoryPath() + \"/share/doc/omc/testmodels/BouncingBall.mo\")")
ModelicaSystem(mod,"BouncingBall.mo","BouncingBall")

It's probably best, to just add the source code of bouncingBall.mo into the documentation.

model BouncingBall
  parameter Real e=0.7 "coefficient of restitution";
  parameter Real g=9.81 "gravity acceleration";
  Real h(fixed=true, start=1) "height of ball";
  Real v(fixed=true) "velocity of ball";
  Boolean flying(fixed=true, start=true) "true, if ball is flying";
  Boolean impact;
  Real v_new(fixed=true);
  Integer foo;

equation
  impact = h <= 0.0;
  foo = if impact then 1 else 2;
  der(v) = if flying then -g else 0;
  der(h) = v;

  when {h <= 0.0 and v <= 0.0,impact} then
    v_new = if edge(impact) then -e*pre(v) else 0;
    flying = v_new > 0;
    reinit(v, v_new);
  end when;

end BouncingBall;

[olivleno]

The parameter sensitivity is using the lottka voltera example, which is very compact.

[bc0n]

100% move to Documenter.jl

[AnHeuermann]

We decided in today's dev-meeting to switch to Documenter.jl. I'll create a PR with the initial setup and CI to build and upload the documentation to a GitHub page.

If that is up and running we can add more and more stuff to it.
Some help for what to put into the documentation is greatly appreciated. What is missing in your opinion / what sections are unclear and so on.

[AnHeuermann]

@olivleno is https://openmodelica.github.io/OMJulia.jl/dev/quickstart/#ModelicaSystem a better documentation or is there any information missing?

[olivleno]

@AnHeuermann thanks for your efforts.

I like the enhancement of the example code showing how to manage result file. Very nice.

Also the note where to find the BouncingBall.mo is very helpful.
But still is my point from above: "doesn't work unless you have the mo file in the proper place." not fully covered.
I'd suggest to extend the note by saying where this file should be copied to such the code works or modify the code such that it directly references the mentioned location.

All this can be considered very very basic stuff that everybody should know, but the path handling can always be a stumbling block if you are using a new environment without knowing how path information is handled, e.g. , the sendExpression(omc, "loadModel(Modelica)") command works out of the box without providing the path to the MSL. If the test models are also shipped with OpenModelica, then one could expect that this location is also known by the environment.

[olivleno]

I tested the Scripting API example code in a julia script.

The line:
OMJulia.quit(omc)

throws the error:
ERROR: UndefVarError: quit not defined suggestion: To exit Julia, use Ctrl-D, or type exit() and press enter.

[AnHeuermann]

You'll need to update OMJulia to v0.2.2