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).
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¶
Goal |
Page |
|---|---|
Learn native CON I/O |
|
Selection / bonds on CON |
How-to — Chemfiles conversion and selection, Frequently Asked Questions |
Declared sections / validate |
Frequently Asked Questions, The CON File Format Specification |
Link C / Fortran / Julia |
|
readcon-db |
|
Plotting |