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. The 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:

1. 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

2. 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. Moreover this is pointlessly repetitive.

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

4. 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

5. The "tick history" saves and restores per-atom properties but it does not similarly save and restore most other types of properties, for example, 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.)

6. Adding a new property to the model requires providing meta-information about the property in many different places -- see fac22a5583c3883ef3e95605a0579bd8f01f63a8

7. There is meta-information about atom properties specifying, for example, which properties are "saveable" -- ie., which properties, such as atom positions, need to be serialized in order to accurately save the state of the model; and which properties, such as instantaneous accelerations, can be recomputed by the engine on the fly. However, there is nowhere to store similar meta-information about other objects such as radial bonds.

8. Sometimes when a property changes, we need to recalculate the model "macrostate" such as the potential energy, temperature, etc. However, although there is a unified way to notify view objects that a toplevel property such as

(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.