matterviz 0.1.0

package/dist/labels.d.ts

@@ -0,0 +1,31 @@
+import type { Category, ChemicalElement } from './';
+export declare const property_labels: Partial<Record<keyof ChemicalElement, [string, string | null]>>;
+export declare const heatmap_keys: (keyof ChemicalElement)[];
+export declare const heatmap_labels: Partial<Record<string, keyof ChemicalElement>>;
+export declare const default_fmt: [string, string];
+export declare const format_num: (num: number, fmt?: string | number) => string;
+export declare function parse_si_float<T extends string | number | null | undefined>(value: T): T | number | string;
+export declare const category_counts: Record<Category, number>;
+export declare const categories: readonly ["actinide", "alkali metal", "alkaline earth metal", "diatomic nonmetal", "lanthanide", "metalloid", "noble gas", "polyatomic nonmetal", "post-transition metal", "transition metal"];
+export declare const elem_symbols: readonly ["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 declare function luminance(clr: string): number;
+export declare function get_bg_color(elem: HTMLElement | null, bg_color?: string | null): string;
+export declare function choose_bw_for_contrast(node: HTMLElement | null, bg_color?: string | null, text_color_threshold?: number): "white" | "black";
+export declare const superscript_map: {
+    readonly '0': "⁰";
+    readonly '1': "¹";
+    readonly '2': "²";
+    readonly '3': "³";
+    readonly '4': "⁴";
+    readonly '5': "⁵";
+    readonly '6': "⁶";
+    readonly '7': "⁷";
+    readonly '8': "⁸";
+    readonly '9': "⁹";
+    readonly '+': "⁺";
+    readonly '-': "⁻";
+};
+export declare function superscript_digits(input: string): string;
+export declare const trajectory_labels: Record<string, string>;
+export declare function get_clean_label(key: string, property_labels?: Record<string, string>): string;
+export declare function get_label_with_unit(key: string, property_labels?: Record<string, string>, units?: Record<string, string>): string;

package/dist/labels.js

@@ -0,0 +1,209 @@
+import { rgb } from 'd3-color';
+import { format } from 'd3-format';
+// TODO add labels and units for all elemental properties
+export const property_labels = {
+    atomic_mass: [`Atomic Mass`, `u`],
+    atomic_radius: [`Atomic Radius`, `Å`],
+    boiling_point: [`Boiling Point`, `K`],
+    covalent_radius: [`Covalent Radius`, `Å`],
+    density: [`Density`, `g/cm³`],
+    electron_affinity: [`Electron Affinity`, null],
+    electronegativity: [`Electronegativity`, null],
+    first_ionization: [`First Ionization Energy`, `eV`],
+    melting_point: [`Melting Point`, `K`],
+    // molar_heat: [`Molar Heat`, `J/(mol·K)`],
+    n_shells: [`Number of Shells`, null],
+    n_valence: [`Electron Valency`, null],
+    number: [`Atomic Number`, null],
+    shells: [`Electron Shell Occupations`, null],
+    specific_heat: [`Specific Heat`, `J/(g K)`],
+};
+export const heatmap_keys = [
+    `atomic_mass`,
+    `atomic_radius`,
+    `covalent_radius`,
+    `electronegativity`,
+    `density`,
+    `boiling_point`,
+    `melting_point`,
+    `first_ionization`,
+];
+export const heatmap_labels = Object
+    .fromEntries(heatmap_keys.map((key) => {
+    const [label, unit] = property_labels[key] ?? [];
+    if (!label)
+        throw `Unexpected missing label ${label}`;
+    return [label + (unit ? ` (${unit})` : ``), key];
+}));
+// allow users to import default_fmt and change it's items in place to
+// set default number format globally
+export const default_fmt = [`,.3~s`, `.3~g`];
+// fmt as number only allowed to support [].map(format_num) without type error
+export const format_num = (num, fmt) => {
+    if (num === null)
+        return ``;
+    if (!fmt || typeof fmt !== `string`) {
+        const [gt_1_fmt, lt_1_fmt] = default_fmt;
+        return format(Math.abs(num) >= 1 ? gt_1_fmt : lt_1_fmt)(num);
+    }
+    return format(fmt)(num);
+};
+export function parse_si_float(value) {
+    // if not string, return as is
+    if (typeof value !== `string`)
+        return 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);
+    if (match) {
+        const [, num_part, suffix] = match;
+        let multiplier = 1;
+        if (suffix) {
+            const suffixes = `yzafpnµm kMGTPEZY`;
+            const index = suffixes.indexOf(suffix);
+            if (index !== -1) {
+                multiplier = Math.pow(1000, index - 8);
+            }
+        }
+        return parseFloat(num_part) * multiplier;
+    }
+    // If it's a number without SI suffix, try parsing it
+    if (/^[-+]?[\d,]+\.?\d*$/.test(cleaned))
+        return parseFloat(cleaned);
+    // If the value is not a formatted number, return as is
+    return value;
+}
+export const category_counts = {
+    actinide: 15,
+    'alkali metal': 6,
+    'alkaline earth metal': 6,
+    'diatomic nonmetal': 7,
+    lanthanide: 15,
+    metalloid: 8,
+    'noble gas': 7,
+    'polyatomic nonmetal': 4,
+    'post-transition metal': 12,
+    'transition metal': 38,
+};
+export const categories = [
+    `actinide`,
+    `alkali metal`,
+    `alkaline earth metal`,
+    `diatomic nonmetal`,
+    `lanthanide`,
+    `metalloid`,
+    `noble gas`,
+    `polyatomic nonmetal`,
+    `post-transition metal`,
+    `transition metal`,
+];
+// deno-fmt-ignore-next-line
+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`];
+// calculate human-perceived brightness from RGB color
+export function luminance(clr) {
+    const { r, g, b } = rgb(clr);
+    // if (![r, g, b].every((c) => c >= 0 && c <= 255)) {
+    //   console.error(`invalid RGB color: ${clr}, parsed to rgb=${r},${g},${b}`)
+    // }
+    return (0.299 * r + 0.587 * g + 0.114 * b) / 255; // https://stackoverflow.com/a/596243
+}
+// get background color of passed DOM node, or recurse up the DOM tree if current node is transparent
+export function get_bg_color(elem, bg_color = null) {
+    if (bg_color)
+        return bg_color;
+    // recurse up the DOM tree to find the first non-transparent background color
+    const transparent = `rgba(0, 0, 0, 0)`;
+    if (!elem)
+        return transparent; // if no DOM node, return transparent
+    const bg = getComputedStyle(elem).backgroundColor; // get node background color
+    if (bg !== transparent)
+        return bg; // if not transparent, return it
+    return get_bg_color(elem.parentElement); // otherwise recurse up the DOM tree
+}
+// pick black or white text color to maximize contrast with background
+export function choose_bw_for_contrast(node, 
+// you can explicitly pass bg_color to avoid DOM recursion and in case get_bg_color() fails
+bg_color = null, text_color_threshold = 0.7) {
+    const light_bg = luminance(get_bg_color(node, bg_color)) > text_color_threshold;
+    return light_bg ? `black` : `white`; // white text for dark backgrounds, black for light
+}
+export const superscript_map = {
+    '0': `⁰`,
+    '1': `¹`,
+    '2': `²`,
+    '3': `³`,
+    '4': `⁴`,
+    '5': `⁵`,
+    '6': `⁶`,
+    '7': `⁷`,
+    '8': `⁸`,
+    '9': `⁹`,
+    '+': `⁺`,
+    '-': `⁻`,
+};
+export function superscript_digits(input) {
+    // use replace all signs and digits with their unicode superscript equivalent
+    return input.replace(/[\d+-]/g, (match) => superscript_map[match] ?? match);
+}
+// Trajectory property labels: controls how properties are displayed in trajectory plots
+export const trajectory_labels = {
+    // Energy properties
+    energy: `Energy (eV)`,
+    energy_per_atom: `Energy per atom (eV/atom)`,
+    potential_energy: `Potential energy (eV)`,
+    kinetic_energy: `Kinetic energy (eV)`,
+    total_energy: `Total energy (eV)`,
+    // Force properties
+    force_max: `F<sub>max</sub> (eV/Å)`,
+    force_norm: `F<sub>norm</sub> (eV/Å)`,
+    'Force Max': `Force Max (eV/Å)`,
+    'Force RMS': `Force RMS (eV/Å)`,
+    // Structural properties
+    volume: `Volume (ų)`,
+    Volume: `Cell Volume (ų)`,
+    density: `Density (g/cm³)`,
+    // Thermodynamic properties
+    temperature: `Temperature (K)`,
+    pressure: `Pressure (GPa)`,
+    stress_max: `σ<sub>max</sub> (GPa)`,
+    stress_frobenius: `σ<sub>F</sub> (GPa)`,
+};
+// Helper function to get clean label without units
+export function get_clean_label(key, property_labels) {
+    // First check if we have an explicit label mapping
+    if (property_labels?.[key]) {
+        // Remove any existing unit notation from the label
+        return property_labels[key].replace(/\s*\([^)]*\)\s*$/, ``);
+    }
+    const lower_key = key.toLowerCase();
+    // Special formatting for force properties
+    if (lower_key === `force_max` || key === `Force Max`) {
+        return `F<sub>max</sub>`;
+    }
+    if (lower_key === `force_norm` || key === `Force RMS`) {
+        return `F<sub>norm</sub>`;
+    }
+    if (lower_key === `stress_max`) {
+        return `σ<sub>max</sub>`;
+    }
+    if (lower_key === `stress_frobenius`) {
+        return `σ<sub>F</sub>`;
+    }
+    if (lower_key === `temperature`) {
+        return `Temperature`;
+    }
+    // Capitalize the key name for all other properties
+    return key.charAt(0).toUpperCase() + key.slice(1);
+}
+// Helper function to get property label with unit for trajectory plotting
+export function get_label_with_unit(key, property_labels, units) {
+    // First check if we have an explicit label mapping
+    if (property_labels?.[key])
+        return property_labels[key];
+    // Get clean label and add unit if available
+    const clean_label = get_clean_label(key, property_labels);
+    const lower_key = key.toLowerCase();
+    const unit = units?.[lower_key] || units?.[key] || ``;
+    return unit ? `${clean_label} (${unit})` : clean_label;
+}

package/dist/material/MaterialCard.svelte

@@ -0,0 +1,135 @@
+<script lang="ts">import { format_num, InfoCard, superscript_digits } from '..';
+import SymmetryCard from './SymmetryCard.svelte';
+let { material, after_symmetry, ...rest } = $props();
+let data = $derived([
+    {
+        title: `Band Gap`,
+        value: material.band_gap,
+        unit: `eV`,
+        tooltip: material.vbm && material.cbm
+            ? `VBM: ${material.vbm}, CBM: ${material.cbm}`
+            : ``,
+    },
+    {
+        title: `Space Group`,
+        value: `${material.symmetry?.number}`,
+        unit: `(${material.symmetry?.symbol})`,
+        condition: material.symmetry?.number,
+    },
+    {
+        title: `E<sub>above hull</sub>`,
+        value: 1000 * (material?.energy_above_hull ?? 0),
+        unit: `meV/atom`,
+        condition: `energy_above_hull` in material,
+    },
+    {
+        title: `Predicted stable`,
+        value: (material?.energy_above_hull ?? 0 > 0) ? `❌ No` : `✅ Yes`,
+        condition: `energy_above_hull` in material,
+    },
+    {
+        title: `Formation Energy`,
+        value: material.formation_energy_per_atom,
+        unit: `eV/atom`,
+    },
+    {
+        title: `Experimentally Observed`,
+        value: material.theoretical ? `❌ No` : `✅ Yes`,
+    },
+    { title: `Total Energy`, value: material.energy_per_atom, unit: `eV/atom` },
+    {
+        title: `Uncorrected Energy`,
+        value: material.uncorrected_energy_per_atom,
+        unit: `eV/atom`,
+        condition: material.uncorrected_energy_per_atom != material.energy_per_atom,
+    },
+    {
+        title: `Last updated`,
+        value: material.last_updated?.$date.split(`T`)[0],
+    },
+    {
+        title: `Origins`,
+        value: material.origins,
+        condition: material.origins?.length,
+    },
+    {
+        title: `Voigt bulk modulus`,
+        value: material.k_voigt,
+        unit: `GPa`,
+    },
+    {
+        title: `Voig shear modulus`,
+        value: material.g_voigt,
+        unit: `GPa`,
+    },
+    { title: `Refractive index`, value: material.n },
+    {
+        title: `Is magnetic`,
+        value: `${material.is_magnetic ? `yes` : `no`} ${material.is_magnetic
+            ? `(${format_num(material.total_magnetization)} µB/f.u.)`
+            : ``}`,
+        tooltip: `µB: Bohr magneton, f.u.: formula unit`,
+    },
+    {
+        title: `Ordering`,
+        value: {
+            NM: `non-magnetic`,
+            FM: `ferromagnetic`,
+            FiM: `ferrimagnetic`,
+            AFM: `antiferromagnetic`,
+        }[material.ordering] ?? `unknown`,
+    },
+    {
+        title: `Possible oxidation states`,
+        value: superscript_digits(material.possible_species?.join(` `) ?? ``),
+        condition: material.possible_species?.length,
+    },
+]);
+</script>
+
+<InfoCard {data} {...rest} title="Material" />
+
+<SymmetryCard {material} />
+
+{@render after_symmetry?.()}
+
+<details>
+  <summary>Related material IDs</summary>
+  {#if material.task_ids?.length}
+    <p>
+      Task IDs: {#each material.task_ids as id (id)}
+        <a href="https://materialsproject.org/tasks/{id}">{id}</a>
+      {/each}
+    </p>
+  {/if}
+  {#if material.database_IDs?.icsd?.length}
+    <p>
+      ICSD IDs: {#each material.database_IDs.icsd as id (id)}
+        {@const href =
+        `https://ccdc.cam.ac.uk/structures/Search?Ccdcid=${id}&DatabaseToSearch=ICSD`}
+        <a {href}>{id}</a>
+      {/each}
+    </p>
+  {/if}
+</details>
+
+<p class="warning">
+  {material.warnings}
+</p>
+
+<style>
+  .warning {
+    color: var(--warning-color, darkred);
+  }
+  p {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1ex 1em;
+    font-size: smaller;
+  }
+  p a {
+    background-color: rgba(255, 255, 255, 0.1);
+    padding: 0 3pt;
+    border-radius: 3pt;
+  }
+</style>

