.. _cooked-soa: 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 :math:`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 -------- - Internal design notes: :doc:`/explanation/design` (engineer-facing; mirrors this contract) - Architecture summary: :doc:`/explanation/architecture`