Python and C reference

Rust items are documented on the types themselves. cargo doc --features python,parallel,zstd --no-deps builds that reference. The C header include/readcon-core.h and the C++ header include/readcon-core.hpp document each exported function. This page is the Python surface those calls correspond to. The snippets are executed by tests/python/test_doc_snippets.py and tests/python/test_release_examples.py. The Rust doctests cover ConFrameReader, ConFrameWriter::from_path_append, frames_from_text, read_first_frame, unit_conversion_factor, and the atom_id correspondence helpers. read_positions and read_coords are the fast coordinate path.

read_con

readcon.read_con(path, n_threads=None, *, comm=None, mode="auto")

Read a .con or .convel path. n_threads is None, 0, or 1 for the calling thread, and n >= 2 for a Rayon pool of that size. A plain file of 64 KiB or more stays mapped. .gz and .zst are chosen from the extension and from the magic bytes. A pipe, including /dev/stdin, is read through the same open and is not mapped.

read_all_frames is the same function.

read_positions and read_coords

These are the fast coordinate path. A stock CON or convel file is one coordinate pass, and no per-frame Python object is built. read_con remains the path that returns frames, metadata, and optional sections.

positions = readcon.read_positions(path, n_threads=None)
coords = readcon.read_coords(path)

read_positions returns one float64 array of shape (frames, atoms, 3). The parser allocates that buffer once. The returned array views it: base is the buffer and OWNDATA is false, so the doubles are not copied again on the way into NumPy. n_threads is None, 0, or 1 for the calling thread, and n >= 2 for a Rayon pool of that size when the build has parallel. read_coords returns a dict. positions has that same shape, masses is (frames, atoms), and cell is (frames, 6) with lengths then angles. atom_ids is column 5 and fixed is the column-4 bitmask, both (frames, atoms). species is one list of (symbol, count) runs when every frame uses that order, and one list per frame when a later frame does not. has_section is true when a frame carries velocities or another per-atom section. partial_fixed is true when a mask holds some axes only. The dict also carries n_frames, n_atoms, parse_s, convert_s, and copy_s. A file whose frames do not share one atom count raises ValueError.

import readcon

frame = readcon.ConFrame(
    (10.0, 10.0, 10.0),
    (90.0, 90.0, 90.0),
    [readcon.Atom("H", 1.25, 0.0, 0.0, atom_id=1, mass=1.0)],
)
readcon.write_con("one.con", [frame])
positions = readcon.read_positions("one.con")
coords = readcon.read_coords("one.con")
assert positions.shape == (1, 1, 3)
assert positions[0, 0, 0] == coords["positions"][0, 0, 0] == 1.25
assert coords["masses"][0, 0] == 1.0
assert list(coords["cell"][0]) == [10.0, 10.0, 10.0, 90.0, 90.0, 90.0]
assert positions.base is not None
assert not positions.flags["OWNDATA"]
assert positions.flags["C_CONTIGUOUS"]

ConFrameList.columns and write_columns

A read_con result keeps one coordinate slab when every frame has the same atom count. columns() returns that slab as positions. A second call is the same array object. masses is (frames, atoms). fixed is (frames, atoms, 3), with 1.0 where that axis is held. cell is (frames, 6), lengths then angles. velocities and forces are (frames, atoms, 3) when any frame carries that section, and None otherwise. n_frames and n_atoms are the two sizes.

Indexing frames[i] takes that frame out of the stored list. columns() then raises OSError. Call columns() before any index.

write_columns(path, columns, symbol="Cu", n_threads=None) writes the dict. Every atom is symbol. The NumPy arrays are borrowed once and the file is formatted with the GIL released. There is no per-atom Python loop. n_threads of 2 or more is the parallel writer.

import readcon

stored = readcon.read_con("one.con")
cols = stored.columns()
assert cols["positions"] is stored.columns()["positions"]
assert cols["positions"].shape == (1, 1, 3)
assert cols["masses"][0, 0] == 1.0
readcon.write_columns("from_columns.con", cols, symbol="H")
written = readcon.read_positions("from_columns.con")
assert written.shape == cols["positions"].shape
assert written[0, 0, 0] == cols["positions"][0, 0, 0]
assert written.base is not None
assert not written.flags["OWNDATA"]

