matterviz 0.3.1 → 0.3.3

package/dist/isosurface/parse.js

@@ -1,11 +1,10 @@
 // Parsers for volumetric data file formats (VASP CHGCAR, Gaussian .cube)
-import { VASP_VOLUMETRIC_REGEX } from '../constants';
+import { COMPRESSION_EXTENSIONS_REGEX, VASP_VOLUMETRIC_REGEX } from '../constants';
 import { ELEM_SYMBOLS } from '../labels';
 import * as math from '../math';
+import { wrap_to_unit_cell } from '../structure/pbc';
 // Bohr radius in Angstroms (for Gaussian .cube unit conversion)
 const BOHR_TO_ANGSTROM = 0.529177249;
-// Wrap a value to [0, 1) range for fractional coordinates
-const wrap_frac = (val) => val - Math.floor(val);
 // === Fast number parsing utilities ===
 // Parse whitespace-separated numbers directly from a string, starting at `pos`.
 // Writes into a pre-allocated Float64Array and returns { count, end_pos }.
@@ -87,13 +86,9 @@ function read_lines(text, pos, count) {
     }
     return { lines: result, next: pos };
 }
-// Build 3D grid directly from Float64Array, computing data_range in the same pass.
-function build_grid(data, nx, ny, nz, divisor = 1) {
+function build_grid({ data, nx, ny, nz, divisor = 1, data_order = `z_fastest`, }) {
     const grid = new Array(nx);
-    let min_val = Infinity;
-    let max_val = -Infinity;
-    let sum = 0;
-    const ny_nz = ny * nz;
+    let [min_val, max_val, sum] = [Infinity, -Infinity, 0];
     const total = nx * ny * nz;
     const data_len = Math.min(data.length, total);
     if (data_len === 0) {
@@ -106,39 +101,68 @@ function build_grid(data, nx, ny, nz, divisor = 1) {
         }
         return { grid, data_range: { min: 0, max: 0, abs_max: 0, mean: 0 } };
     }
-    for (let ix = 0; ix < nx; ix++) {
-        const plane = new Array(ny);
-        for (let iy = 0; iy < ny; iy++) {
-            const row = new Array(nz).fill(0);
-            const base = ix * ny_nz + iy * nz;
-            const row_end = Math.min(base + nz, data_len);
-            for (let flat_idx = base; flat_idx < row_end; flat_idx++) {
-                const val = data[flat_idx] / divisor;
-                row[flat_idx - base] = val;
-                if (val < min_val)
-                    min_val = val;
-                if (val > max_val)
-                    max_val = val;
-                sum += val;
+    if (data_order === `z_fastest`) {
+        // .cube convention: z varies fastest, then y, then x.
+        const ny_nz = ny * nz;
+        for (let ix = 0; ix < nx; ix++) {
+            const plane = new Array(ny);
+            for (let iy = 0; iy < ny; iy++) {
+                const row = new Array(nz).fill(0);
+                const base = ix * ny_nz + iy * nz;
+                const row_end = Math.min(base + nz, data_len);
+                for (let flat_idx = base; flat_idx < row_end; flat_idx++) {
+                    const val = data[flat_idx] / divisor;
+                    row[flat_idx - base] = val;
+                    if (val < min_val)
+                        min_val = val;
+                    if (val > max_val)
+                        max_val = val;
+                    sum += val;
+                }
+                plane[iy] = row;
             }
-            plane[iy] = row;
+            grid[ix] = plane;
+        }
+    }
+    else {
+        // VASP CHGCAR/ELFCAR/LOCPOT convention: x varies fastest, then y, then z.
+        for (let ix = 0; ix < nx; ix++) {
+            const plane = new Array(ny);
+            for (let iy = 0; iy < ny; iy++)
+                plane[iy] = new Array(nz).fill(0);
+            grid[ix] = plane;
+        }
+        let [flat_idx, data_exhausted] = [0, false];
+        for (let iz = 0; iz < nz; iz++) {
+            for (let iy = 0; iy < ny; iy++) {
+                for (let ix = 0; ix < nx; ix++) {
+                    if (flat_idx >= data_len) {
+                        data_exhausted = true;
+                        break;
+                    }
+                    const val = data[flat_idx] / divisor;
+                    grid[ix][iy][iz] = val;
+                    if (val < min_val)
+                        min_val = val;
+                    if (val > max_val)
+                        max_val = val;
+                    sum += val;
+                    flat_idx++;
+                }
+                if (data_exhausted)
+                    break;
+            }
+            if (data_exhausted)
+                break;
         }
-        grid[ix] = plane;
     }
     const abs_max = Math.max(Math.abs(min_val), Math.abs(max_val));
-    return {
-        grid,
-        data_range: {
-            min: min_val,
-            max: max_val,
-            abs_max,
-            mean: sum / data_len,
-        },
-    };
+    const data_range = { min: min_val, max: max_val, abs_max, mean: sum / data_len };
+    return { grid, data_range };
 }
 // === CHGCAR Parser ===
-// Parse VASP CHGCAR/AECCAR/ELFCAR/LOCPOT file format.
-// CHGCAR consists of a POSCAR header followed by volumetric data on a 3D grid.
+// Parse VASP CHGCAR/AECCAR/ELFCAR/LOCPOT/PARCHG file format.
+// CHGCAR/PARCHG consists of a POSCAR header followed by volumetric data on a 3D grid.
 // Spin-polarized files contain two data blocks (total charge + magnetization).
 export function parse_chgcar(content) {
     // Strip leading whitespace
@@ -212,8 +236,16 @@ export function parse_chgcar(content) {
     const is_direct = cur.line.trim().toUpperCase().startsWith(`D`);
     pos = cur.next;
     // Parse atomic positions
-    const lattice_transposed = math.transpose_3x3_matrix(lattice);
-    const lattice_inv = math.matrix_inverse_3x3(lattice_transposed);
+    let cart_to_frac;
+    let frac_to_cart;
+    try {
+        ;
+        ({ cart_to_frac, frac_to_cart } = math.create_lattice_converters(lattice));
+    }
+    catch {
+        console.error(`CHGCAR: lattice matrix is singular; cannot convert coordinates`);
+        return null;
+    }
     const sites = [];
     let atom_idx = 0;
     for (let elem_idx = 0; elem_idx < element_symbols.length; elem_idx++) {
@@ -231,13 +263,13 @@ export function parse_chgcar(content) {
             let abc;
             let xyz;
             if (is_direct) {
-                abc = [wrap_frac(coords[0]), wrap_frac(coords[1]), wrap_frac(coords[2])];
-                xyz = math.mat3x3_vec3_multiply(lattice_transposed, abc);
+                abc = wrap_to_unit_cell(coords);
+                xyz = frac_to_cart(abc);
             }
             else {
                 xyz = math.scale(coords, scale_factor);
-                const raw = math.mat3x3_vec3_multiply(lattice_inv, xyz);
-                abc = [wrap_frac(raw[0]), wrap_frac(raw[1]), wrap_frac(raw[2])];
+                const raw = cart_to_frac(xyz);
+                abc = wrap_to_unit_cell(raw);
             }
             sites.push({
                 species: [{ element, occu: 1, oxidation_state: 0 }],
@@ -289,13 +321,21 @@ export function parse_chgcar(content) {
         // Use Math.abs to guard against negative determinant (left-handed lattice).
         const cell_volume = Math.abs(lattice_params.volume);
         const divisor = cell_volume > 1e-30 ? cell_volume : 1;
-        const { grid, data_range } = build_grid(data.subarray(0, parsed_count), ngx, ngy, ngz, divisor);
+        const { grid, data_range } = build_grid({
+            data: data.subarray(0, parsed_count),
+            nx: ngx,
+            ny: ngy,
+            nz: ngz,
+            divisor,
+            data_order: `x_fastest`,
+        });
         volumes.push({
             grid,
             grid_dims: [ngx, ngy, ngz],
             lattice,
             origin: [0, 0, 0],
             data_range,
+            data_order: `x_fastest`,
             periodic: true, // VASP grids span [0,1) with N points, wrapping at boundaries
             label: volume_labels[vol_idx],
         });
@@ -378,21 +418,22 @@ export function parse_cube(content, options = {}) {
     const is_periodic = options.periodic ?? Math.hypot(...origin) < 1e-6;
     // Parse atomic positions
     const sites = [];
-    const lattice_transposed = math.transpose_3x3_matrix(lattice);
-    let lattice_inv;
+    let cube_cart_to_frac;
     try {
-        lattice_inv = math.matrix_inverse_3x3(lattice_transposed);
+        cube_cart_to_frac = math.create_cart_to_frac(lattice);
     }
     catch {
         // Non-periodic system (molecule), use identity
-        lattice_inv = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+        cube_cart_to_frac = (v) => [v[0], v[1], v[2]];
     }
     for (let atom_idx = 0; atom_idx < n_atoms; atom_idx++) {
         const cur = read_line(content, pos);
         const atom_line = cur.line.trim().split(/\s+/).map(Number);
         pos = cur.next;
         // Validate: need atomic_number, charge, x, y, z (5 tokens, indices 2-4 finite)
-        if (atom_line.length < 5 || !isFinite(atom_line[2]) || !isFinite(atom_line[3]) ||
+        if (atom_line.length < 5 ||
+            !isFinite(atom_line[2]) ||
+            !isFinite(atom_line[3]) ||
             !isFinite(atom_line[4])) {
             console.warn(`.cube atom ${atom_idx}: malformed line "${cur.line.trim()}", skipping`);
             continue;
@@ -402,7 +443,7 @@ export function parse_cube(content, options = {}) {
         // Convert Cartesian to fractional, accounting for origin offset.
         // Store lattice-frame xyz (shifted) so abc and xyz stay consistent.
         const xyz = math.subtract(raw_xyz, origin);
-        const abc = math.mat3x3_vec3_multiply(lattice_inv, xyz);
+        const abc = cube_cart_to_frac(xyz);
         const element = atomic_number_to_symbol(atom_line[0]);
         sites.push({
             species: [{ element, occu: 1, oxidation_state: 0 }],
@@ -438,30 +479,37 @@ export function parse_cube(content, options = {}) {
             return null;
         }
     }
-    const { grid, data_range } = build_grid(data.subarray(0, parsed_count), n_grid[0], n_grid[1], n_grid[2]);
-    const volumes = [{
+    const { grid, data_range } = build_grid({
+        data: data.subarray(0, parsed_count),
+        nx: n_grid[0],
+        ny: n_grid[1],
+        nz: n_grid[2],
+        data_order: `z_fastest`,
+    });
+    const volumes = [
+        {
             grid,
             grid_dims: n_grid,
             lattice,
             origin,
             data_range,
+            data_order: `z_fastest`,
             periodic: is_periodic, // periodic systems wrap; molecular .cube files include both endpoints
             label: `volumetric data`,
-        }];
+        },
+    ];
     return { structure, volumes };
 }
 // Convert atomic number to element symbol using ELEM_SYMBOLS (1-indexed: H=1, He=2, ...)
 function atomic_number_to_symbol(atomic_number) {
     // ELEM_SYMBOLS is 0-indexed (H at index 0), atomic numbers are 1-indexed
     const idx = atomic_number - 1;
-    return (idx >= 0 && idx < ELEM_SYMBOLS.length
-        ? ELEM_SYMBOLS[idx]
-        : `H`);
+    return (idx >= 0 && idx < ELEM_SYMBOLS.length ? ELEM_SYMBOLS[idx] : `H`);
 }
 // Auto-detect and parse volumetric file format based on filename and content
 export function parse_volumetric_file(content, filename) {
     // Strip compression suffixes so "CHGCAR.gz" and "molecule.cube.bz2" match correctly
-    const lower_name = (filename ?? ``).toLowerCase().replace(/\.(gz|bz2|xz|zst)$/, ``);
+    const lower_name = (filename ?? ``).toLowerCase().replace(COMPRESSION_EXTENSIONS_REGEX, ``);
     // Extension-based detection
     if (lower_name.endsWith(`.cube`))
         return parse_cube(content);

package/dist/isosurface/slice.d.ts

@@ -1,3 +1,4 @@
+import type { Vec3 } from '../math';
 import type { VolumetricData } from './types';
 export interface SliceResult {
     data: Float64Array;
@@ -7,4 +8,4 @@ export interface SliceResult {
     max: number;
 }
 export declare function trilinear_interpolate(grid: number[][][], fx: number, fy: number, fz: number, periodic: boolean): number;
-export declare function sample_hkl_slice(volume: VolumetricData, miller_indices: [number, number, number], distance: number): SliceResult | null;
+export declare function sample_hkl_slice(volume: VolumetricData, miller_indices: Vec3, distance: number, n_points?: number): SliceResult | null;

package/dist/isosurface/slice.js

@@ -56,7 +56,7 @@ export function trilinear_interpolate(grid, fx, fy, fz, periodic) {
 // `miller_indices` [h,k,l] defines the plane normal in reciprocal space.
 // `distance` is fractional [0,1] along the normal direction within the cell.
 // Returns null if indices are all zero.
-export function sample_hkl_slice(volume, miller_indices, distance) {
+export function sample_hkl_slice(volume, miller_indices, distance, n_points) {
     const [h_idx, k_idx, l_idx] = miller_indices;
     if (h_idx === 0 && k_idx === 0 && l_idx === 0)
         return null;
@@ -74,9 +74,7 @@ export function sample_hkl_slice(volume, miller_indices, distance) {
     const unit_normal = math.normalize_vec3(plane_normal);
     // In-plane basis vectors
     const [u_vec, v_vec] = math.compute_in_plane_basis(unit_normal);
-    // Compute lattice inverse for Cartesian → fractional conversion.
-    // lattice rows are vectors [a, b, c], so cart = lattice^T * frac → frac = inv(lattice^T) * cart
-    const lattice_inv = math.matrix_inverse_3x3(math.transpose_3x3_matrix(lattice));
+    const cart_to_frac = math.create_cart_to_frac(lattice);
     // Project all 8 unit cell corners onto the (u, v) plane to find sampling bounds.
     // Corners are at fractional coords (0 or 1) for each axis.
     let u_min = Infinity;
@@ -86,9 +84,9 @@ export function sample_hkl_slice(volume, miller_indices, distance) {
     let normal_min = Infinity;
     let normal_max = -Infinity;
     for (let ci = 0; ci < 8; ci++) {
-        const fi = (ci & 1) ? 1 : 0;
-        const fj = (ci & 2) ? 1 : 0;
-        const fk = (ci & 4) ? 1 : 0;
+        const fi = ci & 1 ? 1 : 0;
+        const fj = ci & 2 ? 1 : 0;
+        const fk = ci & 4 ? 1 : 0;
         // Corner in Cartesian: frac * lattice
         const corner = [
             fi * lattice[0][0] + fj * lattice[1][0] + fk * lattice[2][0],
@@ -113,8 +111,8 @@ export function sample_hkl_slice(volume, miller_indices, distance) {
     }
     // Plane position: fractional distance [0,1] along the normal extent
     const d_cartesian = normal_min + distance * (normal_max - normal_min);
-    // Sampling resolution: square grid using max dimension
-    const width = Math.max(nx, ny, nz);
+    // Sampling resolution: caller-specified or default to max grid dimension
+    const width = n_points ?? Math.max(nx, ny, nz);
     const height = width;
     const data = new Float64Array(width * height);
     let data_min = Infinity;
@@ -129,10 +127,7 @@ export function sample_hkl_slice(volume, miller_indices, distance) {
             const px = d_cartesian * unit_normal[0] + u_val * u_vec[0] + v_val * v_vec[0];
             const py = d_cartesian * unit_normal[1] + u_val * u_vec[1] + v_val * v_vec[1];
             const pz = d_cartesian * unit_normal[2] + u_val * u_vec[2] + v_val * v_vec[2];
-            // Convert to fractional coordinates: frac = lattice_inv * p
-            const fx = lattice_inv[0][0] * px + lattice_inv[0][1] * py + lattice_inv[0][2] * pz;
-            const fy = lattice_inv[1][0] * px + lattice_inv[1][1] * py + lattice_inv[1][2] * pz;
-            const fz = lattice_inv[2][0] * px + lattice_inv[2][1] * py + lattice_inv[2][2] * pz;
+            const [fx, fy, fz] = cart_to_frac([px, py, pz]);
             const val = trilinear_interpolate(grid, fx, fy, fz, periodic);
             data[row * width + col] = val;
             if (val < data_min)

package/dist/isosurface/types.d.ts

@@ -8,10 +8,11 @@ export interface DataRange {
 }
 export interface VolumetricData {
     grid: number[][][];
-    grid_dims: [number, number, number];
+    grid_dims: Vec3;
     lattice: Matrix3x3;
     origin: Vec3;
     data_range: DataRange;
+    data_order?: `x_fastest` | `z_fastest`;
     periodic: boolean;
     label?: string;
 }
@@ -34,10 +35,22 @@ export interface IsosurfaceSettings {
     negative_color: string;
     show_negative: boolean;
     wireframe: boolean;
+    halo: number;
     layers?: IsosurfaceLayer[];
 }
 export declare const LAYER_COLORS: readonly ["#3b82f6", "#ef4444", "#22c55e", "#a855f7", "#f97316", "#06b6d4", "#eab308", "#ec4899"];
 export declare function grid_data_range(grid: number[][][]): DataRange;
+export declare function pad_periodic_grid(grid: number[][][], dims: Vec3, pad_fraction: number): {
+    grid: number[][][];
+    dims: Vec3;
+    offset: Vec3;
+};
+export declare function downsample_grid(grid: number[][][], dims: Vec3, max_points?: number): {
+    grid: number[][][];
+    dims: Vec3;
+    factor: number;
+};
 export declare const DEFAULT_ISOSURFACE_SETTINGS: IsosurfaceSettings;
 export declare function auto_isosurface_settings(data_range: DataRange): IsosurfaceSettings;
 export declare function generate_layers(data_range: DataRange, n_layers: number): IsosurfaceLayer[];
+export declare function tile_volumetric_data(volume: VolumetricData, scaling: Vec3): VolumetricData;

package/dist/isosurface/types.js

@@ -1,3 +1,4 @@
+import { scale_lattice_matrix } from '../math';
 // Categorical palette for auto-coloring isosurface layers (Tailwind-inspired)
 export const LAYER_COLORS = [
     `#3b82f6`, // blue
@@ -15,8 +16,7 @@ export function grid_data_range(grid) {
     if (!grid.length || !grid[0]?.length || !grid[0][0]?.length) {
         return { min: 0, max: 0, abs_max: 0, mean: 0 };
     }
-    let min_val = Infinity;
-    let max_val = -Infinity;
+    let [min_val, max_val] = [Infinity, -Infinity];
     let sum = 0;
     let count = 0;
     for (const plane of grid) {
@@ -34,6 +34,109 @@ export function grid_data_range(grid) {
     const abs_max = Math.max(Math.abs(min_val), Math.abs(max_val));
     return { min: min_val, max: max_val, abs_max, mean: count > 0 ? sum / count : 0 };
 }
+// Pad a periodic 3D grid with halo cells from the opposite face so isosurfaces
+// extend beyond the unit cell and close into complete enclosed shapes.
+// Returns a larger grid with dims [nx+2*pad, ny+2*pad, nz+2*pad] and the
+// fractional offset that the padded grid's origin has shifted by.
+export function pad_periodic_grid(grid, dims, pad_fraction) {
+    const [nx, ny, nz] = dims;
+    const frac = Math.max(0, pad_fraction);
+    const px = Math.min(Math.ceil(nx * frac), Math.floor(nx / 2));
+    const py = Math.min(Math.ceil(ny * frac), Math.floor(ny / 2));
+    const pz = Math.min(Math.ceil(nz * frac), Math.floor(nz / 2));
+    if (px === 0 && py === 0 && pz === 0)
+        return { grid, dims, offset: [0, 0, 0] };
+    const out_nx = nx + 2 * px;
+    const out_ny = ny + 2 * py;
+    const out_nz = nz + 2 * pz;
+    const wrap = (val, size) => ((val % size) + size) % size;
+    const out = new Array(out_nx);
+    for (let ix = 0; ix < out_nx; ix++) {
+        const plane = new Array(out_ny);
+        const src_x = wrap(ix - px, nx);
+        for (let iy = 0; iy < out_ny; iy++) {
+            const row = new Array(out_nz);
+            const src_y = wrap(iy - py, ny);
+            for (let iz = 0; iz < out_nz; iz++) {
+                row[iz] = grid[src_x][src_y][wrap(iz - pz, nz)];
+            }
+            plane[iy] = row;
+        }
+        out[ix] = plane;
+    }
+    // Fractional offset: the padded grid starts at -pad/n in each axis
+    const offset = [-px / nx, -py / ny, -pz / nz];
+    return { grid: out, dims: [out_nx, out_ny, out_nz], offset };
+}
+// Max total grid points before downsampling is applied for isosurface extraction.
+// 500K balances visual quality with interactive performance (<200ms marching cubes).
+const MAX_GRID_POINTS = 500_000;
+// Downsample a 3D volumetric grid to keep total point count under a budget.
+// Uses block averaging to preserve data fidelity while reducing grid dimensions.
+// Returns original grid/dims if already within budget.
+export function downsample_grid(grid, dims, max_points = MAX_GRID_POINTS) {
+    const [nx, ny, nz] = dims;
+    const total = nx * ny * nz;
+    if (total <= max_points)
+        return { grid, dims, factor: 1 };
+    // Floor at 1 to avoid Infinity in cbrt(total/0)
+    max_points = Math.max(1, max_points);
+    // Increase factor until the clamped output fits within budget.
+    // A single cbrt step can overshoot for anisotropic grids where max(2,...)
+    // clamping prevents a small axis from shrinking below 2.
+    // clamp_dim: returns 1 for single-cell axes, otherwise clamps to [2, src]
+    const clamp_dim = (src, fac) => Math.min(src, Math.max(2, Math.ceil(src / fac)));
+    let factor = Math.ceil(Math.cbrt(total / max_points));
+    let new_nx = clamp_dim(nx, factor);
+    let new_ny = clamp_dim(ny, factor);
+    let new_nz = clamp_dim(nz, factor);
+    while (new_nx * new_ny * new_nz > max_points) {
+        factor++;
+        const prev_total = new_nx * new_ny * new_nz;
+        new_nx = clamp_dim(nx, factor);
+        new_ny = clamp_dim(ny, factor);
+        new_nz = clamp_dim(nz, factor);
+        // dims hit their floor (2 per axis or 1 for single-cell) — stop to avoid infinite loop
+        if (new_nx * new_ny * new_nz === prev_total)
+            break;
+    }
+    // Proportional partitioning: evenly divides [0, n) into new_n non-empty blocks.
+    // Unlike fixed-stride (ix * factor), this is safe when max(2,...) clamping
+    // produces more output cells than ceil(n/factor) would — no empty blocks.
+    const partition = (n_out, n_src) => Array.from({ length: n_out }, (_, idx) => [
+        Math.round((idx * n_src) / n_out),
+        Math.round(((idx + 1) * n_src) / n_out),
+    ]);
+    const x_ranges = partition(new_nx, nx);
+    const y_ranges = partition(new_ny, ny);
+    const z_ranges = partition(new_nz, nz);
+    const out = new Array(new_nx);
+    for (let ix = 0; ix < new_nx; ix++) {
+        const plane = new Array(new_ny);
+        const [sx_start, sx_end] = x_ranges[ix];
+        for (let iy = 0; iy < new_ny; iy++) {
+            const row = new Array(new_nz);
+            const [sy_start, sy_end] = y_ranges[iy];
+            for (let iz = 0; iz < new_nz; iz++) {
+                let sum = 0;
+                const [sz_start, sz_end] = z_ranges[iz];
+                for (let sx = sx_start; sx < sx_end; sx++) {
+                    const src_plane = grid[sx];
+                    for (let sy = sy_start; sy < sy_end; sy++) {
+                        const src_row = src_plane[sy];
+                        for (let sz = sz_start; sz < sz_end; sz++) {
+                            sum += src_row[sz];
+                        }
+                    }
+                }
+                row[iz] = sum / ((sx_end - sx_start) * (sy_end - sy_start) * (sz_end - sz_start));
+            }
+            plane[iy] = row;
+        }
+        out[ix] = plane;
+    }
+    return { grid: out, dims: [new_nx, new_ny, new_nz], factor };
+}
 // Default isosurface rendering settings
 export const DEFAULT_ISOSURFACE_SETTINGS = {
     isovalue: 0.05,
@@ -42,6 +145,7 @@ export const DEFAULT_ISOSURFACE_SETTINGS = {
     negative_color: `#ef4444`, // red
     show_negative: false,
     wireframe: false,
+    halo: 0,
 };
 // Compute reasonable isosurface settings from a volume's data range.
 // Sets isovalue to 20% of abs_max and enables negative lobe when data has
@@ -51,9 +155,7 @@ export function auto_isosurface_settings(data_range) {
     return {
         ...DEFAULT_ISOSURFACE_SETTINGS,
         // Fall back to default isovalue for all-zero grids to keep controls usable
-        isovalue: data_range.abs_max > 0
-            ? data_range.abs_max * 0.2
-            : DEFAULT_ISOSURFACE_SETTINGS.isovalue,
+        isovalue: data_range.abs_max > 0 ? data_range.abs_max * 0.2 : DEFAULT_ISOSURFACE_SETTINGS.isovalue,
         show_negative: has_negatives,
     };
 }
@@ -78,3 +180,48 @@ export function generate_layers(data_range, n_layers) {
         };
     });
 }
+// Tile (repeat) volumetric data to fill a supercell.
+// Pre-downsamples the source grid when the tiled result would exceed MAX_GRID_POINTS
+// to avoid large temporary allocations. Returns the original volume unchanged for
+// [1,1,1] scaling.
+export function tile_volumetric_data(volume, scaling) {
+    const [sx, sy, sz] = scaling;
+    if (sx === 1 && sy === 1 && sz === 1)
+        return volume;
+    const total_cells = sx * sy * sz;
+    let src_grid = volume.grid;
+    let [nx, ny, nz] = volume.grid_dims;
+    // Pre-downsample source grid so the tiled result stays within budget.
+    // Clamp budget to 8 (minimum downsample output = 2^3) to prevent infinite
+    // loops in downsample_grid when total_cells is very large.
+    if (nx * ny * nz * total_cells > MAX_GRID_POINTS) {
+        const budget = Math.max(8, Math.floor(MAX_GRID_POINTS / total_cells));
+        const ds = downsample_grid(src_grid, [nx, ny, nz], budget);
+        src_grid = ds.grid;
+        [nx, ny, nz] = ds.dims;
+    }
+    const new_nx = nx * sx;
+    const new_ny = ny * sy;
+    const new_nz = nz * sz;
+    const new_grid = new Array(new_nx);
+    for (let ix = 0; ix < new_nx; ix++) {
+        const plane = new Array(new_ny);
+        const src_x = ix % nx;
+        for (let iy = 0; iy < new_ny; iy++) {
+            const row = new Array(new_nz);
+            const src_y = iy % ny;
+            const src_row = src_grid[src_x][src_y];
+            for (let iz = 0; iz < new_nz; iz++) {
+                row[iz] = src_row[iz % nz];
+            }
+            plane[iy] = row;
+        }
+        new_grid[ix] = plane;
+    }
+    return {
+        ...volume,
+        grid: new_grid,
+        grid_dims: [new_nx, new_ny, new_nz],
+        lattice: scale_lattice_matrix(volume.lattice, scaling),
+    };
+}

package/dist/labels.d.ts

@@ -1,4 +1,5 @@
 import type { ChemicalElement, ElementCategory } from './element/types';
+import type { Vec3 } from './math';
 import type { SymbolType } from 'd3-shape';
 import * as d3_symbols from 'd3-shape';
 export type D3Symbol = keyof typeof d3_symbols & `symbol${Capitalize<string>}`;
@@ -12,7 +13,7 @@ export declare const ELEM_HEATMAP_LABELS: Partial<Record<string, keyof ChemicalE
 export declare const DEFAULT_FMT: [string, string];
 export declare const FRACTION_GLYPHS: ReadonlyArray<readonly [number, string]>;
 export declare const format_num: (num: number, fmt?: string | number) => string;
-export declare const format_vec3: (vec: readonly [number, number, number], fmt_spec?: string) => string;
+export declare const format_vec3: (vec: Readonly<Vec3>, fmt_spec?: string) => string;
 export declare const format_bytes: (bytes?: number) => string;
 export declare function format_fractional(value: number): string;
 export declare function parse_si_float<T extends string | number | null | undefined>(value: T): T | number | string;

package/dist/labels.js

@@ -10,9 +10,13 @@ function name_for_symbol(sym) {
     }
     return null;
 }
-export const symbol_names = ([...new Set([...d3_symbols.symbolsFill, ...d3_symbols.symbolsStroke])]
-    .map(name_for_symbol).filter((n) => n !== null));
-export const symbol_map = Object.fromEntries(// Symbol lookup from d3-shape
+export const symbol_names = [
+    ...new Set([...d3_symbols.symbolsFill, ...d3_symbols.symbolsStroke]),
+]
+    .map(name_for_symbol)
+    .filter((n) => n !== null);
+export const symbol_map = Object.fromEntries(
+// Symbol lookup from d3-shape
 symbol_names.map((name) => [name, d3_symbols[`symbol${name}`]]));
 // Format a value for display with optional time formatting
 export function format_value(value, formatter) {
@@ -56,6 +60,7 @@ export const ELEM_PROPERTY_LABELS = {
     electronegativity: [`Electronegativity`, null],
     first_ionization: [`First Ionization Energy`, `eV`],
     melting_point: [`Melting Point`, `K`],
+    mendeleev_number: [`Mendeleev Number`, null],
     // molar_heat: [`Molar Heat`, `J/(mol·K)`],
     n_shells: [`Number of Shells`, null],
     n_valence: [`Electron Valency`, null],
@@ -73,8 +78,7 @@ export const ELEM_HEATMAP_KEYS = [
     `melting_point`,
     `first_ionization`,
 ];
-export const ELEM_HEATMAP_LABELS = Object
-    .fromEntries(ELEM_HEATMAP_KEYS.map((key) => {
+export const ELEM_HEATMAP_LABELS = Object.fromEntries(ELEM_HEATMAP_KEYS.map((key) => {
     const [label, unit] = ELEM_PROPERTY_LABELS[key] ?? [];
     if (!label)
         throw `Unexpected missing label ${label}`;
@@ -141,7 +145,7 @@ export function format_fractional(value) {
             return glyph;
     }
     for (const [target, glyph] of FRACTION_GLYPHS) {
-        if (target !== 0 && Math.abs((1 - x) - target) < eps)
+        if (target !== 0 && Math.abs(1 - x - target) < eps)
             return glyph;
     }
     return format_num(value, `.4~`);
@@ -153,7 +157,7 @@ export function parse_si_float(value) {
     // Remove whitespace and commas
     const cleaned = value.trim().replace(/(\d),(\d)/g, `$1$2`);
     // Check if the value is a SI-formatted number (e.g. "1.23k", "4.56M", "789µ", "12n")
-    const match = cleaned.match(/^([-+]?\d*\.?\d+)\s*([yzafpnµmkMGTPEZY])?$/i);
+    const match = /^([-+]?\d*\.?\d+)\s*([yzafpnµmkMGTPEZY])?$/i.exec(cleaned);
     if (match) {
         const [, num_part, suffix] = match;
         let multiplier = 1;
@@ -196,7 +200,7 @@ export const ELEMENT_CATEGORIES = [
     `post-transition metal`,
     `transition metal`,
 ];
-// deno-fmt-ignore-next-line
+// oxfmt-ignore
 export const ELEM_SYMBOLS = [`H`, `He`, `Li`, `Be`, `B`, `C`, `N`, `O`, `F`, `Ne`, `Na`, `Mg`, `Al`, `Si`, `P`, `S`, `Cl`, `Ar`, `K`, `Ca`, `Sc`, `Ti`, `V`, `Cr`, `Mn`, `Fe`, `Co`, `Ni`, `Cu`, `Zn`, `Ga`, `Ge`, `As`, `Se`, `Br`, `Kr`, `Rb`, `Sr`, `Y`, `Zr`, `Nb`, `Mo`, `Tc`, `Ru`, `Rh`, `Pd`, `Ag`, `Cd`, `In`, `Sn`, `Sb`, `Te`, `I`, `Xe`, `Cs`, `Ba`, `La`, `Ce`, `Pr`, `Nd`, `Pm`, `Sm`, `Eu`, `Gd`, `Tb`, `Dy`, `Ho`, `Er`, `Tm`, `Yb`, `Lu`, `Hf`, `Ta`, `W`, `Re`, `Os`, `Ir`, `Pt`, `Au`, `Hg`, `Tl`, `Pb`, `Bi`, `Po`, `At`, `Rn`, `Fr`, `Ra`, `Ac`, `Th`, `Pa`, `U`, `Np`, `Pu`, `Am`, `Cm`, `Bk`, `Cf`, `Es`, `Fm`, `Md`, `No`, `Lr`, `Rf`, `Db`, `Sg`, `Bh`, `Hs`, `Mt`, `Ds`, `Rg`, `Cn`, `Nh`, `Fl`, `Mc`, `Lv`, `Ts`, `Og`];
 export const SUPERSCRIPT_MAP = {
     '0': `⁰`,

package/dist/layout/FullscreenToggle.svelte

@@ -1,5 +1,14 @@
-<script lang="ts">import Icon from '../Icon.svelte';
-let { fullscreen = $bindable(false), class: className, ...rest } = $props();
+<script lang="ts">
+  import Icon from '../Icon.svelte'
+  import type { HTMLButtonAttributes } from 'svelte/elements'
+
+  let {
+    fullscreen = $bindable(false),
+    class: className,
+    ...rest
+  }: HTMLButtonAttributes & {
+    fullscreen?: boolean
+  } = $props()
 </script>
 
 <button