matterviz 0.3.6 → 0.4.0

package/dist/convex-hull/TemperatureSlider.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+  import { tooltip } from 'svelte-multiselect/attachments'
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  let {
+    available_temperatures,
+    temperature = $bindable(),
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
+    available_temperatures: number[]
+    temperature: number
+  } = $props()
+
+  // Local preview state for smooth slider interaction without causing full re-renders
+  let preview_index = $state<number | null>(null)
+  let last_update_time = 0
+  const THROTTLE_MS = 100
+
+  const temp_index = $derived(
+    Math.max(0, available_temperatures.indexOf(temperature)),
+  )
+  const display_index = $derived(preview_index ?? temp_index)
+  const display_temp = $derived(available_temperatures[display_index] ?? temperature)
+
+  function handle_slider_input(
+    event: Event & { currentTarget: HTMLInputElement },
+  ): void {
+    const new_index = Number(event.currentTarget.value)
+    preview_index = new_index
+    // Throttle parent updates during drag to prevent scene flashing
+    const now = Date.now()
+    if (now - last_update_time >= THROTTLE_MS) {
+      last_update_time = now
+      temperature = available_temperatures[new_index] ?? temperature
+    }
+  }
+
+  function handle_slider_end(
+    event: Event & { currentTarget: HTMLInputElement },
+  ): void {
+    const new_temp = available_temperatures[Number(event.currentTarget.value)]
+    if (new_temp !== undefined) temperature = new_temp
+    preview_index = null
+  }
+
+  function set_closest_temp(value: number): void {
+    temperature = available_temperatures.reduce(
+      (prev, curr) => (Math.abs(curr - value) < Math.abs(prev - value) ? curr : prev),
+      temperature,
+    )
+  }
+</script>
+
+<div
+  {...rest}
+  class="temperature-slider {rest.class ?? ``}"
+  {@attach tooltip({ content: `Temperature for G(T) free energies` })}
+>
+  <label class="temp-label">
+    <input
+      type="number"
+      class="temp-input"
+      value={display_temp}
+      min={available_temperatures[0] ?? 0}
+      max={available_temperatures.at(-1) ?? 1000}
+      onchange={(evt) => set_closest_temp(+evt.currentTarget.value)}
+      aria-label="Temperature (Kelvin)"
+    />
+    <span>K</span>
+  </label>
+  {#if available_temperatures.length > 0}
+    <div class="slider-wrapper">
+      <span class="temp-range">
+        {available_temperatures[0]}–{available_temperatures.at(-1)} K
+      </span>
+      <input
+        type="range"
+        min="0"
+        max={available_temperatures.length - 1}
+        value={display_index}
+        oninput={handle_slider_input}
+        onchange={handle_slider_end}
+        onmouseup={handle_slider_end}
+        ontouchend={handle_slider_end}
+        aria-label="Temperature (Kelvin)"
+      />
+    </div>
+  {/if}
+</div>
+
+<style>
+  .temperature-slider {
+    position: absolute;
+    top: calc(1ex + 50px);
+    right: 1ex;
+    z-index: 2;
+    pointer-events: auto;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 4px;
+    background: color-mix(in srgb, var(--hull-bg, transparent) 80%, transparent);
+    padding: 3px 5px;
+    border-radius: var(--border-radius, 6pt);
+    backdrop-filter: blur(2px);
+  }
+  .slider-wrapper {
+    display: flex;
+    place-items: center;
+    justify-content: var(--slider-justify, center);
+    line-height: 1;
+  }
+  .temperature-slider input[type='range'] {
+    writing-mode: vertical-lr;
+    direction: rtl;
+  }
+  .temp-label {
+    display: flex;
+    align-items: center;
+    gap: 2px;
+  }
+  .temp-input {
+    border: 1px solid color-mix(in srgb, currentColor 5%, transparent);
+    border-radius: 3px;
+    background: transparent;
+    text-align: center;
+  }
+  .temp-input::-webkit-outer-spin-button,
+  .temp-input::-webkit-inner-spin-button {
+    -webkit-appearance: none;
+    margin: 0;
+  }
+  .temp-range {
+    font-size: 0.7em;
+    opacity: 0.7;
+    white-space: nowrap;
+    writing-mode: vertical-rl;
+    transform: rotate(180deg);
+  }
+</style>

package/dist/convex-hull/TemperatureSlider.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { HTMLAttributes } from 'svelte/elements';
+type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
+    available_temperatures: number[];
+    temperature: number;
+};
+declare const TemperatureSlider: import("svelte").Component<$$ComponentProps, {}, "temperature">;
+type TemperatureSlider = ReturnType<typeof TemperatureSlider>;
+export default TemperatureSlider;

