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

frames

UTF-8 CON text (span at ingest when possible)

Optional numerics

frames_soa

RCSO v1 little-endian POD (positions \(N\times 3\) f64, optional forces/velocities)

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 ConCorpus

full

full

Python ConCorpus

cook_frame, delete_cooked_soa, has_valid_cooked_soa, recook_all

get_positions, get_forces, get_velocities

C / C++

rkrdb_cook_frame, rkrdb_delete_cooked, rkrdb_has_valid_cooked, rkrdb_recook_all

rkrdb_get_positions, rkrdb_get_forces, rkrdb_get_velocities

Fortran

db_cook_frame, db_delete_cooked, db_has_valid_cooked, db_recook_all

db_get_positions, db_get_forces, db_get_velocities

CLI

cook-frame, delete-cooked, recook-all

positions

See also#