react-cheminfo 0.23.0 → 0.25.0

package/src/citation/core/index.ts

@@ -12,6 +12,7 @@ export {
   citationFilename,
   formatCitation,
 } from './formats.ts';
+export { GFN2_XTB_PAPER, GFN2_XTB_WORK } from './gfn2Paper.ts';
 export { OPENCHEMLIB_PAPER, OPENCHEMLIB_WORK } from './openchemlibPaper.ts';
 export { PLATFORM_PAPER, PLATFORM_WORK } from './platformPaper.ts';
 export type { Reference, ReferenceAuthor } from './reference.ts';

package/src/clipboard/ui/ClickToCopy.tsx

@@ -24,7 +24,7 @@ export interface ClickToCopyProps {
    * function is called only when the value is clicked.
    */
   value: ClipboardContent | (() => ClipboardContent);
-  /** What is shown; the pointer turns into the copy cursor over it. */
+  /** What is shown; the pointer turns into a clipboard over it. */
   children: ReactNode;
   /**
    * What the value is, named in the hover title: `Copy the SMILES (C=CC=O)`.
@@ -46,9 +46,10 @@ export interface ClickToCopyProps {
    */
   as?: ClickToCopyElement;
   /**
-   * Whether the value is a tab stop and a button of its own, with its glyph.
-   * Off when a copy button beside it already copies the same value, so the
-   * keyboard and a screen reader meet one control, and the eye one glyph.
+   * Whether the value is a tab stop and a button of its own, with the glyph a
+   * keyboard is shown instead of the cursor. Off when a copy button beside it
+   * already copies the same value, so the keyboard and a screen reader meet
+   * one control.
    * @default true
    */
   focusable?: boolean;
@@ -83,9 +84,9 @@ const NESTED_CONTROL =
  * A value that is copied by clicking it.
  *
  * Text in a tool is not selectable — a drag across a viewer must not paint the
- * page — so what is worth taking away is copied this way instead: the copy
- * cursor, a tint and a clipboard glyph announce it on hover, a click or `Enter`
- * puts it on the clipboard, and a tick confirms it. The click stops there, so
+ * page — so what is worth taking away is copied this way instead: a cursor
+ * carrying a clipboard and a tint announce it on hover, a click or `Enter` puts
+ * it on the clipboard, and a tick confirms it. The click stops there, so
  * a value inside a clickable row copies without also opening the row, and a
  * link or a button nested in the value keeps its own click.
  * @param props - See {@link ClickToCopyProps}.

package/src/conformers.ts

@@ -0,0 +1,87 @@
+/**
+ * Conformers of a structure: generated, MMFF94-ranked, duplicate minima
+ * dropped, and refined against a `GeometryRelaxer`.
+ *
+ * Its own door because every step runs openchemlib, and `react-cheminfo/core`
+ * costs nothing on import. The relaxer contract itself, and the coordinates a
+ * relaxer reads and writes, stay in `react-cheminfo/core`: the code that
+ * orchestrates a refinement needs neither openchemlib nor WebAssembly.
+ */
+
+export type {
+  Conformer,
+  ConformerLimits,
+  ConformerRanking,
+  ConformerSet,
+  StopReason,
+} from './structure/core/conformers.ts';
+export {
+  continueConformers,
+  generateConformers,
+  strategyConstant,
+} from './structure/core/conformers.ts';
+export type {
+  ConformerRefinement,
+  ConformerSetRefinement,
+  RefineConformersOptions,
+} from './structure/core/conformerRefine.ts';
+export {
+  REFINED_RANKING,
+  REFINED_SAME_ENERGY_TOLERANCE,
+  refineConformers,
+} from './structure/core/conformerRefine.ts';
+export type {
+  RefinedMinimum,
+  RefinedRanking,
+} from './structure/core/conformerRefineRank.ts';
+export {
+  isRefinedDuplicate,
+  rankByRefinedEnergy,
+} from './structure/core/conformerRefineRank.ts';
+export type { RankedConformer } from './structure/core/conformerMinimise.ts';
+export {
+  minimiseConformer,
+  rankByEnergy,
+} from './structure/core/conformerMinimise.ts';
+export type { KeptConformer } from './structure/core/conformerMinimum.ts';
+export {
+  SAME_CHIRALITY_TOLERANCE,
+  SAME_ENERGY_TOLERANCE,
+  SAME_SHAPE_TOLERANCE,
+  isKeptMinimum,
+  isSameMinimum,
+  isSameShape,
+  minimisedShapes,
+} from './structure/core/conformerMinimum.ts';
+export type {
+  ConformerOptions,
+  ConformerStrategy,
+  MinimisationAlgorithm,
+} from './structure/core/conformerOptions.ts';
+export {
+  CONFORMER_STRATEGIES,
+  DEFAULT_CONFORMER_OPTIONS,
+  MINIMISATION_ALGORITHMS,
+  MINIMISATION_LABELS,
+  ROTATABLE_BOND_WARNING,
+  STRATEGY_DETAILS,
+  STRATEGY_LABELS,
+  isConformerStrategy,
+  isMinimisationAlgorithm,
+  sameConformerOptions,
+} from './structure/core/conformerOptions.ts';
+export type { ConformerSession } from './structure/core/conformerSession.ts';
+export {
+  keepConformerSession,
+  openConformerSession,
+  readPotentialCount,
+} from './structure/core/conformerSession.ts';
+export type {
+  ConformerShape,
+  PrincipalMoments,
+} from './structure/core/conformerShape.ts';
+export {
+  conformerShape,
+  hasFiniteCoordinates,
+} from './structure/core/conformerShape.ts';
+export { registerResources } from './structure/core/oclResources.ts';

package/src/core.ts

@@ -10,6 +10,7 @@ export * from './download/core/index.ts';
 export * from './ecosystem/core/index.ts';
 export * from './error/core/index.ts';
 export * from './format/core/index.ts';
+export * from './language/core/index.ts';
 export * from './orbital/core/index.ts';
 export * from './overlay/core/index.ts';
 export * from './parallel/core/index.ts';

package/src/credits/core/credits.ts

@@ -143,6 +143,22 @@ export const CREDITS = [
     description: 'the array and spectrum operations the data goes through.',
     license: 'MIT',
   },
+  {
+    id: 'occ',
+    name: 'OCC',
+    href: 'https://github.com/peterspackman/occ',
+    description:
+      'the GFN2-xTB implementation the refined geometries and energies come from.',
+    license: 'GPL-3.0',
+  },
+  {
+    id: 'xtb-wasm',
+    name: 'xtb-wasm',
+    href: 'https://github.com/cheminfo/xtb-wasm',
+    description:
+      'GFN2-xTB compiled to WebAssembly, driven from a pool of web workers.',
+    license: 'MIT',
+  },
   {
     id: 'molstar',
     name: 'Mol*',

package/src/ecosystem/core/index.ts

@@ -15,6 +15,7 @@ export type {
   SiteMarkColors,
   SiteName,
   SiteRecord,
+  SiteUrlOptions,
 } from './sites.ts';
 export { ECOSYSTEM_SITES, siteUrl } from './sites.ts';
 export { siteTokensCss } from './tokens.ts';

package/src/ecosystem/core/sites.ts

@@ -1,4 +1,6 @@
 // tokens-ok: file — every site's two colours are declared here.
+import { withLanguageParam } from '../../language/core/languageParam.ts';
+
 import type { EcosystemSite, SiteRecord } from './types.ts';
 
 export type {
@@ -118,8 +120,10 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     tagline: 'Turn a batch of NMR spectra into a map of your samples.',
     group: 'spectra',
     brand: '#4d7c0f',
-    brandAlt: '#b91c1c',
-    mark: { plate: '#4d7c0f', accent: '#b91c1c' },
+    // A yellow, because it is what stays apart from both this green and the
+    // white for a red–green colour-blind visitor; any red merges with the plate.
+    brandAlt: '#a16207',
+    mark: { plate: '#4d7c0f', accent: '#fde047' },
   },
   {
     id: 'derepflow',
@@ -294,6 +298,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'atoms', alt: 'cheminfo', dot: true },
     host: 'atoms.cheminfo.org',
     repository: 'https://github.com/cheminfo/atoms.cheminfo.org',
+    publicRepository: true,
     tagline: 'Electrons, neutrons, Lewis structures and oxidation states.',
     group: 'practice',
     brand: '#b91c1c',
@@ -307,6 +312,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'moles', alt: 'cheminfo', dot: true },
     host: 'moles.cheminfo.org',
     repository: 'https://github.com/cheminfo/moles.cheminfo.org',
+    publicRepository: true,
     tagline: 'Balance a reaction, and work out its mass composition.',
     group: 'practice',
     brand: '#334155',
@@ -330,11 +336,25 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
   },
 ];
 