read_con_string

readcon.read_con_string(text)

Parse CON text that the caller already holds. sys.stdin.read() is that text when the stream is plain CON.

write_con

readcon.write_con(path, frames, precision=None, compression=None, *,
                  canonical=False, comm=None, mode="auto", append=False)

One frame is converted and written, then dropped, before the next frame is converted. A read_con result is written from the stored frames, so the write does not build a Python frame per index. Those frames receive the same header stamp as the C, Fortran, and Julia rewrites, and comm= writes that same stored result, so the serial file and the collective file match. The writer buffer is flushed before the function returns.

compression is None to take the codec from the extension (.gz gzip, .zst zstd), or "gzip", "zstd", or "none". The wheels on PyPI are built with the zstd feature, so a .zst path writes zstd. A source build without that feature raises ValueError and names zstd. append=True extends an uncompressed file. Gzip, zstd, and comm= are refused.

write_con_string

readcon.write_con_string(frames, precision=None, *, canonical=False,
                         start=0, stop=None)

start and stop are a half-open index range. A read_con result in that range is written from the stored frames, with the same header stamp as write_con.

read_extxyz and write_extxyz

tables = readcon.read_extxyz(path)
readcon.write_extxyz(path, tables)

tables["positions"] has shape (frames, atoms, 3), tables["masses"] is (frames, atoms), tables["cell"] is (frames, 6), and tables["species"] is one symbol sequence per frame. A frame of fewer than 4096 atoms is a tuple. A wider frame is a SpeciesRow in a SpeciesFrames sequence, an immutable view of interned strings. tables["species"].ids() is the (frames, atoms) array of those ids, zeros when the file is one symbol. A row supports len, indexing, iteration, slicing, equality with a tuple or a list of the same symbols, pickling, and hash when that tuple would be hashable. tables["arrays"] holds every per-atom column. A repeated symbol is one string object, and a frame whose symbols match the previous frame is that same tuple when the frame is under 4096 atoms. tables["arrays"]["pos"] is tables["positions"]. tables["arrays"]["masses"] is tables["masses"]. tables["arrays"]["species"] is tables["species"]. A .gz or .zst path is read and written as that codec. The wheels on PyPI include zstd. A source build without the zstd feature raises ValueError and names zstd. n_threads of 2 or more splits frames, or the atoms of one wide frame. A file whose symbols differ, or whose header changes from frame to frame, uses the general scan. The uniform scan is only for one species and one column layout repeated in every frame.

iter_con

readcon.iter_con(path, mmap=False, stream=False)

stream=True decompresses and parses while it reads. mmap=True keeps a plain file of at least 64 KiB mapped. The ASE plugin uses stream=True for a forward slice.

Atom correspondence

readcon.atom_id_permutation(reference, other, *, strict=True)
readcon.reorder_like(reference, other, *, strict=True)
readcon.check_atom_id_consistency(frames, *, strict=True)
readcon.minimum_image_displacements(reference, other, *, strict=True)

These calls pair atoms by column 5, atom_id, and not by row. atom_id_permutation returns a list[int]. Entry i is the index in other of the atom with the atom_id of reference atom i. reorder_like returns a new ConFrame, which is other in reference order. Each atom keeps its position, velocity, force, and other per-atom values. Bond endpoints follow the new order. check_atom_id_consistency takes a list of frames, such as a trajectory or a nudged elastic band (NEB), and returns None when every frame names the atoms of frames[0]. A single frame checks that its ids are unique. minimum_image_displacements returns a float64 array of shape (N, 3) in reference order. The cell and the periodic flags are the reference frame’s.

Duplicate ids, a missing or extra id, and a symbol mismatch fail in both modes. strict=True also requires the masses (within 1e-8) and the fixed masks to agree. strict=False allows a mass or mask difference. A failure raises ValidationError. Its frame_index, atom_id, and atom_index attributes are set when the failure names them.

