#3525 [Feature] Expose ability to calculate fully expanded large molecule into chemical structures (#3525)

Author: sapiosciences-dev

api/c/indigo/indigo.h

@@ -639,6 +639,8 @@ CEXPORT const char* indigoGetTGroupAlias(int tgroup);
 
 CEXPORT int indigoTransformSCSRtoCTAB(int item);
 CEXPORT int indigoTransformCTABtoSCSR(int molecule, int templates);
+// [Sapio] FR-48004 Expose expandedMonomersToAtoms to Python API.
+CEXPORT int indigoExpandedMonomersToAtoms(int molecule);
 
 CEXPORT int indigoResetCharge(int atom);
 CEXPORT int indigoResetExplicitValence(int atom);
@@ -1129,6 +1131,13 @@ CEXPORT int indigoRGroupComposition(int molecule, const char* options);
  */
 CEXPORT int indigoExpandAbbreviations(int molecule);
 
+/*
+ * Group pseudoatoms (OH, NH2, etc.): expand to explicit atoms for V3000/molfile
+ * interoperability. Call after expandedMonomersToAtoms(). See
+ * indigo_group_pseudoatoms_expand.h for the list of labels.
+ */
+CEXPORT int indigoExpandGroupPseudoatoms(int molecule);
+
 /* Other */
 
 CEXPORT const char* indigoToString(int handle);

api/c/indigo/src/indigo_abbreviations_expand.cpp

@@ -17,8 +17,10 @@
  ***************************************************************************/
 
 #include "indigo_abbreviations.h"
+#include "indigo_group_pseudoatoms_expand.h"
 
 #include "base_c/bitarray.h"
+#include "base_cpp/array.h"
 #include "base_cpp/scanner.h"
 #include "molecule/elements.h"
 #include "molecule/molecule.h"
@@ -32,6 +34,7 @@
 #include "layout/molecule_layout.h"
 
 #include <algorithm>
+#include <cstring>
 
 namespace indigo
 {
@@ -850,4 +853,115 @@ namespace indigo
         }
 
     } // namespace abbreviations
+
+    static bool isGroupPseudoatomLabel(const char* alias)
+    {
+        for (const char* const* p = GROUP_PSEUDOATOM_EXPAND_LABELS; *p != nullptr; ++p)
+        {
+            if (strcmp(alias, *p) == 0)
+                return true;
+        }
+        return false;
+    }
+
+    static bool buildGroupFragment(const char* label, Molecule& fragment, int& attachment_idx)
+    {
+        fragment.clear();
+        attachment_idx = 0;
+
+        if (strcmp(label, "OH") == 0)
+        {
+            int o = fragment.addAtom(ELEM_O);
+            int h = fragment.addAtom(ELEM_H);
+            fragment.addBond(o, h, BOND_SINGLE);
+            fragment.setAtomXyz(o, 0, 0, 0);
+            fragment.setAtomXyz(h, 1, 0, 0);
+            attachment_idx = 0;
+            return true;
+        }
+        if (strcmp(label, "NH2") == 0)
+        {
+            int n = fragment.addAtom(ELEM_N);
+            int h1 = fragment.addAtom(ELEM_H);
+            int h2 = fragment.addAtom(ELEM_H);
+            fragment.addBond(n, h1, BOND_SINGLE);
+            fragment.addBond(n, h2, BOND_SINGLE);
+            fragment.setAtomXyz(n, 0, 0, 0);
+            fragment.setAtomXyz(h1, 1, 0, 0);
+            fragment.setAtomXyz(h2, -0.5f, 0.866f, 0);
+            attachment_idx = 0;
+            return true;
+        }
+        return false;
+    }
+
+    int expandGroupPseudoatomsInMolecule(Molecule& mol)
+    {
+        int count = 0;
+        QS_DEF(Array<int>, pseudoatoms);
+        pseudoatoms.clear();
+        for (int v = mol.vertexBegin(); v != mol.vertexEnd(); v = mol.vertexNext(v))
+        {
+            if (mol.isPseudoAtom(v) && isGroupPseudoatomLabel(mol.getPseudoAtom(v)))
+                pseudoatoms.push(v);
+        }
+        if (pseudoatoms.size() == 0)
+            return 0;
+
+        std::sort(pseudoatoms.ptr(), pseudoatoms.ptr() + pseudoatoms.size(), std::greater<int>());
+
+        for (int i = 0; i < pseudoatoms.size(); i++)
+        {
+            // Step 1 Build fragment
+            int v = pseudoatoms[i];
+            const char* alias = mol.getPseudoAtom(v);
+            Molecule fragment;
+            int attachment_idx = -1;
+            if (!buildGroupFragment(alias, fragment, attachment_idx))
+                continue;
+
+            Vec3f pos = mol.getAtomXyz(v);
+            const Vertex& vertex = mol.getVertex(v);
+
+            // Step 2 merge fragment into the main structure. Now we have a
+            // forest of atoms, disconnected.
+            QS_DEF(Array<int>, mapping);
+            mol.mergeWithMolecule(fragment, &mapping);
+            int ap_new = mapping[attachment_idx];
+
+            // Step 3 connect fragment to the main structure.
+
+            for (int k = vertex.neiBegin(); k != vertex.neiEnd(); k = vertex.neiNext(k))
+            {
+                int nei = vertex.neiVertex(k);
+                int edge_idx = mol.findEdgeIndex(v, nei);
+                int order = mol.getBondOrder(edge_idx);
+                mol.addBond_Silent(nei, ap_new, order);
+            }
+
+            for (int a = 0; a < fragment.vertexCount(); a++)
+            {
+                int mapped = mapping[a];
+                mol.setAtomXyz(mapped, pos.x, pos.y, pos.z);
+            }
+
+            mol.removeAtom(v);
+            count++;
+        }
+        return count;
+    }
+
 } // namespace indigo
