react-cheminfo 0.29.0 → 0.31.0

package/src/locales/fr.json

@@ -1,6 +1,9 @@
 {
   "language.label": "Langue",
   "chrome.pages": "Pages",
+  "account.signIn": "Se connecter",
+  "account.signOut": "Se déconnecter",
+  "account.signedInAs": "Connecté comme {name}",
   "ecosystem.tools": "Outils",
   "ecosystem.menuHeading": "Nos outils, tous dans le navigateur",
   "ecosystem.otherTools": "Nos autres outils",
@@ -180,12 +183,20 @@
   "download.format": "Format",
   "download.formatHelp": "Un PNG est une image de la figure, ce qu'acceptent une diapositive, une fenêtre de discussion ou un ticket. Un SVG est la figure elle-même : chaque trait reste net quel que soit l'agrandissement, et il reste modifiable ensuite.",
   "download.resolution": "Résolution",
-  "download.resolutionHelp": "Combien de pixels sont peints pour chaque pixel de la figure à l'écran. Deux convient pour une diapositive, trois ou quatre pour l'impression. Un SVG n'a pas de résolution propre : il est enregistré net à toute taille.",
+  "download.resolutionHelp": "Combien de fois la figure à l'écran mesure le fichier. Un PNG reçoit d'autant plus de pixels : deux convient pour une diapositive, trois ou quatre pour l'impression. Un SVG reste net à toute taille, et s'ouvre d'autant plus grand.",
   "download.resolutionExample": "Une figure large de 640 pixels à l'écran est enregistrée large de 1280 pixels.",
   "download.noFigure": "Il n'y a encore aucune figure à enregistrer sur la page.",
   "download.hintRasterSvg": "Un SVG contenant une image de {pixels} : une scène 3D n'a pas de forme vectorielle.",
-  "download.hintSvg": "Un SVG reste net à toute taille, la résolution ne s'applique donc pas. Dessiné {pixels}.",
+  "download.hintSvg": "S'ouvre à {pixels}, et reste net à toute taille.",
   "download.hintPng": "Enregistré {pixels}.",
+  "download.size": "Taille",
+  "download.sizeHelp": "La forme à laquelle la figure est dessinée pour le fichier. Elle est remise en page, si bien que les axes et les étiquettes s'ajustent à cette forme au lieu d'y être étirés. Une colonne de revue mesure 8,5 cm, et son texte s'imprime à la taille où il se lit à l'écran.",
+  "download.sizeScreen": "Comme affichée",
+  "download.sizeColumn": "Colonne de revue",
+  "download.sizeCustom": "Personnalisée",
+  "download.customSize": "Largeur × hauteur",
+  "download.width": "Largeur",
+  "download.height": "Hauteur",
   "pedagogy.check": "Vérifier",
   "pedagogy.revealHint": "Révéler un indice",
   "pedagogy.revealHintCount": "Révéler un indice ({revealed}/{total})",

package/src/overlay/ui/OverlayValueMenu.tsx

@@ -108,7 +108,13 @@ export function OverlayValueMenu<TValue extends string = string>(
               text={option.label}
               htmlTitle={option.title}
               disabled={option.disabled}
-              onClick={() => onChange(option.value)}
+              // A menu opened from inside a panel would otherwise dismiss the
+              // panel too, taking the reader's other settings away mid-choice.
+              shouldDismissPopover={false}
+              onClick={() => {
+                onChange(option.value);
+                setOpen(false);
+              }}
             />
           ))}
         </Menu>

package/src/structure/core/conformerBoltzmann.ts

