Clarify how time is represented in each phase of a System step

[adlarkin]

Signed-off-by: Ashton Larkin [email protected]

[adlarkin]

One other thing to note is that the initial time is 0 when using the ign gazebo command (i.e., paused simulation), while the initial time is dt if the ign gazebo -r command is used (i.e., starting simulation by default). Would this be something worth adding to the documentation?

[chapulina]

This looks reasonable to me. All 3 callbacks are consistent and have the same time for a given step. The relationship between each callback and that sim time is given by the callback's name: PreUpdate happens before that time is reached, Update happens during, PostUpdate happens after.

I think we should also update this tutorial. We may even want to add some more details to the tutorial, like explaining that there's no time zero when the simulation is running.

[adlarkin]

I think we should also update this tutorial. We may even want to add some more details to the tutorial, like explaining that there's no time zero when the simulation is running.

Does anyone have a good way to explain why there's no time zero when simulation starts un-paused, but why there's a time zero when simulation starts paused? The ladder case is simply because simulation hasn't started yet, so the simulation time is zero... but, I'm having a harder time figuring out an intuitive way to explain why there's no time zero for the former case.

[chapulina]

Does anyone have a good way to explain why there's no time zero when simulation starts un-paused

When simulation starts unpaused, the very first iteration is already affecting simulation. Since there's no way to alter time zero, there isn't a time zero in this case.

When simulation starts paused, systems will keep seeing time zero until simulation is unpaused.

The same goes for any paused state in the middle of simulation. If the user pauses right after sim time 1 min, all paused updates should keep receiving sim time 1 min, which is in the past, with dt == 0, until simulation is unpaused.

[azeey]

When simulation starts unpaused, the very first iteration is already affecting simulation. Since there's no way to alter time zero, there isn't a time zero in this case.

This might make sense from the view point of being able to alter state, but not from knowing what the current state is. i.e, I think
the state of the world on the very first call to PreUpdate is the state at time zero, even if simTime says it's 0+dt. If a system wants to report the initial state of the world, this would be the time to do it. Of course, if the system uses simTime as the timestamp, it will be incorrect.

So, IMO, we should document that simTime does not refer to the current time, but the time reached after PreUpdate and Update calls have finished. If *Update functions are called with simulation paused, time does not advance; therefore, the time reached after PreUpdate and Update is the same as the starting time, which explains why there is a difference in starting simulation paused and un-paused.

[adlarkin]

Thanks, @azeey! I think that's a great explanation. I tried to incorporate this in e8a3401; let me know if you think this should be modified in any way.

One other (minor) thing to note is that since we are using Doxygen for the documentation in System.hh, links are automatically generated whenever a reference is made to the UpdateInfo struct (which is desired behavior). However, since the tutorial is in markdown, I'm wondering if we should add a manual link to UpdateInfo in the tutorial so that readers of the tutorial have a reference to it - is anyone opposed to me adding these links in to the tutorial?

[azeey]

I'm wondering if we should add a manual link to UpdateInfo in the tutorial so that readers of the tutorial have a reference to it - is anyone opposed to me adding these links in to the tutorial?

I'm not opposed to this, but the tutorials are also rendered using Doxygen and if you use the namespace qualified name (eg. ignition::gazebo::UpdateInfo), I believe Doxygen will automatically generate the link. This is nice because the link never has to be updated manually when we update gazebo versions.

[adlarkin]

I'm not opposed to this, but the tutorials are also rendered using Doxygen and if you use the namespace qualified name (eg. ignition::gazebo::UpdateInfo), I believe Doxygen will automatically generate the link.

Thanks for pointing that out; I wasn't aware we could do this. I've used this approach to add links in the tutorial in 0153ef8.