matterviz 0.3.6 → 0.4.0

package/dist/structure/index.d.ts

@@ -0,0 +1,124 @@
+import type { CompositionType } from '../composition';
+import type { ElementSymbol } from '../element';
+import type { Vec3 } from '../math';
+import * as math from '../math';
+import type { ComponentProps } from 'svelte';
+import type LatticeComponent from './Lattice.svelte';
+import type { Pbc } from './pbc';
+import type StructureSceneComponent from './StructureScene.svelte';
+export { default as Arrow } from './Arrow.svelte';
+export * from './atom-properties';
+export { default as AtomLegend } from './AtomLegend.svelte';
+export { default as Bond } from './Bond.svelte';
+export * as bonding_strategies from './bonding';
+export { default as CanvasTooltip } from './CanvasTooltip.svelte';
+export { default as Cylinder } from './Cylinder.svelte';
+export { default as Lattice } from './Lattice.svelte';
+export * from './pbc';
+export { default as Structure } from './Structure.svelte';
+export { default as StructureControls } from './StructureControls.svelte';
+export { default as StructureExportPane } from './StructureExportPane.svelte';
+export { default as StructureInfoPane } from './StructureInfoPane.svelte';
+export { default as StructureScene } from './StructureScene.svelte';
+export * from './supercell';
+export type MeasureMode = `distance` | `angle` | `edit-bonds` | `edit-atoms`;
+export type BondEditMode = `add` | `delete`;
+export type Species = {
+    element: ElementSymbol;
+    occu: number;
+    oxidation_state: number;
+};
+export type Site = {
+    species: Species[];
+    abc: Vec3;
+    xyz: Vec3;
+    label: string;
+    properties: Record<string, unknown>;
+};
+export declare const LATTICE_PARAM_KEYS: readonly ["a", "b", "c", "alpha", "beta", "gamma"];
+export type LatticeParams = Record<(typeof LATTICE_PARAM_KEYS)[number], number>;
+export type LatticeType = {
+    matrix: math.Matrix3x3;
+    pbc: Pbc;
+    volume: number;
+} & LatticeParams;
+export type Molecule = {
+    sites: Site[];
+    charge?: number;
+    id?: string;
+    properties?: StructureProperties;
+};
+export type Crystal = Molecule & {
+    lattice: LatticeType;
+};
+export type AnyStructure = Crystal | Molecule;
+export type BondOrder = 1 | 1.5 | 2 | 3 | `aromatic`;
+export type StructureBond = {
+    site_idx_1: number;
+    site_idx_2: number;
+    order: BondOrder;
+    cell_shift?: Vec3;
+};
+export type StructureProperties = Record<string, unknown> & {
+    bonds?: StructureBond[];
+};
+export type BondPair = {
+    pos_1: Vec3;
+    pos_2: Vec3;
+    site_idx_1: number;
+    site_idx_2: number;
+    bond_length: number;
+    strength: number;
+    bond_order?: BondOrder;
+    cell_shift?: Vec3;
+    transform_matrix: Float32Array;
+};
+export type { PerceivedBond, PerceptionOptions } from './bond-order-perception';
+export { compose_perceived_bonds, perceive_bond_orders, } from './bond-order-perception';
+export declare function get_element_counts(structure: AnyStructure): Partial<Record<"S" | "K" | "B" | "H" | "He" | "Li" | "Be" | "C" | "N" | "O" | "F" | "Ne" | "Na" | "Mg" | "Al" | "Si" | "P" | "Cl" | "Ar" | "Ca" | "Sc" | "Ti" | "V" | "Cr" | "Mn" | "Fe" | "Co" | "Ni" | "Cu" | "Zn" | "Ga" | "Ge" | "As" | "Se" | "Br" | "Kr" | "Rb" | "Sr" | "Y" | "Zr" | "Nb" | "Mo" | "Tc" | "Ru" | "Rh" | "Pd" | "Ag" | "Cd" | "In" | "Sn" | "Sb" | "Te" | "I" | "Xe" | "Cs" | "Ba" | "La" | "Ce" | "Pr" | "Nd" | "Pm" | "Sm" | "Eu" | "Gd" | "Tb" | "Dy" | "Ho" | "Er" | "Tm" | "Yb" | "Lu" | "Hf" | "Ta" | "W" | "Re" | "Os" | "Ir" | "Pt" | "Au" | "Hg" | "Tl" | "Pb" | "Bi" | "Po" | "At" | "Rn" | "Fr" | "Ra" | "Ac" | "Th" | "Pa" | "U" | "Np" | "Pu" | "Am" | "Cm" | "Bk" | "Cf" | "Es" | "Fm" | "Md" | "No" | "Lr" | "Rf" | "Db" | "Sg" | "Bh" | "Hs" | "Mt" | "Ds" | "Rg" | "Cn" | "Nh" | "Fl" | "Mc" | "Lv" | "Ts" | "Og", number>>;
+export declare function format_chemical_formula(structure: AnyStructure, sort_fn: (symbols: ElementSymbol[]) => ElementSymbol[]): string;
+export declare function format_formula_by_electronegativity(structure: AnyStructure): string;
+export declare const atomic_radii: CompositionType;
+export declare function get_density(structure: Crystal): number;
+export declare function get_center_of_mass(structure: AnyStructure): Vec3;
+export declare const VECTOR_KEY_PREFIXES: readonly ["force", "forces", "magmom", "magmoms", "spin", "spins"];
+export declare const is_vector_key: (key: string) => boolean;
+export declare const VECTOR_PALETTE: readonly ["#e74c3c", "#3498db", "#2ecc71", "#f39c12", "#9b59b6", "#1abc9c"];
+export declare const default_vector_configs: (keys: string[]) => {
+    [k: string]: {
+        visible: boolean;
+        color: "#e74c3c" | "#3498db" | "#2ecc71" | "#f39c12" | "#9b59b6" | "#1abc9c" | null;
+        scale: null;
+    };
+};
+export declare function get_all_site_vectors(site: Site): {
+    vec: Vec3;
+    key: string;
+}[];
+export declare function get_structure_vector_keys(structure: AnyStructure): string[];
+export interface StructureHandlerData {
+    structure?: AnyStructure;
+    filename?: string;
+    file_size?: number;
+    total_atoms?: number;
+    error_msg?: string;
+    fullscreen?: boolean;
+    camera_position?: Vec3;
+    camera_target?: Vec3;
+    camera_has_moved?: boolean;
+    color_scheme?: string;
+    performance_mode?: `quality` | `speed`;
+    scene_props?: ComponentProps<typeof StructureSceneComponent>;
+    lattice_props?: ComponentProps<typeof LatticeComponent>;
+}
+export interface BondInstance {
+    matrix: Float32Array;
+    color_start: string;
+    color_end: string;
+}
+export interface BondGroupWithGradients {
+    thickness: number;
+    instances: BondInstance[];
+    ambient_light?: number;
+    directional_light?: number;
+}

