This document contains notes related to the implementation of Graphing Quadratic. This is not an exhaustive description of the implementation. The intention is to provide a high-level overview, and to supplement the internal documentation ( source code comments) and external documentation (design document).
The audience for this document is software developers who are familiar with JavaScript and PhET simulation development, as described in PhET Development Overview. The reader should also be familiar with general design patterns used in PhET simulations.
Before reading this document, see model.md, which provides a high-level description of the simulation model.
You may also wish to review the Graphing Quadratics design document, but be forewarned that it is out of date.
This section defines terminology that you'll see used throughout the internal and external documentation. There's no need to memorize this section; skim it once, refer back to it as you explore the implementation.
Standard terminology:
- axis of symmetry - vertical line that intersects the vertex
- constant term - the c term of y = ax2 + bx + c
- curve - generalization of a line, whose curvature need not be zero (geometric definition)
- directrix - a fixed horizontal line used in describing a curve or surface
- focus - a fixed point on the interior of a parabola, used in the formal definition of the curve
- line - a straight curve (geometric definition)
- linear term - the bx term of y = ax2 + bx + c
- parabola - a plane curve generated by a point moving so that its distance from a fixed point (focus) is equal to its distance from a fixed line (directrix)
- quadratic - short for "quadratic equation", in any of the 3 supported forms
- quadratic term - the ax2 term of y = ax2 + bx + c
- roots - or real roots, zero or more point(s) where a polynomial intersects the x axis
- standard form - see model.md
- vertex - the highest or lowest point of a parabola, also it's turning point
- vertex form - see model.md
PhET-specific terminology:
- alternative vertex form - see model.md
- erase button - button with an eraser icon, used to erase the saved curve
- graph contents - everything that is displayed on the graph, excluding the grid and axes
- 'hide graph contents' button - button with an eyeball icon that shows/hides the graph contents
- interactive quadratic - the quadratic that the user can interact with, via sliders, pickers, and/or manipulators
- manipulator - shaded sphere that appears on the graph, used to change some aspect of the interactive quadratic
- saved curve - the saved state of the interactive quadratic, appears on the graph as a gray line
- save button - button with a camera icon, used to create the saved curve
This section describes how this simulation uses patterns that are common to PhET simulations.
Model-view transform: This simulation has a model-view transform that maps from the graph (model) coordinate frame to the view coordinate frame. The origin (0,0) in the model coordinate frame is (not surprisingly) at the origin of the graph.
Query parameters: Query parameters are used to enable sim-specific features, mainly for debugging and testing. Sim-specific query parameters are documented in GQQueryParameters.
Assertions: The implementation makes liberal use of assert to verify pre/post assumptions and perform argument
validation. If you are making modifications to this sim, do so with assertions enabled via the ea query parameter.
Memory management: Unless otherwise documented in the source code, assume
that unlink, removeListener, dispose, etc. are generally not needed. Most object instances exist for the lifetime
of the sim. The exception is QuadraticNode for the saved curve.
This sim reuses a very small number of model and view components from Graphing Lines. Search for "GRAPHING_LINES/" to identify what is reused.
This section provides an overview of the most important model components.
Note that this simulation supports only parabolas that open up or down, i.e. have the form y = ax2 + bx + c. It does not support parabolas that open left or right, i.e. that have the form x = ay2 + by + c.
Quadratic is the primary model
component. It is essentially an immutable data structure that describes a quadratic equation. It supports instantiation
using standard form (via the constructor), vertex form (via createFromVertexForm) and alternate vertex form (
via createFromAlternateVertexForm).
GQModel is the base class for
all model "containers". It includes the model components that are common to all screens. Each screen has a subclass
of GQModel that adds things that are specific to that screen. For
example, ExploreModel is
the model container for the Explore screen.
This section provides an overview of the most important view components.
QuadraticNode is the
primary view component, responsible for rendering the curve that corresponds to a Quadratic instance, and labeling the
curve with an equation. While QuadraticNode is responsible for the placement of the equation relative to the
curve, GQEquationFactory
is responsible for creation of equations.
GQScreenView is the base
class for all ScreenViews in this sim. It includes the view components that are common to all screens, and it handles
common layout responsibilities. Each screen has a subclass of GQScreenView that adds things that are specific to that
screen. For
example, ExploreScreenView
is the view for the Explore screen.
GQGraphNode is the base class
for all graphs in this sim. Each screen has a subclass of GQGraphNode that adds things that are specific to that
screen. For
example, ExploreGraphNode
is the graph for the Explore screen.
GQEquationAccordionBox is the base class for the accordion box that displays the interactive quadratic. Each screen has a subclass of EquationAccordionBox that adds things that are specific to that screen. (Do you see a pattern here? 😉) For example, ExploreEquationAccordionBox is the equation accordion box for the Explore screen.
Each screen has a class whose name ends with "InteractiveEquationNode", for example, ExploreInteractiveEquationNode. This is the UI for modifying the interactive quadratic indirectly, using sliders or pickers. Explore and Focus & Directrix screens use sliders, Standard Form and Vertex Form screens use pickers.
Manipulators are the shaded spheres that appear on the graph. They allow the user to modify the interactive quadratic
directly, by interacting with its curve.
The Manipulator base
class is reused from the Graphing Lines sim, and is extended in
the GQManipulator base
class, which adds optional (x,y) coordinates. The 3 subclasses of GQManipulator
are VertexManipulator, FocusManipulator
and PointOnParabolaManipulator,
for changing the vertex, focus, and point on the parabola, respectively.
Each checkbox in this sim is a subclass
of GQCheckBox, a subtype
of SUN/Checkbox that supports labeling with an optional icon, and provides standardization of various properties (
font, fill,...) You can locate a Checkbox subclass based on the English text used on checkbox. For
example, FocusCheckbox
is the checkbox labeled with "Focus" and a focus manipulator icon.