Skip to main content

readcon_core/
parser.rs

1use crate::error::ParseError;
2use crate::helpers::symbol_to_atomic_number;
3use crate::types::{
4    AtomDatum, ConFrame, FrameHeader, PreboxHeader, SECTION_CHARGES, SECTION_DISPLACEMENTS,
5    SECTION_ENERGIES, SECTION_FORCES, SECTION_MAGMOMS, SECTION_SPINS, SECTION_SPREADS,
6    SECTION_VELOCITIES, meta,
7};
8use serde_json::Value;
9use std::iter::Peekable;
10use std::sync::Arc;
11use std::sync::atomic::{AtomicUsize, Ordering};
12
13/// Line source with peek for section detection (blank-line separators).
14///
15/// Implemented by the memchr cursor on the hot iterator path and by
16/// `Peekable<I>` for tests / ad-hoc callers.
17/// Rows of one coordinate block, in file order.
18///
19/// `atoms` is empty unless the caller asked for per-atom shells. The
20/// numeric columns are the bytes a serial `next_coord_row` loop would
21/// have stored.
22#[doc(hidden)]
23pub struct CoordRows {
24    pub xyz: Vec<f64>,
25    pub ids: Vec<u64>,
26    pub flags: Vec<[bool; 3]>,
27    pub atoms: Vec<crate::types::AtomDatum>,
28    pub consumed: usize,
29}
30
31/// Worker count for a coordinate block that is too wide to hand to one task.
32///
33/// One means the calling thread parses the block. The frame iterator sets
34/// this only for a single wide frame, then puts it back.
35pub(crate) fn wide_workers() -> usize {
36    WIDE_WORKERS.with(|slot| slot.get())
37}
38
39pub(crate) fn set_wide_workers(n: usize) {
40    WIDE_WORKERS.with(|slot| slot.set(n.max(1)));
41}
42
43std::thread_local! {
44    static WIDE_WORKERS: std::cell::Cell<usize> = const { std::cell::Cell::new(1) };
45}
46
47/// Fill `n` coordinate rows.
48///
49/// `breaks[i]` is the absolute index of that row's `\n`. Row 0 begins at
50/// `row0`. `xyz` receives `n * 3` values. `ids` and `flags` may be null
51/// when the caller does not want them. `flags` is the packed column-4 mask.
52#[cfg(feature = "parallel")]
53pub(crate) fn fill_rows_from_breaks(
54    bytes: &[u8],
55    breaks: &[usize],
56    row0: usize,
57    spec_version: u32,
58    start_id: u64,
59    workers: usize,
60    xyz: *mut f64,
61    ids: *mut u64,
62    flags: *mut u8,
63) -> Result<(), ParseError> {
64    let n = breaks.len();
65    if n == 0 {
66        return Ok(());
67    }
68    let chunk = n.div_ceil(workers.max(1)).max(1);
69    let groups = n.div_ceil(chunk);
70    let xyz_ptr = xyz as usize;
71    let ids_ptr = ids as usize;
72    let flags_ptr = flags as usize;
73    let fill = || {
74        use rayon::prelude::*;
75        (0..groups).into_par_iter().try_for_each(|group| {
76            let first = group * chunk;
77            let last = (first + chunk).min(n);
78            for row_index in first..last {
79                let start = if row_index == 0 {
80                    row0
81                } else {
82                    breaks[row_index - 1] + 1
83                };
84                let end = breaks[row_index] + 1;
85                if end > bytes.len() || start > end {
86                    return Err(ParseError::IncompleteFrame);
87                }
88                let default_id = start_id + row_index as u64;
89                let ((row, fixed, atom_id), _next) =
90                    parse_coord_row_at(&bytes[start..end], 0, spec_version, default_id)?;
91                unsafe {
92                    std::ptr::copy_nonoverlapping(
93                        row.as_ptr(),
94                        (xyz_ptr as *mut f64).add(row_index * 3),
95                        3,
96                    );
97                    if ids_ptr != 0 {
98                        *((ids_ptr as *mut u64).add(row_index)) = atom_id;
99                    }
100                    if flags_ptr != 0 {
101                        let mask = u8::from(fixed[0])
102                            | (u8::from(fixed[1]) << 1)
103                            | (u8::from(fixed[2]) << 2);
104                        *((flags_ptr as *mut u8).add(row_index)) = mask;
105                    }
106                }
107            }
108            Ok(())
109        })
110    };
111    on_pool(workers, fill)
112}
113
114/// Run `body` on a pool of `workers` threads.
115///
116/// The pool for a given size is kept for the process. Building one per
117/// call was a serial pause on the wide-frame read and the row formatter.
118#[cfg(feature = "parallel")]
119pub(crate) fn on_pool<T: Send>(workers: usize, body: impl FnOnce() -> T + Send) -> T {
120    if workers < 2 {
121        return body();
122    }
123    // The cached pool is leaked for the process. Miri rejects a thread
124    // that is still running when the test binary exits, so it builds a
125    // pool, runs `body`, and joins.
126    #[cfg(miri)]
127    {
128        return match rayon::ThreadPoolBuilder::new().num_threads(workers).build() {
129            Ok(pool) => pool.install(body),
130            Err(_) => body(),
131        };
132    }
133    #[cfg(not(miri))]
134    {
135        let pool = {
136            use std::sync::{Mutex, OnceLock};
137            static POOLS: OnceLock<Mutex<Vec<(usize, &'static rayon::ThreadPool)>>> =
138                OnceLock::new();
139            let pools = POOLS.get_or_init(|| Mutex::new(Vec::new()));
140            let mut guard = pools.lock().unwrap_or_else(|err| err.into_inner());
141            if let Some((_, pool)) = guard.iter().find(|(size, _)| *size == workers) {
142                *pool
143            } else {
144                let next_core = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
145                let built = match rayon::ThreadPoolBuilder::new()
146                    .num_threads(workers)
147                    .spawn_handler(move |thread| {
148                        // One worker per physical core. Leaving the placement to
149                        // the kernel put two of these on one core and left
150                        // another idle, which is the whole 8-thread gap.
151                        let core = next_core.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
152                        std::thread::Builder::new().spawn(move || {
153                            pin_worker(core);
154                            thread.run();
155                        })?;
156                        Ok(())
157                    })
158                    .build()
159                {
160                    Ok(pool) => pool,
161                    Err(_) => return body(),
162                };
163                let pool: &'static rayon::ThreadPool = Box::leak(Box::new(built));
164                guard.push((workers, pool));
165                pool
166            }
167        };
168        pool.install(body)
169    }
170}
171
172pub(crate) fn pin_worker(core: usize) {
173    // `sched_setaffinity` is Linux. Pinning is a performance hint.
174    #[cfg(all(not(miri), target_os = "linux"))]
175    unsafe {
176        let mut set: libc::cpu_set_t = std::mem::zeroed();
177        libc::CPU_ZERO(&mut set);
178        libc::CPU_SET(core, &mut set);
179        libc::sched_setaffinity(0, std::mem::size_of::<libc::cpu_set_t>(), &set);
180    }
181    #[cfg(any(miri, not(target_os = "linux")))]
182    {
183        let _ = core;
184    }
185}
186
187/// Coordinate rows in `bytes`, which begins at the first row.
188///
189/// `n` rows are required. The returned `consumed` count is the number of
190/// bytes those rows occupy, including their newlines. `symbol` builds the
191/// per-atom shells; `None` leaves `atoms` empty. A structural miss returns
192/// `Err` and the caller keeps the serial loop.
193#[cfg(feature = "parallel")]
194pub(crate) fn parallel_coord_rows(
195    bytes: &[u8],
196    n: usize,
197    spec_version: u32,
198    start_id: u64,
199    workers: usize,
200    symbol: Option<&std::sync::Arc<str>>,
201) -> Result<CoordRows, ParseError> {
202    if n == 0 {
203        return Ok(CoordRows {
204            xyz: Vec::new(),
205            ids: Vec::new(),
206            flags: Vec::new(),
207            atoms: Vec::new(),
208            consumed: 0,
209        });
210    }
211    // Same chunking as the column reader: count newlines, then each worker
212    // walks its own run. An offset per line was a serial pass the plain
213    // read does not pay.
214    let (chunks, consumed) = plan_coord_chunks(bytes, 0, n, workers.max(1))?;
215    let mut xyz = Vec::<f64>::with_capacity(n.saturating_mul(3));
216    let mut ids = Vec::<u64>::with_capacity(n);
217    let mut flags = Vec::<[bool; 3]>::with_capacity(n);
218    let mut atoms_raw: Vec<std::mem::MaybeUninit<crate::types::AtomDatum>> = Vec::new();
219    if symbol.is_some() {
220        atoms_raw = Vec::with_capacity(n);
221        unsafe { atoms_raw.set_len(n) };
222    }
223    let xyz_ptr = xyz.as_mut_ptr() as usize;
224    let ids_ptr = ids.as_mut_ptr() as usize;
225    let flags_ptr = flags.as_mut_ptr() as usize;
226    let atoms_ptr = atoms_raw.as_mut_ptr() as usize;
227    let mut row0 = Vec::with_capacity(chunks.len());
228    let mut acc = 0usize;
229    for (_, nrows) in &chunks {
230        row0.push(acc);
231        acc += *nrows;
232    }
233    let fill_chunk = |index: usize| -> Result<(), ParseError> {
234        let (start, nrows) = chunks[index];
235        let mut row = row0[index];
236        let mut pos = start;
237        let mut shares = symbol.map(|symbol| symbol_shares(symbol, nrows));
238        for _ in 0..nrows {
239            let ((xyz, fixed, atom_id), next) =
240                parse_coord_row_at(bytes, pos, spec_version, start_id + row as u64)?;
241            unsafe {
242                std::ptr::copy_nonoverlapping(xyz.as_ptr(), (xyz_ptr as *mut f64).add(row * 3), 3);
243                *((ids_ptr as *mut u64).add(row)) = atom_id;
244                *((flags_ptr as *mut [bool; 3]).add(row)) = fixed;
245                if let Some(shares) = shares.as_mut() {
246                    let slot = (xyz_ptr as *mut f64).add(row * 3);
247                    let atom =
248                        crate::types::AtomDatum::at_slot(shares.take(), slot, fixed, atom_id);
249                    (*(atoms_ptr as *mut std::mem::MaybeUninit<crate::types::AtomDatum>).add(row))
250                        .write(atom);
251                }
252            }
253            pos = next;
254            row += 1;
255        }
256        Ok(())
257    };
258    let built = if workers < 2 || chunks.len() < 2 {
259        (0..chunks.len()).try_for_each(fill_chunk)
260    } else {
261        on_pool(workers, || {
262            use rayon::prelude::*;
263            (0..chunks.len()).into_par_iter().try_for_each(fill_chunk)
264        })
265    };
266    if let Err(err) = built {
267        std::mem::forget(atoms_raw);
268        return Err(err);
269    }
270    // SAFETY: every row was written before `built` returned Ok. The
271    // length stays 0 on the error path above.
272    unsafe {
273        xyz.set_len(n * 3);
274        ids.set_len(n);
275        flags.set_len(n);
276    }
277    let atoms = if symbol.is_some() {
278        let mut raw = std::mem::ManuallyDrop::new(atoms_raw);
279        unsafe {
280            Vec::from_raw_parts(
281                raw.as_mut_ptr() as *mut crate::types::AtomDatum,
282                n,
283                raw.capacity(),
284            )
285        }
286    } else {
287        Vec::new()
288    };
289    Ok(CoordRows {
290        xyz,
291        ids,
292        flags,
293        atoms,
294        consumed,
295    })
296}
297
298/// Walk `nrows` coordinate lines starting at byte `start`.
299///
300/// `row_base` is the first row's index in `xyz` / `ids` / `flags` / `atoms`.
301/// This is the per-member kernel of [`fill_rows_from_chunks`], so a worker
302/// can parse a slice as soon as that slice has been inflated.
303#[cfg(feature = "parallel")]
304pub(crate) fn parse_coord_run(
305    bytes: &[u8],
306    start: usize,
307    nrows: usize,
308    spec_version: u32,
309    row_base: usize,
310    symbol: Option<&std::sync::Arc<str>>,
311    xyz: *mut f64,
312    ids: *mut u64,
313    flags: *mut [bool; 3],
314    atoms: *mut std::mem::MaybeUninit<crate::types::AtomDatum>,
315) -> Result<usize, ParseError> {
316    let mut pos = start;
317    let mut shares = symbol.map(|symbol| symbol_shares(symbol, nrows));
318    for step in 0..nrows {
319        let row = row_base + step;
320        let ((xyz_row, fixed, atom_id), next) =
321            parse_coord_row_at(bytes, pos, spec_version, row as u64)?;
322        unsafe {
323            let dest = xyz.add(row * 3);
324            std::ptr::copy_nonoverlapping(xyz_row.as_ptr(), dest, 3);
325            *ids.add(row) = atom_id;
326            *flags.add(row) = fixed;
327            if let Some(shares) = shares.as_mut() {
328                let atom = crate::types::AtomDatum::at_slot(shares.take(), dest, fixed, atom_id);
329                (*atoms.add(row)).write(atom);
330            }
331        }
332        pos = next;
333    }
334    Ok(pos)
335}
336
337#[cfg(feature = "parallel")]
338#[allow(dead_code)]
339fn coord_line_ranges(
340    bytes: &[u8],
341    n: usize,
342    workers: usize,
343) -> Result<Vec<(usize, usize)>, ParseError> {
344    let newlines = newline_index(bytes, workers);
345    let mut ranges = Vec::with_capacity(n);
346    let mut start = 0usize;
347    for index in 0..n {
348        if start > bytes.len() {
349            return Err(ParseError::IncompleteFrame);
350        }
351        let end = if index < newlines.len() {
352            newlines[index] + 1
353        } else if index == newlines.len() && start < bytes.len() {
354            bytes.len()
355        } else {
356            return Err(ParseError::IncompleteFrame);
357        };
358        if end < start {
359            return Err(ParseError::IncompleteFrame);
360        }
361        ranges.push((start, end));
362        start = end;
363    }
364    Ok(ranges)
365}
366
367/// Newline positions in `bytes`.
368///
369/// Chunks are cut on byte boundaries, then each interior cut that lands
370/// inside a line is moved to the next newline so a row is not split.
371/// Workers count those newlines, a prefix sum places each run, and the
372/// same workers write the offsets. The offset array is not zeroed, so
373/// the writer is the first touch. `workers < 2` scans on the calling thread.
374#[cfg(feature = "parallel")]
375pub(crate) fn newline_index(bytes: &[u8], workers: usize) -> Vec<usize> {
376    newline_index_at(bytes, 0, workers)
377}
378
379/// [`newline_index`] with `base` added to every stored offset.
380#[cfg(feature = "parallel")]
381pub(crate) fn newline_index_at(bytes: &[u8], base: usize, workers: usize) -> Vec<usize> {
382    if bytes.is_empty() || workers < 2 || bytes.len() < (1 << 20) {
383        return memchr::memchr_iter(b'\n', bytes)
384            .map(|index| base + index)
385            .collect();
386    }
387    let cuts = newline_cuts(bytes, workers);
388    newline_index_exact(&cuts, bytes, base)
389}
390
391/// One cache line, so adjacent chunk counters do not share a line.
392#[cfg(feature = "parallel")]
393#[derive(Clone)]
394#[repr(C, align(64))]
395struct ChunkTally {
396    n: usize,
397}
398
399#[cfg(feature = "parallel")]
400pub(crate) fn newline_cuts(bytes: &[u8], workers: usize) -> Vec<usize> {
401    let workers = workers.min(bytes.len()).max(1);
402    let mut cuts = Vec::with_capacity(workers + 1);
403    cuts.push(0usize);
404    for index in 1..workers {
405        let mut at = index * bytes.len() / workers;
406        // A cut in the middle of a row belongs to the chunk that holds
407        // the newline. Move it to the first byte after that newline.
408        if at > 0 && at < bytes.len() && bytes[at - 1] != b'\n' {
409            if let Some(rel) = memchr::memchr(b'\n', &bytes[at..]) {
410                at += rel + 1;
411            } else {
412                at = bytes.len();
413            }
414        }
415        if cuts.last().copied() != Some(at) {
416            cuts.push(at);
417        }
418    }
419    if cuts.last().copied() != Some(bytes.len()) {
420        cuts.push(bytes.len());
421    }
422    cuts
423}
424
425/// Count newlines in each `cuts` window. One store per chunk, so the
426/// counters do not bounce a cache line during the scan.
427#[cfg(feature = "parallel")]
428fn count_newline_chunks(bytes: &[u8], cuts: &[usize]) -> Vec<usize> {
429    let nchunks = cuts.len().saturating_sub(1);
430    let mut tallies = vec![ChunkTally { n: 0 }; nchunks];
431    if nchunks == 0 {
432        return Vec::new();
433    }
434    let ptr = tallies.as_mut_ptr() as usize;
435    let count = || {
436        use rayon::prelude::*;
437        (0..nchunks).into_par_iter().for_each(|index| {
438            let n = memchr::memchr_iter(b'\n', &bytes[cuts[index]..cuts[index + 1]]).count();
439            unsafe {
440                (*(ptr as *mut ChunkTally).add(index)).n = n;
441            }
442        });
443    };
444    if nchunks < 2 {
445        count();
446    } else {
447        on_pool(nchunks, count);
448    }
449    tallies.into_iter().map(|tally| tally.n).collect()
450}
451
452/// Byte start and row count for each worker that parses `n_rows`
453/// coordinate lines beginning at `start`.
454///
455/// The newline *count* places the rows. Workers then parse their own
456/// slice in order, so the read does not materialise an offset per line.
457/// The returned end is the first byte after the `n_rows`-th newline.
458#[cfg(feature = "parallel")]
459pub(crate) fn plan_coord_chunks(
460    bytes: &[u8],
461    start: usize,
462    n_rows: usize,
463    workers: usize,
464) -> Result<(Vec<(usize, usize)>, usize), ParseError> {
465    if n_rows == 0 {
466        return Ok((Vec::new(), start));
467    }
468    if start >= bytes.len() {
469        return Err(ParseError::IncompleteFrame);
470    }
471    let mut window = n_rows.saturating_mul(96).max(1);
472    loop {
473        let end = start.saturating_add(window).min(bytes.len());
474        let region = &bytes[start..end];
475        let cuts = newline_cuts(region, workers);
476        let counts = count_newline_chunks(region, &cuts);
477        let total: usize = counts.iter().sum();
478        if total >= n_rows || end == bytes.len() {
479            if total < n_rows {
480                return Err(ParseError::IncompleteFrame);
481            }
482            return chunks_from_counts(bytes, start, &cuts, &counts, n_rows);
483        }
484        window = window.saturating_mul(2);
485    }
486}
487
488#[cfg(feature = "parallel")]
489fn chunks_from_counts(
490    bytes: &[u8],
491    start: usize,
492    cuts: &[usize],
493    counts: &[usize],
494    n_rows: usize,
495) -> Result<(Vec<(usize, usize)>, usize), ParseError> {
496    let mut need = n_rows;
497    let mut chunks = Vec::new();
498    let mut end_abs = start;
499    for index in 0..counts.len() {
500        if need == 0 {
501            break;
502        }
503        let have = counts[index];
504        if have == 0 {
505            continue;
506        }
507        let from = start + cuts[index];
508        let to = start + cuts[index + 1];
509        let take = have.min(need);
510        let chunk_end = if take == have && to > from && bytes[to - 1] == b'\n' {
511            to
512        } else {
513            let mut seen = 0usize;
514            let mut found = None;
515            for rel in memchr::memchr_iter(b'\n', &bytes[from..to]) {
516                seen += 1;
517                if seen == take {
518                    found = Some(from + rel + 1);
519                    break;
520                }
521            }
522            found.ok_or(ParseError::IncompleteFrame)?
523        };
524        chunks.push((from, take));
525        end_abs = chunk_end;
526        need -= take;
527    }
528    if need != 0 {
529        return Err(ParseError::IncompleteFrame);
530    }
531    Ok((chunks, end_abs))
532}
533
534/// Parse coordinate rows described by [`plan_coord_chunks`].
535///
536/// Each chunk is a contiguous run of lines. The worker walks that run
537/// and writes `nrows` coordinates at the prefix-summed row.
538#[cfg(feature = "parallel")]
539pub(crate) fn fill_rows_from_chunks(
540    bytes: &[u8],
541    chunks: &[(usize, usize)],
542    spec_version: u32,
543    start_id: u64,
544    workers: usize,
545    xyz: *mut f64,
546    ids: *mut u64,
547    flags: *mut u8,
548) -> Result<(), ParseError> {
549    if chunks.is_empty() {
550        return Ok(());
551    }
552    let mut row0 = Vec::with_capacity(chunks.len());
553    let mut acc = 0usize;
554    for (_, nrows) in chunks {
555        row0.push(acc);
556        acc += *nrows;
557    }
558    let xyz_ptr = xyz as usize;
559    let ids_ptr = ids as usize;
560    let flags_ptr = flags as usize;
561    let fill = || {
562        use rayon::prelude::*;
563        chunks
564            .par_iter()
565            .zip(row0.par_iter().copied())
566            .try_for_each(|(&(start, nrows), mut row)| {
567                let mut pos = start;
568                for _ in 0..nrows {
569                    let ((xyz, fixed, atom_id), next) =
570                        parse_coord_row_at(bytes, pos, spec_version, start_id + row as u64)?;
571                    unsafe {
572                        std::ptr::copy_nonoverlapping(
573                            xyz.as_ptr(),
574                            (xyz_ptr as *mut f64).add(row * 3),
575                            3,
576                        );
577                        if ids_ptr != 0 {
578                            *((ids_ptr as *mut u64).add(row)) = atom_id;
579                        }
580                        if flags_ptr != 0 {
581                            let mask = u8::from(fixed[0])
582                                | (u8::from(fixed[1]) << 1)
583                                | (u8::from(fixed[2]) << 2);
584                            *((flags_ptr as *mut u8).add(row)) = mask;
585                        }
586                    }
587                    pos = next;
588                    row += 1;
589                }
590                Ok(())
591            })
592    };
593    if workers < 2 {
594        let mut row_at = 0usize;
595        for &(start, nrows) in chunks {
596            let mut pos = start;
597            for _ in 0..nrows {
598                let ((row_xyz, fixed, atom_id), next) =
599                    parse_coord_row_at(bytes, pos, spec_version, start_id + row_at as u64)?;
600                unsafe {
601                    std::ptr::copy_nonoverlapping(row_xyz.as_ptr(), xyz.add(row_at * 3), 3);
602                    if ids_ptr != 0 {
603                        *((ids_ptr as *mut u64).add(row_at)) = atom_id;
604                    }
605                    if flags_ptr != 0 {
606                        let mask = u8::from(fixed[0])
607                            | (u8::from(fixed[1]) << 1)
608                            | (u8::from(fixed[2]) << 2);
609                        *((flags_ptr as *mut u8).add(row_at)) = mask;
610                    }
611                }
612                pos = next;
613                row_at += 1;
614            }
615        }
616        Ok(())
617    } else if chunks.len() < 2 {
618        fill()
619    } else {
620        on_pool(workers, fill)
621    }
622}
623
624/// Exact index: count, prefix sum, then store into an unzeroed buffer.
625#[cfg(feature = "parallel")]
626fn newline_index_exact(cuts: &[usize], bytes: &[u8], base: usize) -> Vec<usize> {
627    let nchunks = cuts.len() - 1;
628    let counts = count_newline_chunks(bytes, cuts);
629    let mut slots = vec![0usize; nchunks];
630    let mut total = 0usize;
631    for index in 0..nchunks {
632        slots[index] = total;
633        total += counts[index];
634    }
635    let mut out = Vec::<usize>::with_capacity(total);
636    let ptr = out.as_mut_ptr() as usize;
637    let store = || {
638        use rayon::prelude::*;
639        (0..nchunks).into_par_iter().for_each(|index| {
640            let from = cuts[index];
641            let mut at = slots[index];
642            for rel in memchr::memchr_iter(b'\n', &bytes[from..cuts[index + 1]]) {
643                unsafe {
644                    *((ptr as *mut usize).add(at)) = base + from + rel;
645                }
646                at += 1;
647            }
648        });
649    };
650    if nchunks < 2 {
651        store();
652    } else {
653        on_pool(nchunks.max(1), store);
654    }
655    // SAFETY: the store wrote every index in `0..total`.
656    unsafe { out.set_len(total) };
657    out
658}
659
660#[cfg(feature = "parallel")]
661#[allow(dead_code)]
662fn write_coord_group(
663    bytes: &[u8],
664    group: &[(usize, usize)],
665    row0: usize,
666    spec_version: u32,
667    start_id: u64,
668    symbol: Option<&std::sync::Arc<str>>,
669    xyz_ptr: usize,
670    ids_ptr: usize,
671    flags_ptr: usize,
672    atoms_ptr: usize,
673) -> Result<(), ParseError> {
674    let mut shares = symbol.map(|symbol| symbol_shares(symbol, group.len()));
675    for (offset, &(start, end)) in group.iter().enumerate() {
676        let row_index = row0 + offset;
677        let default_id = start_id + row_index as u64;
678        let ((row, fixed, atom_id), _next) =
679            parse_coord_row_at(&bytes[start..end], 0, spec_version, default_id)?;
680        unsafe {
681            std::ptr::copy_nonoverlapping(
682                row.as_ptr(),
683                (xyz_ptr as *mut f64).add(row_index * 3),
684                3,
685            );
686            *((ids_ptr as *mut u64).add(row_index)) = atom_id;
687            *((flags_ptr as *mut [bool; 3]).add(row_index)) = fixed;
688            if let Some(shares) = shares.as_mut() {
689                let slot = (xyz_ptr as *mut f64).add(row_index * 3);
690                let atom = crate::types::AtomDatum::at_slot(shares.take(), slot, fixed, atom_id);
691                (*(atoms_ptr as *mut std::mem::MaybeUninit<crate::types::AtomDatum>)
692                    .add(row_index))
693                .write(atom);
694            }
695        }
696    }
697    Ok(())
698}
699
700pub trait LineStream<'a> {
701    fn next_line(&mut self) -> Option<&'a str>;
702    fn peek_line(&mut self) -> Option<&'a str>;
703    /// Take `n` coordinate rows starting at the cursor, or `None` to keep
704    /// the one-row loop. The cursor moves only when this returns `Some`.
705    fn try_take_coord_block(
706        &mut self,
707        _n: usize,
708        _spec_version: u32,
709        _start_id: u64,
710        _symbol: &std::sync::Arc<str>,
711        _workers: usize,
712    ) -> Option<CoordRows> {
713        None
714    }
715    /// True when every remaining line, including the current peek, is
716    /// empty or whitespace. Default is false so a one-line peek cannot
717    /// hide a following section.
718    fn remainder_is_whitespace(&mut self) -> bool {
719        false
720    }
721    /// Called while a blank line is peeked. True when that blank begins a
722    /// section: the next line is a symbol and the line after it is a
723    /// component label. A blank that does not is line 1 of the next frame.
724    fn blank_line_opens_section(&mut self) -> bool {
725        false
726    }
727
728    /// With a blank line peeked, true when [`Self::blank_line_opens_section`]
729    /// is true. A stream that cannot look ahead keeps the legacy rule and
730    /// returns true.
731    fn blank_opens_velocity_block(&mut self) -> bool {
732        true
733    }
734
735    /// One coordinate row, fused with the line scan when the stream can do it.
736    ///
737    /// The default pulls a `&str` line. [`crate::iterators::MemchrLines`]
738    /// parses the row directly from the byte cursor so tokenize and numeric
739    /// parse are one pass.
740    fn next_coord_row(
741        &mut self,
742        spec_version: u32,
743        default_id: u64,
744    ) -> Result<([f64; 3], [bool; 3], u64), ParseError> {
745        let line = self.next_line().ok_or(ParseError::IncompleteFrame)?;
746        parse_coord_row(line, spec_version, default_id)
747    }
748
749    /// One vector-section row (xyz, flag, required id), fused with the line
750    /// scan when the stream can do it. End of input is [`ParseError::IncompleteFrame`];
751    /// callers that are inside a named section map that to `IncompleteSection`.
752    fn next_vector_row(
753        &mut self,
754        spec_version: u32,
755    ) -> Result<([f64; 3], [bool; 3], u64), ParseError> {
756        let line = self.next_line().ok_or(ParseError::IncompleteFrame)?;
757        parse_vector_section_row(line, spec_version)
758    }
759}
760
761fn take_vector_row<'a>(
762    lines: &mut impl LineStream<'a>,
763    spec_version: u32,
764    section: &str,
765) -> Result<([f64; 3], [bool; 3], u64), ParseError> {
766    match lines.next_vector_row(spec_version) {
767        Ok(row) => Ok(row),
768        Err(ParseError::IncompleteFrame) => Err(ParseError::IncompleteSection(section.to_string())),
769        Err(err) => Err(err),
770    }
771}
772
773impl<'a, I> LineStream<'a> for Peekable<I>
774where
775    I: Iterator<Item = &'a str> + Clone,
776{
777    #[inline]
778    fn next_line(&mut self) -> Option<&'a str> {
779        Iterator::next(self)
780    }
781    #[inline]
782    fn peek_line(&mut self) -> Option<&'a str> {
783        Peekable::peek(self).copied()
784    }
785    fn blank_line_opens_section(&mut self) -> bool {
786        let mut probe = self.clone();
787        let Some(blank) = probe.next_line() else {
788            return false;
789        };
790        if !blank.trim().is_empty() {
791            return false;
792        }
793        section_follows(&mut probe)
794    }
795
796    fn blank_opens_velocity_block(&mut self) -> bool {
797        match self.peek_line() {
798            Some(line) if line.trim().is_empty() => self.blank_line_opens_section(),
799            _ => true,
800        }
801    }
802}
803
804/// True when `line` has the words `of` and `Component` in that order.
805pub(crate) fn line_has_component_label(line: &str) -> bool {
806    let mut words = line.split_ascii_whitespace();
807    while let Some(word) = words.next() {
808        if word.eq_ignore_ascii_case("of")
809            && words
810                .next()
811                .is_some_and(|next| next.eq_ignore_ascii_case("component"))
812        {
813            return true;
814        }
815    }
816    false
817}
818
819fn section_follows<'a>(lines: &mut impl LineStream<'a>) -> bool {
820    let Some(symbol) = lines.next_line() else {
821        return false;
822    };
823    if symbol.trim().is_empty() || symbol.trim_start().starts_with('{') {
824        return false;
825    }
826    let Some(label) = lines.next_line() else {
827        return false;
828    };
829    line_has_component_label(label)
830}
831
832/// Length of the stack buffer of [`parse_line_of_range_f64_stack`]: the most
833/// columns an atom line has, which are x, y, z, the flag and the optional id
834/// (spec "Coordinates").
835pub const NUMERIC_STACK_WIDTH: usize = COORD_ROW_MIN_COLUMNS + 1;
836
837/// Hot-path: parse up to [`NUMERIC_STACK_WIDTH`] whitespace-separated f64s
838/// into a stack buffer.
839/// Returns count of tokens actually present (before padding).
840/// Pads `out[found..max]` from `defaults` when `found < max` and `found >= min`.
841///
842/// Single-pass over the line bytes: skip ASCII whitespace, then
843/// [`fast_float2::parse_partial`] (Eisel–Lemire / SIMD-class decimal kernel)
844/// with a token-boundary check. No `SplitWhitespace`, no per-token `&str`,
845/// no heap `Vec`. Prefer this over allocating [`parse_line_of_n_f64`] on atom lines.
846#[inline]
847pub fn parse_line_of_range_f64_stack(
848    line: &str,
849    min: usize,
850    max: usize,
851    defaults: &[f64],
852    out: &mut [f64; NUMERIC_STACK_WIDTH],
853) -> Result<usize, ParseError> {
854    debug_assert!(max <= NUMERIC_STACK_WIDTH && min <= max && defaults.len() >= max);
855    let bytes = line.as_bytes();
856    let n = bytes.len();
857    let mut i = 0usize;
858    let mut found = 0usize;
859    while found < max {
860        while i < n && bytes[i].is_ascii_whitespace() {
861            i += 1;
862        }
863        if i >= n {
864            break;
865        }
866        let end = bytes[i..]
867            .iter()
868            .position(|b| b.is_ascii_whitespace())
869            .map(|k| i + k)
870            .unwrap_or(n);
871        let token = std::str::from_utf8(&bytes[i..end]).unwrap_or("");
872        if is_nonfinite_spelling(token) {
873            return Err(ParseError::NonFiniteValue(token.to_string()));
874        }
875        let (val, consumed) = fast_float2::parse_partial::<f64, _>(&bytes[i..])
876            .map_err(|_| ParseError::InvalidNumberFormat(format!("invalid float: {token}")))?;
877        let next = i + consumed;
878        // Reject partial tokens like "1.2abc" (must end at whitespace or EOS).
879        if next != end {
880            return Err(ParseError::InvalidNumberFormat(format!(
881                "invalid float: {token}"
882            )));
883        }
884        if !val.is_finite() {
885            return Err(ParseError::NonFiniteValue(token.to_string()));
886        }
887        out[found] = val;
888        found += 1;
889        i = next;
890    }
891    while i < n && bytes[i].is_ascii_whitespace() {
892        i += 1;
893    }
894    // Reject trailing extra tokens (same contract as the old split loop).
895    if i < n {
896        return Err(ParseError::InvalidVectorLength {
897            expected: max,
898            found: found + 1,
899        });
900    }
901    if found < min || found > max {
902        return Err(ParseError::InvalidVectorLength {
903            expected: max,
904            found,
905        });
906    }
907    while found < max {
908        out[found] = defaults[found];
909        found += 1;
910    }
911    Ok(found)
912}
913
914/// Parses a line of whitespace-separated f64 values using fast-float2.
915///
916/// This is the hot-path parser for coordinate and velocity lines. It uses
917/// `fast_float2::parse` instead of `str::parse::<f64>()` for better throughput
918/// on the numeric-heavy atom data lines. Fixed-width atom lines use
919/// [`parse_line_of_range_f64_stack`] to avoid a heap `Vec` per line.
920///
921/// # Arguments
922///
923/// * `line` - A string slice representing a single line of data.
924/// * `n` - The exact number of f64 values expected on the line.
925pub fn parse_line_of_n_f64(line: &str, n: usize) -> Result<Vec<f64>, ParseError> {
926    if n <= NUMERIC_STACK_WIDTH {
927        let defaults = [0.0f64; NUMERIC_STACK_WIDTH];
928        let mut buf = [0.0f64; NUMERIC_STACK_WIDTH];
929        parse_line_of_range_f64_stack(line, n, n, &defaults, &mut buf)?;
930        return Ok(buf[..n].to_vec());
931    }
932    let mut values = Vec::with_capacity(n.min(max_tokens_on_line(line)));
933    for token in line.split_ascii_whitespace() {
934        values.push(parse_finite_float_token(token)?);
935    }
936    if values.len() == n {
937        Ok(values)
938    } else {
939        Err(ParseError::InvalidVectorLength {
940            expected: n,
941            found: values.len(),
942        })
943    }
944}
945
946/// Parses a line of whitespace-separated f64 values, accepting between `min`
947/// and `max` values (inclusive). Returns a vector of exactly `max` elements,
948/// padding with values from `defaults` when fewer than `max` are present.
949///
950/// Used for atom lines where column 5 (atom_index) is optional.
951/// Prefer [`parse_line_of_range_f64_stack`] on the atom hot path
952/// (`max <= NUMERIC_STACK_WIDTH`).
953pub fn parse_line_of_range_f64(
954    line: &str,
955    min: usize,
956    max: usize,
957    defaults: &[f64],
958) -> Result<Vec<f64>, ParseError> {
959    if max <= NUMERIC_STACK_WIDTH {
960        let mut buf = [0.0f64; NUMERIC_STACK_WIDTH];
961        parse_line_of_range_f64_stack(line, min, max, defaults, &mut buf)?;
962        return Ok(buf[..max].to_vec());
963    }
964    let mut values = Vec::with_capacity(max);
965    for token in line.split_ascii_whitespace() {
966        values.push(parse_finite_float_token(token)?);
967    }
968    if values.len() < min || values.len() > max {
969        return Err(ParseError::InvalidVectorLength {
970            expected: max,
971            found: values.len(),
972        });
973    }
974    while values.len() < max {
975        let idx = values.len();
976        values.push(defaults[idx]);
977    }
978    Ok(values)
979}
980
981/// CON-num.1 spellings. A leading sign is optional. Case is ignored.
982/// Digit and dot tokens return before any letter compare so the atom
983/// hot path does not allocate.
984fn is_nonfinite_spelling(token: &str) -> bool {
985    let rest = token
986        .strip_prefix('+')
987        .or_else(|| token.strip_prefix('-'))
988        .unwrap_or(token);
989    match rest.as_bytes().first() {
990        Some(b) if b.is_ascii_digit() || *b == b'.' => return false,
991        None => return false,
992        _ => {}
993    }
994    rest.eq_ignore_ascii_case("nan")
995        || rest.eq_ignore_ascii_case("inf")
996        || rest.eq_ignore_ascii_case("infinity")
997}
998
999fn parse_finite_float_token(token: &str) -> Result<f64, ParseError> {
1000    if is_nonfinite_spelling(token) {
1001        return Err(ParseError::NonFiniteValue(token.to_string()));
1002    }
1003    let (val, consumed) = fast_float2::parse_partial::<f64, _>(token.as_bytes())
1004        .map_err(|_| ParseError::InvalidNumberFormat(format!("invalid float: {token}")))?;
1005    if consumed != token.len() {
1006        return Err(ParseError::InvalidNumberFormat(format!(
1007            "invalid float: {token}"
1008        )));
1009    }
1010    if !val.is_finite() {
1011        return Err(ParseError::NonFiniteValue(token.to_string()));
1012    }
1013    Ok(val)
1014}
1015
1016fn skip_ascii_ws(bytes: &[u8], mut i: usize) -> usize {
1017    while i < bytes.len() && bytes[i].is_ascii_whitespace() {
1018        i += 1;
1019    }
1020    i
1021}
1022
1023fn take_token(line: &str, i: usize) -> Option<(&str, usize)> {
1024    let bytes = line.as_bytes();
1025    if i >= bytes.len() {
1026        return None;
1027    }
1028    let mut j = i;
1029    while j < bytes.len() && !bytes[j].is_ascii_whitespace() {
1030        j += 1;
1031    }
1032    Some((&line[i..j], j))
1033}
1034
1035/// Column 4. A sign, a decimal point, or a value outside the spec's set
1036/// is `InvalidFixedFlag` in every mode (CON-mask.1, CON-mask.5, D8).
1037fn parse_fixed_flag(token: &str, spec_version: u32) -> Result<[bool; 3], ParseError> {
1038    let bad = || {
1039        ParseError::InvalidFixedFlag(format!(
1040            "column 4 flag {token:?} is not a legal integer for spec {spec_version}"
1041        ))
1042    };
1043    if token.is_empty() || !token.bytes().all(|b| b.is_ascii_digit()) {
1044        return Err(bad());
1045    }
1046    let val: u64 = token.parse::<u64>().map_err(|_| bad())?;
1047    if spec_version < 2 {
1048        return match val {
1049            0 => Ok([false, false, false]),
1050            1 => Ok([true, true, true]),
1051            _ => Err(bad()),
1052        };
1053    }
1054    if val > 7 {
1055        return Err(bad());
1056    }
1057    let v = val as u8;
1058    Ok([v & 1 != 0, v & 2 != 0, v & 4 != 0])
1059}
1060
1061/// Column 5. Digits only, parsed as `u64`, never through `f64` (CON-id.1, D9).
1062/// A sign or a decimal point is `InvalidNumberFormat` at the token level.
1063fn parse_atom_id_token(token: &str) -> Result<u64, ParseError> {
1064    if token.is_empty() || !token.bytes().all(|b| b.is_ascii_digit()) {
1065        return Err(ParseError::InvalidNumberFormat(format!(
1066            "invalid integer: {token}"
1067        )));
1068    }
1069    token.parse::<u64>().map_err(|_| {
1070        ParseError::InvalidNumberFormat(format!("integer out of range 0..=2^64-1: {token}"))
1071    })
1072}
1073
1074/// Coordinate row: three finite floats, an integer flag, and an optional id.
1075/// Four columns take `default_id`, the 0-based position in the frame
1076/// (CON-id.9). Any other width is `InvalidVectorLength` (CON-num.9).
1077fn parse_coord_row(
1078    line: &str,
1079    spec_version: u32,
1080    default_id: u64,
1081) -> Result<([f64; 3], [bool; 3], u64), ParseError> {
1082    parse_vector_row(line, spec_version, Some(default_id))
1083}
1084
1085/// Vector section row. The flag and id columns are required (exact width 5).
1086fn parse_vector_section_row(
1087    line: &str,
1088    spec_version: u32,
1089) -> Result<([f64; 3], [bool; 3], u64), ParseError> {
1090    parse_vector_row(line, spec_version, None)
1091}
1092
1093fn parse_vector_row(
1094    line: &str,
1095    spec_version: u32,
1096    default_id: Option<u64>,
1097) -> Result<([f64; 3], [bool; 3], u64), ParseError> {
1098    let (row, end) = parse_coord_fields(line.as_bytes(), 0, spec_version, default_id)?;
1099    if end != line.len() {
1100        let found = 5 + count_tokens_on_line(line.as_bytes(), end);
1101        return Err(ParseError::InvalidVectorLength { expected: 5, found });
1102    }
1103    Ok(row)
1104}
1105
1106/// Field separator inside a coordinate row. Newline ends the row.
1107#[inline(always)]
1108fn is_field_ws(b: u8) -> bool {
1109    matches!(b, b' ' | b'\t' | b'\r' | 0x0c)
1110}
1111
1112#[inline(always)]
1113fn skip_field_ws(bytes: &[u8], mut i: usize) -> usize {
1114    while i < bytes.len() && is_field_ws(bytes[i]) {
1115        i += 1;
1116    }
1117    i
1118}
1119
1120fn token_on_line(bytes: &[u8], i: usize) -> String {
1121    let mut j = i;
1122    while j < bytes.len() && !is_field_ws(bytes[j]) && bytes[j] != b'\n' {
1123        j += 1;
1124    }
1125    String::from_utf8_lossy(&bytes[i..j]).into_owned()
1126}
1127
1128fn count_tokens_on_line(bytes: &[u8], mut i: usize) -> usize {
1129    let mut n = 0usize;
1130    loop {
1131        i = skip_field_ws(bytes, i);
1132        if i >= bytes.len() || bytes[i] == b'\n' {
1133            break;
1134        }
1135        n += 1;
1136        while i < bytes.len() && !is_field_ws(bytes[i]) && bytes[i] != b'\n' {
1137            i += 1;
1138        }
1139    }
1140    n
1141}
1142
1143/// Invalid UTF-8 in a numeric row, otherwise a normal number-format error.
1144fn utf8_or_number(bytes: &[u8], line_start: usize, i: usize) -> ParseError {
1145    let end = bytes[line_start..]
1146        .iter()
1147        .position(|b| *b == b'\n')
1148        .map(|p| line_start + p)
1149        .unwrap_or(bytes.len());
1150    if std::str::from_utf8(&bytes[line_start..end]).is_err() {
1151        return ParseError::ValidationError("invalid UTF-8".into());
1152    }
1153    ParseError::InvalidNumberFormat(format!("invalid float: {}", token_on_line(bytes, i)))
1154}
1155
1156#[inline(always)]
1157fn parse_f64_at(bytes: &[u8], i: usize, line_start: usize) -> Result<(f64, usize), ParseError> {
1158    if i >= bytes.len() || bytes[i] == b'\n' {
1159        return Err(ParseError::InvalidVectorLength {
1160            expected: 5,
1161            found: 0,
1162        });
1163    }
1164    if bytes[i] >= 0x80 {
1165        return Err(utf8_or_number(bytes, line_start, i));
1166    }
1167    if looks_like_nonfinite(bytes, i) {
1168        let token = token_on_line(bytes, i);
1169        if is_nonfinite_spelling(&token) {
1170            return Err(ParseError::NonFiniteValue(token));
1171        }
1172    }
1173    let (val, consumed) = fast_float2::parse_partial::<f64, _>(&bytes[i..]).map_err(|_| {
1174        ParseError::InvalidNumberFormat(format!("invalid float: {}", token_on_line(bytes, i)))
1175    })?;
1176    let next = i + consumed;
1177    let boundary = next >= bytes.len() || is_field_ws(bytes[next]) || bytes[next] == b'\n';
1178    if !boundary || !val.is_finite() {
1179        let token = token_on_line(bytes, i);
1180        if is_nonfinite_spelling(&token) || !val.is_finite() {
1181            return Err(ParseError::NonFiniteValue(token));
1182        }
1183        return Err(ParseError::InvalidNumberFormat(format!(
1184            "invalid float: {token}"
1185        )));
1186    }
1187    Ok((val, next))
1188}
1189
1190#[inline(always)]
1191fn parse_flag_at(
1192    bytes: &[u8],
1193    i: usize,
1194    spec_version: u32,
1195) -> Result<([bool; 3], usize), ParseError> {
1196    if i >= bytes.len() || bytes[i] == b'\n' {
1197        return Err(ParseError::InvalidVectorLength {
1198            expected: 5,
1199            found: 3,
1200        });
1201    }
1202    let bad = || {
1203        ParseError::InvalidFixedFlag(format!(
1204            "column 4 flag {:?} is not a legal integer for spec {spec_version}",
1205            token_on_line(bytes, i)
1206        ))
1207    };
1208    if !bytes[i].is_ascii_digit() {
1209        return Err(bad());
1210    }
1211    let mut j = i;
1212    let mut val: u64 = 0;
1213    while j < bytes.len() && bytes[j].is_ascii_digit() {
1214        let d = u64::from(bytes[j] - b'0');
1215        val = val
1216            .checked_mul(10)
1217            .and_then(|v| v.checked_add(d))
1218            .ok_or_else(bad)?;
1219        j += 1;
1220    }
1221    if j < bytes.len() && !is_field_ws(bytes[j]) && bytes[j] != b'\n' {
1222        return Err(bad());
1223    }
1224    let fixed = if spec_version < 2 {
1225        match val {
1226            0 => [false, false, false],
1227            1 => [true, true, true],
1228            _ => return Err(bad()),
1229        }
1230    } else if val <= 7 {
1231        let v = val as u8;
1232        [v & 1 != 0, v & 2 != 0, v & 4 != 0]
1233    } else {
1234        return Err(bad());
1235    };
1236    Ok((fixed, j))
1237}
1238
1239#[inline(always)]
1240fn parse_id_at(bytes: &[u8], i: usize) -> Result<(u64, usize), ParseError> {
1241    if i >= bytes.len() || bytes[i] == b'\n' || !bytes[i].is_ascii_digit() {
1242        return Err(ParseError::InvalidNumberFormat(format!(
1243            "invalid integer: {}",
1244            token_on_line(bytes, i)
1245        )));
1246    }
1247    let mut j = i;
1248    let mut val: u64 = 0;
1249    while j < bytes.len() && bytes[j].is_ascii_digit() {
1250        let d = u64::from(bytes[j] - b'0');
1251        val = val
1252            .checked_mul(10)
1253            .and_then(|v| v.checked_add(d))
1254            .ok_or_else(|| {
1255                ParseError::InvalidNumberFormat(format!(
1256                    "integer out of range 0..=2^64-1: {}",
1257                    token_on_line(bytes, i)
1258                ))
1259            })?;
1260        j += 1;
1261    }
1262    if j < bytes.len() && !is_field_ws(bytes[j]) && bytes[j] != b'\n' {
1263        return Err(ParseError::InvalidNumberFormat(format!(
1264            "invalid integer: {}",
1265            token_on_line(bytes, i)
1266        )));
1267    }
1268    Ok((val, j))
1269}
1270
1271/// One parsed coordinate row: xyz, fixed flags, and the atom id.
1272type ParsedCoord = ([f64; 3], [bool; 3], u64);
1273
1274/// One coordinate or vector row starting at `i`.
1275///
1276/// Stops at newline or end of `bytes` and returns the index just past the
1277/// row (after the newline, when one was present). Floats, the flag, and the
1278/// id are parsed in that single scan. The success path does not build error
1279/// strings; those stay on the cold fallback.
1280#[inline(always)]
1281fn parse_coord_fields(
1282    bytes: &[u8],
1283    i: usize,
1284    spec_version: u32,
1285    default_id: Option<u64>,
1286) -> Result<(ParsedCoord, usize), ParseError> {
1287    if let Some(parsed) = parse_coord_fields_fast(bytes, i, spec_version, default_id) {
1288        return Ok(parsed);
1289    }
1290    parse_coord_fields_detailed(bytes, i, spec_version, default_id)
1291}
1292
1293/// Common coordinate row: three finite decimals, a small flag, an optional id.
1294#[inline(always)]
1295fn parse_coord_fields_fast(
1296    bytes: &[u8],
1297    i: usize,
1298    spec_version: u32,
1299    default_id: Option<u64>,
1300) -> Option<(ParsedCoord, usize)> {
1301    let mut i = skip_field_ws(bytes, i);
1302    let mut xyz = [0.0f64; 3];
1303    for dest in &mut xyz {
1304        if i >= bytes.len() || bytes[i] == b'\n' || bytes[i] >= 0x80 {
1305            return None;
1306        }
1307        let (val, next) = crate::fast_dec::parse_f64_hot(bytes, i)?;
1308        if next < bytes.len() && !is_field_ws(bytes[next]) && bytes[next] != b'\n' {
1309            return None;
1310        }
1311        *dest = val;
1312        i = skip_field_ws(bytes, next);
1313    }
1314    let (fixed, next) = parse_flag_fast(bytes, i, spec_version)?;
1315    i = skip_field_ws(bytes, next);
1316    let (atom_id, next) = if i >= bytes.len() || bytes[i] == b'\n' {
1317        (default_id?, i)
1318    } else {
1319        parse_u64_fast(bytes, i)?
1320    };
1321    i = skip_field_ws(bytes, next);
1322    if i < bytes.len() && bytes[i] != b'\n' {
1323        return None;
1324    }
1325    if i < bytes.len() && bytes[i] == b'\n' {
1326        i += 1;
1327    }
1328    Some(((xyz, fixed, atom_id), i))
1329}
1330
1331#[inline(always)]
1332fn parse_u64_fast(bytes: &[u8], i: usize) -> Option<(u64, usize)> {
1333    if i >= bytes.len() || !bytes[i].is_ascii_digit() {
1334        return None;
1335    }
1336    let mut j = i;
1337    let mut val: u64 = 0;
1338    let mut digits = 0u32;
1339    while j < bytes.len() && bytes[j].is_ascii_digit() {
1340        digits += 1;
1341        // 19 digits can overflow u64; the detailed parser reports that.
1342        if digits > 18 {
1343            return None;
1344        }
1345        val = val * 10 + u64::from(bytes[j] - b'0');
1346        j += 1;
1347    }
1348    if j < bytes.len() && !is_field_ws(bytes[j]) && bytes[j] != b'\n' {
1349        return None;
1350    }
1351    Some((val, j))
1352}
1353
1354#[inline(always)]
1355fn parse_flag_fast(bytes: &[u8], i: usize, spec_version: u32) -> Option<([bool; 3], usize)> {
1356    let (val, j) = parse_u64_fast(bytes, i)?;
1357    let fixed = if spec_version < 2 {
1358        match val {
1359            0 => [false, false, false],
1360            1 => [true, true, true],
1361            _ => return None,
1362        }
1363    } else if val <= 7 {
1364        let v = val as u8;
1365        [v & 1 != 0, v & 2 != 0, v & 4 != 0]
1366    } else {
1367        return None;
1368    };
1369    Some((fixed, j))
1370}
1371
1372#[cold]
1373#[inline(never)]
1374fn parse_coord_fields_detailed(
1375    bytes: &[u8],
1376    i: usize,
1377    spec_version: u32,
1378    default_id: Option<u64>,
1379) -> Result<(ParsedCoord, usize), ParseError> {
1380    let line_start = i;
1381    let mut i = skip_field_ws(bytes, i);
1382    if i >= bytes.len() || bytes[i] == b'\n' {
1383        return Err(ParseError::InvalidVectorLength {
1384            expected: 5,
1385            found: 0,
1386        });
1387    }
1388    let mut xyz = [0.0f64; 3];
1389    for (slot, dest) in xyz.iter_mut().enumerate() {
1390        if i >= bytes.len() || bytes[i] == b'\n' {
1391            return Err(ParseError::InvalidVectorLength {
1392                expected: 5,
1393                found: slot,
1394            });
1395        }
1396        if bytes[i] >= 0x80 {
1397            return Err(utf8_or_number(bytes, line_start, i));
1398        }
1399        let (val, next) = parse_f64_at(bytes, i, line_start)?;
1400        *dest = val;
1401        i = skip_field_ws(bytes, next);
1402    }
1403    let (fixed, next) = parse_flag_at(bytes, i, spec_version)?;
1404    i = skip_field_ws(bytes, next);
1405    let (atom_id, next) = if i >= bytes.len() || bytes[i] == b'\n' {
1406        (
1407            default_id.ok_or(ParseError::InvalidVectorLength {
1408                expected: 5,
1409                found: 4,
1410            })?,
1411            i,
1412        )
1413    } else {
1414        parse_id_at(bytes, i)?
1415    };
1416    i = skip_field_ws(bytes, next);
1417    if i < bytes.len() && bytes[i] != b'\n' {
1418        let found = 5 + count_tokens_on_line(bytes, i);
1419        return Err(ParseError::InvalidVectorLength { expected: 5, found });
1420    }
1421    if i < bytes.len() && bytes[i] == b'\n' {
1422        i += 1;
1423    }
1424    Ok(((xyz, fixed, atom_id), i))
1425}
1426
1427/// Coordinate row at byte offset `i` in a multi-line buffer.
1428///
1429/// The returned index is the start of the next line. ASCII rows are valid
1430/// UTF-8 without a separate scan; a non-ASCII byte is checked only then.
1431pub(crate) fn parse_coord_row_at(
1432    bytes: &[u8],
1433    i: usize,
1434    spec_version: u32,
1435    default_id: u64,
1436) -> Result<(ParsedCoord, usize), ParseError> {
1437    if i >= bytes.len() {
1438        return Err(ParseError::IncompleteFrame);
1439    }
1440    parse_coord_fields(bytes, i, spec_version, Some(default_id))
1441}
1442
1443/// Vector-section row at `i`. The id column is required.
1444pub(crate) fn parse_vector_row_at(
1445    bytes: &[u8],
1446    i: usize,
1447    spec_version: u32,
1448) -> Result<(ParsedCoord, usize), ParseError> {
1449    if i >= bytes.len() {
1450        return Err(ParseError::IncompleteFrame);
1451    }
1452    parse_coord_fields(bytes, i, spec_version, None)
1453}
1454
1455/// Scalar section row: one finite float, a flag, and an id. Exact width 3.
1456fn parse_scalar_section_row(
1457    line: &str,
1458    spec_version: u32,
1459) -> Result<(f64, [bool; 3], u64), ParseError> {
1460    let bytes = line.as_bytes();
1461    let i = skip_ascii_ws(bytes, 0);
1462    let (value, i) = parse_finite_at(line, i)?;
1463    let i = skip_ascii_ws(bytes, i);
1464    let (flag_tok, i) = take_token(line, i).ok_or(ParseError::InvalidVectorLength {
1465        expected: 3,
1466        found: 1,
1467    })?;
1468    let fixed = parse_fixed_flag(flag_tok, spec_version)?;
1469    let i = skip_ascii_ws(bytes, i);
1470    let (id_tok, i) = take_token(line, i).ok_or(ParseError::InvalidVectorLength {
1471        expected: 3,
1472        found: 2,
1473    })?;
1474    let atom_id = parse_atom_id_token(id_tok)?;
1475    let i = skip_ascii_ws(bytes, i);
1476    if i < bytes.len() {
1477        let found = 3 + line[i..].split_ascii_whitespace().count();
1478        return Err(ParseError::InvalidVectorLength { expected: 3, found });
1479    }
1480    Ok((value, fixed, atom_id))
1481}
1482
1483fn parse_finite_at(line: &str, i: usize) -> Result<(f64, usize), ParseError> {
1484    let bytes = line.as_bytes();
1485    if i >= bytes.len() {
1486        return Err(ParseError::InvalidVectorLength {
1487            expected: 3,
1488            found: 0,
1489        });
1490    }
1491    // "infinity" parses as the prefix "inf" in fast_float2. Name that
1492    // spelling before the numeric kernel so the leftover is not a format error.
1493    if looks_like_nonfinite(bytes, i) {
1494        let token = take_token(line, i).map(|(tok, _)| tok).unwrap_or("");
1495        if is_nonfinite_spelling(token) {
1496            return Err(ParseError::NonFiniteValue(token.to_string()));
1497        }
1498    }
1499    let (val, consumed) = fast_float2::parse_partial::<f64, _>(&bytes[i..]).map_err(|_| {
1500        let token = take_token(line, i).map(|(tok, _)| tok).unwrap_or("");
1501        ParseError::InvalidNumberFormat(format!("invalid float: {token}"))
1502    })?;
1503    let next = i + consumed;
1504    let boundary = next == bytes.len() || bytes[next].is_ascii_whitespace();
1505    if !boundary || !val.is_finite() {
1506        let token = take_token(line, i).map(|(tok, _)| tok).unwrap_or("");
1507        if is_nonfinite_spelling(token) || !val.is_finite() {
1508            return Err(ParseError::NonFiniteValue(token.to_string()));
1509        }
1510        return Err(ParseError::InvalidNumberFormat(format!(
1511            "invalid float: {token}"
1512        )));
1513    }
1514    Ok((val, next))
1515}
1516
1517/// True when the token may be a non-finite spelling. Digit and dot
1518/// tokens, the common atom-line case, are false after one byte.
1519fn looks_like_nonfinite(bytes: &[u8], i: usize) -> bool {
1520    let mut j = i;
1521    if bytes[j] == b'+' || bytes[j] == b'-' {
1522        j += 1;
1523        if j >= bytes.len() {
1524            return false;
1525        }
1526    }
1527    let b = bytes[j];
1528    !b.is_ascii_digit() && b != b'.'
1529}
1530
1531/// Case-insensitive, after collapsing each run of spaces (CON-file.5, D17).
1532fn labels_equal(found: &str, expected: &str) -> bool {
1533    let mut found_words = found.split_ascii_whitespace();
1534    let mut expected_words = expected.split_ascii_whitespace();
1535    loop {
1536        match (found_words.next(), expected_words.next()) {
1537            (Some(a), Some(b)) => {
1538                if !a.eq_ignore_ascii_case(b) {
1539                    return false;
1540                }
1541            }
1542            (None, None) => return true,
1543            _ => return false,
1544        }
1545    }
1546}
1547
1548/// True when `line`, after the same folding, starts with every word of `prefix`.
1549fn label_has_prefix(line: &str, prefix: &str) -> bool {
1550    let mut found_words = line.split_ascii_whitespace();
1551    for word in prefix.split_ascii_whitespace() {
1552        match found_words.next() {
1553            Some(got) if got.eq_ignore_ascii_case(word) => {}
1554            _ => return false,
1555        }
1556    }
1557    true
1558}
1559
1560fn token_count(line: &str) -> usize {
1561    line.split_ascii_whitespace().count()
1562}
1563
1564/// Most whitespace-separated tokens `line` can hold.
1565///
1566/// `k` tokens take at least one byte each and one separator between each
1567/// pair, `2k - 1` bytes in all.
1568fn max_tokens_on_line(line: &str) -> usize {
1569    line.len().div_ceil(2)
1570}
1571
1572fn json_u64(value: &Value) -> Option<u64> {
1573    value.as_u64()
1574}
1575
1576fn validate_section_arity_value(value: &Value) -> Result<(), ParseError> {
1577    let obj = value.as_object().ok_or_else(|| {
1578        metadata_json_error("section_arity must be an object mapping section names to integers")
1579    })?;
1580    for (name, entry) in obj {
1581        let n = json_u64(entry).ok_or_else(|| {
1582            metadata_json_error(format!("section_arity.{name} must be an integer >= 1"))
1583        })?;
1584        if n < 1 {
1585            return Err(ParseError::InvalidCount(format!(
1586                "section_arity.{name} must be >= 1"
1587            )));
1588        }
1589        // Reserved names have a fixed value-field count (CON-section.13).
1590        if let Some(expect) = crate::types::reserved_section_value_arity(name)
1591            && n != expect
1592        {
1593            return Err(ParseError::InvalidVectorLength {
1594                expected: usize::try_from(expect).unwrap_or(usize::MAX),
1595                found: usize::try_from(n).unwrap_or(usize::MAX),
1596            });
1597        }
1598    }
1599    Ok(())
1600}
1601
1602/// Integer counts. A sign, a decimal point, or any other non-digit token
1603/// is `InvalidCount` (CON-error.3). Zero is a legal token here. The caller
1604/// rejects a per-type count of 0 when the type count is 1 or more (D4).
1605pub(crate) fn parse_count_line(line: &str, n: usize) -> Result<Vec<usize>, ParseError> {
1606    let mut values = Vec::with_capacity(n.min(max_tokens_on_line(line)));
1607    for token in line.split_ascii_whitespace() {
1608        if token.is_empty() || !token.bytes().all(|b| b.is_ascii_digit()) {
1609            return Err(ParseError::InvalidCount(format!(
1610                "count field is not an unsigned integer: {token}"
1611            )));
1612        }
1613        let val: u64 = token.parse::<u64>().map_err(|_| {
1614            ParseError::InvalidCount(format!("count field is out of range: {token}"))
1615        })?;
1616        let val = usize::try_from(val).map_err(|_| {
1617            ParseError::InvalidCount(format!("count field is out of range: {token}"))
1618        })?;
1619        values.push(val);
1620    }
1621    if values.len() == n {
1622        Ok(values)
1623    } else {
1624        Err(ParseError::InvalidVectorLength {
1625            expected: n,
1626            found: values.len(),
1627        })
1628    }
1629}
1630
1631/// True when `line` has no tokens. Spaces and tabs count as empty.
1632pub(crate) fn line_is_whitespace(line: &str) -> bool {
1633    line.split_ascii_whitespace().next().is_none()
1634}
1635
1636/// Lines 8 and 9 of a type count of 0.
1637///
1638/// A token on either line is `InvalidCount`. At end of file, a missing
1639/// line is empty (CON-count.4), and that frame is not `IncompleteHeader`
1640/// (CON-frame.3). Mid-file, both lines are required.
1641pub(crate) fn read_zero_atom_tail<'a>(
1642    mut next_line: impl FnMut() -> Option<&'a str>,
1643) -> Result<(), ParseError> {
1644    let bad = || {
1645        ParseError::InvalidCount("a zero-atom frame requires whitespace-only lines 8 and 9".into())
1646    };
1647    match next_line() {
1648        None => Ok(()),
1649        Some(line) if line_is_whitespace(line) => match next_line() {
1650            None => Ok(()),
1651            Some(line) if line_is_whitespace(line) => Ok(()),
1652            Some(_) => Err(bad()),
1653        },
1654        Some(_) => Err(bad()),
1655    }
1656}
1657
1658fn metadata_json_error(message: impl Into<String>) -> ParseError {
1659    ParseError::InvalidMetadataJson(message.into())
1660}
1661
1662fn validate_metadata_number(key: &str, value: &Value) -> Result<(), ParseError> {
1663    if value.as_f64().is_some() {
1664        Ok(())
1665    } else {
1666        Err(metadata_json_error(format!(
1667            "{key} must be a finite number"
1668        )))
1669    }
1670}
1671
1672fn validate_metadata_integer(key: &str, value: &Value) -> Result<(), ParseError> {
1673    if value.as_u64().is_some() {
1674        Ok(())
1675    } else {
1676        Err(metadata_json_error(format!(
1677            "{key} must be a non-negative integer"
1678        )))
1679    }
1680}
1681
1682/// Validates a parsed metadata JSON object against the spec v2 schema.
1683///
1684/// Type-checks the `validate` and `sections` keys, then runs per-key
1685/// schema checks for the recommended metadata keys. Used by the
1686/// builder/Python `set_metadata_json` paths to fail fast on malformed
1687/// input, and by the parser when the file requested strict validation
1688/// via `"validate": true`.
1689pub fn validate_metadata_schema(
1690    json_obj: &serde_json::Map<String, Value>,
1691) -> Result<(), ParseError> {
1692    let strict_requested = match json_obj.get(meta::VALIDATE) {
1693        Some(Value::Bool(b)) => *b,
1694        Some(_) => return Err(metadata_json_error("validate must be a boolean")),
1695        None => false,
1696    };
1697
1698    match json_obj.get(meta::SECTIONS) {
1699        Some(Value::Array(values)) => {
1700            if values.iter().any(|entry| !entry.is_string()) {
1701                return Err(metadata_json_error("sections must be an array of strings"));
1702            }
1703        }
1704        Some(_) => return Err(metadata_json_error("sections must be an array of strings")),
1705        None if strict_requested => {
1706            return Err(metadata_json_error(
1707                "validate=true requires a sections array, even when empty",
1708            ));
1709        }
1710        None => {}
1711    }
1712
1713    for (key, value) in json_obj {
1714        match key.as_str() {
1715            meta::CON_SPEC_VERSION | meta::SECTIONS | meta::VALIDATE => {}
1716            meta::CON_SPEC_MINOR => {
1717                if json_u64(value).is_none() {
1718                    return Err(metadata_json_error(
1719                        "con_spec_minor must be a JSON integer >= 0",
1720                    ));
1721                }
1722            }
1723            meta::SECTION_ARITY => validate_section_arity_value(value)?,
1724            meta::ENERGY
1725            | meta::TIME
1726            | meta::TIMESTEP
1727            | meta::CONVERGENCE_FMAX
1728            | meta::CONVERGENCE_ENERGY
1729            | meta::FMAX => validate_metadata_number(key, value)?,
1730            meta::FRAME_INDEX | meta::NEB_BEAD | meta::NEB_BAND => {
1731                validate_metadata_integer(key, value)?
1732            }
1733            meta::GENERATOR if !value.is_string() => {
1734                return Err(metadata_json_error("generator must be a string"));
1735            }
1736            meta::GENERATOR => {}
1737            meta::UNITS | meta::POTENTIAL if !value.is_object() => {
1738                return Err(metadata_json_error(format!("{key} must be an object")));
1739            }
1740            meta::POTENTIAL => {
1741                if let Some(potential_type) = value.get("type")
1742                    && !potential_type.is_string()
1743                {
1744                    return Err(metadata_json_error("potential.type must be a string"));
1745                }
1746            }
1747            meta::UNITS => {
1748                // Full v3 checks (required keys) run when con_spec_version >= 3.
1749            }
1750            meta::PBC => validate_pbc_metadata(value)?,
1751            meta::BONDS => validate_bonds_metadata(value)?,
1752            meta::LATTICE_VECTORS => validate_lattice_vectors_metadata(value)?,
1753            meta::CONVERGED if !value.is_boolean() => {
1754                return Err(metadata_json_error("converged must be a boolean"));
1755            }
1756            meta::CONVERGED => {}
1757            _ => {}
1758        }
1759    }
1760
1761    Ok(())
1762}
1763
1764fn validate_pbc_metadata(value: &Value) -> Result<(), ParseError> {
1765    let Some(values) = value.as_array() else {
1766        return Err(metadata_json_error("pbc must be a length-3 boolean array"));
1767    };
1768    if values.len() != 3 || values.iter().any(|entry| !entry.is_boolean()) {
1769        return Err(metadata_json_error("pbc must be a length-3 boolean array"));
1770    }
1771    Ok(())
1772}
1773
1774/// Validate optional `bonds` frame topology metadata.
1775///
1776/// Each element is either a length-2 non-negative integer pair `[i, j]` or an
1777/// object `{"i": i, "j": j, "order"?: integer}`. Indices are 0-based into
1778/// `atom_data` order (parser does not yet know atom count at metadata time;
1779/// bounds are enforced when projecting to chemfiles / selection).
1780fn validate_bonds_metadata(value: &Value) -> Result<(), ParseError> {
1781    let Some(items) = value.as_array() else {
1782        return Err(metadata_json_error("bonds must be an array"));
1783    };
1784    for (idx, item) in items.iter().enumerate() {
1785        if let Some(pair) = item.as_array() {
1786            if pair.len() != 2 {
1787                return Err(metadata_json_error(format!(
1788                    "bonds[{idx}] pair must have exactly two indices"
1789                )));
1790            }
1791            for (k, entry) in pair.iter().enumerate() {
1792                let Some(n) = entry.as_u64() else {
1793                    return Err(metadata_json_error(format!(
1794                        "bonds[{idx}][{k}] must be a non-negative integer"
1795                    )));
1796                };
1797                if n > u32::MAX as u64 {
1798                    return Err(metadata_json_error(format!(
1799                        "bonds[{idx}][{k}] index exceeds u32"
1800                    )));
1801                }
1802            }
1803            continue;
1804        }
1805        if let Some(obj) = item.as_object() {
1806            for key in ["i", "j"] {
1807                let Some(entry) = obj.get(key) else {
1808                    return Err(metadata_json_error(format!(
1809                        "bonds[{idx}] object must include \"{key}\""
1810                    )));
1811                };
1812                let Some(n) = entry.as_u64() else {
1813                    return Err(metadata_json_error(format!(
1814                        "bonds[{idx}].{key} must be a non-negative integer"
1815                    )));
1816                };
1817                if n > u32::MAX as u64 {
1818                    return Err(metadata_json_error(format!(
1819                        "bonds[{idx}].{key} index exceeds u32"
1820                    )));
1821                }
1822            }
1823            if let Some(order) = obj.get("order")
1824                && order.as_i64().is_none()
1825            {
1826                return Err(metadata_json_error(format!(
1827                    "bonds[{idx}].order must be an integer when present"
1828                )));
1829            }
1830            continue;
1831        }
1832        return Err(metadata_json_error(format!(
1833            "bonds[{idx}] must be [i, j] or {{\"i\": i, \"j\": j, \"order\"?: ...}}"
1834        )));
1835    }
1836    Ok(())
1837}
1838
1839fn validate_lattice_vectors_metadata(value: &Value) -> Result<(), ParseError> {
1840    let Some(rows) = value.as_array() else {
1841        return Err(metadata_json_error(
1842            "lattice_vectors must be a 3x3 numeric array",
1843        ));
1844    };
1845    if rows.len() != 3 {
1846        return Err(metadata_json_error(
1847            "lattice_vectors must be a 3x3 numeric array",
1848        ));
1849    }
1850    for row in rows {
1851        let Some(entries) = row.as_array() else {
1852            return Err(metadata_json_error(
1853                "lattice_vectors must be a 3x3 numeric array",
1854            ));
1855        };
1856        if entries.len() != 3 || entries.iter().any(|entry| entry.as_f64().is_none()) {
1857            return Err(metadata_json_error(
1858                "lattice_vectors must be a 3x3 numeric array",
1859            ));
1860        }
1861    }
1862    Ok(())
1863}
1864
1865/// Parses a line of whitespace-separated values into a vector of a specific type.
1866///
1867/// This generic helper function takes a string slice, splits it by whitespace,
1868/// and attempts to parse each substring into the target type `T`. The type `T`
1869/// must implement `std::str::FromStr`.
1870///
1871/// # Arguments
1872///
1873/// * `line` - A string slice representing a single line of data.
1874/// * `n` - The exact number of values expected on the line.
1875///
1876/// # Errors
1877///
1878/// * `ParseError::InvalidVectorLength` if the number of parsed values is not equal to `n`.
1879/// * Propagates any error from the `parse()` method of the target type `T`.
1880///
1881/// # Example
1882///
1883/// ```
1884/// use readcon_core::parser::parse_line_of_n;
1885/// let line = "10.5 20.0 30.5";
1886/// let values: Vec<f64> = parse_line_of_n(line, 3).unwrap();
1887/// assert_eq!(values, vec![10.5, 20.0, 30.5]);
1888///
1889/// let result = parse_line_of_n::<i32>(line, 2);
1890/// assert!(result.is_err());
1891/// ```
1892pub fn parse_line_of_n<T: std::str::FromStr>(line: &str, n: usize) -> Result<Vec<T>, ParseError>
1893where
1894    ParseError: From<<T as std::str::FromStr>::Err>,
1895{
1896    let values: Vec<T> = line
1897        .split_whitespace()
1898        .map(|s| s.parse::<T>())
1899        .collect::<Result<_, _>>()?;
1900
1901    if values.len() == n {
1902        Ok(values)
1903    } else {
1904        Err(ParseError::InvalidVectorLength {
1905            expected: n,
1906            found: values.len(),
1907        })
1908    }
1909}
1910
1911/// Parses the 9-line header of a `.con` file frame from an iterator.
1912///
1913/// This function consumes the next 9 lines from the given line iterator to
1914/// construct a `FrameHeader`. The iterator is advanced by 9 lines on success.
1915///
1916/// # Arguments
1917///
1918/// * `lines` - A mutable reference to an iterator that yields string slices.
1919///
1920/// # Errors
1921///
1922/// * `ParseError::IncompleteHeader` if the iterator has fewer than 9 lines remaining.
1923/// * Propagates any errors from `parse_line_of_n` if the numeric data within
1924///   the header is malformed.
1925///
1926/// # Panics
1927///
1928/// This function will panic if the intermediate vectors for box dimensions or angles,
1929/// after being successfully parsed, cannot be converted into fixed-size arrays.
1930/// This should not happen if `parse_line_of_n` is used correctly with `n=3`.
1931pub fn parse_frame_header<'a>(
1932    lines: &mut impl Iterator<Item = &'a str>,
1933) -> Result<FrameHeader, ParseError> {
1934    let prebox1 = lines
1935        .next()
1936        .ok_or(ParseError::IncompleteHeader)?
1937        .to_string();
1938    // CON-file.2: a leading BOM is rejected. It would sit on line 1.
1939    if prebox1.starts_with('\u{feff}') {
1940        return Err(ParseError::ValidationError(
1941            "file begins with a byte-order mark".into(),
1942        ));
1943    }
1944    let prebox2_raw = lines.next().ok_or(ParseError::IncompleteHeader)?;
1945
1946    // Line 2: if it starts with '{', parse as JSON metadata (spec v2+).
1947    // Otherwise treat as a legacy (pre-v2) file with spec_version = 1.
1948    // One JSON object and nothing else (CON-line2.1). serde_json::from_str
1949    // rejects trailing junk after the value.
1950    let trimmed = prebox2_raw.trim();
1951    let (spec_version, sections, validate, sections_declared) =
1952        if trimmed == "{\"con_spec_version\":2}" {
1953            // The line written by every stock trajectory. Same object the
1954            // JSON parser would build: major 2, no extra keys.
1955            (2, Vec::new(), false, false)
1956        } else if let Some(ver) = simple_metadata_version(trimmed) {
1957            // A header whose only keys are the spec version, an optional
1958            // minor, and a units object. Every byte is still read. Any
1959            // other key falls through to the general parser.
1960            (ver, Vec::new(), false, false)
1961        } else if trimmed.starts_with('{') {
1962            let json_val: serde_json::Value = serde_json::from_str(trimmed)
1963                .map_err(|e| ParseError::InvalidMetadataJson(e.to_string()))?;
1964            let json_obj = json_val.as_object().ok_or_else(|| {
1965                ParseError::InvalidMetadataJson("expected a JSON object".to_string())
1966            })?;
1967            let ver_value = json_obj
1968                .get(meta::CON_SPEC_VERSION)
1969                .ok_or(ParseError::MissingSpecVersion)?;
1970            let ver = json_u64(ver_value).ok_or_else(|| {
1971                ParseError::InvalidMetadataJson(
1972                    "con_spec_version must be a JSON integer, the major version".into(),
1973                )
1974            })?;
1975            if ver > u64::from(u32::MAX) {
1976                return Err(ParseError::UnsupportedVersion(u32::MAX));
1977            }
1978            let ver = ver as u32;
1979            // JSON majors 0 and 1 are UnsupportedVersion (CON-line2.5).
1980            // An unknown major is UnsupportedVersion (CON-line2.6).
1981            // Unknown minors of a known major are accepted (CON-line2.7, CON-status.1).
1982            if ver == 0 || ver == 1 || ver > crate::CON_SPEC_VERSION {
1983                return Err(ParseError::UnsupportedVersion(ver));
1984            }
1985            if ver >= 3 {
1986                match json_obj.get(meta::UNITS) {
1987                    Some(u) => crate::units::validate_v3_units_metadata(u)
1988                        .map_err(|e| ParseError::InvalidUnits(format!("v3 units: {e}")))?,
1989                    None => {
1990                        return Err(ParseError::InvalidUnits(
1991                        "con_spec_version >= 3 requires metadata \"units\" with length and energy"
1992                            .into(),
1993                    ));
1994                    }
1995                }
1996            }
1997
1998            // Single pass over the JSON object: collect sections, capture the
1999            // validate flag, copy the rest into metadata. Folds the previous
2000            // pre-extract get(validate) + re-iterate pattern into one walk.
2001            let mut sections: Vec<String> = Vec::new();
2002            let mut sections_declared = false;
2003            let mut validate = false;
2004            for (k, v) in json_obj {
2005                match k.as_str() {
2006                    meta::CON_SPEC_VERSION => {}
2007                    meta::CON_SPEC_MINOR => {
2008                        if json_u64(v).is_none() {
2009                            return Err(metadata_json_error(
2010                                "con_spec_minor must be a JSON integer >= 0",
2011                            ));
2012                        }
2013                    }
2014                    meta::SECTION_ARITY => {
2015                        validate_section_arity_value(v)?;
2016                    }
2017                    meta::SECTIONS => {
2018                        sections_declared = true;
2019                        let arr = v.as_array().ok_or_else(|| {
2020                            metadata_json_error("sections must be an array of strings")
2021                        })?;
2022                        sections.reserve(arr.len());
2023                        for entry in arr {
2024                            let s = entry.as_str().ok_or_else(|| {
2025                                metadata_json_error("sections must be an array of strings")
2026                            })?;
2027                            sections.push(s.to_string());
2028                        }
2029                    }
2030                    meta::VALIDATE => {
2031                        validate = match v {
2032                            Value::Bool(b) => *b,
2033                            _ => return Err(metadata_json_error("validate must be a boolean")),
2034                        };
2035                    }
2036                    _ => {}
2037                }
2038            }
2039
2040            // Strict-mode schema check fires only when the file requested
2041            // it. Hot-path parses (validate=false) skip the per-key match.
2042            if validate {
2043                validate_metadata_schema(json_obj)?;
2044            }
2045
2046            (ver, sections, validate, sections_declared)
2047        } else {
2048            // Legacy file: no JSON metadata line.
2049            (1_u32, Vec::new(), false, false)
2050        };
2051    let prebox2 = prebox2_raw.to_string();
2052
2053    let boxl_vec = parse_line_of_n_f64(lines.next().ok_or(ParseError::IncompleteHeader)?, 3)?;
2054    let angles_vec = parse_line_of_n_f64(lines.next().ok_or(ParseError::IncompleteHeader)?, 3)?;
2055    let postbox1 = lines
2056        .next()
2057        .ok_or(ParseError::IncompleteHeader)?
2058        .to_string();
2059    let postbox2 = lines
2060        .next()
2061        .ok_or(ParseError::IncompleteHeader)?
2062        .to_string();
2063    let natm_types_line = lines.next().ok_or(ParseError::IncompleteHeader)?;
2064    let natm_types = parse_count_line(natm_types_line, 1)?[0];
2065    // A type count of 0 is a zero-atom frame (CON-count.1, CON-count.4).
2066    // A per-type count of 0 is InvalidCount only when the type count is >= 1.
2067    let (natms_per_type, masses_per_type) = if natm_types == 0 {
2068        read_zero_atom_tail(|| lines.next())?;
2069        (Vec::new(), Vec::new())
2070    } else {
2071        let natms_per_type = parse_count_line(
2072            lines.next().ok_or(ParseError::IncompleteHeader)?,
2073            natm_types,
2074        )?;
2075        if natms_per_type.contains(&0) {
2076            return Err(ParseError::InvalidCount(
2077                "each per-type count must be >= 1".into(),
2078            ));
2079        }
2080        let masses_per_type = parse_line_of_n_f64(
2081            lines.next().ok_or(ParseError::IncompleteHeader)?,
2082            natm_types,
2083        )?;
2084        (natms_per_type, masses_per_type)
2085    };
2086    if validate {
2087        validate_header_geometry(&boxl_vec, &angles_vec)?;
2088        validate_masses(&masses_per_type)?;
2089    }
2090    let shared_line: std::sync::Arc<str> = std::sync::Arc::from(prebox2);
2091    let metadata = crate::types::FrameMeta::from_shared(std::sync::Arc::clone(&shared_line));
2092    Ok(FrameHeader {
2093        prebox_header: PreboxHeader {
2094            user: prebox1,
2095            metadata_line: shared_line,
2096        },
2097        boxl: boxl_vec.try_into().unwrap(),
2098        angles: angles_vec.try_into().unwrap(),
2099        postbox_header: [postbox1, postbox2],
2100        natm_types,
2101        natms_per_type,
2102        masses_per_type,
2103        spec_version,
2104        metadata,
2105        sections,
2106        strict_validation: validate,
2107        sections_declared,
2108    })
2109}
2110
2111/// Spec line limited to `con_spec_version`, optional `con_spec_minor`, and `units`.
2112///
2113/// Returns the major version when the object is exactly that shape and, for
2114/// version 3 or newer, `length` and `energy` are valid units. Anything else
2115/// is `None` so the general JSON parser can accept or reject it.
2116fn simple_metadata_version(line: &str) -> Option<u32> {
2117    let bytes = line.as_bytes();
2118    let mut i = 0usize;
2119    let skip = |i: &mut usize| {
2120        while *i < bytes.len() && bytes[*i].is_ascii_whitespace() {
2121            *i += 1;
2122        }
2123    };
2124    let eat = |i: &mut usize, byte: u8| -> bool {
2125        skip(i);
2126        if *i < bytes.len() && bytes[*i] == byte {
2127            *i += 1;
2128            true
2129        } else {
2130            false
2131        }
2132    };
2133    let quoted = |i: &mut usize| -> Option<&str> {
2134        skip(i);
2135        if *i >= bytes.len() || bytes[*i] != b'"' {
2136            return None;
2137        }
2138        *i += 1;
2139        let start = *i;
2140        while *i < bytes.len() && bytes[*i] != b'"' {
2141            if bytes[*i] == b'\\' {
2142                return None;
2143            }
2144            *i += 1;
2145        }
2146        if *i >= bytes.len() {
2147            return None;
2148        }
2149        let text = std::str::from_utf8(&bytes[start..*i]).ok()?;
2150        *i += 1;
2151        Some(text)
2152    };
2153    let integer = |i: &mut usize| -> Option<u64> {
2154        skip(i);
2155        let start = *i;
2156        if *i < bytes.len() && bytes[*i] == b'-' {
2157            return None;
2158        }
2159        while *i < bytes.len() && bytes[*i].is_ascii_digit() {
2160            *i += 1;
2161        }
2162        if start == *i || (bytes[start] == b'0' && *i > start + 1) {
2163            return None;
2164        }
2165        std::str::from_utf8(&bytes[start..*i]).ok()?.parse().ok()
2166    };
2167    if !eat(&mut i, b'{') {
2168        return None;
2169    }
2170    let mut version = None;
2171    let mut saw_minor = false;
2172    let mut length = None;
2173    let mut energy = None;
2174    let mut extra_unit = false;
2175    loop {
2176        skip(&mut i);
2177        if i < bytes.len() && bytes[i] == b'}' {
2178            i += 1;
2179            break;
2180        }
2181        if version.is_some() || saw_minor || length.is_some() || energy.is_some() || extra_unit {
2182            if !eat(&mut i, b',') {
2183                return None;
2184            }
2185        }
2186        let key = quoted(&mut i)?;
2187        if !eat(&mut i, b':') {
2188            return None;
2189        }
2190        match key {
2191            "con_spec_version" if version.is_none() => version = Some(integer(&mut i)?),
2192            "con_spec_minor" if !saw_minor => {
2193                integer(&mut i)?;
2194                saw_minor = true;
2195            }
2196            "units" if length.is_none() && energy.is_none() && !extra_unit => {
2197                if !eat(&mut i, b'{') {
2198                    return None;
2199                }
2200                loop {
2201                    skip(&mut i);
2202                    if i < bytes.len() && bytes[i] == b'}' {
2203                        i += 1;
2204                        break;
2205                    }
2206                    if length.is_some() || energy.is_some() || extra_unit {
2207                        if !eat(&mut i, b',') {
2208                            return None;
2209                        }
2210                    }
2211                    let ukey = quoted(&mut i)?;
2212                    if !eat(&mut i, b':') {
2213                        return None;
2214                    }
2215                    let value = quoted(&mut i)?;
2216                    match ukey {
2217                        "length" if length.is_none() => length = Some(value),
2218                        "energy" if energy.is_none() => energy = Some(value),
2219                        "mass" | "time" | "velocity" | "force" => {
2220                            if crate::units::validate_unit_for_quantity(ukey, value).is_err() {
2221                                return None;
2222                            }
2223                            extra_unit = true;
2224                        }
2225                        _ => return None,
2226                    }
2227                }
2228            }
2229            _ => return None,
2230        }
2231    }
2232    skip(&mut i);
2233    if i != bytes.len() {
2234        return None;
2235    }
2236    let ver = u32::try_from(version?).ok()?;
2237    if ver == 0 || ver == 1 || ver > crate::CON_SPEC_VERSION {
2238        return None;
2239    }
2240    if ver >= 3 {
2241        let length = length?;
2242        let energy = energy?;
2243        if length.trim().is_empty() || energy.trim().is_empty() {
2244            return None;
2245        }
2246        crate::units::validate_unit_for_quantity("length", length).ok()?;
2247        crate::units::validate_unit_for_quantity("energy", energy).ok()?;
2248    }
2249    Some(ver)
2250}
2251
2252/// Parses a complete frame from a `.con` file, including its header and atomic data.
2253///
2254/// This function first parses the complete frame header and then uses the information within it
2255/// (specifically the number of atom types and atoms per type) to parse the subsequent
2256/// atom coordinate blocks.
2257///
2258/// Each atom takes one line, so the atom vectors reserve no more rows than the
2259/// upper bound of `lines.size_hint()`. With no upper bound, as for `str::lines`,
2260/// they grow as the rows arrive.
2261///
2262/// # Arguments
2263///
2264/// * `lines` - A mutable reference to an iterator that yields string slices for the frame.
2265///
2266/// # Errors
2267///
2268/// * `ParseError::IncompleteFrame` if the iterator ends before all expected
2269///   atomic data has been read.
2270/// * Propagates any errors from the underlying calls to `parse_frame_header` and
2271///   `parse_line_of_n`.
2272///
2273/// # Example
2274///
2275/// ```
2276/// use readcon_core::parser::parse_single_frame;
2277///
2278/// let frame_text = r#"
2279///Generated by test
2280///{"con_spec_version":2}
2281///10.0 10.0 10.0
2282///90.0 90.0 90.0
2283///POSTBOX LINE 1
2284///POSTBOX LINE 2
2285///2
2286///1 1
2287///12.011 1.008
2288///C
2289///Coordinates of Component 1
2290///1.0 1.0 1.0 0 1
2291///H
2292///Coordinates of Component 2
2293///2.0 2.0 2.0 0 2
2294/// "#;
2295///
2296/// let mut lines = frame_text.trim().lines();
2297/// let con_frame = parse_single_frame(&mut lines).unwrap();
2298///
2299/// assert_eq!(con_frame.header.natm_types, 2);
2300/// assert_eq!(con_frame.atom_data.len(), 2);
2301/// assert_eq!(&*con_frame.atom_data[0].symbol, "C");
2302/// assert_eq!(con_frame.atom_data[1].atom_id, 2);
2303/// ```
2304pub fn parse_single_frame<'a>(
2305    lines: &mut impl Iterator<Item = &'a str>,
2306) -> Result<ConFrame, ParseError> {
2307    // The caller owns the iterator and may not be able to clone it. Section
2308    // detection, which needs a lookahead clone, runs later on a `LineStream`
2309    // that can probe (`MemchrLines`, or a `Peekable` whose source is `Clone`).
2310    let max_rows = lines.size_hint().1;
2311    parse_single_frame_ls(&mut IterStream(lines), max_rows)
2312}
2313
2314/// Iterator adapter so [`parse_single_frame`] can satisfy [`LineStream`]
2315/// without requiring [`Clone`].
2316struct IterStream<I>(I);
2317
2318impl<'a, I> Iterator for IterStream<I>
2319where
2320    I: Iterator<Item = &'a str>,
2321{
2322    type Item = &'a str;
2323    fn next(&mut self) -> Option<&'a str> {
2324        self.0.next()
2325    }
2326}
2327
2328impl<'a, I> LineStream<'a> for IterStream<I>
2329where
2330    I: Iterator<Item = &'a str>,
2331{
2332    fn next_line(&mut self) -> Option<&'a str> {
2333        Iterator::next(self)
2334    }
2335    fn peek_line(&mut self) -> Option<&'a str> {
2336        None
2337    }
2338}
2339
2340struct CoordShell {
2341    atoms: Vec<crate::types::AtomDatum>,
2342    coords: Vec<f64>,
2343    ids: Vec<u64>,
2344}
2345
2346thread_local! {
2347    static COORD_SHELLS: std::cell::RefCell<Vec<CoordShell>> =
2348        const { std::cell::RefCell::new(Vec::new()) };
2349}
2350
2351/// Allocate `n_frames` coordinate shells on this thread before the parse.
2352///
2353/// One tight reservation, then each frame takes a shell. Doing the
2354/// reservations inside the parse mixed the allocator with the float
2355/// parse and made eight threads slower than the bytes they write.
2356pub(crate) fn prestash_coord_shells(n_frames: usize, n_atoms: usize) {
2357    // Small frames (the 32-atom strong-scaling files) are cheaper to
2358    // allocate inside the parse. A burst of shells ahead of those frames
2359    // made eight threads slower. Wide atoms, as in the weak-scaling
2360    // fixture, are the case the burst is for.
2361    if n_frames == 0 || n_atoms < 128 {
2362        return;
2363    }
2364    COORD_SHELLS.with(|pool| {
2365        let mut pool = pool.borrow_mut();
2366        pool.reserve(n_frames);
2367        for _ in 0..n_frames {
2368            pool.push(CoordShell {
2369                atoms: Vec::with_capacity(n_atoms),
2370                coords: Vec::with_capacity(n_atoms.saturating_mul(3)),
2371                ids: Vec::with_capacity(n_atoms),
2372            });
2373        }
2374    });
2375}
2376
2377pub(crate) fn clear_coord_shells() {
2378    COORD_SHELLS.with(|pool| pool.borrow_mut().clear());
2379}
2380
2381fn take_coord_shell(n_atoms: usize) -> Option<CoordShell> {
2382    COORD_SHELLS.with(|pool| {
2383        let shell = pool.borrow_mut().pop()?;
2384        if shell.atoms.capacity() >= n_atoms
2385            && shell.coords.capacity() >= n_atoms.saturating_mul(3)
2386            && shell.ids.capacity() >= n_atoms
2387        {
2388            Some(shell)
2389        } else {
2390            None
2391        }
2392    })
2393}
2394
2395/// Columns every atom line has: x, y, z and the flag (spec "Coordinates",
2396/// CON-num.9). The id column is optional (CON-id.9).
2397const COORD_ROW_MIN_COLUMNS: usize = 4;
2398
2399/// Fewest bytes an atom line takes, as in `0 0 0 0`: one byte for each of
2400/// the [`COORD_ROW_MIN_COLUMNS`] columns and one separator between each
2401/// pair. Newlines and the symbol and label lines only add bytes, so `n`
2402/// unread bytes hold at most `n / MIN_COORD_ROW_BYTES` atom lines.
2403pub(crate) const MIN_COORD_ROW_BYTES: usize = 2 * COORD_ROW_MIN_COLUMNS - 1;
2404
2405/// Frame parse over a [`LineStream`].
2406///
2407/// Coordinate rows go through [`LineStream::next_coord_row`] so the memchr
2408/// cursor can fuse the newline scan with numeric parse. Positions, ids, and
2409/// flags land in flat buffers; [`AtomDatum`] values are built from those
2410/// buffers afterwards (one `Vec` allocation, no per-atom heap traffic).
2411///
2412/// `max_rows` bounds the atom lines the rest of the input can hold, and is
2413/// `None` when that is unknown. The buffers reserve no more atoms than it
2414/// allows, so a header that declares more atoms than the input holds
2415/// cannot force a large allocation. The declared counts still decide how
2416/// many rows are read, and so which error is reported.
2417pub(crate) fn parse_single_frame_ls<'a, L>(
2418    lines: &mut L,
2419    max_rows: Option<usize>,
2420) -> Result<ConFrame, ParseError>
2421where
2422    L: LineStream<'a> + Iterator<Item = &'a str>,
2423{
2424    let header = parse_frame_header(lines)?;
2425    // A count the unread input can hold stays in this function, on the same
2426    // reservation and `Arc` bump as before the bound existed. A count that
2427    // cannot fit is a separate cold function so it does not shape this loop.
2428    let Some(total_atoms) = fitting_atom_count(&header.natms_per_type, max_rows) else {
2429        return parse_oversized_frame(lines, header, max_rows);
2430    };
2431    let validate = header.strict_validation;
2432    use crate::storage_dtype::{ElementKind, FloatArray2};
2433    let dt = header.metadata.dtypes();
2434    let f64_positions = dt.positions == ElementKind::Float64;
2435    let shell = take_coord_shell(total_atoms);
2436    let (mut pos_flat, mut ids, mut atom_data) = match shell {
2437        Some(shell) => (shell.coords, shell.ids, shell.atoms),
2438        None => (
2439            Vec::with_capacity(total_atoms.saturating_mul(3)),
2440            Vec::with_capacity(total_atoms),
2441            Vec::with_capacity(total_atoms),
2442        ),
2443    };
2444    let mut positions_other = if f64_positions {
2445        None
2446    } else {
2447        Some(FloatArray2::zeros(dt.positions, total_atoms, 3))
2448    };
2449    let mut global_atom_idx: u64 = 0;
2450    for (type_idx, num_atoms) in header.natms_per_type.iter().enumerate() {
2451        let symbol_line = lines.next().ok_or(ParseError::IncompleteFrame)?;
2452        let symbol: Arc<str> = Arc::from(symbol_line.trim());
2453        let coord_label = lines.next().ok_or(ParseError::IncompleteFrame)?;
2454        if validate {
2455            validate_coordinate_component(type_idx, symbol.as_ref(), coord_label)?;
2456        }
2457        global_atom_idx = ingest_coord_rows(
2458            lines,
2459            *num_atoms,
2460            header.spec_version,
2461            global_atom_idx,
2462            &symbol,
2463            CoordSink {
2464                pos_flat: &mut pos_flat,
2465                ids: &mut ids,
2466                positions_other: &mut positions_other,
2467                atom_data: &mut atom_data,
2468            },
2469        )?;
2470    }
2471    let positions = if f64_positions {
2472        FloatArray2::from_f64_row_major(total_atoms, 3, pos_flat)
2473    } else {
2474        positions_other.expect("non-f64 positions allocated")
2475    };
2476    Ok(crate::types::con_frame_coords_only_with_ids(
2477        header, atom_data, positions, ids,
2478    ))
2479}
2480
2481/// Atom total when it can use [`Vec::with_capacity`] safely.
2482///
2483/// `None` means the counts wrap, exceed `isize::MAX / 4`, or exceed the
2484/// unread atom lines. A `u32::MAX` count with no size hint is `None`: that
2485/// reservation is tens of GiB.
2486#[inline]
2487fn fitting_atom_count(counts: &[usize], max_rows: Option<usize>) -> Option<usize> {
2488    let mut total = 0usize;
2489    for &count in counts {
2490        total = total.checked_add(count)?;
2491    }
2492    if total > (isize::MAX as usize) / 4 {
2493        return None;
2494    }
2495    match max_rows {
2496        Some(rows) if total > rows => None,
2497        None if total > (1 << 20) => None,
2498        _ => Some(total),
2499    }
2500}
2501
2502/// A header declared more atoms than the rest of the input can hold.
2503///
2504/// Reservations stay within `max_rows`. Rows are still read up to the
2505/// declared count, so a short file is `IncompleteFrame`.
2506#[cold]
2507#[inline(never)]
2508fn parse_oversized_frame<'a, L>(
2509    lines: &mut L,
2510    header: FrameHeader,
2511    max_rows: Option<usize>,
2512) -> Result<ConFrame, ParseError>
2513where
2514    L: LineStream<'a> + Iterator<Item = &'a str>,
2515{
2516    let validate = header.strict_validation;
2517    let total_atoms = header
2518        .natms_per_type
2519        .iter()
2520        .fold(0usize, |sum, &n| sum.saturating_add(n));
2521    let reserve_atoms = max_rows.map_or(0, |rows| total_atoms.min(rows));
2522    use crate::storage_dtype::FloatArray2;
2523    let dt = header.metadata.dtypes();
2524    let mut pos_flat = Vec::new();
2525    let _ = pos_flat.try_reserve_exact(reserve_atoms.saturating_mul(3));
2526    let mut ids = Vec::new();
2527    let _ = ids.try_reserve_exact(reserve_atoms);
2528    let mut atom_data: Vec<AtomDatum> = Vec::new();
2529    let _ = atom_data.try_reserve_exact(reserve_atoms);
2530
2531    let mut global_atom_idx: u64 = 0;
2532    for (type_idx, num_atoms) in header.natms_per_type.iter().enumerate() {
2533        let symbol_line = lines.next().ok_or(ParseError::IncompleteFrame)?;
2534        let symbol: Arc<str> = Arc::from(symbol_line.trim());
2535        let coord_label = lines.next().ok_or(ParseError::IncompleteFrame)?;
2536        if validate {
2537            validate_coordinate_component(type_idx, symbol.as_ref(), coord_label)?;
2538        }
2539        global_atom_idx = ingest_coord_rows_cloned(
2540            lines,
2541            *num_atoms,
2542            header.spec_version,
2543            global_atom_idx,
2544            &symbol,
2545            &mut pos_flat,
2546            &mut ids,
2547            &mut atom_data,
2548        )?;
2549    }
2550    let mut positions = FloatArray2::from_f64_row_major(total_atoms, 3, pos_flat);
2551    positions.project_to(dt.positions);
2552    Ok(crate::types::con_frame_coords_only_with_ids(
2553        header, atom_data, positions, ids,
2554    ))
2555}
2556
2557struct CoordSink<'a> {
2558    pos_flat: &'a mut Vec<f64>,
2559    ids: &'a mut Vec<u64>,
2560    positions_other: &'a mut Option<crate::storage_dtype::FloatArray2>,
2561    atom_data: &'a mut Vec<AtomDatum>,
2562}
2563
2564/// Parse `n` coordinate rows into flat SoA buffers.
2565fn ingest_coord_rows<'a, L>(
2566    lines: &mut L,
2567    n: usize,
2568    spec_version: u32,
2569    global_atom_idx: u64,
2570    symbol: &Arc<str>,
2571    sink: CoordSink<'_>,
2572) -> Result<u64, ParseError>
2573where
2574    L: LineStream<'a>,
2575{
2576    let CoordSink {
2577        pos_flat,
2578        ids,
2579        positions_other,
2580        atom_data,
2581    } = sink;
2582    if positions_other.is_none() {
2583        return ingest_coord_rows_f64(
2584            lines,
2585            n,
2586            spec_version,
2587            global_atom_idx,
2588            symbol,
2589            pos_flat,
2590            ids,
2591            atom_data,
2592        );
2593    }
2594    let mut global_atom_idx = global_atom_idx;
2595    for _ in 0..n {
2596        let (xyz, fixed, atom_id) = lines.next_coord_row(spec_version, global_atom_idx)?;
2597        if let Some(pos) = positions_other.as_mut() {
2598            pos.set_f64_row(ids.len(), xyz);
2599        }
2600        let index = pos_flat.len() / 3;
2601        pos_flat.extend_from_slice(&xyz);
2602        let slot = unsafe { pos_flat.as_mut_ptr().add(index * 3) };
2603        ids.push(atom_id);
2604        atom_data.push(AtomDatum::at_slot(Arc::clone(symbol), slot, fixed, atom_id));
2605        global_atom_idx += 1;
2606    }
2607    Ok(global_atom_idx)
2608}
2609
2610/// Coordinate rows for the f64 storage path.
2611///
2612/// The symbol `Arc` is bumped once for the whole block. Cloning it per atom
2613/// was a visible share of the coordinate parse.
2614#[inline(never)]
2615#[allow(clippy::too_many_arguments)]
2616fn ingest_coord_rows_f64<'a, L>(
2617    lines: &mut L,
2618    n: usize,
2619    spec_version: u32,
2620    mut global_atom_idx: u64,
2621    symbol: &Arc<str>,
2622    pos_flat: &mut Vec<f64>,
2623    ids: &mut Vec<u64>,
2624    atom_data: &mut Vec<AtomDatum>,
2625) -> Result<u64, ParseError>
2626where
2627    L: LineStream<'a>,
2628{
2629    let workers = wide_workers();
2630    if workers >= 2 && n >= 4096 {
2631        if let Some(mut block) =
2632            lines.try_take_coord_block(n, spec_version, global_atom_idx, symbol, workers)
2633        {
2634            let base = pos_flat.len();
2635            // Keep a reservation that covers the whole frame. Replacing it
2636            // with a shorter block makes the next species group reallocate
2637            // under live pointers.
2638            if pos_flat.is_empty() && block.xyz.capacity() >= pos_flat.capacity() {
2639                *pos_flat = block.xyz;
2640            } else {
2641                pos_flat.extend_from_slice(&block.xyz);
2642            }
2643            let ptr = pos_flat.as_mut_ptr();
2644            for (i, atom) in block.atoms.iter_mut().enumerate() {
2645                atom.retarget(unsafe { ptr.add(base + i * 3) });
2646            }
2647            if ids.is_empty() {
2648                *ids = block.ids;
2649            } else {
2650                ids.extend_from_slice(&block.ids);
2651            }
2652            if atom_data.is_empty() {
2653                *atom_data = block.atoms;
2654            } else {
2655                atom_data.extend(block.atoms);
2656            }
2657            return Ok(global_atom_idx + n as u64);
2658        }
2659    }
2660    let mut shares = symbol_shares(symbol, n);
2661    for _ in 0..n {
2662        let (xyz, fixed, atom_id) = lines.next_coord_row(spec_version, global_atom_idx)?;
2663        let sym = shares.take();
2664        let index = pos_flat.len() / 3;
2665        pos_flat.extend_from_slice(&xyz);
2666        let slot = unsafe { pos_flat.as_mut_ptr().add(index * 3) };
2667        ids.push(atom_id);
2668        atom_data.push(AtomDatum::at_slot(sym, slot, fixed, atom_id));
2669        global_atom_idx += 1;
2670    }
2671    Ok(global_atom_idx)
2672}
2673
2674/// Coordinate rows when the declared count must not bump an `Arc` by `n`.
2675fn ingest_coord_rows_cloned<'a, L>(
2676    lines: &mut L,
2677    n: usize,
2678    spec_version: u32,
2679    mut global_atom_idx: u64,
2680    symbol: &Arc<str>,
2681    pos_flat: &mut Vec<f64>,
2682    ids: &mut Vec<u64>,
2683    atom_data: &mut Vec<AtomDatum>,
2684) -> Result<u64, ParseError>
2685where
2686    L: LineStream<'a>,
2687{
2688    for _ in 0..n {
2689        let (xyz, fixed, atom_id) = lines.next_coord_row(spec_version, global_atom_idx)?;
2690        pos_flat.extend_from_slice(&xyz);
2691        ids.push(atom_id);
2692        atom_data.push(AtomDatum::coords(
2693            Arc::clone(symbol),
2694            xyz[0],
2695            xyz[1],
2696            xyz[2],
2697            fixed,
2698            atom_id,
2699        ));
2700        global_atom_idx += 1;
2701    }
2702    Ok(global_atom_idx)
2703}
2704
2705/// `n` extra strong references to `symbol`, taken one at a time.
2706///
2707/// `Arc<str>` stores the header (strong count, weak count) immediately
2708/// before the bytes. One `fetch_add` covers the block; each [`SymbolShares::take`]
2709/// turns one of those counts into an `Arc`. Leftovers drop with the guard.
2710struct SymbolShares {
2711    data: *const u8,
2712    len: usize,
2713    left: usize,
2714}
2715
2716impl SymbolShares {
2717    fn raw(&self) -> *const str {
2718        std::ptr::slice_from_raw_parts(self.data, self.len) as *const str
2719    }
2720
2721    fn take(&mut self) -> Arc<str> {
2722        debug_assert!(self.left > 0);
2723        self.left -= 1;
2724        unsafe { Arc::from_raw(self.raw()) }
2725    }
2726}
2727
2728impl Drop for SymbolShares {
2729    fn drop(&mut self) {
2730        for _ in 0..self.left {
2731            drop(unsafe { Arc::from_raw(self.raw()) });
2732        }
2733        self.left = 0;
2734    }
2735}
2736
2737fn symbol_shares(symbol: &Arc<str>, n: usize) -> SymbolShares {
2738    if n == 0 {
2739        return SymbolShares {
2740            data: std::ptr::null(),
2741            len: 0,
2742            left: 0,
2743        };
2744    }
2745    let data = Arc::as_ptr(symbol);
2746    let offset = arc_str_header(symbol.as_ref());
2747    // SAFETY: `Arc::as_ptr` points at the `str` inside the allocation, and
2748    // the two atomic counts sit in front of it. This is the same subtraction
2749    // `Arc::increment_strong_count` performs, done once for `n` clones.
2750    let bytes = data as *const u8;
2751    let strong = unsafe { bytes.sub(offset) as *const AtomicUsize };
2752    unsafe { (*strong).fetch_add(n, Ordering::Relaxed) };
2753    SymbolShares {
2754        data: bytes,
2755        len: symbol.len(),
2756        left: n,
2757    }
2758}
2759
2760fn arc_str_header(text: &str) -> usize {
2761    let header = 2 * std::mem::size_of::<usize>();
2762    let align = std::mem::align_of_val(text);
2763    let rem = header % align;
2764    if rem == 0 {
2765        header
2766    } else {
2767        header + (align - rem)
2768    }
2769}
2770
2771#[cfg(test)]
2772mod symbol_share_tests {
2773    use super::symbol_shares;
2774    use std::sync::Arc;
2775
2776    #[test]
2777    fn one_bump_matches_n_clones() {
2778        for text in ["", "Cu", "Gold", "a-much-longer-component-symbol"] {
2779            let symbol: Arc<str> = Arc::from(text);
2780            let mut shares = symbol_shares(&symbol, 3);
2781            assert_eq!(Arc::strong_count(&symbol), 4);
2782            let owned = [shares.take(), shares.take(), shares.take()];
2783            assert!(owned.iter().all(|arc| arc.as_ref() == text));
2784            drop(owned);
2785            assert_eq!(Arc::strong_count(&symbol), 1);
2786            let mut partial = symbol_shares(&symbol, 2);
2787            let one = partial.take();
2788            drop(partial);
2789            drop(one);
2790            assert_eq!(Arc::strong_count(&symbol), 1);
2791        }
2792    }
2793}
2794
2795fn validate_header_geometry(boxl: &[f64], angles: &[f64]) -> Result<(), ParseError> {
2796    if boxl
2797        .iter()
2798        .any(|length| !length.is_finite() || *length <= 0.0)
2799        || angles
2800            .iter()
2801            .any(|angle| !angle.is_finite() || *angle <= 0.0 || *angle >= 180.0)
2802    {
2803        return Err(ParseError::ValidationError(
2804            "cell geometry must have positive lengths and angles between 0 and 180 degrees"
2805                .to_string(),
2806        ));
2807    }
2808    Ok(())
2809}
2810
2811fn validate_masses(masses_per_type: &[f64]) -> Result<(), ParseError> {
2812    if masses_per_type
2813        .iter()
2814        .any(|mass| !mass.is_finite() || *mass <= 0.0)
2815    {
2816        return Err(ParseError::ValidationError(
2817            "component masses must be positive".to_string(),
2818        ));
2819    }
2820    Ok(())
2821}
2822
2823fn validate_coordinate_component(
2824    type_idx: usize,
2825    symbol: &str,
2826    label: &str,
2827) -> Result<(), ParseError> {
2828    let expected_label = format!("Coordinates of Component {}", type_idx + 1);
2829    if !labels_equal(label, &expected_label) {
2830        return Err(ParseError::ValidationError(format!(
2831            "expected coordinate label {expected_label:?}, found {label:?}"
2832        )));
2833    }
2834    if symbol != "X" && symbol_to_atomic_number(symbol) == 0 {
2835        return Err(ParseError::ValidationError(format!(
2836            "unknown component symbol {symbol}"
2837        )));
2838    }
2839    Ok(())
2840}
2841
2842fn validate_section_component(
2843    section: &str,
2844    type_idx: usize,
2845    atom_idx: usize,
2846    symbol: &str,
2847    label: &str,
2848    header: &FrameHeader,
2849    atom_data: &[AtomDatum],
2850) -> Result<(), ParseError> {
2851    let expected_label = format!("{section} of Component {}", type_idx + 1);
2852    if !labels_equal(label, &expected_label) {
2853        return Err(ParseError::ValidationError(format!(
2854            "expected section label {expected_label:?}, found {label:?}"
2855        )));
2856    }
2857
2858    if header.natms_per_type[type_idx] == 0 {
2859        return Ok(());
2860    }
2861
2862    let expected_symbol = atom_data
2863        .get(atom_idx)
2864        .map(|atom| atom.symbol.as_ref())
2865        .ok_or_else(|| {
2866            ParseError::ValidationError(format!(
2867                "{section} component {} has no coordinate atom to validate against",
2868                type_idx + 1
2869            ))
2870        })?;
2871    if symbol != expected_symbol {
2872        return Err(ParseError::ValidationError(format!(
2873            "{section} component {} symbol mismatch: expected {expected_symbol}, found {symbol}",
2874            type_idx + 1
2875        )));
2876    }
2877
2878    Ok(())
2879}
2880
2881fn validate_section_atom_identity(
2882    section: &str,
2883    atom_idx: usize,
2884    fixed: [bool; 3],
2885    atom_id: u64,
2886    atom_data: &[AtomDatum],
2887) -> Result<(), ParseError> {
2888    let atom = atom_data.get(atom_idx).ok_or_else(|| {
2889        ParseError::ValidationError(format!(
2890            "{section} row {atom_idx} has no coordinate atom to validate against"
2891        ))
2892    })?;
2893
2894    if atom.fixed() != fixed {
2895        return Err(ParseError::ValidationError(format!(
2896            "{section} row {atom_idx} fixed mask mismatch for atom_id {}",
2897            atom.atom_id
2898        )));
2899    }
2900    if atom.atom_id != atom_id {
2901        return Err(ParseError::ValidationError(format!(
2902            "{section} row {atom_idx} atom_id mismatch: expected {}, found {atom_id}",
2903            atom.atom_id
2904        )));
2905    }
2906
2907    Ok(())
2908}
2909
2910/// Consume the single blank line that opens a section.
2911///
2912/// A blank line followed only by whitespace to EOF does not open a section
2913/// (CON-frame.5). The lines stay in the stream.
2914fn frame_minor(header: &FrameHeader) -> u64 {
2915    header.metadata.spec_minor()
2916}
2917
2918fn section_row_arity(header: &FrameHeader, name: &str) -> Option<usize> {
2919    let obj = header.metadata.get(meta::SECTION_ARITY)?.as_object()?;
2920    let n = obj.get(name)?.as_u64()?;
2921    if n >= 1 { Some(n as usize) } else { None }
2922}
2923
2924/// Skip one unknown section of a newer minor.
2925///
2926/// `arity` is the value-field count (CON-section.12). Each data row holds
2927/// that many values, then the flag, and an optional id, so the row has
2928/// `arity + 1` or `arity + 2` tokens (CON-section.14). The label is the
2929/// section name under CON-file.5, then `of Component N` (CON-section.15).
2930fn skip_unknown_section<'a>(
2931    lines: &mut impl LineStream<'a>,
2932    header: &FrameHeader,
2933    name: &str,
2934    arity: usize,
2935) -> Result<(), ParseError> {
2936    if !open_section(lines)? {
2937        return Err(ParseError::IncompleteSection(name.to_string()));
2938    }
2939    let with_flag = arity.saturating_add(1);
2940    let with_id = arity.saturating_add(2);
2941    for (type_idx, &num_atoms) in header.natms_per_type.iter().enumerate() {
2942        if lines.next_line().is_none() {
2943            return Err(ParseError::IncompleteSection(name.to_string()));
2944        }
2945        let label = lines
2946            .next_line()
2947            .ok_or_else(|| ParseError::IncompleteSection(name.to_string()))?;
2948        let expected = format!("{name} of Component {}", type_idx + 1);
2949        if !labels_equal(label, &expected) {
2950            return Err(ParseError::IncompleteSection(name.to_string()));
2951        }
2952        for _ in 0..num_atoms {
2953            let row = lines
2954                .next_line()
2955                .ok_or_else(|| ParseError::IncompleteSection(name.to_string()))?;
2956            let found = token_count(row);
2957            if found != with_flag && found != with_id {
2958                let expected = if found < with_flag {
2959                    with_flag
2960                } else {
2961                    with_id
2962                };
2963                return Err(ParseError::InvalidVectorLength { expected, found });
2964            }
2965        }
2966    }
2967    Ok(())
2968}
2969
2970fn open_section<'a>(lines: &mut impl LineStream<'a>) -> Result<bool, ParseError> {
2971    match lines.peek_line() {
2972        Some(line) if line.trim().is_empty() => {
2973            if lines.remainder_is_whitespace() {
2974                return Ok(false);
2975            }
2976            lines.next_line();
2977            Ok(true)
2978        }
2979        _ => Ok(false),
2980    }
2981}
2982
2983/// Attempts to parse an optional velocity section following coordinate blocks.
2984///
2985/// In `.convel` files, after all coordinate blocks there is a blank separator line
2986/// followed by per-component velocity blocks with the same structure as coordinate
2987/// blocks (symbol line, "Velocities of Component N" line, then atom lines with
2988/// `vx vy vz fixed atomID`).
2989///
2990/// This function peeks at the next line. If it is blank (or contains only whitespace),
2991/// it consumes the blank line and writes each velocity into `column` (row-major
2992/// `n * 3` `f64`s, one allocation). If the next line is not blank (or is absent),
2993/// no velocities are parsed and `column` is left untouched.
2994///
2995/// Returns `Ok(true)` if velocities were found and parsed, `Ok(false)` otherwise.
2996pub fn parse_velocity_section<'a>(
2997    lines: &mut impl LineStream<'a>,
2998    header: &FrameHeader,
2999    atom_data: &mut [AtomDatum],
3000    column: &mut Vec<f64>,
3001) -> Result<bool, ParseError> {
3002    let validate = header.strict_validation;
3003    // A blank line followed only by whitespace to EOF is not a velocity
3004    // block (CON-frame.5, D2). Leave those lines for the iterator.
3005    match lines.peek_line() {
3006        Some(line) if line.trim().is_empty() => {
3007            if lines.remainder_is_whitespace() {
3008                return Ok(false);
3009            }
3010            // CON-section.2 / the legacy fallback: the blank counts only
3011            // when it begins a complete velocity block. Otherwise it is
3012            // line 1 of the next frame (CON-frame.7, CON-header.4).
3013            if !lines.blank_line_opens_section() {
3014                return Ok(false);
3015            }
3016            lines.next_line();
3017        }
3018        _ => return Ok(false),
3019    }
3020
3021    let n = atom_data.len();
3022    column.clear();
3023    column.resize(n.saturating_mul(3), 0.0);
3024    let mut atom_idx: usize = 0;
3025    for (type_idx, &num_atoms) in header.natms_per_type.iter().enumerate() {
3026        // Symbol line
3027        let symbol = lines
3028            .next_line()
3029            .ok_or(ParseError::IncompleteSection(SECTION_VELOCITIES.into()))?
3030            .trim();
3031
3032        // "Velocities of Component N" line
3033        let comp_line = lines
3034            .next_line()
3035            .ok_or(ParseError::IncompleteSection(SECTION_VELOCITIES.into()))?;
3036        if !label_has_prefix(comp_line, "Velocities of Component") {
3037            return Err(ParseError::IncompleteSection(SECTION_VELOCITIES.into()));
3038        }
3039        if validate {
3040            validate_section_component(
3041                "Velocities",
3042                type_idx,
3043                atom_idx,
3044                symbol,
3045                comp_line,
3046                header,
3047                atom_data,
3048            )?;
3049        }
3050
3051        for _ in 0..num_atoms {
3052            let (vals, fixed, atom_id) =
3053                take_vector_row(lines, header.spec_version, SECTION_VELOCITIES)?;
3054            if validate {
3055                validate_section_atom_identity("velocities", atom_idx, fixed, atom_id, atom_data)?;
3056            }
3057            if atom_idx < n {
3058                let base = atom_idx * 3;
3059                column[base] = vals[0];
3060                column[base + 1] = vals[1];
3061                column[base + 2] = vals[2];
3062            }
3063            atom_idx += 1;
3064        }
3065    }
3066
3067    Ok(true)
3068}
3069
3070/// Attempts to parse a force section following coordinate (and optional velocity) blocks.
3071///
3072/// Force sections mirror velocity sections: a blank separator line followed by per-component
3073/// force blocks (symbol line, "Forces of Component N" line, then atom lines with
3074/// `fx fy fz fixed_flag atom_id`).
3075///
3076/// Returns `Ok(true)` if forces were found and parsed, `Ok(false)` otherwise.
3077pub fn parse_force_section<'a>(
3078    lines: &mut impl LineStream<'a>,
3079    header: &FrameHeader,
3080    atom_data: &mut [AtomDatum],
3081    column: &mut Vec<f64>,
3082) -> Result<bool, ParseError> {
3083    let validate = header.strict_validation;
3084    if !open_section(lines)? {
3085        return Ok(false);
3086    }
3087
3088    let n = atom_data.len();
3089    column.clear();
3090    column.resize(n.saturating_mul(3), 0.0);
3091    let mut atom_idx: usize = 0;
3092    for (type_idx, &num_atoms) in header.natms_per_type.iter().enumerate() {
3093        let symbol = lines
3094            .next_line()
3095            .ok_or(ParseError::IncompleteSection(SECTION_FORCES.into()))?
3096            .trim();
3097
3098        let comp_line = lines
3099            .next_line()
3100            .ok_or(ParseError::IncompleteSection(SECTION_FORCES.into()))?;
3101        if !label_has_prefix(comp_line, "Forces of Component") {
3102            return Err(ParseError::IncompleteSection(SECTION_FORCES.into()));
3103        }
3104        if validate {
3105            validate_section_component(
3106                "Forces", type_idx, atom_idx, symbol, comp_line, header, atom_data,
3107            )?;
3108        }
3109
3110        for _ in 0..num_atoms {
3111            let (vals, fixed, atom_id) =
3112                take_vector_row(lines, header.spec_version, SECTION_FORCES)?;
3113            if validate {
3114                validate_section_atom_identity("forces", atom_idx, fixed, atom_id, atom_data)?;
3115            }
3116            if atom_idx < n {
3117                let base = atom_idx * 3;
3118                column[base] = vals[0];
3119                column[base + 1] = vals[1];
3120                column[base + 2] = vals[2];
3121            }
3122            atom_idx += 1;
3123        }
3124    }
3125
3126    Ok(true)
3127}
3128
3129/// Attempts to parse an energies section following coordinate (and optional
3130/// velocity / force) blocks.
3131///
3132/// Energy sections mirror force sections but with one scalar per atom:
3133/// blank separator, then per-component blocks of (symbol, "Energies of
3134/// Component N", and atom lines `e fixed_flag atom_id`). The two
3135/// trailing identity columns are optional and used only for strict
3136/// validation; in non-strict mode any whitespace after the energy is
3137/// ignored.
3138///
3139/// Returns `Ok(true)` if energies were found and parsed, `Ok(false)`
3140/// otherwise.
3141pub fn parse_energy_section<'a>(
3142    lines: &mut impl LineStream<'a>,
3143    header: &FrameHeader,
3144    atom_data: &mut [AtomDatum],
3145) -> Result<bool, ParseError> {
3146    let validate = header.strict_validation;
3147    if !open_section(lines)? {
3148        return Ok(false);
3149    }
3150
3151    let mut atom_idx: usize = 0;
3152    for (type_idx, &num_atoms) in header.natms_per_type.iter().enumerate() {
3153        let symbol = lines
3154            .next_line()
3155            .ok_or(ParseError::IncompleteSection(SECTION_ENERGIES.into()))?
3156            .trim();
3157
3158        let comp_line = lines
3159            .next_line()
3160            .ok_or(ParseError::IncompleteSection(SECTION_ENERGIES.into()))?;
3161        if !label_has_prefix(comp_line, "Energies of Component") {
3162            return Err(ParseError::IncompleteSection(SECTION_ENERGIES.into()));
3163        }
3164        if validate {
3165            validate_section_component(
3166                "Energies", type_idx, atom_idx, symbol, comp_line, header, atom_data,
3167            )?;
3168        }
3169
3170        for _ in 0..num_atoms {
3171            let energy_line = lines
3172                .next_line()
3173                .ok_or(ParseError::IncompleteSection(SECTION_ENERGIES.into()))?;
3174            let (value, fixed, atom_id) =
3175                parse_scalar_section_row(energy_line, header.spec_version)?;
3176            if validate {
3177                validate_section_atom_identity("energies", atom_idx, fixed, atom_id, atom_data)?;
3178            }
3179            if atom_idx < atom_data.len() {
3180                atom_data[atom_idx].set_energy(Some(value));
3181            }
3182            atom_idx += 1;
3183        }
3184    }
3185
3186    Ok(true)
3187}
3188
3189/// Parses declared sections from a frame's header metadata.
3190///
3191/// If `header.sections` is non-empty (v2 file with `"sections"` key in JSON),
3192/// parses each declared section in order. Otherwise falls back to legacy
3193/// blank-separator velocity detection.
3194pub fn parse_declared_sections<'a>(
3195    lines: &mut impl LineStream<'a>,
3196    frame: &mut ConFrame,
3197) -> Result<usize, ParseError> {
3198    let mut applied = 0usize;
3199    // A zero-atom frame has no coordinate block and no section block.
3200    // The legacy velocity fallback must not run (CON-count.1).
3201    if frame.header.natm_types == 0 {
3202        if !frame.header.sections.is_empty() {
3203            return Err(ParseError::InvalidCount(
3204                "a zero-atom frame cannot declare sections".into(),
3205            ));
3206        }
3207        return Ok(0);
3208    }
3209    if !frame.header.sections_declared && frame.header.sections.is_empty() {
3210        // Legacy: try velocity detection via blank separator. A blank
3211        // line can also be the empty line 1 of the next frame, so look for
3212        // the velocity label before committing (CON-frame.5).
3213        let mut column = Vec::new();
3214        let found = lines.blank_opens_velocity_block()
3215            && parse_velocity_section(lines, &frame.header, &mut frame.atom_data, &mut column)?;
3216        if found {
3217            frame.adopt_velocity_column(column);
3218            frame.header.sections.push(SECTION_VELOCITIES.into());
3219            applied = 1;
3220        }
3221    } else {
3222        let sections = std::mem::take(&mut frame.header.sections);
3223        for section in &sections {
3224            match section.as_str() {
3225                SECTION_VELOCITIES => {
3226                    let mut column = Vec::new();
3227                    let found = parse_velocity_section(
3228                        lines,
3229                        &frame.header,
3230                        &mut frame.atom_data,
3231                        &mut column,
3232                    )?;
3233                    if !found {
3234                        return Err(ParseError::IncompleteSection(SECTION_VELOCITIES.into()));
3235                    }
3236                    frame.adopt_velocity_column(column);
3237                    applied += 1;
3238                }
3239                SECTION_FORCES => {
3240                    let mut column = Vec::new();
3241                    let found = parse_force_section(
3242                        lines,
3243                        &frame.header,
3244                        &mut frame.atom_data,
3245                        &mut column,
3246                    )?;
3247                    if !found {
3248                        return Err(ParseError::IncompleteSection(SECTION_FORCES.into()));
3249                    }
3250                    frame.adopt_force_column(column);
3251                    applied += 1;
3252                }
3253                SECTION_ENERGIES => {
3254                    let found = parse_energy_section(lines, &frame.header, &mut frame.atom_data)?;
3255                    if !found {
3256                        return Err(ParseError::IncompleteSection(SECTION_ENERGIES.into()));
3257                    }
3258                    applied += 1;
3259                }
3260                SECTION_CHARGES => {
3261                    let found = parse_charge_section(lines, &frame.header, &mut frame.atom_data)?;
3262                    if !found {
3263                        return Err(ParseError::IncompleteSection(SECTION_CHARGES.into()));
3264                    }
3265                    applied += 1;
3266                }
3267                SECTION_SPINS => {
3268                    let found = parse_spin_section(lines, &frame.header, &mut frame.atom_data)?;
3269                    if !found {
3270                        return Err(ParseError::IncompleteSection(SECTION_SPINS.into()));
3271                    }
3272                    applied += 1;
3273                }
3274                SECTION_MAGMOMS => {
3275                    let found = parse_magmom_section(lines, &frame.header, &mut frame.atom_data)?;
3276                    if !found {
3277                        return Err(ParseError::IncompleteSection(SECTION_MAGMOMS.into()));
3278                    }
3279                    applied += 1;
3280                }
3281                SECTION_DISPLACEMENTS => {
3282                    let found =
3283                        parse_displacement_section(lines, &frame.header, &mut frame.atom_data)?;
3284                    if !found {
3285                        return Err(ParseError::IncompleteSection(SECTION_DISPLACEMENTS.into()));
3286                    }
3287                    applied += 1;
3288                }
3289                SECTION_SPREADS => {
3290                    let found = parse_spread_section(lines, &frame.header, &mut frame.atom_data)?;
3291                    if !found {
3292                        return Err(ParseError::IncompleteSection(SECTION_SPREADS.into()));
3293                    }
3294                    applied += 1;
3295                }
3296                other => {
3297                    if frame_minor(&frame.header) > u64::from(crate::CON_SPEC_MINOR)
3298                        && let Some(arity) = section_row_arity(&frame.header, other)
3299                    {
3300                        skip_unknown_section(lines, &frame.header, other, arity)?;
3301                        continue;
3302                    }
3303                    return Err(ParseError::UnknownSection(other.to_string()));
3304                }
3305            }
3306        }
3307        frame.header.sections = sections;
3308    }
3309    reject_velocities_without_time(&frame.header)?;
3310    Ok(applied)
3311}
3312
3313/// CON-units.11. Versions 1, 2, and 3.0 do not require `units.time`
3314/// (CON-units.8, CON-units.9). From minor 1 the key is required when a
3315/// velocities section is present.
3316fn reject_velocities_without_time(header: &FrameHeader) -> Result<(), ParseError> {
3317    if header.spec_version < 3 || frame_minor(header) < 1 {
3318        return Ok(());
3319    }
3320    if !header
3321        .sections
3322        .iter()
3323        .any(|name| name == SECTION_VELOCITIES)
3324    {
3325        return Ok(());
3326    }
3327    let time_ok = header
3328        .metadata
3329        .get(meta::UNITS)
3330        .and_then(|units| units.get("time"))
3331        .and_then(|value| value.as_str())
3332        .is_some_and(|unit| !unit.trim().is_empty());
3333    if time_ok {
3334        Ok(())
3335    } else {
3336        Err(ParseError::InvalidUnits(
3337            "minor >= 1 requires units.time when a velocities section is present".into(),
3338        ))
3339    }
3340}
3341
3342/// Scalar per-atom section: blank separator + per-type blocks
3343/// (`symbol`, `"X of Component N"`, lines `value fixed atom_id`).
3344fn parse_scalar_atom_section<'a>(
3345    lines: &mut impl LineStream<'a>,
3346    header: &FrameHeader,
3347    atom_data: &mut [AtomDatum],
3348    section_name: &str,
3349    component_label: &str,
3350    mut set_value: impl FnMut(&mut AtomDatum, f64),
3351) -> Result<bool, ParseError> {
3352    let validate = header.strict_validation;
3353    if !open_section(lines)? {
3354        return Ok(false);
3355    }
3356
3357    let mut atom_idx: usize = 0;
3358    for (type_idx, &num_atoms) in header.natms_per_type.iter().enumerate() {
3359        let symbol = lines
3360            .next_line()
3361            .ok_or_else(|| ParseError::IncompleteSection(section_name.into()))?
3362            .trim();
3363
3364        let comp_line = lines
3365            .next_line()
3366            .ok_or_else(|| ParseError::IncompleteSection(section_name.into()))?;
3367        if !label_has_prefix(comp_line, component_label) {
3368            return Err(ParseError::IncompleteSection(section_name.into()));
3369        }
3370        if validate {
3371            validate_section_component(
3372                component_label.trim_end_matches(" of Component").trim(),
3373                type_idx,
3374                atom_idx,
3375                symbol,
3376                comp_line,
3377                header,
3378                atom_data,
3379            )?;
3380        }
3381
3382        for _ in 0..num_atoms {
3383            let data_line = lines
3384                .next_line()
3385                .ok_or_else(|| ParseError::IncompleteSection(section_name.into()))?;
3386            let (value, fixed, atom_id) = parse_scalar_section_row(data_line, header.spec_version)?;
3387            if validate {
3388                validate_section_atom_identity(section_name, atom_idx, fixed, atom_id, atom_data)?;
3389            }
3390            if atom_idx < atom_data.len() {
3391                set_value(&mut atom_data[atom_idx], value);
3392            }
3393            atom_idx += 1;
3394        }
3395    }
3396    Ok(true)
3397}
3398
3399pub fn parse_charge_section<'a>(
3400    lines: &mut impl LineStream<'a>,
3401    header: &FrameHeader,
3402    atom_data: &mut [AtomDatum],
3403) -> Result<bool, ParseError> {
3404    parse_scalar_atom_section(
3405        lines,
3406        header,
3407        atom_data,
3408        SECTION_CHARGES,
3409        "Charges of Component",
3410        |a, v| a.set_charge(Some(v)),
3411    )
3412}
3413
3414pub fn parse_spin_section<'a>(
3415    lines: &mut impl LineStream<'a>,
3416    header: &FrameHeader,
3417    atom_data: &mut [AtomDatum],
3418) -> Result<bool, ParseError> {
3419    parse_scalar_atom_section(
3420        lines,
3421        header,
3422        atom_data,
3423        SECTION_SPINS,
3424        "Spins of Component",
3425        |a, v| a.set_spin(Some(v)),
3426    )
3427}
3428
3429fn parse_vector_named_section<'a>(
3430    lines: &mut impl LineStream<'a>,
3431    header: &FrameHeader,
3432    atom_data: &mut [AtomDatum],
3433    names: (&str, &str, &str),
3434    mut set_value: impl FnMut(&mut AtomDatum, [f64; 3]),
3435    mut check_row: impl FnMut(usize, [f64; 3]) -> Result<(), ParseError>,
3436) -> Result<bool, ParseError> {
3437    let (section_name, component_label, label_kind) = names;
3438    let validate = header.strict_validation;
3439    if !open_section(lines)? {
3440        return Ok(false);
3441    }
3442    let mut atom_idx: usize = 0;
3443    for (type_idx, &num_atoms) in header.natms_per_type.iter().enumerate() {
3444        let symbol = lines
3445            .next_line()
3446            .ok_or_else(|| ParseError::IncompleteSection(section_name.into()))?
3447            .trim();
3448        let comp_line = lines
3449            .next_line()
3450            .ok_or_else(|| ParseError::IncompleteSection(section_name.into()))?;
3451        if !label_has_prefix(comp_line, component_label) {
3452            return Err(ParseError::IncompleteSection(section_name.into()));
3453        }
3454        if validate {
3455            validate_section_component(
3456                label_kind, type_idx, atom_idx, symbol, comp_line, header, atom_data,
3457            )?;
3458        }
3459        for _ in 0..num_atoms {
3460            let (vals, fixed, atom_id) = take_vector_row(lines, header.spec_version, section_name)?;
3461            check_row(atom_idx, vals)?;
3462            if validate {
3463                validate_section_atom_identity(section_name, atom_idx, fixed, atom_id, atom_data)?;
3464            }
3465            if atom_idx < atom_data.len() {
3466                set_value(&mut atom_data[atom_idx], vals);
3467            }
3468            atom_idx += 1;
3469        }
3470    }
3471    Ok(true)
3472}
3473
3474/// Magmoms: 3-vector per atom, same layout as velocities/forces.
3475pub fn parse_magmom_section<'a>(
3476    lines: &mut impl LineStream<'a>,
3477    header: &FrameHeader,
3478    atom_data: &mut [AtomDatum],
3479) -> Result<bool, ParseError> {
3480    parse_vector_named_section(
3481        lines,
3482        header,
3483        atom_data,
3484        (SECTION_MAGMOMS, "Magmoms of Component", "Magmoms"),
3485        |a, v| a.set_magmom(Some(v)),
3486        |_, _| Ok(()),
3487    )
3488}
3489
3490/// Displacements: 3-vector per atom (Angstrom), same layout as velocities/forces.
3491pub fn parse_displacement_section<'a>(
3492    lines: &mut impl LineStream<'a>,
3493    header: &FrameHeader,
3494    atom_data: &mut [AtomDatum],
3495) -> Result<bool, ParseError> {
3496    parse_vector_named_section(
3497        lines,
3498        header,
3499        atom_data,
3500        (
3501            SECTION_DISPLACEMENTS,
3502            "Displacements of Component",
3503            "Displacements",
3504        ),
3505        |a, v| a.set_displacement(Some(v)),
3506        |_, _| Ok(()),
3507    )
3508}
3509
3510/// Spreads: per-atom root-mean-square spread `[sx, sy, sz]` (Angstrom, each
3511/// non-negative), same layout as velocities/forces.
3512pub fn parse_spread_section<'a>(
3513    lines: &mut impl LineStream<'a>,
3514    header: &FrameHeader,
3515    atom_data: &mut [AtomDatum],
3516) -> Result<bool, ParseError> {
3517    parse_vector_named_section(
3518        lines,
3519        header,
3520        atom_data,
3521        (SECTION_SPREADS, "Spreads of Component", "Spreads"),
3522        |a, v| a.set_spread(Some(v)),
3523        |atom_idx, vals| {
3524            if !vals.iter().all(|v| v.is_finite()) {
3525                return Err(ParseError::NonFiniteValue(format!(
3526                    "spreads atom {atom_idx}"
3527                )));
3528            }
3529            if vals.iter().any(|v| *v < 0.0) {
3530                return Err(crate::types::invalid_spread(atom_idx));
3531            }
3532            Ok(())
3533        },
3534    )
3535}
3536
3537#[cfg(test)]
3538mod tests {
3539    use super::*;
3540    use crate::iterators::ConFrameIterator;
3541
3542    #[test]
3543    fn test_parse_line_of_n_success() {
3544        let line = "1.0 2.5 -3.0";
3545        let values = parse_line_of_n::<f64>(line, 3).unwrap();
3546        assert_eq!(values, vec![1.0, 2.5, -3.0]);
3547    }
3548
3549    #[test]
3550    fn test_parse_line_of_n_too_short() {
3551        let line = "1.0 2.5";
3552        let result = parse_line_of_n::<f64>(line, 3);
3553        assert!(result.is_err());
3554        assert!(matches!(
3555            result.unwrap_err(),
3556            ParseError::InvalidVectorLength {
3557                expected: 3,
3558                found: 2
3559            }
3560        ));
3561    }
3562
3563    #[test]
3564    fn test_parse_line_of_n_too_long() {
3565        let line = "1.0 2.5 -3.0 4.0";
3566        let result = parse_line_of_n::<f64>(line, 3);
3567        assert!(result.is_err());
3568        assert!(matches!(
3569            result.unwrap_err(),
3570            ParseError::InvalidVectorLength {
3571                expected: 3,
3572                found: 4
3573            }
3574        ));
3575    }
3576
3577    #[test]
3578    fn test_parse_line_of_n_invalid_float() {
3579        let line = "1.0 abc -3.0";
3580        let result = parse_line_of_n::<f64>(line, 3);
3581        assert!(result.is_err());
3582        assert!(matches!(
3583            result.unwrap_err(),
3584            ParseError::InvalidNumberFormat(_)
3585        ));
3586    }
3587
3588    #[test]
3589    fn test_parse_frame_header_success() {
3590        let lines = [
3591            "PREBOX1",
3592            "{\"con_spec_version\":2}",
3593            "10.0 20.0 30.0",
3594            "90.0 90.0 90.0",
3595            "POSTBOX1",
3596            "POSTBOX2",
3597            "2",
3598            "1 1",
3599            "12.011 1.008",
3600        ];
3601        let mut line_it = lines.iter().copied();
3602        match parse_frame_header(&mut line_it) {
3603            Ok(header) => {
3604                assert_eq!(header.prebox_header.user, "PREBOX1");
3605                assert_eq!(header.spec_version, 2);
3606                assert_eq!(header.boxl, [10.0, 20.0, 30.0]);
3607                assert_eq!(header.angles, [90.0, 90.0, 90.0]);
3608                assert_eq!(header.postbox_header, ["POSTBOX1", "POSTBOX2"]);
3609                assert_eq!(header.natm_types, 2);
3610                assert_eq!(header.natms_per_type, vec![1, 1]);
3611                assert_eq!(header.masses_per_type, vec![12.011, 1.008]);
3612            }
3613            Err(e) => {
3614                panic!("Parsing failed when it should have succeeded. Error: {e:?}");
3615            }
3616        }
3617    }
3618
3619    #[test]
3620    fn test_parse_frame_header_missing_line() {
3621        let lines = [
3622            "PREBOX1",
3623            "{\"con_spec_version\":2}",
3624            "10.0 20.0 30.0",
3625            "90.0 90.0 90.0",
3626            "POSTBOX1",
3627            "POSTBOX2",
3628            "2",
3629            "1 1",
3630            // Missing masses_per_type
3631        ];
3632        let mut line_it = lines.iter().copied();
3633        let result = parse_frame_header(&mut line_it);
3634        assert!(result.is_err());
3635        assert!(matches!(result.unwrap_err(), ParseError::IncompleteHeader));
3636    }
3637
3638    #[test]
3639    fn test_parse_frame_header_missing_spec_version() {
3640        let lines = [
3641            "PREBOX1",
3642            "{}",
3643            "10.0 20.0 30.0",
3644            "90.0 90.0 90.0",
3645            "POSTBOX1",
3646            "POSTBOX2",
3647            "2",
3648            "1 1",
3649            "12.011 1.008",
3650        ];
3651        let mut line_it = lines.iter().copied();
3652        let result = parse_frame_header(&mut line_it);
3653        assert!(result.is_err());
3654        assert!(matches!(
3655            result.unwrap_err(),
3656            ParseError::MissingSpecVersion
3657        ));
3658    }
3659
3660    #[test]
3661    fn test_parse_frame_header_legacy_no_json() {
3662        // A non-JSON line 2 is treated as a legacy (v1) file.
3663        let lines = [
3664            "PREBOX1",
3665            "0.0000 TIME",
3666            "10.0 20.0 30.0",
3667            "90.0 90.0 90.0",
3668            "POSTBOX1",
3669            "POSTBOX2",
3670            "2",
3671            "1 1",
3672            "12.011 1.008",
3673        ];
3674        let mut line_it = lines.iter().copied();
3675        let header = parse_frame_header(&mut line_it).unwrap();
3676        assert_eq!(header.spec_version, 1);
3677        assert!(header.metadata.is_empty());
3678    }
3679
3680    #[test]
3681    fn test_parse_frame_header_malformed_json() {
3682        // Line 2 starts with '{' but is not valid JSON -- this IS an error.
3683        let lines = [
3684            "PREBOX1",
3685            "{broken json",
3686            "10.0 20.0 30.0",
3687            "90.0 90.0 90.0",
3688            "POSTBOX1",
3689            "POSTBOX2",
3690            "2",
3691            "1 1",
3692            "12.011 1.008",
3693        ];
3694        let mut line_it = lines.iter().copied();
3695        let result = parse_frame_header(&mut line_it);
3696        assert!(result.is_err());
3697        assert!(matches!(
3698            result.unwrap_err(),
3699            ParseError::InvalidMetadataJson(_)
3700        ));
3701    }
3702
3703    #[test]
3704    fn test_parse_frame_header_unsupported_version() {
3705        let lines = [
3706            "PREBOX1",
3707            "{\"con_spec_version\":999}",
3708            "10.0 20.0 30.0",
3709            "90.0 90.0 90.0",
3710            "POSTBOX1",
3711            "POSTBOX2",
3712            "2",
3713            "1 1",
3714            "12.011 1.008",
3715        ];
3716        let mut line_it = lines.iter().copied();
3717        let result = parse_frame_header(&mut line_it);
3718        assert!(result.is_err());
3719        assert!(matches!(
3720            result.unwrap_err(),
3721            ParseError::UnsupportedVersion(999)
3722        ));
3723    }
3724
3725    #[test]
3726    fn test_v3_missing_units_rejected() {
3727        let lines = [
3728            "PREBOX1",
3729            "{\"con_spec_version\":3}",
3730            "10.0 20.0 30.0",
3731            "90.0 90.0 90.0",
3732            "POSTBOX1",
3733            "POSTBOX2",
3734            "1",
3735            "1",
3736            "1.0",
3737        ];
3738        let mut line_it = lines.iter().copied();
3739        let err = parse_frame_header(&mut line_it).unwrap_err();
3740        let msg = err.to_string();
3741        assert!(
3742            msg.contains("units") || msg.contains("v3"),
3743            "expected units error, got {msg}"
3744        );
3745    }
3746
3747    #[test]
3748    fn test_v3_invalid_units_rejected() {
3749        let lines = [
3750            "PREBOX1",
3751            r#"{"con_spec_version":3,"units":{"length":"eV","energy":"angstrom"}}"#,
3752            "10.0 20.0 30.0",
3753            "90.0 90.0 90.0",
3754            "POSTBOX1",
3755            "POSTBOX2",
3756            "1",
3757            "1",
3758            "1.0",
3759        ];
3760        let mut line_it = lines.iter().copied();
3761        assert!(parse_frame_header(&mut line_it).is_err());
3762    }
3763
3764    #[test]
3765    fn test_v3_valid_units_exposes_length_energy() {
3766        let lines = [
3767            "PREBOX1",
3768            r#"{"con_spec_version":3,"units":{"length":"angstrom","energy":"eV","mass":"amu","time":"fs"}}"#,
3769            "10.0 20.0 30.0",
3770            "90.0 90.0 90.0",
3771            "POSTBOX1",
3772            "POSTBOX2",
3773            "1",
3774            "1",
3775            "1.0",
3776        ];
3777        let mut line_it = lines.iter().copied();
3778        let header = parse_frame_header(&mut line_it).unwrap();
3779        assert_eq!(header.spec_version, 3);
3780        assert_eq!(header.length_unit(), Some("angstrom"));
3781        assert_eq!(header.energy_unit(), Some("eV"));
3782        let f = header.conversion_factor_to("length", "nm").unwrap();
3783        assert!((f - 0.1).abs() < 1e-12);
3784    }
3785
3786    #[test]
3787    fn test_parse_frame_header_extra_metadata_preserved() {
3788        let lines = [
3789            "PREBOX1",
3790            "{\"con_spec_version\":2,\"generator\":\"test\"}",
3791            "10.0 20.0 30.0",
3792            "90.0 90.0 90.0",
3793            "POSTBOX1",
3794            "POSTBOX2",
3795            "2",
3796            "1 1",
3797            "12.011 1.008",
3798        ];
3799        let mut line_it = lines.iter().copied();
3800        let header = parse_frame_header(&mut line_it).unwrap();
3801        assert_eq!(header.spec_version, 2);
3802        assert_eq!(
3803            header.metadata.get("generator"),
3804            Some(&serde_json::Value::String("test".to_string()))
3805        );
3806    }
3807
3808    #[test]
3809    fn test_parse_frame_header_invalid_natms_per_type() {
3810        let lines = [
3811            "PREBOX1",
3812            "{\"con_spec_version\":2}",
3813            "10.0 20.0 30.0",
3814            "90.0 90.0 90.0",
3815            "POSTBOX1",
3816            "POSTBOX2",
3817            "2",
3818            "1 1 1", // 3 values, but natm_types is 2
3819            "12.011 1.008",
3820        ];
3821        let mut line_it = lines.iter().copied();
3822        let result = parse_frame_header(&mut line_it);
3823        assert!(result.is_err());
3824        assert!(matches!(
3825            result.unwrap_err(),
3826            ParseError::InvalidVectorLength {
3827                expected: 2,
3828                found: 3
3829            }
3830        ));
3831    }
3832
3833    #[test]
3834    fn test_parse_single_frame_success() {
3835        let lines = vec![
3836            "PREBOX1",
3837            "{\"con_spec_version\":2}",
3838            "10.0 20.0 30.0",
3839            "90.0 90.0 90.0",
3840            "POSTBOX1",
3841            "POSTBOX2",
3842            "2",
3843            "3 3",
3844            "12.011 1.008",
3845            "1",
3846            "Coordinates of Component 1",
3847            "0.0 0.0 0.0 0 1",
3848            "1.0940 0.0 0.0 0 2",
3849            "-0.5470 0.9499 0.0 0 3",
3850            "2",
3851            "Coordinates of Component 2",
3852            "5.0 5.0 5.0 0 4",
3853            "6.0940 5.0 5.0 0 5",
3854            "5.5470 5.9499 5.0 0 6",
3855        ];
3856        let mut line_it = lines.iter().copied();
3857        let frame = parse_single_frame(&mut line_it).unwrap();
3858
3859        assert_eq!(frame.header.natm_types, 2);
3860        assert_eq!(frame.header.natms_per_type, vec![3, 3]);
3861        assert_eq!(frame.header.masses_per_type, vec![12.011, 1.008]);
3862        assert_eq!(frame.atom_data.len(), 6);
3863        assert_eq!(&*frame.atom_data[0].symbol, "1");
3864        assert_eq!(frame.atom_data[0].atom_id, 1);
3865        assert_eq!(&*frame.atom_data[5].symbol, "2");
3866        assert_eq!(frame.atom_data[5].atom_id, 6);
3867    }
3868
3869    #[test]
3870    fn test_column_4_value_1_is_x_only_on_spec_2() {
3871        let lines = [
3872            "Generated by probe",
3873            "{\"con_spec_version\":2}",
3874            "20.0 20.0 20.0",
3875            "90.0 90.0 90.0",
3876            "",
3877            "",
3878            "1",
3879            "1",
3880            "63.5",
3881            "Cu",
3882            "Coordinates of component   1",
3883            "1.0 2.0 3.0 1 1",
3884        ];
3885        let mut line_it = lines.iter().copied();
3886        let frame = parse_single_frame(&mut line_it).unwrap();
3887        assert_eq!(frame.header.spec_version, 2);
3888        assert_eq!(frame.atom_data[0].fixed(), [true, false, false]);
3889    }
3890
3891    #[test]
3892    fn test_column_4_value_1_is_all_fixed_on_spec_1() {
3893        let lines = [
3894            "Generated by probe",
3895            "0.0000 TIME",
3896            "20.0 20.0 20.0",
3897            "90.0 90.0 90.0",
3898            "",
3899            "",
3900            "1",
3901            "1",
3902            "63.5",
3903            "Cu",
3904            "Coordinates of component   1",
3905            "1.0 2.0 3.0 1 1",
3906        ];
3907        let mut line_it = lines.iter().copied();
3908        let frame = parse_single_frame(&mut line_it).unwrap();
3909        assert_eq!(frame.header.spec_version, 1);
3910        assert_eq!(frame.atom_data[0].fixed(), [true, true, true]);
3911    }
3912
3913    #[test]
3914    fn test_parse_single_frame_missing_line() {
3915        // With a valid header but truncated atom data, we get IncompleteFrame.
3916        let lines = vec![
3917            "PREBOX1",
3918            "{\"con_spec_version\":2}",
3919            "10.0 20.0 30.0",
3920            "90.0 90.0 90.0",
3921            "POSTBOX1",
3922            "POSTBOX2",
3923            "2",
3924            "3 3",
3925            "12.011 1.008",
3926            "1",
3927            "Coordinates of Component 1",
3928            "0.0 0.0 0.0 0 1",
3929            "1.0940 0.0 0.0 0 2",
3930            "-0.5470 0.9499 0.0 0 3",
3931            // Missing Component 2 entirely
3932        ];
3933        let mut line_it = lines.iter().copied();
3934        let result = parse_single_frame(&mut line_it);
3935        assert!(result.is_err());
3936        assert!(matches!(result.unwrap_err(), ParseError::IncompleteFrame));
3937    }
3938
3939    #[test]
3940    fn test_parse_single_frame_missing_atom_index_defaults_sequential() {
3941        // Column 5 (atom_index) is optional; when absent, defaults to sequential.
3942        let lines = vec![
3943            "PREBOX1",
3944            "{\"con_spec_version\":2}",
3945            "10.0 20.0 30.0",
3946            "90.0 90.0 90.0",
3947            "POSTBOX1",
3948            "POSTBOX2",
3949            "2",
3950            "3 3",
3951            "12.011 1.008",
3952            "1",
3953            "Coordinates of Component 1",
3954            "0.0 0.0 0.0 0 1",
3955            "1.0940 0.0 0.0 0 2",
3956            "-0.5470 0.9499 0.0 0 3",
3957            "2",
3958            "Coordinates of Component 2",
3959            "5.0 5.0 5.0 0",       // No atom_index: defaults to 3
3960            "6.0940 5.0 5.0 0 10", // Explicit atom_index: 10
3961            "5.5470 5.9499 5.0 0", // No atom_index: defaults to 5
3962        ];
3963        let mut line_it = lines.iter().copied();
3964        let frame = parse_single_frame(&mut line_it).unwrap();
3965        assert_eq!(frame.atom_data.len(), 6);
3966        // First type: explicit atom_index values
3967        assert_eq!(frame.atom_data[0].atom_id, 1);
3968        assert_eq!(frame.atom_data[1].atom_id, 2);
3969        assert_eq!(frame.atom_data[2].atom_id, 3);
3970        // Second type: mixed explicit and defaulted
3971        assert_eq!(frame.atom_data[3].atom_id, 3); // defaulted (global idx 3)
3972        assert_eq!(frame.atom_data[4].atom_id, 10); // explicit
3973        assert_eq!(frame.atom_data[5].atom_id, 5); // defaulted (global idx 5)
3974    }
3975
3976    #[test]
3977    fn test_parse_single_frame_too_few_columns_fails() {
3978        // Only 3 columns (missing fixed_flag too) should still fail.
3979        let lines = [
3980            "PREBOX1",
3981            "{\"con_spec_version\":2}",
3982            "10.0 20.0 30.0",
3983            "90.0 90.0 90.0",
3984            "POSTBOX1",
3985            "POSTBOX2",
3986            "1",
3987            "1",
3988            "12.011",
3989            "C",
3990            "Coordinates of Component 1",
3991            "0.0 0.0 0.0", // Only 3 values
3992        ];
3993        let mut line_it = lines.iter().copied();
3994        let result = parse_single_frame(&mut line_it);
3995        assert!(result.is_err());
3996        assert!(matches!(
3997            result.unwrap_err(),
3998            ParseError::InvalidVectorLength {
3999                expected: 5,
4000                found: 3
4001            }
4002        ));
4003    }
4004
4005    #[test]
4006    fn test_parse_velocity_section_present() {
4007        let lines = vec![
4008            "PREBOX1",
4009            "{\"con_spec_version\":2}",
4010            "10.0 20.0 30.0",
4011            "90.0 90.0 90.0",
4012            "POSTBOX1",
4013            "POSTBOX2",
4014            "2",
4015            "1 1",
4016            "63.546 1.008",
4017            "Cu",
4018            "Coordinates of Component 1",
4019            "0.0 0.0 0.0 1 0",
4020            "H",
4021            "Coordinates of Component 2",
4022            "1.0 2.0 3.0 0 1",
4023            "",
4024            "Cu",
4025            "Velocities of Component 1",
4026            "0.1 0.2 0.3 1 0",
4027            "H",
4028            "Velocities of Component 2",
4029            "0.4 0.5 0.6 0 1",
4030        ];
4031        let mut line_it = lines.iter().copied().peekable();
4032        // Parse the frame first (consuming 15 lines)
4033        let mut frame =
4034            parse_single_frame(&mut line_it).expect("coordinate parsing should succeed");
4035        assert!(!frame.has_velocities());
4036
4037        // Now parse the velocity section
4038        let mut column = Vec::new();
4039        let has_vel = parse_velocity_section(
4040            &mut line_it,
4041            &frame.header,
4042            &mut frame.atom_data,
4043            &mut column,
4044        )
4045        .expect("velocity parsing should succeed");
4046        assert!(has_vel);
4047        frame.adopt_velocity_column(column);
4048        assert_eq!(frame.atom_data[0].velocity(), Some([0.1, 0.2, 0.3]));
4049        assert_eq!(frame.atom_data[1].velocity(), Some([0.4, 0.5, 0.6]));
4050    }
4051
4052    #[test]
4053    fn test_validate_true_accepts_matching_section_identity() {
4054        let text = r#"
4055PREBOX1
4056{"con_spec_version":2,"sections":["velocities"],"validate":true}
405710.0 20.0 30.0
405890.0 90.0 90.0
4059POSTBOX1
4060POSTBOX2
40612
40621 1
406363.546 1.008
4064Cu
4065Coordinates of Component 1
40660.0 0.0 0.0 5 0
4067H
4068Coordinates of Component 2
40691.0 2.0 3.0 0 1
4070
4071Cu
4072Velocities of Component 1
40730.1 0.2 0.3 5 0
4074H
4075Velocities of Component 2
40760.4 0.5 0.6 0 1
4077"#;
4078        let mut iter = ConFrameIterator::new(text.trim());
4079        let frame = iter.next().unwrap().unwrap();
4080
4081        assert!(frame.has_velocities());
4082        assert_eq!(
4083            frame
4084                .header
4085                .metadata
4086                .get("validate")
4087                .and_then(|v| v.as_bool()),
4088            Some(true)
4089        );
4090    }
4091
4092    #[test]
4093    fn test_validate_true_rejects_section_atom_id_mismatch() {
4094        let text = r#"
4095PREBOX1
4096{"con_spec_version":2,"sections":["velocities"],"validate":true}
409710.0 20.0 30.0
409890.0 90.0 90.0
4099POSTBOX1
4100POSTBOX2
41011
41021
410363.546
4104Cu
4105Coordinates of Component 1
41060.0 0.0 0.0 5 0
4107
4108Cu
4109Velocities of Component 1
41100.1 0.2 0.3 5 99
4111"#;
4112        let mut iter = ConFrameIterator::new(text.trim());
4113        let err = iter.next().unwrap().unwrap_err();
4114
4115        assert!(matches!(err, ParseError::ValidationError(_)));
4116        assert!(err.to_string().contains("atom_id mismatch"));
4117    }
4118
4119    #[test]
4120    fn test_validate_true_rejects_section_symbol_mismatch() {
4121        let text = r#"
4122PREBOX1
4123{"con_spec_version":2,"sections":["forces"],"validate":true}
412410.0 20.0 30.0
412590.0 90.0 90.0
4126POSTBOX1
4127POSTBOX2
41281
41291
413063.546
4131Cu
4132Coordinates of Component 1
41330.0 0.0 0.0 5 0
4134
4135H
4136Forces of Component 1
41370.1 0.2 0.3 5 0
4138"#;
4139        let mut iter = ConFrameIterator::new(text.trim());
4140        let err = iter.next().unwrap().unwrap_err();
4141
4142        assert!(matches!(err, ParseError::ValidationError(_)));
4143        assert!(err.to_string().contains("symbol mismatch"));
4144    }
4145
4146    #[test]
4147    fn test_validate_absent_allows_legacy_duplicate_identity_mismatch() {
4148        let text = r#"
4149PREBOX1
4150{"con_spec_version":2,"sections":["velocities"]}
415110.0 20.0 30.0
415290.0 90.0 90.0
4153POSTBOX1
4154POSTBOX2
41551
41561
415763.546
4158Cu
4159Coordinates of Component 1
41600.0 0.0 0.0 5 0
4161
4162Cu
4163Velocities of Component 1
41640.1 0.2 0.3 0 99
4165"#;
4166        let mut iter = ConFrameIterator::new(text.trim());
4167        let frame = iter.next().unwrap().unwrap();
4168
4169        assert!(frame.has_velocities());
4170        assert_eq!(frame.atom_data[0].atom_id, 0);
4171        assert_eq!(frame.atom_data[0].fixed(), [true, false, true]);
4172    }
4173
4174    #[test]
4175    fn test_validate_must_be_boolean_when_present() {
4176        let lines = [
4177            "PREBOX1",
4178            "{\"con_spec_version\":2,\"validate\":\"yes\",\"sections\":[]}",
4179            "10.0 20.0 30.0",
4180            "90.0 90.0 90.0",
4181            "POSTBOX1",
4182            "POSTBOX2",
4183            "1",
4184            "1",
4185            "12.011",
4186        ];
4187        let mut line_it = lines.iter().copied();
4188        let err = parse_frame_header(&mut line_it).unwrap_err();
4189
4190        assert!(matches!(err, ParseError::InvalidMetadataJson(_)));
4191        assert!(err.to_string().contains("validate"));
4192    }
4193
4194    #[test]
4195    fn test_validate_true_requires_sections_key() {
4196        let lines = [
4197            "PREBOX1",
4198            "{\"con_spec_version\":2,\"validate\":true}",
4199            "10.0 20.0 30.0",
4200            "90.0 90.0 90.0",
4201            "POSTBOX1",
4202            "POSTBOX2",
4203            "1",
4204            "1",
4205            "12.011",
4206        ];
4207        let mut line_it = lines.iter().copied();
4208        let err = parse_frame_header(&mut line_it).unwrap_err();
4209
4210        assert!(matches!(err, ParseError::InvalidMetadataJson(_)));
4211        assert!(err.to_string().contains("sections"));
4212    }
4213
4214    #[test]
4215    fn test_sections_must_be_string_array_when_present() {
4216        let lines = [
4217            "PREBOX1",
4218            "{\"con_spec_version\":2,\"sections\":[\"velocities\",7]}",
4219            "10.0 20.0 30.0",
4220            "90.0 90.0 90.0",
4221            "POSTBOX1",
4222            "POSTBOX2",
4223            "1",
4224            "1",
4225            "12.011",
4226        ];
4227        let mut line_it = lines.iter().copied();
4228        let err = parse_frame_header(&mut line_it).unwrap_err();
4229
4230        assert!(matches!(err, ParseError::InvalidMetadataJson(_)));
4231        assert!(err.to_string().contains("sections"));
4232    }
4233
4234    #[test]
4235    fn test_validate_true_rejects_non_integer_coordinate_identity_columns() {
4236        let text = r#"
4237PREBOX1
4238{"con_spec_version":2,"sections":[],"validate":true}
423910.0 20.0 30.0
424090.0 90.0 90.0
4241POSTBOX1
4242POSTBOX2
42431
42441
424563.546
4246Cu
4247Coordinates of Component 1
42480.0 0.0 0.0 5.0 0
4249"#;
4250        let mut iter = ConFrameIterator::new(text.trim());
4251        let err = iter.next().unwrap().unwrap_err();
4252
4253        assert!(matches!(err, ParseError::InvalidFixedFlag(_)));
4254        assert!(err.to_string().contains("5.0"));
4255    }
4256
4257    #[test]
4258    fn test_validate_true_rejects_non_exact_coordinate_label() {
4259        let text = r#"
4260PREBOX1
4261{"con_spec_version":2,"sections":[],"validate":true}
426210.0 20.0 30.0
426390.0 90.0 90.0
4264POSTBOX1
4265POSTBOX2
42661
42671
426863.546
4269Cu
4270Coordinates Component 1
42710.0 0.0 0.0 5 0
4272"#;
4273        let mut iter = ConFrameIterator::new(text.trim());
4274        let err = iter.next().unwrap().unwrap_err();
4275
4276        assert!(matches!(err, ParseError::ValidationError(_)));
4277        assert!(err.to_string().contains("Coordinates of Component 1"));
4278    }
4279
4280    #[test]
4281    fn test_validate_true_rejects_unknown_component_symbol() {
4282        let text = r#"
4283PREBOX1
4284{"con_spec_version":2,"sections":[],"validate":true}
428510.0 20.0 30.0
428690.0 90.0 90.0
4287POSTBOX1
4288POSTBOX2
42891
42901
429163.546
4292Qq
4293Coordinates of Component 1
42940.0 0.0 0.0 0 0
4295"#;
4296        let mut iter = ConFrameIterator::new(text.trim());
4297        let err = iter.next().unwrap().unwrap_err();
4298
4299        assert!(matches!(err, ParseError::ValidationError(_)));
4300        assert!(err.to_string().contains("symbol"));
4301    }
4302
4303    #[test]
4304    fn test_declared_section_must_be_present() {
4305        let text = r#"
4306PREBOX1
4307{"con_spec_version":2,"sections":["velocities"]}
430810.0 20.0 30.0
430990.0 90.0 90.0
4310POSTBOX1
4311POSTBOX2
43121
43131
431463.546
4315Cu
4316Coordinates of Component 1
43170.0 0.0 0.0 0 0
4318"#;
4319        let mut iter = ConFrameIterator::new(text.trim());
4320        let err = iter.next().unwrap().unwrap_err();
4321
4322        assert!(matches!(
4323            err,
4324            ParseError::IncompleteSection(ref name) if name == "velocities"
4325        ));
4326    }
4327
4328    #[test]
4329    fn test_non_finite_cell_geometry_rejected_in_strict_mode() {
4330        let lines = [
4331            "PREBOX1",
4332            "{\"con_spec_version\":2,\"sections\":[],\"validate\":true}",
4333            "10.0 NaN 30.0",
4334            "90.0 90.0 90.0",
4335            "POSTBOX1",
4336            "POSTBOX2",
4337            "1",
4338            "1",
4339            "12.011",
4340        ];
4341        let mut line_it = lines.iter().copied();
4342        let err = parse_frame_header(&mut line_it).unwrap_err();
4343
4344        assert!(matches!(err, ParseError::NonFiniteValue(_)));
4345        assert!(err.to_string().contains("NaN"));
4346    }
4347
4348    #[test]
4349    fn test_validate_true_rejects_non_physical_cell_geometry() {
4350        let lines = [
4351            "PREBOX1",
4352            "{\"con_spec_version\":2,\"sections\":[],\"validate\":true}",
4353            "0.0 20.0 30.0",
4354            "90.0 180.0 90.0",
4355            "POSTBOX1",
4356            "POSTBOX2",
4357            "1",
4358            "1",
4359            "12.011",
4360        ];
4361        let mut line_it = lines.iter().copied();
4362        let err = parse_frame_header(&mut line_it).unwrap_err();
4363
4364        assert!(matches!(err, ParseError::ValidationError(_)));
4365        assert!(err.to_string().contains("cell"));
4366    }
4367
4368    #[test]
4369    fn test_validate_true_rejects_reserved_metadata_type_mismatch() {
4370        let lines = [
4371            "PREBOX1",
4372            "{\"con_spec_version\":2,\"sections\":[],\"validate\":true,\"energy\":\"low\"}",
4373            "10.0 20.0 30.0",
4374            "90.0 90.0 90.0",
4375            "POSTBOX1",
4376            "POSTBOX2",
4377            "1",
4378            "1",
4379            "12.011",
4380        ];
4381        let mut line_it = lines.iter().copied();
4382        let err = parse_frame_header(&mut line_it).unwrap_err();
4383
4384        assert!(matches!(err, ParseError::InvalidMetadataJson(_)));
4385        assert!(err.to_string().contains("energy"));
4386    }
4387
4388    #[test]
4389    fn test_validate_true_rejects_malformed_bonds() {
4390        let lines = [
4391            "PREBOX1",
4392            "{\"con_spec_version\":2,\"sections\":[],\"validate\":true,\"bonds\":[[0]]}",
4393            "10.0 20.0 30.0",
4394            "90.0 90.0 90.0",
4395            "POSTBOX1",
4396            "POSTBOX2",
4397            "1",
4398            "1",
4399            "12.011",
4400        ];
4401        let mut line_it = lines.iter().copied();
4402        let err = parse_frame_header(&mut line_it).unwrap_err();
4403        assert!(matches!(err, ParseError::InvalidMetadataJson(_)));
4404        assert!(err.to_string().contains("bonds"));
4405    }
4406
4407    #[test]
4408    fn test_bonds_metadata_round_trip_in_header() {
4409        use crate::types::{Bond, meta};
4410        let lines = [
4411            "PREBOX1",
4412            "{\"con_spec_version\":2,\"bonds\":[[0,1],{\"i\":0,\"j\":2,\"order\":1}]}",
4413            "10.0 20.0 30.0",
4414            "90.0 90.0 90.0",
4415            "POSTBOX1",
4416            "POSTBOX2",
4417            "1",
4418            "1",
4419            "12.011",
4420        ];
4421        let mut line_it = lines.iter().copied();
4422        let header = parse_frame_header(&mut line_it).expect("header");
4423        let bonds = header.bonds();
4424        assert_eq!(bonds.len(), 2);
4425        assert_eq!(bonds[0], Bond::new(0, 1));
4426        assert_eq!(bonds[1].i, 0);
4427        assert_eq!(bonds[1].j, 2);
4428        assert_eq!(bonds[1].order, Some(1));
4429        assert!(header.metadata.contains_key(meta::BONDS));
4430    }
4431
4432    #[test]
4433    fn test_parse_velocity_section_absent() {
4434        let lines = [
4435            "PREBOX1",
4436            "{\"con_spec_version\":2}",
4437            "10.0 20.0 30.0",
4438            "90.0 90.0 90.0",
4439            "POSTBOX1",
4440            "POSTBOX2",
4441            "1",
4442            "1",
4443            "12.011",
4444            "C",
4445            "Coordinates of Component 1",
4446            "0.0 0.0 0.0 0 1",
4447        ];
4448        let mut line_it = lines.iter().copied().peekable();
4449        let mut frame = parse_single_frame(&mut line_it).expect("parse should succeed");
4450        let mut column = Vec::new();
4451        let has_vel = parse_velocity_section(
4452            &mut line_it,
4453            &frame.header,
4454            &mut frame.atom_data,
4455            &mut column,
4456        )
4457        .expect("should succeed with no velocities");
4458        assert!(!has_vel);
4459        assert!(column.is_empty());
4460        assert_eq!(frame.atom_data[0].velocity(), None);
4461    }
4462
4463    /// The velocity column is the storage `atom.velocity` reads. Writing the
4464    /// atom updates that buffer in place, and the bytes match the file.
4465    #[test]
4466    fn velocity_column_aliases_soa_bytes() {
4467        let text = "\
4468bulk
4469{\"con_spec_version\":2}
44704.0 5.0 6.0
447190.0 90.0 90.0
44720 0
44730 0
44741
44752
447663.546
4477Cu
4478Coordinates of Component 1
44790.0 0.0 0.0 7 0
44801.0 0.0 0.0 0 1
4481
4482Cu
4483Velocities of Component 1
44840.125 -0.25 0.5 7 0
4485-0.125 0.25 -0.5 0 1
4486";
4487        let mut frame = ConFrameIterator::new(text)
4488            .next()
4489            .expect("frame")
4490            .expect("parse");
4491        let soa = frame.velocities.f64_slice().expect("f64 column");
4492        let mut packed = Vec::with_capacity(soa.len());
4493        for atom in &frame.atom_data {
4494            packed.extend_from_slice(&atom.velocity().expect("velocity"));
4495        }
4496        assert_eq!(soa, packed.as_slice());
4497        assert_eq!(soa, &[0.125, -0.25, 0.5, -0.125, 0.25, -0.5][..]);
4498        assert_eq!(frame.atom_data[0].velocity_slot(), soa.as_ptr());
4499        frame.atom_data[0].set_velocity(Some([9.0, 8.0, 7.0]));
4500        assert_eq!(frame.velocities.as_f64_row(0), [9.0, 8.0, 7.0]);
4501        assert_eq!(frame.velocities.as_f64_row(1), [-0.125, 0.25, -0.5]);
4502    }
4503
4504    #[test]
4505    fn force_column_aliases_soa_bytes() {
4506        let text = "\
4507bulk
4508{\"con_spec_version\":2,\"sections\":[\"forces\"]}
45094.0 5.0 6.0
451090.0 90.0 90.0
45110 0
45120 0
45131
45142
451563.546
4516Cu
4517Coordinates of Component 1
45180.0 0.0 0.0 0 0
45191.0 1.0 1.0 7 1
4520
4521Cu
4522Forces of Component 1
45230.1 0.2 0.3 0 0
4524-0.4 0.5 -0.6 7 1
4525";
4526        let mut frame = ConFrameIterator::new(text)
4527            .next()
4528            .expect("frame")
4529            .expect("parse");
4530        let soa = frame.forces.f64_slice().expect("f64 column");
4531        let mut packed = Vec::with_capacity(soa.len());
4532        for atom in &frame.atom_data {
4533            packed.extend_from_slice(&atom.force().expect("force"));
4534        }
4535        assert_eq!(soa, packed.as_slice());
4536        assert_eq!(soa, &[0.1, 0.2, 0.3, -0.4, 0.5, -0.6][..]);
4537        assert_eq!(frame.atom_data[0].force_slot(), soa.as_ptr());
4538        frame.atom_data[1].set_force(Some([1.0, 2.0, 3.0]));
4539        assert_eq!(frame.forces.as_f64_row(1), [1.0, 2.0, 3.0]);
4540    }
4541
4542    /// Million-atom `.convel` parse. Release builds must stay under the
4543    /// per-atom box path (about 0.7 s on this host).
4544    #[test]
4545    #[ignore = "times a million-atom convel parse"]
4546    fn microbench_convel_column_parse() {
4547        let n = 1_000_000usize;
4548        let mut text = String::with_capacity(n * 64);
4549        text.push_str("bench\n{\"con_spec_version\":2}\n4 5 6\n90 90 90\n0 0\n0 0\n1\n");
4550        text.push_str(&format!("{n}\n63.546\nCu\nCoordinates of Component 1\n"));
4551        for i in 0..n {
4552            text.push_str(&format!("0 0 0 0 {i}\n"));
4553        }
4554        text.push_str("\nCu\nVelocities of Component 1\n");
4555        for i in 0..n {
4556            let v = (i % 1000) as f64 * 0.001;
4557            text.push_str(&format!("{v} 0 0 0 {i}\n"));
4558        }
4559        let started = std::time::Instant::now();
4560        let frame = ConFrameIterator::new(&text)
4561            .next()
4562            .expect("frame")
4563            .expect("parse");
4564        let elapsed = started.elapsed().as_secs_f64();
4565        eprintln!("convel column parse {n} atoms {elapsed:.4} s");
4566        let soa = frame.velocities.f64_slice().expect("f64");
4567        assert_eq!(frame.atom_data[0].velocity_slot(), soa.as_ptr());
4568        assert_eq!(frame.atom_data[n - 1].velocity().unwrap()[0], 0.999);
4569        assert_eq!(soa[(n - 1) * 3], 0.999);
4570        if !cfg!(debug_assertions) {
4571            assert!(elapsed < 0.35, "convel parse {elapsed:.4} s");
4572        }
4573        let real = std::path::Path::new("bench/h2h/work/thread-reads/con-h2h.convel");
4574        if let Ok(bytes) = std::fs::read(real) {
4575            let started = std::time::Instant::now();
4576            let frame = ConFrameIterator::from_bytes(&bytes)
4577                .next()
4578                .expect("frame")
4579                .expect("parse");
4580            let elapsed = started.elapsed().as_secs_f64();
4581            eprintln!("real convel column parse {elapsed:.4} s");
4582            let soa = frame.velocities.f64_slice().expect("f64");
4583            assert_eq!(frame.atom_data[0].velocity_slot(), soa.as_ptr());
4584            assert_eq!(
4585                frame.atom_data[0].velocity().unwrap(),
4586                frame.velocities.as_f64_row(0)
4587            );
4588        }
4589    }
4590
4591    #[test]
4592    fn test_parse_line_of_range_f64_exact() {
4593        let vals = parse_line_of_range_f64("1.0 2.0 3.0 0.0 42", 4, 5, &[0.0; 5]).unwrap();
4594        assert_eq!(vals, vec![1.0, 2.0, 3.0, 0.0, 42.0]);
4595    }
4596
4597    #[test]
4598    fn test_byte_scan_stack_parses_realistic_coord_line() {
4599        // Typical CON atom line: x y z fixed_mask [atom_id]
4600        let line = "   0.63939999999999997    0.90449999999999997   -0.00009999999999977 1    0";
4601        let defaults = [0.0, 0.0, 0.0, 0.0, 99.0];
4602        let mut buf = [0.0f64; NUMERIC_STACK_WIDTH];
4603        let n = parse_line_of_range_f64_stack(line, 4, 5, &defaults, &mut buf).unwrap();
4604        assert_eq!(n, 5);
4605        assert!((buf[0] - 0.6394).abs() < 1e-4);
4606        assert!((buf[1] - 0.9045).abs() < 1e-4);
4607        assert_eq!(buf[3] as u8, 1);
4608        assert_eq!(buf[4] as u64, 0);
4609        // trailing junk must error
4610        let bad = "1.0 2.0 3.0 1 0 EXTRA";
4611        assert!(parse_line_of_range_f64_stack(bad, 4, 5, &defaults, &mut buf).is_err());
4612        // partial non-boundary token must error
4613        let glued = "1.0 2.0 3.0abc 1 0";
4614        assert!(parse_line_of_range_f64_stack(glued, 4, 5, &defaults, &mut buf).is_err());
4615    }
4616
4617    #[test]
4618    fn test_parse_line_of_range_f64_stack_matches_vec_api() {
4619        let defaults = [0.0, 0.0, 0.0, 0.0, 7.0];
4620        let line = "1.0 2.0 3.0 0.0";
4621        let mut buf = [0.0f64; NUMERIC_STACK_WIDTH];
4622        parse_line_of_range_f64_stack(line, 4, 5, &defaults, &mut buf).unwrap();
4623        let via_vec = parse_line_of_range_f64(line, 4, 5, &defaults).unwrap();
4624        assert_eq!(&buf[..5], via_vec.as_slice());
4625        assert_eq!(buf[4], 7.0);
4626    }
4627
4628    #[test]
4629    fn test_parse_line_of_range_f64_padded() {
4630        let defaults = [0.0, 0.0, 0.0, 0.0, 99.0];
4631        let vals = parse_line_of_range_f64("1.0 2.0 3.0 0.0", 4, 5, &defaults).unwrap();
4632        assert_eq!(vals, vec![1.0, 2.0, 3.0, 0.0, 99.0]);
4633    }
4634
4635    #[test]
4636    fn test_parse_line_of_range_f64_too_few() {
4637        let result = parse_line_of_range_f64("1.0 2.0 3.0", 4, 5, &[0.0; 5]);
4638        assert!(result.is_err());
4639    }
4640
4641    #[test]
4642    fn test_parse_line_of_range_f64_too_many() {
4643        let result = parse_line_of_range_f64("1.0 2.0 3.0 0.0 5.0 6.0", 4, 5, &[0.0; 5]);
4644        assert!(result.is_err());
4645    }
4646
4647    #[test]
4648    fn test_parse_all_four_column_lines() {
4649        // All atom lines have only 4 columns; atom_index defaults to sequential.
4650        let lines = [
4651            "PREBOX1",
4652            "{\"con_spec_version\":2}",
4653            "10.0 10.0 10.0",
4654            "90.0 90.0 90.0",
4655            "POSTBOX1",
4656            "POSTBOX2",
4657            "1",
4658            "3",
4659            "12.011",
4660            "C",
4661            "Coordinates of Component 1",
4662            "0.0 0.0 0.0 0",
4663            "1.0 0.0 0.0 0",
4664            "2.0 0.0 0.0 1",
4665        ];
4666        let mut line_it = lines.iter().copied();
4667        let frame = parse_single_frame(&mut line_it).unwrap();
4668        assert_eq!(frame.atom_data[0].atom_id, 0);
4669        assert_eq!(frame.atom_data[1].atom_id, 1);
4670        assert_eq!(frame.atom_data[2].atom_id, 2);
4671        assert!(frame.atom_data[2].is_fixed());
4672    }
4673
4674    #[test]
4675    fn test_positions_take_the_storage_dtype_of_the_metadata() {
4676        use crate::storage_dtype::{ElementKind, FloatArray2};
4677        let rows = [[0.5, -1.25, 3.0], [1.0e-3, 2.5e4, -7.75]];
4678        let atom_lines: Vec<String> = rows
4679            .iter()
4680            .enumerate()
4681            .map(|(id, [x, y, z])| format!("{x} {y} {z} 0 {id}"))
4682            .collect();
4683        for &kind in ElementKind::all_hosted() {
4684            let metadata = format!(
4685                "{{\"con_spec_version\":3,\"units\":{{\"length\":\"angstrom\",\"energy\":\"eV\"}},\
4686                 \"storage_dtypes\":{{\"positions\":\"{}\"}}}}",
4687                kind.as_str()
4688            );
4689            let mut lines = vec![
4690                "PREBOX1",
4691                metadata.as_str(),
4692                "10.0 10.0 10.0",
4693                "90.0 90.0 90.0",
4694                "POSTBOX1",
4695                "POSTBOX2",
4696                "1",
4697                "2",
4698                "1.008",
4699                "H",
4700                "Coordinates of Component 1",
4701            ];
4702            lines.extend(atom_lines.iter().map(String::as_str));
4703            let frame = parse_single_frame(&mut lines.iter().copied()).unwrap();
4704            assert_eq!(frame.positions.kind(), kind);
4705            assert_eq!(frame.positions.nrows(), rows.len());
4706            for (i, &xyz) in rows.iter().enumerate() {
4707                let mut expected = FloatArray2::zeros(kind, 1, 3);
4708                expected.set_f64_row(0, xyz);
4709                assert_eq!(
4710                    frame.positions.as_f64_row(i),
4711                    expected.as_f64_row(0),
4712                    "{kind:?} row {i}"
4713                );
4714            }
4715        }
4716    }
4717}
4718
4719#[cfg(all(test, feature = "parallel"))]
4720mod newline_index_bench {
4721    use super::newline_index_at;
4722
4723    #[test]
4724    fn index_matches_memchr() {
4725        let mut bytes = vec![b'x'; 80_000];
4726        for index in (20..bytes.len()).step_by(23) {
4727            bytes[index] = b'\n';
4728        }
4729        let serial: Vec<usize> = memchr::memchr_iter(b'\n', &bytes).collect();
4730        assert_eq!(newline_index_at(&bytes, 0, 8), serial);
4731        // Above the 1 MiB serial cutoff, including a buffer of bare newlines.
4732        let mut long = Vec::new();
4733        while long.len() < (1 << 20) + 64 {
4734            long.extend_from_slice(b"01234567 1.25 -2.5 3.5 0 7\n");
4735        }
4736        let long_serial: Vec<usize> = memchr::memchr_iter(b'\n', &long).collect();
4737        assert_eq!(newline_index_at(&long, 40, 8), {
4738            let mut shifted = long_serial.clone();
4739            for offset in &mut shifted {
4740                *offset += 40;
4741            }
4742            shifted
4743        });
4744        let bare = vec![b'\n'; (1 << 20) + 64];
4745        let bare_serial: Vec<usize> = memchr::memchr_iter(b'\n', &bare).collect();
4746        assert_eq!(newline_index_at(&bare, 0, 8), bare_serial);
4747    }
4748}