matterviz 0.3.4 → 0.3.6

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

@@ -0,0 +1,6 @@
+export { default as ChemPotDiagram } from './ChemPotDiagram.svelte'
+export { default as ChemPotDiagram2D } from './ChemPotDiagram2D.svelte'
+export { default as ChemPotDiagram3D } from './ChemPotDiagram3D.svelte'
+export { compute_chempot_async } from './async-compute.svelte'
+export { compute_chempot_diagram, get_ternary_combinations } from './compute'
+export * from './types'

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

@@ -0,0 +1,56 @@
+// Event/pointer normalization for hover tooltips.
+// Handles DOM events and Threlte/Three.js event wrappers (nativeEvent, srcEvent).
+const is_pointer_like_event = (event_val: unknown): event_val is PointerEvent | MouseEvent =>
+  (typeof PointerEvent !== `undefined` && event_val instanceof PointerEvent) ||
+  (typeof MouseEvent !== `undefined` && event_val instanceof MouseEvent)
+
+export function get_pointer_coords(
+  raw_event: unknown,
+): { clientX: number; clientY: number } | null {
+  if (is_pointer_like_event(raw_event)) {
+    return raw_event
+  }
+  if (!raw_event || typeof raw_event !== `object`) return null
+  const event_obj = raw_event as {
+    nativeEvent?: unknown
+    srcEvent?: unknown
+    clientX?: number
+    clientY?: number
+  }
+  if (is_pointer_like_event(event_obj.nativeEvent)) {
+    return event_obj.nativeEvent
+  }
+  if (is_pointer_like_event(event_obj.srcEvent)) {
+    return event_obj.srcEvent
+  }
+  const client_x = event_obj.clientX
+  const client_y = event_obj.clientY
+  if (typeof client_x === `number` && typeof client_y === `number`) {
+    return { clientX: client_x, clientY: client_y }
+  }
+  return null
+}
+
+/** Convert pointer event to container-relative coords for tooltip placement. */
+export function get_hover_pointer(
+  raw_event: unknown,
+  container_rect: DOMRect | null | undefined,
+): { x: number; y: number } | null {
+  const pointer_event = get_pointer_coords(raw_event)
+  if (!pointer_event) return null
+  const offset_x = container_rect?.left ?? 0
+  const offset_y = container_rect?.top ?? 0
+  const x = pointer_event.clientX - offset_x + 4
+  const y = pointer_event.clientY - offset_y + 4
+  return { x, y }
+}
+
+/** Add hover pointer to an info object for tooltip placement. */
+export function with_hover_pointer<T extends { pointer?: { x: number; y: number } }>(
+  info: Omit<T, `pointer`>,
+  raw_event: unknown,
+  container_rect: DOMRect | null | undefined,
+): T {
+  const pointer = get_hover_pointer(raw_event, container_rect)
+  return { ...info, pointer: pointer ?? undefined } as T
+}

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

@@ -0,0 +1,77 @@
+import {
+  analyze_temperature_data,
+  filter_entries_at_temperature,
+} from '$lib/convex-hull/helpers'
+import type { PhaseData } from '$lib/convex-hull/types'
+import type { ChemPotDiagramConfig } from './types'
+import { CHEMPOT_DEFAULTS } from './types'
+
+interface TempFilterProps {
+  interpolate_temperature?: boolean
+  max_interpolation_gap?: number
+}
+
+interface ResolvedTempFilterOptions {
+  interpolate: boolean
+  max_interpolation_gap: number
+}
+
+export interface TempFilterPayload {
+  has_temp_data: boolean
+  available_temperatures: number[]
+  temp_filtered_entries: PhaseData[]
+}
+
+export const get_projection_source_entries = (
+  entries: PhaseData[],
+  temp_filtered_entries: PhaseData[],
+): PhaseData[] => (temp_filtered_entries.length > 0 ? temp_filtered_entries : entries)
+
+const resolve_temp_filter_options = (
+  config: ChemPotDiagramConfig,
+  props: TempFilterProps,
+): ResolvedTempFilterOptions => ({
+  interpolate:
+    config.interpolate_temperature ??
+    props.interpolate_temperature ??
+    CHEMPOT_DEFAULTS.interpolate_temperature,
+  max_interpolation_gap:
+    config.max_interpolation_gap ??
+    props.max_interpolation_gap ??
+    CHEMPOT_DEFAULTS.max_interpolation_gap,
+})
+
+export function get_temp_filter_payload(
+  entries: PhaseData[],
+  temperature: number | undefined,
+  config: ChemPotDiagramConfig,
+  props: TempFilterProps,
+): TempFilterPayload {
+  const { has_temp_data, available_temperatures } = analyze_temperature_data(entries)
+  if (!has_temp_data || temperature === undefined) {
+    return { has_temp_data, available_temperatures, temp_filtered_entries: entries }
+  }
+  const filter_options = resolve_temp_filter_options(config, props)
+  const temp_filtered_entries = filter_entries_at_temperature(
+    entries,
+    temperature,
+    filter_options,
+  )
+  return { has_temp_data, available_temperatures, temp_filtered_entries }
+}
+
+export function get_valid_temperature(
+  temperature: number | undefined,
+  has_temp_data: boolean,
+  available_temperatures: number[],
+): number | undefined {
+  if (!has_temp_data || available_temperatures.length === 0) return temperature
+  const min_temperature = available_temperatures[0]
+  const max_temperature = available_temperatures.at(-1) ?? min_temperature
+  if (temperature === undefined) return min_temperature
+  if (available_temperatures.includes(temperature)) return temperature
+  if (temperature >= min_temperature && temperature <= max_temperature) {
+    return temperature
+  }
+  return min_temperature
+}

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

