Make example-sim a better example.

[pixelzoom]

Many of the questions in the Google Group deal with how to get started with designing and developing their own sim. This is beyond the scope of the PhET Development Overview document. I typically point to example-sim as a starting point, even though I don't feel like it's a great "example" Some things that would make it better:

• Add a very simple 2nd screen and common/, to make it easier to understand the repo structure of most PhET sims.
• Comment the code in a more tutorial fashion.
• ???

Assigning to me and @chrisklus, who has been using example-sim for on-boarding new developers.

[pixelzoom]

Summary of above commits:

• Renamed the existing screen to "Magnets". It currently has only 1 magnet, but a common test/instructional task is to add additional magnets.
• Moved ResetAllButton to standard PhET location (bottom-right).
• Moved control panel to standard PhET location (top-right).
• Added an empty "Particles" screen. My plan for this is to add a quick example that was requested on the Google Group in https://groups.google.com/g/developing-interactive-simulations-in-html5/c/nrBahpJjAf0.
• Revised code comments to be more verbose and instructional.

Before making these changes, I discussed with @chrisklus, to make sure it wasn't going to impact his use of example-sim for instruction. He had no concerns.

I asked @kathy to point me to the Google Doc that is used for test tasks, given to prospective developer candidates. She referred me to this document and I've updated it as needed. It mostly involved renaming classes. I also fixed typos and grammar that were already present in the document.

I asked about any other related materials on Slack dev-public, but none were identified.

Finally, I tested a local build. Then I did grunt dev --brand=phet to publish 1.0.0-dev.18.

[pixelzoom]

The Particles screen has been fleshed out, and I've described to the Google Group user in https://groups.google.com/g/developing-interactive-simulations-in-html5/c/nrBahpJjAf0.

Published in 1.0.0-dev.19.

We'll need a revised screenshot.

There's also likely a memory leak in the Particles screen. If I leave it running in Chrome for a few minutes, then Chrome won't reload the page. The sim keeps running.

[pixelzoom]

I think this is ready for a review. @chrisklus would you mind taking a look? Anything else you'd recommend to make example-sim more effective for tutorials, etc?

When this issue is ready to close, example-sim should be announced to the Google Group as "new and improved".

[pixelzoom]

@chrisklus ping. I'd like to get your feedback on this, so that I can announce the improvements to the Google Group.

[chrisklus]

The changes above are looking great. I like having multiple screens, and that the magnets screen is more representative of a typical PhET ScreenView layout.

I also like that the Particles screen adds more common PhET patterns like Emitter, the usage of step(), and a scenery-phet component like TimeControlNode.

My one suggestion for improvement is to document the units for the model side of the particles screen, and, if needed to make sense, improve the interactions between the variables in applyForce. Since PhET models are often made to be as realistic as possible, it would be nice to reflect that here. It could also give more purpose to the MVT being used - if the particles are some standard size in the model, they could be scaled to their existing size in the view. So I'm referring to units in Particle.js for velocity and positionProperty, as well as GRAVITY in ParticlesModel.

However, I could also see how it might be nice to have everything abstract in the way that it is and just deal with screen coordinates. What do you think @pixelzoom?

[pixelzoom]

I did indeed punt on using physically-realistic units in the Particles model. But I did include a model-view transform in ParticlesScreenView.js:

    // Transform from model coordinates to view coordinates. We're using an identity transform here to demonstrate,
    // but it's almost always a good idea to have such a transform. To see how a different transform can result in
    // a different result in the view, try using this transform, which will cause the particles to flow upward:
    // const modelViewTransform = ModelViewTransform2.createOffsetXYScaleMapping( new Vector2( 0, 500 ), 1, -1 );
    const modelViewTransform = ModelViewTransform2.createIdentity();

So if I understand the suggestions in https://github.com/phetsims/example-sim/issues/13#issuecomment-872493807, you'd like to see particle-like units in the model (nm, ns,...), and a non-identity model-view transform. Do I understand that correctly @chrisklus?

[chrisklus]

So if I understand the suggestions in https://github.com/phetsims/example-sim/issues/13#issuecomment-872493807, you'd like to see particle-like units in the model (nm, ns,...), and a non-identity model-view transform. Do I understand that correctly @chrisklus?

Yes, I thought that would be a more PhET-like model and demonstrate the convenience of scaling with a MVT.

[pixelzoom]

In the above commits, I changed the model units to nm and nm/sec, and I defined the model's origin to be the point where the particles originate.

In ParticlesScreenView, there is now a model-view transform that moves the orgin, and scales from nm to pixels:

    // Transform from model coordinates to view coordinates. The model's origin is at the position where the
    // particles originate. Move that position to the top center of the screen.  Since the model is in nm,
    // scale up from model to view. And since +y is up in the model, the y scale is negative because +y is
    // down in the view (scenery).
    const viewOffset = new Vector2( this.layoutBounds.centerX, 20 );
    const modelViewTransform = ModelViewTransform2.createOffsetXYScaleMapping( viewOffset,
      1 / NANOMETERS_PER_PIXEL, -1 / NANOMETERS_PER_PIXEL );

There lots of interesting programming tasks that could be assigned for this screen, including:

• Change the model-view transform so that particles spray up from the bottom center of the screen.
• Use dt in ParticlesModel, instead of applying an identical force on each step.
• Create particles with random diameter and/or color.

@chrisklus please review, and let me know if you have any other recommendations.

[chrisklus]

Nice, the above commits look great. I think this screen is in good shape for example-sim "level 2". Sola and I can try out the new noted tasks as part of his learning.

Thanks much @pixelzoom, ready to close if you are.

[pixelzoom]

I announced example-sim improvements in this post to the Google Group: https://groups.google.com/g/developing-interactive-simulations-in-html5/c/zkiFrut0oHE

Two more things to do:

• [x] A new screenshot is needed, and I'm not sure what the current procedure is for creating screenshots. I'll ask for a volunteer on Slack.

• [x] Do a production publication of example-sim, since it's runnable from https://phet.colorado.edu/sims/html/example-sim/latest/example-sim_en.html.

[pixelzoom]

Before I could publish a new version, I had to fix master package.json, then do an RC deploy. 1.1.0 is now deployed.

[pixelzoom]

Oops.... I should have updated the screenshot first. Now I'll have to patch the 1.1 branch and publish another production version.

@KatieWoe is going to create an updated screenshot, based on https://phet.colorado.edu/sims/html/example-sim/latest/example-sim_en.html. Start the sim, press the "Magnets" button, and the screen will look like this:

[pixelzoom]

I updated the screenshot in master and 1.1 branches, then published 1.1.1. Tested at https://github.com/phetsims/example-sim/blob/master/README.md.

Closing.