matterviz 0.3.6 → 0.4.0

package/dist/composition/parse.d.ts

@@ -0,0 +1,56 @@
+import type { ElementSymbol } from '../element';
+import type { CompositionType } from './';
+export declare const ATOMIC_NUMBER_TO_SYMBOL: Record<number, ElementSymbol>;
+export declare const SYMBOL_TO_ATOMIC_NUMBER: Partial<CompositionType>;
+export declare const ATOMIC_WEIGHTS: Map<"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 const ELEMENT_ELECTRONEGATIVITY_MAP: Map<"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 const ELEM_NAME_TO_SYMBOL: Record<string, ElementSymbol>;
+export declare const ELEM_SYMBOL_TO_NAME: Partial<Record<ElementSymbol, string>>;
+export declare const is_valid_element: (sym: string) => sym is ElementSymbol;
+export declare const atomic_num_to_symbols: (atomic_composition: Record<number, number>) => CompositionType;
+export declare const atomic_symbol_to_num: (symbol_composition: CompositionType) => Record<number, number>;
+export declare const parse_formula: (formula: string) => CompositionType;
+export declare const normalize_composition: (composition: CompositionType | Record<number, number> | Record<string | number, number>) => CompositionType;
+export declare const sanitize_composition_keys: (composition: Record<string, number>) => CompositionType | null;
+export declare const count_atoms_in_composition: (composition: CompositionType) => number;
+export declare const fractional_composition: (composition: CompositionType, by_weight?: boolean) => CompositionType;
+export declare const parse_composition: (input: string | CompositionType | Record<number, number> | Record<string | number, number>) => CompositionType;
+export declare const get_reduced_formula: (composition: CompositionType) => CompositionType;
+export declare const get_molecular_weight: (composition: CompositionType) => number;
+export type ElementWithOxidation = {
+    element: ElementSymbol;
+    amount: number;
+    oxidation_state?: number;
+    orig_idx: number;
+};
+export type OxiComposition = Record<ElementSymbol, {
+    amount: number;
+    oxidation_state?: number;
+}>;
+export declare const parse_formula_with_oxidation: (formula: string, strict?: boolean) => ElementWithOxidation[];
+export declare const oxi_composition_to_elements: (composition: OxiComposition) => ElementWithOxidation[];
+export declare function extract_formula_elements(formula: string, { unique, sorted }?: {
+    unique?: boolean;
+    sorted?: boolean;
+}): ElementSymbol[];
+export declare function generate_chem_sys_subspaces(input: string | CompositionType | ElementSymbol[]): string[];
+export declare function normalize_element_symbols(csv: string): ElementSymbol[];
+export declare function normalize_element_symbols<T extends string>(csv: string, all_symbols: T[]): T[];
+export type WildcardFormulaToken = {
+    element: ElementSymbol | null;
+    count: number;
+};
+export type ChemsysWithWildcards = {
+    elements: ElementSymbol[];
+    wildcard_count: number;
+};
+export declare const has_wildcards: (input: string) => boolean;
+export declare function parse_chemsys_with_wildcards(input: string): ChemsysWithWildcards;
+export declare const ELEM_WILDCARD: {
+    readonly placeholder: "Zz";
+    readonly to_placeholder: RegExp;
+    readonly from_placeholder: RegExp;
+};
+export declare function parse_formula_with_wildcards(formula: string): WildcardFormulaToken[];
+export declare function matches_chemsys_wildcard(formula: string, explicit_elements: string[], wildcard_count: number): boolean;
+export declare function matches_formula_wildcard(formula: string, pattern: WildcardFormulaToken[]): boolean;

package/dist/composition/parse.js

