matterviz 0.3.4 → 0.3.6

package/dist/src/lib/convex-hull/types.ts

@@ -0,0 +1,267 @@
+import type { CompositionType } from '$lib/composition'
+import type { ShowControlsProp } from '$lib/controls'
+import type { ElementSymbol } from '$lib/element'
+import type { Point2D, Point3D, Vec3 } from '$lib/math'
+import type { Rect, Sides } from '$lib/plot/layout'
+import type { AnyStructure } from '$lib/structure'
+
+export interface StructurePopupStats {
+  id?: string
+  formula?: string
+  e_above_hull?: number
+  e_form?: number
+}
+
+export interface StructurePopupContext {
+  structure: AnyStructure
+  stats?: StructurePopupStats
+  formula_html: string
+}
+
+// Unified convex hull entry interface supporting both pymatgen and Materials Project formats
+export interface PhaseData {
+  // Core required fields
+  composition: CompositionType
+  energy: number
+  entry_id?: string
+
+  // Common computed fields
+  e_above_hull?: number
+  is_stable?: boolean
+  exclude_from_hull?: boolean // If true, entry is shown but not used in hull construction
+  energy_per_atom?: number
+  e_form_per_atom?: number // Formation energy per atom from fetch-mp-pd-data.py
+  reduced_formula?: string
+  name?: string
+
+  // Temperature-dependent free energies (replaces `energy` at selected T)
+  temperatures?: number[] // in Kelvin, use integers for exact matching
+  free_energies?: number[] // G(T) in eV, same length as temperatures
+
+  // Pymatgen-specific fields (optional)
+  '@module'?: string
+  '@class'?: string
+  correction?: number
+  energy_adjustments?: Record<string, number>[]
+  parameters?: Record<string, unknown>
+  data?: Record<string, unknown>
+  structure?: Record<string, unknown>
+
+  // Materials Project-specific fields (optional)
+  attributes?: Record<string, unknown>
+}
+
+// Processed phase data for convex hull calculations
+export interface ProcessedPhaseData {
+  entries: PhaseData[]
+  stable_entries: PhaseData[]
+  unstable_entries: PhaseData[]
+  elements: ElementSymbol[]
+  el_refs: Record<string, PhaseData>
+}
+
+export type MarkerSymbol = // Marker symbol types for convex hull entries
+  `circle` | `star` | `triangle` | `cross` | `diamond` | `square` | `wye`
+
+// Hull face coloring modes for 3D/4D convex hull visualizations
+export type HullFaceColorMode =
+  | `uniform` // Single user-selected color (default)
+  | `formation_energy` // Color by average formation energy of face vertices
+  | `dominant_element` // Color by element with highest concentration at centroid
+  | `facet_index` // Distinct categorical color per facet
+
+export const HULL_FACE_COLOR_MODES: readonly HullFaceColorMode[] = [
+  `uniform`,
+  `formation_energy`,
+  `dominant_element`,
+  `facet_index`,
+] as const
+
+// Plot entry with 3D coordinates for quaternary diagrams
+export interface ConvexHullEntry extends PhaseData, Point3D {
+  is_element: boolean
+  size?: number
+  marker?: MarkerSymbol // Optional marker symbol override (default: circle)
+}
+
+// Configuration for convex hull display
+export interface ConvexHullConfig {
+  width?: number
+  height?: number
+  margin?: Sides
+  unstable_threshold?: number // eV/atom threshold for showing unstable entries
+  show_labels?: boolean
+  show_hull?: boolean
+  point_size?: number
+  line_width?: number
+  font_size?: number
+  colors?: {
+    stable?: string
+    unstable?: string
+    hull_line?: string
+    background?: string
+    text?: string
+    edge?: string
+    tooltip_bg?: string
+    tooltip_text?: string
+    annotation?: string
+  }
+}
+
+// Legend configuration
+export interface ConvexHullControlsType {
+  title?: string
+  show?: ShowControlsProp
+  position?: `top-left` | `top-right` | `bottom-left` | `bottom-right`
+  width?: number
+  show_counts?: boolean
+  show_color_toggle?: boolean
+  show_label_controls?: boolean
+}
+
+// Plane equation: normal·p + offset = 0
+export interface Plane {
+  normal: Point3D
+  offset: number
+}
+
+// Internal face structure for Quickhull algorithm
+export interface ConvexHullFace {
+  vertices: Vec3
+  plane: Plane
+  centroid: Point3D
+  outside_points: Set<number>
+}
+
+// Convex hull triangle with actual coordinate vertices (return type from compute_quickhull_triangles)
+export interface ConvexHullTriangle {
+  vertices: [Point3D, Point3D, Point3D]
+  normal: Point3D
+  centroid: Point3D
+}
+
+export interface LabelPlacement {
+  x: number
+  y: number
+  rect: Rect
+}
+
+// Hover data for tooltips
+export interface HoverData3D<T = ConvexHullEntry> {
+  entry: T
+  position: Point2D
+}
+
+// Phase statistics
+export interface PhaseStats {
+  total: number
+  unary: number
+  binary: number
+  ternary: number
+  quaternary: number
+  quinary_plus: number
+  stable: number
+  unstable: number
+  energy_range: { min: number; max: number; avg: number }
+  hull_distance: { max: number; avg: number }
+  elements: number
+  chemical_system: string
+  // Maximum arity used when computing stats — arity counts beyond this
+  // were zeroed. The UI uses this to decide which arity rows to display.
+  max_arity: number
+}
+
+// Numeric arity-count fields in PhaseStats (for type-safe indexing).
+// Uses Extract to stay in sync with PhaseStats at compile time.
+export type PhaseArityField = Extract<
+  keyof PhaseStats,
+  `unary` | `binary` | `ternary` | `quaternary` | `quinary_plus`
+>
+
+// Highlight styles for convex hull entries
+export interface HighlightStyle {
+  effect?: `pulse` | `glow` | `size` | `color` | `both`
+  color?: string
+  size_multiplier?: number
+  opacity?: number
+  pulse_speed?: number
+}
+
+// --- Gas Phase Thermodynamics ---
+
+// Default temperature (Kelvin) for gas corrections when no temperature is specified
+export const DEFAULT_GAS_TEMP = 300
+
+// Supported gas species for chemical potential calculations
+export type GasSpecies = `O2` | `N2` | `H2` | `CO` | `CO2` | `H2O` | `F2`
+
+// All supported gas species as an array (for iteration)
+export const GAS_SPECIES: readonly GasSpecies[] = [
+  `O2`,
+  `N2`,
+  `H2`,
+  `CO`,
+  `CO2`,
+  `H2O`,
+  `F2`,
+] as const
+
+// Default atmospheric partial pressures (in bar)
+export const DEFAULT_GAS_PRESSURES: Readonly<Record<GasSpecies, number>> = {
+  O2: 0.2095, // ~21% in atmosphere
+  N2: 0.7809, // ~78% in atmosphere
+  H2: 0.1, // typical experimental
+  CO: 1e-6, // trace
+  CO2: 3.95e-4, // ~400 ppm in atmosphere
+  H2O: 0.03, // ~3% humidity
+  F2: 0.1, // typical experimental
+}
+
+// Interface for providing gas thermodynamic data (abstracted for privacy)
+export interface GasThermodynamicsProvider {
+  // Get standard chemical potential μ°(T) at reference pressure P₀=1 bar
+  // Returns value in eV/molecule (not per atom)
+  get_standard_chemical_potential(gas: GasSpecies, T: number): number
+
+  // Get list of supported gas species
+  get_supported_gases(): GasSpecies[]
+
+  // Get valid temperature range [T_min, T_max] in Kelvin
+  get_temperature_range(): [number, number]
+}
+
+// Configuration for gas thermodynamics in convex hull calculations
+export interface GasThermodynamicsConfig {
+  // Which gas species to enable (default: none)
+  enabled_gases?: GasSpecies[]
+
+  // Partial pressures for each gas (in bar, default: DEFAULT_GAS_PRESSURES)
+  pressures?: Partial<Record<GasSpecies, number>>
+
+  // Custom thermodynamic data provider (default: built-in data)
+  provider?: GasThermodynamicsProvider
+
+  // Element mapping: which elements are derived from which gases
+  // e.g., { O: 'O2', N: 'N2' } means O comes from O2 gas, N from N2 gas
+  // Default mapping is inferred from gas formula (O2 -> O, N2 -> N, etc.)
+  element_to_gas?: Partial<Record<ElementSymbol, GasSpecies>>
+}
+
+// Result of analyzing entries for gas-dependent data
+export interface GasAnalysis {
+  // Whether any enabled gas affects the chemical system
+  has_gas_dependent_elements: boolean
+  // Elements that come from gas phases
+  gas_elements: ElementSymbol[]
+  // Gas species that are relevant for this system
+  relevant_gases: GasSpecies[]
+}
+
+// Position options for UI control panels (e.g., GasPressureControls)
+export const GAS_CONTROL_POSITIONS = [
+  `top-left`,
+  `top-right`,
+  `bottom-left`,
+  `bottom-right`,
+] as const
+export type GasControlPosition = (typeof GAS_CONTROL_POSITIONS)[number]