package/dist/convex-hull/barycentric-coords.d.ts

@@ -0,0 +1,18 @@
+import type { ElementSymbol } from '../element';
+import type { Point3D, Vec3 } from '../math';
+import type { ConvexHullEntry, PhaseData } from './types';
+export declare const TRIANGLE_VERTICES: readonly [readonly [1, 0], readonly [0.5, number], readonly [0, 0]];
+export declare function composition_to_barycentric_3d(composition: Record<string, number>, elements: ElementSymbol[]): Vec3;
+export declare function barycentric_to_ternary_xy(barycentric: Vec3): [number, number];
+export declare function barycentric_to_ternary_xyz(barycentric: Vec3, formation_energy: number): Point3D;
+export declare function get_triangle_centroid(): Point3D;
+export declare function calculate_face_normal(p1: Point3D, p2: Point3D, p3: Point3D): Point3D;
+export declare const calculate_face_centroid: (p1: Point3D, p2: Point3D, p3: Point3D) => Point3D;
+export declare function get_ternary_3d_coordinates(entries: PhaseData[], elements: ElementSymbol[], el_refs?: Record<string, PhaseData>): ConvexHullEntry[];
+export declare function get_triangle_edges(): [Point3D, Point3D][];
+export declare function get_triangle_vertical_edges(min_z: number, max_z: number): [Point3D, Point3D][];
+export declare function composition_to_barycentric_nd(composition: Record<string, number>, elements: ElementSymbol[]): number[];
+export declare const TETRAHEDRON_VERTICES: readonly [readonly [1, 0, 0], readonly [0.5, number, 0], readonly [0.5, number, number], readonly [0, 0, 0]];
+export declare function composition_to_barycentric_4d(composition: Record<string, number>, elements: ElementSymbol[]): number[];
+export declare function barycentric_to_tetrahedral(barycentric: number[]): Point3D;
+export declare function compute_4d_coords(entries: PhaseData[], elements: ElementSymbol[]): ConvexHullEntry[];

package/dist/convex-hull/barycentric-coords.js