package/dist/material/MaterialCard.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { SummaryDoc } from '../../types';
+import type { Snippet } from 'svelte';
+interface Props {
+    material: SummaryDoc;
+    after_symmetry?: Snippet;
+    [key: string]: unknown;
+}
+declare const MaterialCard: import("svelte").Component<Props, {}, "">;
+type MaterialCard = ReturnType<typeof MaterialCard>;
+export default MaterialCard;

package/dist/material/SymmetryCard.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">import { InfoCard } from '..';
+let { title = `Symmetry`, material, ...rest } = $props();
+let data = $derived([
+    {
+        title: `Crystal System`,
+        value: `${material.symmetry?.crystal_system}`,
+    },
+    {
+        title: `International Number`,
+        value: material.symmetry?.number,
+    },
+    {
+        title: `Point Group`,
+        value: `${material.symmetry?.point_group}`,
+    },
+    {
+        title: `Symbol`,
+        value: `${material.symmetry?.symbol}`,
+    },
+]);
+</script>
+
+<InfoCard {data} {...rest} {title} />

package/dist/material/SymmetryCard.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { SummaryDoc } from '../../types';
+interface Props {
+    title?: string;
+    material: SummaryDoc;
+    [key: string]: unknown;
+}
+declare const SymmetryCard: import("svelte").Component<Props, {}, "">;
+type SymmetryCard = ReturnType<typeof SymmetryCard>;
+export default SymmetryCard;

