react-cheminfo 0.2.0 → 0.3.0

package/src/orbital/core/sample.ts

@@ -0,0 +1,91 @@
+/**
+ * The one job the viewer asks for, shaped so it can cross a worker boundary.
+ *
+ * The request carries an atomic number and an orbital id, never an
+ * `AtomicOrbital`: that object holds its spherical harmonic as a
+ * function*, which the structured clone algorithm cannot copy. Rebuilding the
+ * list from two plain values costs microseconds and keeps the boundary honest.
+ *
+ * A site that would rather not spend ~25 ms of its main thread per orbital
+ * implements this contract in a worker and hands `AtomicOrbitalViewer` the
+ * `sample` prop; one that does not gets the in-process version for free.
+ */
+
+import type { AtomicGridOptions } from './atomicGrid.ts';
+import { sampleAtomicOrbital } from './atomicGrid.ts';
+import {
+  atomicOrbitalsOf,
+  findAtomicOrbital,
+  hydrogenicParametersOf,
+} from './atomicOrbitals.ts';
+import type { OrbitalGrid } from './grid.ts';
+import { radialNodeRadii } from './hydrogenic.ts';
+
+/** Which orbital to sample, and how finely. */
+export interface AtomicSampleRequest {
+  /** Proton count, 1 to 118. */
+  atomicNumber: number;
+  /** Which orbital of that element, e.g. `3dz2`. */
+  orbitalId: string;
+  /**
+   * Samples along each edge of the cube. The cost is the cube of this.
+   * @default 56
+   */
+  resolution?: number;
+}
+
+/** What one sampling job produces. */
+export interface AtomicSampleResult {
+  /** The signed field, ready for an isosurface. */
+  grid: OrbitalGrid;
+  /** Radii of the orbital's radial nodes, ångström, ascending. */
+  nodeRadii: number[];
+}
+
+/**
+ * Sample one atomic orbital onto a grid.
+ *
+ * Synchronous and free of React, molstar and the DOM, so it runs unchanged on
+ * the main thread, in a worker, and under vitest.
+ * @param request - See {@link AtomicSampleRequest}.
+ * @returns The field, and where its radial nodes are.
+ * @throws {Error} When the element or the orbital id names nothing.
+ */
+export function runAtomicSample(
+  request: AtomicSampleRequest,
+): AtomicSampleResult {
+  const { atomicNumber, orbitalId, resolution } = request;
+  const orbitals = atomicOrbitalsOf(atomicNumber);
+  const orbital = findAtomicOrbital(orbitals, orbitalId);
+  if (orbital === null) {
+    throw new Error(
+      `Element ${atomicNumber} has no orbital ${orbitalId}. Known: ${orbitals
+        .map((entry) => entry.id)
+        .join(', ')}.`,
+    );
+  }
+  const options: AtomicGridOptions = {};
+  if (resolution !== undefined) options.resolution = resolution;
+  return {
+    grid: sampleAtomicOrbital(orbital, options),
+    nodeRadii: radialNodeRadii(hydrogenicParametersOf(orbital)),
+  };
+}
+
+/** How a caller supplies the sampling — in process, or through a worker. */
+export type AtomicSampler = (
+  request: AtomicSampleRequest,
+) => Promise<AtomicSampleResult>;
+
+/**
+ * The default sampler: {@link runAtomicSample}, yielded to the event loop so
+ * the spinner has painted before the main thread is taken.
+ * @param request - See {@link AtomicSampleRequest}.
+ * @returns The field, and where its radial nodes are.
+ */
+export const sampleInProcess: AtomicSampler = async (request) => {
+  await new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+  return runAtomicSample(request);
+};

package/src/orbital/core/screening.ts

