FragmentSpace.java

Go to the documentation of this file.

/*
 *   DENOPTIM
 *   Copyright (C) 2019 Vishwesh Venkatraman <vishwesh.venkatraman@ntnu.no> and
 *   Marco Foscato <marco.foscato@uib.no>
 * 
 *   This program is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU Affero General Public License as published
 *   by the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU Affero General Public License for more details.
 *
 *   You should have received a copy of the GNU Affero General Public License
 *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
package denoptim.fragspace;
 
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.logging.Level;
 
import javax.vecmath.Point3d;
 
import org.openscience.cdk.Atom;
import org.openscience.cdk.PseudoAtom;
import org.openscience.cdk.interfaces.IAtomContainer;
 
import denoptim.constants.DENOPTIMConstants;
import denoptim.exception.DENOPTIMException;
import denoptim.files.UndetectedFileFormatException;
import denoptim.graph.APClass;
import denoptim.graph.APMapping;
import denoptim.graph.AttachmentPoint;
import denoptim.graph.Candidate;
import denoptim.graph.DGraph;
import denoptim.graph.Fragment;
import denoptim.graph.GraphPattern;
import denoptim.graph.Template;
import denoptim.graph.Vertex;
import denoptim.graph.Vertex.BBType;
import denoptim.graph.rings.RingClosingAttractor;
import denoptim.io.DenoptimIO;
import denoptim.utils.GraphUtils;
import denoptim.utils.MoleculeUtils;
import denoptim.utils.Randomizer;
 
public class FragmentSpace
{
    private ArrayList<Vertex> scaffoldLib = null;
 
    private ArrayList<Vertex> fragmentLib = null;
 
    private ArrayList<Vertex> cappingLib = null;
 
    private HashMap<APClass, ArrayList<APClass>> apClassCompatibilityMatrix;
 
    private ArrayList<Vertex> rcvs = new ArrayList<Vertex>();
    
    private HashMap<APClass, ArrayList<APClass>> rcCompatMap;
 
    private HashMap<APClass, APClass> cappingMap;
    
    private Set<APClass> forbiddenEndList;
 
    private HashMap<Integer, ArrayList<Integer>> fragPoolPerNumAP = 
            new HashMap<Integer,ArrayList<Integer>>();
 
    private HashMap<Integer, ArrayList<APClass>> apClassesPerFrag =
            new HashMap<Integer,ArrayList<APClass>>();
 
    private HashMap<APClass, ArrayList<ArrayList<Integer>>> fragsApsPerApClass =
            new HashMap<APClass,ArrayList<ArrayList<Integer>>>();
    
    private final Object LOCK = new Object();
    
    private HashMap<APClass, Double> symmConstraints;
 
    private boolean apClassBasedApproch = false;
 
    private boolean isValid = false;
 
    private FragmentSpaceParameters settings = null;
 
//------------------------------------------------------------------------------
    
    public FragmentSpace()
    {
        fragmentLib = new ArrayList<Vertex>();
        scaffoldLib = new ArrayList<Vertex>();
        cappingLib = new ArrayList<Vertex>();
        settings = new FragmentSpaceParameters(this);
    }
    
//------------------------------------------------------------------------------
 
    public FragmentSpace(FragmentSpaceParameters settings, String scaffFile, 
            String fragFile, String capFile, String cpmFile) 
                    throws DENOPTIMException
    {
        this(settings, scaffFile, fragFile, capFile, cpmFile, "", 
                new HashMap<APClass, Double>());
    }
    
//------------------------------------------------------------------------------
 
    public FragmentSpace(FragmentSpaceParameters settings,
            ArrayList<Vertex> scaffLib,
            ArrayList<Vertex> fragLib,
            ArrayList<Vertex> cappLib,
            HashMap<APClass, ArrayList<APClass>> cpMap,
            HashMap<APClass, APClass> capMap,
            HashSet<APClass> forbEnds,
            HashMap<APClass, ArrayList<APClass>> rcCpMap)
            throws DENOPTIMException
    {
        define(settings, scaffLib, fragLib, cappLib, cpMap, capMap, forbEnds, 
                rcCpMap, null);
    }
 
//------------------------------------------------------------------------------
 
    public FragmentSpace(FragmentSpaceParameters settings,
            ArrayList<Vertex> scaffLib,
            ArrayList<Vertex> fragLib,
            ArrayList<Vertex> cappLib,
            HashMap<APClass, ArrayList<APClass>> cpMap,
            HashMap<APClass, APClass> capMap,
            HashSet<APClass> forbEnds,
            HashMap<APClass, ArrayList<APClass>> rcCpMap,
            HashMap<APClass, Double> symCntrMap)
            throws DENOPTIMException
    {
        define(settings, scaffLib, fragLib, cappLib, cpMap, capMap, forbEnds, 
                rcCpMap, symCntrMap);
    }
 
//------------------------------------------------------------------------------
 
    public FragmentSpace(FragmentSpaceParameters settings, String scaffFile, 
            String fragFile, String capFile, String cpmFile, String rcpmFile,
            HashMap<APClass, Double> symCntrMap) throws DENOPTIMException
    {   
        HashMap<APClass, ArrayList<APClass>> cpMap = 
                new HashMap<APClass, ArrayList<APClass>>();
        HashMap<APClass, APClass> capMap = new HashMap<APClass, APClass>();
        HashSet<APClass> forbEnds = new HashSet<APClass>();
        if (cpmFile.length() > 0)
        {
            DenoptimIO.readCompatibilityMatrix(cpmFile, cpMap, capMap,
                    forbEnds);
        }
 
        HashMap<APClass, ArrayList<APClass>> rcCpMap = 
                new HashMap<APClass, ArrayList<APClass>>();
        if (rcpmFile != null && rcpmFile.length() > 0)
        {
            DenoptimIO.readRCCompatibilityMatrix(rcpmFile, rcCpMap);
        }
        
        ArrayList<Vertex> cappLib = new ArrayList<Vertex>();
        if (capFile.length() > 0)
        {
            try
            {
                cappLib = DenoptimIO.readVertexes(new File(capFile),
                        BBType.CAP);
                for (int i=0; i<cappLib.size(); i++)
                {
                    cappLib.get(i).setBuildingBlockId(i);
                }
            } catch (IllegalArgumentException | UndetectedFileFormatException
                    | IOException | DENOPTIMException e)
            {
                throw new DENOPTIMException("Cound not read library of capping "
                        + "groups from file '" + capFile + "'.", e);
            }
        }
        
        ArrayList<Vertex> fragLib = new ArrayList<Vertex>();
        if (fragFile != null && fragFile.length() > 0)
        {
            try
            {
                fragLib = DenoptimIO.readVertexes(new File(fragFile),
                        BBType.FRAGMENT);
                for (int i=0; i<fragLib.size(); i++)
                {
                    fragLib.get(i).setBuildingBlockId(i);
                }
            } catch (IllegalArgumentException | UndetectedFileFormatException
                    | IOException | DENOPTIMException e)
            {
                throw new DENOPTIMException("Cound not read library of fragments "
                        + "from file '" + fragFile + "'.", e);
            }
        }
        
        ArrayList<Vertex> scaffLib = new ArrayList<Vertex>();
        if (scaffFile != null && scaffFile.length() > 0)
        {
            try
            {
                scaffLib = DenoptimIO.readVertexes(new File(scaffFile),
                        BBType.SCAFFOLD);
                for (int i=0; i<scaffLib.size(); i++)
                {
                    scaffLib.get(i).setBuildingBlockId(i);
                }
            } catch (IllegalArgumentException | UndetectedFileFormatException
                    | IOException | DENOPTIMException e)
            {
                throw new DENOPTIMException("Cound not read library of scaffolds "
                        + "from file '" + fragFile + "'.", e);
            }
        }
 
        define(settings, scaffLib, fragLib, cappLib, cpMap, capMap, forbEnds, 
                rcCpMap, symCntrMap);
    }
    
//------------------------------------------------------------------------------
 
    private void define(FragmentSpaceParameters settings,
            ArrayList<Vertex> scaffLib,
            ArrayList<Vertex> fragLib,
            ArrayList<Vertex> cappLib,
            HashMap<APClass, ArrayList<APClass>> cpMap,
            HashMap<APClass, APClass> capMap,
            HashSet<APClass> forbEnds,
            HashMap<APClass, ArrayList<APClass>> rcCpMap,
            HashMap<APClass, Double> symCntrMap)
            throws DENOPTIMException
    {
        this.settings = settings;
        settings.setFragmentSpace(this);
        
        setScaffoldLibrary(scaffLib);
        setFragmentLibrary(fragLib);
        setCappingLibrary(cappLib);
        setCompatibilityMatrix(cpMap);
        apClassBasedApproch = (cpMap!=null && cpMap.size()>0)
                || (rcCpMap!=null && rcCpMap.size()>0);
        setCappingMap(capMap);
        setForbiddenEndList(forbEnds);
        setRCCompatibilityMatrix(rcCpMap);
        setSymmConstraints(symCntrMap);
 
        groupAndClassifyFragments(apClassBasedApproch);
 
        isValid = true;
    }
 
//------------------------------------------------------------------------------
 
    public boolean isDefined()
    {
        return isValid;
    }
    
//------------------------------------------------------------------------------
    
    public Randomizer getRandomizer()
    {
        return settings.getRandomizer();
    }
 
//------------------------------------------------------------------------------
    
    public void setAPclassBasedApproach(boolean useAPC)
    {
        apClassBasedApproch = useAPC;
    }
    
//------------------------------------------------------------------------------
 
    public boolean useAPclassBasedApproach()
    {
        return apClassBasedApproch;
    }
 
//------------------------------------------------------------------------------
 
    public APClass getAPClassForFragment(IdFragmentAndAP apId)
    {
        APClass cls = null;
        try
        {
            Vertex frg = this.getVertexFromLibrary(
                    apId.getVertexMolType(), apId.getVertexMolId());
            cls = frg.getAttachmentPoints().get(apId.getApId()).getAPClass();
        } catch (Throwable t)
        {
            cls = null;
        }
 
        return cls;
    }
 
//------------------------------------------------------------------------------
 
    public Vertex getVertexFromLibrary(Vertex.BBType bbType, int bbIdx) 
            throws DENOPTIMException
    {
        String msg = "";
        switch (bbType)
        {
            case SCAFFOLD:
                if (scaffoldLib == null)
                {
                    msg = "Cannot retrieve scaffolds before initialising the "
                            + "scaffold library.";
                    throw new DENOPTIMException(msg);
                }
                break;
            case FRAGMENT:
                if (fragmentLib == null)
                {
                    msg = "Cannot retrieve fragments before initialising the "
                            + "fragment library.";
                    throw new DENOPTIMException(msg);
                }
                break;
            case CAP:
                if (cappingLib == null)
                {
                    msg = "Cannot retrieve capping groups before initialising"
                            + "the library of capping groups.";
                    throw new DENOPTIMException(msg);
                }
                break;
                
            default:
                throw new DENOPTIMException("Cannot find building block of "
                        + "type '" + bbType + "' in the fragment space.");
        }
 
        Vertex originalVrtx = null;
        switch (bbType)
        {
            case SCAFFOLD:
                if (bbIdx >-1 && bbIdx < scaffoldLib.size())
                {
                    originalVrtx = scaffoldLib.get(bbIdx);        
                }
                else
                {
                    msg = "Mismatch between scaffold bbIdx (" + bbIdx 
                            + ") and size of the library (" + scaffoldLib.size()
                            + "). FragType: " + bbType;
                    settings.getLogger().log(Level.SEVERE, msg);
                    throw new DENOPTIMException(msg);
                }
                break;
                
            case FRAGMENT:
                if (bbIdx >-1 && bbIdx < fragmentLib.size())
                {
                    originalVrtx = fragmentLib.get(bbIdx);
                }
                else
                {
                    msg = "Mismatch between fragment bbIdx (" + bbIdx 
                            + ") and size of the library (" + fragmentLib.size()
                            + "). FragType: " + bbType;
                    settings.getLogger().log(Level.SEVERE, msg);
                    throw new DENOPTIMException(msg);
                }
                break;
                
            case CAP:
                if (bbIdx >-1 && bbIdx < cappingLib.size())
                {
                    originalVrtx = cappingLib.get(bbIdx);
                }
                else
                {
                    msg = "Mismatch between capping group bbIdx " + bbIdx 
                            + ") and size of the library (" + cappingLib.size()
                            + "). FragType: " + bbType;
                    settings.getLogger().log(Level.SEVERE, msg);
                    throw new DENOPTIMException(msg);
                }
                break;
                
            case UNDEFINED:
                msg = "Attempting to take UNDEFINED type of building block from "
                        + "fragment library.";
                settings.getLogger().log(Level.WARNING, msg);
                if (bbIdx < fragmentLib.size())
                {
                    originalVrtx = fragmentLib.get(bbIdx);
                }
                else
                {
                    msg = "Mismatch between fragment bbIdx (" + bbIdx 
                            + ") and size of the library (" + fragmentLib.size()
                            + "). FragType: " + bbType;
                    settings.getLogger().log(Level.SEVERE, msg);
                    throw new DENOPTIMException(msg);
                }
                break;
    
            default:
                msg = "Unknown type of fragment '" + bbType + "'.";
                settings.getLogger().log(Level.SEVERE, msg);
                throw new DENOPTIMException(msg);
        }
        Vertex clone = originalVrtx.clone();
        
        clone.setVertexId(GraphUtils.getUniqueVertexIndex());
 
        clone.setBuildingBlockId(bbIdx);
        if (originalVrtx.getBuildingBlockId() != bbIdx)
        {
            settings.getLogger().log(Level.WARNING, "Mismatch between building "
                    + "block ID ("
                    + originalVrtx.getBuildingBlockId() + ") and position in "
                    + "the list of building blocks (" + bbIdx + ") for type "
                    + bbType + ".");
        }
        return clone;
    }
    
//------------------------------------------------------------------------------
 
    public int getCappingFragment(APClass rcnCap)
    {
        if (rcnCap == null)
            return -1;
 
        ArrayList<Integer> reacFrags = getCompatibleCappingFragments(rcnCap);
 
        int fapidx = -1;
        if (reacFrags.size() > 0)
        {
            fapidx = settings.getRandomizer().randomlyChooseOne(reacFrags);
        }
 
        return fapidx;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<Integer> getCompatibleCappingFragments(
            APClass cmpReac)
    {
        ArrayList<Integer> lstFragIdx = new ArrayList<>();
        for (int i=0; i<cappingLib.size(); i++)
        {
                Vertex mol = getCappingLibrary().get(i);
            ArrayList<APClass> lstRcn = mol.getAllAPClasses();
            if (lstRcn.contains(cmpReac))
                lstFragIdx.add(i);
        }
        return lstFragIdx;
    }
    
//------------------------------------------------------------------------------
 
    public Vertex makeRandomScaffold()
    {
        int chosenIdx = settings.getRandomizer().nextInt(scaffoldLib.size());
        Vertex scaffold = null;
        try
        {
            scaffold = Vertex.newVertexFromLibrary(
                    GraphUtils.getUniqueVertexIndex(),chosenIdx, 
                    BBType.SCAFFOLD, this);
        } catch (DENOPTIMException e)
        {
            //This cannot happen!
        }
        return scaffold;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<Vertex> getScaffoldLibrary()
    {
        return scaffoldLib;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<Vertex> getFragmentLibrary()
    {
        return fragmentLib;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<Vertex> getCappingLibrary()
    {
        return cappingLib;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<Integer> getCappingGroupsWithAPClass(APClass capApCls)
    {
        ArrayList<Integer> selected = new ArrayList<>();
        for (int i = 0; i < cappingLib.size(); i++)
        {
            APClass apc = cappingLib.get(i).getAP(0).getAPClass();
            if (apc.equals(capApCls))
            {
                selected.add(i);
            }
        }
        return selected;
    }
    
//------------------------------------------------------------------------------
 
    public Vertex getCappingVertexWithAPClass(APClass capApCls)
    {
        for (int i = 0; i < cappingLib.size(); i++)
        {
            APClass apc = cappingLib.get(i).getAP(0).getAPClass();
            if (apc.equals(capApCls))
            {
                try
                {
                    return getVertexFromLibrary(Vertex.BBType.CAP, i);
                } catch (DENOPTIMException e)
                {
                    //This cannot happen
                }
            }
        }
        return null;
    }
 
//------------------------------------------------------------------------------
 
    public void importCompatibilityMatrixFromFile(String inFile)
            throws DENOPTIMException
    {
        setCompatibilityMatrix(new HashMap<APClass, ArrayList<APClass>>());
        setCappingMap(new HashMap<APClass, APClass>());
        setForbiddenEndList(new HashSet<APClass>());
        DenoptimIO.readCompatibilityMatrix(inFile, apClassCompatibilityMatrix,
                cappingMap, forbiddenEndList);
    }
 
//------------------------------------------------------------------------------
 
    public void importRCCompatibilityMatrixFromFile(String inFile)
            throws DENOPTIMException
    {
        setRCCompatibilityMatrix(new HashMap<APClass, ArrayList<APClass>>());
        DenoptimIO.readRCCompatibilityMatrix(inFile, rcCompatMap);
    }
 
//------------------------------------------------------------------------------
 
    public HashMap<APClass, ArrayList<APClass>> getCompatibilityMatrix()
    {
        return apClassCompatibilityMatrix;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<APClass> getCompatibleAPClasses(APClass apc)
    {   
        if (apClassCompatibilityMatrix!= null && apClassCompatibilityMatrix.containsKey(apc))
        {
            return apClassCompatibilityMatrix.get(apc);
        }
        return new ArrayList<APClass>();
    }
 
//------------------------------------------------------------------------------
 
    public HashMap<APClass, ArrayList<APClass>> getRCCompatibilityMatrix()
    {
        return rcCompatMap;
    }
 
//------------------------------------------------------------------------------
 
    public HashMap<APClass, APClass> getCappingMap()
    {
        return cappingMap;
    }
 
//------------------------------------------------------------------------------
 
    public APClass getAPClassOfCappingVertex(APClass srcApClass)
    {
        return cappingMap.get(srcApClass);
    }
 
//------------------------------------------------------------------------------
 
    public Set<APClass> getForbiddenEndList()
    {
        return forbiddenEndList;
    }
 
//------------------------------------------------------------------------------
 
    public Set<APClass> getAllAPClassesFromCPMap()
    {
        return apClassCompatibilityMatrix.keySet();
    }
 
//------------------------------------------------------------------------------
 
    public HashMap<Integer, ArrayList<Integer>> getMapOfFragsPerNumAps()
    {
        return fragPoolPerNumAP;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<Integer> getFragsWithNumAps(int nAps)
    {
        ArrayList<Integer> lst = new ArrayList<>();
        if (fragPoolPerNumAP.containsKey(nAps))
        {
            lst = fragPoolPerNumAP.get(nAps);
        }
        return lst;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<APClass> getAPClassesPerFragment(int fragId)
    {
        synchronized (LOCK)
        {
            return apClassesPerFrag.get(fragId);
        }
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<IdFragmentAndAP> getFragsWithAPClass(APClass apc)
    {
        ArrayList<IdFragmentAndAP> lst = new ArrayList<IdFragmentAndAP>();
 
        synchronized (LOCK)
        {
            if (fragsApsPerApClass.containsKey(apc))
            {
                for (ArrayList<Integer> idxs : fragsApsPerApClass.get(apc))
                {
                    IdFragmentAndAP apId = new IdFragmentAndAP(-1, // vertexId
                            idxs.get(0), // MolId,
                            BBType.FRAGMENT, idxs.get(1), // ApId
                            -1, // noVSym
                            -1);// noAPSym
                    lst.add(apId);
                }
            }
        }
        return lst;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<Vertex> getVerticesWithAPClass(APClass apc)
    {
        ArrayList<Vertex> lst = new ArrayList<Vertex>();
        
        synchronized (LOCK)
        {
            if (fragsApsPerApClass.containsKey(apc))
            {
                for (List<Integer> idxs : fragsApsPerApClass.get(apc))
                {
                    Vertex v = fragmentLib.get(idxs.get(0));
                    lst.add(v);
                }
            }
        }
        return lst;
    }
    
//------------------------------------------------------------------------------
 
    public List<Vertex> getVerticesWithAPClasses(Set<APClass> apcs)
    {
        List<Vertex> lst = new ArrayList<Vertex>();
        
        synchronized (LOCK)
        {
            for (APClass apc : apcs)
            {
                if (!fragsApsPerApClass.containsKey(apc))
                {
                    break;
                }
                
                // NB: the list is over APs, so there can be duplicate vertexes
                for (List<Integer> idxs : fragsApsPerApClass.get(apc))
                {
                    Vertex v = fragmentLib.get(idxs.get(0));
                    if (!lst.contains(v) && v.getAllAPClasses().containsAll(apcs))
                        lst.add(v);
                }
                
                // NB: we mean to do only one loop
                break;
            }
        }
        return lst;
    }
    
//------------------------------------------------------------------------------
 
    public List<Vertex> getVerticesWithAPFingerprint(
            Map<APClass,Integer> apcCounts)
    {
        List<Vertex> matches = new ArrayList<Vertex>();
        for (Vertex candidate : getVerticesWithAPClasses(apcCounts.keySet()))
        {
            boolean isMatch = true;
            for (APClass apc : apcCounts.keySet())
            {
                if (apcCounts.get(apc) > 
                        candidate.getAttachmentPoints().stream().filter(
                                ap -> ap.getAPClass().equals(apc)).count())
                {
                    isMatch = false;
                    break;
                }
            }
            if (isMatch)
                matches.add(candidate);
        }
        return matches;
    }
    
//------------------------------------------------------------------------------
    
    public List<Vertex> getVerticesWithAPClassStartingWith(String root)
    {
        List<Vertex> lst = new ArrayList<Vertex>();
        synchronized (LOCK)
        {
            for (APClass apc : fragsApsPerApClass.keySet())
            {
                if (!apc.toString().startsWith(root))
                    continue;
                for (List<Integer> idxs : fragsApsPerApClass.get(apc))
                {
                    Vertex v = fragmentLib.get(idxs.get(0));
                    if (!lst.contains(v))
                        lst.add(v);
                }
            }
        }
        return lst;
    }
    
//------------------------------------------------------------------------------
    
    public ArrayList<Vertex> getFragmentsCompatibleWithTheseAPs(
            ArrayList<IdFragmentAndAP> srcAPs)
    {
        // First we get all possible APs on any fragment
        ArrayList<IdFragmentAndAP> compatFragAps = 
                getFragAPsCompatibleWithTheseAPs(srcAPs);
 
        // then keep unique fragment identifiers, and store unique
        Set<Integer> compatFragIds = new HashSet<Integer>();
        for (IdFragmentAndAP apId : compatFragAps)
        {
            compatFragIds.add(apId.getVertexMolId());
        }
 
        // Then we pack-up the selected list of fragments
        ArrayList<Vertex> compatFrags = new ArrayList<Vertex>();
        for (Integer fid : compatFragIds)
        {
            try {
                compatFrags.add(getVertexFromLibrary(BBType.FRAGMENT, fid));
            } catch (DENOPTIMException e) {
                settings.getLogger().log(Level.WARNING, "Exception while trying "
                        + "to get fragment '" + fid + "'!");
                e.printStackTrace();
            }
        }
        return compatFrags;
    }
 
//------------------------------------------------------------------------------
    
    public List<Vertex> getRCVsWithAPClass(APClass apc) 
    {
        List<Vertex> chosenRCVs = new ArrayList<Vertex>();
        for (Vertex rcv : getRCVs())
        {
            // NB: RCVs must have only one attachment point
            if (apc.equals(rcv.getAP(0).getAPClass()))
            {
                Vertex copyOfRCV = null;
                try
                {
                    copyOfRCV = getVertexFromLibrary(rcv.getBuildingBlockType(),
                            rcv.getBuildingBlockId());
                    chosenRCVs.add(copyOfRCV);
                } catch (DENOPTIMException e)
                {
                    // This should never happen because we have already taken 
                    // the BB from BBSpace.
                    e.printStackTrace();
                }
            }
        }
        return chosenRCVs;
    }
    
//------------------------------------------------------------------------------
    
    public List<Vertex> getRCVsForAPClass(APClass apc) 
    {
        List<Vertex> chosenRCVs = new ArrayList<Vertex>();
        if (!getCompatibilityMatrix().containsKey(apc))
        {
            return chosenRCVs;
        }
        List<APClass> apcsCompatWithSrcAP = getCompatibilityMatrix().get(apc);
        for (Vertex rcv : getRCVs())
        {
            // NB: RCVs must have only one attachment point
            if (apcsCompatWithSrcAP.contains(rcv.getAP(0).getAPClass()))
            {
                Vertex copyOfRCV = null;
                try
                {
                    copyOfRCV = getVertexFromLibrary(rcv.getBuildingBlockType(),
                            rcv.getBuildingBlockId());
                    chosenRCVs.add(copyOfRCV);
                } catch (DENOPTIMException e)
                {
                    // This should never happen because we have already taken 
                    // the BB from BBSpace.
                    e.printStackTrace();
                }
            }
        }
        return chosenRCVs;
    }
    
//------------------------------------------------------------------------------
    
    public ArrayList<AttachmentPoint> getAPsCompatibleWithThese(
                    ArrayList<AttachmentPoint> srcAPs)
    {
        ArrayList<AttachmentPoint> compAps = 
                new ArrayList<AttachmentPoint>();
        boolean first = true;
        for (AttachmentPoint ap : srcAPs)
        { 
            ArrayList<AttachmentPoint> compForOne = 
                    getAPsCompatibleWithClass(ap.getAPClass());
 
            if (first)
            {
                compAps.addAll(compForOne);
                first = false;
                continue;
            }
            
            ArrayList<AttachmentPoint> toKeep = 
                    new ArrayList<AttachmentPoint>();
            for (AttachmentPoint candAp : compAps)
            {
                for (AttachmentPoint newCand : compForOne)
                {
                    if (newCand == candAp)
                    {
                            toKeep.add(candAp);
                            break;
                    }
                }
            }
            
            compAps = toKeep;
            
            if (compAps.size()==0)
            {
                break;
            }
        }
        return compAps;
    }
    
//------------------------------------------------------------------------------
 
    public ArrayList<IdFragmentAndAP> getFragAPsCompatibleWithTheseAPs(
            ArrayList<IdFragmentAndAP> srcAPs)
    {
        ArrayList<IdFragmentAndAP> compFrAps = new ArrayList<IdFragmentAndAP>();
        boolean first = true;
        for (IdFragmentAndAP apId : srcAPs)
        {
            APClass srcApCls = getAPClassForFragment(apId);
            ArrayList<IdFragmentAndAP> compForOne = 
                    getFragAPsCompatibleWithClass(srcApCls);
 
            if (first)
            {
                compFrAps.addAll(compForOne);
                first = false;
                continue;
            }
 
            ArrayList<IdFragmentAndAP> toKeep = 
                    new ArrayList<IdFragmentAndAP>();
            for (IdFragmentAndAP candAp : compFrAps)
            {
                for (IdFragmentAndAP newId : compForOne)
                {
                    if (newId.sameFragAndAp(candAp))
                    {
                        toKeep.add(candAp);
                        break;
                    }
                }
            }
 
            compFrAps = toKeep;
 
            if (compFrAps.size() == 0)
            {
                break;
            }
        }
 
        return compFrAps;
    }
 
//------------------------------------------------------------------------------
 
    public ArrayList<AttachmentPoint> getAPsCompatibleWithClass(
                    APClass aPC1)
    {
        ArrayList<AttachmentPoint> compatAps = 
                new ArrayList<AttachmentPoint>();
        
        // Take the compatible AP classes
        ArrayList<APClass> compatApClasses = getCompatibleAPClasses(aPC1);
        
        // Find all APs with a compatible class
        if (compatApClasses != null)
        {
            for (APClass klass : compatApClasses)
            {
                ArrayList<Vertex> vrtxs = getVerticesWithAPClass(klass);
                for (Vertex v : vrtxs)
                {
                    for (AttachmentPoint ap : v.getAttachmentPoints())
                    {
                        if (ap.getAPClass() == klass)
                        {
                            compatAps.add(ap);
                        }
                    }
                }
            }
        }
        
        if (compatAps.size()==0)
        {
            settings.getLogger().log(Level.WARNING,"No compatible "
                    + "AP found in the fragment space for APClass '" 
                    + aPC1 + "'.");
        }
        
        return compatAps;
    }
    
//------------------------------------------------------------------------------
    
    public ArrayList<IdFragmentAndAP> getFragAPsCompatibleWithClass(
            APClass aPC1)
    {
        ArrayList<IdFragmentAndAP> compatFragAps = 
                new ArrayList<IdFragmentAndAP>();
 
        // Take the compatible AP classes
        ArrayList<APClass> compatApClasses = getCompatibleAPClasses(aPC1);
 
        // Find all APs with any compatible class
        if (compatApClasses != null)
        {
            for (APClass compClass : compatApClasses)
            {
                compatFragAps.addAll(getFragsWithAPClass(compClass));
            }
        }
        return compatFragAps;
    }
 
//------------------------------------------------------------------------------
 
    public boolean imposeSymmetryOnAPsOfClass(APClass apClass)
    {
        boolean res = true;
        if (hasSymmetryConstrain(apClass))
        {
            if (getSymmetryConstrain(apClass) < (1.0
                    - DENOPTIMConstants.FLOATCOMPARISONTOLERANCE))
            {
                res = false;
            }
        } else
        {
            if (!settings.enforceSymmetry())
            {
                res = false;
            }
        }
        return res;
    }
 
//------------------------------------------------------------------------------
 
    public boolean hasSymmetryConstrain(APClass apClass)
    {
        if (symmConstraints==null)
            return false;
        return symmConstraints.containsKey(apClass);
    }
 
//------------------------------------------------------------------------------
 
    public double getSymmetryConstrain(APClass apClass)
    {
        return symmConstraints.get(apClass);
    }
 
//------------------------------------------------------------------------------
 
    public void setScaffoldLibrary(ArrayList<Vertex> lib)
    {
        scaffoldLib = new ArrayList<Vertex>();
        appendVerticesToLibrary(lib, BBType.SCAFFOLD, scaffoldLib);
    }
 
    public void setFragmentLibrary(ArrayList<Vertex> lib)
    {
        fragmentLib = new ArrayList<Vertex>();
        appendVerticesToLibrary(lib, BBType.FRAGMENT, fragmentLib);
    }
 
//------------------------------------------------------------------------------
 
    public void setCappingLibrary(ArrayList<Vertex> lib)
    {
        cappingLib = new ArrayList<Vertex>();
        appendVerticesToLibrary(lib, BBType.CAP, cappingLib);
    }
 
//------------------------------------------------------------------------------
 
    public void setCompatibilityMatrix(HashMap<APClass, ArrayList<APClass>> map)
    {
        apClassCompatibilityMatrix = map;
    }
 
//------------------------------------------------------------------------------
 
    public void setRCCompatibilityMatrix(HashMap<APClass, 
            ArrayList<APClass>> map)
    {
        rcCompatMap = map;
    }
 
//------------------------------------------------------------------------------
 
    public void setCappingMap(HashMap<APClass, APClass> map)
    {
        cappingMap = map;
    }
 
//------------------------------------------------------------------------------
 
    public void setForbiddenEndList(Set<APClass> lst)
    {
        forbiddenEndList = lst;
    }
 
//------------------------------------------------------------------------------
 
    public void setSymmConstraints(HashMap<APClass, Double> map)
    {
        symmConstraints = map;
    }
 
//------------------------------------------------------------------------------
 
    public void clearAll()
    {
        scaffoldLib = null;
        fragmentLib = null;
        cappingLib = null;
        apClassCompatibilityMatrix = null;
        rcCompatMap = null;
        cappingMap = null;
        forbiddenEndList = null;
        fragPoolPerNumAP = new HashMap<Integer,ArrayList<Integer>>();
        apClassesPerFrag = new HashMap<Integer,ArrayList<APClass>>();
        fragsApsPerApClass = new HashMap<APClass,ArrayList<ArrayList<Integer>>>();
        symmConstraints = null;
        isValid = false;
    }
    
//------------------------------------------------------------------------------
 
    public void appendVerticesToLibrary(ArrayList<Vertex> list, 
            Vertex.BBType bbt, ArrayList<Vertex> library)
    {
        for (Vertex v : list)
        {
            appendVertexToLibrary(v, bbt, library);
        }
    }
    
//------------------------------------------------------------------------------
 
    public void appendVertexToLibrary(Vertex v, 
            Vertex.BBType bbt, ArrayList<Vertex> library)
    {
        v.setBuildingBlockId(library.size());
        v.setBuildingBlockType(bbt);
        library.add(v);
        if (bbt == BBType.FRAGMENT)
        {
            classifyFragment(v, library.size()-1);
        }
    }
    
//------------------------------------------------------------------------------
 
    //TODO: need something to prevent memory overload: 
    // -> keep only some templates?
    // -> remove those who did not lead to good population members?
    // -> remove redundant? The highest-simmetry principle (i.e., rather than 
    //    keeping a template as it is, we'd like to keep its highest symmetry 
    //    isomorphic) would be the first thing to do.
    
    public void addFusedRingsToFragmentLibrary(DGraph graph) 
    {
        addFusedRingsToFragmentLibrary(graph,true,true);
    }
    
//------------------------------------------------------------------------------
 
    public void addFusedRingsToFragmentLibrary(DGraph graph,
            boolean addIfScaffold, boolean addIfFragment) 
    {
        addFusedRingsToFragmentLibrary(graph, addIfScaffold, addIfFragment, null);
    }
    
//------------------------------------------------------------------------------
 
    //TODO: need something to prevent memory overload: 
    // -> keep only some templates?
    // -> remove those who did not lead to good population members?
    // -> remove redundant? The highest-symmetry principle (i.e., rather than 
    //    keeping a template as it is, we'd like to keep its highest symmetry 
    //    isomorphic) would be the first thing to do.
    
    public void addFusedRingsToFragmentLibrary(DGraph graph,
            boolean addIfScaffold, boolean addIfFragment, 
            IAtomContainer wholeMol) 
    {
        List<DGraph> subgraphs = null;
        try
        {   
            subgraphs = graph.extractPattern(GraphPattern.RING);
        } catch (DENOPTIMException e1)
        {
            settings.getLogger().log(Level.WARNING,"Failed to extract "
                    + "fused ring patters.");
            e1.printStackTrace();
        }
 
        for (DGraph g : subgraphs) 
        {
            BBType type = g.hasScaffoldTypeVertex() ? 
                    BBType.SCAFFOLD :
                        BBType.FRAGMENT;
            
            if (!addIfFragment && type == BBType.FRAGMENT) 
            {
                continue;
            }
            if (!addIfScaffold && type == BBType.SCAFFOLD)
            {
                continue;
            }
 
            ArrayList<Vertex> library = type == BBType.FRAGMENT ?
                    fragmentLib : scaffoldLib;
            
            synchronized (LOCK)
            {
                if (!hasIsomorph(g, type)) 
                {   
                    //TODO: try to transform the template into its isomorphic
                    // with highest symmetry, and define the symmetric sets. 
                    // Such enhancement would facilitate the creation of 
                    // symmetric graphs from templates generated on the fly.
                    
                    Template t = new Template(type);
                    t.setInnerGraph(g);
                    
                    boolean has3Dgeometry = false;
                    IAtomContainer subIAC = null;
                    if (wholeMol!=null)
                    {
                        try
                        {
                            subIAC = MoleculeUtils.extractIACForSubgraph(
                                    wholeMol, g, graph, settings.getLogger(),
                                    settings.getRandomizer());
                            t.setIAtomContainer(subIAC,true);
                            has3Dgeometry = true;
                        } catch (DENOPTIMException e1)
                        {
                            e1.printStackTrace();
                            ArrayList<DGraph> lst = new ArrayList<>();
                            lst.add(graph);
                            lst.add(g);
                            String forDebugFile = "failedExtractIAC_" 
                            + graph.getGraphId() + ".json";
                            try
                            {
                                DenoptimIO.writeGraphsToJSON(
                                        new File(forDebugFile), lst);
                                settings.getLogger().log(Level.WARNING, 
                                        "WARNING: failed to extract "
                                        + "molecular representation of graph. "
                                        + "See file '" + forDebugFile + "'.");
                            } catch (DENOPTIMException e)
                            {
                                settings.getLogger().log(Level.WARNING,
                                        "WARNING: failed to extract "
                                        + "molecular representation of graph, "
                                        + "and failed to write graph to file.");
                            }
                        }
                    }
    
                    String msg = "Adding new template (Inner Graph id: " 
                            + t.getInnerGraph().getGraphId() + ") to the "
                            + "library of " + type + "s. The template is "
                            + "generated from graph " + graph.getGraphId();
                    Candidate source = graph.getCandidateOwner();
                    if (source != null)
                        msg = msg + " candidate " + source.getName();
                    else
                        msg = msg + ".";
                    settings.getLogger().log(Level.INFO, msg);
                    
                    appendVertexToLibrary(t, type, library);
                    if (type == BBType.FRAGMENT)
                    {
                        classifyFragment(t,library.size()-1);
                    }
                    
                    String destFileName = type == BBType.FRAGMENT ?
                            settings.getPathnameToAppendedFragments() :
                                settings.getPathnameToAppendedScaffolds();
                    try
                    {
                        if (has3Dgeometry)
                        {
                            DenoptimIO.writeSDFFile(destFileName,subIAC,true);
                        } else {
                            DenoptimIO.writeGraphToSDF(new File(destFileName), 
                                    g, true, false, settings.getLogger(),
                                    settings.getRandomizer());
                        }
                    } catch (DENOPTIMException e)
                    {
                        e.printStackTrace();
                        settings.getLogger().log(Level.WARNING, "WARNING: "
                                + "failed to write newly "
                                + "generated " + type + " to file '" 
                                + destFileName + "'.");
                    }
                }
            }
        }
    }
    
//------------------------------------------------------------------------------
 
    public boolean hasIsomorph(DGraph graph, BBType type) {
        return (type == BBType.SCAFFOLD ? scaffoldLib : fragmentLib)
                .stream()
                .filter(v -> v instanceof Template)
                .map(t -> (Template) t)
                .map(Template::getInnerGraph)
                .anyMatch(graph::isIsomorphicTo);
    }
 
//------------------------------------------------------------------------------
    
    public void registerRCV(Vertex v)
    {
        rcvs.add(v);
    }
  
//------------------------------------------------------------------------------
    
    public ArrayList<Vertex> getRCVs()
    {
        return rcvs;
    }
    
//------------------------------------------------------------------------------
 
    public List<APMapping> mapAPClassCompatibilities(
            List<AttachmentPoint> listA, 
            List<AttachmentPoint> listB, int maxCombinations)
    {
        Map<AttachmentPoint,List<AttachmentPoint>> apCompatilities =
                new HashMap<AttachmentPoint,List<AttachmentPoint>>();
        
        for (AttachmentPoint apA : listA)
        {
            for (AttachmentPoint apB : listB)
            {  
                boolean compatible = false;
                if (useAPclassBasedApproach())
                {   
                    if (apA.getAPClass().isCPMapCompatibleWith(apB.getAPClass(),
                            this))
                    {
                        compatible = true;
                    }
                } else {
                    compatible = true;
                }
                if (compatible)
                {
                    if (apCompatilities.containsKey(apA))
                    {
                        apCompatilities.get(apA).add(apB);
                    } else {
                        List<AttachmentPoint> lst = 
                                new ArrayList<AttachmentPoint>();
                        lst.add(apB);
                        apCompatilities.put(apA,lst);
                    }
                }
            }
        }
        
        // This is used only to keep a sorted list of the map keys
        List<AttachmentPoint> keys = 
                new ArrayList<AttachmentPoint>(
                        apCompatilities.keySet());
        
        // Get all possible combinations of compatible AP pairs
        List<APMapping> apMappings = new ArrayList<APMapping>();
        if (keys.size() > 0)
        {
            int currentKey = 0;
            APMapping currentMapping = new APMapping();
            FragmentSpaceUtils.recursiveCombiner(keys, currentKey, 
                    apCompatilities, currentMapping, apMappings, true, 
                    maxCombinations);
        }
        
        return apMappings;
    }
 
//------------------------------------------------------------------------------
    
    public void classifyFragment(Vertex frg, int fragId)
    {   
        // Classify according to number of APs
        int nAps = frg.getFreeAPCount();
        if (nAps != 0)
        {
            if (getMapOfFragsPerNumAps().containsKey(nAps))
            {
                getFragsWithNumAps(nAps).add(fragId);
            }
            else
            {
                ArrayList<Integer> lst = new ArrayList<>();
                lst.add(fragId);
                getMapOfFragsPerNumAps().put(nAps,lst);
            }
        }
    
        if (useAPclassBasedApproach())
        {
            // Collect classes per fragment
            ArrayList<APClass> lstAPC = frg.getAllAPClasses();
            synchronized (LOCK)
            {
                apClassesPerFrag.put(fragId,lstAPC);
            }
            
            // Classify according to AP-Classes
            List<AttachmentPoint> lstAPs = frg.getAttachmentPoints();
            
            for (int j=0; j<lstAPs.size(); j++)
            {
                AttachmentPoint ap = lstAPs.get(j);
                ArrayList<Integer> apId = new ArrayList<Integer>();
                apId.add(fragId);
                apId.add(j);
                APClass cls = ap.getAPClass();
                
                if (!ap.isAvailable())
                {
                    continue;
                }
                
                synchronized (LOCK)
                {
                    if (fragsApsPerApClass.containsKey(cls))
                    {
                        fragsApsPerApClass.get(cls).add(apId);
                    } else {
                        ArrayList<ArrayList<Integer>> outLst = 
                                    new ArrayList<ArrayList<Integer>>();
                        outLst.add(apId);
                        fragsApsPerApClass.put(cls,outLst);
                    }
                }
            }
            
            if (frg.isRCV())
                registerRCV(frg);
        }
    }
 
//------------------------------------------------------------------------------
 
    public void groupAndClassifyFragments(boolean apClassBasedApproch)
            throws DENOPTIMException
    {   
        for (int j=0; j<getFragmentLibrary().size(); j++)
        {
            Vertex frag = getFragmentLibrary().get(j);
            classifyFragment(frag,j);
        }
    }
 
//------------------------------------------------------------------------------
 
    public static Vertex getPolarizedRCV(boolean polarity)
    {   
        APClass apc = APClass.RCACLASSPLUS;
        if (!polarity)
            apc = APClass.RCACLASSMINUS;
        
        Fragment rcv = new Fragment();
        Atom atom = new PseudoAtom(RingClosingAttractor.RCALABELPERAPCLASS.get(apc), 
                new Point3d());
        rcv.addAtom(atom);
        rcv.addAP(0, new Point3d(1.5, 0.0, 0.0), apc);
        rcv.setAsRCV(true);
        return rcv;
    }
 
//------------------------------------------------------------------------------
    
}