bravais 0.2.1 → 0.3.0

package/dist/types/cif/errors.d.ts

@@ -1,3 +1,4 @@
+import { StructureError } from "../structure/errors.js";
 /** The text is not CIF the tokenizer and parser accept. */
 export declare class CifSyntaxError extends Error {
     /** 1-based line of the problem. */
@@ -5,6 +6,6 @@ export declare class CifSyntaxError extends Error {
     constructor(message: string, line: number);
 }
 /** The CIF parses but does not describe a structure this package can use. */
-export declare class CifStructureError extends Error {
+export declare class CifStructureError extends StructureError {
     constructor(message: string);
 }

package/dist/types/cif/structure.d.ts

@@ -1,12 +1,10 @@
-import type { Lattice, Site, SpaceGroupInfo, SymmetryOperation } from "../structure/types.js";
+import type { StructureListing } from "../structure/types.js";
 import { type CifBlock } from "./parser.js";
-export interface ParsedCifStructure {
-    lattice: Lattice;
-    sites: Site[];
-    /** Null when the file lists no operations; see `spaceGroup` then. */
-    operations: SymmetryOperation[] | null;
-    spaceGroup: SpaceGroupInfo;
-}
+/**
+ * A data block's lattice, merged sites, operations (null when the file lists
+ * none; see `spaceGroup` then) and space-group tags.
+ */
+export type ParsedCifStructure = StructureListing;
 /** True when the block carries atom coordinates (the one a viewer wants). */
 export declare function isStructureBlock(block: CifBlock): boolean;
 /** Lattice, merged sites, operations and space-group tags of one data block. */

package/dist/types/index.d.ts

@@ -1,5 +1,7 @@
 import type { Structure } from "./structure/types.js";
 export { CifStructureError, CifSyntaxError } from "./cif/errors.js";
+export { StructureDataError, StructureError } from "./structure/errors.js";
+export { readStructure, type SiteData, type StructureData, } from "./structure/from-data.js";
 export { parseCif, type CifBlock, type CifDocument, type CifLoop, } from "./cif/parser.js";
 export { parseCifStructure, type ParsedCifStructure } from "./cif/structure.js";
 export { parseSymmetryOperation } from "./cif/symmetry-operations.js";

package/dist/types/structure/elements.d.ts

@@ -1,5 +1,7 @@
 /** Element symbols in atomic-number order. */
 export declare const ELEMENT_SYMBOLS: string[];
+/** True for an element symbol as written, such as "Fe", or "D" for deuterium. */
+export declare function isElementSymbol(symbol: string): boolean;
 /**
  * The element behind a CIF atom label or type symbol: `Fe3+`, `O2-`, `Co1`,
  * `OW`, `fe` and `Wat` all resolve. Null when no element symbol fits.

package/dist/types/structure/errors.d.ts

@@ -0,0 +1,8 @@
+/** A structure, read from a CIF or given as data, that this package cannot use. */
+export declare class StructureError extends Error {
+    constructor(message: string);
+}
+/** Structure data `readStructure` cannot use: a field is missing or malformed. */
+export declare class StructureDataError extends StructureError {
+    constructor(message: string);
+}

package/dist/types/structure/from-data.d.ts

@@ -0,0 +1,57 @@
+import type { LatticeParameters, Mat3, SpaceGroupInfo, Structure, SymmetryOperation, Vec3 } from "./types.js";
+/** One site of `StructureData`: a position and the species that share it. */
+export interface SiteData {
+    /** Name of the site; `site1`, `site2` and so on by its place in the list when absent. */
+    label?: string | null;
+    /** Fractional coordinates; wrapped into the cell. */
+    fractional: Vec3;
+    /** The species at this position; an occupancy defaults to 1. */
+    species: {
+        element: string;
+        occupancy?: number | null;
+    }[];
+}
+/**
+ * A crystal structure as plain data, for structures read or built outside
+ * this package. It survives JSON and `structuredClone`, so it can cross
+ * workers, processes and IPC.
+ */
+export interface StructureData {
+    /**
+     * Cell lengths in ångström and angles in degrees, set with c along z and a
+     * in the xz plane as in pymatgen, or the three cell vectors as rows in
+     * Cartesian ångström, used as given. Vectors win when both are given.
+     */
+    lattice: LatticeParameters | {
+        vectors: Mat3;
+    };
+    /**
+     * The sites as listed: an asymmetric unit that `operations` or
+     * `spaceGroup` expands, or every atom of the cell. Species within 1e-4 of
+     * one position belong to one site, as the rows of a CIF do.
+     */
+    sites: SiteData[];
+    /**
+     * x' = R x + t on fractional coordinates, as `SymmetryOperation`s with R
+     * row-major, or as strings such as `"-x, y+1/2, -z"`. They must include
+     * the identity. When absent or null, `spaceGroup` supplies them, and
+     * without a space group the sites list every atom of the cell.
+     */
+    operations?: (SymmetryOperation | string)[] | null;
+    /** The space group by Hall symbol, Hermann-Mauguin symbol or number. */
+    spaceGroup?: Partial<SpaceGroupInfo> | null;
+}
+/**
+ * Read a structure given as data instead of a CIF, such as one a CIF reader
+ * outside this package produced, so it can be expanded, drawn and analysed
+ * like a structure from `readCif`. The data is checked and then read the way
+ * a CIF's atoms are: positions wrapped into the cell, species at one position
+ * joined into a site and sorted by occupancy, overfull sites scaled to a full
+ * one, and the symmetry checked against the atoms, or looked up from the
+ * space group.
+ *
+ * Throws `StructureDataError` for data that is missing or malformed, or
+ * whose operations do not fit its atoms, and `SpaceGroupLookupError` for an
+ * unknown space group.
+ */
+export declare function readStructure(data: StructureData): Promise<Structure>;

package/dist/types/structure/sites.d.ts

@@ -0,0 +1,19 @@
+import type { Site, Vec3 } from "./types.js";
+/** Rows this close in fractional coordinates describe one site. */
+export declare const SITE_MERGE_TOLERANCE = 0.0001;
+/** One species at one position, as a CIF atom-site row lists it. */
+export interface SiteRow {
+    label: string;
+    element: string;
+    occupancy: number;
+    fractional: Vec3;
+}
+/**
+ * Sites from rows of one species at one position, the way a CIF lists its
+ * atoms. Positions are wrapped into the cell. Rows within
+ * `SITE_MERGE_TOLERANCE` of an earlier row join its site, which keeps that
+ * row's label, adds up the occupancy of a repeated element and sorts its
+ * species by descending occupancy. A site whose occupancies add up to more
+ * than 1 is scaled down to a full site.
+ */
+export declare function assembleSites(rows: Iterable<SiteRow>): Site[];

package/dist/types/structure/types.d.ts

@@ -33,13 +33,13 @@ export interface SymmetryOperation {
     rotation: number[];
     translation: Vec3;
 }
-/** What a CIF says about its space group; null for what it leaves out. */
+/** What a CIF or structure data says about its space group; null for what it leaves out. */
 export interface SpaceGroupInfo {
     /** Number in the International Tables, 1 to 230. */
     number: number | null;
-    /** Hermann-Mauguin symbol as written in the file. */
+    /** Hermann-Mauguin symbol as written in the source. */
     symbol: string | null;
-    /** Hall symbol as written in the file. */
+    /** Hall symbol as written in the source. */
     hallSymbol: string | null;
 }
 export interface Structure {
@@ -49,4 +49,15 @@ export interface Structure {
     operations: SymmetryOperation[];
     spaceGroup: SpaceGroupInfo;
 }
+/**
+ * A structure as its source lists it, before its symmetry is settled: the
+ * operations are null when the source gives none, and `spaceGroup` then
+ * decides them.
+ */
+export interface StructureListing {
+    lattice: Lattice;
+    sites: Site[];
+    operations: SymmetryOperation[] | null;
+    spaceGroup: SpaceGroupInfo;
+}
 export declare const IDENTITY_OPERATION: SymmetryOperation;

package/dist/types/symmetry/moyo.d.ts

@@ -38,10 +38,10 @@ export interface OperationSetting {
     operations: SymmetryOperation[];
 }
 /**
- * Every setting the space group a CIF names admits, spglib's standard one
- * first: one for most symbols, several for a short symbol such as `P 21/c`
- * or a rhombohedral symbol without `:H` or `:R`. A bare number gives the
- * standard setting alone.
+ * Every setting the named space group admits, spglib's standard one first:
+ * one for most symbols, several for a short symbol such as `P 21/c` or a
+ * rhombohedral symbol without `:H` or `:R`. A bare number gives the standard
+ * setting alone.
  */
 export declare function operationSettings(info: SpaceGroupInfo): Promise<OperationSetting[]>;
 /**

package/dist/types/symmetry/resolve.d.ts

@@ -1,11 +1,14 @@
-import type { ParsedCifStructure } from "../cif/structure.js";
-import { type SymmetryOperation } from "../structure/types.js";
+import type { StructureError } from "../structure/errors.js";
+import { type StructureListing, type SymmetryOperation } from "../structure/types.js";
+/** The error a reader reports with, such as `CifStructureError`. */
+export type StructureErrorClass = new (message: string) => StructureError;
 /**
- * The operations a parsed CIF's atoms are expanded with: the file's own
- * loop, checked to fit the atoms, or else the setting of its space group
- * that fits them. A symbol admitting several settings, such as a
- * rhombohedral group with no `:H` or `:R`, is settled by the atoms when the
- * list is already expanded, since only the right setting maps it onto
- * itself, and otherwise by the cell shape, then by the standard setting.
+ * The operations a listing's atoms are expanded with: its own operations,
+ * checked to fit the atoms, or else the setting of its space group that fits
+ * them. A symbol admitting several settings, such as a rhombohedral group
+ * with no `:H` or `:R`, is settled by the atoms when the list is already
+ * expanded, since only the right setting maps it onto itself, and otherwise
+ * by the cell shape, then by the standard setting. Operations that do not
+ * fit are reported as `ErrorClass`.
  */
-export declare function resolveOperations(parsed: ParsedCifStructure): Promise<SymmetryOperation[]>;
+export declare function resolveOperations(parsed: StructureListing, ErrorClass: StructureErrorClass): Promise<SymmetryOperation[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bravais",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A minimal crystal structure viewer for the web: reads CIF files and draws them with three.js.",
   "license": "MIT",
   "author": "Jiacheng Wang",