package/dist/structure/index.js

@@ -0,0 +1,167 @@
+import { ATOMIC_WEIGHTS } from '../composition/parse';
+import { element_data } from '../element';
+import * as math from '../math';
+export { default as Arrow } from './Arrow.svelte';
+export * from './atom-properties';
+export { default as AtomLegend } from './AtomLegend.svelte';
+export { default as Bond } from './Bond.svelte';
+export * as bonding_strategies from './bonding';
+export { default as CanvasTooltip } from './CanvasTooltip.svelte';
+export { default as Cylinder } from './Cylinder.svelte';
+export { default as Lattice } from './Lattice.svelte';
+export * from './pbc';
+export { default as Structure } from './Structure.svelte';
+export { default as StructureControls } from './StructureControls.svelte';
+export { default as StructureExportPane } from './StructureExportPane.svelte';
+export { default as StructureInfoPane } from './StructureInfoPane.svelte';
+export { default as StructureScene } from './StructureScene.svelte';
+export * from './supercell';
+export const LATTICE_PARAM_KEYS = [`a`, `b`, `c`, `alpha`, `beta`, `gamma`];
+export { compose_perceived_bonds, perceive_bond_orders, } from './bond-order-perception';
+export function get_element_counts(structure) {
+    const elements = {};
+    for (const site of structure.sites) {
+        for (const species of site.species) {
+            const { element: elem, occu } = species;
+            elements[elem] = (elements[elem] ?? 0) + occu;
+        }
+    }
+    return elements;
+}
+export function format_chemical_formula(structure, sort_fn) {
+    // concatenate elements in a structure followed by their amount
+    const elements = get_element_counts(structure);
+    const formula = [];
+    for (const element of sort_fn(Object.keys(elements))) {
+        const amount = elements[element] ?? 0;
+        if (amount === 1)
+            formula.push(element);
+        else
+            formula.push(`${element}<sub>${amount}</sub>`);
+    }
+    return formula.join(` `);
+}
+export function format_formula_by_electronegativity(structure) {
+    // concatenate elements in a structure followed by their amount sorted by electronegativity
+    return format_chemical_formula(structure, (symbols) => symbols.sort((el1, el2) => {
+        const elec_neg1 = element_data.find((el) => el.symbol === el1)?.electronegativity ?? 0;
+        const elec_neg2 = element_data.find((el) => el.symbol === el2)?.electronegativity ?? 0;
+        // Sort by electronegativity (ascending), then alphabetically for ties
+        if (elec_neg1 !== elec_neg2)
+            return elec_neg1 - elec_neg2;
+        return el1.localeCompare(el2);
+    }));
+}
+// Atomic radii in Angstroms (used for relative sizing, not absolute rendering scale)
+export const atomic_radii = Object.fromEntries(element_data.map((el) => [el.symbol, el.atomic_radius ?? 1]));
+// unified atomic mass units (u) per cubic angstrom (Å^3)
+// to grams per cubic centimeter (g/cm^3)
+const AMU_PER_A3_TO_G_PER_CM3 = 1.66053907;
+export function get_density(structure) {
+    // calculate the density of a Crystal in g/cm³
+    const elements = get_element_counts(structure);
+    let mass = 0;
+    for (const [element, amount] of Object.entries(elements)) {
+        const weight = ATOMIC_WEIGHTS.get(element);
+        if (weight !== undefined)
+            mass += amount * weight;
+    }
+    return (AMU_PER_A3_TO_G_PER_CM3 * mass) / structure.lattice.volume;
+}
+export function get_center_of_mass(structure) {
+    let center = [0, 0, 0];
+    let total_weight = 0;
+    for (const site of structure.sites) {
+        // Handle disordered sites by summing contributions from all species
+        for (const species of site.species) {
+            const atomic_weight = ATOMIC_WEIGHTS.get(species.element) ?? 1;
+            const weight = atomic_weight * species.occu;
+            const scaled_pos = math.scale(site.xyz, weight);
+            center = math.add(center, scaled_pos);
+            total_weight += weight;
+        }
+    }
+    return math.scale(center, 1 / total_weight);
+}
+// Recognized prefixes for per-site vector data (force, magnetic moment, spin).
+// Both singular and plural forms are accepted. Keys matching exactly or starting
+// with one of these followed by `_` (e.g. `force_DFT`) are treated as vectors.
+export const VECTOR_KEY_PREFIXES = [
+    `force`,
+    `forces`,
+    `magmom`,
+    `magmoms`,
+    `spin`,
+    `spins`,
+];
+export const is_vector_key = (key) => VECTOR_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}_`));
+// Default color palette for distinguishing multiple vector layers
+export const VECTOR_PALETTE = [
+    `#e74c3c`,
+    `#3498db`,
+    `#2ecc71`,
+    `#f39c12`,
+    `#9b59b6`,
+    `#1abc9c`,
+];
+// Single key → null color (semantic coloring); multiple keys → palette colors.
+export const default_vector_configs = (keys) => Object.fromEntries(keys.map((key, idx) => [
+    key,
+    {
+        visible: true,
+        color: keys.length > 1 ? VECTOR_PALETTE[idx % VECTOR_PALETTE.length] : null,
+        scale: null,
+    },
+]));
+function try_parse_vec3(val) {
+    if (Array.isArray(val) &&
+        val.length === 3 &&
+        val.every((elem) => typeof elem === `number` && isFinite(elem)))
+        return val;
+    if (typeof val === `number` && isFinite(val))
+        return [0, 0, val];
+    return null;
+}
+// Priority index for ordering: bare names first in VECTOR_KEY_PREFIXES order,
+// then prefixed keys in the same prefix order, alphabetically within each prefix group.
+function vector_key_sort_order(key) {
+    for (const [prefix_idx, prefix] of VECTOR_KEY_PREFIXES.entries()) {
+        if (key === prefix)
+            return [prefix_idx, 0, ``];
+        if (key.startsWith(`${prefix}_`))
+            return [prefix_idx, 1, key];
+    }
+    return [VECTOR_KEY_PREFIXES.length, 0, key];
+}
+function compare_vector_keys(left, right) {
+    const ord_l = vector_key_sort_order(left);
+    const ord_r = vector_key_sort_order(right);
+    return ord_l[0] - ord_r[0] || ord_l[1] - ord_r[1] || ord_l[2].localeCompare(ord_r[2]);
+}
+// Extract ALL vector properties from a site (not just the first match).
+// Returns entries for every key that is_vector_key() and has a valid 3D vector value.
+// Ordered by VECTOR_KEY_PREFIXES priority, then alphabetically for prefixed keys.
+export function get_all_site_vectors(site) {
+    const props = site.properties;
+    if (!props)
+        return [];
+    const results = [];
+    for (const key of Object.keys(props)) {
+        if (!is_vector_key(key))
+            continue;
+        const vec = try_parse_vec3(props[key]);
+        if (vec)
+            results.push({ vec, key });
+    }
+    return results.sort((left, right) => compare_vector_keys(left.key, right.key));
+}
+// Collect the union of all vector property keys across all sites in a structure,
+// preserving VECTOR_KEY_PREFIXES priority order.
+export function get_structure_vector_keys(structure) {
+    const seen = new Set();
+    for (const site of structure.sites) {
+        for (const { key } of get_all_site_vectors(site))
+            seen.add(key);
+    }
+    return [...seen].sort(compare_vector_keys);
+}

