% Created 2026-08-20 Thu 14:37
% Intended LaTeX compiler: pdflatex
\pdfminorversion=7
\documentclass[preprint,12pt]{elsarticle}
\usepackage{graphicx}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\journal{Computer Physics Communications}
\usepackage{amssymb,amsmath}
\usepackage{booktabs}
\usepackage{url}
\usepackage{hyperref}
\usepackage[ruled,linesnumbered]{algorithm2e}
\usepackage{listings}
\input{figures/generated/macros}
\input{figures/generated/neb_macros}
\input{figures/generated/dlpack_macros}
\newcommand{\DOIPENDING}{pending Zenodo deposit of this manuscript, versioned to the release tag, after acceptance}
\date{\today}
\title{readcon-core reads and writes the CON checkpoint format}
\hypersetup{
 pdfauthor={},
 pdftitle={readcon-core reads and writes the CON checkpoint format},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 30.2 (Org mode 9.7.11)},
 pdflang={English}}
\begin{document}

\label{sec:abstract}
\begin{frontmatter}

\title{readcon-core reads and writes the CON checkpoint format}

\input{authors.tex}

\begin{abstract}
CON is a file format used by rare-event and saddle-search codes to store atomic checkpoints.
We formalize that format in readcon-core, the reference reader and writer.
The parsed positions, velocities, forces, per-atom energies, masses and atom ids are exposed through DLPack.
At 32768 atoms the NumPy \texttt{from\_dlpack} median is $\dlpackExMed$\,s and the copy median is $\dlpackCpMed$\,s, from $\dlpackRepeats$ repeats on one host.
Text CON remains the file other codes read.
\end{abstract}

\begin{keyword}
CON \sep checkpoint format \sep DLPack \sep rare-event dynamics \sep file format
\end{keyword}

\end{frontmatter}
\label{sec:program-summary}
\section*{Program Summary}

