@ccp-nc/crystvis-js 0.6.0 → 0.6.1

package/lib/formats/xyz.js

@@ -7,31 +7,87 @@
 
 import _ from 'lodash';
 import { Atoms } from '@ccp-nc/crystcif-parse';
+import { TensorData } from '../tensor.js';
 
-function load(contents, filename='xyz') {
+/**
+ * Load an Extended XYZ file (optionally multi-frame), extracting NMR tensor data as TensorData objects.
+ *
+ * Only the Extended XYZ format (with a unit cell specified via the Lattice property) is supported.
+ * Standard/plain XYZ files (without a cell) are not supported and will result in an error.
+ * Extended XYZ files can contain additional per-atom properties, including NMR tensors (e.g., magnetic shielding or EFG tensors)
+ * stored as 9 real values per atom. These are automatically converted to TensorData objects if the property name matches
+ * the provided shielding_tag or efg_tag (defaults: 'ms' and 'efg').
+ *
+ * Multi-frame files are supported: use the index argument to select a frame (default: -1, last frame).
+ *
+ * @param {string} contents - The contents of the Extended XYZ file.
+ * @param {string} [filename='xyz'] - Optional name for the returned structure (used as key in result object).
+ * @param {string} [shielding_tag='ms'] - Property name to treat as magnetic shielding tensor (9 real values per atom).
+ * @param {string} [efg_tag='efg'] - Property name to treat as EFG tensor (9 real values per atom).
+ * @param {number} [index=-1] - Frame index to load (0-based, negative counts from end; default -1 = last frame).
+ * @returns {Object} Dictionary mapping filename to Atoms object. Per-atom tensor arrays are stored as TensorData objects.
+ * @throws {Error} If the file is not valid Extended XYZ (e.g., missing cell), or if tensor arrays are malformed.
+ *
+ * Example usage:
+ *   load(contents, 'mystruct', 'ms', 'efg', -1)
+ *   // Returns: { mystruct: Atoms }
+ *   // Atoms.get_array('ms')[0] is a TensorData instance
+ */
+function load(contents, filename='xyz', shielding_tag='ms', efg_tag='efg', index=-1) {
 
-    // Split the file into lines
+    // Split into frames
     let lines = _.split(contents, '\n');
+    let frames = [];
+    let i = 0;
+    while (i < lines.length) {
+        // Skip empty lines
+        while (i < lines.length && _.trim(lines[i]) === '') i++;
+        if (i >= lines.length) break;
+        let lineContent = _.trim(lines[i]);
+        if (lineContent === '') {
+            i++;
+            continue;
+        }
+        let N = parseInt(lineContent);
+        if (isNaN(N) || N <= 0) {
+            i++;
+            continue;
+        }
+        // Check if we have enough lines for this frame
+        if (i + N + 1 >= lines.length) break;
+        let frame = lines.slice(i, i + N + 2);
+        frames.push(frame);
+        i += N + 2;
+    }
+    if (frames.length === 0) {
+        throw Error('No valid frames found in XYZ/Extended XYZ file.');
+    }
+    // Select frame
+    let frame_idx = index < 0 ? frames.length + index : index;
+    if (frame_idx < 0 || frame_idx >= frames.length) {
+        throw Error('Frame index out of range for XYZ/Extended XYZ file.');
+    }
+    lines = frames[frame_idx];
 
     // Parse the first line: number of atoms
     let N = parseInt(_.trim(lines[0]));
     if (isNaN(N) || lines.length < N + 2) {
-        throw Error('Invalid XYZ file');
+        throw Error('Invalid XYZ/Extended XYZ frame: could not parse atom count or frame is too short.');
     }
 
     // Parse the second line: comments
     let info = lines[1];
     // Check if it's extended format
-    let ext = false;
-    let rext = /([A-Za-z]+)=(([A-Za-z0-9.:]+)|"([\s0-9.e-]+)")/g;
-    let m = rext.exec(info);
+    let rext = /([A-Za-z_]+)=(([A-Za-z0-9.:_-]+)|"([^"]+)")/g;
     let matches = [];
     let cell = null;
-    let arrays = [];
-    while (m != null) {
+    let columns = [];
+    
+    let m;
+    while ((m = rext.exec(info)) !== null) {
         matches.push(m);
-        m = rext.exec(info);
     }
+    
     if (matches.length > 0) {
         // It's extended! But does it have the right keywords?
         let props = {};
@@ -40,35 +96,28 @@ function load(contents, filename='xyz') {
             props[m[1]] = m[3] || m[4];
         }
         if ((_.has(props, 'Lattice') && _.has(props, 'Properties'))) {
-            // It's valid!
-            ext = true;
             // Parse the lattice
-            let latt = _.split(props['Lattice'], /\s+/);
+            let latt = _.split(props['Lattice'], /\s+/).filter(s => s.length > 0);
             cell = [];
             for (let i = 0; i < 3; ++i) {
-                cell.push(_.map(latt.slice(3 * i, 3 * i + 3), parseFloat));
-                if (cell[i].indexOf(NaN) > -1) {
-                    throw Error('Invalid Extended XYZ file');
+                let row = _.map(latt.slice(3 * i, 3 * i + 3), parseFloat);
+                if (row.some(v => isNaN(v))) {
+                    throw Error('Invalid Extended XYZ file: could not parse cell row.');
                 }
+                cell.push(row);
             }
-            if (props['Properties'].slice(0, 19) != 'species:S:1:pos:R:3') {
-                throw Error('Invalid Extended XYZ file');
+            if (!props['Properties'].startsWith('species:S:1:pos:R:3')) {
+                throw Error('Invalid Extended XYZ file: Properties string does not start with species:S:1:pos:R:3');
             }
             // Parse the properties
-            let propre = /([A-Za-z]+):(S|R|I):([0-9]+)/g;
-            let columns = [];
-            m = propre.exec(props['Properties'])
-            while (m != null) {
+            let propre = /([A-Za-z_]+):(S|R|I):([0-9]+)/g;
+            while ((m = propre.exec(props['Properties'])) !== null) {
                 columns.push({
                     'name': m[1],
                     'type': m[2],
                     'n': parseInt(m[3]),
-                    'val': [],
                 });
-                m = propre.exec(props['Properties']);
             }
-            // We know the first two are just species and pos
-            arrays = columns.slice(2);
         }
 
         info = _.omit(props, ['Lattice', 'Properties']);
@@ -78,46 +127,94 @@ function load(contents, filename='xyz') {
         };
     }
 
+    // Check if we have a cell
+    if (cell === null) {
+        throw Error('No unit cell (Lattice property) found in this file. Only Extended XYZ format with a cell is supported; plain XYZ files are not supported.');
+    }
+
+    // Initialize arrays for additional properties (skip species and pos which are columns 0 and 1)
+    let arrays = {};
+    for (let i = 2; i < columns.length; ++i) {
+        arrays[columns[i].name] = [];
+    }
+
     // Parse the following lines: atoms
     let elems = [];
     let pos = [];
+    // Determine expected number of tokens per atom line:
+    // species (1) + pos (3) + sum of additional property token counts
+    let expected_tokens = 1 + 3;
+    for (let c = 2; c < columns.length; ++c) {
+        expected_tokens += columns[c].n;
+    }
+
     for (let i = 0; i < N; ++i) {
-        let lspl = _.split(lines[i + 2], /\s+/);
+        let line_index = i + 2;
+        let line = lines[line_index];
+        let lspl = _.split(line, /\s+/).filter(s => s.length > 0);
+
+        // Expect the atom line to contain all tokens; do not attempt to merge
+        // subsequent physical lines. If token count is insufficient, fail fast.
+        if (lspl.length < expected_tokens) {
+            throw Error('Invalid Extended XYZ file: insufficient property values on line ' + (i + 3));
+        }
+        
+        // Read species (column 0)
         elems.push(lspl[0]);
-        pos.push(_.map(lspl.slice(1, 4), parseFloat));
-        if (pos.indexOf(NaN) > -1) {
-            throw Error('Invalid XYZ file');
+        
+        // Track current position in split line
+        let col_idx = 1;
+        
+        // Read positions (column 1: pos:R:3)
+        let position = [];
+        for (let j = 0; j < 3; ++j) {
+            position.push(parseFloat(lspl[col_idx++]));
         }
-
-        // Any additional parsing required?
-        if (ext) {
-            lspl.splice(0, 4);
-            for (let j = 0; j < arrays.length; ++j) {
-                let v = [];
-                let parser = {
-                    'S': String,
-                    'R': parseFloat,
-                    'I': parseInt,
-                }[arrays[j].type];
-                for (let k = 0; k < arrays[j].n; ++k) {
-                    v.push(parser(lspl.splice(0)));
+        if (position.some(v => isNaN(v))) {
+            throw Error('Invalid XYZ file: could not parse atom position.');
+        }
+        pos.push(position);
+        
+        // Read additional properties (columns 2+)
+        for (let c = 2; c < columns.length; ++c) {
+            let col = columns[c];
+            let v = [];
+            let parser = {
+                'S': function(s) { return String(s); },
+                'R': function(s) { return parseFloat(s); },
+                'I': function(s) { return parseInt(s); },
+            }[col.type];
+            
+            for (let k = 0; k < col.n; ++k) {
+                if (col_idx >= lspl.length) {
+                    throw Error('Invalid Extended XYZ file: insufficient property values on line ' + (i + 3));
                 }
+                v.push(parser(lspl[col_idx++]));
+            }
+            
+            // Convert 9-element real arrays into TensorData immediately for shielding/EFG
+            if (col.type === 'R' && col.n === 9 && (col.name === shielding_tag || col.name === efg_tag)) {
+                if (v.length !== 9) {
+                    throw Error('Invalid tensor array for ' + col.name);
+                }
+                v = new TensorData([
+                    [v[0], v[1], v[2]],
+                    [v[3], v[4], v[5]],
+                    [v[6], v[7], v[8]]
+                ]);
+            } else {
                 v = v.length > 1 ? v : v[0];
-                arrays[j].val.push(v);
             }
+            
+            arrays[col.name].push(v);
         }
     }
 
-    // check if we have a cell
-    if (cell === null) {
-        throw Error('No cell found in XYZ file. Please use the Extended XYZ format.');
-    }
-
     let a = new Atoms(elems, pos, cell, info);
-    if (ext) {
-        for (let i = 0; i < arrays.length; ++i) {
-            a.set_array(arrays[i].name, arrays[i].val);
-        }
+    
+    // Add all arrays to atoms object
+    for (let name in arrays) {
+        a.set_array(name, arrays[name]);
     }
 
     let structs = {};

package/lib/loader.js

@@ -31,16 +31,17 @@ class Loader {
         return this._error;
     }
 
-    /** Load file from its contents and format 
+    /**
+     * Load file from its contents and format
      *
      * @param  {String} contents    File contents
      * @param  {String} format      File extension
      * @param  {String} filename    Name of the file. If provided, this will be
      *                              added as a prefix to all the names in the dictionary
-     *
+     * @param  {Object} [options]   Optional parser-specific options (e.g. {shielding_tag, efg_tag} for xyz)
      * @return {Object}             Dictionary of parsed structure(s)
      */
-    load(contents, format='cif', filename=null) {
+    load(contents, format='cif', filename=null, options={}) {
 
         const parsers = {
             cif: CIF,
@@ -50,21 +51,41 @@ class Loader {
         };
 
         format = format.toLowerCase();
+        // Treat extxyz as xyz
+        if (format === 'extxyz') {
+            format = 'xyz';
+        }
+
+        this._error = '';
 
         if (!(format in parsers)) {
             throw Error('Invalid file format');
         }
 
-        this._error = '';
-
         let structs;
 
         try {
-            if (filename)
+            if (format === 'xyz') {
+                // Support shielding_tag, efg_tag, and index for xyz
+                const shielding = options.shielding_tag || 'ms';
+                const efg = options.efg_tag || 'efg';
+                const index = (typeof options.index === 'number') ? options.index : -1;
+                // Pass filename only if provided; otherwise let parser use its default
+                if (filename) {
+                    structs = parsers[format].load(contents, filename, shielding, efg, index);
+                } else {
+                    structs = parsers[format].load(contents, undefined, shielding, efg, index);
+                }
+            } else if (filename) {
                 structs = parsers[format].load(contents, filename);
-            else 
+            } else {
                 structs = parsers[format].load(contents);
+            }
         } catch (err) {
+            // For XYZ parsing, let errors propagate so callers/tests can catch them.
+            if (format === 'xyz') {
+                throw err;
+            }
             this._status = Loader.STATUS_ERROR;
             this._error = err.message || err;
             return;

package/lib/model.js

@@ -627,9 +627,6 @@ class AtomImage {
             let seed = utils.hashCode(this._fxyz + name);
             parameters.ditherSeed = seed/4294967295.0; // Reduce to ]0.5,-0.5]
         }
-        else {
-            
-        }
 
         var r = this.renderer;
         if (r) {

package/lib/primitives/ellipsoid.js

@@ -13,9 +13,6 @@ import {
     addStaticVar
 } from '../utils.js';
 
-// Basic materials
-const _phong = new THREE.MeshPhongMaterial({});
-
 class EllipsoidMesh extends THREE.Mesh {
 
     constructor(parameters = {}) {
@@ -176,7 +173,6 @@ class EllipsoidMesh extends THREE.Mesh {
 
     set color(c) {
         // Change all colors
-        const color = new THREE.Color(c);
         
         // Handle DitherMaterial or standard material
         if (this.material.uniforms && this.material.uniforms.color) {

package/lib/primitives/isosurface.js

@@ -8,9 +8,6 @@ import {
 } from './dither.js';
 import { cellMatrix3, addStaticVar } from '../utils.js';
 
-// Basic materials
-const _phong = new THREE.MeshPhongMaterial({});
-
 class IsosurfaceMesh extends THREE.Mesh {
 
     constructor(field, threshold, lattice, parameters={}) {
@@ -60,7 +57,7 @@ class IsosurfaceMesh extends THREE.Mesh {
             dims[0] = field.length;
             dims[1] = field[0].length;
             dims[2] = field[0][0].length;
-        } catch (e) {
+        } catch {
             // If we're here, something is wrong with field
             throw Error('Invalid field for isosurface rendering');
         }

package/lib/query.js

@@ -57,7 +57,7 @@ class QueryParser {
         switch (names.length) {
             case 0:
                 return [];
-            case 1:
+            case 1: {
                 let name = names[0];
                 let args = query[name];
 
@@ -78,41 +78,16 @@ class QueryParser {
                     default:
                         throw new Error('Invalid query: query name not recognized');
                 }
-            default:
+            }
+            default: {
                 let queries = _.map(query, (v, k) => {
                     var q = {};
                     q[k] = v;
                     return q;
                 });
                 return this.and(queries);
-        }
-
-
-        for (let i = 0; i < names.length; ++i) {
-            let name = names[i];
-            let args = query[name];
-
-            if (!(args instanceof Array)) {
-                args = [args]; // Just for a single argument
             }
-
-            if (name in this._methods) {
-                // Then call the method
-                return this._methods[name].apply(this._context, args);
-            } else switch (name) {
-                case '$and':
-                    return this.and(args);
-                case '$or':
-                    return this.or(args);
-                case '$xor':
-                    return this.xor(args);
-                default:
-                    throw new Error('Invalid query: query name not recognized');
-            }
-
         }
-
-        var name = query[0];
     }
 
     and(queries) {

package/lib/tensor.js

@@ -7,7 +7,6 @@
 
 import _ from 'lodash';
 import * as mjs from 'mathjs';
-import * as THREE from 'three';
 
 const efg2hz = 234964.77815245767;
 const isc2hz = 1.6784031762379067e-16;    // hbar/(2*pi)*1e19

package/outdated.txt

@@ -0,0 +1,12 @@
+Package               Current   Wanted   Latest  Location                           Depended by
+@babel/eslint-parser   7.28.0   7.28.6   7.28.6  node_modules/@babel/eslint-parser  crystvis-js
+chai                    5.2.1    5.3.3    6.2.2  node_modules/chai                  crystvis-js
+chroma-js               3.1.2    3.2.0    3.2.0  node_modules/chroma-js             crystvis-js
+esbuild                0.25.6  0.25.12   0.27.2  node_modules/esbuild               crystvis-js
+eslint                 9.31.0   9.39.2   9.39.2  node_modules/eslint                crystvis-js
+glob                   11.1.0   11.1.0   13.0.0  node_modules/glob                  crystvis-js
+jquery                  3.7.1    3.7.1    4.0.0  node_modules/jquery                crystvis-js
+jsdoc                   4.0.4    4.0.5    4.0.5  node_modules/jsdoc                 crystvis-js
+mathjs                 14.5.3   14.9.1   15.1.0  node_modules/mathjs                crystvis-js
+mocha                  11.7.1   11.7.5   11.7.5  node_modules/mocha                 crystvis-js
+three                 0.178.0  0.178.0  0.182.0  node_modules/three                 crystvis-js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccp-nc/crystvis-js",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "A Three.js based crystallographic visualisation tool",
   "main": "index.js",
   "type": "module",
@@ -72,33 +72,32 @@
     "@ccp-nc/crystcif-parse": "^0.2.9",
     "@jkshenton/three-bmfont-text": "^4.0.1",
     "buffer": "^6.0.3",
-    "chroma-js": "^3.1.2",
+    "chroma-js": "^3.2.0",
     "isosurface": "^1.0.0",
     "jquery": "^3.7.1",
     "load-bmfont": "^1.4.2",
     "lodash": "^4.17.21",
-    "mathjs": "^14.5.3",
+    "mathjs": "^14.9.1",
     "three": "^0.178.0",
     "yargs-parser": "^22.0.0"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "^7.28.0",
-    "chai": "^5.2.1",
+    "@babel/eslint-parser": "^7.28.6",
+    "chai": "^5.3.3",
     "chai-almost": "^1.0.1",
     "clean-jsdoc-theme": "^4.3.0",
     "datauri": "^4.1.0",
-    "elliptic": ">=6.6.1",
-    "esbuild": "^0.25.6",
-    "eslint": "^9.31.0",
+    "esbuild": "^0.25.12",
+    "eslint": "^9.39.2",
     "gh-pages": "^6.3.0",
-    "glob": "^11.0.3",
-    "jpeg-js": ">=0.4.4",
-    "jsdoc": "^4.0.4",
+    "glob": "^11.1.0",
+    "jpeg-js": "^0.4.4",
+    "jsdoc": "^4.0.5",
     "minimist": "^1.2.8",
-    "mocha": "^11.7.1",
-    "msdf-bmfont-xml": "^2.7.0",
+    "mocha": "^11.7.5",
+    "msdf-bmfont-xml": "^2.8.0",
     "npm-watch": "^0.13.0",
-    "serve": "^14.2.4"
+    "serve": "^14.2.5"
   },
   "overrides": {
     "minimist": "$minimist"

package/test/data/ethanol_with_tensors.xyz

@@ -0,0 +1,33 @@
+9
+Lattice="20.0 0.0 0.0 0.0 20.0 0.0 0.0 0.0 20.0" Properties=species:S:1:pos:R:3:ms:R:9 pbc="T T T"
+C        0.05539939      -0.60057807       0.62649405     125.81813960      -9.69204056       1.47151834      -9.69204056     152.57296730     -15.37444798       1.47151834     -15.37444798     153.40518054
+C       -0.30393478       0.62801927      -0.09541083      67.25341634     -10.54059929     -10.70968980     -10.54059929      76.17154239       7.81637325     -10.70968980       7.81637325     131.81262332
+O        0.02847236       0.40911809      -1.55058241     142.74157885     -23.92176821     -21.41240976     -23.92176821     150.62543764       7.18471731     -21.41240976       7.18471731     205.63479341
+H       -0.71042240      -0.84152627       1.36951625      31.54030509       0.67457781      -2.05943366       0.67457781      27.78821965      -2.78219193      -2.05943366      -2.78219193      29.56439885
+H        0.05685210      -1.46800745      -0.03997531      25.12335152      -1.32245778      -1.01062680      -1.32245778      29.43896220      -0.62651903      -1.01062680      -0.62651903      26.16607133
+H        1.01360786      -0.50363368       1.14519882      27.17911795      -2.04842122       0.83359139      -2.04842122      29.62583333      -0.39001171       0.83359139      -0.39001171      29.84956008
+H        0.29595155       1.48046374       0.23638874      22.79911499      -1.48276746      -1.60906958      -1.48276746      23.25594937      -1.80556513      -1.60906958      -1.80556513      25.48107695
+H       -1.38620961       0.77880669      -0.04469536      21.43976417      -1.06047575      -2.00845616      -1.06047575      26.04861314      -0.56302310      -2.00845616      -0.56302310      28.05747534
+H        0.95028353       0.11733764      -1.64693403      26.05496271      -0.59980912       1.29686340      -0.59980912      27.35984859       1.09066721       1.29686340       1.09066721      11.92762208
+9
+Lattice="20.0 0.0 0.0 0.0 20.0 0.0 0.0 0.0 20.0" Properties=species:S:1:pos:R:3:ms:R:9 pbc="T T T"
+C       -0.40320021      -0.45122528       0.73024166     132.90497460       3.59552794     -12.43391876       3.59552794     127.77706275     -12.28247854     -12.43391876     -12.28247854     148.26339821
+C       -0.08346952       0.15676123      -0.68547010     122.86689596      -2.07500597      -3.96961991      -2.07500597      66.98638751     -15.21036672      -3.96961991     -15.21036672      91.39017108
+O        1.32339168       0.48240674      -0.82522243     224.49194781      16.57134021       0.49540797      16.57134021     165.51833992      -2.95162455       0.49540797      -2.95162455     201.51744849
+H       -1.45097303      -0.17661801       0.88316929      31.39533363      -1.50216432      -2.08575051      -1.50216432      27.90719213      -2.17636659      -2.08575051      -2.17636659      24.58283530
+H       -0.38172311      -1.54280162       0.66229165      28.71581869       0.65206504       0.24523305       0.65206504      33.47771386      -0.13534390       0.24523305      -0.13534390      28.16152002
+H        0.34883970      -0.09896098       1.44225454      29.07964610      -0.53596286      -0.80798570      -0.53596286      29.54542507      -0.15879025      -0.80798570      -0.15879025      30.87386769
+H       -0.49669987       1.16926062      -0.71196169      30.60576444       0.72622326      -1.87887897       0.72622326      21.85971975      -3.21777764      -1.87887897      -3.21777764      22.96413413
+H       -0.47664648      -0.52174139      -1.44814277      29.76964783      -1.12461680      -0.30705060      -1.12461680      24.74071487      -2.76789311      -0.30705060      -2.76789311      26.03554994
+H        1.62048090       0.98291862      -0.04716024      15.17890396      -2.46795510       2.53393948      -2.46795510      26.09809172       2.27749188       2.53393948       2.27749188      27.54652654
+9
+Lattice="20.0 0.0 0.0 0.0 20.0 0.0 0.0 0.0 20.0" Properties=species:S:1:pos:R:3:ms:R:9 pbc="T T T"
+C       -0.69807410      -0.44723904       0.24317208     152.92455307      16.26391385      -4.26821306      16.26391385     125.77540629     -16.76320152      -4.26821306     -16.76320152     130.73689699
+C        0.34105554       0.29010150      -0.60698903     102.07784519      13.93734131      16.33479642      13.93734131      80.61538795      -4.05889589      16.33479642      -4.05889589     102.80989037
+O        1.46549475       0.45275295       0.25985932     199.78462184      11.22005439       7.45063951      11.22005439     154.96249301      15.23597911       7.45063951      15.23597911     211.90087809
+H       -0.70180583      -0.01803672       1.24934685      29.98454565      -0.25724168      -2.21732555      -0.25724168      27.45870874      -0.14606383      -2.21732555      -0.14606383      29.16124917
+H       -1.72323835      -0.53104490      -0.12916072      34.48333304      -0.20546525       2.22402884      -0.20546525      27.38393293       0.02054883       2.22402884       0.02054883      25.44008375
+H       -0.45866823      -1.50883543       0.35415125      27.22086782      -0.14588137      -0.17633240      -0.14588137      31.74670019       0.04446484      -0.17633240       0.04446484      28.30452212
+H       -0.09631128       1.20396113      -1.01952636      26.48360645       2.31248543       1.04328519       2.31248543      24.46949466      -2.22404337       1.04328519      -2.22404337      24.50418879
+H        0.70887178      -0.35195473      -1.41265452      26.93480331       1.70750614       1.51654145       1.70750614      22.16202488      -2.45242451       1.51654145      -2.45242451      23.38735678
+H        1.16267574       0.91029525       1.06180108      15.18096611      -3.57189977      -7.34818913      -3.57189977      25.05233266      -0.90280873      -7.34818913      -0.90280873      24.27668518