+/** How a link to a site is written, beyond the site itself. */
+export interface SiteUrlOptions {
+  /**
+   * The language the visitor is reading in, carried so the site opens in it
+   * rather than in the one it defaults to.
+   * @default undefined — the link names no language
+   */
+  language?: string;
+}
+
 /**
  * The address of a site, which is its host over https.
  * @param site - The site being linked to.
+ * @param options - See {@link SiteUrlOptions}.
  * @returns The URL to open.
  */
-export function siteUrl(site: SiteRecord): string {
-  return `https://${site.host}/`;
+export function siteUrl(
+  site: SiteRecord,
+  options: SiteUrlOptions = {},
+): string {
+  return withLanguageParam(`https://${site.host}/`, options.language);
 }

package/src/ecosystem/ui/EcosystemLinks.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactElement } from 'react';
 
+import { useSiteLanguage } from '../../language/ui/siteLanguageContext.ts';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import { groupedSites } from '../core/lookup.ts';
@@ -87,6 +88,7 @@ export interface EcosystemLinksProps {
  * @returns The section of links.
  */
 export function EcosystemLinks(props: EcosystemLinksProps): ReactElement {
+  const language = useSiteLanguage();
   const {
     className,
     currentSiteId,
@@ -117,7 +119,7 @@ export function EcosystemLinks(props: EcosystemLinksProps): ReactElement {
                   <a
                     key={site.id}
                     style={{ ...LINK_STYLE, color: site.brand }}
-                    href={siteUrl(site)}
+                    href={siteUrl(site, { language })}
                   >
                     {site.host}
                   </a>

package/src/ecosystem/ui/SiteTile.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactElement } from 'react';
 
+import { useSiteLanguage } from '../../language/ui/siteLanguageContext.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import { siteNameColors } from '../core/nameColors.ts';
 import type { EcosystemSite, SiteId } from '../core/sites.ts';
@@ -85,6 +86,7 @@ export interface SiteTileProps {
  * @returns The tile.
  */
 export function SiteTile(props: SiteTileProps): ReactElement {
+  const language = useSiteLanguage();
   const {
     className,
     site,
@@ -140,7 +142,7 @@ export function SiteTile(props: SiteTileProps): ReactElement {
     <a
       className={className}
       style={style}
-      href={siteUrl(site)}
+      href={siteUrl(site, { language })}
       target={newTab ? '_blank' : undefined}
       rel={newTab ? 'noreferrer' : undefined}
       onMouseEnter={() => onHover?.(site.id)}

package/src/ecosystem/ui/glyphs.tsx

@@ -179,30 +179,24 @@ export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
       />
     </g>
   ),
-  // Two groups of samples with the outline that holds each: the picture the
-  // tool exists to draw. One is drawn and one is filled rather than both
-  // outlined, because two rings crossing close up into a blob at 16 px —
-  // checked at 16, 20, 24, 32 and 64 before this was settled on.
+  // A score plot without its axes: four samples, and the three the analysis
+  // sets apart carrying the answering colour — the map the tool exists to
+  // draw. The spacing is irregular so the groups read as measured samples
+  // rather than as a pattern, and the two groups sit six units apart, against
+  // under one inside either.
   metabo: (accent) => (
     <>
-      <ellipse
-        cx="12"
-        cy="12.5"
-        rx="5.8"
-        ry="9"
-        fill="none"
-        stroke="#ffffff"
-        strokeWidth="3"
-        transform="rotate(-32 12 12.5)"
-      />
-      <ellipse
-        cx="20.5"
-        cy="20"
-        rx="5.4"
-        ry="8.6"
-        fill={accent}
-        transform="rotate(32 20.5 20)"
-      />
+      <g fill="#ffffff">
+        <circle cx="6.6" cy="20.4" r="2.6" />
+        <circle cx="12.4" cy="18.3" r="2.6" />
+        <circle cx="9.3" cy="25.8" r="2.6" />
+        <circle cx="14.9" cy="24.1" r="2.6" />
+      </g>
+      <g fill={accent}>
+        <circle cx="20.1" cy="7.2" r="2.6" />
+        <circle cx="25.8" cy="8.6" r="2.6" />
+        <circle cx="22.2" cy="13.2" r="2.6" />
+      </g>
     </>
   ),
   // One formula branching into every structure it can be.

package/src/format/core/index.ts

@@ -14,4 +14,4 @@ export { roundTo } from './roundTo.ts';
 export { formatSuperscript } from './superscript.ts';
 export type { DurationStyle, FormatDurationOptions } from './units.ts';
 export { formatBytes, formatDuration } from './units.ts';
-export { pluralize } from './words.ts';
+export { ordinal, pluralize } from './words.ts';

package/src/format/core/words.ts

@@ -15,3 +15,22 @@ export function pluralize(
 ): string {
   return count === 1 ? singular : plural;
 }
+
+/**
+ * English ordinal of a position.
+ *
+ * Only the ordinal comes back, never the noun it counts, so the caller writes
+ * the sentence: `the ${ordinal(n)} conformer produced`.
+ * @param position - 1-based position.
+ * @returns E.g. `1st`, `2nd`, `12th`, `23rd`.
+ */
+export function ordinal(position: number): string {
+  const teens = position % 100;
+  const suffix =
+    teens >= 11 && teens <= 13
+      ? 'th'
+      : (ORDINAL_SUFFIXES[position % 10] ?? 'th');
+  return `${position}${suffix}`;
+}
+
+const ORDINAL_SUFFIXES: Record<number, string> = { 1: 'st', 2: 'nd', 3: 'rd' };

package/src/language/core/index.ts

@@ -0,0 +1,7 @@
+export { languageName } from './languageName.ts';
+export {
+  LANGUAGE_PARAM,
+  isLanguageTag,
+  readLanguageParam,
+  withLanguageParam,
+} from './languageParam.ts';

package/src/language/core/languageName.ts

@@ -0,0 +1,16 @@
+/**
+ * The name of a language, e.g. `French` for `fr`.
+ * @param locale - The locale to name.
+ * @param displayLocale - The language the name is written in.
+ * @returns The name, or the tag itself when the runtime cannot name it.
+ */
+export function languageName(locale: string, displayLocale = 'en'): string {
+  try {
+    return (
+      new Intl.DisplayNames([displayLocale], { type: 'language' }).of(locale) ??
+      locale
+    );
+  } catch {
+    return locale;
+  }
+}

package/src/language/core/languageParam.ts

@@ -0,0 +1,70 @@
+/**
+ * The language a page is read in, as the family carries it between its sites.
+ *
+ * A link from one site to another keeps the language the visitor is reading
+ * in: the tag travels as a query parameter rather than as the path prefix a
+ * translated site routes by, because the site being linked to may not speak
+ * that language at all. A parameter it does not know is ignored; a `/fr/`
+ * path it does not have is a 404.
+ */
+
+import { parseQueryString } from '../../router/core/query.ts';
+
+/** Query parameter every site of the family carries its language in. */
+export const LANGUAGE_PARAM = 'lang';
+
+/**
+ * Whether a string is a language a link may name: a BCP 47 tag already
+ * written in its canonical form, e.g. `fr`, `pt-BR`, `zh-Hant`.
+ * @param value - The candidate tag.
+ * @returns True when the tag is valid and canonical.
+ */
+export function isLanguageTag(value: string): boolean {
+  if (value.length === 0 || value.length > 35) return false;
+  try {
+    return Intl.getCanonicalLocales(value)[0] === value;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The language an address names.
+ * @param search - The query string, with or without its leading `?`.
+ * @returns The tag, or `undefined` when the address names none or names
+ *   something that is not a language.
+ */
+export function readLanguageParam(search: string): string | undefined {
+  const value = parseQueryString(search)[LANGUAGE_PARAM];
+  if (value === undefined || !isLanguageTag(value)) return undefined;
+  return value;
+}
+
+/**
+ * An address that names the language it should be read in.
+ * @param url - The address, absolute or relative.
+ * @param language - The tag to write, or `undefined` to leave the address
+ *   alone — which is what a site passes while it is in the language every
+ *   other site defaults to.
+ * @returns The address, with the language written into its query.
+ */
+export function withLanguageParam(
+  url: string,
+  language: string | undefined,
+): string {
+  if (language === undefined || !isLanguageTag(language)) return url;
+  let address: URL;
+  try {
+    address = new URL(url, RELATIVE_BASE);
+  } catch {
+    return url;
+  }
+  address.searchParams.set(LANGUAGE_PARAM, language);
+  const written = address.toString();
+  return written.startsWith(RELATIVE_BASE)
+    ? written.slice(RELATIVE_BASE.length)
+    : written;
+}
+
+// Only ever used to resolve a relative address, and stripped again after.
+const RELATIVE_BASE = 'https://relative.invalid';

package/src/language/ui/SiteLanguage.tsx

@@ -0,0 +1,26 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import { SiteLanguageContext } from './siteLanguageContext.ts';
+
+/** Props of {@link SiteLanguage}. */
+export interface SiteLanguageProps {
+  /**
+   * The language the page is being read in, or `undefined` while it is the
+   * one every site opens in — a link then names no language at all.
+   */
+  value: string | undefined;
+  /** The page. */
+  children: ReactNode;
+}
+
+/**
+ * Tells every link to a sibling site which language the visitor is reading in,
+ * so moving between the tools of the family keeps the language rather than
+ * landing in English again.
+ * @param props - The language, and the page under it.
+ * @returns The page.
+ */
+export function SiteLanguage(props: SiteLanguageProps): ReactElement {
+  const { value, children } = props;
+  return <SiteLanguageContext value={value}>{children}</SiteLanguageContext>;
+}

package/src/language/ui/index.ts

@@ -0,0 +1,3 @@
+export type { SiteLanguageProps } from './SiteLanguage.tsx';
+export { SiteLanguage } from './SiteLanguage.tsx';
+export { useSiteLanguage } from './siteLanguageContext.ts';

package/src/language/ui/siteLanguageContext.ts

@@ -0,0 +1,20 @@
+import { createContext, use } from 'react';
+
+import { readLanguageParam } from '../core/languageParam.ts';
+
+/** What a site declares the page is being read in. */
+export const SiteLanguageContext = createContext<string | undefined>(undefined);
+
+/**
+ * The language a link out of this page should name.
+ *
+ * Under a `SiteLanguage` it is what the site declared. Without one it is
+ * whatever the address itself names, so a site that has not been told anything
+ * still passes on the language it was opened in.
+ * @returns The tag, or `undefined` when no language is to be carried.
+ */
+export function useSiteLanguage(): string | undefined {
+  const declared = use(SiteLanguageContext);
+  if (declared !== undefined) return declared;
+  return readLanguageParam(globalThis.location?.search ?? '');
+}

package/src/orbital/core/atomicOrbitals.ts

@@ -29,6 +29,7 @@ import {
 import type { RealHarmonic } from './realHarmonics.ts';
 import { harmonicsOf, subshellLetter } from './realHarmonics.ts';
 import { slaterScreening } from './screening.ts';
+import { slaterRemovalEnergy } from './slaterEnergy.ts';
 
 /** One atomic orbital of one element: a shape, a size and an occupancy. */
 export interface AtomicOrbital {
@@ -50,8 +51,16 @@ export interface AtomicOrbital {
   effectiveCharge: number;
   /** Shielding `S` those rules produced. */
   shielding: number;
-  /** `−13.6 Z_eff²/n²`, electronvolts. */
+  /** `−13.606 Z_eff²/n²`, electronvolts: one rydberg times `Z_eff²/n²`. */
   energy: number;
+  /**
+   * Energy to pull this electron off the atom, electronvolts: the difference
+   * of Slater total energies between the ion and the atom. `null` when the
+   * subshell is empty, there being no electron to remove. This, not
+   * {@link AtomicOrbital.energy}, is the number to compare with a measured
+   * ionisation energy — see `slaterEnergy.ts`.
+   */
+  removalEnergy: number | null;
   /** `n − ℓ − 1` spheres on which the wavefunction changes sign. */
   radialNodes: number;
   /** ℓ planes or cones on which it changes sign. */
@@ -120,6 +129,12 @@ export function atomicOrbitalsOf(
       l: subshell.l,
       charge,
     };
+    // Once per subshell, not once per harmonic: the seven orbitals of an f
+    // subshell share one removal energy.
+    const removalEnergy =
+      subshellElectrons === 0
+        ? null
+        : slaterRemovalEnergy(atomicNumber, configuration, subshell);
     const harmonics = harmonicsOf(subshell.l);
     const spread = hundDistribution(subshellElectrons, harmonics.length);
     for (let index = 0; index < harmonics.length; index++) {
@@ -135,6 +150,7 @@ export function atomicOrbitalsOf(
         effectiveCharge: charge,
         shielding: screening.shielding,
         energy: orbitalEnergy(parameters),
+        removalEnergy,
         radialNodes: radialNodeCount(parameters),
         angularNodes: subshell.l,
         meanRadius: meanRadius(parameters),

package/src/orbital/core/hydrogenic.ts

@@ -57,7 +57,8 @@ export function meanRadius(parameters: HydrogenicParameters): number {
 }
 
 /**
- * Orbital energy in the hydrogen-like model, `E = −13.6 Z²/n²` eV.
+ * Orbital energy in the hydrogen-like model, `E = −13.606 Z²/n²` eV — one
+ * rydberg times `Z²/n²`.
  * @param parameters - Which orbital.
  * @returns The energy in electronvolts, always negative.
  */

package/src/orbital/core/index.ts

@@ -69,3 +69,4 @@ export type {
 export { runAtomicSample } from './sample.ts';
 export type { Screening } from './screening.ts';
 export { groupRank, slaterScreening } from './screening.ts';
+export { slaterRemovalEnergy, slaterTotalEnergy } from './slaterEnergy.ts';

package/src/orbital/core/slaterEnergy.ts

@@ -0,0 +1,83 @@
+/**
+ * What Slater's rules are actually good for: the energy it takes to pull one
+ * electron off the atom.
+ *
+ * The hydrogen-like orbital energy `−Ry Z_eff²/n²` is the model's own number
+ * and it orders the orbitals correctly, but it is not an ionisation energy and
+ * must never be read as one — it is 5.4× the measured value for neon, while
+ * being within 10% for lithium, so it is not even a constant factor off.
+ *
+ * Slater fitted his rules to *total* energies, and that is how they are used:
+ * add up `n Z_eff²/n²` over every electron of the atom, do the same for the ion
+ * with one electron gone — recomputing the shielding, which is the whole point,
+ * since the remaining electrons are screened by one fewer neighbour — and
+ * subtract. Over the first four periods that difference lands within a factor
+ * 0.74–1.81 of the measured first ionisation energy, against 0.9–5.4 for the
+ * orbital energy.
+ */
+
+import { RYDBERG_ELECTRONVOLTS } from './constants.ts';
+import type { Subshell, SubshellOccupancy } from './electronConfiguration.ts';
+import { slaterScreening } from './screening.ts';
+
+/**
+ * Total electronic energy of a configuration in the Slater model.
+ * @param atomicNumber - Proton count, the `Z` each electron is screened from.
+ * @param configuration - Every occupied subshell.
+ * @returns The sum of `−Ry Z_eff²/n²` over every electron, electronvolts.
+ */
+export function slaterTotalEnergy(
+  atomicNumber: number,
+  configuration: readonly SubshellOccupancy[],
+): number {
+  let energy = 0;
+  for (const occupied of configuration) {
+    const { effectiveCharge } = slaterScreening(
+      atomicNumber,
+      configuration,
+      occupied,
+    );
+    energy -=
+      (occupied.electrons *
+        RYDBERG_ELECTRONVOLTS *
+        effectiveCharge *
+        effectiveCharge) /
+      (occupied.n * occupied.n);
+  }
+  return energy;
+}
+
+/**
+ * Energy needed to take one electron out of a subshell and off the atom.
+ * @param atomicNumber - Proton count.
+ * @param configuration - Every occupied subshell of the neutral atom.
+ * @param subshell - The subshell the electron leaves.
+ * @returns `E(ion) − E(atom)`, electronvolts, positive for a bound electron.
+ * @throws {RangeError} When that subshell holds no electron to remove.
+ */
+export function slaterRemovalEnergy(
+  atomicNumber: number,
+  configuration: readonly SubshellOccupancy[],
+  subshell: Subshell,
+): number {
+  const ion: SubshellOccupancy[] = [];
+  let found = false;
+  for (const occupied of configuration) {
+    if (occupied.n === subshell.n && occupied.l === subshell.l) {
+      found = true;
+      if (occupied.electrons === 1) continue;
+      ion.push({ ...occupied, electrons: occupied.electrons - 1 });
+      continue;
+    }
+    ion.push(occupied);
+  }
+  if (!found) {
+    throw new RangeError(
+      `the ${subshell.n}${'spdf'[subshell.l] ?? '?'} subshell holds no electron to remove`,
+    );
+  }
+  return (
+    slaterTotalEnergy(atomicNumber, ion) -
+    slaterTotalEnergy(atomicNumber, configuration)
+  );
+}