matterviz 0.3.0 → 0.3.2

package/dist/trajectory/parse/vasp.js

@@ -0,0 +1,65 @@
+import * as math from '../../math';
+import { create_trajectory_frame, is_valid_element_symbol, validate_3x3_matrix, } from '../helpers';
+export function parse_vasp_xdatcar(content, filename) {
+    const lines = content.trim().split(/\r?\n/);
+    if (lines.length < 10)
+        throw new Error(`XDATCAR file too short`);
+    const scale = parseFloat(lines[1]);
+    if (isNaN(scale))
+        throw new Error(`Invalid scale factor`);
+    const lattice_matrix = validate_3x3_matrix(lines.slice(2, 5).map((line) => line.trim().split(/\s+/).map((x) => parseFloat(x) * scale)));
+    const element_names = lines[5].trim().split(/\s+/);
+    const element_counts = lines[6].trim().split(/\s+/).map(Number);
+    if (element_names.length !== element_counts.length) {
+        throw new Error(`XDATCAR element names/counts mismatch: names=${element_names.length}, counts=${element_counts.length}`);
+    }
+    if (element_counts.some((count) => !Number.isFinite(count) || !Number.isInteger(count) || count <= 0)) {
+        throw new Error(`XDATCAR contains invalid element counts: expected finite positive integers`);
+    }
+    const validated_element_names = element_names.map((name) => {
+        if (!is_valid_element_symbol(name)) {
+            throw new Error(`Invalid element symbol in XDATCAR: ${name}`);
+        }
+        return name;
+    });
+    const elements = validated_element_names.flatMap((name, idx) => Array(element_counts[idx]).fill(name));
+    const frames = [];
+    let line_idx = 7;
+    const frac_to_cart = math.create_frac_to_cart(lattice_matrix);
+    while (line_idx < lines.length) {
+        const config_idx = lines.findIndex((line, idx) => idx >= line_idx && line.includes(`Direct configuration=`));
+        if (config_idx === -1)
+            break;
+        const config_line = lines[config_idx];
+        line_idx = config_idx + 1;
+        const step_match = config_line.match(/configuration=\s*(\d+)/);
+        const step = step_match ? parseInt(step_match[1]) : frames.length + 1;
+        const positions = [];
+        for (let idx = 0; idx < elements.length && line_idx < lines.length; idx++) {
+            const coords = lines[line_idx].trim().split(/\s+/).slice(0, 3).map(Number);
+            if (coords.length === 3 && !coords.some(isNaN)) {
+                positions.push(frac_to_cart(coords));
+            }
+            line_idx++;
+        }
+        if (positions.length === elements.length) {
+            const pbc = [true, true, true];
+            const { volume } = math.calc_lattice_params(lattice_matrix);
+            frames.push(create_trajectory_frame(positions, elements, lattice_matrix, pbc, step, {
+                volume,
+            }));
+        }
+    }
+    return {
+        frames,
+        metadata: {
+            filename,
+            source_format: `vasp_xdatcar`,
+            frame_count: frames.length,
+            total_atoms: elements.length,
+            periodic_boundary_conditions: [true, true, true],
+            elements: element_names,
+            element_counts,
+        },
+    };
+}

package/dist/trajectory/parse/xyz.d.ts

@@ -0,0 +1,2 @@
+import type { TrajectoryType } from '../index';
+export declare function parse_xyz_trajectory(content: string): TrajectoryType;

package/dist/trajectory/parse/xyz.js

