About
License

About

Oxidized rust re-implementation of readCon.

Reads and writes both .con (coordinate-only) and .convel (coordinates plus velocities) simulation configuration files used by eOn.

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.
Performance: Uses fast-float2 (Eisel-Lemire algorithm) for the f64 parsing hot path and 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.
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++.
RPC serving: Optional Cap'n Proto RPC interface (rpc feature) for network-accessible parsing.

Install

Language	Install command
Rust	`cargo add readcon-core`
Python	`pip install readcon`
Julia	`julia --project=julia/ReadCon -e 'using Pkg; Pkg.instantiate()'`
C / C++ system	`cargo cinstall --release --prefix /usr/local` (installs `libreadcon_core.{so,a}`, `readcon-core.h`, `readcon-core.hpp`, and a pkg-config file)
C / C++ via meson subproject	drop the repository under `subprojects/readcon-core/` and link against the `readcon_core_dep` dependency

The C/C++ headers require a C99 (readcon-core.h) or C++17 (readcon-core.hpp, for std::optional and std::filesystem) compiler.

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);
}

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.

FFI Layer

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:

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.
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.

Specification

See docs/orgmode/spec.org (or the published HTML build) for the full specification. A summary follows.

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

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)

Why use this over readCon?

Speed, correctness, and multi-language bindings.

Citation

If you use readcon-core in academic work, please cite it via the metadata in CITATION.cff. The Zenodo DOI tracks the latest release.

License

MIT.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

readcon-0.13.0.tar.gz (350.9 kB view details)

Uploaded Jun 26, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

readcon-0.13.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (608.1 kB view details)

Uploaded Jun 26, 2026 PyPymanylinux: glibc 2.17+ x86-64

readcon-0.13.0-pp311-pypy311_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (592.7 kB view details)

Uploaded Jun 26, 2026 PyPymanylinux: glibc 2.17+ ARM64

readcon-0.13.0-cp315-cp315t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (605.1 kB view details)

Uploaded Jun 26, 2026 CPython 3.15tmanylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (607.8 kB view details)

Uploaded Jun 26, 2026 CPython 3.15manylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (605.2 kB view details)

Uploaded Jun 26, 2026 CPython 3.14tmanylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (586.7 kB view details)

Uploaded Jun 26, 2026 CPython 3.14tmanylinux: glibc 2.17+ ARM64

readcon-0.13.0-cp314-cp314-win_amd64.whl (476.3 kB view details)

Uploaded Jun 26, 2026 CPython 3.14Windows x86-64

readcon-0.13.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (607.8 kB view details)

Uploaded Jun 26, 2026 CPython 3.14manylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (590.6 kB view details)

Uploaded Jun 26, 2026 CPython 3.14manylinux: glibc 2.17+ ARM64

readcon-0.13.0-cp314-cp314-macosx_11_0_arm64.whl (547.1 kB view details)

Uploaded Jun 26, 2026 CPython 3.14macOS 11.0+ ARM64

readcon-0.13.0-cp314-cp314-macosx_10_12_x86_64.whl (570.2 kB view details)

Uploaded Jun 26, 2026 CPython 3.14macOS 10.12+ x86-64

readcon-0.13.0-cp313-cp313-win_amd64.whl (476.0 kB view details)

Uploaded Jun 26, 2026 CPython 3.13Windows x86-64

readcon-0.13.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (607.5 kB view details)

Uploaded Jun 26, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (590.3 kB view details)

Uploaded Jun 26, 2026 CPython 3.13manylinux: glibc 2.17+ ARM64

readcon-0.13.0-cp313-cp313-macosx_11_0_arm64.whl (546.8 kB view details)

Uploaded Jun 26, 2026 CPython 3.13macOS 11.0+ ARM64

readcon-0.13.0-cp313-cp313-macosx_10_12_x86_64.whl (569.8 kB view details)

Uploaded Jun 26, 2026 CPython 3.13macOS 10.12+ x86-64

readcon-0.13.0-cp312-cp312-win_amd64.whl (476.2 kB view details)

Uploaded Jun 26, 2026 CPython 3.12Windows x86-64

readcon-0.13.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (608.0 kB view details)

Uploaded Jun 26, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (590.9 kB view details)

Uploaded Jun 26, 2026 CPython 3.12manylinux: glibc 2.17+ ARM64

