matterviz 0.3.2 → 0.3.4

package/dist/convex-hull/helpers.js

@@ -4,15 +4,31 @@ import { format_fractional, format_num, symbol_map } from '../labels';
 import { scaleSequential } from 'd3-scale';
 import { symbol } from 'd3-shape';
 import { analyze_gas_data as _analyze_gas_data, apply_gas_corrections as _apply_gas_corrections, } from './gas-thermodynamics';
-import { DEFAULT_GAS_TEMP, is_unary_entry } from './types';
+import { DEFAULT_GAS_TEMP } from './types';
 export { DEFAULT_GAS_TEMP };
+// Tolerance for classifying a phase as on the convex hull (eV/atom)
+export const HULL_STABILITY_TOL = 1e-6;
+// Clamp raw hull distance and compute stability for a single entry.
+// Excluded entries keep their raw (possibly negative) distance and are never stable.
+export function compute_hull_stability(raw_distance, exclude_from_hull, tol = HULL_STABILITY_TOL) {
+    if (exclude_from_hull)
+        return { e_above_hull: raw_distance, is_stable: false };
+    const e_above_hull = Math.abs(raw_distance) < tol ? 0 : Math.max(0, raw_distance);
+    return { e_above_hull, is_stable: e_above_hull <= tol };
+}
+// Check if entry is on the convex hull (stable or e_above_hull ≈ 0)
+export const is_on_hull = (entry, tol = HULL_STABILITY_TOL) => !entry.exclude_from_hull &&
+    (entry.is_stable === true ||
+        (typeof entry.e_above_hull === `number` && entry.e_above_hull < tol));
+export const get_arity = (entry) => Object.values(entry.composition).filter((count) => count > 0).length;
+export const is_unary_entry = (entry) => get_arity(entry) === 1;
 // Energy color scale factory (shared)
 export function get_energy_color_scale(color_mode, color_scale, plot_entries) {
     if (color_mode !== `energy` || plot_entries.length === 0)
         return null;
     const hull_distances = plot_entries
         .map((entry) => entry.e_above_hull)
-        .filter((v) => typeof v === `number`);
+        .filter((val) => typeof val === `number`);
     if (hull_distances.length === 0)
         return null;
     const lo = Math.min(...hull_distances);
@@ -25,7 +41,7 @@ export function get_energy_color_scale(color_mode, color_scale, plot_entries) {
 export function get_point_color_for_entry(entry, color_mode, colors, energy_scale) {
     const is_stable = Boolean(entry.is_stable) || entry.e_above_hull === 0;
     if (color_mode === `stability`) {
-        return is_stable ? (colors?.stable || `#0072B2`) : (colors?.unstable || `#E69F00`);
+        return is_stable ? colors?.stable || `#0072B2` : colors?.unstable || `#E69F00`;
     }
     return energy_scale && typeof entry.e_above_hull === `number`
         ? energy_scale(entry.e_above_hull)
@@ -55,10 +71,9 @@ export function calc_max_hull_dist_in_data(processed_entries) {
     if (processed_entries.length === 0)
         return 0.5;
     const hull_distances = processed_entries
-        .map((e) => e.e_above_hull)
-        .filter((v) => typeof v === `number` && Number.isFinite(v));
-    const max_val = (hull_distances.length ? Math.max(...hull_distances) : 0) +
-        0.001;
+        .map((entry) => entry.e_above_hull)
+        .filter((val) => typeof val === `number` && Number.isFinite(val));
+    const max_val = (hull_distances.length ? Math.max(...hull_distances) : 0) + 0.001;
     return Math.max(0.1, max_val);
 }
 // Smart threshold for showing unstable entries based on entry count.
@@ -76,9 +91,7 @@ export function compute_auto_hull_dist_threshold(n_entries, max_hull_dist_in_dat
 export function build_entry_tooltip_text(entry) {
     const is_element = is_unary_entry(entry);
     const elem_symbol = is_element ? Object.keys(entry.composition)[0] : ``;
-    const elem_name = is_element
-        ? ELEM_SYMBOL_TO_NAME[elem_symbol] ?? ``
-        : ``;
+    const elem_name = is_element ? (ELEM_SYMBOL_TO_NAME[elem_symbol] ?? ``) : ``;
     let text = is_element
         ? `${elem_symbol}${elem_name ? ` (${elem_name})` : ``}\n`
         : `${entry.name || entry.reduced_formula || ``}\n`;
@@ -98,9 +111,7 @@ export function build_entry_tooltip_text(entry) {
         text += `E<sub>above hull</sub>: ${e_hull_str} eV/atom\n`;
     }
     // Fallback to energy_per_atom if e_form_per_atom is absent
-    const e_form_display = entry.e_form_per_atom !== undefined
-        ? entry.e_form_per_atom
-        : entry.energy_per_atom;
+    const e_form_display = entry.e_form_per_atom !== undefined ? entry.e_form_per_atom : entry.energy_per_atom;
     if (e_form_display !== undefined) {
         const e_form_str = format_num(e_form_display, `.3~`);
         text += `E<sub>form</sub>: ${e_form_str} eV/atom`;
@@ -122,8 +133,7 @@ export function find_hull_entry_at_mouse(canvas, event, plot_entries, project_po
             continue;
         const projected = project_point(entry.x, entry.y, entry.z);
         const distance = Math.hypot(mouse_x - projected.x, mouse_y - projected.y);
-        const base = entry.size ??
-            ((entry.is_stable || entry.e_above_hull === 0) ? 6 : 4);
+        const base = entry.size ?? (entry.is_stable || entry.e_above_hull === 0 ? 6 : 4);
         if (distance < base * container_scale + 5)
             return entry;
     }
@@ -144,12 +154,10 @@ export function calculate_modal_side(wrapper) {
 export function compute_energy_mode_info(entries, // Array of phase entries to analyze
 find_lowest_energy_unary_refs_fn, // Function to find unary references
 energy_source_mode) {
-    const has_precomputed_e_form = entries.length > 0 &&
-        entries.every((e) => typeof e.e_form_per_atom === `number`);
-    const has_precomputed_hull = entries.length > 0 &&
-        entries.every((e) => typeof e.e_above_hull === `number`);
+    const has_precomputed_e_form = entries.length > 0 && entries.every((entry) => typeof entry.e_form_per_atom === `number`);
+    const has_precomputed_hull = entries.length > 0 && entries.every((entry) => typeof entry.e_above_hull === `number`);
     const unary_refs = find_lowest_energy_unary_refs_fn(entries);
-    const elements_in_entries = Array.from(new Set(entries.flatMap((e) => Object.keys(e.composition))));
+    const elements_in_entries = Array.from(new Set(entries.flatMap((entry) => Object.keys(entry.composition))));
     const can_compute_e_form = elements_in_entries.every((el) => Boolean(unary_refs[el]));
     const can_compute_hull = can_compute_e_form;
     // Resolve mode to avoid inconsistent states:
@@ -259,6 +267,42 @@ function get_entry_energy_by_metric(entry, metric) {
     }
     return null;
 }
+function get_label_representative_energy(entry) {
+    if (is_finite(entry.e_form_per_atom))
+        return entry.e_form_per_atom;
+    if (is_finite(entry.energy_per_atom))
+        return entry.energy_per_atom;
+    const energy_per_atom = compute_energy_per_atom(entry);
+    if (energy_per_atom !== null)
+        return energy_per_atom;
+    if (is_finite(entry.energy))
+        return entry.energy;
+    if (is_finite(entry.e_above_hull))
+        return entry.e_above_hull;
+    return Number.POSITIVE_INFINITY;
+}
+function get_fractional_composition_key(composition) {
+    return Object.entries(get_fractional_composition(composition))
+        .sort(([elem_a], [elem_b]) => elem_a.localeCompare(elem_b))
+        .map(([elem, frac]) => `${elem}:${frac.toFixed(6)}`)
+        .join(`|`);
+}
+// Pick one label target per normalized composition. Multiple polymorphs, supercell
+// formulas, or same-composition entries often project to the same screen position.
+export function get_composition_label_entries(entries) {
+    const label_entry_by_composition = new Map();
+    for (const entry of entries) {
+        const comp_key = get_fractional_composition_key(entry.composition);
+        if (!comp_key)
+            continue;
+        const existing = label_entry_by_composition.get(comp_key);
+        if (!existing ||
+            get_label_representative_energy(entry) < get_label_representative_energy(existing)) {
+            label_entry_by_composition.set(comp_key, entry);
+        }
+    }
+    return Array.from(label_entry_by_composition.values());
+}
 // Determine which energy metric to use for a composition group
 // Returns the first metric that ALL entries in the group can provide
 function select_group_energy_metric(polymorphs) {
@@ -267,8 +311,7 @@ function select_group_energy_metric(polymorphs) {
         return `e_form_per_atom`;
     }
     // Try energy_per_atom (either direct field or computed from total energy)
-    if (polymorphs.every((entry) => is_finite(entry.energy_per_atom) ||
-        compute_energy_per_atom(entry) !== null))
+    if (polymorphs.every((entry) => is_finite(entry.energy_per_atom) || compute_energy_per_atom(entry) !== null))
         return `energy_per_atom`;
     // Last resort: e_above_hull (will fail to differentiate stable polymorphs with e_above_hull=0)
     if (polymorphs.every((entry) => is_finite(entry.e_above_hull))) {
@@ -284,11 +327,7 @@ export function compute_all_polymorph_stats(all_entries) {
     // Group entries by fractional composition (normalized stoichiometry)
     const composition_groups = new Map();
     for (const entry of all_entries) {
-        const fractional = get_fractional_composition(entry.composition);
-        const comp_key = Object.entries(fractional)
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([elem, frac]) => `${elem}:${frac.toFixed(6)}`)
-            .join(`|`);
+        const comp_key = get_fractional_composition_key(entry.composition);
         const group = composition_groups.get(comp_key) ?? [];
         if (group.length === 0)
             composition_groups.set(comp_key, group);
@@ -339,15 +378,19 @@ function apply_alpha_to_color(color, alpha) {
     // Handle existing rgba format
     if (color.includes(`rgba`))
         return color.replace(/[\d.]+\)$/, `${alpha})`);
-    if (color.includes(`rgb(`)) { // Convert rgb to rgba
+    if (color.includes(`rgb(`)) {
+        // Convert rgb to rgba
         return color.replace(/rgb\(/, `rgba(`).replace(/\)$/, `, ${alpha})`);
     }
-    const hex_match = color.match(/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/); // Convert hex to rgba
+    const hex_match = /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(color); // Convert hex to rgba
     if (hex_match) {
         let hex = hex_match[1];
         // Expand short form (e.g. "03F") to full form (e.g. "0033FF")
         if (hex.length === 3)
-            hex = [...hex].map((char) => char + char).join(``);
+            hex = hex
+                .split(``)
+                .map((char) => char + char)
+                .join(``);
         const red = parseInt(hex.slice(0, 2), 16);
         const green = parseInt(hex.slice(2, 4), 16);
         const blue = parseInt(hex.slice(4, 6), 16);
@@ -417,7 +460,8 @@ export function get_canvas_text_color(dark_mode, element) {
     if (typeof document === `undefined`)
         return fallback;
     const css_value = getComputedStyle(element ?? document.documentElement)
-        .getPropertyValue(`--text-color`)?.trim();
+        .getPropertyValue(`--text-color`)
+        ?.trim();
     // Check for unsupported CSS functions that canvas can't render
     return css_value && !/light-dark|var\(/i.test(css_value) ? css_value : fallback;
 }
@@ -461,8 +505,7 @@ function entry_has_temp_data(entry) {
 }
 // Check if entry has data at exact temperature T
 export function entry_has_temperature(entry, T) {
-    return entry_has_temp_data(entry) &&
-        (entry.temperatures?.includes(T) ?? false);
+    return entry_has_temp_data(entry) && (entry.temperatures?.includes(T) ?? false);
 }
 // Get energy at temperature T (throws if T not found - validate with entry_has_temperature first)
 export function get_energy_at_temperature(entry, T) {
@@ -623,6 +666,6 @@ export function get_entry_label(entry, elements) {
         pairs = pairs.sort(([el1], [el2]) => elements.indexOf(el1) - elements.indexOf(el2));
     }
     return pairs
-        .map(([el, amt]) => Math.abs(amt - 1) < 1e-6 ? el : `${el}${format_num(amt, `.2~`)}`)
+        .map(([el, amt]) => (Math.abs(amt - 1) < 1e-6 ? el : `${el}${format_num(amt, `.2~`)}`))
         .join(``);
 }

package/dist/convex-hull/thermodynamics.js

@@ -1,7 +1,7 @@
 import { count_atoms_in_composition, extract_formula_elements, sort_by_electronegativity, } from '../composition';
 import * as math from '../math';
 import { barycentric_to_ternary_xyz, barycentric_to_tetrahedral, composition_to_barycentric_3d, composition_to_barycentric_4d, composition_to_barycentric_nd, } from './barycentric-coords';
-import { get_arity, HULL_STABILITY_TOL, is_on_hull, is_unary_entry } from './types';
+import { get_arity, HULL_STABILITY_TOL, is_on_hull, is_unary_entry } from './helpers';
 // Track warned keys to avoid log spam on large datasets with repeated invalid keys
 const warned_keys = new Set();
 // Normalize convex hull composition keys by stripping oxidation states (e.g. "V4+" -> "V")
@@ -41,7 +41,7 @@ export function process_hull_entries(entries) {
     for (const entry of normalized_entries) {
         const stable = typeof entry.is_stable === `boolean`
             ? entry.is_stable
-            : (entry.e_above_hull ?? Infinity) <= 1e-6;
+            : (entry.e_above_hull ?? Infinity) <= HULL_STABILITY_TOL;
         (stable ? stable_entries : unstable_entries).push(entry);
     }
     // Extract unique element symbols from normalized compositions
@@ -120,9 +120,9 @@ export function calculate_e_above_hull(input, reference_entries) {
     }
     // 3. Compute formation energies
     const refs = find_lowest_energy_unary_refs(reference_entries);
-    const compute_e_form = (e) => typeof e.e_form_per_atom === `number`
-        ? e.e_form_per_atom
-        : compute_e_form_per_atom(e, refs);
+    const compute_e_form = (entry) => typeof entry.e_form_per_atom === `number`
+        ? entry.e_form_per_atom
+        : compute_e_form_per_atom(entry, refs);
     const interest_data = entries_of_interest.map((entry) => ({
         entry,
         e_form: compute_e_form(entry),
@@ -192,8 +192,8 @@ export function calculate_e_above_hull(input, reference_entries) {
                 continue;
             try {
                 const bary = composition_to_barycentric_3d(ref.composition, elements);
-                const p = barycentric_to_ternary_xyz(bary, e_form);
-                ref_points.push(p);
+                const point = barycentric_to_ternary_xyz(bary, e_form);
+                ref_points.push(point);
             }
             catch {
                 // Ignore invalid compositions
@@ -202,7 +202,7 @@ export function calculate_e_above_hull(input, reference_entries) {
         // Ensure corner points (pure elements default to e_form = 0)
         for (const el of elements) {
             const corner = barycentric_to_ternary_xyz(composition_to_barycentric_3d({ [el]: 1 }, elements), 0);
-            if (!ref_points.some((p) => Math.hypot(p.x - corner.x, p.y - corner.y, p.z - corner.z) < 1e-9)) {
+            if (!ref_points.some((point) => Math.hypot(point.x - corner.x, point.y - corner.y, point.z - corner.z) < 1e-9)) {
                 ref_points.push(corner);
             }
         }
@@ -216,9 +216,9 @@ export function calculate_e_above_hull(input, reference_entries) {
             }
             try {
                 const bary = composition_to_barycentric_3d(entry.composition, elements);
-                const p = barycentric_to_ternary_xyz(bary, e_form);
-                const z_hull = e_hull_at_xy(hull_models, p.x, p.y);
-                results[id] = z_hull === null ? NaN : Math.max(0, p.z - z_hull);
+                const point = barycentric_to_ternary_xyz(bary, e_form);
+                const z_hull = e_hull_at_xy(hull_models, point.x, point.y);
+                results[id] = z_hull === null ? NaN : Math.max(0, point.z - z_hull);
             }
             catch {
                 results[id] = NaN;
@@ -245,8 +245,8 @@ export function calculate_e_above_hull(input, reference_entries) {
         for (const el of elements) {
             const tet = barycentric_to_tetrahedral(composition_to_barycentric_4d({ [el]: 1 }, elements));
             const corner = { ...tet, w: 0 };
-            const dist = (p) => Math.hypot(p.x - corner.x, p.y - corner.y, p.z - corner.z, p.w);
-            if (!ref_points.some((p) => dist(p) < 1e-9))
+            const dist = (point) => Math.hypot(point.x - corner.x, point.y - corner.y, point.z - corner.z, point.w);
+            if (!ref_points.some((point) => dist(point) < 1e-9))
                 ref_points.push(corner);
         }
         const hull_tetrahedra = compute_lower_hull_4d(ref_points);
@@ -359,8 +359,7 @@ export function calculate_e_above_hull(input, reference_entries) {
         }
     }
     if (is_single) {
-        const id = entries_of_interest[0].entry_id ??
-            JSON.stringify(entries_of_interest[0].composition);
+        const id = entries_of_interest[0].entry_id ?? JSON.stringify(entries_of_interest[0].composition);
         return results[id];
     }
     return results;
@@ -404,8 +403,8 @@ export function get_convex_hull_stats(processed_entries, elements, max_arity = 4
     // Use reduce instead of Math.min/max(...arr) to avoid stack overflow on large datasets
     const energy_range = energies.length > 0
         ? {
-            min: energies.reduce((min, val) => val < min ? val : min, Infinity),
-            max: energies.reduce((max, val) => val > max ? val : max, -Infinity),
+            min: energies.reduce((min, val) => (val < min ? val : min), Infinity),
+            max: energies.reduce((max, val) => (val > max ? val : max), -Infinity),
             avg: energies.reduce((sum, val) => sum + val, 0) / energies.length,
         }
         : { min: 0, max: 0, avg: 0 };
@@ -414,7 +413,7 @@ export function get_convex_hull_stats(processed_entries, elements, max_arity = 4
         .filter((val) => typeof val === `number` && val >= 0);
     const hull_distance = hull_distances.length > 0
         ? {
-            max: hull_distances.reduce((max, val) => val > max ? val : max, -Infinity),
+            max: hull_distances.reduce((max, val) => (val > max ? val : max), -Infinity),
             avg: hull_distances.reduce((sum, val) => sum + val, 0) / hull_distances.length,
         }
         : { max: 0, avg: 0 };
@@ -500,14 +499,14 @@ export function process_hull_for_stats(entries, elements) {
 export function compute_lower_hull_2d(points) {
     // Andrew's monotone chain for lower hull
     // Sort by x then y
-    const sorted = [...points].sort((p1, p2) => (p1.x - p2.x) || (p1.y - p2.y));
+    const sorted = [...points].sort((p1, p2) => p1.x - p2.x || p1.y - p2.y);
     const lower = [];
     const cross = (o, a, b) => (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
-    for (const p of sorted) {
+    for (const point of sorted) {
         while (lower.length >= 2 &&
-            cross(lower[lower.length - 2], lower[lower.length - 1], p) <= 0)
+            cross(lower[lower.length - 2], lower[lower.length - 1], point) <= 0)
             lower.pop();
-        lower.push(p);
+        lower.push(point);
     }
     return lower;
 }
@@ -555,8 +554,7 @@ function compute_plane(p1, p2, p3) {
     const offset = -(normal.x * p1.x + normal.y * p1.y + normal.z * p1.z);
     return { normal, offset };
 }
-const point_plane_signed_distance = (plane, point) => plane.normal.x * point.x + plane.normal.y * point.y + plane.normal.z * point.z +
-    plane.offset;
+const point_plane_signed_distance = (plane, point) => plane.normal.x * point.x + plane.normal.y * point.y + plane.normal.z * point.z + plane.offset;
 const compute_centroid = (p1, p2, p3) => ({
     x: (p1.x + p2.x + p3.x) / 3,
     y: (p1.y + p2.y + p3.y) / 3,
@@ -658,7 +656,11 @@ function build_horizon(faces, visible_face_indices) {
     for (const face_idx of visible_face_indices) {
         const face = faces[face_idx];
         const [a, b, c] = face.vertices;
-        const edges = [[a, b], [b, c], [c, a]];
+        const edges = [
+            [a, b],
+            [b, c],
+            [c, a],
+        ];
         for (const [u, v] of edges) {
             const key = u < v ? `${u}|${v}` : `${v}|${u}`;
             if (!edge_count.has(key))
@@ -781,8 +783,7 @@ export const build_lower_hull_model = (faces) => faces.map((tri) => {
             return { a: 0, b: 0, c: (z1 + z2 + z3) / 3 };
         const a = (z1 * (y2 - y3) + z2 * (y3 - y1) + z3 * (y1 - y2)) / det;
         const b = (z1 * (x3 - x2) + z2 * (x1 - x3) + z3 * (x2 - x1)) / det;
-        const c = (z1 * (x2 * y3 - x3 * y2) + z2 * (x3 * y1 - x1 * y3) + z3 * (x1 * y2 - x2 * y1)) /
-            det;
+        const c = (z1 * (x2 * y3 - x3 * y2) + z2 * (x3 * y1 - x1 * y3) + z3 * (x1 * y2 - x2 * y1)) / det;
         return { a, b, c };
     })();
     const [min_x, _mx, max_x] = [p1.x, p2.x, p3.x].sort((a, b) => a - b);
@@ -820,22 +821,24 @@ function point_in_triangle_xy(model, x, y) {
 }
 export function e_hull_at_xy(models, x, y) {
     let z = null;
-    for (const m of models) {
-        if (x < m.min_x - 1e-9 || x > m.max_x + 1e-9 || y < m.min_y - 1e-9 || y > m.max_y + 1e-9)
+    for (const model of models) {
+        if (x < model.min_x - 1e-9 ||
+            x > model.max_x + 1e-9 ||
+            y < model.min_y - 1e-9 ||
+            y > model.max_y + 1e-9)
             continue;
-        if (!point_in_triangle_xy(m, x, y))
+        if (!point_in_triangle_xy(model, x, y))
             continue;
-        const z_face = m.a * x + m.b * y + m.c;
+        const z_face = model.a * x + model.b * y + model.c;
         z = z === null ? z_face : Math.min(z, z_face);
     }
     return z;
 }
-export const compute_e_above_hull_for_points = (points, models) => points.map((p) => {
-    const z_hull = e_hull_at_xy(models, p.x, p.y);
+export const compute_e_above_hull_for_points = (points, models) => points.map((point) => {
+    const z_hull = e_hull_at_xy(models, point.x, point.y);
     if (z_hull === null)
         return 0;
-    const e_above_hull = p.z - z_hull;
-    return e_above_hull > EPS ? e_above_hull : 0;
+    return point.z - z_hull;
 });
 const subtract_4d = (pt1, pt2) => ({
     x: pt1.x - pt2.x,
@@ -905,8 +908,7 @@ function compute_plane_4d(p1, p2, p3, p4) {
     const [x, y, z, w] = normal_components;
     const normal = normalize_4d({ x, y, z, w });
     // Guard against degenerate (nearly co-planar) points
-    const normal_magnitude = Math.abs(normal.x) + Math.abs(normal.y) + Math.abs(normal.z) +
-        Math.abs(normal.w);
+    const normal_magnitude = Math.abs(normal.x) + Math.abs(normal.y) + Math.abs(normal.z) + Math.abs(normal.w);
     if (normal_magnitude < EPS) {
         return { normal: { x: 0, y: 0, z: 0, w: 0 }, offset: 0 };
     }
@@ -989,8 +991,7 @@ function choose_initial_4_simplex(points) {
                 continue;
             const pa = points[idx_a];
             const pb = points[idx_b];
-            const dist_sq = (pa.x - pb.x) ** 2 + (pa.y - pb.y) ** 2 + (pa.z - pb.z) ** 2 +
-                (pa.w - pb.w) ** 2;
+            const dist_sq = (pa.x - pb.x) ** 2 + (pa.y - pb.y) ** 2 + (pa.z - pb.z) ** 2 + (pa.w - pb.w) ** 2;
             if (dist_sq > max_dist_sq) {
                 max_dist_sq = dist_sq;
                 idx_far_a = idx_a;
@@ -1033,7 +1034,9 @@ function choose_initial_4_simplex(points) {
     let idx_far_hyperplane = -1;
     let best_dist_hyperplane = -1;
     for (let idx = 0; idx < points.length; idx++) {
-        if (idx === idx_far_a || idx === idx_far_b || idx === idx_far_line ||
+        if (idx === idx_far_a ||
+            idx === idx_far_b ||
+            idx === idx_far_line ||
             idx === idx_far_plane)
             continue;
         const dist = Math.abs(point_plane_signed_distance_4d(plane0, points[idx]));
@@ -1096,7 +1099,12 @@ function build_horizon_4d(faces, visible_face_indices) {
         const face = faces[face_idx];
         const [a, b, c, d] = face.vertices;
         // Each tetrahedron face has 4 triangular ridges
-        const ridges = [[a, b, c], [a, b, d], [a, c, d], [b, c, d]];
+        const ridges = [
+            [a, b, c],
+            [a, b, d],
+            [a, c, d],
+            [b, c, d],
+        ];
         for (const ridge of ridges) {
             const sorted = ridge.slice().sort((x, y) => x - y);
             const key = sorted.join(`|`);
@@ -1252,8 +1260,8 @@ function point_in_tetrahedron_3d(p0, p1, p2, p3, point) {
     }
     // Check if inside: all barycentric coords must be >= 0 and sum to 1
     const eps_bary = -1e-9;
-    const inside = bary.every((l) => l >= eps_bary) &&
-        Math.abs(bary.reduce((s, l) => s + l, 0) - 1) < 1e-6;
+    const inside = bary.every((coord) => coord >= eps_bary) &&
+        Math.abs(bary.reduce((sum, coord) => sum + coord, 0) - 1) < 1e-6;
     return { inside, bary };
 }
 const build_tetrahedron_models = (hull_tetrahedra) => hull_tetrahedra.map((tet) => {
@@ -1286,17 +1294,19 @@ export const compute_e_above_hull_4d = (points, hull_tetrahedra) => {
         let hull_w = null;
         for (const model of models) {
             // Fast bounding box prefilter
-            if (x < model.min_x - EPS || x > model.max_x + EPS ||
-                y < model.min_y - EPS || y > model.max_y + EPS ||
-                z < model.min_z - EPS || z > model.max_z + EPS)
+            if (x < model.min_x - EPS ||
+                x > model.max_x + EPS ||
+                y < model.min_y - EPS ||
+                y > model.max_y + EPS ||
+                z < model.min_z - EPS ||
+                z > model.max_z + EPS)
                 continue;
             // Check if point's (x,y,z) is inside the 3D projection of the tetrahedron
             const { inside, bary } = point_in_tetrahedron_3d(model.vertices_3d[0], model.vertices_3d[1], model.vertices_3d[2], model.vertices_3d[3], { x, y, z });
             if (inside) {
                 // Compute w on the hull at this (x,y,z) using barycentric interpolation
                 const [p0, p1, p2, p3] = model.vertices;
-                const w_on_hull = bary[0] * p0.w + bary[1] * p1.w + bary[2] * p2.w +
-                    bary[3] * p3.w;
+                const w_on_hull = bary[0] * p0.w + bary[1] * p1.w + bary[2] * p2.w + bary[3] * p3.w;
                 hull_w = hull_w === null ? w_on_hull : Math.min(hull_w, w_on_hull);
             }
         }
@@ -1304,8 +1314,7 @@ export const compute_e_above_hull_4d = (points, hull_tetrahedra) => {
         // composition domain. Return NaN to indicate invalid input.
         if (hull_w === null)
             return NaN;
-        const distance = w - hull_w;
-        return distance > EPS ? distance : 0;
+        return w - hull_w;
     });
 };
 // --- N-Dimensional Convex Hull (for 5+ element systems) ---
@@ -1343,10 +1352,7 @@ function compute_hyperplane_nd(points) {
     const normal_components = [];
     for (let col = 0; col < dim; col++) {
         // Build (N-1)×(N-1) submatrix by removing column col
-        const submatrix = edges.map((row) => [
-            ...row.slice(0, col),
-            ...row.slice(col + 1),
-        ]);
+        const submatrix = edges.map((row) => [...row.slice(0, col), ...row.slice(col + 1)]);
         const sign = col % 2 === 0 ? 1 : -1;
         normal_components.push(sign * math.det_nxn(submatrix));
     }
@@ -1741,7 +1747,6 @@ export function compute_e_above_hull_nd(query_points, hull_facets, all_points) {
         // would falsely imply the point is stable/on-hull).
         if (hull_energy === null)
             return NaN;
-        const distance = energy - hull_energy;
-        return distance > EPS ? distance : 0;
+        return energy - hull_energy;
     });
 }

package/dist/convex-hull/types.d.ts

@@ -3,12 +3,14 @@ import type { ShowControlsProp } from '../controls';
 import type { ElementSymbol } from '../element';
 import type { Vec3 } from '../math';
 import type { Sides } from '../plot';
+import type { Rect } from '../plot/layout';
 export interface PhaseData {
     composition: CompositionType;
     energy: number;
     entry_id?: string;
     e_above_hull?: number;
     is_stable?: boolean;
+    exclude_from_hull?: boolean;
     energy_per_atom?: number;
     e_form_per_atom?: number;
     reduced_formula?: string;
@@ -38,7 +40,8 @@ export interface Point2D {
 export interface Point3D extends Point2D {
     z: number;
 }
-export type MarkerSymbol = `circle` | `star` | `triangle` | `cross` | `diamond` | `square` | `wye`;
+export type MarkerSymbol = // Marker symbol types for convex hull entries
+`circle` | `star` | `triangle` | `cross` | `diamond` | `square` | `wye`;
 export type HullFaceColorMode = `uniform` | `formation_energy` | `dominant_element` | `facet_index`;
 export declare const HULL_FACE_COLOR_MODES: readonly HullFaceColorMode[];
 export interface ConvexHullEntry extends PhaseData, Point3D {
@@ -93,6 +96,11 @@ export interface ConvexHullTriangle {
     normal: Point3D;
     centroid: Point3D;
 }
+export interface LabelPlacement {
+    x: number;
+    y: number;
+    rect: Rect;
+}
 export interface HoverData3D<T = ConvexHullEntry> {
     entry: T;
     position: {
@@ -123,19 +131,6 @@ export interface PhaseStats {
     max_arity: number;
 }
 export type PhaseArityField = Extract<keyof PhaseStats, `unary` | `binary` | `ternary` | `quaternary` | `quinary_plus`>;
-export declare const HULL_STABILITY_TOL = 0.000001;
-export declare const is_on_hull: (entry: PhaseData, tol?: number) => boolean;
-export declare const get_arity: (entry: PhaseData) => number;
-export declare const is_unary_entry: (entry: PhaseData) => boolean;
-export declare const is_binary_entry: (entry: PhaseData) => boolean;
-export declare const is_ternary_entry: (entry: PhaseData) => boolean;
-export declare const is_quaternary_entry: (entry: PhaseData) => boolean;
-export declare const is_quinary_entry: (entry: PhaseData) => boolean;
-export declare const is_senary_entry: (entry: PhaseData) => boolean;
-export declare const is_septenary_entry: (entry: PhaseData) => boolean;
-export declare const is_octonary_entry: (entry: PhaseData) => boolean;
-export declare const is_nonary_entry: (entry: PhaseData) => boolean;
-export declare const is_denary_entry: (entry: PhaseData) => boolean;
 export interface HighlightStyle {
     effect?: `pulse` | `glow` | `size` | `color` | `both`;
     color?: string;

package/dist/convex-hull/types.js

@@ -4,23 +4,6 @@ export const HULL_FACE_COLOR_MODES = [
     `dominant_element`,
     `facet_index`,
 ];
-// Tolerance for classifying a phase as on the convex hull (eV/atom)
-export const HULL_STABILITY_TOL = 1e-6;
-// Check if entry is on the convex hull (stable or e_above_hull ≈ 0)
-export const is_on_hull = (entry, tol = HULL_STABILITY_TOL) => entry.is_stable === true ||
-    (typeof entry.e_above_hull === `number` && entry.e_above_hull < tol);
-// Arity helpers (inlined from former arity.ts)
-export const get_arity = (entry) => Object.values(entry.composition).filter((count) => count > 0).length;
-export const is_unary_entry = (entry) => get_arity(entry) === 1;
-export const is_binary_entry = (entry) => get_arity(entry) === 2;
-export const is_ternary_entry = (entry) => get_arity(entry) === 3;
-export const is_quaternary_entry = (entry) => get_arity(entry) === 4;
-export const is_quinary_entry = (entry) => get_arity(entry) === 5;
-export const is_senary_entry = (entry) => get_arity(entry) === 6;
-export const is_septenary_entry = (entry) => get_arity(entry) === 7;
-export const is_octonary_entry = (entry) => get_arity(entry) === 8;
-export const is_nonary_entry = (entry) => get_arity(entry) === 9;
-export const is_denary_entry = (entry) => get_arity(entry) === 10;
 // --- Gas Phase Thermodynamics ---
 // Default temperature (Kelvin) for gas corrections when no temperature is specified
 export const DEFAULT_GAS_TEMP = 300;