@@ -0,0 +1,90 @@
+/**
+ * Slater's rules: how much of the nucleus an electron actually feels.
+ *
+ * A hydrogen-like orbital needs one number, the effective nuclear charge, and
+ * taking the full `Z` would draw carbon's 2p six times too small. Slater's rules
+ * estimate the shielding `S` from the other electrons, and `Z_eff = Z − S` is
+ * what the radial function is built with.
+ *
+ * They are an empirical fit from 1930, not a calculation — but they are the ones
+ * every general-chemistry course teaches, they reproduce the periodic trends
+ * that matter (Z_eff rises across a period, barely moves down a group), and a
+ * student can check the arithmetic here against the one they did by hand.
+ *
+ * The electrons are grouped as Slater grouped them, with s and p sharing a
+ * group and each d and f standing alone:
+ *
+ * ```
+ * [1s] [2s2p] [3s3p] [3d] [4s4p] [4d] [4f] [5s5p] [5d] [5f] [6s6p] [6d] [7s7p]
+ * ```
+ */
+
+import type { Subshell, SubshellOccupancy } from './electronConfiguration.ts';
+
+/** The shielding an orbital feels, and what is left of the nuclear charge. */
+export interface Screening {
+  /** Sum of the shielding contributions, `S`. */
+  shielding: number;
+  /** `Z − S`, the charge the hydrogen-like radial function is built with. */
+  effectiveCharge: number;
+}
+
+/**
+ * Apply Slater's rules to one subshell of one atom.
+ * @param atomicNumber - Proton count, the `Z` the shielding is subtracted from.
+ * @param configuration - Every occupied subshell of the atom.
+ * @param subshell - The subshell whose electron is being screened.
+ * @returns Its shielding and effective nuclear charge.
+ */
+export function slaterScreening(
+  atomicNumber: number,
+  configuration: readonly SubshellOccupancy[],
+  subshell: Subshell,
+): Screening {
+  const rank = groupRank(subshell);
+  const isCore = subshell.n === 1;
+  const isDiffuse = subshell.l >= 2;
+  let shielding = 0;
+  for (const occupied of configuration) {
+    const otherRank = groupRank(occupied);
+    if (otherRank > rank) continue;
+    if (otherRank === rank) {
+      // An electron does not shield itself, so one is left out — but only from
+      // its *own* subshell. 2s and 2p share a group, and every one of carbon's
+      // two 2s electrons shields its 2p electron in full.
+      const others = Math.max(
+        0,
+        occupied.electrons - (sameSubshell(occupied, subshell) ? 1 : 0),
+      );
+      shielding += others * (isCore ? 0.3 : 0.35);
+      continue;
+    }
+    if (isDiffuse) {
+      // A d or f electron is screened completely by everything inside it.
+      shielding += occupied.electrons;
+      continue;
+    }
+    shielding +=
+      occupied.electrons * (occupied.n === subshell.n - 1 ? 0.85 : 1);
+  }
+  return {
+    shielding,
+    effectiveCharge: atomicNumber - shielding,
+  };
+}
+
+/**
+ * Where a subshell sits in Slater's left-to-right ordering of groups.
+ *
+ * s and p of the same shell share a group, so they share a rank; d and f each
+ * get their own, placed after the s/p group of the same `n`.
+ * @param subshell - The subshell to rank.
+ * @returns A comparable rank; equal ranks mean the same Slater group.
+ */
+export function groupRank(subshell: Subshell): number {
+  return subshell.n * 10 + (subshell.l <= 1 ? 0 : subshell.l);
+}
+
+function sameSubshell(first: Subshell, second: Subshell): boolean {
+  return first.n === second.n && first.l === second.l;
+}

package/src/orbital/ui/AtomicOrbitalCanvas.tsx