\noindent
\textit{Program Title:} readcon-core (companion: readcon-db)\\
\textit{CPC Library link to program files:} (assigned on acceptance)\\
\textit{Developer's repository link:}
\url{https://github.com/lode-org/readcon-core};
companion store \url{https://github.com/lode-org/readcon-db}\\
\textit{Licensing provisions:} MIT license (MIT)\\
\textit{Programming language:} Rust (core and C ABI); C99 and C++17
headers; Python 3.10+; Julia; Fortran 2008 (\texttt{ISO\_C\_BINDING})\\
\textit{Supplementary material:} specification
\texttt{docs/orgmode/spec.org}; Phase~A corpus
\texttt{resources/conformance/}; printers
\texttt{scripts/print\_neb\_band.py},
\texttt{examples/print\_neb\_band.cpp},
\texttt{examples/print\_neb\_band.f90}.\\
\textit{Computer / Operating system:} any machine with a Rust 1.88+
toolchain, or a prebuilt C library tarball; Linux, macOS, and Windows\\
\textit{RAM:} of order the parsed frame.\\
\textit{External routines:} optional chemfiles, metatensor, DLPack,
zstd, CUDA (feature-gated); readcon-db uses LMDB. Cap'n Proto stays
in the Rust RPC feature.\\
\textit{Nature of problem:} Rare-event and nudged-elastic-band
campaigns need a checkpoint that carries cell, per-type masses,
per-axis constraints, original atom indices, optional
velocities/forces, and machine-readable metadata. Historical CON
readers disagree on column~4, ignore line~2, and have no units
contract. Campaign screening then needs an index over those files
without a second structure dialect.\\
\textit{Solution method:} A documented grammar (spec v2/v3, with an
optional Pest companion) plus a hand-written reference parser and
writer. A single C ABI exposes the parsed frame to non-Python drivers.
Foreign structures enter through chemfiles and leave as CON.
\texttt{readcon-db} is the companion campaign store: LMDB indexes
(energy, formula, section presence) and a derived RCSO cache over the
same text files.\\
\textit{Additional comments including restrictions and unusual features:} Column~4 is a three-bit
mask whose decode depends on \texttt{con\_spec\_version}. Lean
builds keep chemfiles, metatensor, and CUDA symbols and return
\texttt{RKR\_STATUS\_FEATURE\_DISABLED} rather than hiding them. The
builder returns \texttt{NULL} on type-mass mismatch. Text CON is the
interchange; gzip/zstd are envelopes of that text. A default
\texttt{cargo build} is sequential. Python wheels and the published
C prefix enable \texttt{parallel}. Then
\texttt{rkr\_read\_all\_frames} / \texttt{readcon.read\_con} use
Rayon above $48$\,KiB; \texttt{rkr\_read\_all\_frames\_n\_threads}
and \texttt{n\_threads} select the worker count. Version 0.14.9.
The C ABI is frozen within 0.14.x. A 1.0.0 tag is the production
classifier. Cite the software through \texttt{CITATION.cff}
\cite{smithSoftwareCitationPrinciples2016}. The freeze tag is the
\texttt{v0.14.9} GitHub Release. The software archive series is
\texttt{10.5281/zenodo.18753567}
\cite{goswamiReadconcore01472026}. This manuscript does not invent a
paper DOI. Deposit the core and readcon-db freeze tags together; do
not write a second paper for readcon-db alone.\\
\textit{Running time:} the DLPack exchange of a 32768-atom position array has median $\dlpackExMed$\,s and the copy has median $\dlpackCpMed$\,s, from $\dlpackRepeats$ repeats.\\
\section{Introduction}
\label{sec:introduction} Saddle searches, adaptive kinetic Monte Carlo, and nudged elastic band calculations checkpoint atomic configurations many times per image.
CON is a file format used in many places for that checkpoint.
readcon-core formalizes the file and improves the reader and the writer.
The layout is a short header, then atoms grouped by chemical type, each line a position, a constraint flag, and a fifth integer that historical writers used as a display index \cite{chillEONSoftwareLong2014}.
Velocities were stored in a sibling \texttt{.convel} file.
Later files add force blocks and free-form comments in the metadata record of Listing~\ref{lst:header}.
readcon-core exchanges the parsed position array through DLPack, and at 32768 atoms the NumPy exchange median is $\dlpackExMed$\,s against a copy median of $\dlpackCpMed$\,s.

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/structures.pdf}
\caption{Benchmark geometries drawn with xyzrender.
Left, the four-atom CuH2 survey frame.
Centre, the 218-atom CuH2 timing frame.
Right, one image of the two-atom NEB band.
The axes use the Ruhi palette.}
\label{fig:structures}
\end{figure}

The format is small and human-readable.
Independent implementations have treated column 4 as ``fixed or not'' and have ignored line 2.
ASE's \texttt{ase.io.eon} reader is of that class \cite{larsenAtomicSimulationEnvironment2017}: it decodes column 4 with \texttt{bool(int(...))}, discards column 5, and treats leftover force-section lines after the coordinate parse as an error.
Archived eOn C++ does the same boolean decode while keeping the fifth integer on \texttt{.con} (not on \texttt{.convel}).
Neither stack has a units object.
Column 4 therefore cannot carry a per-axis mask unless the reader consults a spec version.

\texttt{readcon-core} is the reference reader and writer for that contract.
Versions 2 and 3 are defined in the accompanying specification (\texttt{docs/orgmode/spec.org}); this paper states the parts that matter for interchange.
The design goal is one on-disk checkpoint and one C ABI, so a Fortran optimizer, a C++ driver, and a Python notebook see the same constraints, identities, and metadata.
\section{Related work}
\label{sec:related} CON is the checkpoint rare-event codes write between saddle searches.
The nine-line type-grouped layout is the unversioned eOn de facto format.
Chill et al. describe the eOn software and do not specify atom-line columns \cite{chillEONSoftwareLong2014}.

Extended XYZ puts \texttt{Lattice=} and a \texttt{Properties=} column schema on the comment line; lean XYZ has neither.
No journal specifies extXYZ.
The living grammar is the ASE/libAtoms dialect \cite{larsenAtomicSimulationEnvironment2017}.
CON uses a JSON object in Listing~\ref{lst:header} for the same job (machine metadata on a record that old tools treat as a comment) and keeps a three-bit constraint mask and a pre-grouping \texttt{atom\_id}.
Lean XYZ, as timed in this paper, has no constraint mask.
The library's ASE adapters convert a parsed \texttt{ConFrame} to \texttt{Atoms} and back; they do not register a \texttt{format}'con'= plugin and do not replace \texttt{ase.io.eon}.
That reader treats leftover force-section lines after the coordinate parse as an error.

H5MD is the structured particle container in this journal \cite{deBuylH5MDStructuredEfficient2014}.
It can carry per-particle mass, force, velocity, SI unit attributes, and an observables tree.
It has no per-axis freeze mask and no type-grouped atom-index recovery.
The equal-geometry timings below treat H5MD as a peer load path, not as ``MD tape.''
GROMACS XTC/TRR and CHARMM/NAMD DCD are engine tapes: masses and restraints live in the TPR or PSF, and restart is a separate checkpoint (\texttt{cpt}, \texttt{namdbin}) \cite{abrahamGromacsHighPerformance2015}.
They are cited here and are not timed.

LAMMPS \texttt{dump custom} can store ids and optional forces on one row \cite{thompsonLammpsFlexibleSimulation2022}.
It does not store a spec-versioned constraint bitmask and does not require type-grouped blocks.
Atomsk converts among many crystal and MD formats and does not read or write eOn CON \cite{hirelAtomskToolManipulating2015}.
chemfiles is the optional ingress library \cite{frauxChemfiles2023}: it opens many formats; this paper measures XYZ\(\to\)\texttt{ConFrame}.
MDAnalysis is used only as the H5MD Python API in the wall-time table \cite{michaudAgrawalMDAnalysisToolkit2011,gowersMDAnalysisPythonPackage2016}; MDTraj is not timed \cite{mcgibbonMDTrajModernOpen2015}.
An optional metatensor export copies four \texttt{TensorBlock}s (positions, velocities, forces, per-atom energies) \cite{bigiMetatensorMetatomicFoundational2026}; it is not a TensorMap or metatomic \texttt{System} path.
\section{The CON format}
\label{sec:format} A spec 2 file places a JSON object in the metadata record of Listing~\ref{lst:header} with at least \texttt{con\_spec\_version}.
Spec 3 requires a \texttt{units} object with non-empty \texttt{length} and \texttt{energy} keys.
The \texttt{sections} array names the data blocks that follow the coordinates (velocities, forces, energies, charges, spins, magnetic moments).
The Rust writer fills \texttt{sections} from the frame.

Column 4 is a bitmask \(0\ldots 7\).
Historical writers emit \(0\) or \(1\) (free or all-fixed).
This specification assigns a three-bit mask for spec 2+: \(1\) is \(x\)-only and \(7\) is all-fixed.
Writers emit \(7\) for all-fixed, never \(1\).
The decoder is spec-aware so that a legacy file with \(1\) remains all-fixed.
Old readers that test ``nonzero means fixed'' over-constrain \(y\) and \(z\) on a legal spec 2 file whose mask is 1 to 6; they still freeze the atom.
Column 5 is \texttt{atom\_id}.
Readers accept four-column lines and default the missing index to the sequential position in the frame.

The metadata record in Listing~\ref{lst:header} was chosen because existing tools treat it as a comment.
Adding a tenth header record, overwriting the postbox records in Listing~\ref{lst:header}, or adding a sidecar file named \texttt{con.meta} breaks those parsers or loses pairing.

\begin{lstlisting}[caption={Records in the header of one frame.},label={lst:header}]
free_line
metadata_line
cell_lengths
cell_angles
postbox
postbox
\end{lstlisting}

Velocities live in a declared \texttt{sections} entry on a \texttt{.con} file.
The \texttt{.convel} extension is the historical name and the blank-separator fallback when the \texttt{sections} key is absent.
A present key, including an empty array, disables that fallback.

Gzip is the portable compression. zstd is an optional feature with the same magic-byte detection.
Both decompress to text and then parse.
They are not a new format.

A Cap'n Proto schema (\texttt{schema/ReadCon.capnp}) exists for an optional Rust RPC service.
It is a parsed-frame transport.
It is not an on-disk ``bcon'' authority.
The campaign store \texttt{readcon-db} keeps cooked SoA numerics in LMDB (RCSO) as a derived cache.
Text CON remains the file that independent tools must implement.

\subsection{Historical decode}
\label{sec:historical} The standard reader treats column 4 as a boolean.
A value of 0 leaves the atom free and any other value fixes x, y and z together.
That reader does not read a units object and it does not read a declared section.

\subsection{Spec-aware decode}
\label{sec:spec-aware} The reader in this paper takes four steps.
\begin{equation}
r \leftarrow \mathrm{next\ record}
\label{eq:propose}
\end{equation}
\begin{equation}
\mathrm{accept}(r) \iff v(r)\in\{2,3\} \land (v(r)\neq 3 \lor \mathrm{units}(r))
\label{eq:accept}
\end{equation}
\begin{equation}
F \leftarrow \mathrm{decode}(r)
\label{eq:update}
\end{equation}
\begin{equation}
\mathrm{stop} \iff \mathrm{no\ further\ record}
\label{eq:stop}
\end{equation}
Equation~\eqref{eq:propose} proposes the next header and its atom lines.
Equation~\eqref{eq:accept} accepts the record when the declared version is 2 or 3 and a version 3 record carries units.
Equation~\eqref{eq:update} writes the cell, the symbols and the constraint mask into the frame.
A legacy column-4 value of 1 is stored as the mask 7.
Equation~\eqref{eq:stop} stops at the end of the file.

\begin{algorithm}[tbp]
\caption{Read one CON file. Each line is the matching equation.}
\label{alg:read} propose the next record\; accept the record when the version test passes\; update the frame from the accepted record\; stop when the file has no further record\;
\end{algorithm}

Figure~\ref{fig:workflow} draws those four steps.

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/workflow.pdf}
\caption{The reader proposes a record, accepts it under the version test, updates the frame, and stops at the end of the file.}
\label{fig:workflow}
\end{figure}

\begin{table}[tbp]
\centering
\caption{Constants for the DLPack exchange.
The same values are used at every atom count.}
\label{tab:dlpack-params}
\begin{tabular}{llll}
\toprule
symbol & meaning & key & value \\
\midrule
$n$ & independent repeats & repeats & $\dlpackRepeats$ \\
$N$ & atom counts & sizes & 32, 128, 512, 2048, 8192, 32768 \\
$w$ & discarded warmups & warmup & 1 \\
dtype & stored positions & storage & IEEE binary64 \\
\bottomrule
\end{tabular}
\end{table}
\section{Library architecture}
\label{sec:architecture} The crate is an hourglass.
The Rust core owns \texttt{ConFrame}, the writer, and optional chemfiles import.
Figure~\ref{fig:architecture} draws that layering.

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/architecture.pdf}
\caption{The Rust core parses and writes CON.
The C interface is the waist, and the language wrappers sit above it.}
\label{fig:architecture}
\end{figure} An optional Pest grammar (\texttt{grammar/readcon.pest}) is a surface-syntax companion; the I/O hot path is the hand-written parser. The C ABI in \texttt{src/ffi.rs} is generated into \texttt{include/readcon-core.h} and that header is what CMake FetchContent, the Meson wrap-file, and \texttt{pkg-config} install.
Consumers do not run cbindgen.