@@ -0,0 +1,102 @@
+/**
+ * How a set of conformers divides itself between its minima at a temperature.
+ *
+ * Each conformer in the list is one minimum of the surface, so the share of
+ * molecules sitting in it is its Boltzmann factor over the sum of them all.
+ * Mirror-image conformers are separate entries and therefore counted twice,
+ * which is right: they are two distinct microstates, and that is what makes
+ * butane two-thirds gauche at room temperature rather than one-half.
+ *
+ * What this is not: a free energy. The weights come from a single energy per
+ * conformer, with no vibrational entropy, no zero-point energy and no solvent,
+ * so a share is the shape of the answer rather than the answer. It is also only
+ * as good as the energies handed to it — see {@link boltzmannConfidence}, which
+ * is what a table showing these shares says out loud.
+ */
+
+/** Room temperature, in kelvin, and what a share is quoted at unless asked otherwise. */
+export const ROOM_TEMPERATURE = 300;
+
+/**
+ * The gas constant in kcal/(mol·K), matching MMFF94's own energy unit.
+ *
+ * At {@link ROOM_TEMPERATURE} this makes RT 0.596 kcal/mol, so a conformer one
+ * kcal/mol up is populated about a fifth as much as the lowest.
+ */
+export const GAS_CONSTANT = 0.001_987_204_259;
+
+/**
+ * The share of molecules in each conformer at thermal equilibrium.
+ *
+ * The energies are taken relative to whichever is lowest, so they may be
+ * absolute or already relative. A conformer whose energy is unknown takes no
+ * share and is left out of the sum: it cannot be placed on the surface, and
+ * spreading the remainder over the others is a smaller lie than inventing a
+ * weight for it.
+ * @param energies - One energy per conformer in kcal/mol, `null` where unknown.
+ * @param temperature - Temperature in kelvin.
+ * @default ROOM_TEMPERATURE
+ * @returns One share per conformer, from 0 to 1 and summing to 1 over the ones
+ * that have an energy; `null` wherever the energy was `null`.
+ */
+export function boltzmannShares(
+  energies: ReadonlyArray<number | null>,
+  temperature: number = ROOM_TEMPERATURE,
+): Array<number | null> {
+  const shares: Array<number | null> = new Array(energies.length).fill(null);
+  if (energies.length === 0) return shares;
+
+  let lowest = Number.POSITIVE_INFINITY;
+  for (const energy of energies) {
+    if (energy !== null && Number.isFinite(energy) && energy < lowest) {
+      lowest = energy;
+    }
+  }
+  if (lowest === Number.POSITIVE_INFINITY) return shares;
+
+  // Measured from the lowest, so every exponent is at most zero and the sum
+  // cannot overflow however far apart the energies are.
+  const rt = GAS_CONSTANT * temperature;
+  if (!(rt > 0)) return shares;
+
+  const factors: Array<number | null> = new Array(energies.length).fill(null);
+  let total = 0;
+  for (let index = 0; index < energies.length; index++) {
+    const energy = energies[index] ?? null;
+    if (energy === null || !Number.isFinite(energy)) continue;
+    const factor = Math.exp(-(energy - lowest) / rt);
+    factors[index] = factor;
+    total += factor;
+  }
+  if (total === 0) return shares;
+
+  for (let index = 0; index < factors.length; index++) {
+    const factor = factors[index] ?? null;
+    if (factor !== null) shares[index] = factor / total;
+  }
+  return shares;
+}
+
+/**
+ * The factor a share is uncertain by, given how well the energies behind it are
+ * known.
+ *
+ * A population is exponential in the energy gap, so an error in a relative
+ * energy is an error in a share by `exp(error / RT)` — and RT is 0.596 kcal/mol
+ * at {@link ROOM_TEMPERATURE}. A force field that ranks conformers to within
+ * about 1.5 kcal/mol therefore places a population to within a factor of
+ * roughly twelve, which is why a share read off one is a shape and not a
+ * number.
+ * @param energyError - The typical error of a relative energy, kcal/mol.
+ * @param temperature - Temperature in kelvin.
+ * @default ROOM_TEMPERATURE
+ * @returns The multiplicative factor, at least 1.
+ */
+export function boltzmannConfidence(
+  energyError: number,
+  temperature: number = ROOM_TEMPERATURE,
+): number {
+  const rt = GAS_CONSTANT * temperature;
+  if (!(rt > 0) || !Number.isFinite(energyError) || energyError <= 0) return 1;
+  return Math.exp(energyError / rt);
+}

package/src/structure/core/conformerEnergy.ts

