@jjlmoya/utils-science 1.39.0 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-science",
-    "version": "1.39.0",
+    "version": "1.41.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -21,10 +21,11 @@ import { rocheLimitSatelliteDisruption } from '../tool/roche-limit-satellite-dis
 import { dysonSphereEnergyCapture } from '../tool/dyson-sphere-energy-capture/index';
 import { globalAlbedoSnowballSimulator } from '../tool/global-albedo-snowball-simulator/index';
 import { conwayLifeRuleLab } from '../tool/conway-life-rule-lab/index';
+import { crystalLatticeStructureFinder } from '../tool/crystal-lattice-structure-finder/index';
 
 export const scienceCategory: ScienceCategoryEntry = {
   icon: 'mdi:flask',
-  tools: [colonyCounter, asteroidImpact, microwaveDetector, simulationProbability, cellularRenewal, cosmicInflation, temperatureTimeline, lorenzAttractor, stellarHabitabilityZone, radioactiveDecay, naturalSelectionDrift, entropySecondLaw, doubleSlitDecoherence, phaseDiagramCriticalPoints, twinParadoxVisualizer, mandelbrotFractal, planetAtmosphereSurvival, threeBodyProblem, rocheLimitSatelliteDisruption, dysonSphereEnergyCapture, globalAlbedoSnowballSimulator, conwayLifeRuleLab],
+  tools: [colonyCounter, asteroidImpact, microwaveDetector, simulationProbability, cellularRenewal, cosmicInflation, temperatureTimeline, lorenzAttractor, stellarHabitabilityZone, radioactiveDecay, naturalSelectionDrift, entropySecondLaw, doubleSlitDecoherence, phaseDiagramCriticalPoints, twinParadoxVisualizer, mandelbrotFractal, planetAtmosphereSurvival, threeBodyProblem, rocheLimitSatelliteDisruption, dysonSphereEnergyCapture, globalAlbedoSnowballSimulator, conwayLifeRuleLab, crystalLatticeStructureFinder],
   i18n: {
     es: () => import('./i18n/es').then((m) => m.content),
     en: () => import('./i18n/en').then((m) => m.content),

package/src/entries.ts

@@ -21,6 +21,7 @@ export { rocheLimitSatelliteDisruption } from './tool/roche-limit-satellite-disr
 export { dysonSphereEnergyCapture } from './tool/dyson-sphere-energy-capture/entry';
 export { globalAlbedoSnowballSimulator } from './tool/global-albedo-snowball-simulator/entry';
 export { conwayLifeRuleLab } from './tool/conway-life-rule-lab/entry';
+export { crystalLatticeStructureFinder } from './tool/crystal-lattice-structure-finder/entry';
 export { scienceCategory } from './category';
 import { asteroidImpact } from './tool/asteroid-impact/entry';
 import { cellularRenewal } from './tool/cellular-renewal/entry';
@@ -44,4 +45,5 @@ import { rocheLimitSatelliteDisruption } from './tool/roche-limit-satellite-disr
 import { dysonSphereEnergyCapture } from './tool/dyson-sphere-energy-capture/entry';
 import { globalAlbedoSnowballSimulator } from './tool/global-albedo-snowball-simulator/entry';
 import { conwayLifeRuleLab } from './tool/conway-life-rule-lab/entry';
-export const ALL_ENTRIES = [asteroidImpact, cellularRenewal, colonyCounter, microwaveDetector, simulationProbability, cosmicInflation, temperatureTimeline, lorenzAttractor, stellarHabitabilityZone, radioactiveDecay, naturalSelectionDrift, entropySecondLaw, doubleSlitDecoherence, phaseDiagramCriticalPoints, twinParadoxVisualizer, mandelbrotFractal, planetAtmosphereSurvival, threeBodyProblem, rocheLimitSatelliteDisruption, dysonSphereEnergyCapture, globalAlbedoSnowballSimulator, conwayLifeRuleLab];
+import { crystalLatticeStructureFinder } from './tool/crystal-lattice-structure-finder/entry';
+export const ALL_ENTRIES = [asteroidImpact, cellularRenewal, colonyCounter, microwaveDetector, simulationProbability, cosmicInflation, temperatureTimeline, lorenzAttractor, stellarHabitabilityZone, radioactiveDecay, naturalSelectionDrift, entropySecondLaw, doubleSlitDecoherence, phaseDiagramCriticalPoints, twinParadoxVisualizer, mandelbrotFractal, planetAtmosphereSurvival, threeBodyProblem, rocheLimitSatelliteDisruption, dysonSphereEnergyCapture, globalAlbedoSnowballSimulator, conwayLifeRuleLab, crystalLatticeStructureFinder];

package/src/index.ts

@@ -22,6 +22,7 @@ export { ROCHE_LIMIT_SATELLITE_DISRUPTION_TOOL } from './tool/roche-limit-satell
 export { DYSON_SPHERE_ENERGY_CAPTURE_TOOL } from './tool/dyson-sphere-energy-capture/index';
 export { GLOBAL_ALBEDO_SNOWBALL_SIMULATOR_TOOL } from './tool/global-albedo-snowball-simulator/index';
 export { CONWAY_LIFE_RULE_LAB_TOOL } from './tool/conway-life-rule-lab/index';
+export { CRYSTAL_LATTICE_STRUCTURE_FINDER_TOOL } from './tool/crystal-lattice-structure-finder/index';
 
 export type {
   KnownLocale,

package/src/tests/locale_completeness.test.ts

@@ -18,7 +18,7 @@ describe('Locale Completeness Validation', () => {
     });
   });
 
-  it('all 22 tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(22);
+    it('all 23 tools registered', () => {
+      expect(ALL_TOOLS.length).toBe(23);
   });
 });

