Write a 'Creating a new Drasil Example' document

[JacquesCarette]

The rest of issue #4 is done. Best to create a new issue for this.

[smiths]

Great idea Jacques. I have an example for a fuelpin in a nuclear reactor that would reuse much of the thermodynamics from swhs. It would be a good experiment at some point to see how easy this is to do. Without the "creating a new Drasil example" document, the implementer wouldn't be able to fairly judge how much of the work was infrastructure related and how much was "real work."

[smiths]

@palmerst , please add a link to your notes about why this is difficult.

[Ant13731]

I saw the Wiki article for creating your own project in drasil and I think it could use a little bit of a refresh (in terms of layout and organization, grammar, etc.). Could this issue then be closed once I am finished with that since it already covers creating a new drasil example?

[smiths]

Yes, @Ant13731 this is a great idea. @oluowoj created the original instructions, and they were tested last year by a few students in my grad class. They could use a refresh and an update.

[Ant13731]

I don't think we use Travis anymore for our CI, so should the link in this section be changed/removed: https://github.com/JacquesCarette/Drasil/wiki/Creating-Your-Project-in-Drasil#instructions-on-how-to ? @balacij had a really good summary of how to set it up for gh-actions/gh-pages on one of his pull requests.

[Ant13731]

I think this is pretty much ready for review: https://github.com/JacquesCarette/Drasil/wiki/Creating-Your-Project-in-Drasil

I switched out most of the images for code excerpts. That way, users can copy any needed information directly and the guide can be changed easily to accommodate any updates.

[JacquesCarette]

This looks quite good. It is very "operational", i.e. focuses on getting things done, which is nice. It really points out the fact that more conceptual documentation is still missing (and I need to write some of that).

[smiths]

@JacquesCarette, I discussed with @Ant13731 and @balacij that the best way to review these instructions is for someone to actually use them to do create a new example. If the Mitacs student is still starting this month (I haven't heard anything), maybe she could "test" the instructions by creating a new example? We can use new people to test the new "getting started" information that has been added this summer. (My impression is that future students are in for a real treat. The entry to using and understanding Drasil has definitely taken a nice jump up this summer!)

[JacquesCarette]

She was supposed to have started already... we've been in touch. So what would be a nice new example?

[smiths]

We don't have any numerical library examples in Drasil, so what about adding software for estimating the radius of convergence of a power series:

https://github.com/JohnErnsthausen/roc/blob/master/docs/SRS/SRS.pdf

John did this example for CAS 741. I think it is fairly well done, but it might be too difficult. The example also makes frequent use of indices, which Drasil doesn't yet entirely understand.

Another example is A Cache Coherence Simulator, but I think it is too involved an example. Moreover, we'd have to bring in another party for the domain knowledge, since this isn't an area of expertise for me.

This Radio Signal Strength Calculator is still a physics type example, but with application to data transmission. One of Rong's students did this example. It might be different enough from the current examples to be worth adding? It might also be too complex for a first example for a new student.

We could create another example if we have a target in mind. We would want to be careful to not add anything where we spend too much time working on the example. One thought that comes to mind is to look at the family of projectile motion and change it so that we essentially end the SRS with stating the ODE that needs to be solved. Right now we solve the ODE and give explicit equations to be generated in the code, but we could instead as the code to generate the interface to an ODE solver.

[JacquesCarette]

Very tricky indeed. Maybe start with something very simple, like a 2D physics problem, like simulating the motion of a 'square' on an incline with friction?

[smiths]

I didn't suggest something like a 2D physics problem because we already have physics problems in Drasil. I was also thinking that you wouldn't want the new student spending time on physics, but rather spending time on Drasil programming.

If we are going to add a new example, what about adding an example that focuses on computing, rather than on physics? We could add an example for root finding? If we put in some assumptions about continuity we could make the example fairly simple. If we want something really simple, we could just do the quadratic equation?

It actually would be pretty neat to put interpolation into Drasil, since we use interpolation in GlassBR. If I remember correctly, we use linear interpolation, which is another simple example. At some point it would be nice if GlassBR "knew" what interpolation meant. Right now the code generation and the SRS aren't as connected as they could be.

[JacquesCarette]

One issue is that so many examples go just a tad beyond what Drasil can currently encode. Not having proper sequences, for example, is very restrictive. If we want to find a single root, then root finding is possible.

[smiths]

Here are some options that I've come up with. I believe the examples are simple enough that we can add them to Drasil without having to extend Drasil's capabilities. I've also aimed for examples that overlap with current examples, so that we can refactor the common knowledge.

1. Conservation of momentum to 1D collisions between two masses
2. Free fall calculator - like projectile motion, but in 1D
3. Free fall with air resistance
4. Inclined plane calculator
5. Newton's law of cooling calculator

All of the above examples come from Omni Calculator. I picked examples that overlap with our existing case studies. We could find more examples. The web-pages are pretty good, although not all of the examples explicitly show the equations they are using to solve the problem.

[JacquesCarette]

That sounds good. I guess these potential projects shouldn't be in this particular issue, but somewhere else?

[smiths]

The discussion was about a project for the student that was supposed to start in July. (We kind of hijacked the original issue.) :-) I'm guessing that this discussion of picking a project isn't relevant, since it is almost August and the student hasn't yet started.