How-to — migrate a stack onto CON

Note

Diátaxis how-to (goal-oriented). Learning paths: Tutorial — your first CON checkpoint (native CON I/O) and Convert other formats into CON (foreign formats). Executable conversion (CI): Executable Chemfiles notebook / scripts/run-chemfiles-notebook.sh.

The frequently asked questions explain what a code gains by moving onto .con, and what readcon-db, the frame application programming interface (API) and the plotting tools add.

Moving to 0.20

builder%add_atom and builder%add_atom_full take the per-axis fixed flags before the atom id and the mass. That is the rkr_frame_add_atom_full order. A caller that still passes the id and the mass first is on the previous public argument order:

! previous public order
st = bd%add_atom(symbol, x, y, z, atom_id, mass, fixed_x, fixed_y, fixed_z)
! current public order
st = bd%add_atom(symbol, x, y, z, fixed_x, fixed_y, fixed_z, atom_id, mass)
st = bd%add_atom_full(symbol, x, y, z, fixed_x, fixed_y, fixed_z, atom_id, mass, &
     velocity=vel, force=frc)

velocity and force are optional rank-1 arrays of length 3 and still follow the mass. add_atom takes velocity only.

Stock CON and convel files read coordinates through the column walker. Python read_positions returns one (frames, atoms, 3) array and read_coords adds masses and the cell. C rkr_read_positions returns that column without building frame objects. Free the handle with rkr_free_position_block. Frames that do not share one atom count are an error.

Moving to 0.19

read_all_frames and read_con without n_threads stay on the calling thread. Pass n_threads of 2 or more for a Rayon pool. The older docs that described a 48 KiB automatic pool do not match this reader.

read_extxyz returns a dict with positions, masses, cell, species, and arrays. It used to return a tuple of the three numeric arrays. Index the dict. A frame of fewer than 4096 atoms keeps a tuple of symbols, and a repeated symbol is one string object. A wider frame is a SpeciesRow over interned strings. It compares equal to that tuple or to a list of the same symbols, and species.ids() is the id array.

write_con streams one frame at a time and flushes before it returns. append=True extends an uncompressed file. .gz and .zst select the codec from the extension. write_con_string takes start and stop. A read_con result is written with the same header as the C, Fortran, and Julia rewrites: the current spec, con_spec_minor when the file omitted it, default units when the file omitted them, and the spec 2 constraint mask. A collective write of that result matches the serial write.

The ASE formats are the ase-readcon package, entry point group ase.ioformats, names readcon-con and readcon-convel.

One-command convert (CLI)

Build with chemfiles when the input is not already CON:

cargo build --release --features chemfiles
./target/release/readcon-core convert structure.xyz structure.con
./target/release/readcon-core convert structure.pdb structure.con
# native CON inspect / rewrite (no chemfiles required):
./target/release/readcon-core convert input.con out.con
./target/release/readcon-core input.con   # summary only

Library entry (same logic as the CLI):

use readcon_core::convert::convert_path_to_con;
use std::path::Path;

let report = convert_path_to_con(Path::new("in.xyz"), Path::new("out.con"))?;
assert!(report.n_atoms_last > 0);

Python one-liner

Chemfiles-linked install for foreign formats:

pip install 'readcon-chemfiles==0.23.2'   # or: maturin develop --features python,chemfiles
import readcon

# Foreign or CON → CON
report = readcon.convert_to_con("structure.xyz", "structure.con")
print(report)  # n_frames, n_atoms_last, native_con

# Same via frame API (tutorial / notebook path; CI-run)
frame = readcon.read_chemfiles_first("structure.xyz")
frame.write_con("structure.con")

Executable Org Babel for the XYZ path: scripts/run-chemfiles-notebook.sh (wired in ci_python.yml chemfiles matrix).

ASE hand-off (keep CON as authority)

import readcon

frame = readcon.read_first_frame("structure.con")
atoms = frame.to_ase()          # atom_id array + constraints when present
# ... calculator / MD step ...
frame2 = readcon.ConFrame.from_ase(atoms)
frame2.write_con("after.con")   # interchange stays CON text

ASE adapters are optional. After the calculator step, write CON again so readcon-db ingest and hourglass consumers still see the interchange file.

Into readcon-db

Once files are CON text:

# see readcon-db docs for open/ingest/select; packages:
#   cargo add readcon-db
#   pip install readcon-db

Screening indexes use the same field meanings as readcon_core::index_proj (finite energy, formula, sections mask). That only works if the blob on disk is CON, not a private trajectory dialect.

Batch: many foreign files → CON

for f in structures/*.{xyz,pdb,gro}; do
  ./target/release/readcon-core convert "$f" "con/${f##*/}.con"
done

Python:

from pathlib import Path
import readcon

for path in Path("structures").glob("*.xyz"):
    readcon.convert_to_con(str(path), str(Path("con") / f"{path.stem}.con"))

More chemfiles recipes: How-to — Chemfiles conversion and selection.

After conversion