Trajectory outputs and logs are stored in a directory.
The output directory contains a traj sub directory with a header.json file, many snap$(NUMBER).zarr.zip files where NUMBER is the frame number of the snapshot, and finally a footer.json.
The initial state returned by setup is stored in snap0.zarr.zip.
Inside the snap$(NUMBER).zarr.zip there is a snap/medyan group containing the snapshot of the MEDYAN.Context at the step. Other state may be stored in child groups of snap.
The header.json file also has a top level "medyan" key with a value describing the system being simulated.
Other header information may be under other top level keys.
A snapshot describes the state of a Context at a single point in time.
A snapshot can be used to set the state of a Context if it was constructed with the same system and parameters as the Context used to create the snapshot. Trying to load a snapshot into a Context constructed with a different system or parameters may lead to unexpected results.
By default units are in nm, pN, and s. Coordinates are relative to the center of the grid.
The snapshot doesn’t hold the exact full state of a Context, simulations restarted from a snapshot may not have the exact same results because:
The snapshot doesn’t store the state of the random number generator.
Coordinates may be rounded to save disk space.
Dictionaries and other internal data structures may get reordered and or resorted when the snapshot is loaded.
Multithreading may be non deterministic.
But if rounding isn’t too extreme, the reloaded Context should have the same statistics.
Snapshot Versioning
The snapshot format is versioned by the “version” attribute. The current snapshot version is:
usingMEDYANMEDYAN.SNAPSHOT_VERSION
v"0.8.0"
Currently before snapshot version 1.0.0 anything goes.
After snapshot version 1.0.0 is released.
Snapshots written with a previous snapshot version above v"1" should be readable. Snapshots written with a newer snapshot version are generally not readable.
If new agent types are added to MEDYAN.jl, usually only the minor version needs to be updated, as nothing special needs to be done to read older snapshot versions without that added agent type.
If new data is added to an existing agent type, also usually only the minor version needs to be increment, though the case of the new data not existing must be handled with some default.
If the way an existing agent type is stored significantly changes, such that external code analyzing the snapshot would need to be modified, the major version must be incremented. Also if possible there should be a function to update a snapshot from the old version to the new version.
“#experimental” and “#comment” prefixes
Any group, dataset, or attribute name prefixed with with “#” can change format or be removed without changing the snapshot version.
“#experimental” is used for saving new types of agents or other data that doesn’t have a stable format yet.
“#comment” is used for saving human readable comments that could change in format or wording.
Example snapshot
usingMEDYANusingSmallZarrGroupscinit, s = MEDYAN.example_all_sites_context()group = MEDYAN.snapshot(cinit)
The state of a link_2mon, organized in a nested struct of vector like form. Any static arrays will be unwrapped into a tuple of vectors, in column major order. The “name” attribute of each subgroup and dataset is the corresponding property name in the StructArray Any property in the default state that isn’t in the snapshot will stay at its default value.
group["link_2mons/1/state"]
📂
├─ 📂 1 🏷️ name => "chemstate",
| ├─ 🔢 1: 2 Int64 🏷️ name => "a",
| └─ 🔢 2: 2 Float64 🏷️ name => "b",
├─ 📂 2 🏷️ name => "mechstate",
| └─ 📂 1 🏷️ name => "â",
| ├─ 🔢 1: 2 Float32 🏷️ name => "1",
| ├─ 🔢 2: 2 Float32 🏷️ name => "2",
| └─ 🔢 3: 2 Float32 🏷️ name => "3",
└─ 🔢 3: 2 Bool 🏷️ name => "is_minimized",
mechboundary
There is a dataset for each type of boundary, the total boundary is an intersection of the following.
Each column is the 3 vertex indexes of a triangle. Indexes are one based, and follow the right hand rule. Looking at the triangle from the outside in, they have counterclockwise winding.
🔢 vertlist