package/dist/src/lib/coordination/CoordinationBarPlot.svelte

@@ -0,0 +1,311 @@
+<script lang="ts">
+  import { PLOT_COLORS } from '$lib/colors'
+  import { StatusMessage } from '$lib/feedback'
+  import { create_file_drop_handler } from '$lib/io'
+  import { format_value } from '$lib/labels'
+  import { BarPlot } from '$lib/plot'
+  import type {
+    AxisConfig,
+    BarHandlerProps,
+    BarSeries,
+    Orientation,
+  } from '$lib/plot/types'
+  import type { AnyStructure } from '$lib/structure'
+  import type { BondingStrategy } from '$lib/structure/bonding'
+  import { parse_any_structure } from '$lib/structure/parse'
+  import { is_crystal } from '$lib/structure/validation'
+  import type { ComponentProps } from 'svelte'
+  import { SvelteMap, SvelteSet } from 'svelte/reactivity'
+  import { calc_coordination_nums, type CoordinationData } from './calc-coordination'
+  import type { SplitMode } from './index'
+
+  type CoordinationMetadata = {
+    element?: string
+    structure_label?: string
+  } & Record<string, unknown>
+
+  interface StructureEntry {
+    label: string
+    structure: AnyStructure
+    color?: string
+    data?: CoordinationData
+  }
+  let {
+    structures,
+    strategy = `electroneg_ratio`,
+    split_mode = `by_element`,
+    mode = $bindable(`grouped`),
+    orientation = `vertical` as Orientation,
+    x_axis = {},
+    y_axis = {},
+    allow_file_drop = true,
+    on_file_drop,
+    loading = $bindable(false),
+    error_msg = $bindable(),
+    ...rest
+  }: Omit<ComponentProps<typeof BarPlot>, `series`> & {
+    structures:
+      | AnyStructure
+      | Record<string, AnyStructure | { structure: AnyStructure; color?: string }>
+      | StructureEntry[]
+    strategy?: BondingStrategy
+    split_mode?: SplitMode
+    x_axis?: AxisConfig
+    y_axis?: AxisConfig
+    allow_file_drop?: boolean
+    on_file_drop?: (content: string | ArrayBuffer, filename: string) => void
+    loading?: boolean
+    error_msg?: string
+  } = $props()
+
+  let dragover = $state(false)
+  let dropped_entries = $state<StructureEntry[]>([])
+  let is_horizontal = $derived(orientation === `horizontal`)
+
+  // Normalize input to consistent array of { label, structure, color }
+  const structure_entries = $derived.by<StructureEntry[]>(() => {
+    if (!structures) return []
+
+    const base_entries = Array.isArray(structures)
+      ? (structures as StructureEntry[])
+      : (is_crystal(structures)
+        ? [{ label: `Structure`, structure: structures as AnyStructure }]
+        : Object.entries(
+          structures as Record<
+            string,
+            AnyStructure | { structure: AnyStructure; color?: string }
+          >,
+        ).map(([label, value]) =>
+          `structure` in value
+            ? { label, ...value }
+            : { label, structure: value as AnyStructure }
+        ))
+
+    // Merge user-provided structures with dropped structures
+    return [...base_entries, ...dropped_entries]
+  })
+
+  // Compute coordination data for each structure
+  const entries_with_data = $derived(structure_entries.map((entry) => ({
+    ...entry,
+    data: calc_coordination_nums(entry.structure, strategy),
+  })))
+
+  // Compute appropriate ranges
+  const ranges = $derived.by(() => {
+    // CN axis should always start at 0 and show at least [0,4]
+    let max_cn = 4 // minimum max value
+    for (const entry of entries_with_data) {
+      for (const [cn] of entry.data.cn_histogram) max_cn = Math.max(max_cn, cn)
+    }
+    const cn_range: [number, number] = [-0.5, max_cn + 0.5]
+
+    return { count: [0, null] as [number, null], cn: cn_range } // Count axis should always start at 0
+  })
+
+  // Derive integer CN ticks for axis labels
+  const cn_ticks = $derived.by(() => {
+    const all_cns = new SvelteSet<number>()
+    // Always include minimum CN values 0-4
+    for (let idx = 0; idx <= 4; idx++) all_cns.add(idx)
+    // Add actual CN values from data
+    for (const entry of entries_with_data) {
+      for (const [cn] of entry.data.cn_histogram) all_cns.add(cn)
+    }
+    return Array.from(all_cns).sort((cn1, cn2) => cn1 - cn2)
+  })
+
+  // Build BarPlot series based on split_mode
+  const bar_series = $derived.by<BarSeries<CoordinationMetadata>[]>(() => {
+    if (split_mode === `by_element`) {
+      // One series per element across all structures
+      const element_series_map = new SvelteMap<string, Map<number, number>>()
+
+      // Collect all unique CNs across all elements
+      const all_cns = new SvelteSet<number>()
+
+      for (const entry of entries_with_data) {
+        for (const [element, cn_histogram] of entry.data.cn_histogram_by_element) {
+          if (!element_series_map.has(element)) {
+            element_series_map.set(element, new SvelteMap())
+          }
+          const element_map = element_series_map.get(element)
+          if (!element_map) continue
+
+          for (const [cn, count] of cn_histogram) {
+            all_cns.add(cn)
+            element_map.set(cn, (element_map.get(cn) ?? 0) + count)
+          }
+        }
+      }
+
+      // Sort CNs for consistent x-axis
+      const sorted_cns = Array.from(all_cns).sort((a, b) => a - b)
+
+      // Convert map to array and ensure all series have same x-values
+      return Array.from(element_series_map.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([element, cn_map], idx) => {
+          return {
+            x: sorted_cns,
+            y: sorted_cns.map((cn) => cn_map.get(cn) ?? 0),
+            label: element,
+            color: PLOT_COLORS[idx % PLOT_COLORS.length],
+            bar_width: 0.8,
+            visible: true,
+            metadata: { element },
+          }
+        })
+    } else if (split_mode === `by_structure`) {
+      // One series per structure
+      // First collect all unique CNs
+      const all_cns = new SvelteSet<number>()
+      for (const entry of entries_with_data) {
+        for (const [cn] of entry.data.cn_histogram) {
+          all_cns.add(cn)
+        }
+      }
+      const sorted_cns = Array.from(all_cns).sort((a, b) => a - b)
+
+      return entries_with_data.map((entry, idx) => {
+        return {
+          x: sorted_cns,
+          y: sorted_cns.map((cn) => entry.data.cn_histogram.get(cn) ?? 0),
+          label: entry.label,
+          color: entry.color ?? PLOT_COLORS[idx % PLOT_COLORS.length],
+          bar_width: 0.8,
+          visible: true,
+          metadata: { structure_label: entry.label },
+        }
+      })
+    } else {
+      // split_mode === 'none': combine all into single series
+      const combined_histogram = new SvelteMap<number, number>()
+
+      for (const entry of entries_with_data) {
+        for (const [cn, count] of entry.data.cn_histogram) {
+          combined_histogram.set(cn, (combined_histogram.get(cn) ?? 0) + count)
+        }
+      }
+
+      const x_vals = Array.from(combined_histogram.keys()).sort((a, b) => a - b)
+      const y_vals = x_vals.map((cn) => combined_histogram.get(cn) ?? 0)
+
+      return [
+        {
+          x: x_vals,
+          y: y_vals,
+          label: `All Sites`,
+          color: PLOT_COLORS[0],
+          bar_width: 0.8,
+          visible: true,
+          metadata: {},
+        },
+      ]
+    }
+  })
+
+  const compute_and_add = (content: string | ArrayBuffer, filename: string) => {
+    try {
+      const text_content = content instanceof ArrayBuffer
+        ? new TextDecoder().decode(content)
+        : content
+      const parsed_structure = parse_any_structure(text_content, filename)
+      if (is_crystal(parsed_structure)) {
+        dropped_entries = [{
+          label: filename || `Dropped structure`,
+          structure: parsed_structure,
+        }, ...dropped_entries]
+      } else {
+        error_msg = `Structure has no lattice or sites; cannot compute coordination`
+      }
+    } catch (exc) {
+      error_msg = `Failed to process structure: ${
+        exc instanceof Error ? exc.message : String(exc)
+      }`
+    }
+  }
+
+  const handle_file_drop = create_file_drop_handler({
+    allow: () => allow_file_drop,
+    on_drop: (content, filename) =>
+      (on_file_drop || compute_and_add)(content, filename),
+    on_error: (msg) => {
+      error_msg = msg
+    },
+    set_loading: (val) => {
+      loading = val
+      if (val) [error_msg, dragover] = [undefined, false]
+    },
+  })
+
+  let display = $state({ x_zero_line: false, y_zero_line: false })
+  // Update display when orientation changes
+  $effect(() => {
+    display.x_zero_line = is_horizontal
+    display.y_zero_line = !is_horizontal
+  })
+
+  const cn_axis = { label: `Coordination Number`, format: `d` }
+  const count_axis = { label: `Count`, format: `d` }
+</script>
+
+<StatusMessage bind:message={error_msg} type="error" dismissible />
+
+{#if bar_series.length === 0}
+  <StatusMessage
+    message={allow_file_drop
+    ? `Drag and drop structure files here to compute coordination numbers`
+    : `No coordination data to display`}
+  />
+{:else}
+  {#snippet tooltip(info: BarHandlerProps<CoordinationMetadata>)}
+    {@const cn = info.x}
+    {@const count = info.y}
+    {@const element = info.metadata?.element}
+    {@const structure_label = info.metadata?.structure_label}
+    {#if element}
+      {element} —
+    {/if}
+    {#if structure_label}
+      {structure_label} —
+    {/if}
+    CN: {format_value(cn, `.0f`)}
+    <br />
+    Sites: {format_value(count, `.0f`)}
+  {/snippet}
+
+  <BarPlot
+    {...rest}
+    series={bar_series}
+    bind:orientation
+    bind:mode
+    x_axis={{
+      ...(is_horizontal ? count_axis : cn_axis),
+      range: is_horizontal ? ranges.count : ranges.cn,
+      ticks: is_horizontal ? undefined : cn_ticks,
+      ...x_axis,
+      label_shift: { y: 20, ...(is_horizontal ? y_axis : x_axis).label_shift },
+    }}
+    y_axis={{
+      ...(is_horizontal ? cn_axis : count_axis),
+      range: is_horizontal ? ranges.cn : ranges.count,
+      ticks: is_horizontal ? cn_ticks : undefined,
+      ...y_axis,
+      label_shift: { x: 2, ...(is_horizontal ? x_axis : y_axis).label_shift },
+    }}
+    bind:display
+    {tooltip}
+    ondrop={handle_file_drop}
+    ondragover={(event) => {
+      event.preventDefault()
+      if (!allow_file_drop) return
+      dragover = true
+    }}
+    ondragleave={(event) => {
+      event.preventDefault()
+      dragover = false
+    }}
+    class={(rest.class ?? ``) + (dragover ? ` dragover` : ``)}
+  />
+{/if}

package/dist/src/lib/coordination/calc-coordination.ts

@@ -0,0 +1,93 @@
+import type { AnyStructure } from '$lib/structure'
+import type { BondingStrategy } from '$lib/structure/bonding'
+import { BONDING_STRATEGIES } from '$lib/structure/bonding'
+
+export interface CoordinationSite {
+  site_idx: number
+  element: string
+  coordination_num: number
+  neighbor_elements: string[]
+}
+
+export interface CoordinationData {
+  sites: CoordinationSite[]
+  cn_by_element: Map<string, number[]>
+  cn_histogram: Map<number, number>
+  cn_histogram_by_element: Map<string, Map<number, number>>
+}
+
+// Calculate coordination numbers for all sites in a structure using the specified bonding strategy.
+//
+// Note: This function operates on the sites present in the structure. For structures with periodic
+// boundary conditions (PBC), image atoms should be added to the structure BEFORE calling this function
+// to ensure atoms at cell boundaries have their full coordination environment calculated correctly.
+// Use get_pbc_image_sites() from '$lib/structure/pbc' to expand the structure with image atoms.
+//
+// When working with PBC-expanded structures:
+// - Image atoms are appended after the original sites
+// - Bonds will be calculated between original and image atoms
+// - Caller should extract coordination numbers for only the first N sites (original atoms)
+export function calc_coordination_nums(
+  structure: AnyStructure,
+  strategy: BondingStrategy = `electroneg_ratio`,
+): CoordinationData {
+  // Get bonds using the specified strategy
+  const bonds = BONDING_STRATEGIES[strategy](structure)
+
+  // Count neighbors for each site
+  const neighbor_counts = new Map<number, Set<number>>()
+  const sites = structure.sites
+
+  for (const bond of bonds) {
+    const { site_idx_1, site_idx_2 } = bond
+    if (!neighbor_counts.has(site_idx_1)) {
+      neighbor_counts.set(site_idx_1, new Set())
+    }
+    if (!neighbor_counts.has(site_idx_2)) {
+      neighbor_counts.set(site_idx_2, new Set())
+    }
+    const neighbors_1 = neighbor_counts.get(site_idx_1)
+    const neighbors_2 = neighbor_counts.get(site_idx_2)
+    if (neighbors_1) neighbors_1.add(site_idx_2)
+    if (neighbors_2) neighbors_2.add(site_idx_1)
+  }
+
+  // Build coordination site data
+  const coordination_sites: CoordinationSite[] = []
+  const cn_by_element = new Map<string, number[]>()
+  const cn_histogram = new Map<number, number>()
+  const cn_histogram_by_element = new Map<string, Map<number, number>>()
+
+  for (const [site_idx, site] of sites.entries()) {
+    const element = site.species[0]?.element ?? `Unknown`
+    const neighbors_set = neighbor_counts.get(site_idx) ?? new Set()
+    const coordination_num = neighbors_set.size
+
+    // Get neighbor elements
+    const neighbor_elements = Array.from(neighbors_set).map(
+      (neighbor_idx) => sites[neighbor_idx].species[0]?.element ?? `Unknown`,
+    )
+
+    coordination_sites.push({ site_idx, element, coordination_num, neighbor_elements })
+
+    // Update cn_by_element
+    const element_array = cn_by_element.get(element) ?? []
+    element_array.push(coordination_num)
+    cn_by_element.set(element, element_array)
+
+    // Update overall cn_histogram
+    cn_histogram.set(coordination_num, (cn_histogram.get(coordination_num) ?? 0) + 1)
+
+    // Update cn_histogram_by_element
+    const element_histogram = cn_histogram_by_element.get(element) ?? new Map()
+    element_histogram.set(coordination_num, (element_histogram.get(coordination_num) ?? 0) + 1)
+    cn_histogram_by_element.set(element, element_histogram)
+  }
+
+  return {
+    sites: coordination_sites,
+    cn_by_element,
+    cn_histogram,
+    cn_histogram_by_element,
+  }
+}

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

@@ -0,0 +1,9 @@
+export * from './calc-coordination'
+export { default as CoordinationBarPlot } from './CoordinationBarPlot.svelte'
+
+export const SPLIT_MODES = {
+  by_element: `By Element`,
+  by_structure: `By Structure`,
+  none: `Combined`,
+} as const
+export type SplitMode = keyof typeof SPLIT_MODES