Superatom S-groups

Building of Superatom S-group

We show how to build Superatom S-groups in the example of the phenyl group.

First, the whole molecule should be built using the Core API methods, or imported. In this example, we import it from SMILES format. Then the SuperatomSgroup is constructed with the molecule in the argument of the constructor.

Creating of SuperatomSgroup object

Molecule mol = MolImporter.importMol("C1=CC=CC=C1C");
Cleaner.clean(mol, 2, null);
 
// Create the Sgroups.
SuperatomSgroup superSg = new SuperatomSgroup(mol);

On this page:

Superatom S-groups
- Building of Superatom S-group
- Expanded, contracted state
Amino acid S-groups
Repeating unit S-groups

In order to set subscript of a Superatom S-group, use the SuperatomSgroup.setSubscript(String) method:

Set subscript of the S-group

superSg.setSubscript("Ph");

The atoms that are supposed to be a part of an S-group should be added to it (that is, set the S-group as the parent of the MolAtom). In our example, we add the carbon atoms of the benzene ring to the S-group, they are the first six atoms of the molecule.

Setting an S-group as the parent of its atoms

for (int i = 0; i < 6; i++) {
    mol.setSgroupParent(mol.getAtom(i), superSg, true);
}
superSg.calculateAttachmentPoints();

In the argument of the Molecule.setSgroupParent() method, MolAtom represents the atom to be added to the Superatom S-group superSg. If the value of the boolean parameter is true, the atom will be added to the S-group, otherwise it will be removed from there. The molecule now is inconsistent, because an attachment point is missing from the Superatom S-group. Use the SuperatomSgroup.calculateAttachmentPoints() method to add automatically, or use the SuperatomSgroup.addAttachmentPoint(MolAtom) method to add manually the missing attachment points.

Adding attachment points

Since Marvin 6.0, we support to add S-group attachment point only to atoms that are part of a Superatom S-group. Attachment points are represented by an object which stores its attach atom, crossing bond and order. The attach atom is one of the MolAtoms of the superatom S-group on which the attachment point is placed. The crossing bond is a bond where

one of the end atoms is inside the Superatom S-group (this atom is called attach atom);
the other end atom is outside the Superatom S-group.

When an attachment point is free, the crossing bond is null, further crossing bond addition is possible. The order is an integer greater than zero defining the priority of the attachment point. When a bond is added to a contracted superatom S-group, it occupies a free attachment point with the lowest order.

To add an attachment point, use one of the following methods:

SuperatomSgroup.addAttachmentPoint(MolAtom);
SuperatomSgroup.addAttachmentPoint(MolAtom, int order);

In the first case, the smallest unused number is set as order.

Crossing bond can be added to an attachment point by invoking SuperatomSgroup.addCrossingBond(MolAtom attachAtom, MolBond crossingBond) method. However, the crossing bond information is updated automatically by Molecule.add(MolBond bond) method.

Note, that the method MolAtom.setAttach(int) is deprecated, and its usage is not recommended any more.

Calculate attachment points

By invoking SuperatomSgroup.calculateAttachmentPoints(), attachments points are put to atoms in the superatom S-group that have bond which other end atom is outside the group (crossing bond). It is useful when the superatom S-group is created using the SuperatomSgroup.setSgroupGraph() method.

Getting the attachment point information

Attachment point information of a superatom S-group can be received by calling method SuperatomSgroup.getAttachmentPoints(). The result is an java.util.ArrayList of AttachmentPoint objects from the superatom S-group. The list is sorted by increasing attachment point orders.

Note, that the method MolAtom.getAttach() is deprecated, and its usage is not recommended any more. The orders of the attachment points located on a given atom can be obtained by invoking method SuperatomSgroup.getAttachmentPointOrders(MolAtom). It returns the ArrayList<Integer> of attachment point orders located on the given MolAtom.

Full example of building polystyrene

/*
 *  Copyright (c) 1998-2014 ChemAxon Ltd. All Rights Reserved.
 *  This software is the confidential and proprietary information of
 *  ChemAxon. You shall not disclose such Confidential Information
 *  and shall use it only in accordance with the terms of the agreements
 *  you entered into with ChemAxon.
 *  
 */
package chemaxon.examples.strucrep;
 
import java.io.IOException;
 
import chemaxon.calculations.clean.Cleaner;
import chemaxon.formats.MolExporter;
import chemaxon.formats.MolImporter;
import chemaxon.marvin.util.CleanUtil;
import chemaxon.struc.Molecule;
import chemaxon.struc.Sgroup;
import chemaxon.struc.graphics.MBracket;
import chemaxon.struc.sgroup.RepeatingUnitSgroup;
import chemaxon.struc.sgroup.SuperatomSgroup;
 
/**
 * Example class for creating sgroups.
 * 
 * @author Janos Kendi
 * 
 */
