matterviz 0.1.0

package/dist/trajectory/plotting.d.ts

@@ -0,0 +1,12 @@
+import type { DataSeries } from '../plot';
+import type { Trajectory, TrajectoryDataExtractor } from './index';
+export declare const Y2_PROPERTIES: Set<string>;
+export interface PlotSeriesOptions {
+    property_labels?: Record<string, string>;
+    units?: Record<string, string>;
+    colors?: string[];
+    y2_properties?: Set<string>;
+    default_visible_properties?: Set<string>;
+}
+export declare function generate_plot_series(trajectory: Trajectory, data_extractor: TrajectoryDataExtractor, options?: PlotSeriesOptions): DataSeries[];
+export declare function should_hide_plot(trajectory: Trajectory | undefined, plot_series: DataSeries[], tolerance?: number): boolean;

package/dist/trajectory/plotting.js

@@ -0,0 +1,148 @@
+// Plotting utilities for trajectory visualization
+import { plot_colors } from '../colors';
+import { get_clean_label } from '../labels';
+// Properties that should be assigned to the secondary y-axis
+export const Y2_PROPERTIES = new Set([
+    `force_max`,
+    `force_norm`,
+    `stress_max`,
+    `stress_frobenius`,
+    `volume`,
+    `density`,
+    `pressure`,
+    `temperature`,
+]);
+// Generate plot data series from trajectory
+export function generate_plot_series(trajectory, data_extractor, options = {}) {
+    if (!trajectory || trajectory.frames.length === 0)
+        return [];
+    const { property_labels, units, colors = plot_colors, y2_properties = Y2_PROPERTIES, default_visible_properties = new Set([`energy`, `force_max`, `stress_frobenius`]), } = options;
+    // Single pass: extract data and detect constants simultaneously
+    const property_data = new Map();
+    // Extract data from all frames in a single pass
+    trajectory.frames.forEach((frame) => {
+        const data = data_extractor(frame, trajectory);
+        for (const [key, value] of Object.entries(data)) {
+            // Skip non-numeric values, step, and marker properties
+            if (typeof value !== `number` || key === `Step` || key.startsWith(`_constant_`)) {
+                continue;
+            }
+            if (!property_data.has(key)) {
+                property_data.set(key, {
+                    values: [],
+                    sum: 0,
+                    sum_squares: 0,
+                    min: value,
+                    max: value,
+                });
+            }
+            const prop = property_data.get(key);
+            if (!prop)
+                continue;
+            prop.values.push(value);
+            prop.sum += value;
+            prop.sum_squares += value * value;
+            prop.min = Math.min(prop.min, value);
+            prop.max = Math.max(prop.max, value);
+        }
+    });
+    // Filter out constant properties and create series
+    const series = [];
+    let color_idx = 0;
+    for (const [key, prop] of property_data) {
+        const n = prop.values.length;
+        if (n <= 1)
+            continue;
+        // Fast constant detection using coefficient of variation
+        const mean = prop.sum / n;
+        const variance = (prop.sum_squares - prop.sum * prop.sum / n) / n;
+        const coefficient_of_variation = Math.abs(mean) > 1e-10
+            ? Math.sqrt(variance) / Math.abs(mean)
+            : Math.sqrt(variance);
+        const lower_key = key.toLowerCase();
+        const is_energy = lower_key === `energy`;
+        const has_significant_variation = coefficient_of_variation >= 1e-6;
+        // Skip properties with very low variation (effectively constant)
+        // Exception: always include energy regardless of variation
+        if (!has_significant_variation && !is_energy) {
+            continue;
+        }
+        // Create series data
+        const x_values = Array.from({ length: n }, (_, idx) => idx);
+        const y_values = prop.values;
+        const color = colors[color_idx % colors.length];
+        const y_axis = y2_properties.has(lower_key) ? `y2` : `y1`;
+        // For energy: only visible by default if it has significant variation
+        // For other properties: use the normal default visibility logic
+        const is_default_visible = is_energy
+            ? has_significant_variation &&
+                (default_visible_properties.has(lower_key) || default_visible_properties.has(key))
+            : (default_visible_properties.has(lower_key) || default_visible_properties.has(key));
+        // Extract unit and create clean label
+        const unit = units?.[lower_key] || units?.[key] || ``;
+        const clean_label = get_clean_label(key, property_labels);
+        const full_label = unit ? `${clean_label} (${unit})` : clean_label;
+        series.push({
+            x: x_values,
+            y: y_values,
+            label: full_label,
+            unit,
+            y_axis,
+            visible: is_default_visible,
+            markers: n < 30 ? `line+points` : `line`,
+            metadata: x_values.map(() => ({ series_label: full_label })),
+            line_style: {
+                stroke: color,
+                stroke_width: 2,
+            },
+            point_style: {
+                fill: color,
+                radius: 4,
+                stroke: color,
+                stroke_width: 1,
+            },
+        });
+        color_idx++;
+    }
+    // Fallback visibility for volume/density if no priority properties are visible
+    const has_visible_priority = series.some((s) => s.visible &&
+        ![`volume`, `density`].some((prop) => s.label?.toLowerCase().includes(prop)));
+    if (!has_visible_priority) {
+        series.forEach((s) => {
+            const label_lower = s.label?.toLowerCase() || ``;
+            if (label_lower.includes(`volume`) || label_lower.includes(`density`)) {
+                s.visible = true;
+            }
+        });
+    }
+    // Sort by visibility for legend ordering
+    series.sort((a, b) => Number(b.visible) - Number(a.visible));
+    return series;
+}
+// Check if all plotted values are constant (should hide plot)
+export function should_hide_plot(trajectory, plot_series, tolerance = 1e-10) {
+    if (!trajectory || trajectory.frames.length <= 1)
+        return false;
+    // If there are no series to plot, hide the plot
+    if (plot_series.length === 0)
+        return true;
+    // Get all visible series, and if none are visible, check fallback properties
+    let visible_series = plot_series.filter((s) => s.visible);
+    // If no explicit properties are visible, fall back to volume and density if they exist
+    if (visible_series.length === 0) {
+        const fallback_properties = [`volume`, `density`];
+        visible_series = plot_series.filter((s) => fallback_properties.some((prop) => s.label?.toLowerCase().includes(prop.toLowerCase())));
+    }
+    if (visible_series.length === 0)
+        return true;
+    for (const series of visible_series) {
+        if (series.y.length <= 1)
+            continue;
+        const first_value = series.y[0];
+        const has_variation = series.y.some((value) => Math.abs(value - first_value) > tolerance);
+        if (has_variation) {
+            return false; // Found variation, don't hide plot
+        }
+    }
+    return true; // All series are constant, hide plot
+}

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Janosh Riebesell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The software is provided "as is", without warranty of any kind, express or
+implied, including but not limited to the warranties of merchantability,
+fitness for a particular purpose and noninfringement. In no event shall the
+authors or copyright holders be liable for any claim, damages or other
+liability, whether in an action of contract, tort or otherwise, arising from,
+out of or in connection with the software or the use or other dealings in the
+software.

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "matterviz",
+  "description": "Interactive visualizations for materials science: periodic tables, 3D structures, MD trajectories, heatmaps, scatter plots.",
+  "author": "Janosh Riebesell <janosh.riebesell@gmail.com>",
+  "homepage": "https://janosh.github.io/matterviz",
+  "repository": "https://github.com/janosh/matterviz",
+  "license": "MIT",
+  "version": "0.1.0",
+  "type": "module",
+  "svelte": "./dist/index.js",
+  "bugs": "https://github.com/janosh/matterviz/issues",
+  "dependencies": {
+    "@sveltejs/kit": "^2.21.5",
+    "@threlte/core": "8.0.5",
+    "@threlte/extras": "^9.3.0",
+    "@types/d3-force": "^3.0.10",
+    "@types/d3-hierarchy": "^3.1.7",
+    "@types/js-yaml": "^4.0.9",
+    "d3": "^7.9.0",
+    "d3-array": "^3.2.4",
+    "d3-color": "^3.1.0",
+    "d3-force": "^3.0.0",
+    "d3-format": "^3.1.0",
+    "d3-hierarchy": "^3.1.2",
+    "d3-interpolate-path": "^2.3.0",
+    "d3-scale": "^4.0.2",
+    "d3-scale-chromatic": "^3.1.0",
+    "d3-shape": "^3.2.0",
+    "h5wasm": "^0.8.1",
+    "highlight.js": "^11.11.1",
+    "js-yaml": "^4.1.0",
+    "svelte": "5.34.3",
+    "svelte-multiselect": "11.1.1",
+    "svelte-zoo": "^0.4.19",
+    "three": "^0.177.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.53.0",
+    "@rollup/plugin-yaml": "^4.1.2",
+    "@stylistic/eslint-plugin": "^4.4.1",
+    "@sveltejs/adapter-static": "3.0.8",
+    "@sveltejs/package": "^2.3.11",
+    "@sveltejs/vite-plugin-svelte": "^5.1.0",
+    "@types/d3-array": "^3.2.1",
+    "@types/d3-color": "^3.1.3",
+    "@types/d3-format": "^3.0.4",
+    "@types/d3-interpolate-path": "^2.0.3",
+    "@types/d3-scale": "^4.0.9",
+    "@types/d3-scale-chromatic": "^3.1.0",
+    "@types/d3-shape": "^3.1.7",
+    "@types/d3-time-format": "^4.0.3",
+    "@types/three": "^0.177.0",
+    "@vitest/coverage-v8": "^3.2.3",
+    "d3-time-format": "^4.1.0",
+    "eslint": "^9.29.0",
+    "eslint-plugin-svelte": "^3.9.2",
+    "happy-dom": "^18.0.1",
+    "hastscript": "^9.0.1",
+    "mdsvex": "^0.12.6",
+    "mdsvexamples": "^0.5.0",
+    "prettier": "^3.5.3",
+    "prettier-plugin-svelte": "^3.4.0",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-katex": "^7.0.1",
+    "rehype-slug": "^6.0.0",
+    "remark-math": "3.0.1",
+    "sharp": "^0.34.2",
+    "svelte-check": "^4.2.1",
+    "svelte-preprocess": "^6.0.3",
+    "svelte-toc": "^0.6.1",
+    "svelte2tsx": "^0.7.39",
+    "typescript": "5.8.3",
+    "typescript-eslint": "^8.34.1",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.3"
+  },
+  "keywords": [
+    "svelte",
+    "periodic table",
+    "chemistry",
+    "data viz",
+    "plotting",
+    "component"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./element/data": {
+      "types": "./dist/element/data.d.ts",
+      "default": "./dist/element/data.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./composition": {
+      "types": "./dist/composition.d.ts",
+      "default": "./dist/composition.js"
+    },
+    "./colors": {
+      "types": "./dist/colors.d.ts",
+      "default": "./dist/colors.js"
+    },
+    "./io": {
+      "types": "./dist/io.d.ts",
+      "default": "./dist/io.js"
+    },
+    "./labels": {
+      "types": "./dist/labels.d.ts",
+      "default": "./dist/labels.js"
+    },
+    "./math": {
+      "types": "./dist/math.d.ts",
+      "default": "./dist/math.js"
+    },
+    "./periodic-table": {
+      "types": "./dist/periodic-table.d.ts",
+      "default": "./dist/periodic-table.js"
+    },
+    "./plot": {
+      "types": "./dist/plot.d.ts",
+      "default": "./dist/plot.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ]
+}

package/readme.md

@@ -0,0 +1,95 @@
+<h1 align="center">
+  <img src="static/logo.svg" alt="Logo" height="100">
+</h1>
+
+<h4 align="center">
+
+[![Tests](https://github.com/janosh/matterviz/actions/workflows/test.yml/badge.svg)](https://github.com/janosh/matterviz/actions/workflows/test.yml)
+[![GH Pages](https://github.com/janosh/matterviz/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/janosh/matterviz/actions/workflows/gh-pages.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/janosh/matterviz/main.svg?badge_token=nUqJfPCFS4uyMwcFSDIfdQ)](https://results.pre-commit.ci/latest/github/janosh/matterviz/main?badge_token=nUqJfPCFS4uyMwcFSDIfdQ)
+[![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=stackblitz)](https://stackblitz.com/github/janosh/matterviz)
+
+</h4>
+
+`matterviz` is a toolkit for building interactive web UIs for materials science: periodic tables, 3d crystal structures (and molecules, though needs some improvements!), Bohr atoms, nuclei, heatmaps, scatter plots. It's under active development and not yet ready for production use but we appreciate any feedback from beta testers! 🙏
+
+![Screenshot of landing page](static/2023-02-13-landing-page.webp)
+
+## 📦 &thinsp; Heatmap
+
+This screenshot demonstrates the periodicity of elemental properties (i.e. why it's called periodic table). In this case, you're seeing recurring bumps and valleys in the first ionization energy as a function of atomic number.
+
+![Screenshot of periodic table heatmap](static/2023-02-13-heatmap.webp)
+
+## ⚛️ &thinsp; 3D Structure Viewer
+
+![3D Structure Viewer](https://github.com/janosh/matterviz/assets/30958850/72f78ad8-16fc-4eab-84ca-a985ce27e2b1)
+
+## ⚛️ &thinsp; Element Details Pages
+
+The details page for gold.
+
+<https://user-images.githubusercontent.com/30958850/186975855-8e0d94f9-e4e3-47a2-9354-9c012b37307c.mp4>
+
+## 🔨 &thinsp; Installation
+
+```sh
+npm install --dev matterviz
+```
+
+## 📙 &thinsp; Usage
+
+Import the `PeriodicTable` component and pass it some heatmap values:
+
+```svelte
+<script>
+  import { PeriodicTable } from 'matterviz'
+
+  const heatmap_values = { H: 10, He: 4, Li: 8, Fe: 3, O: 24 }
+</script>
+
+<PeriodicTable {heatmap_values} />
+```
+
+## 🎬 &thinsp; Events
+
+`PeriodicTable.svelte` forwards the following events from each `ElementTile`:
+
+1. `click`
+1. `mouseenter`
+1. `mouseleave`
+1. `keyup`
+1. `keydown`
+
+Each event is a Svelte `dispatch` event with the following `detail` payload:
+
+```ts
+detail: {
+  element: ChemicalElement
+  active: boolean // whether the event target tile is currently active
+  dom_event: Event // the DOM event that triggered the Svelte dispatch
+}
+```
+
+See `DispatchPayload` and `PeriodicTableEvents` in `src/lib/index.ts`
+
+## 🧪 &thinsp; Coverage
+
+| Statements                                                                                 | Branches                                                                          | Lines                                                                            |
+| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| ![Statements](https://img.shields.io/badge/statements-99.84%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-82.92%25-yellow.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-99.84%25-brightgreen.svg?style=flat) |
+
+## 🙏 &thinsp; Acknowledgements
+
+- Element properties in `src/lib/element-data.ts` were combined from [`Bowserinator/Periodic-Table-JSON`](https://github.com/Bowserinator/Periodic-Table-JSON/blob/master/PeriodicTableJSON.json) under Creative Commons license and [`robertwb/Periodic Table of Elements.csv`](https://gist.github.com/robertwb/22aa4dbfb6bcecd94f2176caa912b952) (unlicensed).
+- Thanks to [Images of Elements](https://images-of-elements.com) for providing photos of elemental crystals and glowing excited gases.
+- Thanks to [@kadinzhang](https://github.com/kadinzhang) and their [Periodicity project](https://ptable.netlify.app) [[code](https://github.com/kadinzhang/Periodicity)] for the idea to display animated Bohr model atoms and inset a scatter plot into the periodic table to visualize the periodic nature of elemental properties.
+- Big thanks to all sources of element images. See [`fetch-elem-images.ts`](https://github.com/janosh/matterviz/blob/-/src/fetch-elem-images.ts) and [`static/elements`](https://github.com/janosh/matterviz/tree/main/static/elements).
+- Thanks to [@ixxie](https://github.com/ixxie) ([shenhav.fyi](https://shenhav.fyi)) for a lot of great suggestions, UX ideas, helping me learn [`threlte`](https://threlte.xyz) and contributing the [`Bond.svelte`](https://github.com/janosh/matterviz/blob/-/src/lib/structure/Bond.svelte) component.
+
+This project would not have been possible as a one-person side project without many fine open-source projects. 🙏 To name just a few:
+
+|           3D graphics           |               2D graphics                |                     Docs                     |               Bundler               |               Testing                |
+| :-----------------------------: | :--------------------------------------: | :------------------------------------------: | :---------------------------------: | :----------------------------------: |
+| [three.js](https://threejs.org) |          [d3](https://d3js.org)          |         [mdsvex](https://mdsvex.com)         |     [vite](https://vitejs.dev)      | [playwright](https://playwright.dev) |
+| [threlte](https://threlte.xyz)  | [sharp](https://sharp.pixelplumbing.com) | [rehype](https://github.com/rehypejs/rehype) | [sveltekit](https://kit.svelte.dev) |     [vitest](https://vitest.dev)     |