Python (\texttt{readcon} / \texttt{readcon-chemfiles}), Julia, and Fortran bind the C ABI (Python also calls the Rust parser directly).
The \texttt{python} feature enables Rayon.
Then \texttt{read\_all\_frames} / \texttt{read\_con} parse in parallel when the buffer is at least \$48\$$\backslash$,KiB; \texttt{n\_threads=1} forces the sequential iterator.
A default \texttt{cargo build} is sequential.
The published C prefix is built with \texttt{parallel}, so \texttt{rkr\_read\_all\_frames} follows the same automatic policy.
\texttt{rkr\_read\_all\_frames\_n\_threads} selects the worker count (\(0\) auto, \(1\) sequential, \(n\geq 2\) a pool).
Lean builds return \texttt{RKR\_STATUS\_FEATURE\_DISABLED} for chemfiles, metatensor, and CUDA rather than hiding the symbol.
RPC is a Rust feature and is not on the C ABI.
Builder \texttt{rkr\_frame\_builder\_build} returns \texttt{NULL} on validation errors (including type-mass mismatch); it does not abort.

The 0.14.x contract freezes ownership, sentinels (\texttt{NaN}, \texttt{UINT64\_MAX}, \texttt{NULL}), and the Z \(=1\ldots 92\) (+ D/T) helpers.
Additive symbols appear in a 0.14.z patch when the C ABI grows.
A breaking C change is a 0.15+ minor.
\section{Performance}
\label{sec:performance} We time the base commit against ASE, chemfiles, h5py, MDAnalysis, OVITO and pymatgen on one host.
We use the same frames for every arm.
We interleave the arms inside each repeat.
Figure~\ref{fig:timing} shows those median wall times.
Figure~\ref{fig:ratios} shows the base time divided by each peer time.
A ratio below 1 means the base commit returned first.
We report the median and the type 7 quartiles.
The supplement prints the remaining figures from the same campaign files.

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/timing.pdf}
\caption{Median wall time of the base commit and of each peer that reads the frames.
The base bar is readcon at the base commit.}
\label{fig:timing}
\end{figure}

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/ratios.pdf}
\caption{Base time divided by peer time.
The marker is the median ratio and the bar runs from the type 7 lower quartile to the type 7 upper quartile.}
\label{fig:ratios}
\end{figure}