@@ -0,0 +1,181 @@
+/**
+ * The molstar canvas showing one atomic orbital.
+ *
+ * `AtomicOrbitalViewer` reaches this through `React.lazy`, so a page that
+ * never shows an orbital never downloads molstar for it — which is the whole
+ * reason the two components are separate files.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+import { useEffect, useRef, useState } from 'react';
+
+import type { PhasePalette } from '../core/palette.ts';
+import { PHASE_PALETTES } from '../core/palette.ts';
+import type { AtomicSampler } from '../core/sample.ts';
+import { sampleInProcess } from '../core/sample.ts';
+
+import type { OrbitalViewer } from './viewer.ts';
+import { createOrbitalViewer } from './viewer.ts';
+
+/** Props of {@link AtomicOrbitalCanvas}. */
+export interface AtomicOrbitalCanvasProps {
+  /** Proton count of the element on screen. */
+  atomicNumber: number;
+  /** Which orbital of it, e.g. `3dz2`. */
+  orbitalId: string;
+  /**
+   * Colours the two phases are drawn in.
+   * @default PHASE_PALETTES.textbook
+   */
+  palette?: PhasePalette;
+  /**
+   * Samples along each edge of the cube; the cost is the cube of it.
+   * @default 56
+   */
+  resolution?: number;
+  /**
+   * Whether the scene turns on its own, which is what makes a still screenshot
+   * of a 3D shape readable.
+   * @default false
+   */
+  spinning?: boolean;
+  /**
+   * How the field is produced. Supply a worker-backed sampler to keep the main
+   * thread free; the default runs in process.
+   * @default sampleInProcess
+   */
+  sample?: AtomicSampler;
+  /**
+   * Called with the radial node radii, ångström, each time an orbital is
+   * sampled — so the page can mark them on a radial plot beside the canvas.
+   * @default undefined
+   */
+  onNodeRadii?: (radii: number[]) => void;
+  /**
+   * Called when an orbital cannot be drawn, with the reason.
+   * @default undefined
+   */
+  onError?: (message: string) => void;
+}
+
+/**
+ * Mount one molstar canvas and keep it showing the orbital named by the props.
+ * @param props - See {@link AtomicOrbitalCanvasProps}.
+ * @returns The canvas, with a progress note while it samples.
+ */
+export function AtomicOrbitalCanvas(
+  props: AtomicOrbitalCanvasProps,
+): ReactElement {
+  const {
+    atomicNumber,
+    orbitalId,
+    palette = PHASE_PALETTES.textbook,
+    resolution = DEFAULT_RESOLUTION,
+    spinning = false,
+    sample = sampleInProcess,
+    onNodeRadii,
+    onError,
+  } = props;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const viewerRef = useRef<OrbitalViewer | null>(null);
+  const [drawn, setDrawn] = useState<string | null>(null);
+
+  // What the canvas is being asked to show. Comparing it with what it *is*
+  // showing gives the progress note without a state write on every prop change.
+  const wanted = `${atomicNumber}|${orbitalId}|${resolution}|${palette.id}`;
+  const busy = drawn !== wanted;
+
+  // Callbacks are read through refs so a caller passing an inline arrow does
+  // not re-sample the orbital on every render of its parent.
+  const callbacks = useRef({ onNodeRadii, onError });
+  useEffect(() => {
+    callbacks.current = { onNodeRadii, onError };
+  });
+
+  // Created and disposed once per mount. React 19 runs this twice in
+  // development; `createOrbitalViewer` is synchronous so the first canvas is
+  // always disposed instead of leaking its WebGL context.
+  useEffect(() => {
+    const container = containerRef.current;
+    if (container === null) return;
+    const viewer = createOrbitalViewer(container);
+    viewerRef.current = viewer;
+    const observer = new ResizeObserver(() => {
+      viewer.handleResize();
+    });
+    observer.observe(container);
+    return () => {
+      observer.disconnect();
+      viewerRef.current = null;
+      viewer.dispose();
+    };
+  }, []);
+
+  useEffect(() => {
+    const viewer = viewerRef.current;
+    if (viewer === null) return;
+    let cancelled = false;
+    void sample({ atomicNumber, orbitalId, resolution })
+      .then(async (result) => {
+        if (cancelled) return;
+        callbacks.current.onNodeRadii?.(result.nodeRadii);
+        const reach = await viewer.showOrbital(result.grid, {
+          positiveColour: palette.positive,
+          negativeColour: palette.negative,
+        });
+        await viewer.frame(reach);
+        if (!cancelled) setDrawn(wanted);
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        callbacks.current.onError?.(
+          error instanceof Error ? error.message : String(error),
+        );
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [atomicNumber, orbitalId, resolution, palette, sample, wanted]);
+
+  useEffect(() => {
+    void viewerRef.current?.setSpin(spinning);
+  }, [spinning]);
+
+  return (
+    <div ref={containerRef} style={CANVAS_STYLE}>
+      {busy && <div style={BUSY_STYLE}>Sampling…</div>}
+    </div>
+  );
+}
+
+/** Samples per edge; 56 resolves the radial node of a 3s in about 25 ms. */
+const DEFAULT_RESOLUTION = 56;
+
+/**
+ * A square, centred stage: an atomic orbital is as tall as it is wide, so a
+ * square wastes the least of the frame and keeps the lobes the same size when
+ * the surrounding column changes width.
+ */
+const CANVAS_STYLE: CSSProperties = {
+  position: 'relative',
+  width: '100%',
+  maxWidth: 'min(100%, 60vh)',
+  aspectRatio: '1 / 1',
+  margin: '0 auto',
+  minHeight: 260,
+  borderRadius: 3,
+  overflow: 'hidden',
+};
+
+const BUSY_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 8,
+  left: 8,
+  zIndex: 1,
+  padding: '3px 8px',
+  borderRadius: 3,
+  background: 'rgba(255, 255, 255, 0.85)',
+  color: '#5f6b7c',
+  fontSize: 11,
+};

package/src/orbital/ui/AtomicOrbitalViewer.tsx

@@ -0,0 +1,150 @@
+/**
+ * One atomic orbital in three dimensions, and what to say when there cannot be
+ * one.
+ *
+ * Two precautions, both of which are the reason to use this component rather
+ * than the canvas directly: the WebGL probe runs *before* molstar is touched,
+ * because a locked-down school machine would otherwise get a blank rectangle
+ * with no explanation, and the canvas sits behind `React.lazy`, so a page that
+ * never reaches it never downloads molstar.
+ *
+ * ```tsx
+ * import { AtomicOrbitalViewer } from 'react-cheminfo/orbital';
+ *
+ * <AtomicOrbitalViewer atomicNumber={26} orbitalId="3dz2" />;
+ * ```
+ */
+
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { Suspense, lazy, useState } from 'react';
+
+import type { PhasePalette } from '../core/palette.ts';
+import type { AtomicSampler } from '../core/sample.ts';
+
+// Deep import on purpose: `capability.ts` imports nothing, while the sibling
+// canvas pulls molstar in — which is exactly what this probe exists to avoid.
+import type { ViewerCapability } from './capability.ts';
+import { probeViewerCapability } from './capability.ts';
+
+const AtomicOrbitalCanvas = lazy(async () => {
+  const module = await import('./AtomicOrbitalCanvas.tsx');
+  return { default: module.AtomicOrbitalCanvas };
+});
+
+/** Props of {@link AtomicOrbitalViewer}. */
+export interface AtomicOrbitalViewerProps {
+  /** Proton count of the element, 1 to 118. */
+  atomicNumber: number;
+  /** Which orbital of it, e.g. `3dz2`; ids come from `atomicOrbitalsOf`. */
+  orbitalId: string;
+  /**
+   * Colours the two phases are drawn in.
+   * @default PHASE_PALETTES.textbook
+   */
+  palette?: PhasePalette;
+  /**
+   * Samples along each edge of the cube; the cost is the cube of it.
+   * @default 56
+   */
+  resolution?: number;
+  /**
+   * Whether the scene turns on its own.
+   * @default false
+   */
+  spinning?: boolean;
+  /**
+   * How the field is produced. Supply a worker-backed sampler to keep the main
+   * thread free; the default runs in process.
+   * @default sampleInProcess
+   */
+  sample?: AtomicSampler;
+  /**
+   * Called with the radial node radii, ångström, each time an orbital is
+   * sampled.
+   * @default undefined
+   */
+  onNodeRadii?: (radii: number[]) => void;
+  /**
+   * What to show while molstar is downloading.
+   * @default 'Loading the 3D viewer…'
+   */
+  fallback?: ReactNode;
+  /**
+   * What to show when the machine cannot render at all. Receives the probe, so
+   * a site can word the refusal in its own voice; the default writes
+   * `capability.message`.
+   * @default undefined
+   */
+  renderUnsupported?: (capability: ViewerCapability) => ReactNode;
+}
+
+/**
+ * The 3D atomic orbital.
+ * @param props - See {@link AtomicOrbitalViewerProps}.
+ * @returns The viewer, or an explanation of why this machine cannot show one.
+ */
+export function AtomicOrbitalViewer(
+  props: AtomicOrbitalViewerProps,
+): ReactElement {
+  const {
+    fallback = 'Loading the 3D viewer…',
+    renderUnsupported,
+    ...canvas
+  } = props;
+  const [capability] = useState(probeViewerCapability);
+  const [failure, setFailure] = useState<string | null>(null);
+
+  if (!capability.supported) {
+    return (
+      <div style={NOTE_STYLE}>
+        {renderUnsupported?.(capability) ?? capability.message}
+      </div>
+    );
+  }
+
+  return (
+    <div style={ROOT_STYLE}>
+      <Suspense fallback={<div style={NOTE_STYLE}>{fallback}</div>}>
+        <AtomicOrbitalCanvas
+          {...canvas}
+          onError={(message) => {
+            setFailure(message);
+          }}
+        />
+      </Suspense>
+      {failure !== null && (
+        <div style={FAILURE_STYLE}>
+          This orbital could not be drawn: {failure}
+        </div>
+      )}
+    </div>
+  );
+}
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  minWidth: 0,
+};
+
+const NOTE_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  minHeight: 260,
+  padding: 12,
+  borderRadius: 3,
+  background: 'rgb(241 245 249)',
+  color: '#5f6b7c',
+  fontSize: 13,
+  textAlign: 'center',
+};
+
+const FAILURE_STYLE: CSSProperties = {
+  padding: '6px 9px',
+  borderRadius: 3,
+  background: '#fdeaea',
+  color: '#8c2b2b',
+  fontSize: 12,
+};

