smiles-js 2.0.3 → 2.1.0

package/src/manipulation.js

@@ -12,8 +12,13 @@ import {
   cloneSubstitutions,
   cloneComponents,
   deepCloneRing,
+  deepCloneLinear,
+  deepCloneFusedRing,
+  deepCloneMolecule,
 } from './constructors.js';
-import { validatePosition, isLinearNode, isMoleculeNode } from './ast.js';
+import {
+  validatePosition, isLinearNode, isMoleculeNode, isRingNode, isFusedRingNode,
+} from './ast.js';
 import { computeFusedRingPositions } from './layout/index.js';
 
 /**
@@ -29,10 +34,16 @@ export function ringAttach(ring, position, attachment, options = {}) {
     updatedAttachments[position] = [];
   }
 
-  // Clone the attachment and set metaIsSibling if provided in options
+  // Clone the attachment and set metaIsSibling/metaBeforeInline if provided in options
   let attachmentToAdd = attachment;
-  if (options.sibling !== undefined) {
-    attachmentToAdd = { ...attachment, metaIsSibling: options.sibling };
+  if (options.sibling !== undefined || options.beforeInline !== undefined) {
+    attachmentToAdd = { ...attachment };
+    if (options.sibling !== undefined) {
+      attachmentToAdd.metaIsSibling = options.sibling;
+    }
+    if (options.beforeInline !== undefined) {
+      attachmentToAdd.metaBeforeInline = options.beforeInline;
+    }
   }
 
   updatedAttachments[position] = [...updatedAttachments[position], attachmentToAdd];
@@ -627,3 +638,397 @@ export function moleculeReplaceComponent(molecule, index, newComponent) {
   newComponents[index] = newComponent;
   return createMoleculeNode(newComponents);
 }
+
+/**
+ * Generic repeat / polymer methods
+ */
+
+/**
+ * Deep-clone any AST node
+ */
+function cloneNode(node) {
+  if (isRingNode(node)) return deepCloneRing(node);
+  if (isLinearNode(node)) return deepCloneLinear(node);
+  if (isFusedRingNode(node)) return deepCloneFusedRing(node);
+  if (isMoleculeNode(node)) return deepCloneMolecule(node);
+  throw new Error(`Unknown node type: ${node?.type}`);
+}
+
+/**
+ * Find the maximum ring number used anywhere in a node tree.
+ * This is needed to renumber ring copies so ring markers don't collide.
+ */
+function maxRingNumber(node) {
+  if (isRingNode(node)) {
+    let max = node.ringNumber || 0;
+    Object.values(node.attachments || {}).forEach((list) => {
+      list.forEach((att) => { max = Math.max(max, maxRingNumber(att)); });
+    });
+    return max;
+  }
+  if (isFusedRingNode(node)) {
+    let max = 0;
+    (node.rings || []).forEach((r) => { max = Math.max(max, r.ringNumber || 0); });
+    return max;
+  }
+  if (isMoleculeNode(node)) {
+    let max = 0;
+    (node.components || []).forEach((c) => { max = Math.max(max, maxRingNumber(c)); });
+    return max;
+  }
+  if (isLinearNode(node)) {
+    let max = 0;
+    Object.values(node.attachments || {}).forEach((list) => {
+      list.forEach((att) => { max = Math.max(max, maxRingNumber(att)); });
+    });
+    return max;
+  }
+  return 0;
+}
+
+/**
+ * Shift all ring numbers in a node by a given delta.
+ * Returns a new node (immutable).
+ */
+function shiftRingNumbers(node, delta) {
+  if (delta === 0) return node;
+
+  if (isRingNode(node)) {
+    const newAttachments = {};
+    Object.entries(node.attachments || {}).forEach(([pos, list]) => {
+      newAttachments[pos] = list.map((att) => shiftRingNumbers(att, delta));
+    });
+    return createRingNode(
+      node.atoms,
+      node.size,
+      node.ringNumber + delta,
+      node.offset,
+      node.substitutions,
+      newAttachments,
+      node.bonds || [],
+      node.metaBranchDepths || null,
+    );
+  }
+
+  if (isFusedRingNode(node)) {
+    const newRings = (node.rings || []).map((r) => ({
+      ...r,
+      ringNumber: (r.ringNumber || 1) + delta,
+    }));
+    return createFusedRingNode(newRings);
+  }
+
+  if (isMoleculeNode(node)) {
+    const newComponents = (node.components || []).map((c) => shiftRingNumbers(c, delta));
+    return createMoleculeNode(newComponents);
+  }
+
+  if (isLinearNode(node)) {
+    const newAttachments = {};
+    Object.entries(node.attachments || {}).forEach(([pos, list]) => {
+      newAttachments[pos] = list.map((att) => shiftRingNumbers(att, delta));
+    });
+    return createLinearNode(node.atoms, node.bonds, newAttachments, node.metaLeadingBond);
+  }
+
+  return node;
+}
+
+/**
+ * Repeat a monomer unit n times, creating a polymer chain.
+ *
+ * leftId and rightId are 1-indexed positions defining the attachment points.
+ * For Linear nodes, leftId=1 and rightId=atoms.length are the natural endpoints.
+ * For Ring nodes, leftId=1 and rightId=size are the natural SMILES endpoints
+ * (the first and last atoms emitted in the ring's SMILES).
+ *
+ * The resulting Molecule concatenates n copies. In SMILES, concatenation
+ * bonds the last atom of component i to the first atom of component i+1.
+ *
+ * @param {Object} node - Any AST node (Ring, Linear, FusedRing, Molecule)
+ * @param {number} n - Number of repeating units (>= 1)
+ * @param {number} leftId - 1-indexed left (incoming) attachment point
+ * @param {number} rightId - 1-indexed right (outgoing) attachment point
+ * @returns {Object} Molecule node (or clone for n=1)
+ */
+export function repeat(node, n, leftId, rightId) {
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error('Repeat count n must be an integer >= 1');
+  }
+  if (!Number.isInteger(leftId) || leftId < 1) {
+    throw new Error('leftId must be a positive integer');
+  }
+  if (!Number.isInteger(rightId) || rightId < 1) {
+    throw new Error('rightId must be a positive integer');
+  }
+
+  if (n === 1) {
+    return cloneNode(node);
+  }
+
+  // For simple Linear nodes (no attachments), efficiently concatenate atoms arrays
+  const hasAttachments = isLinearNode(node) && Object.keys(node.attachments || {}).length > 0;
+  if (isLinearNode(node) && !hasAttachments && leftId === 1 && rightId === node.atoms.length) {
+    let atoms = [];
+    let bonds = [];
+    for (let i = 0; i < n; i += 1) {
+      atoms = [...atoms, ...node.atoms];
+      if (node.bonds.length > 0) {
+        bonds = [...bonds, ...node.bonds];
+      }
+    }
+    return createLinearNode(atoms, bonds, {});
+  }
+
+  const maxRing = maxRingNumber(node);
+  const copies = [];
+  for (let i = 0; i < n; i += 1) {
+    const delta = i * maxRing;
+    const copy = delta > 0 ? shiftRingNumbers(cloneNode(node), delta) : cloneNode(node);
+    copies.push(copy);
+  }
+
+  return createMoleculeNode(copies);
+}
+
+/**
+ * Repeat a ring n times by fusing, creating an acene-like system.
+ *
+ * Each new ring shares `offset` atoms with the previous ring,
+ * producing linear fused ring systems (naphthalene, anthracene, etc.).
+ *
+ * @param {Object} ring - Ring AST node
+ * @param {number} n - Total number of rings (>= 1)
+ * @param {number} offset - Fusion offset (shared atoms between adjacent rings)
+ * @returns {Object} Ring (n=1) or FusedRing (n>=2) node
+ */
+export function fusedRepeat(ring, n, offset) {
+  if (!isRingNode(ring)) {
+    throw new Error('fusedRepeat requires a Ring node');
+  }
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error('Repeat count n must be an integer >= 1');
+  }
+  if (!Number.isInteger(offset) || offset < 1) {
+    throw new Error('Fusion offset must be a positive integer');
+  }
+
+  if (n === 1) {
+    return deepCloneRing(ring);
+  }
+
+  // First fusion: ring1.fuse(offset, ring2)
+  const ring1 = createRingNode(
+    ring.atoms,
+    ring.size,
+    1,
+    0,
+    ring.substitutions,
+    ring.attachments,
+    ring.bonds || [],
+    ring.metaBranchDepths || null,
+  );
+  const ring2 = createRingNode(
+    ring.atoms,
+    ring.size,
+    2,
+    offset,
+    ring.substitutions,
+    {},
+    ring.bonds || [],
+    null,
+  );
+  let result = createFusedRingNode([ring1, ring2]);
+
+  // Additional fusions
+  for (let i = 2; i < n; i += 1) {
+    const nextRing = createRingNode(
+      ring.atoms,
+      ring.size,
+      i + 1,
+      offset,
+      ring.substitutions,
+      {},
+      ring.bonds || [],
+      null,
+    );
+    result = fusedRingAddRing(result, offset + i * (ring.size - offset), nextRing);
+  }
+
+  return result;
+}
+
+/**
+ * Mirror / symmetry methods
+ */
+
+/**
+ * Mirror a linear chain around a pivot atom to create a palindromic structure.
+ *
+ * Takes atoms [0..pivotId-1] (left half including pivot), then appends
+ * atoms [pivotId-2..0] in reverse. The pivot atom appears once in the center.
+ * Bonds and attachments are mirrored accordingly.
+ *
+ * @param {Object} linear - Linear AST node
+ * @param {number} [pivotId] - 1-indexed pivot position (default: atoms.length)
+ * @returns {Object} New Linear or Molecule node
+ */
+export function linearMirror(linear, pivotId) {
+  const pivot = pivotId !== undefined ? pivotId : linear.atoms.length;
+  if (!Number.isInteger(pivot) || pivot < 1 || pivot > linear.atoms.length) {
+    throw new Error(
+      `pivotId must be an integer between 1 and ${linear.atoms.length}`,
+    );
+  }
+
+  // Left half: atoms [0..pivot-1] (includes pivot)
+  const leftAtoms = linear.atoms.slice(0, pivot);
+  // Right half: atoms [0..pivot-2] reversed (excludes pivot)
+  const rightAtoms = linear.atoms.slice(0, pivot - 1).reverse();
+
+  const newAtoms = [...leftAtoms, ...rightAtoms];
+
+  // Mirror bonds
+  // In main-chain format, bonds[i] is the bond between atoms[i] and atoms[i+1]
+  // Pad bonds to full length (pivot-1 entries for the left half) so mirror is correct
+  const paddedLeftBonds = Array.from(
+    { length: pivot - 1 },
+    (_, i) => linear.bonds[i] || null,
+  );
+  const rightBonds = paddedLeftBonds.slice(0, pivot - 1).reverse();
+  const newBonds = [...paddedLeftBonds, ...rightBonds];
+
+  // Mirror attachments
+  const leftAttachments = linear.attachments || {};
+  const hasAtt = Object.keys(leftAttachments).length > 0;
+
+  if (!hasAtt) {
+    return createLinearNode(newAtoms, newBonds, {});
+  }
+
+  // Attachments need ring renumbering for the mirrored half
+  const totalMaxRing = maxRingNumber(linear);
+  const newAttachments = cloneAttachments(leftAttachments);
+
+  // Mirror each attachment position: position p mirrors to (2*pivot - p)
+  Object.entries(leftAttachments).forEach(([posStr, attList]) => {
+    const pos = Number(posStr);
+    if (pos === pivot) return; // pivot attachments stay, no mirror
+    const mirrorPos = 2 * pivot - pos;
+    if (mirrorPos < 1 || mirrorPos > newAtoms.length) return;
+    if (!newAttachments[mirrorPos]) {
+      newAttachments[mirrorPos] = [];
+    }
+    attList.forEach((att) => {
+      const shifted = totalMaxRing > 0
+        ? shiftRingNumbers(cloneNode(att), totalMaxRing)
+        : cloneNode(att);
+      newAttachments[mirrorPos] = [...newAttachments[mirrorPos], shifted];
+    });
+  });
+
+  return createLinearNode(newAtoms, newBonds, newAttachments);
+}
+
+/**
+ * Mirror a molecule's component sequence to create an ABA-like structure.
+ *
+ * Takes components [0..pivot], then appends components [pivot-1..0] in reverse
+ * with ring numbers shifted to avoid collisions.
+ *
+ * @param {Object} molecule - Molecule AST node
+ * @param {number} [pivotComponent] - 0-indexed pivot component (default: last)
+ * @returns {Object} New Molecule node
+ */
+export function moleculeMirror(molecule, pivotComponent) {
+  const pivot = pivotComponent !== undefined
+    ? pivotComponent
+    : molecule.components.length - 1;
+  if (!Number.isInteger(pivot) || pivot < 0 || pivot >= molecule.components.length) {
+    throw new Error(
+      `pivotComponent must be an integer between 0 and ${molecule.components.length - 1}`,
+    );
+  }
+
+  // Left half: components [0..pivot] (includes pivot)
+  const leftComponents = molecule.components.slice(0, pivot + 1);
+  // Right half: components [0..pivot-1] reversed (excludes pivot)
+  const rightSources = molecule.components.slice(0, pivot).reverse();
+
+  // Shift ring numbers in mirrored components
+  let totalMaxRing = 0;
+  leftComponents.forEach((c) => {
+    totalMaxRing = Math.max(totalMaxRing, maxRingNumber(c));
+  });
+
+  const rightComponents = rightSources.map((c) => {
+    const cloned = cloneNode(c);
+    return totalMaxRing > 0 ? shiftRingNumbers(cloned, totalMaxRing) : cloned;
+  });
+
+  return createMoleculeNode([...leftComponents, ...rightComponents]);
+}
+
+/**
+ * Mirror a ring's attachments and substitutions to create symmetric patterns.
+ *
+ * For each attachment/substitution at position p, adds a copy at the mirror
+ * position relative to the pivot. The mirror position for p around pivot v
+ * on a ring of size s is: ((2*v - p - 1) mod s) + 1  (1-indexed).
+ *
+ * @param {Object} ring - Ring AST node
+ * @param {number} [pivotId=1] - 1-indexed pivot position
+ * @returns {Object} New Ring node
+ */
+export function ringMirror(ring, pivotId) {
+  const pivot = pivotId !== undefined ? pivotId : 1;
+  validatePosition(pivot, ring.size);
+
+  const { size } = ring;
+
+  // Helper: compute mirror position (1-indexed)
+  // For a ring, position p mirrors around pivot v as:
+  // mirror = ((2*v - p - 1) mod s) + 1
+  // This reflects p across v on the ring.
+  const mirrorPos = (p) => ((((2 * (pivot - 1) - (p - 1)) % size) + size) % size) + 1;
+
+  // Mirror substitutions
+  const newSubstitutions = { ...ring.substitutions };
+  Object.entries(ring.substitutions).forEach(([posStr, atom]) => {
+    const pos = Number(posStr);
+    const mp = mirrorPos(pos);
+    if (mp !== pos && !newSubstitutions[mp]) {
+      newSubstitutions[mp] = atom;
+    }
+  });
+
+  // Mirror attachments
+  const newAttachments = cloneAttachments(ring.attachments);
+  const totalMaxRing = maxRingNumber(ring);
+
+  Object.entries(ring.attachments).forEach(([posStr, attList]) => {
+    const pos = Number(posStr);
+    const mp = mirrorPos(pos);
+    if (mp === pos) return; // pivot position or self-symmetric, skip
+    if (!newAttachments[mp]) {
+      newAttachments[mp] = [];
+    }
+    attList.forEach((att) => {
+      const shifted = totalMaxRing > 0
+        ? shiftRingNumbers(cloneNode(att), totalMaxRing)
+        : cloneNode(att);
+      newAttachments[mp] = [...newAttachments[mp], shifted];
+    });
+  });
+
+  return createRingNode(
+    ring.atoms,
+    ring.size,
+    ring.ringNumber,
+    ring.offset,
+    newSubstitutions,
+    newAttachments,
+    ring.bonds || [],
+    ring.metaBranchDepths || null,
+  );
+}