Figure~\ref{fig:restart} draws the uninterrupted band and the two resumed bands on the $(s, d)$ plane.
Figure~\ref{fig:restartfmt} is the energy surface of each resume route.

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/restart.pdf}
\caption{Uninterrupted and resumed bands on the $(s, d)$ plane, with the energy beside the map.}
\label{fig:restart}
\end{figure}

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/restart_formats.pdf}
\caption{Energy surface of the uninterrupted band, the POSCAR resume and the ASE resume.}
\label{fig:restartfmt}
\end{figure}
\section{Multi-language fidelity}
\label{sec:fidelity} A clause-keyed Phase A corpus under \texttt{resources/conformance/} locks the column-4 collision (spec 1 value \(1\) is all-fixed; spec 2 value \(1\) is \$x\$-only; spec 2 value \(7\) is all-fixed), required v3 units, missing \texttt{con\_spec\_version}, unsupported version \(4\), unknown section names, and \texttt{validate=true} without \texttt{sections}.
Each valid id has a JSON golden for spec version, column-4 mask, positions, atom ids, and symbols.
Rust, the C ABI, and Python share the same parser.
Fortran and Julia call the C ABI.
The optional Pest grammar is exercised separately (\texttt{cargo test -{}-{}features grammar}).
The published cxx tarball on the \texttt{v0.14.9} GitHub Release is the CMake FetchContent URL (SHA256 \texttt{4bf6b1809da292a7ea5cc59376e57220f31afa052c7365aecdc3b039c70b52f3}).
\section{Applications}
\label{sec:applications} eOn and the amsel campaign stack consume CON as the checkpoint between potential evaluations and saddle searches.
\texttt{readcon-db} indexes those files for energy, formula, and section presence.
\texttt{resources/examples/neb\_band.con} is a four-image spec-3 band (two atoms).
\texttt{resources/examples/cuh2\_band.con} is the same declared bead tags on the 218-atom \texttt{cuh2.con} geometry.
Each frame declares \texttt{neb\_bead}, \texttt{neb\_band}, \texttt{energy}, \texttt{fmax}.
\texttt{scripts/print\_neb\_band.py}, \texttt{examples/print\_neb\_band.cpp}, and \texttt{examples/print\_neb\_band.f90} print bead, energy, and \(f_{\max}\).
The energies are line-2 JSON.
They are not a production NEB.
The declared barrier \(E_1-E_0\) is $\nebBarrierEv$\,eV.
The declared \(f_{\max}\) is not recomputed from the force block.
The supplement lists the bead table.
Python \texttt{index\_projection()} returns the same campaign scalars (formula, energy, \texttt{neb\_bead}) that \texttt{readcon-db} indexes.
Python notebooks use \texttt{readcon} for lean I/O and \texttt{readcon-chemfiles} when the input arrives as XYZ.
This paper reports the XYZ mapping.
It does not report residue or occupancy for PDB and GRO.
The C++ RAII header is the path for in-process drivers that cannot embed a Python interpreter.
\section{DLPack exchange}
\label{sec:dlpack} The Rust frame stores positions, velocities, forces, per-atom energies, masses and atom ids in contiguous arrays.
\texttt{positions\_dlpack}, \texttt{velocities\_dlpack}, \texttt{forces\_dlpack}, \texttt{atom\_energies\_dlpack}, \texttt{masses\_dlpack} and \texttt{atom\_ids\_dlpack} borrow those arrays as DLPack views.
The C ABI exports the same fields as \texttt{rkr\_frame\_*\_dlpack} and \texttt{rkr\_frame\_builder\_*\_dlpack}.
The Python \texttt{xyz}, \texttt{vel} and \texttt{frc} getters allocate a fresh NumPy array from that storage, and that array implements \texttt{\_\_dlpack\_\_}.
We measure that exchange against a copy.
NumPy \texttt{from\_dlpack} and PyTorch \texttt{from\_dlpack} share that array's pointer.
JAX \texttt{from\_dlpack} does not share the pointer on this build.
CuPy did not import.
A copy allocates a second array with \texttt{numpy.array(copy=True)}.
Table~\ref{tab:dlpack-params} fixes the repeats, the sizes and the dtype.
The hardware line is x86\_64, 8, Intel Xeon Processor.
Figure~\ref{fig:dlpack} and Table~\ref{tab:dlpack} report the median and the type 7 quartiles.