+
+CEXPORT int indigoExpandGroupPseudoatoms(int molecule)
+{
+    INDIGO_BEGIN
+    {
+        IndigoObject& obj = self.getObject(molecule);
+        if (obj.type != IndigoObject::MOLECULE)
+            throw IndigoError("indigoExpandGroupPseudoatoms(): expected molecule, got %s", obj.debugInfo());
+        Molecule& mol = obj.getMolecule();
+        return expandGroupPseudoatomsInMolecule(mol);
+    }
+    INDIGO_END(-1);
+}

api/c/indigo/src/indigo_group_pseudoatoms_expand.h

@@ -0,0 +1,63 @@
+/****************************************************************************
+ * Copyright (C) from 2009 to Present EPAM Systems.
+ *
+ * This file is part of Indigo toolkit.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ ***************************************************************************/
+
+#ifndef __indigo_group_pseudoatoms_expand_h__
+#define __indigo_group_pseudoatoms_expand_h__
+
+#include "molecule/molecule.h"
+
+namespace indigo
+{
+
+    /**
+     * Table of group pseudoatom labels that are expanded for V3000/molfile
+     * interoperability and for proper computation of properties within Indigo
+     * (e.g. molecular weight; Indigo cannot compute mass for structures that
+     * contain pseudoatoms). These labels (e.g. "OH", "NH2") appear as atom
+     * labels in the default monomer library of Ketcher.
+     * They are not valid single-atom symbols in MOL/V3000; toolkits like RDKit
+     * expect element symbols only. Expanding them to explicit atoms (O+H,
+     * N+H+H) allows the molfile to be read by strict parsers and enables
+     * property calculations.
+     *
+     * This table is the single source of truth: add new labels here as they are
+     * encountered in monomer libraries (e.g. Ketcher's default library). Do not
+     * duplicate this list elsewhere.
+     */
+    static const char* const GROUP_PSEUDOATOM_EXPAND_LABELS[] = {"OH", "NH2", nullptr};
+
+    /**
+     * Expands group pseudoatoms (see GROUP_PSEUDOATOM_EXPAND_LABELS) in the
+     * given molecule into explicit atoms and bonds, in place. These pseudoatoms
+     * are handled because they are defined in Ketcher's default monomer library.
+     * Expansion is needed both for proper computation of properties in Indigo
+     * (e.g. molecular weight, which is not defined for pseudoatoms) and for
+     * V3000/molfile interoperability with downstream toolkits (e.g. RDKit).
+     * Used after expandedMonomersToAtoms() so that the result is valid for
+     * export and for property calculations. Distinct from
+     * indigoExpandAbbreviations(), which expands SMILES-style abbreviations (Me,
+     * Et, Ph, etc.) from abbreviations.xml.
+     *
+     * @param mol Molecule to modify (must be Molecule, not QueryMolecule).
+     * @return Number of group pseudoatoms expanded.
+     */
+    int expandGroupPseudoatomsInMolecule(Molecule& mol);
+
+} // namespace indigo
+
+#endif

