From fd3e61799e5ab66fa674e19899699dd3011f24b2 Mon Sep 17 00:00:00 2001 From: pixelzoom Date: Thu, 7 Mar 2024 12:22:39 -0700 Subject: [PATCH] https://github.com/phetsims/faradays-electromagnetic-lab/issues/71 --- doc/implementation-notes.md | 137 ++++++++++++++++++------------------ doc/model.md | 2 + 2 files changed, 70 insertions(+), 69 deletions(-) diff --git a/doc/implementation-notes.md b/doc/implementation-notes.md index ffaaa98b..7eafee00 100644 --- a/doc/implementation-notes.md +++ b/doc/implementation-notes.md @@ -9,6 +9,9 @@ * [Coordinate Frames](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#coordinate-frames) * [Query Parameters](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#query-parameters) * [Memory Management](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#memory-management) + * [Software Design Patterns](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#software-design-patterns) +* [Model](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#model) +* [View](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#view) * [Sound](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#sound) * [Alternative Input](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#alternative-input) * [PhET-iO](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#phet-io) @@ -17,8 +20,7 @@ This document contains notes related to the implementation of _Faraday's Electromagnetic Lab_. This is not an exhaustive description of the implementation. The intention is to provide a concise high-level overview, and to supplement the internal -documentation -(source code comments) and external documentation (design documents). +documentation (source code comments) and external documentation (design documents). Before reading this document, please read: @@ -89,44 +91,36 @@ public dispose(): void { } ``` -## Sound - -As of the 1.0 release, UI Sounds are supported, while sonification is not supported. - -`WaterFaucetNode` has a temporary implementation for UI Sound, intended to be removed when sound design is -completed for `FaucetNode`; see [scenery-phet#840](https://github.com/phetsims/scenery-phet/issues/840). - -`FELSonifier` and its subclasses may be ignored. They are experimental sonification code that is not included in -the 1.0 release. We will revisit this code in a future release. - -## Alternative Input - -To identify code related to focus order, search for `pdomOrder`. - -To identify sim-specific support for keyboard input, search for `tagName`. These classes have custom input listeners -(typically `KeyboardDragListener`) that handle keyboard events. - -This sim currently does not make use of hotkeys (aka, shortcuts). But if it does in the future... -To identify hotkeys, search for `addHotkey`. +### Software Design Patterns -When a draggable object has focus, it is immediately draggable. This sim does not use `GrabDragInteraction`, which -requires a Node that has focus to be "grabbed" before it can be dragged. PhET typically does not use `GrabDragInteraction` -until Description is supported. - -## PhET-iO +**Class fields of type Property** This pattern may be unfamiliar and is used frequently for model Properties. +We desired a public API that is readonly, while the private API is mutable. This is accomplished using +two class fields, both of which refer to the same Property instance. The field names are similar, with the private +field name having an underscore prefix. Here's an example: -The PhET-iO instrumentation of this sim is relatively straightforward. As described -in [Memory Management](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#memory-management), -everything that needs to be stateful is created at startup, and exists for the lifetime of the sim. -So there is no sim-specific use of `PhetioGroup` or `PhetioCapsule`. - ------ +```ts +class SomeClass { + + // Position of this model element + public readonly positionProperty: TReadOnlyProperty; + private readonly _positionProperty: Property; + + public constructor() { + this._positionProperty = new Vector2Property( Vector2.ZERO ); + this.positionProperty = this._positionProperty; + } + + public reset() { + this._positionProperty.reset(); + } +} +``` -//TODO Reuse description from doc/java-version/Physics_Implementation.pdf. +## Model MathCAD data and the B-field. See BarMagnetFieldData.ts. -Model algorithms ported from Java require a constant dt clock, firing at a constant framerate. +Model algorithms ported from Java require a constant dt clock, firing at a constant framerate. FELScreenModel creates an instance of ConstantDtClock to implement this. Instead of overriding step, subclasses of FELScreenModel should add a listener to the ConstantDtClock. See ConstantDtClock.ts and FELScreenModel.ts. @@ -136,43 +130,12 @@ All stepping is handled by the model. The most complicated part of the sim may be `Coil.createCoilSegments`. It creates an ordered `CoilSegment[]` that describes the shape of the coil, and the path that electrons follow as they flow through the coil. So that objects (bar magnet, compass,...) may -pass through the coil, CoilSegments are designated as belonging to either the +pass through the coil, CoilSegments are designated as belonging to either the foreground layer or background layer of the coil. -Coil (model) and CoilNode (view) are generalized, and are used by the pickup coil -and electromagnet. - Pickup coil model is Hollywood. See PickupCoil.ts. -Electrons are lightweight, with no Properties, and no need to be PhET-iO stateful. -They are create by Coil in `createElectrons` when the shape of the coil is changed -(by changing the number of loops, or the loop area). - -ElectronsNode renders all Electrons efficiently using scenery Sprites. Two instances -of ElectronsNode are required, for foreground and background layers. - - - -This pattern may be unfamiliar and is used frequently in the model for Properties. -The public API is readonly, while the private API is mutable. -Both fields refer to the same Property instance. -The field names are similar, with the private field name having an underscore prefix. - -```ts -// Position of this model element -public readonly positionProperty: TReadOnlyProperty; -private readonly _positionProperty: Property; - -public constructor( ... ) { - ... - this._positionProperty = new Vector2Property( ... ); - this.positionProperty = this._positionProperty; -} -``` - -## At A Glance - -Most important part of the model class hierarchy: +The most important part of the model class hierarchy is: ``` CurrentIndicator @@ -195,7 +158,7 @@ FELMovable PickupCoil ``` -_Composition_ (not class hierarchy) for each Screen's TModel: +This diagram shows the _composition_ (not class hierarchy) for each Screen's TModel: ``` BarMagnetScreenModel @@ -248,4 +211,40 @@ GeneratorScreenModel Voltmeter ImmediateCompass FieldMeter -``` \ No newline at end of file +``` + +## View + +`ElectronsNode` renders all Electrons efficiently using scenery `Sprites`. Two instances +of `ElectronsNode` are required, for foreground and background layers of a coil. + +## Sound + +As of the 1.0 release, UI Sounds are supported, while sonification is not supported. + +`WaterFaucetNode` has a temporary implementation for UI Sound, intended to be removed when sound design is +completed for `FaucetNode`; see [scenery-phet#840](https://github.com/phetsims/scenery-phet/issues/840). + +`FELSonifier` and its subclasses may be ignored. They are experimental sonification code that is not included in +the 1.0 release. We will revisit this code in a future release. + +## Alternative Input + +To identify code related to focus order, search for `pdomOrder`. + +To identify sim-specific support for keyboard input, search for `tagName`. These classes have custom input listeners +(typically `KeyboardDragListener`) that handle keyboard events. + +This sim currently does not make use of hotkeys (aka, shortcuts). But if it does in the future... +To identify hotkeys, search for `addHotkey`. + +When a draggable object has focus, it is immediately draggable. This sim does not use `GrabDragInteraction`, which +requires a Node that has focus to be "grabbed" before it can be dragged. PhET typically does not use `GrabDragInteraction` +until Description is supported. + +## PhET-iO + +The PhET-iO instrumentation of this sim is relatively straightforward. As described +in [Memory Management](https://github.com/phetsims/faradays-electromagnetic-lab/blob/main/doc/implementation-notes.md#memory-management), +everything that needs to be stateful is created at startup, and exists for the lifetime of the sim. +So there is no sim-specific use of `PhetioGroup` or `PhetioCapsule`. \ No newline at end of file diff --git a/doc/model.md b/doc/model.md index 6efea966..7bbe2c39 100644 --- a/doc/model.md +++ b/doc/model.md @@ -1,5 +1,7 @@ TODO https://github.com/phetsims/faradays-electromagnetic-lab/issues/70 +Reuse description from doc/java-version/Physics_Implementation.pdf. + MathCAD for 1G bar magnet. Pickup Coil models Faraday's Law. Induced EMF is used to derive current amplitude.