@@ -0,0 +1,486 @@
+import { element_data } from '../element';
+import { ELEM_SYMBOLS } from '../labels';
+// Create symbol/number/mass/electronegativity lookup maps for O(1) access
+export const ATOMIC_NUMBER_TO_SYMBOL = {};
+export const SYMBOL_TO_ATOMIC_NUMBER = {};
+export const ATOMIC_WEIGHTS = new Map();
+export const ELEMENT_ELECTRONEGATIVITY_MAP = new Map();
+export const ELEM_NAME_TO_SYMBOL = {};
+export const ELEM_SYMBOL_TO_NAME = {};
+// Populate maps at module load time
+for (const element of element_data) {
+    ATOMIC_NUMBER_TO_SYMBOL[element.number] = element.symbol;
+    SYMBOL_TO_ATOMIC_NUMBER[element.symbol] = element.number;
+    ATOMIC_WEIGHTS.set(element.symbol, element.atomic_mass);
+    ELEMENT_ELECTRONEGATIVITY_MAP.set(element.symbol, element.electronegativity ?? 0);
+    ELEM_NAME_TO_SYMBOL[element.name] = element.symbol;
+    ELEM_SYMBOL_TO_NAME[element.symbol] = element.name;
+}
+// Type guard: check if a string is a valid element symbol
+export const is_valid_element = (sym) => ELEM_SYMBOLS.includes(sym);
+// Check if object has atomic numbers as keys (1-118)
+const is_atomic_number_composition = (obj) => {
+    const keys = Object.keys(obj);
+    const atomic_nums = keys.map(Number);
+    return (keys.length > 0 &&
+        atomic_nums.every((atomic_num) => Number.isInteger(atomic_num) && Object.hasOwn(ATOMIC_NUMBER_TO_SYMBOL, atomic_num)));
+};
+const format_state = (state) => (state > 0 ? `+` : ``) + state;
+const parse_count = (count) => (count ? parseFloat(count) : 1);
+const format_count = (count) => {
+    if (!Number.isFinite(count))
+        return `${count}`;
+    return Number(count.toPrecision(12)).toLocaleString(`en-US`, {
+        maximumSignificantDigits: 12,
+        useGrouping: false,
+    });
+};
+// Convert atomic numbers to element symbols
+export const atomic_num_to_symbols = (atomic_composition) => {
+    const composition = {};
+    for (const [atomic_num_str, amount] of Object.entries(atomic_composition)) {
+        const symbol = ATOMIC_NUMBER_TO_SYMBOL[Number(atomic_num_str)];
+        if (!symbol)
+            throw new Error(`Invalid atomic number: ${atomic_num_str}`);
+        if (amount > 0)
+            composition[symbol] = (composition[symbol] ?? 0) + amount;
+    }
+    return composition;
+};
+// Convert element symbols to atomic numbers
+export const atomic_symbol_to_num = (symbol_composition) => {
+    const atomic_composition = {};
+    for (const [symbol, amount] of Object.entries(symbol_composition)) {
+        if (!is_valid_element(symbol))
+            throw new Error(`Invalid element symbol: ${symbol}`);
+        const atomic_num = SYMBOL_TO_ATOMIC_NUMBER[symbol];
+        if (!atomic_num)
+            throw new Error(`Invalid element symbol: ${symbol}`);
+        if (amount > 0) {
+            atomic_composition[atomic_num] = (atomic_composition[atomic_num] || 0) + amount;
+        }
+    }
+    return atomic_composition;
+};
+// Expand parentheses in chemical formulas
+const expand_parentheses = (formula) => {
+    while (formula.includes(`(`)) {
+        const expanded = formula.replaceAll(/\(([^()]+)\)(\d+(?:\.\d+)?|\.\d+)?/g, (_match, group, multiplier) => {
+            const mult = parse_count(multiplier);
+            return group.replaceAll(/([A-Z][a-z]?)(\d+(?:\.\d+)?|\.\d+)?/g, (_m, element, count) => {
+                const count_str = format_count(parse_count(count) * mult);
+                return element + (count_str === `1` ? `` : count_str);
+            });
+        });
+        if (expanded === formula) {
+            // unclosed/empty parens match nothing -> would loop forever
+            throw new Error(`Unbalanced or empty parentheses in formula: ${formula}`);
+        }
+        formula = expanded;
+    }
+    return formula;
+};
+// Parse chemical formula string into composition object. Hydrate/adduct segments
+// joined by ·, ⋅, or * are scaled by their leading coefficient (CuSO4·5H2O -> Cu S O9 H10)
+export const parse_formula = (formula) => {
+    const composition = {};
+    const cleaned = formula.replaceAll(/\s/g, ``);
+    const segments = cleaned.split(/[·⋅*]/).filter(Boolean);
+    for (const [seg_idx, segment] of segments.entries()) {
+        // only hydrate segments (after a separator) carry a leading multiplier
+        const coeff = seg_idx > 0 ? /^(?:\d+(?:\.\d+)?|\.\d+)/.exec(segment)?.[0] : undefined;
+        const multiplier = coeff ? parseFloat(coeff) : 1;
+        const expanded = expand_parentheses(segment.slice(coeff?.length ?? 0));
+        for (const match of expanded.matchAll(/([A-Z][a-z]?)(\d+(?:\.\d+)?|\.\d+)?/g)) {
+            const [, element, count] = match;
+            if (!is_valid_element(element))
+                throw new Error(`Invalid element symbol: ${element}`);
+            composition[element] = (composition[element] ?? 0) + parse_count(count) * multiplier;
+        }
+    }
+    return composition;
+};
+// Normalize composition to positive numbers only
+export const normalize_composition = (composition) => {
+    if (is_atomic_number_composition(composition)) {
+        return normalize_composition(atomic_num_to_symbols(composition));
+    }
+    const normalized = {};
+    for (const [element, amount] of Object.entries(composition)) {
+        if (typeof amount === `number` && amount > 0 && is_valid_element(element)) {
+            normalized[element] = amount;
+        }
+    }
+    return normalized;
+};
+// Sanitize composition keys by extracting valid element symbols.
+// Handles malformed keys like "B0.", "Fe2+", "Fe[2+]", "Ca^2+" by extracting
+// the element symbol portion. Merges amounts for keys that map to the same element.
+// Returns null if no valid elements can be extracted.
+// NOTE: Only extracts the FIRST valid element from each key. Keys with multiple
+// elements (e.g. "CO3", "Fe2O3") will lose stoichiometry - use parse_formula for those.
+export const sanitize_composition_keys = (composition) => {
+    const sanitized = {};
+    for (const [key, amount] of Object.entries(composition)) {
+        if (typeof amount !== `number` || amount <= 0)
+            continue;
+        // Extract first valid element symbol from key (e.g. "B0." -> "B", "Fe2+" -> "Fe")
+        const elem = (key.match(/[A-Z][a-z]?/g) ?? []).find(is_valid_element);
+        if (elem)
+            sanitized[elem] = (sanitized[elem] || 0) + amount;
+    }
+    const result = normalize_composition(sanitized);
+    return Object.keys(result).length > 0 ? result : null;
+};
+// Get total number of atoms
+export const count_atoms_in_composition = (composition) => Object.values(composition).reduce((sum, count) => sum + (count ?? 0), 0);
+export const fractional_composition = (composition, by_weight = false) => {
+    // Filter out zero/negative amounts for both branches
+    const filtered = Object.fromEntries(Object.entries(composition).filter(([, amount]) => amount > 0));
+    if (by_weight) {
+        const element_weights = Object.fromEntries(Object.entries(filtered).map(([element, amount]) => {
+            if (!is_valid_element(element))
+                throw new Error(`Unknown element: ${element}`);
+            const atomic_mass = ATOMIC_WEIGHTS.get(element);
+            if (!atomic_mass)
+                throw new Error(`Unknown element: ${element}`);
+            return [element, amount * atomic_mass];
+        }));
+        const total_weight = Object.values(element_weights).reduce((sum, wt) => sum + wt, 0);
+        if (total_weight === 0)
+            return {};
+        return Object.fromEntries(Object.entries(element_weights).map(([element, weight]) => [
+            element,
+            weight / total_weight,
+        ]));
+    }
+    const total = count_atoms_in_composition(filtered);
+    if (total === 0)
+        return {};
+    return Object.fromEntries(Object.entries(filtered).map(([element, amount]) => [element, amount / total]));
+};
+// Parse composition from various input types
+export const parse_composition = (input) => {
+    if (typeof input === `string`) {
+        if (input.trim().startsWith(`{`) && input.trim().endsWith(`}`)) {
+            try {
+                return normalize_composition(JSON.parse(input));
+            }
+            catch {
+                // Fall through to formula parsing
+            }
+        }
+        return normalize_composition(parse_formula(input));
+    }
+    return normalize_composition(input);
+};
+// Calculate GCD of two numbers
+const gcd = (num_a, num_b) => num_b === 0 ? num_a : gcd(num_b, num_a % num_b);
+// Get reduced formula by dividing all amounts by their GCD
+// Example: Fe2O4 -> FeO2, H4O2 -> H2O
+export const get_reduced_formula = (composition) => {
+    const amounts = Object.values(composition).filter((amt) => amt > 0);
+    if (amounts.length === 0)
+        return {};
+    // Find GCD of all amounts (works with integers; for floats, find approximate GCD)
+    const all_integers = amounts.every((amt) => Number.isInteger(amt));
+    if (!all_integers)
+        return composition; // Can't reduce non-integer compositions
+    const divisor = amounts.reduce((acc, amt) => gcd(acc, amt));
+    if (divisor <= 1)
+        return composition;
+    const reduced = {};
+    for (const [elem, amt] of Object.entries(composition)) {
+        if (is_valid_element(elem))
+            reduced[elem] = amt / divisor;
+    }
+    return reduced;
+};
+// Calculate molecular weight (sum of atomic masses * amounts)
+export const get_molecular_weight = (composition) => Object.entries(composition).reduce((total, [elem, amount]) => {
+    const mass = is_valid_element(elem) ? (ATOMIC_WEIGHTS.get(elem) ?? 0) : 0;
+    return total + mass * amount;
+}, 0);
+// Parse oxidation state string (e.g. "+2", "2+", "-", "[2-]") to number
+const parse_oxidation_state = (oxidation_str) => {
+    // Handle bare signs: "+", "-" are treated as ±1
+    if (oxidation_str === `+` || oxidation_str === `-`) {
+        return oxidation_str === `+` ? 1 : -1;
+    }
+    // Handle formats like "2+", "+2", "2-", "-2"
+    const ox_match = /([+-]?)(\d+)([+-]?)/.exec(oxidation_str);
+    if (!ox_match)
+        return 0;
+    const [, sign_before, number, sign_after] = ox_match;
+    const sign = sign_before || sign_after || `+`;
+    return sign === `-` ? -parseInt(number, 10) : parseInt(number, 10);
+};
+// Parse chemical formula string with oxidation states into structured data.
+// Supports both ^2+ and [2+] syntax for oxidation states.
+// Examples: "Fe^2+O3", "Fe[2+]O3", "Ca^2+Cl^-2"
+// Tracks original element order from the input string.
+// When strict=true, throws on conflicting oxidation states for the same element.
+export const parse_formula_with_oxidation = (formula, strict = false) => {
+    const elements = [];
+    const cleaned_formula = expand_parentheses(formula.replaceAll(/\s/g, ``));
+    // Regex to match: Element, optional oxidation state and/or count in either order
+    // Pattern: ([A-Z][a-z]?)  - element symbol
+    //          Followed by one of:
+    //          - oxidation then optional count: (?:\^([+-]?\d+[+-]?|[+-])|\[([+-]?\d+[+-]?|[+-])\])(count?)
+    //          - count then optional oxidation: count(?:\^([+-]?\d+[+-]?|[+-])|\[([+-]?\d+[+-]?|[+-])\])?
+    //          - just oxidation: (?:\^([+-]?\d+[+-]?|[+-])|\[([+-]?\d+[+-]?|[+-])\])
+    //          - just count: count
+    //          - neither
+    const regex = /([A-Z][a-z]?)(?:(?:\^([+-]?\d+[+-]?|[+-])|\[([+-]?\d+[+-]?|[+-])\])((?:\d+(?:\.\d+)?|\.\d+)?)|((?:\d+(?:\.\d+)?|\.\d+))(?:\^([+-]?\d+[+-]?|[+-])|\[([+-]?\d+[+-]?|[+-])\])?)?/g;
+    let match;
+    let orig_idx = 0;
+    while ((match = regex.exec(cleaned_formula)) !== null) {
+        const element = match[1];
+        // Oxidation can be in groups 2/3 (oxidation first) or 6/7 (count first)
+        // Count can be in group 4 (after oxidation) or 5 (before oxidation)
+        const oxidation_str = match[2] || match[3] || match[6] || match[7];
+        const count_str = match[4] || match[5];
+        const count = parse_count(count_str);
+        if (!is_valid_element(element))
+            throw new Error(`Invalid element symbol: ${element}`);
+        const oxidation_state = oxidation_str ? parse_oxidation_state(oxidation_str) : undefined;
+        // Find or add element entry
+        const existing = elements.find((el) => el.element === element);
+        if (existing) {
+            existing.amount += count;
+            // Handle oxidation state conflicts
+            if (oxidation_state === undefined) {
+                // No oxidation state in current match, nothing to do
+            }
+            else if (existing.oxidation_state === undefined) {
+                // Set oxidation state on first occurrence
+                existing.oxidation_state = oxidation_state;
+            }
+            else if (strict && existing.oxidation_state !== oxidation_state) {
+                // In strict mode, throw on conflicting oxidation states
+                throw new Error(`Conflicting oxidation states for ${element}: ${format_state(existing.oxidation_state)} and ${format_state(oxidation_state)}`);
+            }
+        }
+        else {
+            elements.push({ element, amount: count, oxidation_state, orig_idx: orig_idx++ });
+        }
+    }
+    return elements;
+};
+// Convert OxiComposition to ElementWithOxidation array
+// Does not preserve original order since objects don't have a defined order
+export const oxi_composition_to_elements = (composition) => Object.entries(composition).flatMap(([element, { amount, oxidation_state }], idx) => is_valid_element(element) ? [{ element, amount, oxidation_state, orig_idx: idx }] : []);
+// Extract element symbols from a chemical formula.
+// Default (unique=true, sorted=true): "NbZr2Nb" -> ["Nb", "Zr"]
+// unique=false: Fast token extraction preserving order without parentheses expansion
+//   "NbZr2Nb" -> ["Nb", "Zr", "Nb"], "Fe2(SO4)3" -> ["Fe", "S", "O"]
+//   Validates tokens against ELEM_SYMBOLS, filtering out invalid ones.
+// sorted=false: Preserves order of first appearance (only applies when unique=true)
+//   "ZrNb" -> ["Zr", "Nb"]
+export function extract_formula_elements(formula, { unique = true, sorted = true } = {}) {
+    if (!unique) {
+        // Fast path: regex token extraction without parentheses expansion
+        const matches = formula.match(/[A-Z][a-z]?/g) ?? [];
+        const elements = [];
+        for (const match of matches) {
+            if (is_valid_element(match))
+                elements.push(match);
+        }
+        return elements;
+    }
+    const symbols = Object.keys(parse_formula(formula)).filter(is_valid_element);
+    return sorted ? symbols.sort() : symbols;
+}
+// Generate all non-empty subsets of a chemical system as hyphenated strings.
+// Input: formula string, composition object, or element symbol array
+// Output: All subsets sorted alphabetically: ["B", "Mo", "Sc", "B-Mo", "B-Sc", "Mo-Sc", "B-Mo-Sc"]
+// Complexity: O(2^n) where n = number of unique elements (fine for typical ~1-5 elements)
+export function generate_chem_sys_subspaces(input) {
+    let elements;
+    if (typeof input === `string`)
+        elements = extract_formula_elements(input);
+    else if (Array.isArray(input)) {
+        const uniq = [...new Set(input)];
+        for (const elem of uniq) {
+            if (!is_valid_element(elem))
+                throw new Error(`Invalid element symbol: ${elem}`);
+        }
+        elements = uniq;
+    }
+    else {
+        elements = [];
+        for (const elem of Object.keys(input)) {
+            if (!is_valid_element(elem))
+                throw new Error(`Invalid element symbol: ${elem}`);
+            elements.push(elem);
+        }
+    }
+    const sorted = [...elements].sort();
+    const subspaces = [];
+    const subset_count = 2 ** sorted.length;
+    for (let mask = 1; mask < subset_count; mask++) {
+        const subset = [];
+        for (let idx = 0; idx < sorted.length; idx++) {
+            if (mask & (1 << idx))
+                subset.push(sorted[idx]);
+        }
+        subspaces.push(subset.join(`-`));
+    }
+    return subspaces;
+}
+export function normalize_element_symbols(csv, all_symbols) {
+    const input_set = new Set(csv
+        .split(`,`)
+        .map((sym) => sym.trim())
+        .filter(Boolean));
+    const symbols = all_symbols ?? ELEM_SYMBOLS;
+    return symbols.filter((sym) => input_set.has(sym));
+}
+// Check if input contains wildcard elements (*).
+// Works for both chemsys format (Li-Fe-*-*) and exact formula format (LiFe*2*).
+export const has_wildcards = (input) => input.includes(`*`);
+// Parse chemsys format with wildcards: "Li-Fe-*-*" -> { elements: ["Li", "Fe"], wildcard_count: 2 }
+// Accepts both hyphen and comma separators.
+// Throws if any non-wildcard token is not a valid element symbol.
+export function parse_chemsys_with_wildcards(input) {
+    const tokens = input
+        .replaceAll('-', `,`)
+        .split(`,`)
+        .map((tok) => tok.trim())
+        .filter(Boolean);
+    const elements = [];
+    let wildcard_count = 0;
+    for (const token of tokens) {
+        if (token === `*`) {
+            wildcard_count++;
+        }
+        else if (is_valid_element(token)) {
+            elements.push(token);
+        }
+        else {
+            throw new Error(`Invalid element symbol or wildcard: ${token}`);
+        }
+    }
+    return { elements: elements.sort(), wildcard_count };
+}
+// Placeholder for wildcards during parentheses expansion (Zz is not a real element symbol).
+// Use static regex literals to avoid escaping issues if placeholder ever changes.
+export const ELEM_WILDCARD = {
+    placeholder: `Zz`,
+    to_placeholder: /\*/g,
+    from_placeholder: /Zz/g,
+};
+// Parse exact formula with wildcards: "LiFe*2*" -> [{ element: "Li", count: 1 }, { element: "Fe", count: 1 }, { element: null, count: 2 }, { element: null, count: 1 }]
+// The * character represents any element, optionally followed by a count.
+// Each * in the pattern represents a distinct element position (wildcards cannot share elements).
+// Examples:
+//   "LiFe*2*" -> Li(1), Fe(1), *(2), *(1) - matches formulas with 4 distinct elements
+//   "*2O3" -> *(2), O(3) - matches any binary oxide with 2:3 ratio
+//   "**O4" -> *(1), *(1), O(4) - matches ternary oxides with 1:1:4 ratio
+export function parse_formula_with_wildcards(formula) {
+    const tokens = [];
+    // Expand parentheses, treating * as a pseudo-element (temporarily replace to protect it)
+    let cleaned = formula.replaceAll(/\s/g, ``);
+    // Protect wildcards from parentheses expansion by replacing * with placeholder
+    cleaned = cleaned.replace(ELEM_WILDCARD.to_placeholder, ELEM_WILDCARD.placeholder);
+    cleaned = expand_parentheses(cleaned);
+    // Restore wildcards
+    cleaned = cleaned.replace(ELEM_WILDCARD.from_placeholder, `*`);
+    // Regex to match either:
+    // 1. Standard element symbol with optional decimal count
+    // 2. Wildcard with optional decimal count
+    const regex = /([A-Z][a-z]?)((?:\d+(?:\.\d+)?|\.\d+)?)|(\*)((?:\d+(?:\.\d+)?|\.\d+)?)/g;
+    let match;
+    while ((match = regex.exec(cleaned)) !== null) {
+        if (match[3] === `*`) {
+            // Wildcard match
+            const count = parse_count(match[4]);
+            tokens.push({ element: null, count });
+        }
+        else if (match[1]) {
+            // Element symbol match
+            const element = match[1];
+            const count = parse_count(match[2]);
+            if (!is_valid_element(element)) {
+                throw new Error(`Invalid element symbol: ${element}`);
+            }
+            tokens.push({ element, count });
+        }
+    }
+    return tokens;
+}
+// Check if a formula matches a chemsys pattern with wildcards.
+// The formula must contain exactly the specified elements plus wildcard_count additional distinct elements.
+// Example: matches_chemsys_wildcard("LiFeCoO", ["Li", "Fe"], 2) -> true (Co and O fill the wildcards)
+export function matches_chemsys_wildcard(formula, explicit_elements, wildcard_count) {
+    try {
+        const formula_elements = extract_formula_elements(formula, { unique: true });
+        const required_count = explicit_elements.length + wildcard_count;
+        // Must have exactly the right number of elements
+        if (formula_elements.length !== required_count)
+            return false;
+        // Must contain all explicit elements
+        const formula_set = new Set(formula_elements);
+        for (const elem of explicit_elements) {
+            if (!is_valid_element(elem) || !formula_set.has(elem))
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Check if a formula matches an exact formula pattern with wildcards.
+// Each wildcard (*) must be satisfied by a distinct element not used by explicit elements or other wildcards.
+// Example: matches_formula_wildcard("LiFeCoNiO4", [{element: "Li", count: 1}, {element: null, count: 1}, ...])
+export function matches_formula_wildcard(formula, pattern) {
+    try {
+        const composition = parse_formula(formula);
+        // Separate explicit elements and wildcards from pattern
+        const explicit_requirements = [];
+        const wildcard_counts = [];
+        for (const token of pattern) {
+            if (token.element === null) {
+                wildcard_counts.push(token.count);
+            }
+            else {
+                // Merge counts for same element (e.g. "LiLi" -> Li with count 2)
+                const existing = explicit_requirements.find((req) => req.element === token.element);
+                if (existing) {
+                    existing.count += token.count;
+                }
+                else {
+                    explicit_requirements.push({ element: token.element, count: token.count });
+                }
+            }
+        }
+        // Check explicit element requirements
+        const used_elements = new Set();
+        for (const req of explicit_requirements) {
+            if (composition[req.element] !== req.count)
+                return false;
+            used_elements.add(req.element);
+        }
+        // Get remaining elements (candidates for wildcards)
+        const remaining_elements = Object.entries(composition)
+            .filter(([elem]) => !used_elements.has(elem))
+            .map(([elem, count]) => ({ elem, count }));
+        // Must have exactly as many remaining elements as wildcards
+        if (remaining_elements.length !== wildcard_counts.length)
+            return false;
+        // Try to match remaining elements to wildcards (each wildcard needs a distinct element)
+        // Sort both by count to enable greedy matching
+        const sorted_remaining = [...remaining_elements].sort((a, b) => a.count - b.count);
+        const sorted_wildcards = [...wildcard_counts].sort((a, b) => a - b);
+        // Check if counts match (simple comparison works because we need exact matches)
+        for (let idx = 0; idx < sorted_wildcards.length; idx++) {
+            if (sorted_remaining[idx].count !== sorted_wildcards[idx])
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,29 @@
+export declare const COMPRESSION_FORMATS: {
+    readonly gzip: readonly [".gz", ".gzip"];
+    readonly deflate: readonly [".deflate"];
+    readonly 'deflate-raw': readonly [".z"];
+    readonly zip: readonly [".zip"];
+    readonly xz: readonly [".xz"];
+    readonly bz2: readonly [".bz2"];
+};
+export declare const COMPRESSION_EXTENSIONS: readonly string[];
+export declare const TRAJ_KEYWORDS: readonly string[];
+export declare const STRUCT_KEYWORDS: readonly string[];
+export declare const STRUCT_KEYWORDS_STRICT: readonly string[];
+export declare const TRAJ_KEYWORDS_REGEX: RegExp;
+export declare const STRUCT_KEYWORDS_REGEX: RegExp;
+export declare const STRUCT_KEYWORDS_STRICT_REGEX: RegExp;
+export declare const TRAJ_KEYWORDS_SIMPLE_REGEX: RegExp;
+export declare const TRAJ_EXTENSIONS: readonly string[];
+export declare const TRAJ_EXTENSIONS_REGEX: RegExp;
+export declare const STRUCTURE_EXTENSIONS: readonly string[];
+export declare const STRUCTURE_EXTENSIONS_REGEX: RegExp;
+export declare const TRAJ_FALLBACK_EXTENSIONS: readonly string[];
+export declare const TRAJ_FALLBACK_EXTENSIONS_REGEX: RegExp;
+export declare const VASP_FILES_REGEX: RegExp;
+export declare const VASP_VOLUMETRIC_REGEX: RegExp;
+export declare const XDATCAR_REGEX: RegExp;
+export declare const CONFIG_DIRS_REGEX: RegExp;
+export declare const MD_SIM_EXCLUDE_REGEX: RegExp;
+export declare const XYZ_EXTXYZ_REGEX: RegExp;
+export declare const COMPRESSION_EXTENSIONS_REGEX: RegExp;

package/dist/constants.js

@@ -0,0 +1,99 @@
+// Shared keyword constants for file type detection across the codebase
+// compression formats and their file extensions
+export const COMPRESSION_FORMATS = {
+    gzip: [`.gz`, `.gzip`],
+    deflate: [`.deflate`],
+    'deflate-raw': [`.z`],
+    zip: [`.zip`], // Browser DecompressionStream doesn't support ZIP
+    xz: [`.xz`], // Browser DecompressionStream doesn't support XZ
+    bz2: [`.bz2`], // Browser DecompressionStream doesn't support BZ2
+};
+// All detectable compression extensions
+export const COMPRESSION_EXTENSIONS = Object.freeze(Object.values(COMPRESSION_FORMATS).flat());
+// Keywords that indicate a file is likely a trajectory file
+export const TRAJ_KEYWORDS = Object.freeze([
+    `trajectory`,
+    `traj`,
+    `relax`,
+    `npt`,
+    `nvt`,
+    `nve`,
+    `qha`,
+    `md`,
+    `dynamics`,
+    `simulation`,
+]);
+// Keywords that indicate a file is likely a structure file
+export const STRUCT_KEYWORDS = Object.freeze([
+    `structure`,
+    `phono`,
+    `vasp`,
+    `crystal`,
+    `material`,
+    `lattice`,
+    `geometry`,
+    `unit_cell`,
+    `unitcell`,
+    `atoms`,
+    `sites`,
+    `data`,
+    `phono3py`,
+    `phonopy`,
+]);
+// More restrictive keywords for JSON/YAML files (excludes generic terms like "data")
+export const STRUCT_KEYWORDS_STRICT = Object.freeze([
+    `structure`,
+    `phono`,
+    `vasp`,
+    `crystal`,
+    `material`,
+    `lattice`,
+    `geometry`,
+    `unit_cell`,
+    `unitcell`,
+    `atoms`,
+    `sites`,
+    `phono3py`,
+    `phonopy`,
+]);
+// Regex patterns for keyword matching
+export const TRAJ_KEYWORDS_REGEX = new RegExp(`(^|[-_.])(${TRAJ_KEYWORDS.join(`|`)})([-_.]|$)`, `i`);
+export const STRUCT_KEYWORDS_REGEX = new RegExp(`(${STRUCT_KEYWORDS.join(`|`)})`, `i`);
+export const STRUCT_KEYWORDS_STRICT_REGEX = new RegExp(`(${STRUCT_KEYWORDS_STRICT.join(`|`)})`, `i`);
+export const TRAJ_KEYWORDS_SIMPLE_REGEX = new RegExp(`(${TRAJ_KEYWORDS.join(`|`)})`, `i`);
+// File extensions for different file types
+export const TRAJ_EXTENSIONS = Object.freeze([`.traj`, `.xtc`, `.lammpstrj`]);
+export const TRAJ_EXTENSIONS_REGEX = new RegExp(`\\.(${TRAJ_EXTENSIONS.map((ext) => ext.slice(1)).join(`|`)})$`, `i`);
+export const STRUCTURE_EXTENSIONS = Object.freeze([
+    `.cif`,
+    `.mcif`,
+    `.poscar`,
+    `.vasp`,
+    `.cube`,
+    `.lmp`,
+    `.data`,
+    `.dump`,
+    `.pdb`,
+    `.mol`,
+    `.mol2`,
+    `.sdf`,
+    `.mmcif`,
+]);
+export const STRUCTURE_EXTENSIONS_REGEX = new RegExp(`\\.(${STRUCTURE_EXTENSIONS.map((ext) => ext.slice(1)).join(`|`)})$`, `i`);
+export const TRAJ_FALLBACK_EXTENSIONS = Object.freeze([
+    `.dat`,
+    `.data`,
+    `.log`,
+    `.out`,
+    `.json`,
+]);
+export const TRAJ_FALLBACK_EXTENSIONS_REGEX = new RegExp(`\\.(${TRAJ_FALLBACK_EXTENSIONS.map((ext) => ext.slice(1)).join(`|`)})$`, `i`);
+// Special regex patterns
+export const VASP_FILES_REGEX = /(?:^|[\\/_.-])(poscar|contcar|potcar|incar|kpoints|outcar)(?:[\\/_.-]|$)/i;
+export const VASP_VOLUMETRIC_REGEX = /(?:^|[\\/_.-])(chgcar|aeccar[012]?|elfcar|locpot|parchg)(?:[\\/_.-]|$)/i;
+export const XDATCAR_REGEX = /xdatcar/i;
+export const CONFIG_DIRS_REGEX = /(?:^|[\\/])(\.vscode|\.idea|\.nyc_output|\.cache|\.tmp|\.temp|node_modules|dist|build|coverage)(?:[\\/]|$)/i;
+export const MD_SIM_EXCLUDE_REGEX = /md_simulation\.(out|txt|yml|py|csv|html|css|md|js|ts)$/i;
+export const XYZ_EXTXYZ_REGEX = /\.(xyz|extxyz)$/i;
+// Compression extensions regex (shared across files)
+export const COMPRESSION_EXTENSIONS_REGEX = new RegExp(`\\.(${COMPRESSION_EXTENSIONS.map((ext) => ext.slice(1)).join(`|`)})$`, `i`);