matterviz 0.3.7 → 0.4.0

package/dist/structure/export.js

@@ -108,6 +108,7 @@ export function generate_mtl_content(scene) {
         const materials = Array.isArray(object.material) ? object.material : [object.material];
         for (const mat of materials) {
             // Skip if already processed or no name
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty name should use default
             const mat_name = mat.name || `default_material`;
             if (processed_materials.has(mat_name))
                 continue;
@@ -294,10 +295,10 @@ function convert_instanced_meshes_to_regular(scene) {
 // Generate a filename for structure exports based on structure metadata
 // Sanitize string for use in filenames by removing problematic characters.
 const sanitize_filename_part = (text) => text
-    .replace(/<\/?[^>]+>/g, ``) // strip HTML tags
-    .replace(/[/\\:*?"<>|]/g, `_`) // replace filesystem-invalid chars
-    .replace(/_+/g, `_`) // condense consecutive underscores
-    .replace(/^_|_$/g, ``); // remove leading/trailing underscores
+    .replaceAll(/<\/?[^>]+>/g, ``) // strip HTML tags
+    .replaceAll(/[/\\:*?"<>|]/g, `_`) // replace filesystem-invalid chars
+    .replaceAll(/_+/g, `_`) // condense consecutive underscores
+    .replaceAll(/^_|_$/g, ``); // remove leading/trailing underscores
 export function create_structure_filename(structure, extension) {
     if (!structure)
         return `structure.${extension}`;
@@ -432,7 +433,7 @@ function get_cif_block_name(structure) {
         if (structure.id) {
             // Remove invalid CIF characters (keep alphanumerics and underscores)
             // and condense consecutive underscores for cleaner block names
-            return structure.id.replace(/[^a-zA-Z0-9_]/g, `_`).replace(/_+/g, `_`);
+            return structure.id.replaceAll(/[^a-zA-Z0-9_]/g, `_`).replaceAll(/_+/g, `_`);
         }
         return `structure`;
     }
@@ -469,7 +470,8 @@ export function structure_to_cif_str(structure) {
         const symmetry = structure.symmetry;
         const { space_group_number, space_group_symbol } = symmetry;
         if (typeof space_group_symbol === `string` && space_group_symbol) {
-            lines.push(`_space_group_name_H-M_alt ${space_group_symbol}`);
+            // Quote H-M symbols: their spaces (e.g. 'F m -3 m') would break CIF tokenization
+            lines.push(`_space_group_name_H-M_alt '${space_group_symbol}'`);
         }
         if ((typeof space_group_number === `number` || typeof space_group_number === `string`) &&
             space_group_number) {
@@ -477,6 +479,9 @@ export function structure_to_cif_str(structure) {
         }
     }
     lines.push(``);
+    // Explicit identity-only symmetry-ops loop (like pymatgen's CifWriter): sites are the
+    // full P1 list, so without it parsers would re-apply the H-M ops and multiply sites
+    lines.push(`loop_`, `_symmetry_equiv_pos_as_xyz`, `  'x, y, z'`, ``);
     // Atom site loop header
     lines.push(`loop_`);
     lines.push(`_atom_site_label`);
@@ -487,24 +492,15 @@ export function structure_to_cif_str(structure) {
     lines.push(`_atom_site_occupancy`);
     // Cache inverse transpose for Cartesian→fractional conversion (avoids recomputing per site)
     const cart_to_frac = lattice.matrix?.length === 3 ? math.create_cart_to_frac(lattice.matrix) : null;
-    // Atom sites
+    // Atom sites: one row per species entry so disordered (multi-species) sites
+    // keep every component with its own occupancy instead of only species[0]
     for (let idx = 0; idx < structure.sites.length; idx++) {
         const site = structure.sites[idx];
         if (!site)
             continue; // Skip if site is undefined
-        // Extract element symbol from species
-        let element_symbol = `X`; // default fallback
-        let occupancy = 1;
-        if (site.species && Array.isArray(site.species) && site.species.length > 0) {
-            const first_species = site.species[0];
-            if (first_species && `element` in first_species && first_species.element) {
-                element_symbol = first_species.element;
-                occupancy = first_species?.occu ?? 1;
-            }
-        }
         // Get fractional coordinates
         let frac_coords;
-        if (site.abc && Array.isArray(site.abc) && site.abc.length >= 3) {
+        if (Array.isArray(site.abc) && site.abc.length >= 3) {
             frac_coords = site.abc.slice(0, 3);
         }
         else if (site.xyz?.length >= 3 && cart_to_frac) {
@@ -512,9 +508,17 @@ export function structure_to_cif_str(structure) {
         }
         else
             throw new Error(`No valid coordinates found for site ${idx}`);
-        // Format: label element_symbol x y z
-        const label = site.label || `${element_symbol}${idx + 1}`;
-        lines.push(`${label} ${element_symbol} ${frac_coords[0].toFixed(8)} ${frac_coords[1].toFixed(8)} ${frac_coords[2].toFixed(8)} ${occupancy.toFixed(8)}`);
+        const coords_str = frac_coords.map((coord) => coord.toFixed(8)).join(` `);
+        const species_list = site.species?.length ? site.species : [{ element: `X`, occu: 1 }];
+        for (const [spec_idx, species] of species_list.entries()) {
+            const elem = species?.element || `X`;
+            // Row format: label element x y z occupancy. Labels must be unique per row,
+            // so disordered sites get a per-species suffix.
+            const label = species_list.length > 1
+                ? `${elem}${idx + 1}_${spec_idx}`
+                : site.label || `${elem}${idx + 1}`;
+            lines.push(`${label} ${elem} ${coords_str} ${(species?.occu ?? 1).toFixed(8)}`);
+        }
     }
     return lines.join(`\n`);
 }
@@ -528,8 +532,8 @@ export function structure_to_poscar_str(structure) {
     const lines = [];
     // Use plain text formula for POSCAR title to avoid HTML tags
     const formula = get_electro_neg_formula(structure, true);
-    const title = structure.id ||
-        (formula && formula !== `Unknown` ? formula : null) ||
+    const title = structure.id || // oxlint-disable-line @typescript-eslint/prefer-nullish-coalescing -- first non-empty string
+        (formula && formula !== `Unknown` ? formula : null) || // oxlint-disable-line @typescript-eslint/prefer-nullish-coalescing -- first non-empty string
         `Generated from structure`;
     lines.push(title);
     lines.push(`1.0`); // Scale factor (1.0 for direct coordinates)

package/dist/structure/index.d.ts

@@ -36,9 +36,7 @@ export type Site = {
     properties: Record<string, unknown>;
 };
 export declare const LATTICE_PARAM_KEYS: readonly ["a", "b", "c", "alpha", "beta", "gamma"];
-export type LatticeParams = {
-    [key in (typeof LATTICE_PARAM_KEYS)[number]]: number;
-};
+export type LatticeParams = Record<(typeof LATTICE_PARAM_KEYS)[number], number>;
 export type LatticeType = {
     matrix: math.Matrix3x3;
     pbc: Pbc;
@@ -84,7 +82,7 @@ export declare const atomic_radii: CompositionType;
 export declare function get_density(structure: Crystal): number;
 export declare function get_center_of_mass(structure: AnyStructure): Vec3;
 export declare const VECTOR_KEY_PREFIXES: readonly ["force", "forces", "magmom", "magmoms", "spin", "spins"];
-export declare function is_vector_key(key: string): boolean;
+export declare const is_vector_key: (key: string) => boolean;
 export declare const VECTOR_PALETTE: readonly ["#e74c3c", "#3498db", "#2ecc71", "#f39c12", "#9b59b6", "#1abc9c"];
 export declare const default_vector_configs: (keys: string[]) => {
     [k: string]: {

package/dist/structure/index.js

@@ -94,9 +94,7 @@ export const VECTOR_KEY_PREFIXES = [
     `spin`,
     `spins`,
 ];
-export function is_vector_key(key) {
-    return VECTOR_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}_`));
-}
+export const is_vector_key = (key) => VECTOR_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}_`));
 // Default color palette for distinguishing multiple vector layers
 export const VECTOR_PALETTE = [
     `#e74c3c`,

package/dist/structure/label-placement.js

@@ -26,8 +26,8 @@ export const choose_site_label_offset = (bond_directions, base_offset) => {
     if (offset_length < LABEL_OFFSET_EPS || bond_directions.length === 0) {
         return base_offset;
     }
-    const preferred_direction = math.normalize_vec3(base_offset, [0, 1, 0]);
-    const repulsion_direction = math.normalize_vec3(bond_directions.reduce((offset_sum, bond_direction) => math.subtract(offset_sum, bond_direction), [0, 0, 0]), preferred_direction);
+    const preferred_direction = math.normalize_vec(base_offset, [0, 1, 0]);
+    const repulsion_direction = math.normalize_vec(bond_directions.reduce((offset_sum, bond_direction) => math.subtract(offset_sum, bond_direction), [0, 0, 0]), preferred_direction);
     let best_direction = preferred_direction;
     let best_score = -Infinity;
     for (const candidate_direction of [
@@ -35,7 +35,7 @@ export const choose_site_label_offset = (bond_directions, base_offset) => {
         repulsion_direction,
         ...LABEL_OFFSET_DIRECTIONS,
     ]) {
-        const direction = math.normalize_vec3(candidate_direction, preferred_direction);
+        const direction = math.normalize_vec(candidate_direction, preferred_direction);
         const score = label_direction_score(direction, bond_directions, preferred_direction);
         if (score <= best_score + LABEL_OFFSET_EPS)
             continue;
@@ -59,7 +59,7 @@ export const label_screen_position = (atom_position, label_offset, visual_radius
     const offset_length = Math.hypot(offset_x, offset_y);
     const direction_x = offset_length > LABEL_OFFSET_EPS ? offset_x / offset_length : 0;
     const direction_y = offset_length > LABEL_OFFSET_EPS ? offset_y / offset_length : label_offset[1] >= 0 ? -1 : 1;
-    const radius_direction = math.normalize_vec3(label_offset, [0, 1, 0]);
+    const radius_direction = math.normalize_vec(label_offset, [0, 1, 0]);
     const radius_edge = math.add(atom_position, math.scale(radius_direction, visual_radius));
     const radius_screen = project_to_screen(radius_edge, label_camera, size);
     const atom_screen_radius = Math.hypot(radius_screen[0] - atom_screen[0], radius_screen[1] - atom_screen[1]);

package/dist/structure/measure.d.ts

@@ -1,6 +1,7 @@
 import type { LatticeConverters, Matrix3x3, Vec3 } from '../math';
+import type { Pbc } from './pbc';
 export type AngleMode = `degrees` | `radians`;
 export declare const MAX_SELECTED_SITES = 8;
-export declare function displacement_pbc(from: Vec3, to: Vec3, lattice_matrix: Matrix3x3 | null | undefined, converters?: LatticeConverters): Vec3;
-export declare function distance_pbc(a: Vec3, b: Vec3, lattice_matrix: Matrix3x3): number;
+export declare function displacement_pbc(from: Vec3, to: Vec3, lattice_matrix: Matrix3x3 | null | undefined, converters?: LatticeConverters, pbc?: Pbc): Vec3;
+export declare function distance_pbc(a: Vec3, b: Vec3, lattice_matrix: Matrix3x3, converters?: LatticeConverters, pbc?: Pbc): number;
 export declare function angle_between_vectors(v1: Vec3, v2: Vec3, mode?: AngleMode): number;

package/dist/structure/measure.js

@@ -2,14 +2,15 @@
 import { min_image_displacement, subtract } from '../math';
 export const MAX_SELECTED_SITES = 8;
 // Calculate minimum image displacement between two points under PBC
-// If lattice_matrix is null/undefined, returns Euclidean displacement
-export function displacement_pbc(from, to, lattice_matrix, converters) {
+// If lattice_matrix is null/undefined, returns Euclidean displacement.
+// pbc flags disable wrapping along non-periodic axes (e.g. slab vacuum directions).
+export function displacement_pbc(from, to, lattice_matrix, converters, pbc) {
     if (!lattice_matrix)
         return subtract(to, from);
-    return min_image_displacement(from, to, lattice_matrix, converters);
+    return min_image_displacement(from, to, lattice_matrix, converters, pbc);
 }
-export function distance_pbc(a, b, lattice_matrix) {
-    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix);
+export function distance_pbc(a, b, lattice_matrix, converters, pbc) {
+    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix, converters, pbc);
     return Math.hypot(dx, dy, dz);
 }
 export function angle_between_vectors(v1, v2, mode = `degrees`) {