matterviz 0.3.5 → 0.3.6

package/dist/src/lib/chempot-diagram/compute.ts

@@ -0,0 +1,1014 @@
+// Core computational logic for chemical potential diagrams.
+// Ports pymatgen's ChemicalPotentialDiagram algorithm to TypeScript.
+// Reference: pymatgen/analysis/chempot_diagram.py
+
+import type { PhaseData } from '$lib/convex-hull/types'
+import { convex_hull_2d, EPS, polygon_centroid, solve_linear_system } from '$lib/math'
+import type { Vec2 } from '$lib/math'
+import { CHEMPOT_DEFAULTS, type ChemPotDiagramConfig, type ChemPotDiagramData } 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: Record<string, number>): number =>
+  Object.values(composition).reduce((sum, count) => sum + (count ?? 0), 0)
+
+const gcd = (num_a: number, num_b: number): number =>
+  num_b === 0 ? num_a : gcd(num_b, num_a % num_b)
+
+const get_reduced_formula = (composition: Record<string, number>): Record<string, number> => {
+  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: PhaseData): number {
+  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<Record<string, number>, string>()
+
+// Get a stable reduced formula string from composition dict (cached)
+export function formula_key_from_composition(composition: Record<string, number>): string {
+  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: PhaseData[]): {
+  min_entries: PhaseData[]
+  el_refs: Record<string, PhaseData>
+} {
+  const by_formula = new Map<string, { entry: PhaseData; epa: number }>()
+
+  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: Record<string, PhaseData> = {}
+
+  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: PhaseData,
+  el_refs: Record<string, PhaseData>,
+): number {
+  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: PhaseData[],
+  formula: string,
+  el_refs: Record<string, PhaseData>,
+): number | undefined {
+  let best_value: number | undefined
+  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 function renormalize_entries(
+  entries: PhaseData[],
+  el_refs: Record<string, PhaseData>,
+  elements: string[],
+): PhaseData[] {
+  return 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 as Record<string, number>)[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: PhaseData[],
+  el_refs: Record<string, PhaseData>,
+  elements: string[],
+): { hyperplanes: number[][]; hyperplane_entries: PhaseData[] } {
+  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<PhaseData>(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: number[][] = []
+  const hyperplane_entries: PhaseData[] = []
+
+  for (const entry of min_entries) {
+    const atom_count = count_atoms_in_composition(entry.composition)
+    const composition = entry.composition as Record<string, number>
+    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: [number, number][]): number[][] {
+  const dim = lims.length
+  const borders: number[][] = []
+  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: number,
+  a01: number,
+  b0: number,
+  a10: number,
+  a11: number,
+  b1: number,
+  out: number[],
+): boolean {
+  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: number[],
+  b: number[],
+  c: number[],
+  offsets: number[],
+  out: number[],
+): boolean {
+  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: number[][],
+  border_hyperplanes: number[][],
+  hyperplane_entries: PhaseData[],
+  dim: number,
+): Record<string, number[][]> {
+  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: Record<string, number[][]> = {}
+  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: number[][] =
+    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(): boolean {
+    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: Record<string, number[][]>,
+  elem_indices: number[],
+  padding: number,
+  default_min_limit: number,
+): number[] {
+  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: number[][],
+  elem_indices: number[],
+  new_lims: number[],
+  default_min_limit: number,
+  padding: number,
+): number[][] {
+  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: number[][],
+  elements: string[],
+): { element: string; min_val: number; max_val: number }[] {
+  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: number[][],
+  k: number = 2,
+): { scores: number[][]; eigenvectors: number[][] } {
+  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: number[][] = 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: number[][] = []
+  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: number[][]): [number, number] {
+  const dx = line_pts[1][0] - line_pts[0][0]
+  const dy = line_pts[1][1] - line_pts[0][1]
+  const perp: [number, number] = [-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: number[][],
+  tol: number = 1e-4,
+): {
+  unique: number[][]
+  orig_indices: number[] // for each unique point, the index in the original array
+} {
+  const unique: number[][] = []
+  const orig_indices: number[] = []
+  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: number[][]): {
+  simplex_indices: number[][]
+  ann_loc: number[]
+} {
+  // 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: Vec2[] = 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: Vec2): number {
+    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: number[][] = []
+  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: number[][]): number {
+  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: number[],
+  min_font: number,
+  max_font: number,
+): number[] {
+  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 interface VisibleDomainLabel {
+  formula: string
+  position: [number, number, number]
+  label_font_size: number
+}
+
+export function get_visible_domain_labels(
+  face_positions: ArrayLike<number>,
+  face_domain_map: string[],
+  label_font_size_by_formula: ReadonlyMap<string, number>,
+  pinned_labels: VisibleDomainLabel[] = [],
+): VisibleDomainLabel[] {
+  const n_faces = Math.min(Math.floor(face_positions.length / 9), face_domain_map.length)
+  const accum = new Map<string, { area: number; x: number; y: number; z: number }>()
+
+  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] as [
+        number,
+        number,
+        number,
+      ],
+      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: string[]): string[][] {
+  const sorted = [...elements].sort()
+  const n_elems = sorted.length
+  if (n_elems < 3) return []
+  const combos: string[][] = []
+  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
+}
+
+// === Full N-D Computation Cache ===
+// In projection mode, the expensive vertex enumeration (compute_domains) depends only
+// on the entries, formal_chempots, default_min_limit, and limits -- NOT on which 3
+// elements are projected onto. When showing all C(n,3) ternary projections of the same
+// quaternary system, this cache avoids repeating the ~42s computation per projection.
+
+interface FullNDResult {
+  domains: Record<string, number[][]>
+  el_refs: Record<string, PhaseData>
+  min_entries: PhaseData[]
+  hyperplanes: number[][]
+  hyperplane_entries: PhaseData[]
+  compute_lims: [number, number][]
+}
+
+let nd_cache: {
+  key: string
+  result: FullNDResult
+} | null = 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: PhaseData[],
+  formal_chempots: boolean,
+  default_min_limit: number,
+  limits: ChemPotDiagramConfig[`limits`],
+): string {
+  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: PhaseData[],
+  config: ChemPotDiagramConfig = {},
+): ChemPotDiagramData {
+  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<string>()
+  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: FullNDResult | null =
+    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: [number, number][] = 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 < 0) {
+        throw new Error(`Display element ${element} not present in compute element set`)
+      }
+      return idx
+    })
+    const projected: Record<string, number[][]> = {}
+    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,
+  }
+}