crystcif-parse

A TypeScript parser for Crystallographic Information File (CIF) files. This module provides a structure to parse the CIF 1.1 data format and interpret core structural keywords to retrieve crystal structures.

v0.3 is a breaking release. The package is now ESM-only and written in TypeScript. See MIGRATING.md if you are upgrading from v0.2.

Features

• Full CIF 1.1 tokeniser and parser
• Structural core dictionary keywords (positions, cell parameters, labels)
• Symmetry operations and Hall symbol interpretation
• TypeScript types / declarations included — no @types package needed
• ESM-only; Node ≥ 18 required

Not supported

• CIF 2.0 syntax
• Non-essential atomic properties (masses, charges, bonds, etc.)

Installation

npm install @ccp-nc/crystcif-parse

Usage

import { parseCifStructures, Atoms, parseCif } from '@ccp-nc/crystcif-parse';
import { readFileSync } from 'fs';

const text = readFileSync('structure.cif', 'utf8');

// High-level: parse directly into Atoms instances
const structures = parseCifStructures(text);
// { 'block_name': Atoms, ... }

const atoms = structures['my_block'];
console.log(atoms.length());               // number of atoms
console.log(atoms.get_chemical_symbols()); // ['C', 'H', 'O', ...]
console.log(atoms.get_positions());        // [[x,y,z], ...]
console.log(atoms.get_cell());             // [[...], [...], [...]]
console.log(atoms.get_pbc());              // [true, true, true]

// Low-level: access the raw parsed data blocks
const cifdict = parseCif(text);
// { 'block_name': { '_tag': DataItem, ... }, ... }

API

parseCifStructures(ciftext: string): Record<string, Atoms>

Parses a CIF string and returns a dictionary of Atoms instances keyed by data block name. Equivalent to Atoms.readCif(ciftext).

parseCif(ciftext: string): CifDict

Low-level parser. Returns a dictionary of raw data blocks. Each block maps tag names to DataItem objects containing the parsed CifValue(s).

class Atoms

A class representing a single crystal structure, inspired by the Python class of the same name in the Atomic Simulation Environment.

Constructor

new Atoms(
  elems:     (string | number)[],  // element symbols or atomic numbers
  positions: number[][],           // Cartesian [x,y,z] per atom (default [])
  cell?:     CellInput,            // unit cell (see below)
  info?:     Record<string, unknown>,
  scaled?:   boolean,              // treat positions as fractional (default false)
  tolerant?: boolean,              // accept unknown symbols (default false)
)

cell input formats (CellInput)

Value	Meaning
null / false	No periodicity
number	Cubic cell with that lattice parameter
[a, b, c]	Orthorhombic cell
[[a,b,c],[α,β,γ]]	Lengths and angles (degrees)
[[…],[…],[…]]	Full 3×3 Cartesian cell vectors
[a, null, c]	Partial periodicity (null axis = non-periodic)

Methods

Method	Returns
.length()	number — atom count
.get_positions()	number[][] — Cartesian coordinates
.get_scaled_positions()	number[][] — fractional coordinates
.get_chemical_symbols()	string[]
.get_atomic_numbers()	number[]
.get_cell()	(Vec3 | null)[] | null
.get_inv_cell()	number[][] | null
.get_pbc()	[boolean, boolean, boolean]
.get_array(name)	unknown[] — any stored per-atom array
.set_array(name, arr)	Store a per-atom array
Atoms.readCif(cif, symtol?)	Record<string, Atoms> — static, parse CIF string

CLI

npx validate-cif structure.cif another.cif

Validates one or more CIF files and exits with a non-zero code if any fail.

Exported types

import type {
  Vec3, Matrix3x3, CellPar, CellInput,
  SymOp, Token, TokenType,
  CifValue, CifValueType,
  DataItem, SingleDataItem, LoopDataItem,
  CifBlock, CifDict,
} from '@ccp-nc/crystcif-parse';

Development

npm run build        # compile to dist/ via tsup
npm test             # run Vitest test suite
npm run type-check   # tsc --noEmit
npm run lint         # ESLint
npm run format       # Prettier