Interoperability with PhET Simulations

PhET Interactive Simulations are engaging, playful educational tools that make it easy for students to learn science and math content. PhET-iO augments PhET Simulations with interoperability features making them a much more flexible, powerful tool. Simulations can be customized for classrooms or individual learners, provide adaptive feedback, and provide data on student usage and progress.

---

Features

---

Documentation

Object Identifiers and Types

Each object in a simulation is associated with an identifier and a type. The identifier (a) appears in messages produced by the object in the data log (b) is used to configure the object and (c) is used to interact with the object dynamically. The type describes the nature of the object as well as methods for interacting with the object. For instance, a user interface component commonly found in PhET Simulations is a "reset all" button, which restores the simulation to its initial state. The identifier and type for a reset all button in a simulation may be given like this:

// The Reset All button, which appears in the bottom right of the screen
resetAllButton: TResetAllButton

The identifier can be used to refer globally to the instance after it has been created, and the type shows what kinds of events and methods are provided by the object. In this case, the TResetAllButton provides an event to the data stream when the button is pressed.

// Names of events emitted by the button
events: [ 'fired' ]

Here is a larger example of the identifiers and names for PhET's Faraday's Law Simulation:

{

  // The root for cross-cutting interoperable features
  phetio: TPhETIO,

  // Simulation-specific content
  faradaysLaw: {

    // The sim itself
    sim: PhETIOCommon.getSimAPI(),

    // The navigation bar, including the PhET Menu and menu items.
    navigationBar: PhETIOCommon.getNavigationBarAPI(),

    // Content in the screen
    faradaysLawScreen: {

      // Physical values in the model and settings
      model: {
        showSecondCoilProperty: TProperty( TBoolean ),
        showMagnetArrowsProperty: TProperty( TBoolean ),
        magnetModel: {
          positionProperty: TProperty( TVector2 ),
          flippedProperty: TProperty( TBoolean ),
          showFieldLinesProperty: TProperty( TBoolean )
        },
        voltmeterModel: {
          thetaProperty: TProperty( TNumber ) // the angle of the needle, in radians
        }
      },

      // Visible objects
      view: {
        controlPanel: {
          resetAllButton: TResetAllButton,
          flipMagnetButton: TButton,
          showFieldCheckBox: TCheckBox,
          singleCoilRadioButton: TRadioButton( TBoolean ),
          doubleCoilRadioButton: TRadioButton( TBoolean )
        },
        magnet: TNode.extend( {
          dragHandler: TTandemDragHandler
        } )
      }
    }
  }
}

The full identifier for an object is given by the full path to reach the object. For example, the magnet's position is 'faradaysLaw.faradaysLawScreen.magnet.position'. Noted that all identifiers are prefixed by the name of the simulation and the name of the screen within the simulation to facilitate cross-simulation studies.

---

Query Parameters

Several query parameters govern the behavior of an instrumented PhET simulation:

• phet-io.emitStates: Outputs the full state at the end of every frame.
• phet-io.emitDeltas: Outputs state keyframes every 10 seconds and deltas every frame
• phet-io.emitEmptyDeltas: When emitting states using phetio.js, emit deltas that are empty, to simplify playback in some systems.
• phet-io.log: If set to console, will stream phetioEvents to console. This is useful for understanding or debugging the phetioEvent log output in real-time. If using Chrome or Firefox, using phet-io.log=lines provides a colorized single-line output.
• phet-io.docs: Will output type documentation to the console, see https://github.com/phetsims/phet-io/issues/218
• phet-io.expressions: Evaluate expressions on phetio wrapper objects, like: http://localhost/faradays-law/faradays-law_en.html?ea&brand=phet-io&phet-io.log=console&phet-io.expressions=[["beaker.beakerScreen.soluteSelector","setVisible",[true]]] Described in more detail below.

---

Query Parameter API for instrumented instances

Instrumented objects in a simulation can be customized through a query parameter named phet-io.expressions. Here is an example of that query parameter:

?phet-io.expressions=phet-io.expressions=[["beaker.beakerScreen.soluteSelector","setVisible",[true]]]

The list of available methods and types are provided below in the types section. A complete an example of this is provided in customization.html. Please be aware that different browsers have different limits on the length of query strings. If a query string becomes too long, it will simply be truncated, leading to errors during parsing. Internet Explorer has the lowest maximum query string length at approximately 2000 characters. This limit can be reached easily if setting many state variables through the query string. An alternative to configuration with query strings is to configure the simulation after it launches using the iframe API.

---

Data Stream

