Getting started¶

Tip

Install one language, then run the Tutorial — your first CON checkpoint. XYZ/PDB/GRO conversion is a separate path: Convert other formats into CON.

Install¶

Pick one language. Version pins match this tree (0.16.1).

Package	Install	Destination
Python CON I/O	`pip install 'readcon==0.16.1'`	PyPI
Python + chemfiles	`pip install 'readcon-chemfiles==0.16.1'`	PyPI (do not mix with lean `readcon` in the same venv)
Rust CON I/O	`cargo add readcon-core@0.16.1`	docs.rs
Rust + chemfiles	`cargo add readcon-core@0.16.1 --features chemfiles`	same crate
readcon-db	`cargo add readcon-db` / `pip install readcon-db`	docs · PyPI
Julia	from this repo: `julia --project=julia/ReadCon -e 'using Pkg; Pkg.instantiate()'`	Language bindings
C / C++ / Fortran	CMake FetchContent, Meson wrap, or `pkg-config readcon-core`	Language bindings
Prebuilt C ABI	`readcon-core-clib-$VER-$target.tar.gz` on the GitHub Release	Language bindings (Julia / Fortran / `pkg-config`)

Python: CON I/O¶

pip install 'readcon==0.16.1'

Python: CON I/O plus format conversion¶

pip install 'readcon-chemfiles==0.16.1'
# do not also install lean readcon in the same venv

Rust: CON I/O¶

cargo add readcon-core@0.16.1

Rust: with conversion¶

cargo add readcon-core@0.16.1 --features chemfiles

readcon-db¶

Separate package; CON text stays authoritative. Hosted docs: lode-org.github.io/readcon-db/docs.

cargo add readcon-db
# or: pip install readcon-db

Julia¶

From a checkout of this repository:

julia --project=julia/ReadCon -e 'using Pkg; Pkg.instantiate()'

Language API notes: Language bindings.

Fortran / C / C++¶

Headers in include/ are shipped. cbindgen is not required. CMake FetchContent / find_package(readcon-core), Meson dependency('readcon-core'), or pkg-config --libs readcon-core after a prefix install. The cxx tarball on the GitHub Release is readcon-core-cxx-$VERSION.tar.gz.

include(FetchContent)
FetchContent_Declare(
  readcon-core
  URL https://github.com/lode-org/readcon-core/releases/download/v0.16.1/readcon-core-cxx-0.16.1.tar.gz
  URL_HASH SHA256=94df61bccfe2518a95b76041cf9042ef9f331d781ca400de2bfef5c070e1309a
)
FetchContent_MakeAvailable(readcon-core)
target_link_libraries(app PRIVATE readcon-core::shared)

The slim cxx tarball on the v0.16.1 GitHub Release is the FetchContent URL. A vendor tarball (readcon-core-cxx-0.16.1-vendor.tar.gz) ships crates for offline builds. The Meson wrap file is packaging/wrapdb/readcon-core.wrap on that same release.

readcon_dep = dependency('readcon-core')

From a git checkout:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$PWD/prefix
cmake --build build && cmake --install build
export PKG_CONFIG_PATH=$PWD/prefix/lib/pkgconfig
pkg-config --cflags --libs readcon-core

Fortran smoke from a checkout (after a release build of the cdylib):

cd fortran/ReadCon && fpm test --flag "-L../../target/release" \
  --link-flag "-L../../target/release -lreadcon_core -ldl -lpthread -lm"

Prebuilt C ABI (no local cargo): unpack readcon-core-clib-$VERSION-$target.tar.gz from the GitHub Release, then export READCON_CORE_LIB / PKG_CONFIG_PATH. Attach assets to an already-published tag with Actions → C ABI library tarball → tag=vX.Y.Z. Windows + chemfiles is not a clib asset.

Smoke test¶

From the repository root (fixtures live under resources/test/):

import readcon
frame = readcon.read_first_frame("resources/test/tiny_cuh2.con")
print(frame.cell, len(frame))

use readcon_core::iterators::read_first_frame;
let frame = read_first_frame(std::path::Path::new("resources/test/tiny_cuh2.con"))?;
println!("{:?} {}", frame.header.boxl, frame.atom_data.len());

Where to go next¶

Documentation follows Diátaxis. Use one quadrant at a time.

Goal	Page	Kind
Learn CON I/O end-to-end	Tutorial — your first CON checkpoint	Tutorial
Migrate foreign formats → CON (+ db, selection)	How-to — migrate a stack onto CON	How-to
Task recipes by language	How-to — CON I/O by language	How-to
XYZ / PDB / GRO → CON	Convert other formats into CON	Tutorial
Batch convert / C conversion API	How-to — Chemfiles conversion and selection	How-to
Why conversion is optional; bonds	Explanation — Chemfiles ingress and CON topology	Explanation
Why CON / sections / stack	Frequently Asked Questions, Format Evolution and Design Rationale	Explanation
On-disk format	The CON File Format Specification	Reference
API tables	Language bindings	Reference
Measurements (ASV / Cachegrind / peers)	Performance Benchmarks	Explanation

Scope (map of the stack)¶

Task	Path
Read / write CON	`readcon` / `readcon-core`
Link from Fortran / C / C++	Hourglass `rkr_*` ABI
readcon-db (install)	`cargo add readcon-db` / `pip install readcon-db`
Many trajectories, multi-reader	readcon-db docs (CON text authoritative)
Campaign field projection	`index_proj <https://docs.rs/readcon-core/latest/readcon_core/index_proj/>`_ (same meanings as db indexes)
Foreign structure file → CON	Optional chemfiles build
ASE calculator hand-off	Optional `to_ase` / `from_ase`
Migrate foreign stack → CON	How-to — migrate a stack onto CON (CLI `convert`, `convert_to_con`)
PR / CI speed gates	Performance Benchmarks (ASV + Cachegrind)

Library layout: Library architecture.