matterviz 0.3.6 → 0.4.0

package/dist/chempot-diagram/compute.js

@@ -0,0 +1,804 @@
+// Core computational logic for chemical potential diagrams.
+// Ports pymatgen's ChemicalPotentialDiagram algorithm to TypeScript.
+// Reference: pymatgen/analysis/chempot_diagram.py
+import { convex_hull_2d, EPS, polygon_centroid, solve_linear_system } from '../math';
+import { CHEMPOT_DEFAULTS } from './types';
+// Inlined from $lib/composition/parse to keep this module worker-safe
+// ($lib/composition barrel transitively imports binary .json.gz data
+// that the worker bundler can't handle).
+const count_atoms_in_composition = (composition) => Object.values(composition).reduce((sum, count) => sum + (count ?? 0), 0);
+const gcd = (num_a, num_b) => num_b === 0 ? num_a : gcd(num_b, num_a % num_b);
+const get_reduced_formula = (composition) => {
+    const amounts = Object.values(composition).filter((amt) => amt > 0);
+    if (amounts.length === 0)
+        return {};
+    let scale = 1;
+    if (!amounts.every((amt) => Number.isInteger(amt))) {
+        scale = 0;
+        for (let mult = 1; mult <= 100; mult++) {
+            if (amounts.every((amt) => Math.abs(amt * mult - Math.round(amt * mult)) < 0.03)) {
+                scale = mult;
+                break;
+            }
+        }
+        if (scale === 0)
+            return composition;
+    }
+    const int_amounts = amounts.map((amt) => Math.round(amt * scale));
+    const divisor = int_amounts.reduce((acc, amt) => gcd(acc, amt));
+    if (scale === 1 && divisor <= 1)
+        return composition;
+    const factor = scale / divisor;
+    return Object.fromEntries(Object.entries(composition)
+        .filter(([, amt]) => amt > 0)
+        .map(([elem, amt]) => [elem, Math.round(amt * factor)]));
+};
+// === Entry Helpers ===
+// Get energy per atom for a PhaseData entry
+export function get_energy_per_atom(entry) {
+    if (typeof entry.energy_per_atom === `number`)
+        return entry.energy_per_atom;
+    const atoms = count_atoms_in_composition(entry.composition);
+    if (atoms <= 0) {
+        throw new Error(`Invalid composition with non-positive atom count: ${JSON.stringify(entry.composition)}`);
+    }
+    return entry.energy / atoms;
+}
+// Cache for reduced formula strings -- avoids recomputing get_reduced_formula
+// in hot loops. Key is object identity (WeakMap), value is the formula string.
+const formula_cache = new WeakMap();
+// Get a stable reduced formula string from composition dict (cached)
+export function formula_key_from_composition(composition) {
+    const cached = formula_cache.get(composition);
+    if (cached)
+        return cached;
+    const reduced = get_reduced_formula(composition);
+    const key = Object.entries(reduced)
+        .filter(([, amt]) => amt > 0)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([el, amt]) => (amt === 1 ? el : `${el}${amt}`))
+        .join(``);
+    formula_cache.set(composition, key);
+    return key;
+}
+// === Core Algorithm ===
+// Group entries by reduced formula, keep only the minimum-energy entry per composition.
+// Also extract elemental reference entries.
+export function get_min_entries_and_el_refs(entries) {
+    const by_formula = new Map();
+    for (const entry of entries) {
+        const key = formula_key_from_composition(entry.composition);
+        const epa = get_energy_per_atom(entry);
+        const existing = by_formula.get(key);
+        if (!existing || epa < existing.epa) {
+            by_formula.set(key, { entry, epa });
+        }
+    }
+    const min_entries = Array.from(by_formula.values(), ({ entry }) => entry);
+    const el_refs = {};
+    for (const entry of min_entries) {
+        const positive = Object.entries(entry.composition).filter(([, amt]) => amt > 0);
+        if (positive.length === 1)
+            el_refs[positive[0][0]] = entry;
+    }
+    return { min_entries, el_refs };
+}
+// Compute formation energy per atom against elemental references.
+export function compute_form_energy_per_atom(entry, el_refs) {
+    const atom_count = count_atoms_in_composition(entry.composition);
+    const energy_per_atom = get_energy_per_atom(entry);
+    let ref_energy = 0;
+    for (const [element, amount] of Object.entries(entry.composition)) {
+        if (amount <= 0)
+            continue;
+        const fraction = amount / atom_count;
+        const ref_entry = el_refs[element];
+        if (ref_entry)
+            ref_energy += fraction * get_energy_per_atom(ref_entry);
+    }
+    return energy_per_atom - ref_energy;
+}
+// Find minimum formation energy per atom across entries of one formula.
+export function best_form_energy_for_formula(entries, formula, el_refs) {
+    let best_value;
+    for (const entry of entries) {
+        if (formula_key_from_composition(entry.composition) !== formula)
+            continue;
+        const e_form = entry.e_form_per_atom ?? compute_form_energy_per_atom(entry, el_refs);
+        if (best_value === undefined || e_form < best_value)
+            best_value = e_form;
+    }
+    return best_value;
+}
+// Renormalize entry energies to be relative to elemental references (formal chemical potentials).
+// For each entry, subtracts sum(x_i * E_ref_i) from its energy per atom.
+export const renormalize_entries = (entries, el_refs, elements) => entries.map((entry) => {
+    const atoms = count_atoms_in_composition(entry.composition);
+    let renorm_energy = 0;
+    for (const el of elements) {
+        const frac = atoms > 0 ? (entry.composition[el] ?? 0) / atoms : 0;
+        const ref = el_refs[el];
+        if (ref)
+            renorm_energy += frac * get_energy_per_atom(ref);
+    }
+    const new_energy_per_atom = get_energy_per_atom(entry) - renorm_energy;
+    return {
+        ...entry,
+        energy: new_energy_per_atom * atoms,
+        energy_per_atom: new_energy_per_atom,
+    };
+});
+// Build hyperplane representation for minimum entries.
+// Each row is [x_1, ..., x_n, -E_per_atom].
+// Filters to entries with negative formation energy plus all elemental refs.
+export function build_hyperplanes(min_entries, el_refs, elements) {
+    const n_elems = elements.length;
+    const element_ref_energies = elements.map((element) => {
+        const ref_entry = el_refs[element];
+        return ref_entry ? get_energy_per_atom(ref_entry) : 0;
+    });
+    const always_include = new Set(Object.values(el_refs));
+    const tol = 1e-6; // PhaseDiagram.formation_energy_tol
+    const use_precomputed_hull = min_entries.every((entry) => typeof entry.is_stable === `boolean` || typeof entry.e_above_hull === `number`);
+    const hyperplanes = [];
+    const hyperplane_entries = [];
+    for (const entry of min_entries) {
+        const atom_count = count_atoms_in_composition(entry.composition);
+        const composition = entry.composition;
+        const energy_per_atom = get_energy_per_atom(entry);
+        const row = Array(n_elems + 1).fill(0);
+        let ref_energy = 0;
+        for (let elem_idx = 0; elem_idx < n_elems; elem_idx++) {
+            const element = elements[elem_idx];
+            const fraction = atom_count > 0 ? (composition[element] ?? 0) / atom_count : 0;
+            row[elem_idx] = fraction;
+            ref_energy += fraction * element_ref_energies[elem_idx];
+        }
+        const form_energy = energy_per_atom - ref_energy;
+        const on_precomputed_hull = use_precomputed_hull &&
+            !entry.exclude_from_hull &&
+            (entry.is_stable === true ||
+                (typeof entry.e_above_hull === `number` && entry.e_above_hull <= tol));
+        const include_entry = use_precomputed_hull
+            ? on_precomputed_hull || always_include.has(entry)
+            : form_energy < -tol || always_include.has(entry);
+        if (include_entry) {
+            row[n_elems] = -energy_per_atom;
+            hyperplanes.push(row);
+            hyperplane_entries.push(entry);
+        }
+    }
+    return { hyperplanes, hyperplane_entries };
+}
+// Build border hyperplanes from per-element limits.
+// For each axis with limits [lo, hi], creates two halfspace rows.
+export function build_border_hyperplanes(lims) {
+    const dim = lims.length;
+    const borders = [];
+    for (let idx = 0; idx < dim; idx++) {
+        // Lower bound: -mu_i + lo <= 0 → [-1, 0, ..., lo]
+        const lower = Array(dim + 1).fill(0);
+        lower[idx] = -1;
+        lower[dim] = lims[idx][0];
+        borders.push(lower);
+        // Upper bound: mu_i - hi <= 0 → [1, 0, ..., -hi]
+        const upper = Array(dim + 1).fill(0);
+        upper[idx] = 1;
+        upper[dim] = -lims[idx][1];
+        borders.push(upper);
+    }
+    return borders;
+}
+// Inline 2x2 linear solve (Cramer's rule). Returns false if singular.
+// Writes solution into out[0], out[1].
+function solve_2x2(a00, a01, b0, a10, a11, b1, out) {
+    const det = a00 * a11 - a01 * a10;
+    if (Math.abs(det) < EPS)
+        return false;
+    out[0] = (b0 * a11 - b1 * a01) / det;
+    out[1] = (a00 * b1 - a10 * b0) / det;
+    return true;
+}
+// Inline 3x3 linear solve via Cramer's rule. Returns false if singular.
+// Takes three halfspace rows directly to avoid array allocation in the hot loop.
+function solve_3x3(a, b, c, offsets, out) {
+    const det = a[0] * (b[1] * c[2] - b[2] * c[1]) -
+        a[1] * (b[0] * c[2] - b[2] * c[0]) +
+        a[2] * (b[0] * c[1] - b[1] * c[0]);
+    if (Math.abs(det) < EPS)
+        return false;
+    const inv = 1 / det;
+    out[0] =
+        (offsets[0] * (b[1] * c[2] - b[2] * c[1]) -
+            a[1] * (offsets[1] * c[2] - b[2] * offsets[2]) +
+            a[2] * (offsets[1] * c[1] - b[1] * offsets[2])) *
+            inv;
+    out[1] =
+        (a[0] * (offsets[1] * c[2] - b[2] * offsets[2]) -
+            offsets[0] * (b[0] * c[2] - b[2] * c[0]) +
+            a[2] * (b[0] * offsets[2] - offsets[1] * c[0])) *
+            inv;
+    out[2] =
+        (a[0] * (b[1] * offsets[2] - offsets[1] * c[1]) -
+            a[1] * (b[0] * offsets[2] - offsets[1] * c[0]) +
+            offsets[0] * (b[0] * c[1] - b[1] * c[0])) *
+            inv;
+    return true;
+}
+// Compute chemical potential domains via vertex enumeration.
+// This replaces scipy's HalfspaceIntersection.
+// For each combination of dim halfspaces, solves the linear system to find a
+// candidate vertex, checks feasibility against all halfspaces, then assigns
+// vertices to the phases whose hyperplanes are active at that vertex.
+export function compute_domains(hyperplanes, border_hyperplanes, hyperplane_entries, dim) {
+    const n_entries = hyperplanes.length;
+    const all_hs = [...hyperplanes, ...border_hyperplanes];
+    const n_total = all_hs.length;
+    const tol = 1e-6;
+    // Pre-compute formula keys for entry hyperplanes (avoid repeated work in hot loop)
+    const entry_formulas = hyperplane_entries.map((entry) => formula_key_from_composition(entry.composition));
+    const domains = {};
+    for (const formula of entry_formulas) {
+        if (!domains[formula])
+            domains[formula] = [];
+    }
+    // Pre-allocate reusable buffers to avoid GC pressure in the combo loop
+    const mu = Array(dim).fill(0);
+    const offsets = Array(dim).fill(0);
+    // For dim <= 3, use inline solvers; for larger dims, build A on the fly
+    const A_rows = dim > 3 ? Array.from({ length: dim }, () => Array(dim).fill(0)) : [];
+    // Generate all combinations of dim indices from n_total halfspaces
+    const combo = Array(dim).fill(0);
+    for (let idx = 0; idx < dim; idx++)
+        combo[idx] = idx;
+    function advance_combo() {
+        let pos = dim - 1;
+        while (pos >= 0 && combo[pos] >= n_total - dim + pos)
+            pos--;
+        if (pos < 0)
+            return false;
+        combo[pos]++;
+        for (let idx = pos + 1; idx < dim; idx++)
+            combo[idx] = combo[idx - 1] + 1;
+        return true;
+    }
+    while (true) {
+        // Combinations containing only border halfspaces cannot be assigned to any
+        // entry domain, so skip solving them entirely.
+        let has_entry_hyperplane = false;
+        if (dim === 2) {
+            has_entry_hyperplane = combo[0] < n_entries || combo[1] < n_entries;
+        }
+        else if (dim === 3) {
+            has_entry_hyperplane =
+                combo[0] < n_entries || combo[1] < n_entries || combo[2] < n_entries;
+        }
+        else {
+            for (let row = 0; row < dim; row++) {
+                if (combo[row] < n_entries) {
+                    has_entry_hyperplane = true;
+                    break;
+                }
+            }
+        }
+        if (!has_entry_hyperplane) {
+            if (!advance_combo())
+                break;
+            continue;
+        }
+        // Compute offsets (negated last column of selected halfspaces)
+        for (let row = 0; row < dim; row++)
+            offsets[row] = -all_hs[combo[row]][dim];
+        // Solve for vertex using dimension-specialized solvers
+        let solved = false;
+        if (dim === 2) {
+            const h0 = all_hs[combo[0]];
+            const h1 = all_hs[combo[1]];
+            solved = solve_2x2(h0[0], h0[1], offsets[0], h1[0], h1[1], offsets[1], mu);
+        }
+        else if (dim === 3) {
+            solved = solve_3x3(all_hs[combo[0]], all_hs[combo[1]], all_hs[combo[2]], offsets, mu);
+        }
+        else {
+            // General case: build A matrix and use LU solver
+            for (let row = 0; row < dim; row++) {
+                const hs = all_hs[combo[row]];
+                for (let col = 0; col < dim; col++)
+                    A_rows[row][col] = hs[col];
+            }
+            const result = solve_linear_system(A_rows, offsets);
+            if (result) {
+                for (let idx = 0; idx < dim; idx++)
+                    mu[idx] = result[idx];
+                solved = true;
+            }
+        }
+        if (solved) {
+            // Feasibility check: all halfspaces must be satisfied (a·mu + b <= tol)
+            const selected_hs_idx_0 = dim > 0 ? combo[0] : -1;
+            const selected_hs_idx_1 = dim > 1 ? combo[1] : -1;
+            const selected_hs_idx_2 = dim > 2 ? combo[2] : -1;
+            for (let idx = 0; idx < n_total; idx++) {
+                if (dim <= 3) {
+                    if (idx === selected_hs_idx_0 ||
+                        idx === selected_hs_idx_1 ||
+                        idx === selected_hs_idx_2)
+                        continue;
+                }
+                else {
+                    let is_active_halfspace = false;
+                    for (let combo_idx = 0; combo_idx < dim; combo_idx++) {
+                        if (combo[combo_idx] === idx) {
+                            is_active_halfspace = true;
+                            break;
+                        }
+                    }
+                    if (is_active_halfspace)
+                        continue;
+                }
+                const hs = all_hs[idx];
+                let val = hs[dim];
+                if (dim === 2) {
+                    val += hs[0] * mu[0] + hs[1] * mu[1];
+                }
+                else if (dim === 3) {
+                    val += hs[0] * mu[0] + hs[1] * mu[1] + hs[2] * mu[2];
+                }
+                else {
+                    for (let jdx = 0; jdx < dim; jdx++)
+                        val += hs[jdx] * mu[jdx];
+                }
+                if (val > tol) {
+                    solved = false;
+                    break;
+                }
+            }
+            if (solved) {
+                // Assign vertex to entries whose hyperplanes are active
+                const vertex = dim === 2 ? [mu[0], mu[1]] : dim === 3 ? [mu[0], mu[1], mu[2]] : [...mu];
+                for (let idx = 0; idx < dim; idx++) {
+                    const hs_idx = combo[idx];
+                    if (hs_idx < n_entries) {
+                        domains[entry_formulas[hs_idx]].push([...vertex]);
+                    }
+                }
+            }
+        }
+        // Advance to next combination (lexicographic order)
+        if (!advance_combo())
+            break;
+    }
+    return Object.fromEntries(Object.entries(domains).filter(([, domain]) => domain.length > 0));
+}
+// Apply element padding: replace coordinates close to default_min_limit with
+// actual_min - padding for cleaner visual bounds. Single pass over all points.
+export function apply_element_padding(domains, elem_indices, padding, default_min_limit) {
+    const replace_threshold = Math.max(Math.abs(padding), EPS);
+    // Single-pass: track min per axis, skipping default_min_limit values
+    const mins = elem_indices.map(() => Infinity);
+    for (const pts of Object.values(domains)) {
+        for (const pt of pts) {
+            for (let idx = 0; idx < elem_indices.length; idx++) {
+                const val = pt[elem_indices[idx]];
+                if (Math.abs(val - default_min_limit) > replace_threshold && val < mins[idx]) {
+                    mins[idx] = val;
+                }
+            }
+        }
+    }
+    return mins.map((min_val) => (Number.isFinite(min_val) ? min_val : default_min_limit) - padding);
+}
+// Replace default_min_limit coordinates with padded limits for display
+export function pad_domain_points(pts, elem_indices, new_lims, default_min_limit, padding) {
+    const replace_threshold = Math.max(Math.abs(padding), EPS);
+    return pts.map((pt) => {
+        const padded = [...pt];
+        for (let idx = 0; idx < elem_indices.length; idx++) {
+            const col = elem_indices[idx];
+            if (Math.abs(padded[col] - default_min_limit) < replace_threshold) {
+                padded[col] = new_lims[idx];
+            }
+        }
+        return padded;
+    });
+}
+// Build per-axis min/max ranges for a set of points
+export function build_axis_ranges(points, elements) {
+    return elements.map((element, axis_idx) => {
+        let [min_val, max_val] = [Infinity, -Infinity];
+        for (const point of points) {
+            const val = point[axis_idx];
+            if (val < min_val)
+                min_val = val;
+            if (val > max_val)
+                max_val = val;
+        }
+        return { element: element ?? `\u03BC${axis_idx}`, min_val, max_val };
+    });
+}
+// === Label Placement Helpers ===
+// Simple PCA: center data, compute covariance, eigendecompose, project to top-k.
+// Used in 3D for finding domain polygon orientation for label placement.
+export function simple_pca(data, k = 2) {
+    const n_rows = data.length;
+    const n_cols = data[0]?.length ?? 0;
+    if (n_rows === 0 || n_cols === 0) {
+        return { scores: [], eigenvectors: [] };
+    }
+    // Center the data
+    const means = Array(n_cols).fill(0);
+    for (const row of data) {
+        for (let col = 0; col < n_cols; col++)
+            means[col] += row[col];
+    }
+    for (let col = 0; col < n_cols; col++)
+        means[col] /= n_rows;
+    const centered = data.map((row) => row.map((val, col) => val - means[col]));
+    // Covariance matrix
+    const cov = Array.from({ length: n_cols }, () => Array(n_cols).fill(0));
+    for (const row of centered) {
+        for (let idx = 0; idx < n_cols; idx++) {
+            for (let jdx = idx; jdx < n_cols; jdx++) {
+                cov[idx][jdx] += row[idx] * row[jdx];
+            }
+        }
+    }
+    for (let idx = 0; idx < n_cols; idx++) {
+        cov[idx][idx] /= n_rows;
+        for (let jdx = idx + 1; jdx < n_cols; jdx++) {
+            cov[idx][jdx] /= n_rows;
+            cov[jdx][idx] = cov[idx][jdx];
+        }
+    }
+    // Power iteration for top-k eigenvectors (sufficient for k=2 on small matrices)
+    const eigenvectors = [];
+    const work_cov = cov.map((row) => [...row]);
+    for (let comp = 0; comp < k; comp++) {
+        let vec = Array(n_cols).fill(0);
+        vec[comp % n_cols] = 1; // initial guess
+        for (let iter = 0; iter < 100; iter++) {
+            // Matrix-vector multiply
+            const new_vec = Array(n_cols).fill(0);
+            for (let idx = 0; idx < n_cols; idx++) {
+                for (let jdx = 0; jdx < n_cols; jdx++) {
+                    new_vec[idx] += work_cov[idx][jdx] * vec[jdx];
+                }
+            }
+            // Normalize
+            const norm = Math.hypot(...new_vec);
+            if (norm < EPS)
+                break;
+            const prev = vec;
+            vec = new_vec.map((val) => val / norm);
+            // Early exit when eigenvector has converged
+            if (prev.every((val, idx) => Math.abs(val - vec[idx]) < EPS))
+                break;
+        }
+        // Rayleigh quotient for deflation
+        const eigenvalue = vec.reduce((sum, val, idx) => {
+            let mv = 0;
+            for (let jdx = 0; jdx < n_cols; jdx++)
+                mv += work_cov[idx][jdx] * vec[jdx];
+            return sum + val * mv;
+        }, 0);
+        eigenvectors.push(vec);
+        // Deflate: remove this component from the covariance matrix
+        for (let idx = 0; idx < n_cols; idx++) {
+            for (let jdx = 0; jdx < n_cols; jdx++) {
+                work_cov[idx][jdx] -= eigenvalue * vec[idx] * vec[jdx];
+            }
+        }
+    }
+    // Project data onto eigenvectors
+    const scores = centered.map((row) => eigenvectors.map((ev) => row.reduce((sum, val, idx) => sum + val * ev[idx], 0)));
+    return { scores, eigenvectors };
+}
+// Compute orthonormal vector to a 2D line segment (for label offset in 2D diagrams)
+export function orthonormal_2d(line_pts) {
+    const dx = line_pts[1][0] - line_pts[0][0];
+    const dy = line_pts[1][1] - line_pts[0][1];
+    const perp = [-dy, dx];
+    const len = Math.hypot(perp[0], perp[1]);
+    if (len < EPS)
+        return [0, 1];
+    return [perp[0] / len, perp[1] / len];
+}
+// Deduplicate points within tolerance, returning unique points and index mapping
+export function dedup_points(pts, tol = 1e-4) {
+    const unique = [];
+    const orig_indices = [];
+    for (let idx = 0; idx < pts.length; idx++) {
+        const pt = pts[idx];
+        const is_dup = unique.some((existing) => existing.every((val, dim) => Math.abs(val - pt[dim]) < tol));
+        if (!is_dup) {
+            unique.push(pt);
+            orig_indices.push(idx);
+        }
+    }
+    return { unique, orig_indices };
+}
+// For a 3D domain, compute convex hull boundary edges and annotation location.
+// Deduplicates vertices first, then uses PCA to project to 2D for the convex
+// hull computation. Returns only the outer boundary edges, not interior lines.
+export function get_3d_domain_simplexes_and_ann_loc(points_3d) {
+    // Deduplicate vertices to avoid cluttered interior edges
+    const { unique, orig_indices } = dedup_points(points_3d);
+    if (unique.length < 3) {
+        if (unique.length === 2) {
+            const midpoint = unique[0].map((val, dim) => (val + unique[1][dim]) / 2);
+            return { simplex_indices: [[orig_indices[0], orig_indices[1]]], ann_loc: midpoint };
+        }
+        return { simplex_indices: [], ann_loc: unique[0] ?? points_3d[0] ?? [0, 0, 0] };
+    }
+    const { scores, eigenvectors } = simple_pca(unique, 2);
+    // 2D convex hull of PCA-projected unique points → only boundary edges
+    const pts_2d = scores.map((row) => [row[0], row[1]]);
+    const hull = convex_hull_2d(pts_2d);
+    const centroid = polygon_centroid(hull);
+    // Map centroid back to 3D
+    const n_dims = unique[0].length;
+    const mean_3d = Array.from({ length: n_dims }, (_, dim) => unique.reduce((sum, pt) => sum + pt[dim], 0) / unique.length);
+    const centroid_x = centroid[0] ?? 0;
+    const centroid_y = centroid[1] ?? 0;
+    const first_eigenvector = eigenvectors[0] ?? Array(n_dims).fill(0);
+    const second_eigenvector = eigenvectors[1] ?? Array(n_dims).fill(0);
+    const ann_loc = mean_3d.map((m, dim) => m + centroid_x * first_eigenvector[dim] + centroid_y * second_eigenvector[dim]);
+    // Map hull vertices back to original point indices using nearest projected
+    // vertex instead of stringified coordinates to avoid precision aliasing.
+    function nearest_projected_idx(target) {
+        let [nearest_idx, min_sq_dist] = [0, Infinity];
+        for (let idx = 0; idx < pts_2d.length; idx++) {
+            const dx = pts_2d[idx][0] - target[0];
+            const dy = pts_2d[idx][1] - target[1];
+            const sq_dist = dx * dx + dy * dy;
+            if (sq_dist < min_sq_dist) {
+                min_sq_dist = sq_dist;
+                nearest_idx = idx;
+            }
+        }
+        return nearest_idx;
+    }
+    const simplex_indices = [];
+    for (let hull_idx = 0; hull_idx < hull.length; hull_idx++) {
+        const pt_a = hull[hull_idx];
+        const pt_b = hull[(hull_idx + 1) % hull.length];
+        const ui_a = nearest_projected_idx(pt_a);
+        const ui_b = nearest_projected_idx(pt_b);
+        // Map back to original array indices
+        simplex_indices.push([orig_indices[ui_a], orig_indices[ui_b]]);
+    }
+    return { simplex_indices, ann_loc };
+}
+// === Label Sizing ===
+// Bounding box diagonal of a set of N-D points (Euclidean distance between
+// the min and max corners). Returns 0 for fewer than 2 points.
+export function bbox_diagonal(points) {
+    if (points.length < 2)
+        return 0;
+    let sq_sum = 0;
+    for (let col = 0; col < points[0].length; col++) {
+        let lo = Infinity, hi = -Infinity;
+        for (const pt of points) {
+            lo = Math.min(lo, pt[col]);
+            hi = Math.max(hi, pt[col]);
+        }
+        sq_sum += (hi - lo) ** 2;
+    }
+    return Math.sqrt(sq_sum);
+}
+// Map an array of raw size values to font sizes via linear interpolation.
+// Returns a new array of font sizes in [min_font, max_font].
+// If all sizes are equal, returns the midpoint for all.
+export function scale_to_font_range(sizes, min_font, max_font) {
+    const min_size = Math.min(...sizes);
+    const max_size = Math.max(...sizes);
+    const range = max_size - min_size;
+    const mid = (min_font + max_font) / 2;
+    return sizes.map((size) => range > 0 ? min_font + ((max_font - min_font) * (size - min_size)) / range : mid);
+}
+export function get_visible_domain_labels(face_positions, face_domain_map, label_font_size_by_formula, pinned_labels = []) {
+    const n_faces = Math.min(Math.floor(face_positions.length / 9), face_domain_map.length);
+    const accum = new Map();
+    for (let face_idx = 0; face_idx < n_faces; face_idx++) {
+        const formula = face_domain_map[face_idx];
+        if (!formula || !label_font_size_by_formula.has(formula))
+            continue;
+        const base = face_idx * 9;
+        const ax = face_positions[base];
+        const ay = face_positions[base + 1];
+        const az = face_positions[base + 2];
+        const bx = face_positions[base + 3];
+        const by = face_positions[base + 4];
+        const bz = face_positions[base + 5];
+        const cx = face_positions[base + 6];
+        const cy = face_positions[base + 7];
+        const cz = face_positions[base + 8];
+        const abx = bx - ax;
+        const aby = by - ay;
+        const abz = bz - az;
+        const acx = cx - ax;
+        const acy = cy - ay;
+        const acz = cz - az;
+        const cross_x = aby * acz - abz * acy;
+        const cross_y = abz * acx - abx * acz;
+        const cross_z = abx * acy - aby * acx;
+        const area = Math.hypot(cross_x, cross_y, cross_z) / 2;
+        if (area <= EPS)
+            continue;
+        const centroid_x = (ax + bx + cx) / 3;
+        const centroid_y = (ay + by + cy) / 3;
+        const centroid_z = (az + bz + cz) / 3;
+        const entry = accum.get(formula) ?? { area: 0, x: 0, y: 0, z: 0 };
+        entry.area += area;
+        entry.x += centroid_x * area;
+        entry.y += centroid_y * area;
+        entry.z += centroid_z * area;
+        accum.set(formula, entry);
+    }
+    const visible_labels = [...accum.entries()]
+        .filter(([, entry]) => entry.area > EPS)
+        .map(([formula, entry]) => ({
+        formula,
+        position: [entry.x / entry.area, entry.y / entry.area, entry.z / entry.area],
+        label_font_size: label_font_size_by_formula.get(formula) ?? 12,
+    }));
+    for (const label of pinned_labels) {
+        if (!visible_labels.some((visible_label) => visible_label.formula === label.formula)) {
+            visible_labels.push(label);
+        }
+    }
+    return visible_labels.sort((label_a, label_b) => label_a.formula.localeCompare(label_b.formula));
+}
+// === Ternary Combinations ===
+// Generate all C(n,3) ternary element combinations from a sorted element list.
+// Each triplet is sorted alphabetically. Returns empty array for fewer than 3 elements.
+export function get_ternary_combinations(elements) {
+    const sorted = [...elements].sort();
+    const n_elems = sorted.length;
+    if (n_elems < 3)
+        return [];
+    const combos = [];
+    for (let first = 0; first < n_elems - 2; first++) {
+        for (let second = first + 1; second < n_elems - 1; second++) {
+            for (let third = second + 1; third < n_elems; third++) {
+                combos.push([sorted[first], sorted[second], sorted[third]]);
+            }
+        }
+    }
+    return combos;
+}
+let nd_cache = null;
+// Content-based fingerprint for N-D result caching. Uses sorted formula keys
+// so deserialized Web Worker copies match and different compositions never collide.
+export function make_nd_cache_key(entries, formal_chempots, default_min_limit, limits) {
+    const keyed = entries
+        .map((entry) => [
+        formula_key_from_composition(entry.composition),
+        entry.energy,
+        entry.is_stable ?? ``,
+        entry.e_above_hull ?? ``,
+        entry.exclude_from_hull ?? ``,
+    ].join(`:`))
+        .sort();
+    return `${keyed.join(`,`)}|${formal_chempots}|${default_min_limit}|${JSON.stringify(limits ?? {})}`;
+}
+// === Main Pipeline ===
+// Compute the full chemical potential diagram from entries and config.
+// Returns domains, elements, refs, and all intermediate data.
+//
+// Supports two modes based on config.elements vs data dimensionality:
+// - **Subsystem mode**: config.elements matches data element count → filter entries
+//   to subsystem, compute in reduced dimensionality (fast for ternary from ternary data)
+// - **Projection mode**: config.elements has fewer elements than data → compute in
+//   full N-D, then project domain vertices to selected display axes (column extraction).
+//   This matches pymatgen's ChemicalPotentialDiagram behavior for multinary systems.
+export function compute_chempot_diagram(entries, config = {}) {
+    const { formal_chempots = CHEMPOT_DEFAULTS.formal_chempots, default_min_limit = CHEMPOT_DEFAULTS.default_min_limit, limits, } = config;
+    // Detect all unique elements across all input entries (single pass, low allocation)
+    const all_data_elements_set = new Set();
+    for (const entry of entries) {
+        for (const [element, amount] of Object.entries(entry.composition)) {
+            if (amount > 0)
+                all_data_elements_set.add(element);
+        }
+    }
+    const all_data_elements = Array.from(all_data_elements_set).sort();
+    // Display elements: user-specified order (controls axis mapping), or auto-detect
+    const display_elements = config.elements?.length ? [...config.elements] : all_data_elements;
+    // Projection mode: display fewer axes than the data has elements
+    // In this mode, compute in full N-D and project afterward
+    const is_projection = display_elements.length < all_data_elements.length &&
+        display_elements.every((el) => all_data_elements.includes(el));
+    // Computation elements: full element set for projection, display set for subsystem
+    const compute_elements = is_projection ? all_data_elements : display_elements;
+    // Try cache for projection mode (same entries + config = same N-D domains)
+    const cache_key = is_projection
+        ? make_nd_cache_key(entries, formal_chempots, default_min_limit, limits)
+        : ``;
+    let nd_result = is_projection && nd_cache?.key === cache_key ? nd_cache.result : null;
+    if (!nd_result) {
+        // In subsystem mode, filter entries to only those within the element set
+        let working_entries = entries;
+        if (!is_projection && config.elements?.length) {
+            const target_set = new Set(config.elements);
+            working_entries = entries.filter((entry) => {
+                for (const [element, amount] of Object.entries(entry.composition)) {
+                    if (amount > 0 && !target_set.has(element))
+                        return false;
+                }
+                return true;
+            });
+        }
+        // Sort entries by composition (Schwartzian transform to avoid recomputing keys)
+        const sorted_entries = working_entries
+            .map((entry) => ({ entry, key: formula_key_from_composition(entry.composition) }))
+            .sort((a, b) => a.key.localeCompare(b.key))
+            .map(({ entry }) => entry);
+        // Get min entries and elemental references
+        let { min_entries, el_refs } = get_min_entries_and_el_refs(sorted_entries);
+        const dim = compute_elements.length;
+        if (dim < 2) {
+            throw new Error(`ChemicalPotentialDiagram requires 2+ elements, got ${dim}`);
+        }
+        // Check all elemental refs exist for the computation elements
+        const missing_refs = compute_elements.filter((el) => !el_refs[el]);
+        if (missing_refs.length > 0) {
+            throw new Error(`Missing elemental reference entries for: ${missing_refs.join(`, `)}`);
+        }
+        // Renormalize if using formal chemical potentials
+        if (formal_chempots) {
+            min_entries = renormalize_entries(min_entries, el_refs, compute_elements);
+            const renorm_result = get_min_entries_and_el_refs(min_entries);
+            el_refs = renorm_result.el_refs;
+        }
+        // Build limits array for computation elements
+        const compute_lims = compute_elements.map((el) => {
+            if (limits?.[el])
+                return limits[el];
+            return [default_min_limit, 0];
+        });
+        // Build hyperplanes and compute domains in full dimensionality
+        const { hyperplanes, hyperplane_entries } = build_hyperplanes(min_entries, el_refs, compute_elements);
+        const border_hyperplanes = build_border_hyperplanes(compute_lims);
+        const domains = compute_domains(hyperplanes, border_hyperplanes, hyperplane_entries, dim);
+        nd_result = {
+            domains,
+            el_refs,
+            min_entries,
+            hyperplanes,
+            hyperplane_entries,
+            compute_lims,
+        };
+        // Cache for projection mode reuse
+        if (is_projection) {
+            nd_cache = { key: cache_key, result: nd_result };
+        }
+    }
+    let domains = nd_result.domains;
+    let output_lims = nd_result.compute_lims;
+    // Project domain vertices from N-D to display axes (column extraction)
+    if (is_projection) {
+        const col_indices = display_elements.map((element) => {
+            const idx = compute_elements.indexOf(element);
+            if (idx === -1) {
+                throw new Error(`Display element ${element} not present in compute element set`);
+            }
+            return idx;
+        });
+        const projected = {};
+        for (const [formula, pts] of Object.entries(domains)) {
+            projected[formula] = pts.map((pt) => col_indices.map((idx) => pt[idx]));
+        }
+        domains = projected;
+        output_lims = col_indices.map((col_idx) => nd_result.compute_lims[col_idx]);
+    }
+    return {
+        domains,
+        elements: display_elements,
+        el_refs: nd_result.el_refs,
+        min_entries: nd_result.min_entries,
+        hyperplanes: nd_result.hyperplanes,
+        hyperplane_entries: nd_result.hyperplane_entries,
+        lims: output_lims,
+    };
+}