matterviz 0.3.1 → 0.3.3

package/dist/convex-hull/helpers.js

@@ -1,33 +1,47 @@
+import { get_d3_interpolator } from '../colors';
 import { ELEM_SYMBOL_TO_NAME } from '../composition';
 import { format_fractional, format_num, symbol_map } from '../labels';
 import { scaleSequential } from 'd3-scale';
-import * as d3_sc from 'd3-scale-chromatic';
 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);
     const hi_raw = Math.max(...hull_distances, 0.1);
     const hi = Math.max(hi_raw, lo + 1e-6);
-    // Cast needed: d3-scale-chromatic module has non-interpolator exports (e.g. `default`)
-    const interpolator = d3_sc[color_scale] ||
-        d3_sc.interpolateViridis;
+    const interpolator = get_d3_interpolator(color_scale);
     return scaleSequential(interpolator).domain([lo, hi]);
 }
 // Point color resolver (shared)
 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)
@@ -57,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.
@@ -78,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`;
@@ -100,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`;
@@ -124,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;
     }
@@ -146,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:
@@ -261,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) {
@@ -269,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))) {
@@ -286,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);
@@ -341,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);
@@ -419,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;
 }
@@ -463,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) {
@@ -625,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/index.d.ts

@@ -11,6 +11,7 @@ export { default as ConvexHullControls } from './ConvexHullControls.svelte';
 export { default as ConvexHullInfoPane } from './ConvexHullInfoPane.svelte';
 export { default as ConvexHullStats } from './ConvexHullStats.svelte';
 export { default as ConvexHullTooltip } from './ConvexHullTooltip.svelte';
+export * from './demo-temperature';
 export * from './gas-thermodynamics';
 export { default as GasPressureControls } from './GasPressureControls.svelte';
 export * from './helpers';

package/dist/convex-hull/index.js

@@ -7,6 +7,7 @@ export { default as ConvexHullControls } from './ConvexHullControls.svelte';
 export { default as ConvexHullInfoPane } from './ConvexHullInfoPane.svelte';
 export { default as ConvexHullStats } from './ConvexHullStats.svelte';
 export { default as ConvexHullTooltip } from './ConvexHullTooltip.svelte';
+export * from './demo-temperature';
 export * from './gas-thermodynamics';
 export { default as GasPressureControls } from './GasPressureControls.svelte';
 export * from './helpers';

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

@@ -1,31 +1,18 @@
 import type { ElementSymbol } from '../element';
-import type { ConvexHullTriangle, PhaseData, Point2D, Point3D, ProcessedPhaseData } from './types';
+import type { ConvexHullEntry, ConvexHullTriangle, PhaseData, PhaseStats, Point2D, Point3D, ProcessedPhaseData } from './types';
 export declare function normalize_hull_composition_keys(composition: Record<string, number>): Partial<Record<ElementSymbol, number>>;
 export declare function process_hull_entries(entries: PhaseData[]): ProcessedPhaseData;
 export declare function compute_e_form_per_atom(entry: PhaseData, el_refs: Record<string, PhaseData>): number | null;
 export declare function find_lowest_energy_unary_refs(entries: PhaseData[]): Record<string, PhaseData>;
 export declare function calculate_e_above_hull(entry: PhaseData, reference_entries: PhaseData[]): number;
 export declare function calculate_e_above_hull(entries: PhaseData[], reference_entries: PhaseData[]): Record<string, number>;
-export declare function get_convex_hull_stats(processed_entries: PhaseData[], elements: ElementSymbol[], max_arity: 3 | 4): {
-    total: number;
-    unary: number;
-    binary: number;
-    ternary: number;
-    quaternary: number;
-    stable: number;
-    unstable: number;
-    energy_range: {
-        min: number;
-        max: number;
-        avg: number;
-    };
-    hull_distance: {
-        max: number;
-        avg: number;
-    };
-    elements: number;
-    chemical_system: string;
-} | null;
+export declare function get_convex_hull_stats(processed_entries: PhaseData[], elements: ElementSymbol[], max_arity?: number): PhaseStats | null;
+export interface HighDimHullResult {
+    stable_entries: ConvexHullEntry[];
+    unstable_entries: ConvexHullEntry[];
+    phase_stats: PhaseStats | null;
+}
+export declare function process_hull_for_stats(entries: PhaseData[], elements?: ElementSymbol[]): HighDimHullResult | null;
 export declare function compute_lower_hull_2d(points: Point2D[]): Point2D[];
 export declare function interpolate_hull_2d(hull: Point2D[], x: number): number | null;
 export declare function compute_quickhull_triangles(points: Point3D[]): ConvexHullTriangle[];