Little documentation on how to interpret the objects in the YMMSL file once loaded

[djgroen]

In developing FabMUSCLE I found the MUSCLE3 documentation to be generally pretty good. However, there is very little information on how the Configuration YMMSL object can be processed once it's read in.

I currently went to the Source code and investigated all the Python files related to it to figure out how to extract ComputeElement object names and implementation, but perhaps there could be some documentation on how these YMMSL objects are structured.

This ticket may be too early, as I do acknowledge there are still design iterations going on (e.g., multiscale/muscle3#21)

[LourensVeen]

Did you see the separate ymmsl-python documentation? Is the issue that that's not complete enough, or that there's no clear link in the MUSCLE 3 docs to it?

[djgroen]

I did find that, and the issue is that it's not complete enough. The section https://ymmsl-python.readthedocs.io/en/master/ymmsl_python.html#reading-ymmsl-files is very brief, and only describes how to load the file without explaining the structure of the Configuration object in any way. It does refer to the API documentation, but there it only tells the user about two fields (model and settings) without referring any further.

[LourensVeen]

Okay, I think I see what you mean. The model attribute is of type ModelReference or Model (which is derived from ModelReference), so you can look there to see what attributes it has in turn, and work your way down the tree that way. That's not explained really, and the Working with yMMSL objects section is a wall of text that assumes too much familiarity with YAtiML, and doesn't really explain the object model.

I'll transfer this issue to the ymmsl-python repo, and will fix it for the next release.

[djgroen]

Sounds reasonably to me. To give you an example of the way I use it, you can have a look at the 20-line make_muscle_ensemble() function in https://github.com/djgroen/FabMUSCLE/blob/master/FabMUSCLE.py. This may be useful, as I can imagine other launcher-developers will be wanting to do similar things?

[LourensVeen]

Yes, probably. I'm happy to see that that looks nice and clean, so I think the object model is pretty good, it just needs better documentation.

[LourensVeen]

Okay, I've looked at the documentation in detail again now, and with the benefit of not having seen it for a while, it did look pretty poorly written. So I've mostly redone the documentation, see https://ymmsl-python.readthedocs.io/en/latest/index.html. I'm honestly not entirely sure that this is much better, but probably at least a little. I'd love to hear your opinion. Note that the API docs have a rendering issue (#4) that I need to look at at some point, but I need to move on with other things first.

Note that there's also a new release 0.10.0, because I'm cleaning up a bit of a naming mess in MUSCLE 3 by now consistently referring to global model settings as settings, not parameters (something like a random number seed is clearly not a model parameter). I tried to do that for MUSCLE 3 0.1.0, but missed several spots, so now things are inconsistent. In fixing that, I renamed ParameterValue to SettingValue in ymmsl-python, and created a new release to depend on for MUSCLE 3 0.2.0. MUSCLE 3 0.1.0 is pinned to ymmsl-python 0.9.1, so that shouldn't break.

[LourensVeen]

@djgroen Not sure if you got pinged on this, since it's now in the other repo. See above :).

[djgroen]

Thanks for pinging me. I'm in the busy part of my teaching term, but I did chalk this up my task list and will be happy to look into this once my schedule is slightly bit quieter (estimate: in 1-3 weeks).

So far I had been focusing on the deployment issue on Eagle, but when I look into MUSCLE3 the next time, I'll examine this instead :).

[LourensVeen]

Perfect, take your time :). The new MUSCLE 3 release 0.2.0 should be out soon, it will have some improvements for distributed running as well, so maybe that will help the Eagle issue too.