How-to — atom correspondence¶
Note
Diátaxis how-to. The file layout is the Tutorial — your first CON checkpoint. Language recipes for read and write are How-to — CON I/O by language.
Column 5 is atom_id, the atom’s index before type-grouping. readcon-core
keeps that id through read and write. The in-memory order is still the
type-grouped file order, so a positional zip of two frames pairs whatever
atoms happen to share a slot. A writer that emits oxygen before carbon, or
a band image whose rows were renumbered, then reports a displacement for
the wrong atom.
The CPC paper treats that stable id as what makes atom correspondence
possible. These four calls are that correspondence. reference is frame A.
other is frame B. Errors name the frame index and the atom_id.
Call |
Result |
|---|---|
|
|
|
B in A’s order. Positions, velocities, forces, and the other per-atom sections move with the atom. Bond endpoints are remapped |
|
The first frame in a trajectory or NEB band that disagrees with frame 0, and the atom |
|
Wrapped |
Duplicate ids, a missing id, an extra id, and a symbol mismatch fail in
both modes. strict (the default) also requires the mass and the fixed
mask to agree. Masses within 1e-8 agree, the same tolerance the builder
uses for one mass per CON type. strict false keeps the id and symbol
checks and allows a mass or mask difference.
The displacement uses the reference frame’s cell. FrameHeader::cell_matrix
supplies the lattice (a stored lattice_vectors matrix, otherwise the
matrix built from lines 3–4) and pbc_effective supplies the periodic
axes. A missing pbc key is fully periodic. The helper inverts that
matrix.
Rust¶
use readcon_core::{
IdentityCheck, atom_id_permutation, check_atom_id_consistency,
minimum_image_displacements, reorder_like,
};
let perm = atom_id_permutation(&reactant, &product, IdentityCheck::Strict)?;
let product_in_reactant_order = reorder_like(&reactant, &product, IdentityCheck::Strict)?;
check_atom_id_consistency(&band, IdentityCheck::Strict)?;
let disp = minimum_image_displacements(&reactant, &product, IdentityCheck::Strict)?;
disp[i] is the minimum-image step of reactant atom i. A coordinate that
was stored one cell away comes back as the short vector.
Python¶
import readcon
perm = readcon.atom_id_permutation(reactant, product)
ordered = readcon.reorder_like(reactant, product)
readcon.check_atom_id_consistency(band)
disp = readcon.minimum_image_displacements(reactant, product) # (N, 3)
Pass strict=False to allow a mass or fixed-mask difference. A failure
raises ValidationError. frame_index, atom_id, and atom_index are
set when the failure names them. Frame 0 is the reference. Frame 1 is the
other frame. In a band, frame_index is the first image that disagrees
with image 0.
C and C++¶
uint64_t perm[/* N */];
rkr_frame_atom_id_permutation(frame_a, frame_b, 1, perm, n);
RKRConFrame *ordered = rkr_frame_reorder_like(frame_a, frame_b, 1);
uint64_t frame_index, atom_id;
rkr_frames_check_atom_ids(frames, nframes, 1, &frame_index, &atom_id);
double disp[/* 3 * N */];
rkr_frame_minimum_image_displacements(frame_a, frame_b, 1, disp, 3 * n);
strict is 0 for the lenient mass and mask check. On failure the detail
is rkr_last_error_message. The consistency call writes UINT64_MAX to
both outputs when the band agrees. rkr_frame_reorder_like returns a
handle the caller frees with free_rkr_frame.
The C++ wrappers are ConFrame::atom_id_permutation,
ConFrame::reorder_like, ConFrame::minimum_image_displacements, and
check_atom_id_consistency. They throw readcon::Error with that same
message.
A Claisen-like allyl vinyl ether, written with carbon before oxygen in the reactant and oxygen before carbon in the product, is the regression for the positional zip. One image of a three-image band stored with two atoms swapped is the regression for a renumbered band.