@@ -0,0 +1,109 @@
+import * as math from '../../math';
+import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
+export function parse_xyz_trajectory(content) {
+    const lines = content.trim().split(/\r?\n/);
+    const frames = [];
+    let line_idx = 0;
+    while (line_idx < lines.length) {
+        if (!lines[line_idx]?.trim()) {
+            line_idx++;
+            continue;
+        }
+        const num_atoms = parseInt(lines[line_idx].trim(), 10);
+        if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 1 >= lines.length) {
+            line_idx++;
+            continue;
+        }
+        const comment = lines[++line_idx] || ``;
+        const metadata = {};
+        // Extract properties efficiently
+        const extractors = {
+            step: /(?:step|frame|ionic_step)\s*[=:]?\s*(\d+)/i,
+            energy: /(?:energy|E|etot|total_energy)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            volume: /(?:volume|vol|V)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            pressure: /(?:pressure|press|P)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            temperature: /(?:temperature|temp|T)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            force_max: /(?:max_force|force_max|fmax)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            bandgap: /(?:bandgap|E_gap|gap)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+        };
+        const step_match = extractors.step.exec(comment);
+        const step = step_match?.[1] ? parseInt(step_match[1]) : frames.length;
+        Object.entries(extractors).forEach(([key, pattern]) => {
+            if (key === `step`)
+                return;
+            const match = pattern.exec(comment);
+            if (match)
+                metadata[key] = parseFloat(match[1]);
+        });
+        // Extract lattice matrix
+        const lattice_match = comment.match(/Lattice\s*=\s*"([^"]+)"/i);
+        let lattice_matrix;
+        if (lattice_match) {
+            const values = lattice_match[1].split(/\s+/).map(Number);
+            if (values.length === 9 && values.every((value) => Number.isFinite(value))) {
+                lattice_matrix = [[values[0], values[1], values[2]], [
+                        values[3],
+                        values[4],
+                        values[5],
+                    ], [values[6], values[7], values[8]]];
+                metadata.volume = math.calc_lattice_params(lattice_matrix).volume;
+            }
+        }
+        // Parse atoms
+        const positions = [];
+        const elements = [];
+        const forces = [];
+        const has_forces = comment.includes(`forces:R:3`);
+        for (let idx = 0; idx < num_atoms; idx++) {
+            line_idx++;
+            if (line_idx >= lines.length)
+                break;
+            const parts = lines[line_idx].trim().split(/\s+/);
+            if (parts.length >= 4) {
+                const x_coord = parseFloat(parts[1]);
+                const y_coord = parseFloat(parts[2]);
+                const z_coord = parseFloat(parts[3]);
+                if (!Number.isFinite(x_coord) || !Number.isFinite(y_coord) ||
+                    !Number.isFinite(z_coord)) {
+                    console.warn(`Skipping XYZ atom with invalid coordinates in frame ${frames.length} at line ${line_idx + 1}`);
+                    continue;
+                }
+                const raw_symbol = parts[0];
+                const element_symbol = coerce_element_symbol(raw_symbol);
+                if (!element_symbol) {
+                    console.warn(`Skipping XYZ atom with unknown element symbol "${raw_symbol}" in frame ${frames.length}`);
+                    continue;
+                }
+                elements.push(element_symbol);
+                positions.push([x_coord, y_coord, z_coord]);
+                if (has_forces && parts.length >= 7) {
+                    const force_x = parseFloat(parts[4]);
+                    const force_y = parseFloat(parts[5]);
+                    const force_z = parseFloat(parts[6]);
+                    if (Number.isFinite(force_x) &&
+                        Number.isFinite(force_y) &&
+                        Number.isFinite(force_z)) {
+                        forces.push([force_x, force_y, force_z]);
+                    }
+                }
+            }
+        }
+        if (forces.length > 0) {
+            metadata.forces = forces;
+            const magnitudes = forces.map((force) => Math.hypot(...force));
+            metadata.force_max = Math.max(...magnitudes);
+            // Calculate RMS (root mean square) of force magnitudes
+            metadata.force_norm = Math.sqrt(magnitudes.reduce((sum, mag) => sum + mag ** 2, 0) / magnitudes.length);
+        }
+        frames.push(create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? [true, true, true] : undefined, step, metadata));
+        line_idx++;
+    }
+    return {
+        frames,
+        metadata: {
+            source_format: `xyz_trajectory`,
+            frame_count: frames.length,
+            total_atoms: frames[0]?.structure.sites.length || 0,
+        },
+    };
+}

package/dist/trajectory/types.d.ts

@@ -0,0 +1,11 @@
+import type { ElementSymbol } from '../element';
+export type AtomTypeMapping = Record<number, ElementSymbol>;
+export interface LoadingOptions {
+    use_indexing?: boolean;
+    buffer_size?: number;
+    index_sample_rate?: number;
+    extract_plot_metadata?: boolean;
+    bin_file_threshold?: number;
+    text_file_threshold?: number;
+    atom_type_mapping?: AtomTypeMapping;
+}