api/c/indigo/src/indigo_molecule.cpp

@@ -21,6 +21,7 @@
 #include "base_cpp/output.h"
 #include "base_cpp/scanner.h"
 #include "indigo_array.h"
+#include "indigo_group_pseudoatoms_expand.h"
 #include "indigo_io.h"
 #include "indigo_ket_document.h"
 #include "indigo_mapping.h"

api/c/indigo/src/indigo_molecule_operations.cpp

@@ -20,6 +20,7 @@
 #include "base_cpp/output.h"
 #include "base_cpp/scanner.h"
 #include "indigo_array.h"
+#include "indigo_group_pseudoatoms_expand.h"
 #include "indigo_io.h"
 #include "indigo_ket_document.h"
 #include "indigo_mapping.h"
@@ -3168,3 +3169,67 @@ CEXPORT int indigoExpandMonomers(int item)
     }
     INDIGO_END(0);
 }
+
+// [Sapio] FR-48004 Expose expandedMonomersToAtoms to Python API.
+// This function fully expands all template atoms (monomers) in a macromolecule to regular atoms.
+// It creates a working copy of the molecule to avoid side effects, marks all template atoms as
+// expanded, then calls the internal expandedMonomersToAtoms() method to perform the actual
+// expansion. The result is a new molecule with all monomers fully expanded to their atomic
+// structures, suitable for molecular weight calculations and compatibility with third-party tools.
+CEXPORT int indigoExpandedMonomersToAtoms(int molecule)
+{
+    INDIGO_BEGIN
+    {
+        BaseMolecule& mol = self.getObject(molecule).getBaseMolecule();
+
+        // Create a working copy to avoid side effects on the original molecule
+        std::unique_ptr<IndigoMolecule> work_mol = std::make_unique<IndigoMolecule>();
+        QS_DEF(Array<int>, work_mapping);
+        work_mol->mol.clone(mol, 0, &work_mapping);
+
+        // Set display options on template atoms in the working copy
+        // This marks them as expanded so expandedMonomersToAtoms() will process them.
+        // We validate each template atom's occurrence index before accessing to detect
+        // data corruption issues early.
+        for (int v_idx = work_mol->mol.vertexBegin(); v_idx != work_mol->mol.vertexEnd(); v_idx = work_mol->mol.vertexNext(v_idx))
+        {
+            if (!work_mol->mol.isTemplateAtom(v_idx))
+                continue;
+
+            // Get the template occurrence index - this should not throw since we checked isTemplateAtom()
+            int template_occur_idx = work_mol->mol.getTemplateAtomOccurrence(v_idx);
+
+            // Validate that the occurrence index is valid in the pool
+            // If invalid, this indicates data corruption and we should fail rather than silently skip
+            if (!work_mol->mol.isValidTemplateOccurrence(template_occur_idx))
+            {
+                throw IndigoError("expandedMonomersToAtoms: template atom #%d has invalid occurrence index %d (data corruption detected)", v_idx,
+                                  template_occur_idx);
+            }
+
+            // Mark this template atom as expanded
+            work_mol->mol.setTemplateAtomDisplayOption(v_idx, DisplayOption::Expanded);
+        }
+
+        // Call expandedMonomersToAtoms on the working copy
+        // This method clones internally and returns a molecule with all expanded monomers
+        // converted to regular atoms.
+        std::unique_ptr<BaseMolecule> expanded = work_mol->mol.expandedMonomersToAtoms();
+
+        // Create new IndigoMolecule for the final result
+        std::unique_ptr<IndigoMolecule> new_mol = std::make_unique<IndigoMolecule>();
+        QS_DEF(Array<int>, mapping);
+        new_mol->mol.clone(*expanded, 0, &mapping);
+
+        // Expand group pseudoatoms (OH, NH2, etc.) to explicit atoms for V3000 interoperability
+        expandGroupPseudoatomsInMolecule(new_mol->mol);
+
+        // Copy properties from original molecule
+        auto& props = self.getObject(molecule).getProperties();
+        new_mol->copyProperties(props);
+
+        // Add to session and return ID
+        return self.addObject(new_mol.release());
+    }
+    INDIGO_END(-1);
+}