public class BuildMoleculeWithSgroupExample {
 
    public static void main(String[] args) throws IOException {
 
		// Import the molecule
		Molecule mol = MolImporter.importMol("C1=CC=CC=C1C(C)CC");
		Cleaner.clean(mol, 2, null);
 
		// Create Superatom S-group.
		SuperatomSgroup superSg = new SuperatomSgroup(mol);
 
		for (int i = 0; i < 6; i++) {
		    mol.setSgroupParent(mol.getAtom(i), superSg, true);
		}
		superSg.setSubscript("Ph");
	
		//Add attachment point. The attach atom is the fifth of the molecule.
		//The crossing bond is also fifth one of the molecule. 
		superSg.addAttachmentPoint(mol.getAtom(5), 1);
		superSg.addCrossingBond(mol.getAtom(5), mol.getBond(5));
	
		//Create Repeating unit S-group
		RepeatingUnitSgroup repeatingSg = new RepeatingUnitSgroup(mol, "ht",
			Sgroup.ST_SRU);
	
		// Set the RepeatingUnitSgroup atoms.
		for (int i = 0; i < 9; i++) {
	 	    if (mol.getAtom(i).getBondCount() >  1) {
				mol.setSgroupParent(mol.getAtom(i), repeatingSg, true);
	    	}
		}
		repeatingSg.addStarAtoms();
	
		// Set the parent-child relation.
		repeatingSg.addChildSgroup(superSg);
	
		CleanUtil.generateBracketCoords(repeatingSg, MBracket.T_SQUARE);
 
		System.out.println(MolExporter.exportToFormat(mol, "mrv:P"));
    }
 
}

Expanded, contracted state

There are two states of the molecule:

All represented atoms are present in the parent molecule in all expandable S-group independently from their expansion state. Here we can see a special S-group state called Sgroup.XSTATE_XC where the S-group remembers its previous contracted state but the represented atoms were moved to the molecule graph and the abbreviation (SgroupAtom) was removed from the molecule graph. Set this state on all Sgroups by calling Molecule.setGUIContracted(false) or by calling Sgroup.setGUIStateRecursively(false) individually on Sgroup-s. Example for a typical usage is a non-GUI related API based calculation where we need the represented atoms in the molecule graph instead of the abbreviation.
Either the abbreviation (SuperAtom) or the represented atom set is exclusively present depending on the state of the S-group. In the case of expanded S-groups (called Sgroup.XSTATE_X) the represented atoms are present in the parent molecule. In the case of contracted S-groups (called Sgroup.XSTATE_C) the abbreviation (SgroupAtom) is present in the parent molecule. Set this state on all Sgroups by calling Molecule.setGUIContracted(true) or by calling Sgroup.setGUIStateRecursively(true) individually on Sgroup-s.

Note: when Molecule.isGUIContracted() returns true and afterwards you call:

    Molecule.setGUIContracted(false); 
    Molecule.setGUIContracted(true);

the second setGUIContracted call will restore the state before the first setGUIContracted call!

Amino acid S-groups

AminoAcidSgroups are special SuperatomSgroups to represent amino acids. The construction of these groups are exactly the same as the SuperatomSgroups. There are two additional attributes - the one letter and the three letter name of the amino acid.

Repeating unit S-groups

Repeating unit S-groups are used to represent polymers and other repeating units.

In order to construct a repeating unit S-group object, use its constructor as

Constructing a repeating unit S-group

RepeatingUnitSgroup repeatingSg = new RepeatingUnitSgroup(Molecule mol, String connectivity, int type);

The parameter Molecule object will be the parent of the S-group repeatingSg. The String connectivity defines way the units connects to each other: "ht", for head-to-tail; "hh", for head-to-head, and "eu" for either/undefined polymers. The type of the S-group can be defined using the following constants:

Sgroup.ST_ANY,
Sgroup.ST_SRU,
Sgroup.ST_COPOLYMER,
Sgroup.ST_CROSSLINK,
Sgroup.ST_GRAFT,
Sgroup.ST_MODIFICATION.

Atoms and bonds can be added to a repeating unit S-group in a same way as to a Superatom S-group.

The bracket of this type of S-groups defines the repeating fragment of the polymer. Bonds that cross the brackets, called crossing bonds, define how the repeating units of the S-group connect.

The generateBracketCoord method of the CleanUtil class generates brackets. As parameter the S-group and the bracket type, square or round, should be added:

Bracket generation for repeating unit S-groups

CleanUtil.generateBracketCoords(repeatingSg, MBracket.T_SQUARE);

The end groups of polymers are often unknown or unspecified which are represented by star atoms (*). Star atoms are defined with the repeatingSg.addStarAtoms() method call.

Full example of building of polystyrene can be found above.