MD2D Model Schema

Problems arising from lack of a unified model schema

(TL;DR: When you look closely, there are a lot of inconsistencies in the dark recesses of the MD2D data model that are just waiting to bite us in the behind. The unified model schema outlined in the next section could help.)

Here are some related issues with the MD2D model object implemented in modeler.js and md2d.js:

• There are set and get methods for top-level properties of the model such as temperature_control, but for atom properties there is no getAtomProperties method to match setAtomProperties.

• The serialization of atom properties use upper case keys such as X and Y, but setAtomProperties uses different, lower-case keys such as x and y for the same properties. The same keys should be used in both cases, for ease of use and so that the more code can be shared.

• Atoms are just one kind of "physics object" that we need to serialize or edit the properties of -- some others are obstacles, elements, and radial bonds -- but there are no setter/getter methods such as setObstacleProperties for these other kinds of object.

• The serialization and deserialization path for the properties of atoms, obstacles, elements, and radial bonds are convoluted and pointlessly different for each type of object -- compare obstacle deserialization and atom deserialization

• The "tick history" saves and restores per-atom properties but it does not save and restore other types of properties such as per-obstacle properties or toplevel properties like temperature_control. This can be seen by visiting http://lab.dev.concord.org/examples/interactives/interactives.html#interactives/gas-laws-page-4.json, allowing the model to run so that the obstacle moves to the right, stopping the model, seeking to the beginning by typing model.seek(0) in the console, and then clicking the play button. The atoms' positions change back to their starting points but the obstacle's position does not. (Note that using the reset button is not sufficient to demonstrate the problem because it reloads all model properties from the serialized JSON.)

• There is meta-information about atom properties specifying, for example, which properties are "saveable" -- i.e., which properties are transient and which properties need to be serialized in order to accurately save the state of the model. However, there is nowhere to store similar meta-information about other objects such as radial bonds.

• Adding a new atom property to the model requires providing meta-information about the property in many different places -- see fac22a5

• Although there is a unified way to notify an observer that a toplevel property such as temperature_control has changed, there is no way to notify an observer that the potential energy has changed. We rely instead on observing tick events, but this is not reliable because the potential energy (or something else, such as the x-position of obstacle #2) can change as a result of user action while the model is stopped.

Proposed design

Summary

At the top of modeler.js, define a schema object that contains the names of top-level properties of the model (such as height), a set of metadata about each property, and the names of each type of object contained in the model (such as obstacles and atoms). Recursively use the same, or a very similar, format for describing each property of each object type (such as the charge property of atoms).

Refer to the metadata defined in this schema throughout modeler.js when, for example, allocating storage arrays, storing tick-history items, serializing, deserializing, issuing "change" events to listeners, or pushing data back and forth from the underlying computational engine.

Sketch of information needed

Toplevel (width, chargeShading, viscosity)

• Should this property be passed to the engine when it is constructed or configured?
• Should changing this property trigger a model-state recalculation (changing the gravitationalField potential instantaneously changes the total energy)
• Is this property view related? (This is a hint for developers and for use by a controller that configures a view; the model doesn't construct a view or maintain a reference to it.)
• Should this property be persisted in the tick history?

Of course, we should be able to define a custom setter for each property in order to do the right thing when it changes.

Atoms (x, charge, marked)

• Should this property be serialized?
• Should this property be passed the engine? (Note: the engine should continue to use an array of properties indexed by atom, because access to x[j] is faster than access to atoms[j][X] when you consider that the atoms[j] dereference can't meaningfully be cached in inner loops. However, modeler should operate on transposed array of atoms indexed by property -- what we at first called the results array. This means we should optimize what we pass back and forth between model and engine.)
• Should this property be persisted in the tick history? (For example, we might want to mark atoms in such a way that marks added at a later time persist when scrubbing the history backwards. That should be a policy choice we can flip by changing a value in the schema; and we might even allow specific models to override that policy choice by overriding the default schema.)

Obstacles

Radial Bonds

Allow the engine to be. We don't need to make the engine object serialize and deserialize itself. In fact, it works on "transposed" arrays of properties.

However, we want node.js programs to be able to load a model and run it. But these programs don't need to store history, don't need methods for handling interactive events, etc.

If we've done our refactoring work well, this would be a simple case of inheritance. The high level model would provide additional methods atop the lower level base class; and it would register a few additional property names (see (1) above) that the lower level model doesn't know about

(3) Unify the way notifications get handled

• Can't rely on only the tick event to update graphs; interactive changes may cause graphs to need to be updated without a tick event or change in the model time.

• Also want to be able to track the need to repaint vs. merely update positions. When an model property or an object property is changed, we need to repaint; but when the engine integrates, we have special knowledge that only positions changed, so we can use a faster update method.

(What about when a vdw pair is created or destroyed. You would like the "view interface object" to tell the view attached to it that it does or doesn't need to redraw the vdw pair.)

(4) Clarify and unify the set of events, properties, and methods that the model supports.

Consider the view, the scripting api, and the developers' needs.