package/dist/structure/label-placement.d.ts

@@ -0,0 +1,14 @@
+import type { Vec3 } from '../math';
+import type { Camera, Object3D } from 'three';
+export declare const LABEL_OFFSET_EPS = 1e-9;
+type LabelOffsetSource = Vec3 | (() => Vec3);
+export declare const choose_site_label_offset: (bond_directions: Vec3[], base_offset: Vec3) => Vec3;
+export declare const label_screen_position: (atom_position: Vec3, label_offset: Vec3, visual_radius: number, label_screen_margin: number, label_camera: Camera, size: {
+    width: number;
+    height: number;
+}) => [number, number];
+export declare const make_label_position_calculator: (_atom_position: Vec3, label_offset: LabelOffsetSource, visual_radius: number, label_screen_margin: number) => (object: Object3D, label_camera: Camera, size: {
+    width: number;
+    height: number;
+}) => [number, number];
+export {};

package/dist/structure/label-placement.js

@@ -0,0 +1,72 @@
+import * as math from '../math';
+import { Vector3 } from 'three';
+export const LABEL_OFFSET_EPS = 1e-9;
+const LABEL_OFFSET_DIRECTIONS = [
+    [0, -1, 0],
+    [1, 0, 0],
+    [-1, 0, 0],
+    [1, 1, 0],
+    [-1, 1, 0],
+    [1, -1, 0],
+    [-1, -1, 0],
+    [0, 0, 1],
+    [0, 0, -1],
+];
+const label_direction_score = (direction, bond_directions, preferred_direction) => {
+    let max_bond_alignment = 0;
+    for (const bond_direction of bond_directions) {
+        max_bond_alignment = Math.max(max_bond_alignment, Math.max(0, math.dot(direction, bond_direction)));
+    }
+    const preferred_bonus = Math.max(0, math.dot(direction, preferred_direction)) * 0.05;
+    const screen_plane_bonus = Math.abs(direction[2]) < LABEL_OFFSET_EPS ? 0.02 : 0;
+    return -max_bond_alignment + preferred_bonus + screen_plane_bonus;
+};
+export const choose_site_label_offset = (bond_directions, base_offset) => {
+    const offset_length = Math.hypot(...base_offset);
+    if (offset_length < LABEL_OFFSET_EPS || bond_directions.length === 0) {
+        return base_offset;
+    }
+    const preferred_direction = math.normalize_vec(base_offset, [0, 1, 0]);
+    const repulsion_direction = math.normalize_vec(bond_directions.reduce((offset_sum, bond_direction) => math.subtract(offset_sum, bond_direction), [0, 0, 0]), preferred_direction);
+    let best_direction = preferred_direction;
+    let best_score = -Infinity;
+    for (const candidate_direction of [
+        preferred_direction,
+        repulsion_direction,
+        ...LABEL_OFFSET_DIRECTIONS,
+    ]) {
+        const direction = math.normalize_vec(candidate_direction, preferred_direction);
+        const score = label_direction_score(direction, bond_directions, preferred_direction);
+        if (score <= best_score + LABEL_OFFSET_EPS)
+            continue;
+        best_score = score;
+        best_direction = direction;
+    }
+    return math.scale(best_direction, offset_length);
+};
+const project_to_screen = (position, label_camera, size) => {
+    const projected = new Vector3(...position).project(label_camera);
+    return [
+        (projected.x * size.width) / 2 + size.width / 2,
+        (-projected.y * size.height) / 2 + size.height / 2,
+    ];
+};
+export const label_screen_position = (atom_position, label_offset, visual_radius, label_screen_margin, label_camera, size) => {
+    const atom_screen = project_to_screen(atom_position, label_camera, size);
+    const offset_screen = project_to_screen(math.add(atom_position, label_offset), label_camera, size);
+    const offset_x = offset_screen[0] - atom_screen[0];
+    const offset_y = offset_screen[1] - atom_screen[1];
+    const offset_length = Math.hypot(offset_x, offset_y);
+    const direction_x = offset_length > LABEL_OFFSET_EPS ? offset_x / offset_length : 0;
+    const direction_y = offset_length > LABEL_OFFSET_EPS ? offset_y / offset_length : label_offset[1] >= 0 ? -1 : 1;
+    const radius_direction = math.normalize_vec(label_offset, [0, 1, 0]);
+    const radius_edge = math.add(atom_position, math.scale(radius_direction, visual_radius));
+    const radius_screen = project_to_screen(radius_edge, label_camera, size);
+    const atom_screen_radius = Math.hypot(radius_screen[0] - atom_screen[0], radius_screen[1] - atom_screen[1]);
+    const screen_gap = atom_screen_radius + label_screen_margin;
+    return [atom_screen[0] + direction_x * screen_gap, atom_screen[1] + direction_y * screen_gap];
+};
+export const make_label_position_calculator = (_atom_position, label_offset, visual_radius, label_screen_margin) => (object, label_camera, size) => {
+    const world_position = object.getWorldPosition(new Vector3());
+    return label_screen_position([world_position.x, world_position.y, world_position.z], typeof label_offset === `function` ? label_offset() : label_offset, visual_radius, label_screen_margin, label_camera, size);
+};

