@khanacademy/perseus 3.0.0 → 4.0.0

package/src/widgets/molecule/molecule-layout.ts

@@ -0,0 +1,362 @@
+/**
+ * A molecule layout engine.
+ *
+ * This module transforms the SMILES syntax tree into a set of rendering
+ * instructions.  A rendering instruction is an object indicating what type of
+ * thing to render (e.g. text or line), where to render it, and any other style
+ * properties needed.
+ *
+ * For instance, an oxygen atom might be rendered as
+ * {type: "text", value: "O", pos: [0, 0], idx: "1,0"}
+ */
+
+// Default length of the bond.  This currently corresponds directly to pixels
+// in the renderer, but we may want this just to be arbitrary in the future.
+const bondLength = 30;
+
+/**
+ * Compute a coordinate by moving an angle and length from an origin point.
+ *
+ * Args:
+ *     origin: a list of the [x, y] coordinates of the origin
+ *     angle: an angle in degrees from the origin, following the typical
+ *         convention of +x axis = 0 degrees, +y axis = 90 degrees.
+ *     length: the distance to the new point
+ * Return:
+ *     a two-element list containing the [x, y] coordinates of the point.
+ */
+function polarAdd(origin: any, angle, length) {
+    const x = origin[0];
+    const y = origin[1];
+    return [
+        x + Math.cos((angle * 2 * Math.PI) / 360) * length,
+        y + -1.0 * Math.sin((angle * 2 * Math.PI) / 360) * length,
+    ];
+}
+
+/**
+ * Compute the layout for a single atom.
+ *
+ * Args:
+ *     atom: the atom node for which layout is being created, as returned from
+ *         convertTree; the computed position of this atom is added to this
+ *         object in place, in addition to being returned in the layout
+ *         instruction.
+ *         TODO(colin): refactor so that we don't need to modify this in place
+ *     atoms: the list of all atoms, as returned from convertTree, used to
+ *         position this atom appropriately relative to its neighbors
+ *     bonds: the list of all bonds, as returned from convertTree, used to
+ *         determine the geometry based on bond type
+ *     rotationAngle: a constant rotation for the whole molecule (in degrees)
+ *
+ * Return:
+ *     a rendering instruction for the atom, containing a type (text), the text
+ *     to render, the position, and the atom index
+ */
+function atomLayout(
+    atom: any,
+    atoms: any,
+    bonds: ReadonlyArray<any>,
+    rotationAngle: number,
+): any {
+    let textValue = atom.symbol;
+    if (textValue === "C" && Object.keys(atoms).length !== 1) {
+        // By convention, don't render the C for carbon in a chain.
+        textValue = null;
+    }
+
+    if (atom.idx === "1,0") {
+        // The first atom is special-cased because there are no neighbors for
+        // relative positioning.
+        const pos = [0, 0];
+        atom.pos = pos;
+        // Conventionally, molecules are rendered where the first bond is not
+        // horizontal, but at a 30 degree angle, so subtract 30 degrees for the
+        // first atom's direction.
+        atom.baseAngle = -30 + rotationAngle;
+        return {type: "text", value: textValue, pos: pos, idx: atom.idx};
+    }
+    // If we're an atom with any other index than the case just handled, we're
+    // guaranteed to have a neighbor who has a defined position.
+    const prevPositionedAtom =
+        atoms[
+            atom.connections.find(function (c) {
+                return atoms[c].pos;
+            })
+        ];
+
+    // Find this atom's index in the previous atom's connections
+    const myIndex = prevPositionedAtom.connections.indexOf(atom.idx);
+
+    let baseAngleIncrement = 60;
+    let angleIncrement = 120;
+    if (prevPositionedAtom.connections.length === 4) {
+        // By convention, if an atom has 4 bonds, we represent it with 90
+        // degree angles in 2D, even though it would have tetrahedral geometry
+        // with ~110 degree angles in 3D.
+        angleIncrement = 90;
+        baseAngleIncrement = 90;
+    } else if (
+        bonds.find(
+            (bond) => bond.bondType === "triple" && bond.to === atom.idx,
+        ) ||
+        bonds.find(
+            (bond) =>
+                bond.bondType === "triple" &&
+                bond.to === prevPositionedAtom.idx,
+        )
+    ) {
+        // Triple bonds have a bond angle of 180 degrees, so don't change the
+        // direction in which we made the previous bond.
+        angleIncrement = 0;
+        baseAngleIncrement = 0;
+    }
+
+    let angle = 0;
+    const idxPath = prevPositionedAtom.idx.split(":");
+    const lastAtomIdx = idxPath[idxPath.length - 1].split(",")[0];
+
+    // Conventionally, a single chain of atoms is rendered as a zig-zag pattern
+    // with 120 degree angles.  This means we need to flip the angle every
+    // other atom.  The parser ensures that indices always alternate odd-even,
+    // including taking into account branch points.
+    // TODO(colin): don't depend on the parser's indexing scheme and just track
+    // this entirely in the layout engine.
+    if (parseInt(lastAtomIdx) % 2 !== 0) {
+        angle =
+            prevPositionedAtom.baseAngle -
+            (baseAngleIncrement - angleIncrement * myIndex);
+    } else {
+        angle =
+            prevPositionedAtom.baseAngle +
+            (baseAngleIncrement - angleIncrement * myIndex);
+    }
+
+    const pos = polarAdd(prevPositionedAtom.pos, angle, bondLength);
+
+    atom.pos = pos;
+    atom.baseAngle = angle;
+
+    return {type: "text", value: textValue, pos: pos, idx: atom.idx};
+}
+
+/**
+ * Get the start and end position for a bond connecting two atoms.
+ *
+ * If we have non-carbon atoms that render with explicit letters connected by a
+ * bond, we don't want the line for the bond to extend into the lettering for
+ * the atom.
+ *
+ * This function returns the start and end positions of the bond's line, taking
+ * into account that one or both end points might need to be moved to make room
+ * for text.
+ *
+ * TODO(colin): this makes assumptions about the relative sizes of the length
+ * of a bond and the text.  Think about alternate ways to represent this that
+ * might not have that problem.
+ */
+function maybeShrinkLines(fromAtom: any, toAtom) {
+    const shrinkFactor = 0.25;
+    let fromPos = [fromAtom.pos[0], fromAtom.pos[1]];
+    let toPos = [toAtom.pos[0], toAtom.pos[1]];
+    if (fromAtom.symbol !== "C") {
+        fromPos = [
+            toAtom.pos[0] -
+                (1 - shrinkFactor) * (toAtom.pos[0] - fromAtom.pos[0]),
+            toAtom.pos[1] -
+                (1 - shrinkFactor) * (toAtom.pos[1] - fromAtom.pos[1]),
+        ];
+    }
+    if (toAtom.symbol !== "C") {
+        // For carbon atoms, conventionally we don't draw any letter, so this
+        // special cases drawing the bond lines all the way to the point where
+        // they meet.
+        toPos = [
+            fromAtom.pos[0] -
+                (1 - shrinkFactor) * (fromAtom.pos[0] - toAtom.pos[0]),
+            fromAtom.pos[1] -
+                (1 - shrinkFactor) * (fromAtom.pos[1] - toAtom.pos[1]),
+        ];
+    }
+    return [fromPos, toPos];
+}
+
+/**
+ * Compute the layout for a bond between two atoms.
+ *
+ * Args:
+ *     bond: the bond node for which the layout is being computed, as returned
+ *         by convertTree
+ *     atoms: the list of all atoms returned by convertTree, which should
+ *         already have been processed for layout and thus have positions set
+ *
+ * Return:
+ *     a rendering instruction for the bond containing a type
+ *     (line:{single,double,triple}) and the line's endpoints
+ */
+function bondLayout(bond: any, atoms: any): any {
+    const fromAtom = atoms[bond.from];
+    const toAtom = atoms[bond.to];
+    const startAndEndPos = maybeShrinkLines(fromAtom, toAtom);
+    return {
+        type: "line:" + bond.bondType,
+        startPos: startAndEndPos[0],
+        endPos: startAndEndPos[1],
+    };
+}
+
+/**
+ * Convert an array of atom indices to a single string unique identifier.
+ *
+ * For linear molecules, or for atoms in the main chain, this will just be the
+ * atom index, something like "0,1".  For branched molecules, however, we
+ * uniquely identify atoms by an array of atoms where the branching happened,
+ * followed by the index in the current branch (like ["0,1", "1,2", "1,1"]).
+ * This function just joins the parts with a colon so that we can have nice
+ * object keys that still track the series of branches to get to an atom, which
+ * is guaranteed to be a unique identifier.
+ *
+ */
+function idxString(idx) {
+    return idx.join(":");
+}
+
+/**
+ * Convert the parse tree output by the parser into an ordered list of atoms
+ * and bonds to render.
+ *
+ * Args:
+ *     atoms: the output list of atoms that we're in the process of building.
+ *         This should be the empty list if not being called recursively.
+ *     bonds: the output list of bonds that we're in the process of building.
+ *         This should be the empty list if not being called recursively.
+ *     tree: the parse tree generated by the SMILES parser module.
+ *
+ * Return:
+ *     the final value of atoms and bonds, which are lists of all the atom
+ *     nodes and bond nodes, respectively, that need to be rendered.
+ */
+function convertTree(atoms: any, bonds: any, tree: any): [any, any] {
+    if (tree === null) {
+        return [atoms, bonds];
+    }
+    if (tree.type === "atom") {
+        const treeIdx = idxString(tree.idx);
+        atoms[treeIdx] = {idx: treeIdx, symbol: tree.symbol, connections: []};
+        if (tree.bonds) {
+            tree.bonds.forEach(function (b) {
+                const toIdx = idxString(b.to.idx);
+                atoms[treeIdx].connections.push(toIdx);
+                bonds.push({from: treeIdx, to: toIdx, bondType: b.bondType});
+                convertTree(atoms, bonds, b.to);
+                atoms[toIdx].connections.push(treeIdx);
+            });
+        }
+    }
+    return [atoms, bonds];
+}
+
+/**
+ * Recursively process the queue of atoms that need to have layout computed.
+ *
+ * Args:
+ *     outputs: the array of atom rendering instructions we're in the process
+ *         of building.  This should be the empty array if not being called
+ *         recursively.
+ *     atomProcessingQueue: the array of unique identifier strings (see the
+ *         comment for idxString for more information about these) of atoms
+ *         currently in line to be processed.  When not being called
+ *         recursively, this should be a array with a single element, the
+ *         unique identifier of the first atom in the structure ("1,0" in the
+ *         current scheme).
+ *     atoms: the array of all atom nodes to be rendered, as returned by
+ *         convertTree
+ *     bonds: the array of all bond nodes to be rendered, as returned by
+ *         convertTree
+ *
+ * Return:
+ *     an array of rendering instructions for all the atoms in the molecule
+ */
+function atomLayoutHelper(
+    outputs,
+    atomProcessingQueue,
+    atoms,
+    bonds,
+    rotationAngle,
+) {
+    if (atomProcessingQueue.length === 0) {
+        return outputs;
+    }
+
+    const queuedAtomIdx = atomProcessingQueue.shift();
+    const atom = atoms[queuedAtomIdx];
+    atom.connections.forEach(function (c) {
+        if (!atoms[c].pos) {
+            atomProcessingQueue.push(c);
+        }
+    });
+    return atomLayoutHelper(
+        outputs.concat(atomLayout(atom, atoms, bonds, rotationAngle)),
+        atomProcessingQueue,
+        atoms,
+        bonds,
+        rotationAngle,
+    );
+}
+
+/**
+ * Recursively process the queue of bonds that need to have layout computed.
+ *
+ * Args:
+ *     outputs: the array of bond rendering instructions we're in the process
+ *         of building.  This should be the empty array or the array of all
+ *         atom rendering instructions if not being called recursively.
+ *     atoms: the array of all atom nodes to be rendered, as returned by
+ *         convertTree
+ *     bonds: the array of all bond nodes to be rendered, as returned by
+ *         convertTree
+ *
+ * Return:
+ *     an array of rendering instructions for all the bonds in the molecule
+ *     concatenated to the initial value of outputs
+ */
+function bondLayoutHelper(outputs: Array<any>, atoms, bonds: any) {
+    if (bonds.length === 0) {
+        return outputs;
+    }
+    return bondLayoutHelper(
+        outputs.concat(bondLayout(bonds[0], atoms)),
+        atoms,
+        bonds.slice(1),
+    );
+}
+
+/**
+ * Compute an array of rendering instructions from the parse tree of a molecule.
+ *
+ * Args:
+ *     tree: the parse tree as returned by the SMILES parser module
+ *     rotationAngle: a global rotation (in degrees) to be applied to the whole
+ *         molecule; this is manually adjustable in the widget.
+ *
+ * Return:
+ *     an array of rendering instructions for all the atoms and bonds in the
+ *     molecule suitable for processing by the renderer
+ */
+function layout(tree: any, rotationAngle: any): any {
+    const converted = convertTree({}, [], tree);
+    const atoms = converted[0];
+    const bonds = converted[1];
+    const outputs = atomLayoutHelper([], ["1,0"], atoms, bonds, rotationAngle);
+    return bondLayoutHelper(outputs, atoms, bonds);
+}
+
+export default {
+    layout: layout,
+    // The remainder are exported for testing and are not intended for external
+    // use.
+    _atomLayout: atomLayout,
+    _bondLayout: bondLayout,
+    _bondLength: bondLength,
+    _convertTree: convertTree,
+};

