Create examples.md for DC flavors

[arouinfar]

This sim will need client guides before this sim goes into RC for full publication.

[arouinfar]

Include an example with vertex.isDraggableProperty vertex.isCuttableProperty and vertex.labelProperty are customized. Let users know that students can add onto this special vertex with their own components, but deleting that component won't affect the other customizations in the circuit. #833

[arouinfar]

Examples.md should be created after the PhET-iO design is complete, so marking as on-hold.

[samreid]

Also, in https://github.com/phetsims/circuit-construction-kit-common/issues/876 we decided to document a strategy for customizing dragged-out objects. That would likely be written in examples.md.

[arouinfar]

Here's what @samreid wrote up in #876:

Here is a line of code that customizes elements as they are created:

phetioClient.invoke( 
'circuitConstructionKitDc.introScreen.model.circuit.resistorGroup.elementCreatedEmitter', 
'addListener', [
( state, phetioID ) => phetioClient.invoke( phetioID + '.isEditableProperty', 'setValue', [ false ] )
]);

It can be pasted in the chrome dev tools while running studio. Or it can be added to a wrapper. Or after running Studio => Test, you can paste it in the launched sim.

[arouinfar]

From @samreid in #898

Current and Power Readings

Due to an implementation detail in the simulation, the current and power are computed in a 2-phase algorithm, and have their values set twice during one step. So if you are observing values like circuitConstructionKitDc.introScreen.model.circuit.lightBulbGroup.lightBulb_0.currentProperty or circuitConstructionKitDc.introScreen.model.circuit.batteryGroup.battery_0.powerGeneratedProperty in the data stream or by adding listeners to them, please be aware there will be the intermediate value and the final value. The intermediate value is computed by the numerical algorithm, then the final value is computed via a post-processing "current conservation" step, which often just changes the values slightly.

[arouinfar]

Explain https://github.com/phetsims/circuit-construction-kit-common/issues/929 to load saved circuits created from Studio.

Inspect circuitConstructionKitDc.*Screen.model.circuit in Studio, and use Get Value to populate the text box with the circuit state. The Copy Set Value Code will copy the phetioClient.invoke command for this circuit onto the clipboard. Verify the circuit is correctly restored by testing it in the Standard PhET-iO Wrapper (either Test or Download will do). If it looks good, use this code in your custom wrapper.

One limitation is that circuits must be saved on the appropriate screen. You cannot load a circuit created on the Lab Screen on the Intro Screen, or vice-versa. Circuit elements outside of the layoutBounds will likely shift when restored, so be cognizant of the aspect ratio.

[arouinfar]

For #630 we should include examples that include

• Re-indexing carousel items, calling attention to the multiple wires.
• Hiding page control dots if the carousel is reduced to a single page or if the carousel is hidden entirely.
• If hiding Real Bulbs, also hide checkbox.

[arouinfar]

I've committed an initial draft of the examples. Next, I'll review and adapt for the virtual-lab flavor.

[arouinfar]

@samreid @matthew-blackman I've completed the examples.md for both DC flavors. https://github.com/phetsims/phet-io-sim-specific/blob/master/repos/circuit-construction-kit-dc/examples.md https://github.com/phetsims/phet-io-sim-specific/blob/master/repos/circuit-construction-kit-dc-virtual-lab/examples.md

@matthew-blackman can you take a look and see if there are any else you think we should highlight? This can be done as a part of our self-QA process.

[matthew-blackman]

There are looking really nice! I added a section to each for 'Voltmeters and non-contact ammeters', describing the probe connection properties and how they can be used. @arouinfar if all looks well, these files are looking very comprehensive to me!

[arouinfar]

Thanks @matthew-blackman! I made a few edits to the example you added and removed mention of the non-contact ammeter from the virtual-lab guide since it's irrelevant. I think we're ready to close this issue.