Reference — Chemfiles conversion and selection

Note

Diátaxis reference. Learning path: Convert other formats into CON. Executable Org: Executable Chemfiles notebook (scripts/run-chemfiles-notebook.sh).

Convert other formats into CON; for tasks see How-to — Chemfiles conversion and selection; for rationale see Explanation — Chemfiles ingress and CON topology. Binding-wide matrices live in Language bindings; on-disk bonds key in The CON File Format Specification.

Feature and install matrix

Build	Cargo	PyPI	chemfiles_enabled() / has_chemfiles_support()
Lean	default features	readcon	false (stubs)
Full	--features chemfiles	readcon-chemfiles	true
Full editable	maturin develop --features python,chemfiles	n/a	true

Optional extra on lean package: readcon[chemfiles] → depends on readcon-chemfiles==X.Y.Z (same version; avoid installing both modules).

Rust modules

Module	Role
readcon_core::chemfiles_import	Foreign format → ConFrame
readcon_core::chemfiles_selection	Selection grammar on ConFrame

Import (full feature)

Function	Purpose
con_frame_from_chemfiles(&Frame)	Single chemfiles frame
con_frame_from_trajectory_path(path)	First step of a file
con_frame_from_trajectory_path_nth(path, i)	Step i via read_step
nsteps_from_trajectory_path(path)	Trajectory::nsteps
con_frames_from_trajectory_path(path)	All steps
con_frames_from_trajectory_path_with(path, opts)	Skip / stride / topology / guess_bonds
con_frames_from_memory(data, format)	Buffer + format name ("XYZ", …)
con_frames_from_memory_with	Memory + skip / stride / guess_bonds
ChemfilesReadOpts	start / step / stop / format / topology / guess_bonds
chemfiles_internal_units_json()	Line-2 units chemfiles actually emits (Å, ps, amu)
bonds_from_chemfiles_frame	Topology → Vec<Bond>
chemfiles_enabled()	const fn probe

Import (stubs without feature): path/memory helpers return ChemfilesImportError::FeatureDisabled. con_frame_from_chemfiles is only available with the feature (needs chemfiles::Frame in the signature).

Selection (always available; stubs error without feature)

Item	Purpose
SelectionMatch / SelectionResult	Match payload
evaluate_selection_on_con_frame(sel, frame)	Full result
select_atom_indices(sel, frame)	Atom context → sorted unique indices
parse_selection_string(sel)	Context size only

Constants: CHEMFILES_EXTRA_PREFIX, CHEMFILES_ATOM_PROPS_KEY, CHEMFILES_ATOM_NAMES_KEY, CHEMFILES_ATOM_TYPES_KEY, CHEMFILES_RESIDUES_KEY, CHEMFILES_UNIT_SYSTEM_KEY.

Imported frames stamp chemfiles internal units on CON line 2 (length angstrom, time ps, mass amu). Chemfiles converts GRO nm → Å (and other format units) on read; the CON numbers are already in that system. Energy stays the CON default eV because chemfiles does not convert energies.

Error: ChemfilesImportError (Chemfiles / InvalidFrame / Io / FeatureDisabled; Chemfiles variant only in full builds).

Python (import readcon)

API	Lean wheel	readcon-chemfiles
has_chemfiles_support()	False	True
read_chemfiles(path, *, skip=0, step=1, stop=None, topology=None, format=None, guess_bonds=False)	RuntimeError	list[ConFrame]
read_chemfiles_first(path)	RuntimeError	ConFrame
read_chemfiles_nth(path, index)	RuntimeError	ConFrame (read_step)
read_chemfiles_nsteps(path)	RuntimeError	int
read_chemfiles_memory(data, format, *, skip=0, step=1, stop=None, guess_bonds=False)	RuntimeError	list[ConFrame]
select_on_frame(frame, sel) / frame.select(sel)	error	dict
select_atom_indices(frame, sel) / frame.select_atoms(sel)	error	list[int]
frame.write_con(path)	yes	yes
PyConFrame.bonds / has_bonds	yes	yes

select / select_on_frame dict keys: selection, context_size, matches (list[list[int]]), primary_indices. format for memory import is a chemfiles name ("XYZ", "PDB", "GRO", …).

C / C++

Symbol	Notes
rkr_has_chemfiles_support	0 or 1
rkr_frame_select	Fills RKRSelectionResult*; stubs → RKR_STATUS_SELECTION_ERROR
rkr_selection_result_match_count / _context_size / _match_at / _primary_indices / _free	Always declared
readcon::ConFrame::select	C++ RAII; throws if support is 0
readcon::has_chemfiles_support	C++

CON metadata keys (topology / sidecars)

Key	Meaning
bonds	Array of [i,j] or {i,j,order?}; 0-based atom_data indices
chemfiles_atom_names	Display names, chemfiles/=atom_id= order
chemfiles_atom_types	Atomic types, parallel to names
chemfiles_atom_properties	Per-atom property bags
chemfiles::…	Unmapped frame properties

See The CON File Format Specification § frame topology for normative wording.

Selection grammar (implemented on CON frames)

Pattern	Needs bonds?	Context size
name X / type Y / all / none	no	1
bonds: … / pairs: … / two: …	yes for topology filters	2
angles: … / three: …	yes (derived)	3
dihedrals: … / four: …	yes (derived)	4
is_bonded / is_angle / is_dihedral	yes	2 / 3 / 4

These patterns are what CON selection implements (tests under chemfiles_selection_cpp_regression for topology cases). Format limits (resname, properties, impropers, geometry thresholds) are CON limits—see chemfiles-explain.org (What selection cannot see on CON). The optional conversion stack may reuse a third-party grammar engine; that is an implementation detail, not a second public API surface.

CI / release artifacts

Workflow	Produces
python_wheels.yml matrix default	PyPI readcon
python_wheels.yml matrix chemfiles	PyPI readcon-chemfiles (Windows uses official prebuilt libchemfiles + advapi32; not chemfiles-from-sources)
c_lib_tarball.yml	readcon-core-clib-$VER-$target.tar.gz on Linux/macOS; Windows + chemfiles is an explicit skip
crates_publish.yml	crates.io readcon-core (chemfiles still optional feature)

Pending/active trusted publishers must use exact PyPI names readcon and readcon-chemfiles.