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; then stopping the model and seeking to the beginning by typing model.seek(0) in the console. The atoms' positions change back 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.

(1) In the beginning of the md2d modeler, clearly list an introspectable schema about all the properties it handles

configuration view config: chargeShading engine config: temperature_control

the kinds of objects we model atoms obstacles radial bonds text boxes! (i.e,, something that doesn't get pushed to the engine at all and maybe gets passed to the view as a "package" that is not inspected by the model at all)

for each object, information about each of the per-object properties (where object = atom, radial bond, obstacle...) is it saveable/not saveable is it engine/non-engine (non-engine properties don't need to be put into transposed form) what is the default value

model state time temperature potential energy

(2) Use the introspected information to unify serialization, history, and get/setAtomProperty methods

To be clearer about what the problem is.

• setAtomProperties uses different property names than the "atoms" serialization. Conceptually, deserialization of atoms should just be a simple loop that repeatedly calls setAtomProperties (conversely, serialization should just unroll the results of looped getAtomProperties calls)
• there are no setObstacleProperties, setRadialBondProperties. These should exist.
• history only stores per-atom properties, not per-obstacle properties (for example) and also not whole-model properties like "temperature_control"

(3) create a simple engine wrapper

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.