@@ -0,0 +1,182 @@
+import { compute_e_form_per_atom, find_lowest_energy_unary_refs } from './thermodynamics';
+import { is_unary_entry } from './helpers';
+// --- Ternary coordinates ---
+export const TRIANGLE_VERTICES = [
+    [1, 0],
+    [0.5, Math.sqrt(3) / 2],
+    [0, 0],
+];
+export function composition_to_barycentric_3d(composition, elements) {
+    if (elements.length !== 3) {
+        throw new Error(`Ternary system requires exactly 3 elements, got ${elements.length}`);
+    }
+    const amounts = elements.map((el) => composition[el] || 0);
+    const total = amounts.reduce((sum, amt) => sum + amt, 0);
+    if (total === 0) {
+        throw new Error(`Composition has no elements from the ternary system: ${elements.join(`-`)}`);
+    }
+    const normalized = amounts.map((amount) => amount / total);
+    return [normalized[0], normalized[1], normalized[2]];
+}
+// map barycentric coordinates to triangular 2D coordinates
+export function barycentric_to_ternary_xy(barycentric) {
+    const [v0, v1, v2] = TRIANGLE_VERTICES;
+    const [a, b, c] = barycentric;
+    const x = v0[0] * a + v1[0] * b + v2[0] * c;
+    const y = v0[1] * a + v1[1] * b + v2[1] * c;
+    return [x, y];
+}
+// map barycentric coordinates to ternary 3D coordinates
+export function barycentric_to_ternary_xyz(barycentric, formation_energy) {
+    const [x, y] = barycentric_to_ternary_xy(barycentric);
+    return { x, y, z: formation_energy };
+}
+export function get_triangle_centroid() {
+    const [v0, v1, v2] = TRIANGLE_VERTICES;
+    const centroid_x = (v0[0] + v1[0] + v2[0]) / 3;
+    const centroid_y = (v0[1] + v1[1] + v2[1]) / 3;
+    return { x: centroid_x, y: centroid_y, z: 0 };
+}
+export function calculate_face_normal(p1, p2, p3) {
+    const edge1 = { x: p2.x - p1.x, y: p2.y - p1.y, z: p2.z - p1.z };
+    const edge2 = { x: p3.x - p1.x, y: p3.y - p1.y, z: p3.z - p1.z };
+    const nx = edge1.y * edge2.z - edge1.z * edge2.y;
+    const ny = edge1.z * edge2.x - edge1.x * edge2.z;
+    const nz = edge1.x * edge2.y - edge1.y * edge2.x;
+    const magnitude = Math.hypot(nx, ny, nz);
+    if (magnitude === 0)
+        return { x: 0, y: 0, z: 1 };
+    return { x: nx / magnitude, y: ny / magnitude, z: nz / magnitude };
+}
+export const calculate_face_centroid = (p1, p2, p3) => ({
+    x: (p1.x + p2.x + p3.x) / 3,
+    y: (p1.y + p2.y + p3.y) / 3,
+    z: (p1.z + p2.z + p3.z) / 3,
+});
+export function get_ternary_3d_coordinates(entries, elements, el_refs) {
+    if (elements.length !== 3) {
+        throw new Error(`Ternary convex hull requires exactly 3 elements, got ${elements.length}`);
+    }
+    // Filter to entries within the ternary system first (use Set for O(1) lookups)
+    const element_set = new Set(elements);
+    const within_system = entries.filter((entry) => Object.keys(entry.composition).every((el) => element_set.has(el)));
+    if (within_system.length === 0) {
+        throw new Error(`No entries found within the ternary system: ${elements.join(`-`)}`);
+    }
+    // Check if we have formation energies - provide detailed diagnostics if missing
+    const entries_with_e_form = within_system.filter((entry) => typeof entry.e_form_per_atom === `number` && Number.isFinite(entry.e_form_per_atom));
+    // If none have e_form_per_atom, try to derive them using refs; only error if we can't
+    const refs = el_refs ?? find_lowest_energy_unary_refs(entries);
+    if (entries_with_e_form.length === 0) {
+        const missing_refs = elements.filter((el) => !refs[el]);
+        if (missing_refs.length > 0) {
+            throw new Error([
+                `Ternary convex hull requires formation energies (e_form_per_atom) for z-axis positioning, but none of the ${within_system.length} entries in the ${elements.join(`-`)} system have this field.`,
+                `\nCannot compute formation energies because elemental references are missing for: ${missing_refs.join(`, `)}.`,
+                `To fix: Ensure your dataset includes stable unary (single-element) entries for each element.`,
+            ].join(`\n`));
+        }
+        // proceed; values will be computed during mapping below
+    }
+    // Map entries to ternary plot coordinates
+    const result = within_system.map((entry) => {
+        const barycentric = composition_to_barycentric_3d(entry.composition, elements);
+        const e_form_per_atom = typeof entry.e_form_per_atom === `number` && Number.isFinite(entry.e_form_per_atom)
+            ? entry.e_form_per_atom
+            : (compute_e_form_per_atom(entry, refs) ?? NaN);
+        const xyz = barycentric_to_ternary_xyz(barycentric, e_form_per_atom);
+        const is_element = is_unary_entry(entry);
+        return { ...entry, ...xyz, is_element };
+    });
+    return result;
+}
+export function get_triangle_edges() {
+    const [v0, v1, v2] = TRIANGLE_VERTICES.map(([x, y]) => ({ x, y, z: 0 }));
+    return [
+        [v0, v1],
+        [v1, v2],
+        [v2, v0],
+    ];
+}
+export function get_triangle_vertical_edges(min_z, max_z) {
+    const vertices = TRIANGLE_VERTICES.map(([x, y]) => ({ x, y, z: 0 }));
+    return vertices.map((vertex) => [
+        { ...vertex, z: min_z },
+        { ...vertex, z: max_z },
+    ]);
+}
+// --- N-dimensional barycentric coordinates (for 5+ element systems) ---
+// Convert composition to N-dimensional barycentric coordinates
+// Returns array of length N where coords sum to 1 (all N coords are explicit)
+// The last coordinate represents formation energy when used in hull calculations
+export function composition_to_barycentric_nd(composition, elements) {
+    const n = elements.length;
+    if (n < 2) {
+        throw new Error(`Barycentric coordinates require at least 2 elements, got ${n}`);
+    }
+    // NaN and undefined/missing elements are treated as 0
+    const amounts = elements.map((el) => {
+        const val = composition[el];
+        return val == null || Number.isNaN(val) ? 0 : val;
+    });
+    let total = 0;
+    const negative = [];
+    for (let idx = 0; idx < amounts.length; idx++) {
+        if (amounts[idx] < 0)
+            negative.push(elements[idx]);
+        else
+            total += amounts[idx];
+    }
+    if (negative.length > 0) {
+        throw new Error(`Composition contains negative amounts for: ${negative.join(`, `)}`);
+    }
+    if (total === 0) {
+        throw new Error(`Composition has no elements from the system: ${elements.join(`-`)}`);
+    }
+    return amounts.map((amount) => amount / total);
+}
+// --- Quaternary coordinates ---
+export const TETRAHEDRON_VERTICES = [
+    [1, 0, 0],
+    [0.5, Math.sqrt(3) / 2, 0],
+    [0.5, Math.sqrt(3) / 6, Math.sqrt(6) / 3],
+    [0, 0, 0],
+];
+export function composition_to_barycentric_4d(composition, elements) {
+    if (elements.length !== 4) {
+        throw new Error(`Quaternary barycentric coordinates require exactly 4 elements`);
+    }
+    const amounts = elements.map((el) => composition[el] || 0);
+    const total = amounts.reduce((sum, amount) => sum + amount, 0);
+    if (total === 0) {
+        throw new Error(`Composition has no elements from the quaternary system: ${elements.join(`-`)}`);
+    }
+    return amounts.map((amount) => amount / total);
+}
+// map barycentric coordinates to tetrahedral 3D coordinates
+export function barycentric_to_tetrahedral(barycentric) {
+    if (barycentric.length !== 4) {
+        throw new Error(`Tetrahedral coordinates require exactly 4D barycentric input, got ${barycentric.length}`);
+    }
+    let [x, y, z] = [0, 0, 0];
+    for (let idx = 0; idx < 4; idx++) {
+        x += barycentric[idx] * TETRAHEDRON_VERTICES[idx][0];
+        y += barycentric[idx] * TETRAHEDRON_VERTICES[idx][1];
+        z += barycentric[idx] * TETRAHEDRON_VERTICES[idx][2];
+    }
+    return { x, y, z };
+}
+export function compute_4d_coords(entries, elements) {
+    if (elements.length !== 4) {
+        throw new Error(`Quaternary convex hull requires exactly 4 elements`);
+    }
+    // Use Set for O(1) lookups instead of O(n) includes
+    const element_set = new Set(elements);
+    const within_system = entries.filter((entry) => Object.keys(entry.composition).every((el) => element_set.has(el)));
+    return within_system.map((entry) => {
+        const barycentric_4d = composition_to_barycentric_4d(entry.composition, elements);
+        const tetrahedral = barycentric_to_tetrahedral(barycentric_4d);
+        const is_element = is_unary_entry(entry);
+        return { ...entry, ...tetrahedral, is_element };
+    });
+}