package/src/orbital/ui/camera.ts

@@ -0,0 +1,125 @@
+/**
+ * The camera moves an atomic orbital needs: frame it from an angle its lobes
+ * can be told apart at, and the slow spin that makes a flat screenshot of a 3D
+ * shape readable.
+ */
+
+import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+
+/** Transition length used when the caller does not pick one, milliseconds. */
+export const DEFAULT_CAMERA_DURATION = 250;
+
+/**
+ * Fraction of the bounding sphere kept as breathing room around the orbital.
+ *
+ * `camera.reset()` frames the scene with molstar's own margin, which suits a
+ * protein filling a wide viewport. One orbital in a square frame measured 20%
+ * of the pixels that way — it read as a speck. Framing the visible bounding
+ * sphere directly, with a small margin, is what makes it legible.
+ */
+const FRAMING_MARGIN = 0.08;
+
+/**
+ * Frame everything currently in the scene.
+ * @param plugin - The molstar context.
+ * @param durationMs - Transition length. Pass 0 for an instant jump.
+ */
+export function resetCamera(
+  plugin: PluginContext,
+  durationMs = DEFAULT_CAMERA_DURATION,
+): void {
+  const scene = plugin.canvas3d?.boundingSphereVisible;
+  if (scene === undefined || scene.radius <= 0) {
+    plugin.managers.camera.reset(undefined, durationMs);
+    return;
+  }
+  plugin.managers.camera.focusSphere(scene, {
+    extraRadius: scene.radius * FRAMING_MARGIN,
+    minRadius: 0.5,
+    durationMs,
+  });
+}
+
+/**
+ * Direction from the target to the camera for a single atom's orbital.
+ *
+ * An atomic orbital is aligned with the cartesian axes, so the default view
+ * looks straight down one of them and a `p_z` or a `d_z²` collapses into
+ * concentric rings — geometrically correct and completely unreadable. Coming in
+ * off-axis separates the lobes.
+ */
+const ORBITAL_VIEW_OFFSET = Vec3.create(0.8, -1, 0.45);
+
+/**
+ * Screen up for that view: `+z`, so the z axis is vertical exactly as every
+ * textbook draws `p_z` and `d_z²`.
+ */
+const ORBITAL_VIEW_UP = Vec3.create(0, 0, 1);
+
+/**
+ * Frame the scene from an oblique angle, for a lone atom rather than a molecule.
+ *
+ * `camera.focus` cannot do this: its `up` and `dir` arguments only *flip* the
+ * orientation the camera already has, so an explicit viewpoint has to be set
+ * through the snapshot.
+ * @param plugin - The molstar context.
+ * @param orbitalRadius - Extent of the drawn surface, ångström. Molstar sizes a
+ * volume representation's bounding sphere from the whole sampled box, which is
+ * far larger than the isosurface inside it, so framing that sphere leaves the
+ * orbital a quarter of the frame wide. Omit it to fall back on the scene.
+ * @param durationMs - Transition length. Pass 0 for an instant jump.
+ */
+export function frameOrbital(
+  plugin: PluginContext,
+  orbitalRadius?: number,
+  durationMs = DEFAULT_CAMERA_DURATION,
+): void {
+  const canvas3d = plugin.canvas3d;
+  const scene = canvas3d?.boundingSphereVisible;
+  if (canvas3d === undefined || scene === undefined || scene.radius <= 0) {
+    resetCamera(plugin, durationMs);
+    return;
+  }
+  const radius =
+    orbitalRadius !== undefined && orbitalRadius > 0
+      ? orbitalRadius * (1 + FRAMING_MARGIN)
+      : scene.radius * (1 + FRAMING_MARGIN);
+  const offset = Vec3.setMagnitude(
+    Vec3.zero(),
+    ORBITAL_VIEW_OFFSET,
+    canvas3d.camera.getTargetDistance(radius),
+  );
+  // An atomic orbital is centred on its nucleus at the origin, so the drawn
+  // surface is symmetric about it even when the sampled box's sphere is not.
+  const centre = orbitalRadius === undefined ? scene.center : Vec3.zero();
+  canvas3d.camera.setState(
+    {
+      target: Vec3.clone(centre),
+      position: Vec3.add(Vec3.zero(), centre, offset),
+      up: Vec3.clone(ORBITAL_VIEW_UP),
+      radius,
+    },
+    durationMs,
+  );
+}
+
+/**
+ * Turn the automatic spin on or off.
+ * @param plugin - The molstar context.
+ * @param spinning - Whether the scene should keep turning.
+ * @param speed - Revolutions per minute-ish; molstar's own unit.
+ */
+export function setSpin(
+  plugin: PluginContext,
+  spinning: boolean,
+  speed = 1,
+): void {
+  plugin.canvas3d?.setProps({
+    trackball: {
+      animate: spinning
+        ? { name: 'spin', params: { speed, axis: Vec3.create(0, 1, 0) } }
+        : { name: 'off', params: {} },
+    },
+  });
+}