Documentation improvements

[Samuel-amap]

Some other issues are related to documentation enhancements, but other general remarks or specific errors could be added here over time until it gets a makeover.

[Samuel-amap]

A few notes :

More Multiscale examples would be worthwhile. There are several ways of declaring code before running a simulation, and more examples with MTGs could help users.

The difference between Status() and status() might need some clarification, examples make use of both without explaining the difference. Making a distinction between 'timestep state', final state, current status, etc. would also be clearer.

[Samuel-amap]

Some of PlantSimEngine's requirements for a modeler, worth making very easy to access in the documentation, and which may constrain the way processes are broken down into models or coupled together :

• Hard dependencies can only have one parent
• Can't have two variables with the same name in the same scale
• No cyclic dependencies, those need to be broken up with usage of values of the previous timestep, or the models need to be designed differently
• One can only make use of the previous timestep, for anything beyond, modelers will have to handle themselves
• Hard dependencies need to be declared
• Modelers need to explicit whether parallelization is possible over organs or timesteps for each model
• Meteo values and Status variables currently need some kind of consistency in terms of the # of timesteps
• Steady-state assumption between timesteps
• No interpolation (?)
• It is currently assumed users and modelers use data types with enough precision to prevent accumulation errors
• Organs missing in the initial MTG but declared in the mapping are organs created during simulation, with consistent naming (?)

[Samuel-amap]

Another heavily implicit aspect of PlantSimEngine (that should remain true in the future) is that **Weather inputs are the timeline's baseline **.

Any kind of model timestep is expected to be a multiple of (or possibly interpolatable from) the weather data timestep. This design aspect makes sense for many plant models and the approximations they make but needs to be justified and very explicit in the documentation, and properly handled internally.

[Samuel-amap]

More implicit constraints of PSE :

• Status templates and variables are initialised / queried in a specific order : (If I'm not mistaken) soft dependency nodes initialise their scale's status templates. After that, nodes already present in the MTG are queried for any variables that may be initialised. If a status template is empty but some variables are requested as global outputs the corresponding template will be initialised [Note : this can leave some status templates uninitialised, see Uninitialised status template in HardDependency #103]. Then user-provided variables are inspected (?)

• A model cannot be used twice within the same process, nor can it be used twice at the same scale. (Needs confirmation)

[Samuel-amap]

PSE has two main, somewhat distinct, use cases :

• a ModelList with a few models, and a 'simple' simulation that can run quite fast and might be parallelisable
• More complex multiscale simulations involving many specialised models + some that are used as workarounds, ...

A tutorial or piece of documentation could be more explicit in there being two clearly distinct approaches. The slight differences in goal (and API) mean there might be slightly different communities and users, and current documentation is not very clear for either.

[Samuel-amap]

Something that came to mind after fiddling with the coupling example in the tests that is used to check MTG growth :

It might not be obvious to a user (especially if they have an L-system or diffusion model POV, perhaps ?) how to couple models in such a way that it is possible for them to implement a diffusion-based approach that makes a decision on how a resource is distributed or mapped at (for example) every branching point of a tree.

Such an approach is possible in PSE, but might require a (slightly clunky ?) model that heavily iterates across the MTG. Coupling it with other models would be non-trivial.

It might be worth clearing up any confusion users/modelers could have and providing some examples of such an approach.

[Samuel-amap]

Worth documenting explicitely : workarounds for variables updated multiple times / non-steady state model handling #114

Also worth documenting clearly : no current way of handling cyclic dependencies in modellist mode : #130

[Samuel-amap]

Other random notes :

Initialisation order needs more clarification.
MTG scale and symbol are different concepts compared to PSE's organ/scale, and Julia's symbols. Also, root/tree/leaf discussion can get confusing when detailing organ creation.

add_organ! and node creation with attributes need to be detailed a little, possibly

[Samuel-amap]

Another aspect well-worth detailing :

Straightforward organ creation models lead to an instant MTG and GraphSimulation update, which means the new organ might be run immediately in the following timestep, and create another organ if the conditions are still met, which they can be if resources only update next timestep (also leading to a potential bug in terms of resource consumption equilibrium).

I'm pretty sure this issue was encountered and worked around several times in XPalm (and slower and more realistic growth leads to this problem being much more minor, and errors being very marginal, and possibly compensating each other somewhat). Organs being initially immature -at least for one timestep- is one solution, others could probably be discussed.

This is due to the way run! is implemented in multiscale, operating on node statuses at a specific scale. Adding dynamically to this status collection means the new nodes will be iterated on in the same timestep. It looks like a bug to me, but there might be a rationale for this, it needs more discussion.

For now, the order in which models are run, and the order in which organs are added and iterated on can lead to behaviour that needs to be worked around. And the way things are, deleting nodes would probably lead to bugs (but deleting nodes doesn't happen in XPalm), so worth pointing out.

[Samuel-amap]

#128 updates documentation and addresses most of the points mentioned here. New and leftover problems can go in a new issue.