package/dist/convex-hull/demo-temperature.d.ts

@@ -0,0 +1,6 @@
+import type { PhaseData } from './types';
+export declare const demo_temperatures: number[];
+type Composition = Record<string, number>;
+export declare function make_demo_phase(composition: Composition, seed: number, entropy_boost?: number): PhaseData;
+export declare const create_temp_ternary_entries_li_fe_o: () => PhaseData[];
+export {};

package/dist/convex-hull/demo-temperature.js

@@ -0,0 +1,38 @@
+export const demo_temperatures = Array.from({ length: 13 }, (_, idx) => 300 + idx * 100);
+function seeded_random(seed) {
+    const x_val = Math.sin(seed * 9999) * 10000;
+    return x_val - Math.floor(x_val);
+}
+export function make_demo_phase(composition, seed, entropy_boost = 0) {
+    const n_elements = Object.keys(composition).length;
+    const energy = -0.3 * n_elements - seeded_random(seed) * 0.5;
+    const entropy_coef = 0.5 + n_elements * 0.3 + seeded_random(seed + 1) * 2 + entropy_boost;
+    return {
+        composition,
+        energy,
+        temperatures: demo_temperatures,
+        free_energies: demo_temperatures.map((temp_kelvin) => energy +
+            entropy_coef * temp_kelvin * 0.0001 -
+            0.00005 * temp_kelvin * Math.log(temp_kelvin)),
+    };
+}
+export const create_temp_ternary_entries_li_fe_o = () => [
+    ...[`Li`, `Fe`, `O`].map((element, idx) => make_demo_phase({ [element]: 1 }, idx)),
+    ...[
+        [`Li`, `Fe`],
+        [`Li`, `O`],
+        [`Fe`, `O`],
+    ].flatMap(([element_a, element_b], idx) => [0.33, 0.5, 0.67].flatMap((fraction, jdx) => [
+        make_demo_phase({ [element_a]: fraction, [element_b]: 1 - fraction }, 100 + idx * 10 + jdx),
+        make_demo_phase({ [element_a]: fraction, [element_b]: 1 - fraction }, 200 + idx * 10 + jdx, 3),
+    ])),
+    ...[
+        { Li: 0.33, Fe: 0.33, O: 0.34 },
+        { Li: 0.5, Fe: 0.25, O: 0.25 },
+        { Li: 0.25, Fe: 0.5, O: 0.25 },
+        { Li: 0.25, Fe: 0.25, O: 0.5 },
+    ].flatMap((composition, idx) => [
+        make_demo_phase(composition, 300 + idx),
+        make_demo_phase(composition, 400 + idx, 4),
+    ]),
+];

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

