matterviz 0.3.6 → 0.4.0

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

@@ -1,267 +0,0 @@
-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

@@ -1,311 +0,0 @@
-<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

@@ -1,93 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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