Data Model Purpose and Description

A Blender ".blend" file contains an internal database of the Properties used by "addon" applications (like CellBlender). When an addon changes the Properties that it uses, this can render previous .blend files incompatible.

Since CellBlender makes extensive use of Blender's Property Database, we must have a mechanism to "upgrade" older .blend files whenever newer versions of CellBlender break backward compatibility via changes in our Blender Property definitions.

We have decided to handle this with a two-tiered mechanism which includes a relatively stable "Data Model" along with a mechanism to upgrade that Data Model when it needs to be changed. This page is intended as a guide on how to do that.

The "Data Model" is a python dictionary containing all of the "important" data needed for an MCell/CellBlender model/simulation. This dictionary can be easily imported, exported, and converted into (and out of) CellBlender's Property Database representation. This Data Model provides one level of "isolation" from any superficial changes made to the CellBlender Property Database, and it is stored inside the ".blend" file as a pickled string via the "save_pre" handler whenever a .blend file is saved.

Whenever a version of the CellBlender addon detects that it is opening a .blend file from a different version of the addon, the CellBlender properties will be completely reconstructed from the data model found in the .blend file. This is done in the "load_post" handler of the addon.

This works fine, but it still does not address the problem of changes to the Data Model itself. In other words, what will happen when a newer version of CellBlender opens an older .blend file with an older Data Model? This case is handled by making a series of modifications to the Data Model dictionary read from the .blend file until it matches the current Data Model version of the addon. The series of Data Model changes are applied like a series of patches to move the Data Model from whatever version it started with up to the current version. The series of "patches" could be a single linear series of small changes, but they could also include large "jumps" to move from one older version to a much newer version in one step. This might be done to improve upgrading speed if it is found that the series of small steps is taking too long to get from some versions to others.