readcon-0.13.0-cp312-cp312-macosx_11_0_arm64.whl (547.3 kB view details)

Uploaded Jun 26, 2026 CPython 3.12macOS 11.0+ ARM64

readcon-0.13.0-cp312-cp312-macosx_10_12_x86_64.whl (570.4 kB view details)

Uploaded Jun 26, 2026 CPython 3.12macOS 10.12+ x86-64

readcon-0.13.0-cp311-cp311-win_amd64.whl (478.3 kB view details)

Uploaded Jun 26, 2026 CPython 3.11Windows x86-64

readcon-0.13.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (606.5 kB view details)

Uploaded Jun 26, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (591.0 kB view details)

Uploaded Jun 26, 2026 CPython 3.11manylinux: glibc 2.17+ ARM64

readcon-0.13.0-cp311-cp311-macosx_11_0_arm64.whl (548.7 kB view details)

Uploaded Jun 26, 2026 CPython 3.11macOS 11.0+ ARM64

readcon-0.13.0-cp311-cp311-macosx_10_12_x86_64.whl (571.9 kB view details)

Uploaded Jun 26, 2026 CPython 3.11macOS 10.12+ x86-64

readcon-0.13.0-cp310-cp310-win_amd64.whl (478.4 kB view details)

Uploaded Jun 26, 2026 CPython 3.10Windows x86-64

readcon-0.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (606.8 kB view details)

Uploaded Jun 26, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

readcon-0.13.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (591.5 kB view details)

Uploaded Jun 26, 2026 CPython 3.10manylinux: glibc 2.17+ ARM64

File details

Details for the file readcon-0.13.0.tar.gz.

File metadata

Download URL: readcon-0.13.0.tar.gz
Upload date: Jun 26, 2026
Size: 350.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for readcon-0.13.0.tar.gz
Algorithm	Hash digest
SHA256	`2781fe51f72308f3d858ea1241beb257021c65849a867895e5debba40bc598e9`
MD5	`d93d630cf91f2f6c06d456dba6b69475`
BLAKE2b-256	`3a412a8720c573d38374ecebb6ae52d903e6a8b9595450c601011cd433b06c89`

Algorithm	Hash digest
SHA256	`c3984a21e8941f06cd9a1c58196da02ec55d3e3f0834ab4ea2d81bcb65eed23b`
MD5	`f8dfb48fe14ab089b61724902345e8d5`
BLAKE2b-256	`b2f5f04fed32db83d96932bba15331b6e768564bbf389bb33e175bd03e790ee8`

Algorithm	Hash digest
SHA256	`d3aae53b249f870f7ff96a4c6e2d9363ff11a1b62a10f9d4fd2748b385fc4423`
MD5	`fb6396952562c14839ea770c6e5e06d0`
BLAKE2b-256	`2f5ec8ca463f0ac42dd862c3ab1331795c5dc2dc65ac365a802368db5d76331b`

Algorithm	Hash digest
SHA256	`b1471b7cf07b143c74fbfafa612d63c7b6ed1810a14454972312e739456340a8`
MD5	`e212139996c47f961370a620c97f569d`
BLAKE2b-256	`d68ddc7c9a25323a03988c263ed427dbd1fa227add353ae193f52b80e75a857a`

Algorithm	Hash digest
SHA256	`71fc312ac7a4ff3235c56a352c25f575b1a9aa17c2de3bc200c535eb3c209548`
MD5	`88f41de2b2bb9dfcc0927502f52cd4c8`
BLAKE2b-256	`1100723b5f6a58e000439c12b5b55bde98d16d5b9b5c60a24337181242292696`

Algorithm	Hash digest
SHA256	`4394617adf05e5d38733aabdf844190c2f33639eaa776da701d179200f2e1623`
MD5	`f15b0a6cdeabc2335288a8d3c31efe5f`
BLAKE2b-256	`c7c35ebe7d75725a8bc1e657733ffcc8d77e497f1ecd402abcae0c9747f4f03b`

Algorithm	Hash digest
SHA256	`5695cb1a64a6c6634a100003315b152afc88b7dae225f8ce2fd4c01bc33da260`
MD5	`2da240efc17f01b99628ce7b9a0599f6`
BLAKE2b-256	`e247bf29b00dd77b3ac81086d8c54e319a8ab3075f660edfd31d837540472b43`

