Cooked structure-of-arrays (SoA) tier (RCSO / frames_soa)#
Contract#
RCSO is non-authoritative. CON text in frames is the sole authority for hash, dedup, join/split, reindex, and CON export. Cooked numerics in frames_soa are derived POD only; they never replace the text tier.
Summary#
readcon-db stores two tiers per frame key:
Tier |
LMDB DB |
Role |
|---|---|---|
Authority |
|
UTF-8 CON text (span at ingest when possible) |
Optional numerics |
|
RCSO v1 little-endian POD (positions \(N\times 3\) |
Default ingest does not cook. Call cook_frame / recook_all / CLI cook-frame / recook-all (or append_trajectory_path_cook(..., true) in Rust) to populate RCSO. delete_cooked_soa drops only the cooked tier; CON text and indexes stay.
Why the .con text is still required#
RCSO is not fully equivalent to CON: it omits element symbols, masses, cell/angles, constraints, JSON metadata, and exact on-disk bytes. Those are required for xxHash3 dedup, symbol/formula indexes, reindex, join/split, and CON export. Do not omit frames when cooked exists.
Numeric hot path#
get_positions / get_forces / get_velocities (Rust, Python, C rkrdb_get_positions / rkrdb_get_forces / rkrdb_get_velocities, CLI positions) prefer a valid RCSO blob and skip CON parse on a hit. Missing or corrupt cooked falls back to parsing CON text. Authority APIs (frame_hash, find_by_hash, get_frame_text, reindex, shard join) never read frames_soa.
Language surfaces#
Surface |
Cook / delete / has-valid |
Positions / forces / velocities |
|---|---|---|
Rust |
full |
full |
Python |
|
|
C / C++ |
|
|
Fortran |
|
|
CLI |
|
|
See also#
Internal design notes: readcon-db design notes (engineer-facing; mirrors this contract)
Architecture summary: Architecture