Here is (the beginning of) a sample data log from the Color Vision simulation:

{
  "messageIndex": 0,
  "eventType": "model",
  "phetioID": "sim",
  "componentType": "TSim",
  "event": "simStarted",
  "time": 1447285103220,
  "parameters": {
    "sessionID": null,
    "simName": "‪Color Vision‬",
    "simVersion": "1.1.0-phet-io.3",
    "url": "http://www.colorado.edu/physics/phet/dev/html/phet-io/newschools/color-vision_en.html",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36",
    "provider": "PhET Interactive Simulations, University of Colorado Boulder"
  }
}
{
  "messageIndex": 1,
  "eventType": "user",
  "phetioID": "homeScreen.singleBulbScreenLargeButton",
  "componentType": "TButton",
  "event": "fired",
  "time": 1447285111392,
  "children": [
    {
      "messageIndex": 2,
      "eventType": "model",
      "phetioID": "sim.showHomeScreen",
      "componentType": "TProperty",
      "event": "changed",
      "time": 1447285111393,
      "parameters": {
        "oldValue": true,
        "newValue": false
      }
    }
  ]
}
{
  "messageIndex": 3,
  "eventType": "user",
  "phetioID": "colorVision.singleBulbScreen.photonRadioButton",
  "componentType": "TRadioButton",
  "event": "fired",
  "time": 1447285114104,
  "parameters": {
    "value": "photon"
  },
  "children": [
    {
      "messageIndex": 4,
      "eventType": "model",
      "phetioID": "colorVision.singleBulbScreen.beamType",
      "componentType": "TProperty",
      "event": "changed",
      "time": 1447285114104,
      "parameters": {
        "oldValue": "beam",
        "newValue": "photon"
      }
    }
  ]
}

Here is a brief description of each of the fields in a message:

Attribute	Description
messageIndex	The number of the message, starting with 0. Can be used to verify that the correct number of messages was received.
eventType	{user|model} whether the message was originated by a user action or by the simulation itself. For instance, a button press is a user event while a state change in the simulation is a model event (even if it was triggered by a user event)
phetioID	The unique identifier for the object sending the message. It usually starts with ${simulation-name}.${screen-name} except for globals outside of screens, or objects in the navigation bar.
componentType	The name of the component type of the object that sent the message. Component type names begin with a capital letter T because they refer to Type wrappers.
event	The name of the event that was fired by the object.
time	The number of milliseconds since the epoch (in 1960) as reported by the client machine. No effort is made to verify that this matches any other clock.
parameters	(optional) Key value pairs that describe the details of the event.
children	(optional) Events that were triggered while this event was being processed.

  var sim = SimWrapperUtils.getSim( 'concentration' );

  // Get a reference to the iframe for the sim
  var simFrame = document.getElementById( 'sim' );

  // This sim does not need any listeners to be added before the sim launches, so it can be phet-io.standalone
  simFrame.src = sim.URL + '&ea&phet-io.standalone';

  // Construct the sim iframe client that can be used to send messages to the sim.
  var simIFrameClient = new SimIFrameClient( simFrame );

  // Keep track of whether the sim is active or not
  var lastActiveValue = true;

  // When the user presses the "Toggle Active" button, send a command to the iframe
  document.getElementById( 'toggleActiveButton' ).addEventListener( 'click', function() {

    // Send a message using the simIFrameClient to invoke a method on an instance
    simIFrameClient.invoke( sim.camelCaseName + '.sim.active', 'setValue', [ !lastActiveValue ] );
  } );

  // When the sim launches, wire up a listener to the active Property, so we can report its value and
  // use the correct value when toggling
  simIFrameClient.onSimInitialized( function() {

    // Send a message using the simIFrameClient to link up to the active Property
    simIFrameClient.invoke( sim.camelCaseName + '.sim.active', 'link', [ function( active ) {
          lastActiveValue = active;
          document.getElementById( 'readout' ).innerHTML = 'Active: ' + active;
        } ]
    );
  } );

// Wait for the phase where we can add listeners
simIFrameClient.onPhETiOInitialized( function() {

  // Add any desired listeners to phet-io (cannot communicate with sim instances at this
  // point since they have not been created yet
  simIFrameClient.invoke( 'phetio', 'addPhETIOEventsListener', [ function( message ) {
        textarea.innerHTML += '\n' + message;
        textarea.scrollTop = textarea.scrollHeight;
      } ], function() {

        // after that is complete, launch the simulation
        simIFrameClient.invoke( 'phetio', 'launchSimulation', [] );
      }
  );
} );