C passes strict as a uint8_t, with 0 for the lenient mass and mask check. The C calls are rkr_frame_atom_id_permutation, rkr_frame_reorder_like, rkr_frames_check_atom_ids, and rkr_frame_minimum_image_displacements. A C failure leaves the detail in rkr_last_error_message. The C++ wrappers are ConFrame::atom_id_permutation, ConFrame::reorder_like, ConFrame::minimum_image_displacements, and check_atom_id_consistency. The Rust calls take IdentityCheck::Strict or IdentityCheck::Lenient. How-to — atom correspondence is the how-to.

ASE formats

Install ase-readcon next to readcon. Its pyproject.toml publishes:

[project.entry-points."ase.ioformats"]
readcon-con = "ase_readcon.io:readcon_con_format"
readcon-convel = "ase_readcon.io:readcon_convel_format"

Install both packages, then ASE loads the ase.ioformats group:

pip install readcon ase
pip install -e ase-readcon

The format names are readcon-con and readcon-convel. A read of index=":" returns every frame. A geometry file uses readcon-con. A file with velocities uses readcon-convel, and that writer keeps the velocities. Column 5 is arrays["atom_id"]. A missing array is written as 0 .. n-1. ASE tags are not column 5. A hold on every axis is FixAtoms. A hold on some axes is FixCartesian with that mask. Masses are the per-atom masses from the file, including a later frame whose element order differs. The example below builds two frames, one atom fixed on every axis and one fixed on z only, then reads them back.

import readcon
from ase.constraints import FixAtoms, FixCartesian
from ase.io import read, write

cu = readcon.Atom("Cu", 0.0, 0.0, 0.0, fixed=[True, True, True], atom_id=4, mass=63.546)
h = readcon.Atom("H", 1.2, 0.0, 0.0, fixed=[False, False, True], atom_id=9, mass=1.008)
h.vx, h.vy, h.vz = 0.1, 0.0, 0.0
frame = readcon.ConFrame((10.0, 10.0, 10.0), (90.0, 90.0, 90.0), [cu, h])
readcon.write_con("run.con", [frame, frame])
images = read("run.con", index=":", format="readcon-con")
assert len(images) == 2
assert list(images[0].arrays["atom_id"]) == [4, 9]
assert abs(images[0].get_masses()[0] - 63.546) < 1e-6
assert any(isinstance(c, FixAtoms) for c in images[0].constraints)
assert any(isinstance(c, FixCartesian) for c in images[0].constraints)
write("again.convel", images, format="readcon-convel")
back = read("again.convel", index=":", format="readcon-convel")
assert list(back[1].arrays["atom_id"]) == [4, 9]
assert back[1].get_velocities()[1][0] != 0.0

read_conbin and read_pdb

write_conbin(con_path, out_path) streams a CON file into a CON-bin. read_conbin(path) returns positions, velocities, and the atom count. read_pdb(path) returns positions, masses, and the cell, and does not build a frame. The runnable copies are in How-to — CON I/O by language.

C writer calls

create_writer_from_path_append_c and create_writer_from_path_append_with_precision_c open an uncompressed file at the end. rkr_writer_flush pushes the buffer. rkr_write_frames_to_string serializes frames without a file. rkr_read_all_frames stays on the calling thread. rkr_read_all_frames_n_threads takes the worker count. A count below 2 is the calling thread. rkr_read_positions returns the same coordinate column as Python read_positions and does not build frame objects. rkr_position_block_values is the row-major x y z pointer. rkr_free_position_block frees the handle and that buffer. NULL is a no-op. rkr_read_positions_n_threads takes the worker count. A count below 2 is the calling thread. A file whose frames do not share one atom count returns NULL. The declarations and the error records are in include/readcon-core.h. The C++ header includes that C API. The C++ wrappers are ConFrameWriter::OpenMode, ConFrameWriter::flush, and ConFrameWriter::round_trip in include/readcon-core.hpp.