Algorithm	Hash digest
SHA256	`c4de046a159f4ec5218a727db9cf4c40b7b3f5aa0c99aba1a50c19964f738e69`
MD5	`47dcbebbbdcfeeff2645f0e916281451`
BLAKE2b-256	`886fa77da85fc37e321d0dabac8e4ea04602eeb5e427b7e9920e8362083d7522`

Algorithm	Hash digest
SHA256	`a3d5925e89a4e2aa02b510f32eb6b15424812271c7508e7962f49184c2d71e8f`
MD5	`cda2cb642fe8d82a3e7b85c3037257ab`
BLAKE2b-256	`962abc99e93cea46829b9a2800138b15b8f004fa31d8bf945e5506484adde5eb`

Algorithm	Hash digest
SHA256	`a9e7dd2f7fdff202fe7f968a75a223a3d58e498321af4f4538b6f6cfc629cef5`
MD5	`45ee7feb34627bf6e04c9c661a293bf7`
BLAKE2b-256	`339d752c43c9dc62c1253f5f393e5e2f02f15977d87441e3917d57732a6d1e7d`

Algorithm	Hash digest
SHA256	`c49b460e7c1bb96ec7f16b242a15f8318cbaf5d41433fa2dd9a2cab39a380d31`
MD5	`87ad2a73d194f9001613f4898e3eac96`
BLAKE2b-256	`e38d8f119858a022a5fd93f7c22d064512438de5177b59af771f909817557485`

Algorithm	Hash digest
SHA256	`0b9508361171fa7fc1f1200c8ec649074a42794736c4f159a19c996256bd038b`
MD5	`c92e9a0aa5232ad7f95748393bee0616`
BLAKE2b-256	`3ceefd2bddc81d282ccda365362d35f0edc21823a8cb69acb7be91767f68bbd6`

Algorithm	Hash digest
SHA256	`727e64d2d145cc9719de5573185e8790e065ea14059e0de692d41698216008d5`
MD5	`c9f8dfc6e424cfbbc43379b7bc09a9cf`
BLAKE2b-256	`f871b3569f76346eb5310f2b59bff27515f26a3b22e472833a770e686129c57e`

Algorithm	Hash digest
SHA256	`0fa1199bcf77b1ec3cef16d85914527feffc29209303255c6e66c74f50247b7e`
MD5	`4b94d9d0e2e7c86c6ac147cbdd311304`
BLAKE2b-256	`2b4c16ff3109927128396b45ddeb0ac8c9af64d34de132540dfb8b53ea466e9e`

Algorithm	Hash digest
SHA256	`81990766a607a9155b4938de39e923be1cd7433fb6dec1064b9bec335f23367f`
MD5	`6841728b8ce3b3e499dc9ec9c498b7f1`
BLAKE2b-256	`0395f3cc5aaf09d5681d03019ba8513e9e37742a755c780f77ff445b7c58f90e`

Algorithm	Hash digest
SHA256	`bd71ee7eb8ed7234ac9bbc3dcceb006a198591e78e3c605d58bbf02a2324bd67`
MD5	`54d928326b5ab6b4d649628a08e7767f`
BLAKE2b-256	`97ec5ff979dae49c38a601b88ce7fa7a0c86bcb4faf94c565630f65754f2f2e4`

Algorithm	Hash digest
SHA256	`e4f7beb876d94a063000de5573e8d5a993f2ed84f497cdd134de268a73f6bbc7`
MD5	`7cdc6d44bf20c19e0295062088cf4923`
BLAKE2b-256	`f15f2a32092ebaac140a9e14f9e09fef878dd143f0c40e83ff28f81b6d364bfb`

Algorithm	Hash digest
SHA256	`cc6f4871814fbc6932cb7865e211daf45327aecf48508af0b3cf7c8f5a9c71aa`
MD5	`893c6a51561829c9d700e47e62295597`
BLAKE2b-256	`a8af0e062f3633acd10906809e7538a0a6ae891874187a5039119df75fbd90b7`

Algorithm	Hash digest
SHA256	`8bddd08de3f9742d626cc6a2e88a0942de0ff82c91b63c5f07916624f168f51c`
MD5	`986c622ed58e3d5593471f5d5cde996e`
BLAKE2b-256	`46909debf4b24f39b5ba614a1204a9fc7c36914c6639ff2cd5e6fdcaf1b4e032`