api/cpp/src/IndigoBaseMolecule.cpp

@@ -17,6 +17,7 @@
  ***************************************************************************/
 
 #include "IndigoBaseMolecule.h"
+#include "IndigoMolecule.h"
 #include "IndigoSession.h"
 
 #include <indigo.h>
@@ -47,3 +48,9 @@ IndigoAtom IndigoBaseMolecule::getAtom(int atomIndex) const
     session()->setSessionId();
     return IndigoAtom(session()->_checkResult(indigoGetAtom(id(), atomIndex)), session());
 }
+
+IndigoMolecule IndigoBaseMolecule::expandedMonomersToAtoms() const
+{
+    session()->setSessionId();
+    return IndigoMolecule(session()->_checkResult(indigoExpandedMonomersToAtoms(id())), session());
+}

api/cpp/src/IndigoBaseMolecule.h

@@ -23,6 +23,8 @@
 
 namespace indigo_cpp
 {
+    class IndigoMolecule;
+
     class IndigoBaseMolecule : public IndigoChemicalStructure
     {
     protected:
@@ -38,5 +40,8 @@ namespace indigo_cpp
         std::string ctfile() const override;
 
         IndigoAtom getAtom(int atomIndex) const;
+
+        /** Converts expanded template atoms (monomers) to regular atoms. Returns a new molecule. */
+        IndigoMolecule expandedMonomersToAtoms() const;
     };
 }

api/dotnet/src/IndigoLib.cs

@@ -1,4 +1,4 @@
-using System.Runtime.InteropServices;
+using System.Runtime.InteropServices;
 using System.Security;
 
 namespace com.epam.indigo
@@ -1335,6 +1335,12 @@ public static extern int indigoSetSGroupBrackets(int sgroup, int brk_style, floa
         [DllImport("indigo"), SuppressUnmanagedCodeSecurity]
         public static extern int indigoExpandAbbreviations(int structure);
 
+        [DllImport("indigo"), SuppressUnmanagedCodeSecurity]
+        public static extern int indigoExpandGroupPseudoatoms(int molecule);
+
+        [DllImport("indigo"), SuppressUnmanagedCodeSecurity]
+        public static extern int indigoExpandedMonomersToAtoms(int molecule);
+
         [DllImport("indigo"), SuppressUnmanagedCodeSecurity]
         public static extern int indigoIterateTautomers(int structure, string parameters);
 

api/dotnet/src/IndigoObject.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections;
 
 namespace com.epam.indigo
@@ -2320,6 +2320,16 @@ public int expandAbbreviations()
             return dispatcher.checkResult(IndigoLib.indigoExpandAbbreviations(self));
         }
 
+        /// <summary>
+        /// Converts expanded template atoms (monomers) to regular atoms.
+        /// Returns a new molecule; the original is not modified.
+        /// </summary>
+        public IndigoObject expandedMonomersToAtoms()
+        {
+            dispatcher.setSessionID();
+            return new IndigoObject(dispatcher, dispatcher.checkResult(IndigoLib.indigoExpandedMonomersToAtoms(self)));
+        }
+
         public int nameToStructure(string name, string parameters)
         {
             dispatcher.setSessionID();

api/java/indigo/src/main/java/com/epam/indigo/IndigoLib.java

@@ -956,6 +956,10 @@ int indigoCreateEdgeSubmolecule(
 
     int indigoExpandAbbreviations(int structure);
 
+    int indigoExpandGroupPseudoatoms(int molecule);
+
+    int indigoExpandedMonomersToAtoms(int molecule);
+
     int indigoIterateTautomers(int structure, String params);
 
     int indigoNameToStructure(String name, String params);