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 |
|
|
Python + chemfiles |
|
readcon-chemfiles on PyPI (do not mix with lean |
Rust CON I/O |
|
|
Rust + chemfiles |
|
same crate |
readcon-db |
|
|
Julia |
from this repo: |
|
C / C++ / Fortran |
CMake FetchContent, Meson wrap, or |
|
Prebuilt C ABI |
|
Language bindings (Julia / Fortran / |
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 |
|
Migrate foreign formats → CON (+ db, selection) |
How-to |
|
Task recipes by language |
How-to |
|
XYZ / PDB / GRO → CON |
Tutorial |
|
Batch convert / C conversion API |
How-to |
|
Why conversion is optional; bonds |
Explanation |
|
Why CON / sections / stack |
Frequently Asked Questions, Format Evolution and Design Rationale |
Explanation |
On-disk format |
Reference |
|
API tables |
Reference |
|
Measurements (ASV / Cachegrind / peers) |
Explanation |
See the frequently asked questions for the package or optional feature that each task needs and for the library layout.