# Table of Contents
1. [About](#org6c05cb6)
1. [Features](#orgdaee6f9)
2. [Install](#org6030511)
3. [Tutorial](#org396efa6)
4. [Design Decisions](#org9e2ac18)
1. [FFI Layer](#org821878d)
5. [Specification](#orgdd36a00)
1. [CON format](#org5e88f7d)
2. [convel format](#org4b3e8e7)
6. [Why use this over readCon?](#org7a9436c)
7. [Citation](#org4154b3e)
2. [License](#org45415ab)
<a id="org6c05cb6"></a>
# About
Oxidized rust re-implementation of [readCon](https://github.com/HaoZeke/readCon).
Reads and writes both `.con` (coordinate-only) and `.convel` (coordinates
plus velocities) simulation configuration files used by [eOn](https://theory.cm.utexas.edu/eon/).
**Ecosystem:** this crate is the **interchange and multi-language ABI** layer.
For campaign-scale corpora (mmap LMDB, non-SQL indexes on natoms / symbols /
energy / forces / velocities, xxHash3 dedup, multi-reader), use the companion
crate **[readcon-db](https://github.com/lode-org/readcon-db)** (`readcon_db` on
PyPI when published). Blobs in the corpus remain CON text and are always
decoded with **readcon-core**—semantics never fork. Foreign formats (XYZ, PDB,
GRO, …) enter via the optional **chemfiles** feature (`read_chemfiles*`), not
ASE. ASE adapters are optional and only for calculator hand-off.
| Interchange | **readcon-core** / Python **`readcon`** | Parse/write CON & convel, spec v2–v3 metadata, chemfiles ingress, hourglass C/Python/Julia FFI |
| Corpus | **[readcon-db](https://github.com/lode-org/readcon-db)** / **`readcon_db`** | Heed/LMDB store, secondary indexes, exact-match dedup, CLI + C/Python/Fortran |
<a id="orgdaee6f9"></a>
## Features
- **CON and convel support:** Parses both coordinate-only and velocity-augmented files. Velocity sections are auto-detected without relying on file extensions.
- **Lazy iteration:** `ConFrameIterator` parses one frame at a time for memory-efficient trajectory processing; `next_with_raw_span` preserves the on-disk blob for corpus ingest without re-serialization.
- **Performance:** Uses [fast-float2](https://github.com/aldanor/fast-float-rust) (Eisel-Lemire algorithm) for the f64 parsing hot path and [memmap2](https://docs.rs/memmap2) for large trajectory files.
- **Parallel parsing:** Optional rayon-based parallel frame parsing behind the `parallel` feature gate.
- **Language bindings:** Python (PyO3), Julia (ccall), C (cbindgen FFI), and C++ (RAII header-only wrapper), following the hourglass design from [Metatensor](https://github.com/metatensor/metatensor).
- **Spec-v2 metadata helpers:** Rust, Python, Julia, C, and C++ bindings all expose typed helpers for common JSON metadata keys like `energy`, `frame_index`, `time`, `timestep`, `neb_bead`, and `neb_band`, while still allowing raw JSON metadata when needed.
- **Spec-v2 validation:** `validate=true` enforces finite numeric values, reserved metadata schema, physical header geometry, exact component labels, valid symbols, declared section presence, and matching per-atom identity columns.
- **Force and constraint fidelity:** Writers preserve velocities, forces, original atom ids, and per-axis fixed masks across Rust, Python, Julia, C, and C++.
- **Campaign corpora:** pair with [readcon-db](https://github.com/lode-org/readcon-db) for indexed multi-trajectory stores (see its `docs/design.md`).
- **RPC serving:** Optional Cap'n Proto RPC interface (`rpc` feature) for network-accessible parsing.
<a id="org6030511"></a>
## Install
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-left" />
<col class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">Language</th>
<th scope="col" class="org-left">Install command</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left">Rust</td>
<td class="org-left"><code>cargo add readcon-core</code></td>
</tr>
<tr>
<td class="org-left">Python</td>
<td class="org-left"><code>pip install readcon</code></td>
</tr>
<tr>
<td class="org-left">Julia</td>
<td class="org-left"><code>julia --project=julia/ReadCon -e 'using Pkg; Pkg.instantiate()'</code></td>
</tr>
<tr>
<td class="org-left">C / C++ system</td>
<td class="org-left"><code>cargo cinstall --release --prefix /usr/local</code> (installs <code>libreadcon_core.{so,a}</code>, <code>readcon-core.h</code>, <code>readcon-core.hpp</code>, and a pkg-config file)</td>
</tr>
<tr>
<td class="org-left">C / C++ via meson subproject</td>
<td class="org-left">drop the repository under <code>subprojects/readcon-core/</code> and link against the <code>readcon_core_dep</code> dependency</td>
</tr>
</tbody>
</table>
The C/C++ headers require a C99 (`readcon-core.h`) or C++17 (`readcon-core.hpp`, for `std::optional` and `std::filesystem`) compiler.
<a id="org396efa6"></a>
## Tutorial
A copy-pasteable walkthrough that parses a multi-frame trajectory, inspects metadata, builds a new frame, and writes it back. Run it as-is.
cargo run --example rust_usage -- resources/test/tiny_multi_cuh2.con
The example above iterates lazily over every frame, prints atom counts plus the per-frame energy if present, and exits. Equivalent flows in the other bindings:
import readcon
# Read every frame; the iterator yields PyConFrame objects
for frame in readcon.iter_frames("resources/test/tiny_multi_cuh2.con"):
print(frame.natms_per_type, frame.energy()) # energy() is None when absent
# Build and write a new frame
b = readcon.ConFrameBuilder(cell=[10.0, 10.0, 10.0], angles=[90.0, 90.0, 90.0])
b.set_energy(-42.5).add_atom("Cu", 0.0, 0.0, 0.0, 1, 63.546)
b.write("out.con")
using ReadCon
for frame in iter_frames("resources/test/tiny_multi_cuh2.con")
println(frame.natms_per_type, " ", energy(frame))
end
#include <readcon-core.hpp>
#include <iostream>
int main() {
readcon::ConFrameIterator it("resources/test/tiny_multi_cuh2.con");
for (const auto &frame : it) {
std::cout << frame.atoms().size() << " atoms";
if (auto e = frame.energy_opt()) std::cout << " E=" << *e;
std::cout << "\n";
}
}
#include <readcon-core.h>
#include <stdio.h>
int main(void) {
uintptr_t n = 0;
RKRConFrame **frames = rkr_read_all_frames("resources/test/tiny_multi_cuh2.con", &n);
for (uintptr_t i = 0; i < n; ++i) {
printf("frame %zu energy=%f\n", i, rkr_frame_energy(frames[i]));
}
free_rkr_frame_array(frames, n);
}
<a id="org9e2ac18"></a>
## Design Decisions
The library is designed with the following principles in mind:
- **Lazy Parsing:** The `ConFrameIterator` allows for lazy parsing of frames, which can be more memory-efficient when dealing with large trajectory files.
- **Interoperability:** The FFI layer makes the core parsing logic accessible from other programming languages, increasing the library's utility. Currently, a `C` header is auto-generated along with a hand-crafted `C++` interface, following the hourglass design from [Metatensor](https://github.com/metatensor/metatensor).
<a id="org821878d"></a>
### FFI Layer
**C/Fortran quick map (v0.13.1+):** optional Cargo features gate *behavior*, not always symbols.
Metatensor and zstd entry points exist in lean builds but return
`RKR_STATUS_FEATURE_DISABLED` (-11) or a null writer (zstd). Never confuse with
`RKR_STATUS_INTERNAL_ERROR` (-7). Prefer `include/readcon-metatensor.h` when using
blocks; source `target/<profile>/readcon-metatensor.env` for `libmetatensor` paths.
DLPack builder exports use dlpk `ArcArray -> DLPackTensor` (**shared** allocation, not a deep copy; no separate `_borrowed` C API).
Gzip writers are always on; Fortran: `open_writer_gzip` / `_zstd` (+ precision variants).
Details: Sphinx **Language bindings** and `fortran/README.md`.
A key challenge in designing an FFI is deciding how data is exposed to the C-compatible world. This library uses a hybrid approach to offer both safety and convenience:
1. **Opaque Pointers (The Handle Pattern):** The primary way to interact with
frame data is through an opaque pointer, represented as `RKRConFrame*` in C.
The C/C++ client holds this "handle" but cannot inspect its contents
directly. Instead, it must call Rust functions to interact with the data
(e.g., `rkr_frame_get_header_line(frame_handle, ...)`). This is the safest
and most flexible pattern, as it completely hides Rust's internal data
structures and memory layout, preventing ABI breakage if the Rust code is
updated.
2. **Transparent `#[repr(C)]` Structs (The Data Extraction Pattern):** For
convenience and performance in cases where only the core atomic data is
needed, the library provides a function (`rkr_frame_to_c_frame`) to extract a
"lossy" but transparent `CFrame` struct from an opaque handle. The C/C++
client can directly read the fields of this struct (e.g.,
`my_c_frame->num_atoms`). The client takes ownership of this extracted struct
and is responsible for freeing its memory.
This hybrid model provides the best of both worlds: the safety and
forward-compatibility of opaque handles for general use, and the performance of
direct data access for the most common computational tasks.
<a id="orgdd36a00"></a>
## Specification
See [docs/orgmode/spec.org](docs/orgmode/spec.md) (or the [published HTML build](https://lode-org.github.io/readcon-core/spec.html)) for the full specification. A summary follows.
<a id="org5e88f7d"></a>
### CON format
- A 9-line header (comments, cell dimensions, cell angles, atom type/count/mass metadata)
- Line 2 is reserved for spec-v2 JSON metadata
- Per-type coordinate blocks (symbol, label, atom lines with x y z fixed atomID)
- Optional spec-v2 `sections` and `validate` metadata for declared per-atom sections and strict validation
- Multiple frames are concatenated directly with no separator
<a id="org4b3e8e7"></a>
### convel format
Same as CON, with an additional velocity section after each frame's coordinates:
- A blank separator line
- Per-type velocity blocks (symbol, label, atom lines with vx vy vz fixed atomID)
<a id="org7a9436c"></a>
## Why use this over [readCon](https://github.com/HaoZeke/readCon)?
Speed, correctness, and multi-language bindings.
<a id="org4154b3e"></a>
## Citation
If you use `readcon-core` in academic work, please cite it via the metadata in [CITATION.cff](CITATION.cff). The Zenodo DOI tracks the latest release.
<a id="org45415ab"></a>
# License
MIT.