package/dist/structure/measure.d.ts

@@ -0,0 +1,7 @@
+import type { LatticeConverters, Matrix3x3, Vec3 } from '../math';
+import type { Pbc } from './pbc';
+export type AngleMode = `degrees` | `radians`;
+export declare const MAX_SELECTED_SITES = 8;
+export declare function displacement_pbc(from: Vec3, to: Vec3, lattice_matrix: Matrix3x3 | null | undefined, converters?: LatticeConverters, pbc?: Pbc): Vec3;
+export declare function distance_pbc(a: Vec3, b: Vec3, lattice_matrix: Matrix3x3, converters?: LatticeConverters, pbc?: Pbc): number;
+export declare function angle_between_vectors(v1: Vec3, v2: Vec3, mode?: AngleMode): number;

package/dist/structure/measure.js

@@ -0,0 +1,30 @@
+// functions for measuring distances and angles between structure sites
+import { min_image_displacement, subtract } from '../math';
+export const MAX_SELECTED_SITES = 8;
+// Calculate minimum image displacement between two points under PBC
+// If lattice_matrix is null/undefined, returns Euclidean displacement.
+// pbc flags disable wrapping along non-periodic axes (e.g. slab vacuum directions).
+export function displacement_pbc(from, to, lattice_matrix, converters, pbc) {
+    if (!lattice_matrix)
+        return subtract(to, from);
+    return min_image_displacement(from, to, lattice_matrix, converters, pbc);
+}
+export function distance_pbc(a, b, lattice_matrix, converters, pbc) {
+    const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix, converters, pbc);
+    return Math.hypot(dx, dy, dz);
+}
+export function angle_between_vectors(v1, v2, mode = `degrees`) {
+    const n1 = Math.hypot(v1[0], v1[1], v1[2]);
+    const n2 = Math.hypot(v2[0], v2[1], v2[2]);
+    if (n1 === 0 || n2 === 0)
+        return 0;
+    // Dot product of vectors
+    const dot = v1[0] * v2[0] + v1[1] * v2[1] + v1[2] * v2[2];
+    // Normalize dot product to get cosine
+    const cos_angle = dot / (n1 * n2);
+    // Clamp to [-1, 1] to avoid numerical errors with acos
+    const clamped = Math.max(-1, Math.min(1, cos_angle));
+    // Compute angle using arccos
+    const ang = Math.acos(clamped);
+    return mode === `degrees` ? (ang * 180) / Math.PI : ang;
+}

