The CON File Format Specification¶
- Date:
2026-10-11
Requirement words¶
The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY on this page follow RFC 2119.
Specification¶
- Version
3.1 (major 3, minor 1)
- Date
2026-10-11
- Status
Stable
- Reference implementation
- Surface grammar
grammar/readcon.pest(included in the appendix; not the hot path)- Clause index
docs/orgmode/clauses.tsv, emitted byscripts/emit_clauses.py- In-memory API
CON implementation notes (informative for this format)
This document is the normative CON format. CON checkpoints come from
rare-event work on eOn
Goswami [2026] Goswami [2026] Goswami et al. [2025] Chill et al. [2014].
Each normative requirement has an id CON-<section>.<n>.
Where this prose and the included PEG disagree, these clauses win.
- CON-status.1 :: MUST
A reader MUST accept the version number of every minor of major 3, including minor 0 and unknown minors.
- CON-status.2 :: MUST
A new implementation MUST accept version 2 and implicit version 1.
File¶
A file is a concatenation of frames. Extensions: .con, .convel,
and the compression envelopes .con.gz, .convel.gz, .con.zst,
.convel.zst.
- CON-file.1 :: MUST
A CON file MUST be UTF-8.
- CON-file.2 :: MUST NOT
A CON file MUST NOT begin with a byte-order mark.
- CON-file.3 :: MUST
Parsers MUST accept LF (
\n) and CRLF (\r\n) line endings.- CON-file.4 :: MUST
Parsers MUST ignore trailing spaces and tabs on every line.
- CON-file.5 :: MUST
Labels MUST be compared case-insensitively after collapsing each run of spaces to one space.
- CON-file.6 :: MUST NOT
Writers MUST NOT insert an extra blank line between frames.
Frame and end of file¶
Each frame is a 9-line header, one coordinate block per atom type, then the declared sections. There is no inter-frame marker. After a complete frame the next line is line 1 of the next frame, even when that line is empty. A stray blank therefore shifts that header and fails at its line 3.
- CON-frame.1 :: MUST
After the last complete frame, lines that contain only whitespace MUST be ignored.
- CON-frame.2 :: MUST NOT
Readers MUST NOT silently drop a partial last frame.
- CON-frame.3 :: MUST
One to eight header lines of a further frame MUST be reported as
IncompleteHeader, except a type count of 0 at end of file whose lines 8 and 9 are absent.- CON-frame.4 :: MUST
Fewer coordinate rows than the header declares MUST be reported as
IncompleteFrame.- CON-frame.5 :: MUST NOT
A blank line followed only by whitespace to end of file MUST NOT be read as a legacy velocity block.
- CON-frame.6 :: MUST
A partial declared section MUST be reported as
IncompleteSection(name).- CON-frame.7 :: MUST
After a complete frame, including its declared sections or the legacy velocity block where that applies, the next line MUST be line 1 of the next frame, even when it is empty.
Header¶
Line |
Content |
|---|---|
1 |
Free-form generator text, preserved |
2 |
One JSON object, or free text for version 1 |
3 |
Three lengths a, b, and c, in |
4 |
|
5 |
Free-form text, preserved |
6 |
Free-form text, preserved |
7 |
Type count, integer >= 0 |
8 |
Per-type counts, empty when line 7 is 0 |
9 |
Masses in |
Line 1 and lines 5-6 have no semantics.
Line 1 MAY be empty, and parsers MUST keep that empty line.
Line 2 MAY be empty. An empty line 2 does not start with {, so the frame is implicit version 1.
Angstrom and amu apply when units or that key is absent.
- CON-header.1 :: MAY
Writers MAY leave lines 5 and 6 empty.
- CON-header.2 :: MUST
Parsers MUST preserve line 1 and lines 5 and 6.
- CON-header.3 :: MUST
Line 3 and the coordinate columns MUST be read in
units.length, and line 9 inunits.mass. Absentunitsor an absent key means angstrom and amu.- CON-header.4 :: MUST
Parsers MUST accept an empty line 1 and an empty line 2. An empty line 1 is preserved. An empty line 2 is implicit version 1.
Line 2: Metadata¶
Line 2 is one JSON object when the file is version 2 or newer.
A line that does not start with { after trimming is implicit version 1.
Metadata is line 2. Line numbers count from 1.
- CON-line2.1 :: MUST
A line 2 that starts with
{MUST be one UTF-8 JSON object and nothing else.- CON-line2.2 :: MUST
Malformed JSON on that line MUST be rejected.
- CON-line2.3 :: MUST
A JSON object that omits
con_spec_versionMUST be rejected.- CON-line2.4 :: MUST
con_spec_versionMUST be a JSON number, the major version, not a string.- CON-line2.5 :: MUST
JSON
con_spec_version0 or 1 MUST be rejected asUnsupportedVersion.- CON-line2.6 :: MUST
An unknown major MUST be rejected as
UnsupportedVersion.- CON-line2.7 :: MUST
A reader of a known major MUST accept the version number of every minor of that major, including minors it does not implement.
- CON-line2.8 :: MUST
Unknown keys MUST be preserved on rewrite.
- CON-line2.9 :: MUST
con_spec_minor, when present, MUST be a JSON integer >= 0.- CON-line2.10 :: MUST
A missing
con_spec_minor, or an explicit 0, MUST mean minor 0.- CON-line2.11 :: MUST
sections, when present, MUST be an array of strings.- CON-line2.12 :: MUST
validate, when present, MUST be a boolean.- CON-line2.13 :: MUST
Reserved keys MUST use the types in this document.
Cell¶
Line 3 is |a| |b| |c|. Line 4 is alpha angle(b,c), beta angle(a,c),
gamma angle(a,b), in degrees. a lies along x and b lies in the xy plane.
eOn 3.6.0 reads that placement at client/ConFileIO.cpp:659-681 and writes it at :531-549.
ASE cellpar_to_cell uses the same orientation by default (ase/geometry/cell.py:50, ab_normal=(0,0,1)).
lattice_vectors is three row vectors in units.length, [a, b, c].
- CON-cell.1 :: MUST
When
lattice_vectorsis present, readers MUST prefer it over lines 3-4.- CON-cell.2 :: MUST
A writer that emits
lattice_vectorsMUST write lines 3-4 consistent with that matrix at the precision the writer is using.- CON-cell.3 :: MUST
A missing
pbckey MUST be read as periodic in all three directions.- CON-cell.4 :: MUST
pbc, when present, MUST be a length-3 array of booleans.- CON-cell.5 :: MUST
lattice_vectors, when present, MUST be three length-3 arrays of finite numbers.- CON-cell.6 :: MUST
When
lattice_vectorsis absent, a reader MUST builda=(|a|, 0, 0),b=(|b| cos gamma, |b| sin gamma, 0), andc=(|c| cos beta, |c| (cos alpha - cos beta cos gamma) / sin gamma, |c| sqrt(1 - cos^2 beta - ((cos alpha - cos beta cos gamma) / sin gamma)^2)), with the angles converted from degrees.
Counts¶
A type count of 0 is a frame with no atoms.
Lines 8 and 9 are whitespace only, no coordinate block and no section follow, sections is absent or empty, and the legacy velocity fallback does not apply.
That frame is legal with validate true.
A per-type count of 0 is InvalidCount when the type count is 1 or more.
ASE 3.29.0 write_eon(Atoms()) writes type count 0, an empty line 8, and an unterminated empty line 9 (ase/io/eon.py:277-307).
ase.io.eon.read_eon then raises IndexError at images[0] (ase/io/eon.py:188). The StopIteration from the ninth next() is caught inside that function (:177-179).
ase.io.read(path, format”eon”)= raises StopIteration from ase/io/formats.py:821 (next(_iread(...)) on a read that yields no image).
- CON-count.1 :: MUST
A type count of 0 MUST be a frame with zero atoms: lines 8 and 9 contain only whitespace, no coordinate block and no section block follow,
sectionsis absent or empty, and the legacy velocity fallback does not apply. Any other token on line 8 or 9 MUST beInvalidCount.- CON-count.2 :: MUST
A zero-atom frame of that form MUST be accepted in every mode, including
validatetrue.CON-validate.3still requires thesectionskey whenvalidateis true.- CON-count.3 :: MUST
When the type count is 1 or more, each per-type count MUST be an integer >= 1, and any other count token MUST be
InvalidCount.- CON-count.4 :: MUST
At end of file, when line 7 is 0, missing lines 8 and 9 MUST be read as empty, and
CON-frame.3MUST NOT report that frame asIncompleteHeader.- CON-count.5 :: SHOULD NOT
Writers SHOULD NOT write a zero-atom frame for a consumer that predates v3.1.
- CON-count.6 :: MUST
The coordinate blocks MUST follow header order.
- CON-count.7 :: MUST
The total atom count MUST equal the sum of line 8.
- CON-count.8 :: MUST
Component numbers in labels MUST start at 1.
Coordinates¶
One block per type: a symbol line, a Coordinates of Component N label,
then one atom line per atom of that type. Columns are whitespace-separated.
Column |
Token |
Meaning |
|---|---|---|
1 |
float |
x, in |
2 |
float |
y, in |
3 |
float |
z, in |
4 |
integer |
Constraint flag |
5 |
integer |
Atom id, optional |
Per-direction constraints (column 4)¶
Column 4 is an integer token. Bit 0 is x, bit 1 is y, bit 2 is z. Spec 1 (no JSON on line 2): 0 is free, 1 is fixed in all three directions. Spec 2 and later: 0 through 7 are the bitmask, and 1 is x only. Writers of spec 2 and later emit 7 for all-fixed.
- CON-mask.1 :: MUST
Column 4 MUST be an integer token with no sign and no decimal point.
- CON-mask.2 :: MUST
In spec 1, readers MUST treat 0 as free and 1 as fixed on x, y, and z.
- CON-mask.3 :: MUST
In spec 1, any other column-4 token MUST be
InvalidFixedFlag.- CON-mask.4 :: MUST
In spec 2 and later, values 0 through 7 MUST be read as the bitmask above.
- CON-mask.5 :: MUST
A float spelling, a sign, or a value outside the legal set MUST be
InvalidFixedFlagin every mode, including whenvalidateis absent or false.- CON-mask.6 :: MUST NOT
A spec 2 or later writer MUST NOT emit 1 to mean all-fixed.
- CON-mask.7 :: MUST
A spec 2 or later writer MUST emit 7 for an atom fixed on x, y, and z.
Atom index (column 5)¶
Column 5 is the atom id. No base is implied.
Grouping by type reorders atoms relative to a pre-group sequence.
eOn 3.6.0 stable-sorts by ascending id when the ids are unique, and keeps file order when any id repeats (client/ConFileIO.cpp:147-176 matter_order, called at :691).
v3.4.0 has the same function.
- CON-id.1 :: MUST
Column 5, when present, MUST be parsed as an integer in 0 through 2^64-1, and MUST NOT be parsed through binary64.
- CON-id.2 :: MUST NOT
Readers MUST NOT assume that ids start at 0 or at 1.
- CON-id.3 :: MUST
Writers MUST emit ids that are unique within the frame.
- CON-id.4 :: MUST
Readers MUST accept repeated ids.
- CON-id.5 :: MUST
The pre-grouping order of a frame MUST be ascending column-5 id when the ids are unique, and file order otherwise.
- CON-id.6 :: MUST
A reader MUST expose column-5 ids unchanged.
- CON-id.7 :: MUST
A reader or consumer that returns atoms in pre-grouping order MUST use
CON-id.5.- CON-id.8 :: MAY
A reader MAY return atoms in file order together with their column-5 ids.
- CON-id.9 :: MUST
A 4-column atom line MUST use the 0-based position of that atom in the frame as its id.
Sections¶
A section is present exactly when its name is in sections.
An empty sections array means no section follows, and it disables the
legacy velocity fallback. With no sections key, one blank line that
begins a complete velocity block is a velocity section. A blank line
that does not begin that block is line 1 of the next frame. That fallback
is the only undeclared section, and CON-frame.5 limits it.
Minor 1 reserves the names in the table below.
A vector row has arity 3 and a scalar row has arity 1.
Those integers count value fields only.
Section declaration¶
- CON-section.1 :: MUST
On disk, a section MUST be treated as present exactly when its name is listed in
sections, aside from the legacy velocity fallback.- CON-section.2 :: MUST
Exactly one blank line MUST precede each section block.
- CON-section.3 :: MUST NOT
Writers MUST NOT put a blank line between the component blocks inside a section.
- CON-section.4 :: MUST
Each component block MUST be a symbol line, a label, and one data row per atom of that type.
- CON-section.5 :: MUST
The per-atom energy section name MUST be
energies.- CON-section.6 :: MUST NOT
atom_energiesMUST NOT be used as a section name.- CON-section.7 :: MUST
An unknown section name MUST be reported as
UnknownSectionwhen the frame minor is not newer than the minor this reader implements.- CON-section.8 :: MAY
When the frame minor is newer than the reader implements, the reader MAY skip an unknown section whose value-field count is given by
section_arity.- CON-section.9 :: MUST
If that minor is newer and
section_aritydoes not give the value-field count, the reader MUST reportUnknownSection.- CON-section.10 :: MUST
Adding a reserved section name MUST increase
con_spec_minor.- CON-section.11 :: MUST NOT
Adding a reserved section name MUST NOT require a new major.
- CON-section.12 :: MUST
section_arity, when present, MUST be an object mapping section names to integers >= 1, each the number of value fields on a data row, excluding the flag and the optional id.- CON-section.13 :: MUST
An entry for a reserved section MUST equal 3 for a vector row and 1 for a scalar row, else
InvalidVectorLength.- CON-section.14 :: MUST
A data row of an unknown section MUST hold that arity of value fields, then the flag, and an optional id, so the row has arity+1 or arity+2 tokens.
- CON-section.15 :: MUST
The label of any section MUST be its name compared under
CON-file.5, followed byof Component N.- CON-section.16 :: MUST
A writer of minor 2 or later MUST list in
section_arityevery section it emits that minor 1 does not reserve.
Name |
Label |
Row |
|---|---|---|
|
|
|
|
|
|
|
|
energy flag id |
|
|
charge flag id |
|
|
spin flag id |
|
|
|
|
|
|
|
|
|
Identity columns repeat the coordinate flag and id.
0 in a spreads row is a classical point.
- CON-section.17 :: MAY
When
validateis not true, readers MAY ignore an identity-column mismatch after the row has the right number of fields.- CON-section.18 :: SHOULD
The
energymetadata value SHOULD equal the sum of theenergiesrows.- CON-section.19 :: MUST NOT
A mismatch between that sum and
energyMUST NOT reject the frame.- CON-section.20 :: MUST
Each
spreadsvalue MUST be finite and >= 0.
Validation mode¶
- CON-validate.1 :: MUST
validatetrue MUST add the checks inCON-validate.4.- CON-validate.2 :: MUST NOT
validatetrue MUST NOT relax a check that already applies in every mode.- CON-validate.3 :: MUST
When
validateis true,sectionsMUST be present, and an empty array is legal.- CON-validate.4 :: MUST
In that mode, readers MUST reject a bad reserved-key type, a non-positive cell length, an angle outside (0, 180) degrees, a non-positive mass, a coordinate label that does not match, an unrecognized symbol other than
X, a section label or symbol mismatch, or an identity column that does not match the coordinate row, asValidationError.
Frame topology (bonds)¶
bonds is optional frame topology, not a section.
Each entry is [i, j] or {"i": i, "j": j} with an optional integer order.
Indices are 0-based into coordinate-block order, not column-5 ids.
This key is legal on major 3. It does not change the major.
- CON-bonds.1 :: MUST NOT
bondsMUST NOT appear insections.- CON-bonds.2 :: MUST
With
validatetrue, a malformedbondsentry MUST be rejected.- CON-bonds.3 :: MUST
With
validatefalse, unknownbondsshapes MUST be preserved.
Units (required)¶
units maps a dimension to a unit expression: names combined with \*, /, ^, and parentheses.
Version 3 requires length and energy.
Velocity is length/time taken from units.
The natural time unit used by eOn and by ASE, verified by an eOn 3.6.0 round trip, is written exactly (amu*angstrom^2/eV)^0.5.
That expression is a time. units.rs parses it as about 10.180505710759414 fs.
eOn hard-codes 10.1805055 fs (include/eon/ParametersOptions.h:26).
The relative difference is about 2e-8.
A writer that canonicalises the expression by inserting spaces is not using the pinned spelling.
Names below are the ones src/units.rs at f09b1af accepts for length, energy, mass, and time, compared case-insensitively.
- CON-units.1 :: MUST
Major 3 MUST include
units.lengthandunits.energyas non-empty strings of the matching dimension.- CON-units.2 :: MUST
Optional
mass,time,velocity, andforcestrings, when present, MUST have the matching dimension.- CON-units.3 :: MUST
A writer of minor 1 or later MUST write
units.timewhenever the frame has a velocities section.- CON-units.4 :: MUST NOT
A writer MUST NOT insert
time: fssilently when the frame does not carry a time unit.- CON-units.5 :: MUST
The natural unit MUST be written with the exact spelling
(amu*angstrom^2/eV)^0.5.- CON-units.6 :: MUST NOT
Version 1 MUST NOT carry a
unitsobject.- CON-units.7 :: MAY
Version 2 MAY carry
units.- CON-units.8 :: MUST
In versions 1, 2, and 3.0, velocities MUST be read as
units.lengthper the natural time unit, and length is angstrom whenunits.lengthis absent.- CON-units.9 :: MUST NOT
Any
units.timeon versions 1, 2, and 3.0 MUST NOT be trusted.- CON-units.10 :: MUST
From minor 1 onward,
units.timeMUST be authoritative for velocities.- CON-units.11 :: MUST
A frame of minor 1 or later with a velocities section and no
units.timeMUST be rejected withInvalidUnits.- CON-units.12 :: MUST
A writer of minor 1 or later asked to write velocities with no time unit MUST fail with
InvalidUnits.- CON-units.13 :: MUST
An invalid unit expression on write MUST be reported as
InvalidUnits.- CON-units.14 :: MUST NOT
Writers MUST NOT replace an invalid unit with a default.
- CON-units.15 :: MAY
A consumer MAY apply an explicit velocity time-unit override when a file breaks
CON-units.8throughCON-units.10.- CON-units.16 :: MUST
A reader MUST accept at least these names case-insensitively: length m, meter, metre, angstrom, a, å, nm, nanometer, bohr, a0; energy j, joule, ev, mev, hartree, ha, kcal, kj; mass kg, kilogram, u, amu, dalton, da; time s, second, fs, femtosecond, ps, picosecond, ns, nanosecond; count mol.
Minor 0 is the v3.0 rule because the producers of those velocity sections wrote natural-unit numbers under a fs label.
Numbers¶
- CON-num.1 :: MUST
Readers MUST reject NaN, Inf, Infinity, and the signed and mixed-case spellings of those words, in every numeric field and in every mode, as
NonFiniteValue.- CON-num.2 :: MUST NOT
validatetrue MUST NOT be required before a reader appliesCON-num.1.- CON-num.3 :: MUST NOT
validatetrue MUST NOT accept a non-finite value.- CON-num.4 :: MUST NOT
The C ABI absent-value NaN sentinel MUST NOT be written to a file. It is specified in the implementation notes.
- CON-num.5 :: MUST
Readers MUST convert a finite decimal token to binary64 with correct rounding.
- CON-num.6 :: MUST
A conforming writer in its default mode MUST write each finite float so that parsing it returns the same binary64 (
FloatFormat::RoundTrip).- CON-num.7 :: MUST
Fixed-decimal output MUST be used only when the writer is asked for it, and it need not round-trip.
- CON-num.8 :: MUST
A token that is not a decimal number and not a non-finite spelling MUST be
InvalidNumberFormat, except whereCON-error.3names another class.- CON-num.9 :: MUST
A row with the wrong number of fields MUST be
InvalidVectorLength.
eOn .convel output at 6 digits after the decimal (kConvelPrecision in client/ConFileIO.cpp:43) is fixed-decimal and lossy.
The kinetic-energy loss for that rounding was measured on one 336-atom Pt slab at 300 K (one Maxwell-Boltzmann draw) as 5.8e-7 relative.
A float token is an optional + or -, a significand with at least one digit, an optional fraction (a leading dot is allowed), and an optional exponent. An integer token is one or more ASCII digits and nothing else.
Compression¶
- CON-compress.1 :: MUST
A gzip envelope MUST expose every member of a multi-member file, in order, as CON text.
- CON-compress.2 :: MUST
A zstd envelope MUST expose every frame in the stream as CON text.
- CON-compress.3 :: SHOULD
Readers SHOULD detect gzip and zstd by magic bytes, not only by the extension.
- CON-compress.4 :: MAY
A writer MAY split one frame across gzip members at the same deflate level. The first member then sets the FEXTRA flag. Its extra field contains subfield id
RCwhose data is the ASCII magicRCZ1, a little-endianu16member count, and that many little-endianu64file offsets of the members. A reader MAY inflate those slices concurrently. A gzip file without that subfield, including one member and a multi-member file from another writer, MUST still be read in order.gzip -dreads both.- CON-compress.5 :: MAY
A writer MAY split one frame across zstd frames at the same level. A skippable frame (magic
50 2a 4d 18) then precedes them and carries the sameRCZ1index. A decoder MUST ignore an unknown skippable frame. A one-frame zstd file has no index.zstd -dreads both.
Errors¶
Line numbers count from 1. Metadata failures are line 2.
IncompleteSection carries the section name.
A reader that stops at the first error MUST use the lowest line number, so threads cannot change which error is reported.
Class |
When |
|---|---|
|
Line 2 starts with |
|
Line 2 is malformed JSON, a reserved key has the wrong type, or |
|
NaN, Inf, or a spelling of either, any mode. |
|
Column 4 is not a legal integer flag, any mode. |
|
A count field is not an unsigned integer, or a per-type count is 0 when the type count is 1 or more. A type count of 0 is a legal zero-atom frame. |
|
A unit expression is missing, mistyped, or the wrong dimension. A minor of 1 or later with velocities and no |
|
A started frame has too few header lines, other than |
|
A coordinate block is shorter than declared. |
|
A declared section is missing or short. |
|
Column 5 or another field is not a decimal number. |
|
A row has the wrong number of fields, or a reserved arity is not 3 for a vector or 1 for a scalar. An unknown-section row has that many value fields, then a flag, and an optional id. |
|
A section name is not known and cannot be skipped. |
|
Unknown major, or JSON major 0 or 1. |
|
A |
- CON-error.1 :: MUST
Each class in the table MUST be distinguishable by a caller.
- CON-error.2 :: MUST
Reported line numbers MUST count from 1, with metadata on line 2.
- CON-error.3 :: MUST
A count field that is not an unsigned integer, including a sign, a decimal point, or
-1, MUST beInvalidCount. Column 4 MUST beInvalidFixedFlag. Column 5 and every other such field MUST beInvalidNumberFormat.- CON-error.4 :: MUST
A reader that stops at an error MUST report the one with the lowest line number.
Version history¶
Version |
Date |
Change |
|---|---|---|
1 |
original |
eOn text. Column 5 present. Column 4 is 0 or 1. No JSON. |
2 |
2026-03-25 |
JSON line 2, ids, bit masks, declared sections. |
3.0 |
2026-06-27 |
|
3.1 |
2026-10-11 |
Minor 1. |
Normative changes on 2026-10-11, by decision:
Non-finite numbers are rejected in every mode (
D1).A partial last frame is an error. Trailing whitespace is not a frame. A blank line and then only whitespace is not a velocity block (
D2).A section is present exactly when its name is in
sections. Builder clearing is not a format rule (D3).A type count of 0 with empty lines 8 and 9 is a legal zero-atom frame. A zero per-type count when the type count is >= 1 is
InvalidCount. D4 revised after checking eOn 3.6.0 (D4).One blank line before a section, and none between its component blocks (
D5).The scalar energy section is
energies(D6).bondsis specified for major 3 (D7).Column 4 is an integer flag, with spec-1 and spec-2 meanings (
D8).Column 5 is an integer id. Unique ids define ascending pre-grouping order. A repeated id keeps file order (
D9).Velocity units follow the version rules, and the natural spelling is pinned (
D10).Invalid units fail the writer (
D11).Lines 3-4 and
lattice_vectorsfollow the cell convention. Missingpbcis fully periodic (D12).Default float text round-trips binary64. Fixed decimals are opt-in (
D13).Unknown keys are kept. Unknown sections of a newer minor MAY be skipped by
section_arity(D14).The major stays 3.
con_spec_minoris 1. A same-major reader accepts every minor’s version number (D15).Gzip members and zstd frames are normative envelopes (
D16).Line 2 is one JSON line. Trailing space is ignored. Labels collapse spaces (
D17).
con_spec_minor is the minor of that major. ConFrameBuilder stamps con_spec_minor 1 on every spec 3 frame it builds when the caller has not set the key. set_con_spec_minor (Rust, rkr_frame_builder_set_con_spec_minor, and the C++ method of the same name) overrides that value before build. The writer MUST NOT invent or replace con_spec_minor (D15).
The media type chemical/x-con is informative, as is text/plain; charset=utf-8.
CON has no magic bytes. Identify a file by extension and by this header.
Reader compatibility¶
Version 1 is the text of the pre-readcon eOn writer (svn-Dec16_2020 client/Matter.cpp:748).
The eOn 2.17-3.4 column calls readcon.
Cells cite file:line at eOn v3.6.0, v3.4.0, and v2.17.10, ASE 3.29.0, and readcon f09b1af.
Feature |
eOn >= 3.5 |
eOn 2.17-3.4 |
ASE 3.29.0 |
chemfiles |
OVITO 3.16.1 |
readcon f09b1af |
|---|---|---|---|---|---|---|
JSON line 2 |
v3.6.0 |
v3.4.0 |
|
No CON reader ( |
No CON reader. The input list has no CON entry. |
|
Masks 1-6 |
v3.6.0 |
v3.4.0 |
|
No CON reader. |
No CON reader. |
|
Sections |
v3.6.0 |
v3.4.0 |
|
No CON reader. |
No CON reader. |
|
4-column lines |
v3.6.0 |
v3.4.0 |
|
No CON reader. |
No CON reader. |
|
Gzip |
v3.6.0 |
v3.4.0 |
|
No CON reader. |
No CON reader. |
|
Velocities |
v3.6.0 |
v3.4.0 |
|
No CON reader. |
No CON reader. |
|
Examples¶
Version 3.1¶
Two types, lattice_vectors, pbc, masks 0, 3, and 7, ids out of order, velocities with units.time, and forces.
Ids 2, 0, 1 appear in that file order. Mask 3 is x and y. Mask 7 is all three.
- ::
- name:
v31-frame
Generated by readcon v3.1 example {“con_spec_version”:3,”con_spec_minor”:1,”units”:{“length”:”angstrom”,”energy”:”eV”,”mass”:”amu”,”time”:”(amu*angstrom^2/eV)^0.5”},”pbc”:[true,true,false],”lattice_vectors”:[[10.0,0.0,0.0],[0.0,10.0,0.0],[0.0,0.0,20.0]],”sections”:[“velocities”,”forces”]} 10.0 10.0 20.0 90.0 90.0 90.0 0 0 0 0 0 2 2 1 195.084 1.00794 Pt Coordinates of Component 1 0.0 0.0 0.0 0 2 5.0 5.0 0.0 3 0 H Coordinates of Component 2 5.0 5.0 10.0 7 1
Pt Velocities of Component 1 0.01 0.0 0.0 0 2 0.0 0.02 0.0 3 0 H Velocities of Component 2 0.0 0.0 0.03 7 1
Pt Forces of Component 1 0.1 0.0 0.0 0 2 0.0 -0.2 0.0 3 0 H Forces of Component 2 0.0 0.0 0.3 7 1
The same frame as a version 1 reader sees it¶
Spec 1 cannot store masks 3 or 7, JSON, or sections.
The projection below uses column 4 values 0 and 1 only.
Mask 3 and mask 7 both become 1, meaning all-fixed.
Velocities and forces are omitted because a version 1 reader that treats a blank line as the next header cannot return them.
ASE read_eon is that reader.
- ::
- name:
v31-as-v1
Generated by readcon v3.1 example 0.0000 TIME 10.0 10.0 20.0 90.0 90.0 90.0 0 0 0 0 0 2 2 1 195.084 1.00794 Pt Coordinates of Component 1 0.0 0.0 0.0 0 2 5.0 5.0 0.0 1 0 H Coordinates of Component 2 5.0 5.0 10.0 1 1
Zero atoms¶
Nine header lines. Line 7 is 0. Lines 8 and 9 are empty. No coordinate block and no section follow.
- ::
- name:
zero-atom-frame
zero-atom frame {“con_spec_version”:3,”con_spec_minor”:1,”units”:{“length”:”angstrom”,”energy”:”eV”}} 10.0 10.0 10.0 90.0 90.0 90.0
0
Token grammar¶
- CON-token.1 :: MUST
Integer tokens MUST match one or more ASCII digits, with no sign and no decimal point.
- CON-token.2 :: MUST
Float tokens MUST be finite decimals. A leading sign, a leading dot, and an exponent are allowed. Non-finite spellings are
CON-num.1, not floats.- CON-token.3 :: MUST
The separators inside a line MUST be spaces or tabs.
- CON-token.4 :: MUST
The included PEG is informative surface syntax. A reader MUST follow this document when the PEG allows a token these clauses reject.
Appendix: PEG¶
The surface grammar is grammar/readcon.pest.
A bare src include leaves the language empty and does not export, so this include names text.
// CON / convel surface syntax (PEG / Pest).
//
// Aligns with docs/orgmode/spec.org (CON v3.1). This grammar defines the
// *syntactic* shape of one or more concatenated frames. Semantic rules
// (atom counts matching header N_i, fixed-mask legal sets, validate=true
// geometry, section_arity skips) are enforced by src/parser.rs.
// Where this PEG and the specification disagree, the specification wins
// (CON-token.4).
//
// Hot-path I/O does not depend on Pest. gzip and zstd envelopes are not
// grammar (CON-compress): readers detect them by magic bytes.
//
// Section row arities (spec sections):
// vector: velocities, forces, magmoms, displacements, spreads
// -> v0 v1 v2 fixed atom_id
// scalar: energies, charges, spins -> value fixed atom_id
// unknown: a newer minor may skip a block whose data rows have the
// token count declared by section_arity (semantic; the PEG
// accepts the generic block shape).
/// One or more frames. No leading BOM. Trailing whitespace-only lines
/// after the last frame are ignored (CON-file.6, CON-frame.1).
file = { SOI ~ !bom ~ frame+ ~ (ws* ~ NL)* ~ EOI }
bom = { "\u{FEFF}" }
/// Header lines 1-6. The type count chooses a zero-atom tail or typed body.
header_open = {
free_line ~ NL
~ metadata_line ~ NL
~ float3_line
~ float3_line
~ free_line ~ NL
~ free_line ~ NL
}
/// One or more frames. A type count of 0 has no coordinate block (CON-count.1).
frame = { header_open ~ (zero_atom | typed_body) }
/// Free-form line. Does not consume the trailing newline.
free_line = { (!NL ~ ANY)* }
/// Line 2 is one JSON object when it starts with `{`, otherwise legacy text.
metadata_line = { ws* ~ json_object | legacy_metadata }
legacy_metadata = { ws* ~ !"{" ~ free_line }
json_object = {
"{" ~ ws*
~ (json_pair ~ (ws* ~ "," ~ ws* ~ json_pair)*)?
~ ws* ~ "}" ~ ws*
}
json_pair = { json_string ~ ws* ~ ":" ~ ws* ~ json_value }
json_value = {
json_string | json_number | json_object | json_array | "true" | "false" | "null"
}
json_array = {
"[" ~ ws*
~ (json_value ~ (ws* ~ "," ~ ws* ~ json_value)*)?
~ ws* ~ "]"
}
json_string = @{ "\"" ~ json_char* ~ "\"" }
json_char = _{
"\\\"" | "\\\\" | "\\/" | "\\b" | "\\f" | "\\n" | "\\r" | "\\t"
| "\\u" ~ ASCII_HEX_DIGIT{4}
| (!("\"" | "\\") ~ ANY)
}
json_number = @{
"-"? ~ ASCII_DIGIT+
~ ("." ~ ASCII_DIGIT+)?
~ (("e" | "E") ~ ("+" | "-")? ~ ASCII_DIGIT+)?
}
float3_line = { ws* ~ float ~ ws+ ~ float ~ ws+ ~ float ~ ws* ~ NL }
/// Type count >= 1 (CON-count.3). A type count of 0 uses zero_atom.
count_line = { ws* ~ positive_integer ~ ws* ~ NL }
count_list_line = { ws* ~ positive_integer ~ (ws+ ~ positive_integer)* ~ ws* ~ NL }
float_list_line = { ws* ~ float ~ (ws+ ~ float)* ~ ws* ~ NL }
/// "0", "00", ... with no other token. The newline may be absent at EOI.
zero_integer = @{ "0"+ }
zero_count_line = { ws* ~ zero_integer ~ ws* ~ (NL | EOI) }
blank_line = { ws* ~ NL }
/// Whitespace lines 8 and 9, shortened only at end of file (CON-count.4).
zero_atom = {
zero_count_line ~
(
blank_line ~ (blank_line | EOI)
| EOI
)
}
typed_body = {
count_line
~ count_list_line
~ float_list_line
~ type_block+
~ section*
}
/// One chemical-type block: symbol, "Coordinates of Component k", atom lines.
type_block = {
symbol_line ~ NL
~ coord_label ~ NL
~ vector_atom_line ~ (NL ~ vector_atom_line)*
~ NL?
}
symbol_line = { ws* ~ symbol ~ ws* }
/// Element / type symbol (letters, optional trailing digits/underscore).
symbol = @{ ASCII_ALPHA ~ (ASCII_ALPHANUMERIC | "_")* }
/// Labels are case-insensitive. Runs of spaces are `ws+` (CON-file.4).
coord_label = {
ws* ~ ^"Coordinates of Component" ~ ws+ ~ positive_integer ~ ws*
}
/// Coordinate row: v0 v1 v2 fixed_mask [atom_id]. Column 4 and 5 are
/// unsigned integer tokens (no sign, no decimal point).
vector_atom_line = {
ws* ~ float ~ ws+ ~ float ~ ws+ ~ float
~ ws+ ~ integer
~ (ws+ ~ integer)?
~ ws*
}
/// Scalar section row: value fixed_mask atom_id. Identity columns required.
scalar_atom_line = {
ws* ~ float
~ ws+ ~ integer
~ ws+ ~ integer
~ ws*
}
/// Backward-compatible alias used by tests and older notes.
atom_line = { vector_atom_line }
/// Optional section: one blank line, then homogeneous type blocks.
section = {
ws* ~ NL
~ (section_type_block_vector+ | section_type_block_scalar+ | generic_type_block+)
}
section_type_block_vector = {
symbol_line ~ NL
~ section_label_vector ~ NL
~ vector_section_line ~ (NL ~ vector_section_line)*
~ NL?
}
section_type_block_scalar = {
symbol_line ~ NL
~ section_label_scalar ~ NL
~ scalar_atom_line ~ (NL ~ scalar_atom_line)*
~ NL?
}
/// Unknown section shape. The hand parser skips it only for a newer minor
/// whose `section_arity` names the exact token count (CON-section.8).
generic_type_block = {
symbol_line ~ NL
~ generic_label ~ NL
~ token_line ~ (NL ~ token_line)*
~ NL?
}
generic_label = { ws* ~ symbol ~ (ws+ ~ (symbol | positive_integer))* ~ ws* }
token_line = { ws* ~ (float | integer) ~ (ws+ ~ (float | integer))* ~ ws* }
/// Vector section rows require the flag and the id (exact five tokens).
vector_section_line = {
ws* ~ float ~ ws+ ~ float ~ ws+ ~ float
~ ws+ ~ integer
~ ws+ ~ integer
~ ws*
}
section_kind_vector = { ^"Velocities" | ^"Forces" | ^"Magmoms" | ^"Displacements" | ^"Spreads" }
section_kind_scalar = { ^"Energies" | ^"Charges" | ^"Spins" }
/// Union of all section kinds (docs / tests).
section_kind = { section_kind_vector | section_kind_scalar }
section_label_vector = {
ws* ~ section_kind_vector ~ ws+ ~ ^"of Component" ~ ws+ ~ positive_integer ~ ws*
}
section_label_scalar = {
ws* ~ section_kind_scalar ~ ws+ ~ ^"of Component" ~ ws+ ~ positive_integer ~ ws*
}
/// Finite decimal, or a non-finite spelling the semantic layer rejects
/// as NonFiniteValue (CON-num.1, CON-token.2). A leading sign, a leading
/// dot, and an exponent are allowed.
float = _{ finite_float | non_finite }
finite_float = @{
("+" | "-")?
~ (ASCII_DIGIT+ ~ ("." ~ ASCII_DIGIT*)? | "." ~ ASCII_DIGIT+)
~ (("e" | "E") ~ ("+" | "-")? ~ ASCII_DIGIT+)?
}
non_finite = @{
("+" | "-")? ~ (^"infinity" | ^"nan" | ^"inf")
}
/// Unsigned digit token. No sign and no decimal point (CON-token.1).
integer = @{ ASCII_DIGIT+ }
positive_integer = @{ ("1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9") ~ ASCII_DIGIT* }
ws = _{ " " | "\t" }
NL = _{ "\r\n" | "\n" }
References¶
The metadata schema is schema/con-metadata.schema.json.
Unknown keys validate. con_spec_minor and section_arity are reserved.
Samuel T. Chill, Matthew Welborn, Rye Terrell, Liang Zhang, J.-C. Berthet, Andreas Pedersen, Hannes Jónsson, and Graeme Henkelman. EON: software for long time simulations of atomic scale systems. Modelling and Simulation in Materials Science and Engineering, 22(5):055002, 2014. doi:10.1088/0965-0393/22/5/055002.
Rohit Goswami. Reproducible orchestration of best practices for reaction path optimization with the nudged elastic band. MethodsX, 16:103899, 2026. doi:10.1016/j.mex.2026.103899.
Rohit Goswami. Two-dimensional rmsd projections for reaction path visualization and validation. MethodsX, 16:103851, 2026. doi:10.1016/j.mex.2026.103851.
Rohit Goswami, Maxim Masterov, Satish Kamath, Alejandro Peña-Torres, and Hannes Jónsson. Efficient implementation of gaussian process regression accelerated saddle point searches with application to molecular reactions. Journal of Chemical Theory and Computation, 21(16):7935–7943, 2025. doi:10.1021/acs.jctc.5c00866.