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

Package

Install

Destination

Python CON I/O

pip install 'readcon==0.23.2'

readcon on PyPI

Python + chemfiles

pip install 'readcon-chemfiles==0.23.2'

readcon-chemfiles on PyPI (do not mix with lean readcon in the same venv)

Rust CON I/O

cargo add readcon-core@0.23.2

docs.rs

Rust + chemfiles

cargo add readcon-core@0.23.2 --features chemfiles

same crate

readcon-db

cargo add readcon-db / pip install readcon-db

readcon-db docs · readcon-db on 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.23.2'

Python: CON I/O plus format conversion

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

Rust: CON I/O

cargo add readcon-core@0.23.2

Rust: with conversion

cargo add readcon-core@0.23.2 --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.23.2/readcon-core-cxx-0.23.2.tar.gz
  URL_HASH SHA256=f08dfa919f61671636f01032f7c49a0f74f464a9f04bcd86f054f85402575b4a
)
FetchContent_MakeAvailable(readcon-core)
target_link_libraries(app PRIVATE readcon-core::shared)

The slim cxx tarball on the v0.23.2 GitHub Release is the FetchContent URL. A vendor tarball (readcon-core-cxx-0.23.2-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.

ASE

ase-readcon registers readcon-con and readcon-convel on the ase.ioformats entry point. ase.io.read and ase.io.write load that group when the format name is one of those two.

[project.entry-points."ase.ioformats"]
readcon-con = "ase_readcon.io:readcon_con_format"
readcon-convel = "ase_readcon.io:readcon_convel_format"
pip install 'readcon==0.23.2' ase
pip install -e ase-readcon

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

Command line

The readcon-core binary inspects a CON file and can rewrite it. convert copies a CON path with no extra features. XYZ, PDB, and GRO need a build with chemfiles.

cargo build --release
./target/release/readcon-core resources/test/tiny_cuh2.con
./target/release/readcon-core resources/test/tiny_cuh2.con copy.con
cargo build --release --features chemfiles
./target/release/readcon-core convert water.xyz water.con

The library call behind convert is convert_path_to_con. A native CON input sets native_con and does not load chemfiles.

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

See the frequently asked questions for the package or optional feature that each task needs and for the library layout.