@@ -0,0 +1,130 @@
+import type { D3InterpolateName } from '$lib/colors'
+import type { PhaseData } from '$lib/convex-hull/types'
+import type { Point2D } from '$lib/math'
+
+// Per-element chemical potential bounds [min, max] in eV
+// Default is [-50, 0] matching pymatgen
+export type ChemPotLimits = Partial<Record<string, [number, number]>>
+
+export type ChemPotColorMode = `none` | `energy` | `formation_energy` | `arity` | `entries`
+
+// For quaternary+ systems: "single" shows one 3D diagram with projection switcher,
+// "grid" shows all C(n,3) ternary projections simultaneously
+export type ChemPotProjectionMode = `single` | `grid`
+
+// Visual and behavioral configuration for the diagram
+export interface ChemPotDiagramConfig {
+  // Plot formal (reference) chemical potentials mu_X - mu_X^0, or absolute DFT energies mu_X
+  formal_chempots?: boolean // default true
+  // Lower bound for unspecified element limits (eV)
+  default_min_limit?: number // default -50
+  // Padding (eV) to trim default_min_limit bounding box for cleaner plots
+  element_padding?: number // default 1.0
+  // Whether to label stable phases by formula
+  label_stable?: boolean // default true
+  // Which 2 or 3 elements to use as axes (default: first 2 or 3 from entries)
+  elements?: string[]
+  // Per-element chemical potential bounds
+  limits?: ChemPotLimits
+  // 3D only: overlay domains for specified formulas (can be from other chemical systems)
+  formulas_to_draw?: string[]
+  draw_formula_meshes?: boolean // default true
+  draw_formula_lines?: boolean // default true
+  formula_colors?: string[] // default Dark2 palette
+  show_tooltip?: boolean // default true
+  tooltip_detail_level?: `compact` | `detailed` // default detailed
+  // Region coloring mode for 3D diagram
+  color_mode?: ChemPotColorMode // default none
+  // D3 interpolator for continuous color scales (energy, formation_energy, entries)
+  color_scale?: D3InterpolateName // default interpolateSpectral
+  // Reverse the color scale direction
+  reverse_color_scale?: boolean // default true
+  // Enable linear interpolation for temperatures not in the data (default: true)
+  interpolate_temperature?: boolean
+  // Maximum temperature gap (Kelvin) allowed for interpolation (default: 500)
+  max_interpolation_gap?: number
+  // For quaternary+ systems: show one diagram with projection switcher ("single")
+  // or all C(n,3) ternary projections in a grid ("grid"). Default: "single"
+  projection_mode?: ChemPotProjectionMode
+}
+
+// Computed chemical potential diagram data
+export interface ChemPotDiagramData {
+  // Stability domains keyed by reduced formula
+  domains: Record<string, number[][]>
+  // Sorted element list for this diagram
+  elements: string[]
+  // Elemental reference entries keyed by element symbol
+  el_refs: Record<string, PhaseData>
+  // Minimum-energy entries per composition
+  min_entries: PhaseData[]
+  // Hyperplane data: rows of [x_1, ..., x_n, -E_per_atom]
+  hyperplanes: number[][]
+  // Entries corresponding to hyperplanes (same order)
+  hyperplane_entries: PhaseData[]
+  // Axis limits array: [[min, max], ...] per element
+  lims: [number, number][]
+}
+
+export interface ChemPotHoverInfoBase {
+  formula: string
+  view: `2d` | `3d`
+  pointer?: Point2D
+  n_points: number
+  axis_ranges: AxisRangeData[]
+}
+
+export interface AxisRangeData {
+  element: string
+  min_val: number
+  max_val: number
+}
+
+export interface ChemPotHoverInfo2D extends ChemPotHoverInfoBase {
+  view: `2d`
+}
+
+export interface ChemPotHoverInfo3D extends ChemPotHoverInfoBase {
+  view: `3d`
+  n_vertices: number
+  n_edges: number
+  ann_loc: number[]
+  touches_limits: string[]
+  is_elemental: boolean
+  is_draw_formula: boolean
+  matching_entry_count: number
+  min_energy_per_atom: number | null
+  max_energy_per_atom: number | null
+  neighbors: string[]
+}
+
+export type ChemPotHoverInfo = ChemPotHoverInfo2D | ChemPotHoverInfo3D
+
+// Default configuration values
+export const CHEMPOT_DEFAULTS = {
+  formal_chempots: true,
+  default_min_limit: -50,
+  element_padding: 1.0,
+  label_stable: true,
+  draw_formula_meshes: true,
+  draw_formula_lines: true,
+  show_tooltip: true,
+  tooltip_detail_level: `detailed`,
+  color_mode: `formation_energy` as ChemPotColorMode,
+  color_scale: `interpolateSpectral` as D3InterpolateName,
+  reverse_color_scale: true,
+  interpolate_temperature: true,
+  max_interpolation_gap: 500,
+  projection_mode: `single` as ChemPotProjectionMode,
+  // Dark2 qualitative palette (same as pymatgen/plotly default)
+  formula_colors: [
+    `#1b9e77`,
+    `#d95f02`,
+    `#7570b3`,
+    `#e7298a`,
+    `#66a61e`,
+    `#e6ab02`,
+    `#a6761d`,
+    `#666666`,
+  ],
+} as const

