PhET-iO design for Geometric Optics: Basics

[pixelzoom]

@arouinfar and I discussed the general requirements in #2, and how what they mean for PhET-iO instrumentation.

Changing defaults, and showing/hiding things in the sim is easy. On the other end of the spectrum is PhET-iO: it's difficult to change what PhET-iO elements are created, so that things that are not relevant to Basics are never created, and don't appear in the Studio tree. We're not sure how to proceed, and should have a general discussion.

In the meantime, I'm going to take the absolute easiest approach to make the sim look & behave as desired.

[pixelzoom]

@samreid commented in #2, which is about general requirements. I'm moving that comment to this issue, which is about PhET-iO design. Responding to the comment above, @samreid said:

On the other end of the spectrum is PhET-iO: it's difficult to change what PhET-iO elements are created, so that things that are not relevant to Basics are never created

We have faced this in Circuit Construction Kit and in Center and Spread. For instance, in center and spread, this code only instruments the velocity of an object in the soccer screens:

this.velocityProperty = new Vector2Property( options.velocity, {
  tandem: objectType === CASObjectType.SOCCER_BALL ?
          options.tandem.createTandem( 'velocityProperty' ) :
          Tandem.OPT_OUT
} );

To clarify. The velocityProperty is always created, but a PhET-iO element is only created when appropriate.

We have also adjusted tandem names as appropriate for the context:

this.addLinkedElement( casObject, {
  tandem: options.tandem.createTandem(
    casObject.objectType === CASObjectType.SOCCER_BALL ? 'soccerBall' :
    'dataPoint'
  ),
  phetioState: false
} );

[pixelzoom]

Yes thanks, I'm familiar with how this can be accomplished, and I've done bits of conditional instrumentation in the past. Imo, it's to be avoided if possible. It's more difficult to design, implement, test fully, and maintain -- a lot of cost for questionable gains. So the question is: Does PhET want to incur that cost?

If PhET does decide to go down the path of conditionally instrumenting (creating different APIs for Full vs Basics), here are the Pros and Cons:

Pros

• The Basics API will be arguably simpler, since it won't contain as many things that are not relevant.

Cons

• More difficult/costly for PhET to design, implement, test, maintain.
• Instructional Designers will need to learn how to navigate 2 different Studio trees.
• Client code will be more difficult to repurpose/tweak because the APIs will be significantly different.

Pro or Con?

• The client will not have the option of restoring something that PhET has decided to remove from the Basics version. For example, if the client would like to have 2 arrows in their Basics version, that will be impossible.

[pixelzoom]

Here's an idea...

Instead of a costly development effort to create a version of a sim, why doesn't PhET use Studio to create versions? Right now, I can take the full version of Geometric Optics, and customize it in Studio to do 95% of what we want for the Basics version. But I can't turn that into something that PhET can publish. So instead, I'm going to spend days of programming to accomplish what could be done with Studio in a few hours.

Is using PhET-iO to create and publish variations of PhET sims something that should be pursued? Creating something like Geometric Optics: Basics could conceivably be done by a designer in a few hours, rather than a developer in weeks or months.

[samreid]

I proposed a similar idea for simplifying the creation of sim variations in phetsims/chipper#1153 (comment). Many of those pros and cons also apply to this proposal.

[pixelzoom]

Update: Geometric Optics: Basics was feature-complete < 24 hours after the creation of its repository. The PhET-iO API (and Studio tree) is currently identical to Geometric Optics, and I consider that to be advantageous for PhET and clients. If PhET decides to conditionally uninstrument/rename PhET-iO elements for Basics, I suspect that's going to take many days (if not weeks) of design and implementation.

[pixelzoom]

2/24/2022 design meeting:

The consensus was that "one API, one Studio tree" is a good fit for these sims.

• I'm going to restore both lens shapes, so that they can be restored via Studio, if desired. We decided not to restore the non-flat mirror shapes, because we'd like the mirror to be freely draggable, and it's in a position optimized for a flat mirror.

• I also noticed that there's a layout problem when 'direct' is the default. The UI components to the left of the control panel are in a bad location.

[pixelzoom]

Change requests from 2/24/2022 design meeting were completed in the above commits.

Ready for PhET-iO design and review. Highly recommended to start with the full version in phetsims/geometric-optics#237.

[arouinfar]

@pixelzoom I've finished my review of the Studio tree. I made sure to exercise the features that aren't in the phet-brand version of this sim but can be enabled via PhET-iO. In general, the tree looked great and there was very little to report.