@@ -0,0 +1,16 @@
+import type { GasAnalysis, GasSpecies, GasThermodynamicsConfig, GasThermodynamicsProvider, PhaseData } from './types';
+import type { ElementSymbol } from '../element';
+export declare const R_EV_PER_K = 0.00008617333262;
+export declare const P_REF = 1;
+export declare const DEFAULT_ELEMENT_TO_GAS: Readonly<Partial<Record<ElementSymbol, GasSpecies>>>;
+export declare const GAS_STOICHIOMETRY: Readonly<Record<GasSpecies, Partial<Record<ElementSymbol, number>>>>;
+export declare const create_default_gas_provider: () => GasThermodynamicsProvider;
+export declare function get_default_gas_provider(): GasThermodynamicsProvider;
+export declare function compute_gas_chemical_potential(provider: GasThermodynamicsProvider, gas: GasSpecies, T: number, P: number): number;
+export declare function compute_element_chemical_potential(provider: GasThermodynamicsProvider, gas: GasSpecies, element: ElementSymbol, T: number, P: number): number;
+export declare function analyze_gas_data(entries: PhaseData[], config: GasThermodynamicsConfig): GasAnalysis;
+export declare function get_effective_pressures(config: GasThermodynamicsConfig): Record<GasSpecies, number>;
+export declare function compute_gas_correction(entry: PhaseData, config: GasThermodynamicsConfig, T: number, pressures: Record<GasSpecies, number>): number;
+export declare function apply_gas_corrections(entries: PhaseData[], config: GasThermodynamicsConfig | undefined, T: number): PhaseData[];
+export declare const format_chemical_potential: (mu: number, decimals?: number) => string;
+export declare function format_pressure(P: number): string;