CON file I/O via readcon-core¶
Starting from v2.12, eOn uses the readcon-core
Rust library for .con and .convel file I/O in the C++ client, while
Python uses the companion readcon package.
C++ Client¶
Reading¶
auto frame = readcon::read_first_frame(filename);
matter.con2matter(frame);
read_first_frame uses memory-mapped I/O for efficient parsing. The returned
ConFrame is then used to populate the Matter object via the
con2matter(const readcon::ConFrame&) overload.
Writing¶
readcon::ConFrameBuilder builder(lengths, angles, prebox_header, postbox_header);
for (long i = 0; i < nAtoms; i++) {
builder.add_atom(symbol, x, y, z, is_fixed, atom_id, mass);
}
auto frame = builder.build();
readcon::ConFrameWriter writer(filename, precision);
writer.extend({frame});
Position precision is 17 digits (matching the previous %22.17f format).
Velocity files use 6-digit precision.
Movie-like outputs can also carry structured frame metadata:
eonc::io::ConFrameMetadata metadata;
metadata.frame_index = 7;
metadata.energy = matter.getPotentialEnergy();
metadata.scalars.push_back({"step_size", step_size});
metadata.scalars.push_back({"convergence", convergence});
matter.matter2con("minimization.con", /*append=*/true, &metadata);
The metadata maps onto readcon-core fields such as energy,
frame_index, neb_bead, neb_band, arbitrary scalar metadata, string
metadata, and an escape hatch for raw JSON.
Multi-frame (append)¶
For multi-frame output, append=true extends the file in place:
if (!path[i]->matter2con(filename, /*append=*/i > 0, &metadata)) {
throw std::runtime_error("Failed to append frame");
}
The new frame is written by ConFrameWriter opened with OpenMode::Append,
so an N-frame trajectory costs N frame writes rather than N(N+1)/2.
flush() returns only after the new frames are a complete multi-frame .con
that a reader or a tail can parse. A non-empty file that does not end in a
newline receives one before the next frame. Gzip and zstd are refused by that
mode.
If the target file exists but cannot be parsed, the append fails rather than
truncating the history. That check runs when eOn did not write the file, or
when its size or modification time moved since eOn wrote it; frames this
process wrote and nobody touched since are extended without a re-parse.
eonc::io::resetConAppendState() drops that bookkeeping for a file replaced
with same-sized content inside one filesystem timestamp tick.
Gzip and zstd targets keep the read-all-and-rewrite path. A compressed member cannot be extended in place, and readcon-core reads a single gzip member, so appended members would be invisible on read-back.
NEB path writers use a small helper wrapper so that per-image metadata stays
consistent across neb.con, neb_path_*.con, and related outputs:
eonc::neb::writePathCon(path, tangent, eigenmode_solvers, numImages,
estimateEigenvalues, "neb.con");
That helper currently stores per-frame fields such as neb_bead, optional
neb_band, reaction_coordinate, relative_energy, and parallel_force.
Python server¶
The eon/fileio.py module uses the readcon PyPI package:
import readcon
frames = readcon.read_con(filename) # read all frames
frame = readcon.read_first_frame(filename) # single frame
readcon.write_con(filename, [frame]) # write
savecon writes those frames to a temporary file in the same directory and
os.replace moves it over the destination. The temporary name keeps the
suffix, so a .gz or .zst target stays compressed. A writer that raises
leaves the previous file. An uncompressed append still extends the file in
place with write_con(append=True).
DurableTable in the same module appends one text line to a table or a
log. The line is a single write, followed by a flush and an fsync. A
final data line with no newline, or with the wrong number of fields, is
dropped on read and a warning is logged. The next append cuts that tail
off before it writes. A write that raises is truncated back to the
length the file had once the torn tail was gone. header_lines keeps a
short header, min_fields is the field count, and exact requires that
count rather than a minimum.
At the time of writing, the Python orchestration layer is still primarily a
consumer of .con data; the richer frame metadata is currently produced in
the C++ client for trajectory outputs and downstream visualization tooling.
Build requirements¶
Rust >= 1.88 (provided by pixi via conda-forge)
cbindgen >= 0.29 (installed via
cargo install cbindgen)Meson >= 1.8.0
The readcon-core library is fetched as a Meson subproject via
subprojects/readcon-core.wrap and linked statically. The wrap pins v0.20.0,
and client/meson.build asks for >=0.20.0 on both resolution paths.
eon/fileio.py needs the companion readcon package at >=0.20.0.
Updating the subproject¶
Meson uses an existing subprojects/readcon-core/ directory unchanged and does
not re-fetch it when the wrap revision changes. After pulling a commit that
moves the wrap, reset the checkout:
meson subprojects update --reset readcon-core
Skipping the reset leaves the build configuring against whatever tag sits on
disk. The version constraint on the subproject() call catches that at
configure time and names readcon-core, so a version complaint about the
subproject points at a stale checkout rather than at anything in
client/ConFileIO.cpp.