PhET-iO instrumentation notes

[pixelzoom]

This issue contains misc notes about PhET-iO instrumentation, which will hopefully benefit whoever does the instrumentation.

Vector Addition was not instrumented for PhET-iO when initially developed, and the implementation was not informed by any PhET-iO design requirements. Other than using type-specific Properties (e.g. BooleanProperty), and tandems for top-level model and view types (provided by simula-rasa template) no consideration was given to PhET-iO.

Most of the objects in the sim are created on startup, and exist for the lifetime of the sim. Instrumentation of those objects should be straightforward: identify which objects should be PhET-iO elements, add tandems to those elements in code, specifying metadata related to elements in Studio.

In the Equations screen, all vectors are created at startup. This screen has different learning goals, and the UI for this screen consequently does not support creation or deletion of vectors.

Each vector set has a sum vector, and the model and view for that sum vector (and its component vectors) is created at startup for all screens.

In the Explore 1D, Explore 2D, and Lab screens, all non-sum vectors (and their component vectors) are dynamic elements. They are created when dragged out of the toolbox, and disposed when returned to the toolbox. The reason for this is historical. These screens share the same toolbox implementation, and until very late (after dev testing), the Lab screen supported the ability to create an infinite number of vectors. This was changed to a fixed limit (10), and all screens with toolboxes now have a limit. (The limit in Explore 1D and Explore 2D is 1.) While it would therefore be possible to create all vectors at startup, I recommend against it: it would be a non-trivial implementation change, we seldom expect all 40 vectors (2 scenes * 2 vector sets * 10 vectors) to be used in the Lab screen, and (though unlikely) we could never change back to infinite vectors in the future.

So vectors (model and view) will need to be instrumented using PhET-iO's dynamic element mechanism, which is PhetioGroup as of the writing. Vector and VectorNode are the relevant classes.

Below is a list of related classes that are created dynamically when a Vector or VectorNode its created. According to @samreid in https://github.com/phetsims/phet-io/issues/1454#issuecomment-546559626, these classes should not need their own PhetioGroups.

Vector subcomponents
ComponentVector - 2 per Vector

VectorNode subcomponents
ComponentVectorNode- 2 per VectorNode
DashedArrowNode - 1 per ComponentVectorNode
VectorAngleNode - 1 per VectorNode
CurvedArrowNode - 1 per VectorAngleNode
VectorLabelNode - 1 per VectorNode, 1 per ComponentVectorNode
VectorSymbolNode - 1 per VectorLabelNode
ArrowOverSymbolNode - 1 per VectorSymbolNode
SCENERY_PHET/ArrowNode - 1 per VectorNode