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

readcon-core

Surface grammar

grammar/readcon.pest (included in the appendix; not the hot path)

Clause index

docs/orgmode/clauses.tsv, emitted by scripts/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.

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 units.length

2

float

y, in units.length

3

float

z, in units.length

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 InvalidFixedFlag in every mode, including when validate is 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_energies MUST NOT be used as a section name.

CON-section.7 :: MUST

An unknown section name MUST be reported as UnknownSection when 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_arity does not give the value-field count, the reader MUST report UnknownSection.

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 by of Component N.

CON-section.16 :: MUST

A writer of minor 2 or later MUST list in section_arity every section it emits that minor 1 does not reserve.

Name

Label

Row

velocities

Velocities of Component N

vx vy vz flag id

forces

Forces of Component N

fx fy fz flag id

energies

Energies of Component N

energy flag id

charges

Charges of Component N

charge flag id

spins

Spins of Component N

spin flag id

magmoms

Magmoms of Component N

mx my mz flag id

displacements

Displacements of Component N

dx dy dz flag id, units.length

spreads

Spreads of Component N

sx sy sz flag id, units.length, each >= 0

Identity columns repeat the coordinate flag and id. 0 in a spreads row is a classical point.

CON-section.17 :: MAY

When validate is not true, readers MAY ignore an identity-column mismatch after the row has the right number of fields.

CON-section.18 :: SHOULD

The energy metadata value SHOULD equal the sum of the energies rows.

CON-section.19 :: MUST NOT

A mismatch between that sum and energy MUST NOT reject the frame.

CON-section.20 :: MUST

Each spreads value MUST be finite and >= 0.

Validation mode

CON-validate.1 :: MUST

validate true MUST add the checks in CON-validate.4.

CON-validate.2 :: MUST NOT

validate true MUST NOT relax a check that already applies in every mode.

CON-validate.3 :: MUST

When validate is true, sections MUST 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, as ValidationError.

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

bonds MUST NOT appear in sections.

CON-bonds.2 :: MUST

With validate true, a malformed bonds entry MUST be rejected.

CON-bonds.3 :: MUST

With validate false, unknown bonds shapes 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.length and units.energy as non-empty strings of the matching dimension.

CON-units.2 :: MUST

Optional mass, time, velocity, and force strings, when present, MUST have the matching dimension.

CON-units.3 :: MUST

A writer of minor 1 or later MUST write units.time whenever the frame has a velocities section.

CON-units.4 :: MUST NOT

A writer MUST NOT insert time: fs silently 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 units object.

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.length per the natural time unit, and length is angstrom when units.length is absent.

CON-units.9 :: MUST NOT

Any units.time on versions 1, 2, and 3.0 MUST NOT be trusted.

CON-units.10 :: MUST

From minor 1 onward, units.time MUST be authoritative for velocities.

CON-units.11 :: MUST

A frame of minor 1 or later with a velocities section and no units.time MUST be rejected with InvalidUnits.

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.8 through CON-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

validate true MUST NOT be required before a reader applies CON-num.1.

CON-num.3 :: MUST NOT

validate true 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 where CON-error.3 names 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 RC whose data is the ASCII magic RCZ1, a little-endian u16 member count, and that many little-endian u64 file 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 -d reads 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 same RCZ1 index. A decoder MUST ignore an unknown skippable frame. A one-frame zstd file has no index. zstd -d reads 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

MissingSpecVersion

Line 2 starts with { but omits con_spec_version.

InvalidMetadataJson

Line 2 is malformed JSON, a reserved key has the wrong type, or validate true omits sections.

NonFiniteValue

NaN, Inf, or a spelling of either, any mode.

InvalidFixedFlag

Column 4 is not a legal integer flag, any mode.

InvalidCount

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.

InvalidUnits

A unit expression is missing, mistyped, or the wrong dimension. A minor of 1 or later with velocities and no units.time is this class on read and on write.

IncompleteHeader

A started frame has too few header lines, other than CON-count.4.

IncompleteFrame

A coordinate block is shorter than declared.

IncompleteSection(name)

A declared section is missing or short.

InvalidNumberFormat

Column 5 or another field is not a decimal number.

InvalidVectorLength

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.

UnknownSection

A section name is not known and cannot be skipped.

UnsupportedVersion

Unknown major, or JSON major 0 or 1.

ValidationError

A validate true check failed. It MUST NOT relax NonFiniteValue or InvalidFixedFlag. A legal zero-atom frame is accepted.

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 be InvalidCount. Column 4 MUST be InvalidFixedFlag. Column 5 and every other such field MUST be InvalidNumberFormat.

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

units.length and units.energy MUST be present. Minor absent.

3.1

2026-10-11

Minor 1. units.time when velocities are present. Natural-unit rule.

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).

  • bonds is 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_vectors follow the cell convention. Missing pbc is 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_minor is 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 ase/io/eon.py

chemfiles

OVITO 3.16.1

readcon f09b1af

JSON line 2

v3.6.0 client/ConFileIO.cpp:586 read_all_frames, :463 frame_from_matter.

v3.4.0 client/ConFileIO.cpp:573. v2.17.10 client/ConFileIO.cpp:294.

:72 stores line 2 as text. :255 writes preBox_header_2.

No CON reader (src/formats).

No CON reader. The input list has no CON entry.

src/parser.rs:458.

Masks 1-6

v3.6.0 client/ConFileIO.cpp:386 getFixedMask, :714 setFixedMask.

v3.4.0 client/ConFileIO.cpp:386 and :701. v2.17.10 :144-146 writes one boolean on all axes and :384-385 collapses any fixed bit to 1.

:139 bool(int(tokens[3])). Writer emits 0 or 1.

No CON reader.

No CON reader.

src/types.rs:644. Outside 0-7 is not InvalidFixedFlag unless validate is true.

Sections

v3.6.0 client/ConFileIO.cpp:422-424 leaves forces off.

v3.4.0 client/ConFileIO.cpp:422. v2.17.10 has velocities only (:174).

:177 reads the next line as a header, so a section blank does not parse.

No CON reader.

No CON reader.

src/parser.rs:1100.

4-column lines

v3.6.0 client/ConFileIO.cpp:586 via readcon.

v3.4.0 client/ConFileIO.cpp:573. v2.17.10 client/ConFileIO.cpp:294.

:138-139 reads xyz and column 4, not column 5.

No CON reader.

No CON reader.

src/parser.rs:665 defaults column 5 to the 0-based index.

Gzip

v3.6.0 client/ConFileIO.cpp:577-578 one gzip member.

v3.4.0 client/ConFileIO.cpp:564-565. v2.17.10 :118 compression_from_extension.

:177 reads text lines. No gzip decoder in this module.

No CON reader.

No CON reader.

src/compression.rs:85 GzDecoder reads the first member.

Velocities

v3.6.0 client/ConFileIO.cpp:43 precision 6, :444 set_atom_velocity, include/eon/ParametersOptions.h:26 timeUnit 10.1805055 fs.

v3.4.0 client/ConFileIO.cpp:43 and :431, same ParametersOptions.h:26. v2.17.10 client/ConFileIO.cpp:174.

:303 writes xyz, flag, and id. No velocity block.

No CON reader.

No CON reader.

src/parser.rs:1117 parses the numbers and does not apply units.time. src/writer.rs:269 can still insert time: fs.

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.

[CWT+14]

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.

[Gos26a]

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.

[Gos26b]

Rohit Goswami. Two-dimensional rmsd projections for reaction path visualization and validation. MethodsX, 16:103851, 2026. doi:10.1016/j.mex.2026.103851.

[GMK+25]

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.