Merge branch 'master' of https://github.com/phetsims/wave-interference

doc/implementation-notes.md

@@ -1,14 +1,22 @@
+# Wave Interference - implementation notes
+
+This document contains notes related to the implementation of Wave Interference. The audience for this document is software developers who are familiar with JavaScript and PhET simulation development, as described in [PhET Development Overview](http://bit.ly/phet-html5-development-overview).
+
+Before reading this document, see [model.md](https://github.com/phetsims/wave-interference/blob/master/doc/model.md), which provides a high-level description of the simulation model.
+
+## Overview
+
 The Wave Interference simulation depicts waves on a 2 dimensional surface and the interference patterns they create.  
 The first 3 screens show a 2D lattice and time-based wave propagation, while the fourth screen shows the interference 
 pattern from a slit with a given 2d shape, which is instantly updated.  
 
-The query string ?log can be used to output the selected frequency and wavelenth, for debugging.
+The query string `?log` can be used to output the selected frequency and wavelenth, for debugging.
 Other sim-specific query parameters are described in wave-interference/js/common/WaveInterferenceQueryParameters.js
 
 There are no dynamically created/destroyed user interface components or model elements in the simulation, so the
 simulation doesn't require dispose calls.
 
-# The first three Screens: Waves, Interference, Slits
+## The first three Screens: Waves, Interference, Slits
 
 The first three screens are mainly implemented in js/common.  
 
@@ -34,7 +42,7 @@ The lattice extends beyond the visible region, and damping is applied near the b
 reflection and artifacts around the edges.
 
 We run the physics on a finite discrete lattice, but must match up with the correct values (frequency, wavelength and
-wave speed) for each scene.  Run the simulation with ?dev to get corresponding output in the console.  Use the stopwatch 
+wave speed) for each scene.  Run the simulation with `?dev` to get corresponding output in the console.  Use the stopwatch 
 and sim play/pause feature to record one cycle.  To measure the wave speed, let the light propagate to the edge of the 
 boundary, then use the measuring tape to measure distance and divide by the elapsed time on the stopwatch.
 
@@ -43,7 +51,7 @@ correct.
 
 The following values can also be reported by running with`?log`.
 
-## Water
+### Water
 | Value | Frequency (Hz) | Wavelength (cm) |
 | :--- | ---: | ---: |
 | min | 0.25 | 7.4 |
@@ -52,13 +60,13 @@ The following values can also be reported by running with`?log`.
 Wave speed measured at 7.1E-2/1.43 = 5cm/sec.  In https://github.com/phetsims/wave-interference/issues/43 we decided this
 is a reasonable wave speed for a wave pool, even though it doesn't match wave speeds for, say, oceanic waves.
 
-## Sound
+### Sound
 | Value | Frequency (Hz) | Wavelength (cm) |
 | :--- | ---: | ---: |
 | min | 220 | 156 |
 | max | 440 | 78 |
 
-## Light
+### Light
 | Color | Frequency (THz) | Wavelength (nm) | 
 | :--- | ---: | ---: | 
 | Red (VisibleColor min) | 384.35 | 780.00 | 
@@ -69,13 +77,13 @@ which is about 4% off of the true speed of light.  Measuring the colored wavefro
 Since the distance and wave propagation speeds are independent of frequency, measurements for different colors will
 give the same speed of light.  See also WavesScreenModel usage of `timeScaleFactor` for how the model is calibrated.
 
-## Slits Screen
+### Slits Screen
 Here is a schematic for the two-slit dimensions:
 ![schematic for the two-slit dimensions](images/slitDimensions.jpg?raw=true "Two-Slit Dimensions")
 
-By using ?dev, you can show the IdealInterferenceOverlay, which depicts d sin(θ) = mλ (theoretical maxima) and d sin(θ) = (m+1/2)λ (theoretical minima).
+By using `?dev`, you can show the IdealInterferenceOverlay, which depicts d sin(θ) = mλ (theoretical maxima) and d sin(θ) = (m+1/2)λ (theoretical minima).
 See https://github.com/phetsims/wave-interference/issues/74
 
-# The Final Screen: Diffraction
+## The Final Screen: Diffraction
 In the fourth screen, we use a Fast Fourier Transform (FFT) in order to compute the diffraction pattern, see
-https://en.wikipedia.org/wiki/Diffraction
+https://en.wikipedia.org/wiki/Diffraction

doc/model.md

@@ -1,32 +1,39 @@
-# Waves Screen
+# Wave Interference - model description
+
+This is a high-level description of the model used in Wave Interference. It's intended for audiences
+that are not necessarily technical.
+
+## Waves Screen
 
 This screen depicts a 2D wave on the surface of water, or the cross-section of a spherical wave for sound or light. The
 user can choose between a continuous or pulse wave.  The user can control the frequency and amplitude of the wave,
 and observe how it appears on the center line in a chart.  For light, the user can also observe the light collecting
-on the screen on the right.  The wave speeds can be computed as wave speed = frequency * wavelength.
+on the screen on the right.  The wave speeds can be computed as `wave speed = frequency * wavelength`.
 
-# Interference Screen
+## Interference Screen
 
 This screen has two point sources that can be enabled/disabled independently, and interference patterns emerge from the
 overlapping waves.  The point sources are always in-phase.  The interference pattern shows constructive interference
-at d*sin(theta) = m*lambda.
+at `d * sin(theta) = m * lambda`.
 
-# Slits Screen
+## Slits Screen
 
 This screen provides an incoming plane wave, and the user can control the location of the barrier, the number of
 slits and the location and width of the slits.  According to the Huygens-Fresnel principle, each part of the wave
 produces spherical waves, and hence the part that passes through the slit produces spherical waves.
 
-For double-slit (where d is the separation between centers of the slits):
-d sin(θ) = mλ for maxima,
-d sin(θ) = (m + 1/2)λ for minima
+For double-slit (where `d` is the separation between centers of the slits):
+* `d sin(θ) = mλ` for maxima,
+* `d sin(θ) = (m + 1/2)λ` for minima
+
 see http://electron9.phys.utk.edu/optics421/modules/m1/diffraction_and_interference.htm
 
-For single slit (where a is the width of the aperture):
-a sin(θ) = mλ for minima
-a sin(θ) = (m+1/2)λ for maxima
+For single slit (where `a` is the width of the aperture):
+* `a sin(θ) = mλ` for minima
+* `a sin(θ) = (m+1/2)λ` for maxima
+
 see http://hyperphysics.phy-astr.gsu.edu/hbase/phyopt/sinslit.html
 
-# Diffraction Screen (under development)
+## Diffraction Screen (under development)
 
-The diffraction pattern is computed as the discrete Fast Fourier Transform of the input pattern.
+The diffraction pattern is computed as the discrete Fast Fourier Transform of the input pattern.