\begin{figure}[tbp]
\centering
\includegraphics[width=\textwidth]{figures/generated/dlpack.pdf}
\caption{Median time to exchange a position array through DLPack, and the median time to copy it, against the atom count.
Each point is the median of $\dlpackRepeats$ repeats.}
\label{fig:dlpack}
\end{figure}

\begin{table}[tbp]
\centering
\caption{NumPy DLPack exchange and a copy of the same position array.
Quartiles are type 7.}
\label{tab:dlpack}
\input{figures/generated/dlpack_table}
\end{table}

The reproduction command is \texttt{python3 paper/cpc/scripts/bench\_dlpack.py} at commit \texttt{\dlpackCommit} of \url{https://github.com/lode-org/readcon-core}.
\section{Availability}
\label{sec:availability} One version number covers this release of the crate and the wheels (\texttt{readcon} and \texttt{readcon-chemfiles}).
Julia \texttt{Project.toml} and the Fortran fpm package live in this repository and bind a prebuilt or locally built \texttt{libreadcon\_core}; they are not registry packages.
CMake FetchContent and the in-tree Meson wrap-file point at the slim cxx tarball on the matching GitHub Release.
Cite the software through \texttt{CITATION.cff} \cite{smithSoftwareCitationPrinciples2016}.
The freeze tag is the \texttt{v0.14.9} GitHub Release.
The software archive series is \texttt{10.5281/zenodo.18753567} \cite{goswamiReadconcore01472026}.
This manuscript does not invent a paper DOI.
The software archive is \texttt{10.5281/zenodo.18753567}.
The manuscript deposit is \DOIPENDING.
The command that regenerates the DLPack table is \texttt{python3 paper/cpc/scripts/bench\_dlpack.py}.

\bibliographystyle{elsarticle-num} \bibliography{rg_main}
\end{document}