Algorithm	Hash digest
SHA256	`b3f7f7f144ee4bd46617a83030115c36bbe5f4d954d89f6ff48f64de4fd8859f`
MD5	`dbe679a6dd97520fadab55b1e2e1300f`
BLAKE2b-256	`602d347f4b4832eafafbb9e40011c816dac84b8e13e36f4e86a9cfe5ee9b653b`

Algorithm	Hash digest
SHA256	`0708880bc2b56073d407e8b4e7f87eaed5003ff257515ed314bd04785702d0a2`
MD5	`de080d66e38aa6d9c8d50ad1f2978b4d`
BLAKE2b-256	`7fe47484cebc5368331cfa75474687ff9ee78b40586a1d38e5633714ff664714`

readcon 0.13.0

Table of Contents

About

Features

Install

Tutorial

Design Decisions

FFI Layer

Specification

CON format

convel format

Why use this over readCon?

Citation

License

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Algorithm	Hash digest
SHA256	`a45a4518ac8be1101be0d3a548bc57e4cdc32f951dcb2831a46d9b82ab2f9ffa`
MD5	`26038cd815ec476ece2087eb94689e1b`
BLAKE2b-256	`c6d01e4b21c6f496c376ec16221667f487d487225d9c471875281b01973afca5`

Algorithm	Hash digest
SHA256	`53987304fdb1beb322d8d7fcd6fa36d327ebbb0cf5a78384b6b8df8c97bc91d9`
MD5	`3a3c95a687b29af1e0cc71c6cad5de1c`
BLAKE2b-256	`5b7ee149892560bb13426b45aa17cc999c71085180ae22018db60acac60b91ee`

Algorithm	Hash digest
SHA256	`56a4020b222df5090467b97e1d3e79d7ae1da2a21b7323a8f9ac2f3bd5f3a91b`
MD5	`151d8130a3cef3efceea870578ad31ef`
BLAKE2b-256	`05771bc813f4595d41726db5301f4468cec749dcb35dde529e35981e70edabbc`

Algorithm	Hash digest
SHA256	`97f45d7f161e24e3001c60fdada738caa43450b7e598ccd3057194399cf5b16b`
MD5	`e5bf2e39d86773da2c11576797d9430f`
BLAKE2b-256	`4247c9c1b40013bc1507cc26efa5130fb55dc3082821ed95cf1daf5c66627dae`

Algorithm	Hash digest
SHA256	`4749d1334abe7f82dde196ba2fcfba0e5f8b037f0ad3f06dc55e63158a4f8f5f`
MD5	`8e626a1bfd3dfbebbd6eeb90ecb354d6`
BLAKE2b-256	`2421b270ebae3123de0ee669c7b256b1b41dd8025aad00db405e8a79ff6ce081`

Algorithm	Hash digest
SHA256	`ef48b561964c1dc8b20f33aeffe05b6533846f1ee51498e70cc247e0cfbd8d98`
MD5	`905838502168ae9dac2f365254363252`
BLAKE2b-256	`224ab4164effaa259acd249e547b7cc6a2137f76c9289ea94b386b653fe6e904`

Algorithm	Hash digest
SHA256	`e46bdee9181bd26292a76d6d4561592409b74a3df76171d11e422ae3772ed808`
MD5	`d74c10cf56fab359fc877f9af8f918f4`
BLAKE2b-256	`31fd01a2a92cf0b5872e39b6f4acd3399d8ec5f7b6f13922757bac928cfd30c3`

Algorithm	Hash digest
SHA256	`c5a29030c806ead9e68eb21963a86b3726504a7645ef82d90e1684fcf5107bc3`
MD5	`3b8ecc126c6edf300229682688eb47a1`
BLAKE2b-256	`7377697c823f0440fb9564382d5590094758a8b09309acefa13c32126aae1802`

Algorithm	Hash digest
SHA256	`eed66d228f53424fc1feea74ab978abe16bc670badd48b564f3cacb255a67126`
MD5	`790afaa9b3721c17ca83b54ea2685f1b`
BLAKE2b-256	`37825d10913670fc9681bc837804c42ee9b0fbd0bf4289506364aabc8430ecd7`