package/src/tests/tool_validation.test.ts

@@ -4,8 +4,8 @@ import { scienceCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
-    it('should have 22 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(22);
+    it('should have 23 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(23);
     });
 
     it('scienceCategory should be defined', () => {

package/src/tool/crystal-lattice-structure-finder/bibliography.astro

@@ -0,0 +1,14 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { crystalLatticeStructureFinder } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const content = await crystalLatticeStructureFinder.i18n[locale]?.();
+---
+
+{content && <SharedBibliography links={content.bibliography} />}

package/src/tool/crystal-lattice-structure-finder/bibliography.ts

@@ -0,0 +1,20 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'NIST CODATA, Avogadro constant',
+    url: 'https://physics.nist.gov/cgi-bin/cuu/Value?na',
+  },
+  {
+    name: 'OpenStax Chemistry 2e, Unit Cells and Crystal Structures',
+    url: 'https://openstax.org/books/chemistry-2e/pages/10-6-lattice-structures-in-crystalline-solids',
+  },
+  {
+    name: 'Cambridge University DoITPoMS, Crystal structures and packing',
+    url: 'https://www.doitpoms.ac.uk/tlplib/atomic-scale-structure/index.php',
+  },
+  {
+    name: 'International Union of Crystallography, Online Dictionary of Crystallography',
+    url: 'https://dictionary.iucr.org/',
+  },
+];

package/src/tool/crystal-lattice-structure-finder/component.astro

@@ -0,0 +1,366 @@
+---
+import type { LatticeId } from './logic';
+import './crystal-lattice-structure-finder.css';
+
+interface Props {
+  ui: Record<string, string>;
+}
+
+const { ui } = Astro.props;
+
+const latticeOptions: Array<{ id: LatticeId; uiKey: string; shortKey: string }> = [
+  { id: 'simple-cubic', uiKey: 'latticeSimpleCubic', shortKey: 'shortSc' },
+  { id: 'face-centered-cubic', uiKey: 'latticeFcc', shortKey: 'shortFcc' },
+  { id: 'hexagonal-close-packed', uiKey: 'latticeHcp', shortKey: 'shortHcp' },
+];
+
+const materialOptions: Array<{ id: string; uiKey: string; noteKey: string }> = [
+  { id: 'copper', uiKey: 'materialCopper', noteKey: 'materialCopperNote' },
+  { id: 'aluminum', uiKey: 'materialAluminum', noteKey: 'materialAluminumNote' },
+  { id: 'polonium', uiKey: 'materialPolonium', noteKey: 'materialPoloniumNote' },
+  { id: 'magnesium', uiKey: 'materialMagnesium', noteKey: 'materialMagnesiumNote' },
+  { id: 'titanium', uiKey: 'materialTitanium', noteKey: 'materialTitaniumNote' },
+  { id: 'halite', uiKey: 'materialHalite', noteKey: 'materialHaliteNote' },
+];
+---
+
+<div class="lattice-lab" id="lattice-lab">
+  <section class="lattice-viewer" aria-label={ui.viewerLabel}>
+    <div class="lattice-orbit">
+      <svg class="lattice-svg" id="lattice-svg" viewBox="0 0 720 560" role="img" aria-label={ui.viewerLabel}>
+        <defs>
+          <radialGradient id="lattice-atom-corner" cx="35%" cy="30%" r="70%">
+            <stop offset="0%" stop-color="#fff7d1"></stop>
+            <stop offset="45%" stop-color="#f6b44b"></stop>
+            <stop offset="100%" stop-color="#9f4f23"></stop>
+          </radialGradient>
+          <radialGradient id="lattice-atom-face" cx="35%" cy="30%" r="70%">
+            <stop offset="0%" stop-color="#e8fff8"></stop>
+            <stop offset="48%" stop-color="#54d6b0"></stop>
+            <stop offset="100%" stop-color="#167c78"></stop>
+          </radialGradient>
+          <radialGradient id="lattice-atom-interior" cx="35%" cy="30%" r="70%">
+            <stop offset="0%" stop-color="#f2f0ff"></stop>
+            <stop offset="48%" stop-color="#8f82ff"></stop>
+            <stop offset="100%" stop-color="#473caa"></stop>
+          </radialGradient>
+        </defs>
+        <g id="lattice-grid"></g>
+        <g id="lattice-atoms"></g>
+      </svg>
+    </div>
+
+    <div class="lattice-legend">
+      <span><i class="lattice-swatch lattice-swatch-corner"></i>{ui.cornerAtoms}</span>
+      <span><i class="lattice-swatch lattice-swatch-face"></i>{ui.faceAtoms}</span>
+      <span><i class="lattice-swatch lattice-swatch-interior"></i>{ui.interiorAtoms}</span>
+    </div>
+  </section>
+
+  <section class="lattice-console" aria-label="Crystal lattice controls">
+    <div class="lattice-summary">
+      <div>
+        <span id="lattice-short-name">FCC</span>
+        <strong id="lattice-density">-</strong>
+      </div>
+      <p>{ui.density}</p>
+    </div>
+
+    <label class="lattice-field lattice-field-select" for="lattice-material">
+      <span>{ui.material}</span>
+      <select id="lattice-material">
+        {materialOptions.map((opt) => (
+          <option value={opt.id} data-note={ui[opt.noteKey]}>{ui[opt.uiKey]}</option>
+        ))}
+      </select>
+    </label>
+
+    <div class="lattice-note">
+      <span id="lattice-formula">Cu</span>
+      <p id="lattice-material-note">{ui.materialNote}</p>
+    </div>
+
+    <label class="lattice-field lattice-field-select" for="lattice-structure">
+      <span>{ui.lattice}</span>
+      <select id="lattice-structure">
+        {latticeOptions.map((opt) => (
+          <option value={opt.id} data-short={ui[opt.shortKey]}>{ui[opt.uiKey]}</option>
+        ))}
+      </select>
+    </label>
+
+    <div class="lattice-slider-grid">
+      <label class="lattice-field" for="lattice-rotation">
+        <span>{ui.rotation}</span>
+        <output id="lattice-rotation-output">38 deg</output>
+        <input id="lattice-rotation" type="range" min="-70" max="70" step="1" value="38" />
+      </label>
+
+      <label class="lattice-field" for="lattice-zoom">
+        <span>{ui.zoom}</span>
+        <output id="lattice-zoom-output">100%</output>
+        <input id="lattice-zoom" type="range" min="75" max="130" step="1" value="100" />
+      </label>
+    </div>
+
+    <div class="lattice-input-grid">
+      <label class="lattice-number" for="lattice-a">
+        <span>{ui.latticeA} (Å)</span>
+        <input id="lattice-a" type="text" inputmode="decimal" pattern="[0-9.]*" value="3.615" />
+      </label>
+      <label class="lattice-number" for="lattice-c-ratio">
+        <span>{ui.cRatio}</span>
+        <input id="lattice-c-ratio" type="text" inputmode="decimal" pattern="[0-9.]*" value="1" />
+      </label>
+      <label class="lattice-number" for="lattice-mass">
+        <span>{ui.molarMass} (g/mol)</span>
+        <input id="lattice-mass" type="text" inputmode="decimal" pattern="[0-9.]*" value="63.546" />
+      </label>
+    </div>
+
+    <button class="lattice-reset" id="lattice-reset" type="button">{ui.resetView}</button>
+  </section>
+
+  <section class="lattice-results" aria-label="Crystal lattice results">
+    <div class="lattice-result-group">
+      <h2>{ui.crystalProperties}</h2>
+      <div class="lattice-metric-row">
+        <span>{ui.atomsPerCell}</span>
+        <strong id="lattice-atoms-cell">-</strong>
+      </div>
+      <div class="lattice-metric-row">
+        <span>{ui.coordination}</span>
+        <strong id="lattice-coordination">-</strong>
+      </div>
+      <div class="lattice-metric-row">
+        <span>{ui.packingFactor}</span>
+        <strong id="lattice-packing">-</strong>
+      </div>
+    </div>
+
+    <div class="lattice-result-group">
+      <h2>{ui.physicalMetrics}</h2>
+      <div class="lattice-metric-row">
+        <span>{ui.cellVolume}</span>
+        <strong id="lattice-volume">-</strong>
+      </div>
+      <div class="lattice-metric-row">
+        <span>{ui.cellMass}</span>
+        <strong id="lattice-cell-mass">-</strong>
+      </div>
+      <div class="lattice-metric-row">
+        <span>{ui.radius}</span>
+        <strong id="lattice-radius">-</strong>
+      </div>
+    </div>
+  </section>
+</div>
+
+<script>
+  import {
+    MATERIAL_PRESETS,
+    calculatePackingPercent,
+    calculateTheoreticalDensity,
+    getLattice,
+    getMaterial,
+  } from './logic';
+  import type { AtomSite, DensityResult, LatticeId, LatticeStructure, MaterialPreset } from './logic';
+
+  const svgNamespace = 'http://www.w3.org/2000/svg';
+  const materialSelect = document.getElementById('lattice-material') as HTMLSelectElement | null;
+  const structureSelect = document.getElementById('lattice-structure') as HTMLSelectElement | null;
+  const rotationInput = document.getElementById('lattice-rotation') as HTMLInputElement | null;
+  const zoomInput = document.getElementById('lattice-zoom') as HTMLInputElement | null;
+  const aInput = document.getElementById('lattice-a') as HTMLInputElement | null;
+  const cRatioInput = document.getElementById('lattice-c-ratio') as HTMLInputElement | null;
+  const massInput = document.getElementById('lattice-mass') as HTMLInputElement | null;
+  const gridLayer = document.getElementById('lattice-grid');
+  const atomLayer = document.getElementById('lattice-atoms');
+  const resetButton = document.getElementById('lattice-reset');
+
+  const labels = {
+    formula: document.getElementById('lattice-formula'),
+    note: document.getElementById('lattice-material-note'),
+    rotation: document.getElementById('lattice-rotation-output'),
+    zoom: document.getElementById('lattice-zoom-output'),
+    shortName: document.getElementById('lattice-short-name'),
+    density: document.getElementById('lattice-density'),
+    packing: document.getElementById('lattice-packing'),
+    atomsCell: document.getElementById('lattice-atoms-cell'),
+    coordination: document.getElementById('lattice-coordination'),
+    volume: document.getElementById('lattice-volume'),
+    cellMass: document.getElementById('lattice-cell-mass'),
+    radius: document.getElementById('lattice-radius'),
+  };
+
+  function formatNumber(value: number, digits = 3): string {
+    return new Intl.NumberFormat('en', {
+      maximumFractionDigits: digits,
+      minimumFractionDigits: value < 10 ? Math.min(2, digits) : 0,
+    }).format(value);
+  }
+
+  function activeMaterial(): MaterialPreset {
+    return getMaterial(materialSelect?.value ?? MATERIAL_PRESETS[0].id);
+  }
+
+  function decimalValue(input: HTMLInputElement | null, fallback: number): number {
+    if (!input) return fallback;
+
+    const normalized = input.value.replace(/,/g, '.').replace(/[^0-9.]/g, '');
+    if (normalized !== input.value) input.value = normalized;
+
+    const value = Number(normalized);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+  }
+
+  function projectPoint(point: [number, number, number], rotation: number, zoom: number, hex = false) {
+    const angle = (rotation * Math.PI) / 180;
+    const x0 = hex ? point[0] : point[0] - 0.5;
+    const y0 = hex ? point[1] : point[1] - 0.5;
+    const z0 = point[2] - 0.5;
+    const x = x0 * Math.cos(angle) - y0 * Math.sin(angle);
+    const y = x0 * Math.sin(angle) + y0 * Math.cos(angle);
+    const scale = zoom * (hex ? 136 : 210);
+
+    return {
+      x: 360 + (x - y) * scale * 0.58,
+      y: 288 + (x + y) * scale * 0.26 - z0 * scale * 0.78,
+      depth: x + y + z0,
+    };
+  }
+
+  function clearLayer(layer: Element | null) {
+    while (layer?.firstChild) {
+      layer.firstChild.remove();
+    }
+  }
+
+  function drawLine(from: { x: number; y: number }, to: { x: number; y: number }) {
+    const line = document.createElementNS(svgNamespace, 'line');
+    line.setAttribute('x1', from.x.toFixed(2));
+    line.setAttribute('y1', from.y.toFixed(2));
+    line.setAttribute('x2', to.x.toFixed(2));
+    line.setAttribute('y2', to.y.toFixed(2));
+    line.classList.add('lattice-edge');
+    gridLayer?.append(line);
+  }
+
+  const ATOM_RADIUS_MAP: Record<AtomSite['role'], number> = { corner: 18, face: 24, interior: 28 };
+
+  function atomRadius(role: AtomSite['role'], zoom: number) {
+    return ATOM_RADIUS_MAP[role] * (zoom / 100);
+  }
+
+  function drawAtom(site: AtomSite, position: { x: number; y: number; depth: number }, zoom: number) {
+    const circle = document.createElementNS(svgNamespace, 'circle');
+    circle.setAttribute('cx', position.x.toFixed(2));
+    circle.setAttribute('cy', position.y.toFixed(2));
+    circle.setAttribute('r', atomRadius(site.role, zoom).toFixed(2));
+    circle.setAttribute('data-depth', position.depth.toFixed(3));
+    circle.classList.add('lattice-atom', `lattice-atom-${site.role}`);
+    atomLayer?.append(circle);
+  }
+
+  function renderCell() {
+    if (!structureSelect || !rotationInput || !zoomInput) return;
+
+    const lattice = getLattice(structureSelect.value as LatticeId);
+    const rotation = Number(rotationInput.value);
+    const zoom = Number(zoomInput.value);
+    const isHex = lattice.id === 'hexagonal-close-packed';
+    const projected = lattice.vertices.map((vertex) => projectPoint(vertex, rotation, zoom / 100, isHex));
+
+    clearLayer(gridLayer);
+    clearLayer(atomLayer);
+
+    lattice.edges.forEach(([from, to]) => drawLine(projected[from], projected[to]));
+
+    const atoms = lattice.sites
+      .map((site) => {
+        const source: [number, number, number] = isHex
+          ? [site.x * 2 - 1, site.y * 1.732 - 0.866, site.z]
+          : [site.x, site.y, site.z];
+        return { site, position: projectPoint(source, rotation, zoom / 100, isHex) };
+      })
+      .sort((a, b) => a.position.depth - b.position.depth);
+
+    atoms.forEach(({ site, position }) => drawAtom(site, position, zoom));
+  }
+
+  function currentCustomMaterial(): MaterialPreset {
+    const material = activeMaterial();
+    return {
+      ...material,
+      latticeId: (structureSelect?.value as LatticeId) ?? material.latticeId,
+      latticeA: decimalValue(aInput, material.latticeA),
+      cToA: decimalValue(cRatioInput, material.cToA ?? getLattice(material.latticeId).cToA ?? 1),
+      atomicMass: decimalValue(massInput, material.atomicMass),
+    };
+  }
+
+  function updateResults() {
+    if (!structureSelect || !rotationInput || !zoomInput || !aInput || !cRatioInput || !massInput) return;
+
+    const material = currentCustomMaterial();
+    const lattice = getLattice(material.latticeId);
+    const result = calculateTheoreticalDensity(material);
+    const selectedStructure = structureSelect.options[structureSelect.selectedIndex];
+
+    renderLabels(lattice, material, result, selectedStructure);
+    renderCell();
+  }
+
+  function renderLabels(
+    lattice: LatticeStructure,
+    material: MaterialPreset,
+    result: DensityResult,
+    selectedOption: HTMLOptionElement | undefined,
+  ) {
+    const radius = material.latticeA * lattice.radiusToA;
+    labels.rotation!.textContent = `${rotationInput!.value} deg`;
+    labels.zoom!.textContent = `${zoomInput!.value}%`;
+    labels.shortName!.textContent = selectedOption?.getAttribute('data-short') ?? '';
+    labels.density!.textContent = `${formatNumber(result.density, 3)} g/cm³`;
+    labels.packing!.textContent = `${formatNumber(calculatePackingPercent(lattice), 2)}%`;
+    labels.atomsCell!.textContent = formatNumber(result.atomsPerCell, 2);
+    labels.coordination!.textContent = `${lattice.coordinationNumber}`;
+    labels.volume!.textContent = `${formatNumber(result.cellVolumeCm3 * 1e24, 3)} ų`;
+    labels.cellMass!.textContent = `${result.cellMassG.toExponential(3)} g`;
+    labels.radius!.textContent = `${formatNumber(radius, 3)} Å`;
+    resetButton?.classList.toggle('lattice-reset-active', rotationInput!.value !== '38' || zoomInput!.value !== '100');
+  }
+
+  function loadMaterial(materialId: string) {
+    const material = getMaterial(materialId);
+    const lattice = getLattice(material.latticeId);
+
+    populateInputs(material, lattice);
+    labels.formula!.textContent = material.formula;
+    const selectedMaterial = materialSelect?.options[materialSelect.selectedIndex ?? -1];
+    labels.note!.textContent = selectedMaterial?.getAttribute('data-note') ?? '';
+    updateResults();
+  }
+
+  function populateInputs(material: MaterialPreset, lattice: LatticeStructure) {
+    if (structureSelect) structureSelect.value = material.latticeId;
+    if (aInput) aInput.value = `${material.latticeA}`;
+    if (cRatioInput) cRatioInput.value = `${material.cToA ?? lattice.cToA ?? 1}`;
+    if (massInput) massInput.value = `${material.atomicMass}`;
+  }
+
+  materialSelect?.addEventListener('change', () => loadMaterial(materialSelect.value));
+  structureSelect?.addEventListener('change', updateResults);
+  rotationInput?.addEventListener('input', updateResults);
+  zoomInput?.addEventListener('input', updateResults);
+  aInput?.addEventListener('input', updateResults);
+  cRatioInput?.addEventListener('input', updateResults);
+  massInput?.addEventListener('input', updateResults);
+  resetButton?.addEventListener('click', () => {
+    if (rotationInput) rotationInput.value = '38';
+    if (zoomInput) zoomInput.value = '100';
+    updateResults();
+  });
+
+  loadMaterial(materialSelect?.value ?? MATERIAL_PRESETS[0].id);
+</script>