package/dist/material/index.d.ts

@@ -0,0 +1,2 @@
+export { default as MaterialCard } from './MaterialCard.svelte';
+export { default as SymmetryCard } from './SymmetryCard.svelte';

package/dist/material/index.js

@@ -0,0 +1,2 @@
+export { default as MaterialCard } from './MaterialCard.svelte';
+export { default as SymmetryCard } from './SymmetryCard.svelte';

package/dist/math.d.ts

@@ -0,0 +1,24 @@
+import type { LatticeParams } from './structure/index';
+export type Vec3 = [number, number, number];
+export type Matrix3x3 = [Vec3, Vec3, Vec3];
+export type NdVector = number[];
+export declare function calc_lattice_params(matrix: Matrix3x3): LatticeParams & {
+    volume: number;
+};
+export declare function norm(vec: NdVector): number;
+export declare function scale(vec: NdVector, factor: number): NdVector;
+export declare function euclidean_dist(vec1: Vec3, vec2: Vec3): number;
+export declare function pbc_dist(pos1: Vec3, // First position vector (Cartesian coordinates)
+pos2: Vec3, // Second position vector (Cartesian coordinates)
+lattice_matrix: Matrix3x3, // 3x3 lattice matrix where each row is a lattice vector
+lattice_inv?: Matrix3x3): number;
+export declare function matrix_inverse_3x3(matrix: Matrix3x3): Matrix3x3;
+export declare function mat3x3_vec3_multiply(matrix: Matrix3x3, vector: Vec3): Vec3;
+export declare function add(...vecs: NdVector[]): NdVector;
+export declare function dot(vec1: NdVector, vec2: NdVector): number | number[] | number[][];
+export declare function to_voigt(tensor: number[][]): number[];
+export declare function from_voigt(voigt: number[]): number[][];
+export declare function vec9_to_mat3x3(flat_array: number[]): number[][];
+export declare function tensor_to_flat_array(tensor: number[][]): number[];
+export declare const transpose_matrix: (matrix: Matrix3x3) => Matrix3x3;
+export declare function cell_to_lattice_matrix(a: number, b: number, c: number, alpha: number, beta: number, gamma: number): Matrix3x3;

