CON implementation notes¶
- Date:
2026-10-11
Requirement words¶
The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY on this page follow RFC 2119.
Status¶
These notes are informative for the CON format. The normative text is The CON File Format Specification. Nothing here changes a byte a conforming reader MUST accept.
Absent values in the C ABI¶
Several rkr_* getters return an IEEE NaN when a number is absent.
rkr_frame_energy does this when the frame has no energy key.
That NaN is an API sentinel.
It is not a CON number, and it is not written to a file.
The format clauses are CON-num.1 and CON-num.4.
Clearing a section¶
One rule: clearing a section removes that section from the next build.
The on-disk result is the format rule.
A section is present exactly when its name is in sections.
clear_velocities_section, clear_forces_section, and
clear_energies_section drop the stored block so the next build omits it.
The section name for per-atom energies is energies.
In-memory arrays¶
The reference builder stores one column per field.
Positions are shape (N, 3).
Velocities, forces, magmoms, displacements, and spreads use the same shape when the section is present.
energies, charges, and spins are length N.
Atom ids are integers, one per atom.
DLPack exports report their own shape, strides, dtype, and device.
The data pointer stays valid until a growth of the buffer reallocates it.
Callers that keep a raw pointer across an added atom MUST take a new view.
On-disk coordinates and section values stay decimal text.
storage_dtypes describes the in-memory element type only.
It is not a change to the file encoding.
Velocity time-unit override¶
readcon bindings, readcon-db, and eOn keep an explicit
velocity_time_unit override for a file that breaks the version rule
in the specification (CON-units.11).
The override does not change what a writer is allowed to emit.