package/dist/structure/parse.d.ts

@@ -0,0 +1,66 @@
+import type { OptimadeStructure } from '../api/optimade';
+import * as math from '../math';
+import type { AnyStructure, Crystal, Site, StructureProperties } from './';
+import type { Pbc } from './pbc';
+export interface ParsedStructure {
+    sites: Site[];
+    properties?: StructureProperties;
+    lattice?: {
+        matrix: math.Matrix3x3;
+        a: number;
+        b: number;
+        c: number;
+        alpha: number;
+        beta: number;
+        gamma: number;
+        volume: number;
+        pbc?: Pbc;
+    };
+}
+export interface PhonopyCell {
+    lattice: number[][];
+    points: {
+        symbol: string;
+        coordinates: number[];
+        mass: number;
+        reduced_to?: number;
+    }[];
+    reciprocal_lattice?: number[][];
+}
+export interface PhonopyData {
+    phono3py?: {
+        version: string;
+        [key: string]: unknown;
+    };
+    phonopy?: {
+        version: string;
+        [key: string]: unknown;
+    };
+    space_group?: {
+        type: string;
+        number: number;
+        Hall_symbol: string;
+    };
+    primitive_cell?: PhonopyCell;
+    unit_cell?: PhonopyCell;
+    supercell?: PhonopyCell;
+    phonon_primitive_cell?: PhonopyCell;
+    phonon_supercell?: PhonopyCell;
+    phonon_displacements?: unknown[];
+    [key: string]: unknown;
+}
+export declare function parse_poscar(content: string): ParsedStructure | null;
+export declare function parse_xyz(content: string): ParsedStructure | null;
+export declare function parse_cif(content: string, wrap_fractional_coords?: boolean, strict?: boolean): ParsedStructure | null;
+export type CellType = `primitive_cell` | `unit_cell` | `supercell` | `phonon_primitive_cell` | `phonon_supercell` | `auto`;
+export declare function parse_phonopy_yaml(content: string, cell_type?: CellType): ParsedStructure | null;
+export declare function normalize_fractional_coords(structure: ParsedStructure): ParsedStructure;
+export declare function parse_structure_file(content: string, filename?: string): ParsedStructure | null;
+export declare function parse_any_structure(content: string, filename: string): AnyStructure | null;
+export declare function parse_optimade_json(content: string): ParsedStructure | null;
+export declare function parse_optimade_from_raw(raw: unknown): ParsedStructure | null;
+export declare function is_optimade_json(content: string): boolean;
+export declare const is_optimade_raw: (raw: unknown) => boolean;
+export declare function optimade_to_crystal(optimade_structure: OptimadeStructure): Crystal | null;
+export declare function is_structure_file(filename: string): boolean;
+export declare const detect_structure_type: (filename: string, content: string) => `crystal` | `molecule` | `unknown`;