package/dist/math.js

@@ -0,0 +1,216 @@
+// Calculate all lattice parameters in a single efficient pass
+export function calc_lattice_params(matrix) {
+    const [a_vec, b_vec, c_vec] = matrix;
+    // Calculate vector lengths (lattice parameters a, b, c)
+    const a = Math.sqrt(a_vec[0] ** 2 + a_vec[1] ** 2 + a_vec[2] ** 2);
+    const b = Math.sqrt(b_vec[0] ** 2 + b_vec[1] ** 2 + b_vec[2] ** 2);
+    const c = Math.sqrt(c_vec[0] ** 2 + c_vec[1] ** 2 + c_vec[2] ** 2);
+    // Calculate volume using scalar triple product
+    const volume = Math.abs(a_vec[0] * (b_vec[1] * c_vec[2] - b_vec[2] * c_vec[1]) +
+        a_vec[1] * (b_vec[2] * c_vec[0] - b_vec[0] * c_vec[2]) +
+        a_vec[2] * (b_vec[0] * c_vec[1] - b_vec[1] * c_vec[0]));
+    // Calculate dot products for angles (only once each)
+    const dot_ab = a_vec[0] * b_vec[0] + a_vec[1] * b_vec[1] + a_vec[2] * b_vec[2];
+    const dot_ac = a_vec[0] * c_vec[0] + a_vec[1] * c_vec[1] + a_vec[2] * c_vec[2];
+    const dot_bc = b_vec[0] * c_vec[0] + b_vec[1] * c_vec[1] + b_vec[2] * c_vec[2];
+    // Convert to angles in degrees
+    const rad_to_deg = 180 / Math.PI;
+    const alpha = Math.acos(dot_bc / (b * c)) * rad_to_deg;
+    const beta = Math.acos(dot_ac / (a * c)) * rad_to_deg;
+    const gamma = Math.acos(dot_ab / (a * b)) * rad_to_deg;
+    return { a, b, c, alpha, beta, gamma, volume };
+}
+export function norm(vec) {
+    return Math.sqrt(vec.reduce((acc, val) => acc + val ** 2, 0));
+}
+export function scale(vec, factor) {
+    return vec.map((component) => component * factor);
+}
+export function euclidean_dist(vec1, vec2) {
+    return norm(add(vec1, scale(vec2, -1)));
+}
+// Calculate the minimum distance between two points considering periodic boundary conditions.
+export function pbc_dist(pos1, // First position vector (Cartesian coordinates)
+pos2, // Second position vector (Cartesian coordinates)
+lattice_matrix, // 3x3 lattice matrix where each row is a lattice vector
+lattice_inv) {
+    // Use provided inverse or compute it
+    const inv_matrix = lattice_inv ?? matrix_inverse_3x3(lattice_matrix);
+    // Convert Cartesian coordinates to fractional coordinates
+    const frac1 = mat3x3_vec3_multiply(inv_matrix, pos1);
+    const frac2 = mat3x3_vec3_multiply(inv_matrix, pos2);
+    // Calculate fractional distance vector
+    const frac_diff = add(frac1, scale(frac2, -1));
+    // Apply minimum image convention: wrap to [-0.5, 0.5)
+    const wrapped_frac_diff = frac_diff.map((x) => {
+        // Wrap to [0, 1) first, then shift to [-0.5, 0.5)
+        let wrapped = x - Math.floor(x);
+        if (wrapped >= 0.5)
+            wrapped -= 1;
+        return wrapped;
+    });
+    // Convert back to Cartesian coordinates
+    const cart_diff = mat3x3_vec3_multiply(lattice_matrix, wrapped_frac_diff);
+    return norm(cart_diff);
+}
+export function matrix_inverse_3x3(matrix) {
+    /** Calculate the inverse of a 3x3 matrix */
+    const [[a, b, c], [d, e, f], [g, h, i]] = matrix;
+    const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
+    if (Math.abs(det) < 1e-10) {
+        throw `Matrix is singular and cannot be inverted`;
+    }
+    const inv_det = 1 / det;
+    return [
+        [
+            (e * i - f * h) * inv_det,
+            (c * h - b * i) * inv_det,
+            (b * f - c * e) * inv_det,
+        ],
+        [
+            (f * g - d * i) * inv_det,
+            (a * i - c * g) * inv_det,
+            (c * d - a * f) * inv_det,
+        ],
+        [
+            (d * h - e * g) * inv_det,
+            (b * g - a * h) * inv_det,
+            (a * e - b * d) * inv_det,
+        ],
+    ];
+}
+// Multiply a 3x3 matrix by a 3D vector
+export function mat3x3_vec3_multiply(matrix, vector) {
+    const [a, b, c] = matrix;
+    const [x, y, z] = vector;
+    return [
+        a[0] * x + a[1] * y + a[2] * z,
+        b[0] * x + b[1] * y + b[2] * z,
+        c[0] * x + c[1] * y + c[2] * z,
+    ];
+}
+export function add(...vecs) {
+    // add up any number of same-length vectors
+    if (vecs.length === 0)
+        return [];
+    const first_vec = vecs[0];
+    const length = first_vec.length;
+    // Validate all vectors have the same length
+    for (const vec of vecs) {
+        if (vec.length !== length) {
+            throw `All vectors must have the same length`;
+        }
+    }
+    const result = new Array(length).fill(0);
+    for (const vec of vecs) {
+        for (let idx = 0; idx < length; idx++) {
+            result[idx] += vec[idx];
+        }
+    }
+    return result;
+}
+export function dot(vec1, vec2) {
+    // Handle the case where both inputs are scalars
+    if (typeof vec1 === `number` && typeof vec2 === `number`) {
+        return vec1 * vec2;
+    }
+    // Handle the case where one input is a scalar and the other is a vector
+    if (typeof vec1 === `number` && Array.isArray(vec2)) {
+        throw `Scalar and vector multiplication is not supported`;
+    }
+    if (Array.isArray(vec1) && typeof vec2 === `number`) {
+        throw `vector and scalar multiplication is not supported`;
+    }
+    // Handle the case where both inputs are vectors
+    if (!Array.isArray(vec1[0]) && !Array.isArray(vec2[0])) {
+        if (vec1.length !== vec2.length) {
+            throw `Vectors must be of same length`;
+        }
+        return vec1.reduce((sum, val, index) => sum + val * vec2[index], 0);
+    }
+    // Handle the case where the first input is a matrix and the second is a vector
+    if (Array.isArray(vec1[0]) && !Array.isArray(vec2[0])) {
+        const mat1 = vec1;
+        if (mat1[0].length !== vec2.length) {
+            throw `Number of columns in matrix must be equal to number of elements in vector`;
+        }
+        return mat1.map((row) => row.reduce((sum, val, index) => sum + val * vec2[index], 0));
+    }
+    // Handle the case where both inputs are matrices
+    if (Array.isArray(vec1[0]) && Array.isArray(vec2[0])) {
+        const mat1 = vec1;
+        const mat2 = vec2;
+        if (mat1[0].length !== mat2.length) {
+            throw `Number of columns in first matrix must be equal to number of rows in second matrix`;
+        }
+        return mat1.map((row, i) => mat2[0].map((_, j) => row.reduce((sum, _, k) => sum + mat1[i][k] * mat2[k][j], 0)));
+    }
+    // Handle any other cases
+    throw `Unsupported input dimensions. Inputs must be scalars, vectors, or matrices.`;
+}
+// Conversion utilities for vectors and tensors below
+// Convert 3x3 symmetric tensor to 6-element Voigt notation vector
+// Voigt notation maps: (1,1)->1, (2,2)->2, (3,3)->3, (2,3)->4, (1,3)->5, (1,2)->6
+export function to_voigt(tensor) {
+    if (tensor.length !== 3 || !tensor.every((row) => row.length === 3)) {
+        throw new Error(`Expected 3x3 tensor, got ${tensor.length}x${tensor[0]?.length ?? `n/a`}`);
+    }
+    const [t11, t12, t13, _t21, t22, t23, _t31, _t32, t33] = tensor.flat();
+    return [t11, t22, t33, t23, t13, t12];
+}
+// Convert 6-element Voigt notation vector to 3x3 symmetric tensor
+export function from_voigt(voigt) {
+    if (voigt.length !== 6) {
+        throw new Error(`Expected 6-element Voigt vector, got ${voigt.length} elements`);
+    }
+    const [v1, v2, v3, v4, v5, v6] = voigt;
+    return [[v1, v6, v5], [v6, v2, v4], [v5, v4, v3]];
+}
+// Convert flat 9-element array to 3x3 tensor (row-major order)
+export function vec9_to_mat3x3(flat_array) {
+    if (flat_array.length !== 9) {
+        throw new Error(`Expected 9-element array, got ${flat_array.length} elements`);
+    }
+    const [a1, a2, a3, a4, a5, a6, a7, a8, a9] = flat_array;
+    return [[a1, a2, a3], [a4, a5, a6], [a7, a8, a9]];
+}
+// Convert 3x3 tensor to flat 9-element array (row-major order)
+export function tensor_to_flat_array(tensor) {
+    if (tensor.length !== 3 || !tensor.every((row) => row.length === 3)) {
+        throw new Error(`Expected 3x3 tensor, got ${tensor.length}x${tensor[0]?.length ?? `n/a`}`);
+    }
+    const [t11, t12, t13, t21, t22, t23, t31, t32, t33] = tensor.flat();
+    return [t11, t12, t13, t21, t22, t23, t31, t32, t33];
+}
+// Transpose a 3x3 matrix
+export const transpose_matrix = (matrix) => [
+    [matrix[0][0], matrix[1][0], matrix[2][0]],
+    [matrix[0][1], matrix[1][1], matrix[2][1]],
+    [matrix[0][2], matrix[1][2], matrix[2][2]],
+];
+// Convert unit cell parameters to lattice matrix (crystallographic convention)
+export function cell_to_lattice_matrix(a, b, c, alpha, beta, gamma) {
+    // Convert angles to radians
+    const alpha_rad = (alpha * Math.PI) / 180;
+    const beta_rad = (beta * Math.PI) / 180;
+    const gamma_rad = (gamma * Math.PI) / 180;
+    const cos_alpha = Math.cos(alpha_rad);
+    const cos_beta = Math.cos(beta_rad);
+    const cos_gamma = Math.cos(gamma_rad);
+    const sin_gamma = Math.sin(gamma_rad);
+    // Calculate volume factor for triclinic system
+    const vol_factor = Math.sqrt(1 -
+        cos_alpha ** 2 -
+        cos_beta ** 2 -
+        cos_gamma ** 2 +
+        2 * cos_alpha * cos_beta * cos_gamma);
+    // Standard crystallographic lattice vectors
+    const c1 = c * cos_beta;
+    const c2 = (c * (cos_alpha - cos_beta * cos_gamma)) / sin_gamma;
+    const c3 = (c * vol_factor) / sin_gamma;
+    return [
+        [a, 0, 0],
+        [b * cos_gamma, b * sin_gamma, 0],
+        [c1, c2, c3],
+    ];
+}