package/dist/trajectory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -1,2 +1,4 @@
 export declare function merge_nested<T extends Record<string, unknown>>(obj1: T, obj2?: Partial<T>): T;
 export declare const escape_html: (unsafe_string: string) => string;
+export declare const normalize_unicode_minus: (value: string) => string;
+export declare const normalize_scientific_notation: (value: string) => string;

package/dist/utils.js

@@ -17,3 +17,7 @@ export const escape_html = (unsafe_string) => unsafe_string
     .replaceAll(`>`, `>`)
     .replaceAll(`"`, `"`)
     .replaceAll(`'`, `'`);
+// Normalize unicode minus (U+2212) to ASCII hyphen-minus.
+export const normalize_unicode_minus = (value) => value.replace(/−/g, `-`);
+// Normalize scientific notation variants (d/D exponent, Mathematica *^).
+export const normalize_scientific_notation = (value) => normalize_unicode_minus(value).toLowerCase().replace(/d/g, `e`).replace(/\*\^/g, `e`);

package/dist/xrd/XrdPlot.svelte

@@ -10,10 +10,12 @@ import { compute_broadened_pattern, DEFAULT_BROADENING } from './broadening';
 function is_xrd_pattern(obj) {
     if (!obj || typeof obj !== `object`)
         return false;
-    const record = obj;
-    return (Array.isArray(record.x) &&
-        Array.isArray(record.y) &&
-        record.x.length === record.y.length);
+    const pattern_obj = obj;
+    const x = pattern_obj.x;
+    const y = pattern_obj.y;
+    return (Array.isArray(x) &&
+        Array.isArray(y) &&
+        x.length === y.length);
 }
 function format_hkl(hkl, format) {
     if (format === `compact`) {

package/dist/xrd/calc-xrd.js

@@ -162,7 +162,6 @@ export function compute_xrd_pattern(structure, options = {}) {
             if (ELEMENT_Z[element_symbol] === undefined) {
                 throw new Error(`Unknown atomic number for element ${element_symbol}`);
             }
-            // Cast needed: imported JSON has different type structure than our union type
             const raw_coeff = ATOMIC_SCATTERING_PARAMS[element_symbol];
             if (!raw_coeff) {
                 throw new Error(`No atomic scattering coefficients for ${element_symbol}. Extend ATOMIC_SCATTERING_PARAMS.`);

package/package.json

@@ -5,10 +5,10 @@
   "homepage": "https://janosh.github.io/matterviz",
   "repository": "https://github.com/janosh/matterviz",
   "license": "MIT",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "svelte": "./dist/index.js",
   "bugs": "https://github.com/janosh/matterviz/issues",
@@ -17,15 +17,17 @@
     "build": "vite build",
     "preview": "vite preview",
     "test": "vitest --run && playwright test",
-    "package": "svelte-package && mkdir -p dist/xrd && cp extensions/rust/src/atomic_scattering_params.json dist/xrd/",
-    "prepare": "svelte-kit sync && svelte-package && mkdir -p dist/xrd && cp extensions/rust/src/atomic_scattering_params.json dist/xrd/",
-    "prepublishOnly": "svelte-package && mkdir -p dist/xrd && cp extensions/rust/src/atomic_scattering_params.json dist/xrd/"
+    "package-dist-assets": "node scripts/package-dist-assets.mjs",
+    "package:dist": "svelte-package && pnpm run package-dist-assets",
+    "package": "pnpm run package:dist",
+    "prepare": "NODE_OPTIONS=--experimental-strip-types svelte-kit sync && pnpm run package:dist",
+    "prepublishOnly": "pnpm run package:dist"
   },
   "dependencies": {
-    "@spglib/moyo-wasm": "^0.7.4",
-    "@sveltejs/kit": "^2.50.1",
-    "@threlte/core": "^8.3.1",
-    "@threlte/extras": "^9.7.1",
+    "@spglib/moyo-wasm": "^0.7.9",
+    "@sveltejs/kit": "2.53.4",
+    "@threlte/core": "^8.4.1",
+    "@threlte/extras": "^9.8.1",
     "@types/d3-force": "^3.0.10",
     "@types/d3-hierarchy": "^3.1.7",
     "@types/js-yaml": "^4.0.9",
@@ -40,17 +42,18 @@
     "d3-scale-chromatic": "^3.1.0",
     "d3-shape": "^3.2.0",
     "fflate": "^0.8.2",
-    "h5wasm": "^0.8.11",
+    "h5wasm": "^0.9.0",
     "highlight.js": "^11.11.1",
     "js-yaml": "^4.1.1",
-    "svelte": "5.49.1",
-    "svelte-multiselect": "^11.6.0",
-    "three": "^0.182.0"
+    "svelte": "5.52.0",
+    "svelte-multiselect": "^11.6.2",
+    "svelte-toc": "^0.6.3",
+    "three": "^0.183.2"
   },
   "devDependencies": {
-    "@playwright/test": "^1.58.1",
+    "@playwright/test": "^1.58.2",
     "@rollup/plugin-yaml": "^4.1.2",
-    "@stylistic/eslint-plugin": "^5.7.1",
+    "@stylistic/eslint-plugin": "^5.9.0",
     "@sveltejs/adapter-static": "3.0.10",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
@@ -62,23 +65,26 @@
     "@types/d3-scale-chromatic": "^3.1.0",
     "@types/d3-shape": "^3.1.8",
     "@types/d3-time-format": "^4.0.3",
-    "@types/three": "^0.182.0",
+    "@types/three": "^0.183.1",
+    "@typescript/native-preview": "7.0.0-dev.20260304.1",
     "@vitest/coverage-v8": "^4.0.18",
     "@wooorm/starry-night": "^3.9.0",
     "abstract-syntax-tree": "^2.22.0",
     "d3-time-format": "^4.1.0",
-    "eslint": "^9.39.2",
-    "eslint-plugin-svelte": "^3.14.0",
-    "happy-dom": "^20.4.0",
-    "matterviz-wasm": "^0.0.4",
+    "eslint": "^10.0.2",
+    "eslint-plugin-svelte": "^3.15.0",
+    "happy-dom": "^20.8.3",
+    "matterviz-wasm": "^0.0.7",
     "mdsvex": "^0.12.6",
     "rehype-katex": "^7.0.1",
     "remark-math": "3.0.1",
-    "svelte-check-rs": "0.7.4",
+    "svelte-check-rs": "0.9.5",
     "svelte-preprocess": "^6.0.3",
-    "svelte2tsx": "^0.7.47",
+    "svelte2tsx": "^0.7.51",
+    "typedoc": "^0.28.17",
+    "typedoc-plugin-markdown": "^4.10.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "^8.54.0",
+    "typescript-eslint": "^8.56.1",
     "vite": "^7.3.1",
     "vitest": "^4.0.18"
   },
@@ -115,6 +121,10 @@
       "types": "./dist/composition/index.d.ts",
       "default": "./dist/composition/index.js"
     },
+    "./chempot-diagram": {
+      "types": "./dist/chempot-diagram/index.d.ts",
+      "default": "./dist/chempot-diagram/index.js"
+    },
     "./colors": {
       "types": "./dist/colors/index.d.ts",
       "default": "./dist/colors/index.js"

package/readme.md

@@ -55,7 +55,7 @@ Rich element pages with physical properties, electron configurations, Bohr atom
 ## 🔨   Installation
 
 ```sh
-npm install --dev matterviz
+pnpm add -D matterviz
 ```
 
 ## 📙   Usage
@@ -114,10 +114,10 @@ npm install --dev matterviz
 
 ## 🙏   Acknowledgements
 
-- Element properties in `src/lib/element-data.ts` were combined from [`Bowserinator/Periodic-Table-JSON`](https://github.com/Bowserinator/Periodic-Table-JSON/blob/master/PeriodicTableJSON.json) under Creative Commons license and [`robertwb/Periodic Table of Elements.csv`](https://gist.github.com/robertwb/22aa4dbfb6bcecd94f2176caa912b952) (unlicensed).
+- Element properties in `src/lib/element/data.ts` were combined from [`Bowserinator/Periodic-Table-JSON`](https://github.com/Bowserinator/Periodic-Table-JSON/blob/master/PeriodicTableJSON.json) under Creative Commons license and [`robertwb/Periodic Table of Elements.csv`](https://gist.github.com/robertwb/22aa4dbfb6bcecd94f2176caa912b952) (unlicensed).
 - Thanks to [Images of Elements](https://images-of-elements.com) for providing photos of elemental crystals and glowing excited gases.
 - Thanks to [@kadinzhang](https://github.com/kadinzhang) and their [Periodicity project](https://ptable.netlify.app) [[code](https://github.com/kadinzhang/Periodicity)] for the idea to display animated Bohr model atoms and inset a scatter plot into the periodic table to visualize the periodic nature of elemental properties.
-- Big thanks to all sources of element images. See [`fetch-elem-images.ts`](https://github.com/janosh/matterviz/blob/-/src/fetch-elem-images.ts) and [`static/elements`](https://github.com/janosh/matterviz/tree/main/static/elements).
+- Big thanks to all sources of element images. See [`fetch-elem-images.ts`](https://github.com/janosh/matterviz/blob/-/src/scripts/fetch-elem-images.ts) and [`static/elements`](https://github.com/janosh/matterviz/tree/main/static/elements).
 - Thanks to [@ixxie](https://github.com/ixxie) ([shenhav.fyi](https://shenhav.fyi)) for great suggestions.
 
 This project would not have been possible as a one-person side project without many fine open-source projects. 🙏 To name just a few:
@@ -141,6 +141,6 @@ Use [`citation.cff`](citation.cff) or cite the [Zenodo record](https://zenodo.or
   url = {https://github.com/janosh/matterviz},
   note = {10.5281/zenodo.17094509 - https://github.com/janosh/matterviz},
   urldate = {2026-01-23}, % optional, replace with your date of access
-  version = {0.2.2}, % replace with the version you use
+  version = {0.3.1}, % replace with the version you use
 }
 ```

package/dist/trajectory/parse.d.ts

@@ -1,42 +0,0 @@
-import type { ElementSymbol } from '../element';
-import type { FrameIndex, FrameLoader, ParseProgress, TrajectoryFrame, TrajectoryMetadata, TrajectoryType } from './index';
-export declare const MAX_SAFE_STRING_LENGTH: number;
-export declare const MAX_METADATA_SIZE: number;
-export declare const LARGE_FILE_THRESHOLD: number;
-export declare const INDEX_SAMPLE_RATE = 100;
-export declare const MAX_BIN_FILE_SIZE: number;
-export declare const MAX_TEXT_FILE_SIZE: number;
-export type AtomTypeMapping = Record<number, ElementSymbol>;
-export interface LoadingOptions {
-    use_indexing?: boolean;
-    buffer_size?: number;
-    index_sample_rate?: number;
-    extract_plot_metadata?: boolean;
-    bin_file_threshold?: number;
-    text_file_threshold?: number;
-    atom_type_mapping?: AtomTypeMapping;
-}
-export declare function is_trajectory_file(filename: string, content?: string): boolean;
-export declare class TrajFrameReader implements FrameLoader {
-    private format;
-    private global_numbers?;
-    constructor(filename: string);
-    get_total_frames(data: string | ArrayBuffer): Promise<number>;
-    build_frame_index(data: string | ArrayBuffer, sample_rate: number, on_progress?: (progress: ParseProgress) => void): Promise<FrameIndex[]>;
-    load_frame(data: string | ArrayBuffer, frame_number: number): Promise<TrajectoryFrame | null>;
-    extract_plot_metadata(data: string | ArrayBuffer, options?: {
-        sample_rate?: number;
-        properties?: string[];
-    }, on_progress?: (progress: ParseProgress) => void): Promise<TrajectoryMetadata[]>;
-    private load_xyz_frame;
-    private load_ase_frame;
-    private parse_xyz_metadata;
-    private parse_ase_metadata;
-}
-export declare function parse_trajectory_data(data: unknown, filename?: string, atom_type_mapping?: AtomTypeMapping): Promise<TrajectoryType>;
-export declare function get_unsupported_format_message(filename: string, content: string): string | null;
-export declare function parse_trajectory_async(data: ArrayBuffer | string, filename: string, on_progress?: (progress: ParseProgress) => void, options?: LoadingOptions): Promise<TrajectoryType>;
-export declare function create_frame_loader(filename: string): FrameLoader;
-export declare const XYZFrameLoader: typeof TrajFrameReader;
-export declare const ASEFrameLoader: typeof TrajFrameReader;
-export declare function load_binary_traj(resp: Response, type: string, fallback?: boolean): Promise<ArrayBuffer | string>;