Document the workflow of External Libraries in Wiki

[cd155]

Current Situation

In Drasil, we connect our main program to external libraries to achieve computation.

For example, we use ODEInfo as an interface to connect to ODE external libraries. Those external libraries are called ODE solvers. Another example is a Non-ODE solver, in which we give explicit equations. Both solvers generated code. However, the workflow about those solvers hasn't been written very well.

non-ODE Solver

1. glassbr
   • explicit equations

ODE Solver

ODE examples in drasil-examples

1. NoPCM
   • solving a single first-order ODEs in C, C#, java, python
2. PDController
   • solving two first-order ODEs in python

Things get tricky, the PDController introduced a second-order ODE in the Instance Model. In order to solve it, the user rewrites the second-order ODE to two first-order ODE. The new coupled of two first ODEs be solved in Scipy Library. However, the documentation of concrete workflow from the Instance Model to generated code is not be written.

Purposed Change

Add a new page in Wiki, to document the following topics

• how to connect to non-ODE external libraries
• how the code be generated in non-ODE external libraries
• how to use ODEInfo to connect ODE solver
• how the code be generated in the ODE solver
• What's the difference in generated code between 'when giving explicit equations are taken' and 'the ODE be solved'?
  • ~~@JacquesCarette sorry I didn't ask in the meeting directly. I am not sure I completely understand this question. Would you mind clarifying what it means "once where the explicit equations are taken, how that goes to code" and "once ODE solved and how that goes to code".~~

[smiths]

@cd155, what @JacquesCarette meant by "once where the explicit equations are taken" is to document the code generation stage for a non-ODE example. For instance, GlassBR is an example where code is generated from explicit equations. (Explicit means an equation where the LHS is the dependent variable and its value is defined by the expression on the right hand side. The dependent variable does not appear on the RHS (if it did, then the equation would be implicit). What we have not really documented is how we go from the "instance model" to the generated code. We haven't done this for the case of the ODEs, and we haven't done this for the case of explicit equations.

[cd155]

The documentation for Choices is located on https://github.com/JacquesCarette/Drasil/wiki/The-Code-Generator I did document codeSpec, but it is not completed.

This is ticket is partially overlap with what @peter-michalski did in #2961. The work flow chart is helpful to understand how the Drasil Code Generator generate code.

Do you think this should be closed? @smiths

[smiths]

@cd155, yes I think we can close this issue. We will always be working to improve our documentation, but I think the topics mentioned in this issue have been sorted out.

Thank you @cd155 for your work to address your open issues. Much appreciated!