LammpsIO

Overview

Parses LAMMPS data and dump files, extracting atom positions, types, IDs, simulation box bounds, and column headers as zero-copy typed arrays.


Package	`@voltstack/lammps-io`
Language	C++17 with Node.js NAPI bindings
Platform	Linux x64
Links	GitHub · npm

Installation

npm install @voltstack/lammps-io

Modules

const { dataParser, dumpParser, statsParser } = require('@voltstack/lammps-io');

Module	Purpose
`dataParser`	Parses LAMMPS data files (static structures)
`dumpParser`	Parses LAMMPS dump files (trajectory snapshots)
`statsParser`	Computes statistics from dump files and typed arrays

Data Parser

`dataParser.parseData(filepath, options?)`

Parses a LAMMPS data file.

function parseData(
  filepath: string,
  options?: { includeIds?: boolean }
): ParseResult | null

Parameter	Type	Description
`filepath`	`string`	Path to the LAMMPS data file
`options.includeIds`	`boolean`	Include atom IDs in the output (default: `false`)

Returns ParseResult | null:

interface ParseResult {
  // [x1, y1, z1, x2, y2, z2, ...]
  positions: Float32Array;
  // Atom type per particle
  types: Uint16Array;
  // Only present if includeIds is true
  ids?: Uint32Array;
  metadata: {
    timestep: number;
    natoms: number;
    boxBounds: {
      xlo: number; xhi: number;
      ylo: number; yhi: number;
      zlo: number; zhi: number;
    };
    headers: string[];
  };
  min: [number, number, number];
  max: [number, number, number];
}

For LAMMPS data files, metadata.timestep is always 0 and metadata.headers is always an empty array — data files have no ITEM: TIMESTEP or ITEM: ATOMS column-header line. These fields are only meaningful for parseDump.

Throws on unreadable or invalid input (e.g., "Failed to open file", "Invalid LAMMPS data format", "No atoms parsed").

Dump Parser

`dumpParser.parseDump(filepath, options?)`

Parses a LAMMPS dump file (single timestep snapshot).

function parseDump(
  filepath: string,
  options?: { includeIds?: boolean; properties?: string[] }
): ParseResult | null

Parameter	Type	Description
`filepath`	`string`	Path to the LAMMPS dump file
`options.includeIds`	`boolean`	Include atom IDs in the output (default: `false`)
`options.properties`	`string[]`	Extra column names to extract as Float32Arrays. Use `"*"` as a wildcard to extract all non-base columns (`id`, `type`, `x`, `y`, `z` are always excluded from the wildcard).

Returns ParseResult | null. The shape extends the base ParseResult with:

metadata.timestep — the actual timestep value from the dump file.
metadata.headers — column names from the ITEM: ATOMS line (e.g., ["id", "type", "x", "y", "z", "vx", "vy", "vz"]).
properties — present only when options.properties is provided. An object mapping each requested column name to a Float32Array of per-atom values.

// Example: extract velocity columns
const result = dumpParser.parseDump('dump.lammpstrj', {
  properties: ['vx', 'vy', 'vz']
});
// result.properties.vx  → Float32Array (one value per atom)
// result.properties.vy  → Float32Array
// result.properties.vz  → Float32Array

// Wildcard: extract all non-base columns
const result2 = dumpParser.parseDump('dump.lammpstrj', {
  properties: ['*']
});

Throws on unreadable or invalid input (e.g., "Failed to open file", "Invalid LAMMPS dump format"). The typed contract returns NativeParseResult | null.

For files with more than 50,000 atoms, the dump parser automatically uses multi-threaded parsing with hardware concurrency detection.

Stats Parser

`statsParser.getStatsForProperty(filepath, propertyIndex)`

Computes the min and max for a column in a dump file.

function getStatsForProperty(
  filepath: string,
  propertyIndex: number
): { min: number; max: number }

Parameter	Type	Description
`filepath`	`string`	Path to the LAMMPS dump file
`propertyIndex`	`number`	Zero-based column index

`statsParser.getMinMaxFromTypedArray(typedArray)`

Computes the min and max from a typed array.

function getMinMaxFromTypedArray(
  typedArray: Float32Array | Float64Array | Int32Array | Uint32Array
): { min: number; max: number }

`statsParser.computeMagnitudes(vectorArray)`

Computes the magnitude (√(x² + y² + z²)) of each vector.

function computeMagnitudes(
  vectorArray: Float32Array[] | Float64Array[] | number[][]
): Float32Array

`statsParser.getUniqueValuesForProperty(filepath, propertyIndex, maxValues?)`

Returns the sorted unique values for a column in a dump file.

function getUniqueValuesForProperty(
  filepath: string,
  propertyIndex: number,
  maxValues?: number
): number[]

Parameter	Type	Default	Description
`filepath`	`string`	—	Path to the LAMMPS dump file
`propertyIndex`	`number`	—	Zero-based column index
`maxValues`	`number`	`100`	Maximum number of unique values to return (0 = unlimited)

Performance

Memory-mapped I/O (mmap) for large file reads without copying into memory.
Multi-threaded parsing for dump files with > 50K atoms.
Fast number parsing via the fast_float library.
Zero-copy typed arrays — Data is allocated directly on the V8 heap.
Compiled with -O3 -ffast-math -std=c++17.

LAMMPS File Formats

Data File

N atoms
M atom types

xlo xhi
ylo yhi
zlo zhi

Atoms

1 1 0.0 0.0 0.0
2 1 1.5 0.0 0.0
...

Dump File

ITEM: TIMESTEP
1000
ITEM: NUMBER OF ATOMS
5000
ITEM: BOX BOUNDS pp pp pp
0.0 50.0
0.0 50.0
0.0 50.0
ITEM: ATOMS id type x y z
1 1 0.0 0.0 0.0
2 1 1.5 0.0 0.0
...

LammpsIO

On this page