@@ -0,0 +1,97 @@
+/**
+ * Which energy of a conformer a reader is being shown.
+ *
+ * A refined conformer carries two of everything — what the force field said and
+ * what the better method said afterwards — and a table that mixes them is a
+ * ranking of nothing. So every column reads through one of these, and they all
+ * take the same ranking.
+ */
+
+// Type-only, so nothing here pulls the generator — or openchemlib — into
+// `react-cheminfo/core`, which every page loads.
+import type { ConformerRanking } from './conformers.ts';
+
+/**
+ * What a refinement has to say for an energy column to read it.
+ *
+ * The structural minimum rather than the whole `ConformerRefinement`, so a site
+ * that carries its conformers in a shape of its own — positions instead of a
+ * molfile, say — can still be read by the same helpers and drawn by the same
+ * table.
+ */
+export interface ConformerRowRefinement {
+  /** The rank this conformer held before the refinement reordered the set. */
+  forceFieldId: number;
+  /** Total energy at the relaxed geometry, kcal/mol. */
+  energy: number;
+  /** Energy above the most stable refined conformer, kcal/mol. */
+  relativeEnergy: number;
+}
+
+/**
+ * The least a conformer must carry to be ranked and drawn.
+ *
+ * `Conformer` from `react-cheminfo/conformers` satisfies it, and so does any
+ * per-site record that keeps the same three numbers.
+ */
+export interface ConformerRow {
+  /** 1-based rank in the set, most stable first. */
+  id: number;
+  /** Total force-field energy in kcal/mol, `null` when not computed. */
+  energy: number | null;
+  /** Energy above the most stable conformer, `null` without an energy. */
+  relativeEnergy: number | null;
+  /**
+   * What a better method said, once the set has been refined.
+   * @default null
+   */
+  refinement?: ConformerRowRefinement | null;
+}
+
+/**
+ * The energy above the most stable conformer, in the ranking asked for.
+ * @param conformer - The conformer to read.
+ * @param ranking - Which method's energies to read.
+ * @default 'force-field'
+ * @returns kcal/mol above the lowest, or `null` when that method produced none.
+ */
+export function relativeEnergyOf(
+  conformer: ConformerRow,
+  ranking: ConformerRanking = 'force-field',
+): number | null {
+  return ranking === 'refined'
+    ? (conformer.refinement?.relativeEnergy ?? null)
+    : conformer.relativeEnergy;
+}
+
+/**
+ * The total energy, in the ranking asked for, so the two columns of a row
+ * describe one method.
+ * @param conformer - The conformer to read.
+ * @param ranking - Which method's energies to read.
+ * @default 'force-field'
+ * @returns kcal/mol, or `null` when that method produced none.
+ */
+export function totalEnergyOf(
+  conformer: ConformerRow,
+  ranking: ConformerRanking = 'force-field',
+): number | null {
+  return ranking === 'refined'
+    ? (conformer.refinement?.energy ?? null)
+    : conformer.energy;
+}
+
+/**
+ * The ranking a set should be read in: refined once anything has been refined,
+ * the force field's until then.
+ * @param conformers - The set to inspect.
+ * @returns `'refined'` when at least one conformer carries a refinement.
+ */
+export function bestRanking(
+  conformers: readonly ConformerRow[],
+): ConformerRanking {
+  for (const conformer of conformers) {
+    if (conformer.refinement != null) return 'refined';
+  }
+  return 'force-field';
+}

package/src/structure/core/index.ts

@@ -1,5 +1,20 @@
 export type { AtomLabelPlacement, LabelledMolecule } from './atomLabels.ts';
 export { applyAtomLabels, customAtomLabel } from './atomLabels.ts';
+export {
+  GAS_CONSTANT,
+  ROOM_TEMPERATURE,
+  boltzmannConfidence,
+  boltzmannShares,
+} from './conformerBoltzmann.ts';
+export type {
+  ConformerRow,
+  ConformerRowRefinement,
+} from './conformerEnergy.ts';
+export {
+  bestRanking,
+  relativeEnergyOf,
+  totalEnergyOf,
+} from './conformerEnergy.ts';
 export type {
   EditorGesture,
   EditorGuideKey,