subStructure

Jump to Description or Examples; explanation of how commands are documented.

Purpose

The subStructure command is used to return a list of all the atoms connected to a given atom which are not also bonded to a second given atom.

Syntax

subStructure varName atom1 ?atom2?

Description

Jump to Syntax or Examples

In the above syntax, atom1 and atom2 are single atom specifications. If these atoms are directly bonded, then a list of atoms composed of atom1 and all the atoms connected to atom1, which are not also connected to atom2, is returned to the object handle varName. If atom2 is not given as an argument or is in a different molecule than atom1, then all the atoms in the molecule containing atom1 are returned to object handle varName. If the two atoms specified are not in the same database, or are in the same molecule but not directly bonded, or are both members of the same ring, then the subStructure command reports an error.

Example 1

Jump to Syntax or Description

BTCL > select atom1 "ethanol:1:C1"
BTCL > select atom2 "ethanol:1:C2"
BTCL > subStructure list1 $atom1 $atom2
BTCL > subStructure list2 $atom2 $atom1
BTCL > database handle dbh ethanol
BTCL > $dbh get names1 Name $list1
BTCL > $dbh get names2 Name $list2
BTCL > object print $names1
 type:     STRING
 items:    4
 elements: 1
 contents:
    "C1"
    "H4"
    "H5"
    "H6"
BTCL > object print $names2
 type:     STRING
 items:    5
 elements: 1
 contents:
    "C2"
    "O3"
    "H7"
    "H8"
    "H9"

In this example, it is assumed that we have loaded a system database that contains an ethanol molecule. The first two select commands are used to create objects that refer to the two carbons in the ethanol molecule (atom1 and atom2). Two subStructure commands are then executed to get the lists of atoms attached to both carbon atoms (list1 and list2). The following database handle command is used to create a database handle (dbh) to the ethanol molecule, which is then used with two database handle get operations to get the atom names corresponding to the atoms in list1 and list2, names1 and names2, respectively. Finally, the contents of the names list objects are printed out using the object print command.

Notice that atom C1 (atom1) is the methyl group carbon, whereas atom C2 (atom2) is the methydroxyl group carbon.

The first command is a database handle command, which is used to create a handle ($dbh) to the ethanol molecule system.

Example 2

BTCL > $dbh get v1 Coord $atom1
BTCL > $dbh get v2 Coord $atom2
BTCL > vector vBond subtract $v1 $v2
BTCL > vector vBond multiply $vBond 0.5
BTCL > $dbh get coords Coord $list2
BTCL > vector coords add $coords $vBond
BTCL > $dbh set $coords Coord $list2

This example shows how lists of atoms created with the subStructure command can be used to alter molecular geometries. Here, the bond length of the C2-C1 bond is increased by 50% by adding half the bond vector to all the atom coordinates of the methyl group (containing the C1 atom). Continuing from the previous example, the atomic coordinates of the carbon atoms (atom1 and atom2) are extracted from the database using database handle get operations, as vectors v1 and v2. Two vector operations are then performed (a subtraction and a multiply by 0.5) to obtain half the bond vector ($vbond) from atom2 to atom1. Another database handle get command is then performed to extract coordinates of the group of atoms at atom1, i.e., the methyl group list1. The half bond vector, vBond, is then added to the methyl atom coordinates using a vector add operation. Finally, the new coordinates for the methyl group (list1) are set for the methyl group atoms using a database handle set operation.

Main access page

Advanced-Use access.

List of BTCL commands subset command vector command