package/dist/src/lib/colors/index.ts

@@ -0,0 +1,249 @@
+import { rgb } from 'd3-color'
+import * as d3_sc from 'd3-scale-chromatic'
+import type { Vec3 } from '$lib/math'
+import type { ELEM_SYMBOLS } from '$lib/labels'
+import alloy_colors from './alloy-colors.json' with { type: 'json' }
+import dark_mode_colors from './dark-mode-colors.json' with { type: 'json' }
+import jmol_colors from './jmol-colors.json' with { type: 'json' }
+import muted_colors from './muted-colors.json' with { type: 'json' }
+import pastel_colors from './pastel-colors.json' with { type: 'json' }
+import vesta_colors from './vesta-colors.json' with { type: 'json' }
+
+// Extract color scheme interpolate function names from d3-scale-chromatic
+export type D3InterpolateName = keyof typeof d3_sc & `interpolate${string}`
+export type D3ColorSchemeName = D3InterpolateName extends `interpolate${infer Name}`
+  ? Name
+  : never
+export const get_d3_interpolator = (name: D3InterpolateName): ((t: number) => string) => {
+  const candidate = d3_sc[name]
+  return typeof candidate === `function` ? candidate : d3_sc.interpolateViridis
+}
+export const COLOR_SCALE_TYPES = [`continuous`, `categorical`] as const
+export type ColorScaleType = (typeof COLOR_SCALE_TYPES)[number]
+
+// color values have to be in hex format since that's the only format
+// <input type="color"> supports
+// https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color#value
+export const DEFAULT_CATEGORY_COLORS: Record<string, string> = {
+  'diatomic nonmetal': `#ff8c00`, // darkorange
+  'noble gas': `#9932cc`, // darkorchid
+  'alkali metal': `#006400`, // darkgreen
+  'alkaline earth metal': `#483d8b`, // darkslateblue
+  metalloid: `#b8860b`, // darkgoldenrod
+  'polyatomic nonmetal': `#a52a2a`, // brown
+  'transition metal': `#571e6c`,
+  'post-transition metal': `#938d4a`,
+  lanthanide: `#58748e`,
+  actinide: `#6495ed`, // cornflowerblue
+}
+
+export const AXIS_COLORS = [
+  // [axis name, color, hover color]
+  [`x`, `#d75555`, `#e66666`],
+  [`y`, `#55b855`, `#66c966`],
+  [`z`, `#5555d7`, `#6666e6`],
+] as const
+export const NEG_AXIS_COLORS = [
+  [`nx`, `#b84444`, `#cc5555`],
+  [`ny`, `#44a044`, `#55b155`],
+  [`nz`, `#4444b8`, `#5555c9`],
+] as const
+
+export type RGBColor = Vec3
+export type ElementColorScheme = Record<(typeof ELEM_SYMBOLS)[number], RGBColor>
+
+const rgb_scheme_to_hex = (obj: Record<string, number[]>): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(obj)
+      .filter(([, val]) => val.length >= 3)
+      .map(([key, val]) => [key, rgb(val[0], val[1], val[2]).formatHex()]),
+  )
+
+export const vesta_hex = rgb_scheme_to_hex(vesta_colors)
+export const jmol_hex = rgb_scheme_to_hex(jmol_colors)
+export const alloy_hex = rgb_scheme_to_hex(alloy_colors)
+export const pastel_hex = rgb_scheme_to_hex(pastel_colors)
+export const muted_hex = rgb_scheme_to_hex(muted_colors)
+export const dark_mode_hex = rgb_scheme_to_hex(dark_mode_colors)
+
+export const ELEMENT_COLOR_SCHEMES = {
+  Vesta: vesta_hex,
+  Jmol: jmol_hex,
+  Alloy: alloy_hex,
+  Pastel: pastel_hex,
+  Muted: muted_hex,
+  'Dark Mode': dark_mode_hex,
+} as const
+
+export type ColorSchemeName = keyof typeof ELEMENT_COLOR_SCHEMES
+export const default_element_colors = { ...vesta_hex }
+
+// Helper function to detect if a value is a color string
+export const is_color = (val: unknown): val is string => {
+  if (typeof val !== `string`) return false
+  // Check for hex colors, rgb/rgba, hsl/hsla, color(), var(), and named colors
+  // Exclude incomplete function prefixes like 'rgb', 'hsl', 'var', 'color'
+  return /^(#[0-9a-f]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)|color\([^)]+\)|var\([^)]+\)|(?!rgb$|hsl$|var$|color$)[a-z]+)$/i.test(
+    val.trim(),
+  )
+}
+
+export const PLOT_COLORS = [
+  // Color series for e.g. line plots
+  `#63b3ed`,
+  `#68d391`,
+  `#fbd38d`,
+  `#fc8181`,
+  `#d6bcfa`,
+  `#4fd1c7`,
+  `#f687b3`,
+  `#fed7d7`,
+  `#bee3f8`,
+  `#c6f6d5`,
+] as const
+
+// calculate human-perceived brightness from RGB color
+export function luminance(clr: string) {
+  const { r, g, b } = rgb(clr)
+
+  return (0.299 * r + 0.587 * g + 0.114 * b) / 255 // https://stackoverflow.com/a/596243
+}
+
+// get background color of passed DOM node, or recurse up the DOM tree if current node is transparent
+export function get_bg_color(
+  elem: HTMLElement | null,
+  bg_color: string | null = null,
+): string {
+  if (bg_color) return bg_color
+  // recurse up the DOM tree to find the first non-transparent background color
+  const transparent = `rgba(0, 0, 0, 0)`
+  if (!elem) return transparent // if no DOM node, return transparent
+
+  const bg = getComputedStyle(elem).backgroundColor // get node background color
+  if (bg !== transparent) return bg // if not transparent, return it
+  return get_bg_color(elem.parentElement) // otherwise recurse up the DOM tree
+}
+
+export interface ContrastOptions {
+  bg_color?: string
+  luminance_threshold?: number
+  choices?: [string, string]
+}
+
+export function pick_contrast_color(options: ContrastOptions = {}) {
+  const { bg_color, luminance_threshold = 0.7, choices = [`black`, `white`] } = options
+  const light_bg = luminance(bg_color ?? `white`) > luminance_threshold
+  return light_bg ? choices[0] : choices[1] // dark text for light backgrounds, light for dark
+}
+
+// Svelte attachment that automatically picks dark or light text color to maximize contrast with node's background color
+export const contrast_color =
+  (options: ContrastOptions = {}) =>
+  (node: HTMLElement) => {
+    node.style.color = pick_contrast_color({ ...options, bg_color: get_bg_color(node) })
+  }
+
+const is_valid_bg = (bg: string): boolean =>
+  bg !== `` && bg !== `rgba(0, 0, 0, 0)` && bg !== `transparent`
+
+// Detect and return the page background color from html/body elements or user preferences
+export function get_page_background(
+  fallback_dark = `#1a1a1a`,
+  fallback_light = `#ffffff`,
+): string {
+  if (typeof window === `undefined`) return ``
+
+  // Try to get background from html or body
+  const html_bg = getComputedStyle(document.documentElement).backgroundColor
+  const body_bg = getComputedStyle(document.body).backgroundColor
+
+  // Check if background is not transparent/unset
+  // Prefer body background as it's more likely to be styled by the theme
+  if (is_valid_bg(body_bg)) return body_bg
+  if (is_valid_bg(html_bg)) return html_bg
+
+  // Fall back to prefers-color-scheme
+  const prefers_dark = globalThis.matchMedia(`(prefers-color-scheme: dark)`).matches
+  return prefers_dark ? fallback_dark : fallback_light
+}
+
+// Detect dark mode: checks data-theme attribute, localStorage, then OS preference
+export function is_dark_mode(): boolean {
+  if (typeof document === `undefined`) return false
+  const data_theme = document.documentElement.dataset.theme
+  if (data_theme === `dark` || data_theme === `light`) return data_theme === `dark`
+  try {
+    const stored = localStorage.getItem(`theme`)
+    if (stored === `dark` || stored === `light`) return stored === `dark`
+  } catch {
+    /* localStorage throws in private browsing mode */
+  }
+  return globalThis.matchMedia?.(`(prefers-color-scheme: dark)`).matches ?? false
+}
+
+// Watch for dark mode changes and call callback on each change. Returns cleanup function.
+export function watch_dark_mode(on_change: (dark: boolean) => void): () => void {
+  if (typeof document === `undefined`) return () => {} // No-op in SSR
+  const notify = () => on_change(is_dark_mode())
+
+  const observer = new MutationObserver(notify)
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: [`data-theme`],
+  })
+
+  const on_storage = (ev: StorageEvent) => {
+    if (ev.key === `theme`) notify()
+  }
+  globalThis.addEventListener(`storage`, on_storage)
+
+  const media_query = globalThis.matchMedia?.(`(prefers-color-scheme: dark)`)
+  media_query?.addEventListener(`change`, notify)
+
+  return () => {
+    observer.disconnect()
+    globalThis.removeEventListener(`storage`, on_storage)
+    media_query?.removeEventListener(`change`, notify)
+  }
+}
+
+// Convert a CSS color string to hex format for use with <input type="color">.
+// Returns fallback for CSS variables, transparent, invalid colors, or undefined.
+// Uses d3-color for robust parsing of named colors, rgb(), hsl(), etc.
+export function css_color_to_hex(color: string | undefined, fallback: string): string {
+  if (!color || color.startsWith(`var(`)) return fallback
+  if (color === `transparent`) return `#ffffff`
+  const parsed = rgb(color)
+  return Number.isNaN(parsed.r) ? fallback : parsed.formatHex()
+}
+
+// Add or modify the alpha channel of a color.
+// Supports hex (#rgb, #rgba, #rrggbb, #rrggbbaa), rgb(), and rgba() formats.
+// Returns the color in rgba() format, or the original color if format is unsupported.
+export function add_alpha(color: string, alpha: number): string {
+  // Clamp alpha to valid CSS range [0, 1]
+  const clamped_alpha = Math.max(0, Math.min(1, alpha))
+
+  // Handle hex colors (#rgb, #rgba, #rrggbb, #rrggbbaa)
+  if (color.startsWith(`#`)) {
+    const hex = color.slice(1)
+    // Guard against malformed hex (only 3, 4, 6, or 8 chars are valid)
+    if (![3, 4, 6, 8].includes(hex.length)) return color
+
+    // Extract RGB, ignoring any existing alpha channel
+    const is_short = hex.length === 3 || hex.length === 4
+    const red = parseInt(is_short ? hex[0] + hex[0] : hex.slice(0, 2), 16)
+    const green = parseInt(is_short ? hex[1] + hex[1] : hex.slice(2, 4), 16)
+    const blue = parseInt(is_short ? hex[2] + hex[2] : hex.slice(4, 6), 16)
+    return `rgba(${red}, ${green}, ${blue}, ${clamped_alpha})`
+  }
+  // Handle rgb() colors
+  if (color.startsWith(`rgb(`)) {
+    return color.replace(`rgb(`, `rgba(`).replace(`)`, `, ${clamped_alpha})`)
+  }
+  // Handle rgba() - replace existing alpha (supports scientific notation like 1e-5)
+  if (color.startsWith(`rgba(`)) {
+    return color.replace(/,\s*[\d.eE\-+]+\)$/, `, ${clamped_alpha})`)
+  }
+  return color
+}