package/src/widgets/molecule/smiles-parser.ts

@@ -0,0 +1,296 @@
+// Regexp defining characters that are valid SMILES characters that this parser
+// can parse.  In addition to serving as a sort of validation, this also keeps
+// out unimplemented features (like cycles and stereochemistry), which use
+// additional characters.
+const smilesRe = new RegExp("^[A-Za-z\\[\\]()=#+-]*$");
+
+// Regexp defining what characters are valid as atom names.  This includes
+// common 1-character elements, Cl and Br for convenience, and the open
+// bracket, which can be used to include anything as an atom name.
+const atomRe = new RegExp("^(Cl|Br|[CONPSFBI]|\\[)");
+
+function ParseError(message: string) {
+    // @ts-expect-error [FEI-5003] - TS2683 - 'this' implicitly has type 'any' because it does not have a type annotation.
+    this.message = message;
+}
+
+/**
+ * Perform a functional update of a possibly nested object.
+ *
+ * Args:
+ *     obj: an object, will not be modified
+ *     keylist: a list of keys whose values will be updated in the object.
+ *         This represents a path to a value inside nested objects.  For
+ *         example, if keylist == ["a", "b", "c"], then a new object is
+ *         returned with obj["a"]["b"]["c"] updated.  Note that if any of the
+ *         keys is not already present, this will insert {} as a default value
+ *         for that key.
+ *     val: the new value to associate with the keypath
+ *
+ * Return: a new object, which is a shallow copy of the original with the value
+ *     at the specified keypath replaced.
+ */
+function _mset(obj, keylist, val) {
+    const k0 = keylist[0];
+    const rest = keylist.slice(1);
+    let newObj;
+    if (Array.isArray(obj)) {
+        newObj = [...obj];
+    } else {
+        newObj = {...(obj || {})};
+    }
+    let newVal = val;
+    if (rest.length > 0) {
+        newVal = _mset(newObj[k0], rest, val);
+    }
+    newObj[k0] = newVal;
+    return newObj;
+}
+
+/**
+ * Perform a functional increment of a value in a nested object.
+ *
+ * Args:
+ *     obj: an object; this will not be modified
+ *     keylist: a list of keys representing a path into a nested object.  (See
+ *         `_mset` for examples.)
+ *
+ * Return:
+ *     an object that is a shallow copy of obj, with the value at the specified
+ *     path incremeneted.
+ */
+function _inc(obj, keylist: Array<number | string>) {
+    const val = keylist.reduce(function (acc, elt) {
+        return acc[elt];
+    }, obj);
+
+    return _mset(obj, keylist, val + 1);
+}
+
+function validate(smiles) {
+    return smilesRe.test(smiles);
+}
+
+/**
+ * Parse a bond modifier character, updating the context object so that the
+ * next bond created has this modifier.
+ */
+function parseBondModifier(smiles: any, ctx) {
+    const firstChar = smiles[0];
+    const rest = smiles.slice(1);
+    if (firstChar === "=") {
+        return parse(rest, _mset(ctx, ["bond", "bondType"], "double"));
+    }
+    if (firstChar === "#") {
+        return parse(rest, _mset(ctx, ["bond", "bondType"], "triple"));
+    }
+    throw new ParseError("Invalid character: " + firstChar);
+}
+
+/**
+ * Slice the input string, removing a parenthesized expression.
+ * (Will handle nested parentheses.)
+ *
+ * parenStack should be a list containing any open parentheses already
+ * encountered.  (Usually, this will be ["("])
+ */
+function sliceFromMatchingCloseParen(smiles: any, parenStack: Array<any>) {
+    if (parenStack.length === 0) {
+        return smiles;
+    }
+
+    if (smiles === "") {
+        throw new ParseError("Mismatched parentheses");
+    }
+
+    const firstChar = smiles[0];
+    const rest = smiles.slice(1);
+
+    if (firstChar === "(") {
+        return sliceFromMatchingCloseParen(rest, parenStack.concat(firstChar));
+    }
+
+    if (firstChar === ")") {
+        return sliceFromMatchingCloseParen(rest, parenStack.slice(1));
+    }
+
+    return sliceFromMatchingCloseParen(rest, parenStack);
+}
+
+/**
+ * Parse a branch, as indicated by the presence of a parenthesized experession.
+ *
+ * This returns a list of all branches (including the continuation of the
+ * backbone) that should be added to the previous atom's bond list.
+ */
+function parseParenthesizedExpression(smiles: any, ctx: any) {
+    const firstChar = smiles[0];
+    const rest = smiles.slice(1);
+    if (firstChar === "(") {
+        let newCtx = {...ctx, parens: ctx.parens + "("};
+        // increment the branch index
+        newCtx = _inc(ctx, ["idx", ctx.idx.length - 1, 1]);
+
+        let inBranchIdx = -1;
+        if (ctx.idx[ctx.idx.length - 1][0] % 2 === 0) {
+            // HACK(colin): this is so that we preserve the odd/even series in
+            // indices in branches; the layout engine uses this to select
+            // angles, and if we don't do this, editing one part of a molecule
+            // can cause another to flop around oddly.
+            // TODO(colin): this should just start at 0 all the time, and the
+            // layout engine should figure out continuity.
+            inBranchIdx = 0;
+        }
+        const parenCtx = {
+            ...newCtx,
+            idx: newCtx.idx.concat([[inBranchIdx, 0]]),
+            parens: newCtx.parens.concat("("),
+        } as const;
+        const parenExpr = parse(rest, parenCtx);
+        const remainder = parse(
+            sliceFromMatchingCloseParen(rest, ["("]),
+            newCtx,
+        );
+        return [parenExpr].concat(remainder);
+    }
+    if (firstChar === ")") {
+        if (ctx.parens[ctx.parens.length - 1] !== "(") {
+            throw new ParseError("Mismatched parentheses");
+        }
+        return null;
+    }
+    throw new ParseError("Invalid bare character: " + firstChar);
+}
+
+/**
+ * Get the symbol of the next atom in the molecule.
+ *
+ * Return a 2-element list containing that symbol and the remainder of the
+ * molecule.
+ */
+function readAtomSymbol(smiles: any, _ctx) {
+    let sym = null;
+    let rest = null;
+    if (smiles[0] === "[") {
+        const closingIdx = smiles.indexOf("]");
+        if (closingIdx === -1) {
+            return ["", smiles];
+        }
+        sym = smiles.slice(1, closingIdx);
+        rest = smiles.slice(closingIdx + 1);
+    } else {
+        const match = atomRe.exec(smiles);
+        // @ts-expect-error [FEI-5003] - TS2322 - Type 'string' is not assignable to type 'null'. | TS2531 - Object is possibly 'null'.
+        sym = match[1];
+        // @ts-expect-error [FEI-5003] - TS2531 - Object is possibly 'null'.
+        rest = smiles.slice(sym.length);
+    }
+
+    return [sym, rest];
+}
+
+/**
+ * Parse the next atom in the molecule, returning an atom object if this is the
+ * first atom in the molecule, or a bond object with this atom as the
+ * destination of the bond if this is not the first atom.
+ */
+function parseAtom(smiles, ctx) {
+    const symbolInfo = readAtomSymbol(smiles, ctx);
+    const atom = symbolInfo[0];
+    if (atom === "") {
+        return ["error", "Unable to parse bracketed atom."];
+    }
+    const rest = symbolInfo[1];
+
+    // Atoms are indexed by a list of two-element lists.  In each two-element
+    // list, the first element is the atom counter, and the second element is
+    // the branch counter.  Branches are 1-indexed so that the main chain of
+    // the molecule can be indicated by 0.  Atoms may be either 0- or
+    // 1-indexed, defaulting to 1, to maintain a alternating pattern of
+    // odd/even indices. So, for example, if an atom has a branch off the main
+    // chain, and its atom index is x, then the indices of atoms are:
+    //     Atom where branch occurs: [[x, 0]]
+    //     First atom in the branch: [[x, 1], [1, 0]]  (assuming x is even)
+    //     Next atom in the main chain: [[x + 1, 0]]
+
+    // increment the atom counter and reset the branch counter
+    const newCtx = _mset(
+        ctx,
+        ["idx", ctx.idx.length - 1],
+        [1 + ctx.idx[ctx.idx.length - 1][0], 0],
+    );
+    let restOfMolecule = parse(
+        rest,
+        _mset(newCtx, ["bond", "bondType"], "single"),
+    );
+    if (!Array.isArray(restOfMolecule) && !!restOfMolecule) {
+        //TODO(colin): fix this awkwardness.
+        restOfMolecule = [restOfMolecule];
+    }
+    const atomObj = {
+        type: "atom",
+        symbol: atom,
+        bonds: restOfMolecule,
+        idx: newCtx.idx,
+    } as const;
+    if (ctx.bond) {
+        return {
+            type: "bond",
+            bondType: ctx.bond.bondType,
+            to: atomObj,
+        };
+    }
+    return atomObj;
+}
+
+function startsWithAtom(s: any) {
+    return atomRe.test(s);
+}
+
+function isModifierChar(s: any) {
+    return s === "=" || s === "#";
+}
+
+/**
+ * Parse a SMILES string to an internal tree representation.
+ *
+ * Args:
+ *   smiles [string]: a string representing the molecule.
+ *
+ * Returns: the parse tree (see top-of file docstring for details).
+ *
+ * Throws:
+ *     ParseError: if the input is not valid SMILES or contains features not
+ *         yet implemented.
+ */
+function parse(smiles: any, ctx: any): any {
+    if (!validate(smiles)) {
+        throw new ParseError("Invalid input.");
+    }
+
+    if (!smiles || smiles.length === 0) {
+        return null;
+    }
+
+    if (startsWithAtom(smiles)) {
+        return parseAtom(
+            smiles,
+            ctx || {
+                idx: [[0, 0]],
+                parens: [],
+                stack: [],
+                bondModifiers: [],
+            },
+        );
+    }
+    if (isModifierChar(smiles[0])) {
+        // TODO(colin): add a better error message in the case where the input
+        // is invalid and starts with a modifier character?
+        return parseBondModifier(smiles, ctx);
+    }
+    // TODO(colin): add additional cases for unimplemented bits of SMILES
+    // syntax.
+    return parseParenthesizedExpression(smiles, ctx);
+}
+
+export default {parse: parse, ParseError: ParseError};