Fragment Commands

Introduction

This chapter describes a number of ChemShell commands that operate on the ChemShell data structure describing a molecule or crystal (also known as the fragment structure). In order to keep the data structure in memory, the fragment has to be declared.

Create

The c_create command is used to setup the fragment structure. See also the z_to_c command described in the Z-matrix section.

List of Functions in this section:

c_create

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Identifier for the resulting fragment object

last argument Tcl List yes - Fragment contents

Description:

c_create creates a fragment object from a set of input records, the following is the simplest form:

c_create coords=c {
coordinates angstrom
o 0. 0. 0.
h 0. 1. 0.
h 0. -0.5 1.0
}

The valid fields are as follows

coordinates: subsequent records define the position of the atoms. Each input record has the form

symbol x y z

Optionally, an atomic charge may be presented as well. If the charge is omitted, it is assumed to be undefined (this is not the same as setting it to zero). The charge may be optionally be preceeded by the keyword "charge".

shells Subsequent records define the position of shells. Each input line consists of:

symbol x y z charge

bqs To define point charge positions. Each subsequent record has the form

symbol x y z charge

space_group Allows the specification of a space group on the next record, which can be presented as a number or a symbol, e.g.

space_group
p-1

cell_constants Allows the specification of crystallographic cell parameters, presented (for 3D systems) as

cell_constants
a b c alpha beta gamma

and for slabs as

cell_constants
a b gamma

and for polymers as

cell_constants
a

Note that if a cell_constants record is presented, it is assumed that coordinates ,shells , and bqs are presented in fractional (or, for 1 and 2D, mixed) units.

cell Allows the specification of real-space periodicity information. Depending on the dimensionality of the system, either 1, 2, or 3 records may be presented, each specifying a real-space vector defining the corresponding cell vector

cell
x1 y1 z1
x2 y2 z2
x3 y3 z3

When cell is presented, it is assumed that the coordinates will be in real-space (cartesian) form.

The coordinates bqs, shells and cell keywords may be optionally followed by a unit specification (e.g. angstrom above) to indicate the unit of length used. The default is au.

connect: specifies how the fragment's connectivity table should be generated. Valid values are covalent (default), ionic or no for an empty connection table. See the connect command for details of the covalent and ionic modes. Note that the connectivity method used is not stored in the fragment file, so the mode should always be specified when reconnecting the fragment if you do not want to use the default.

Manipulations

The following Tcl functions will change a molecule definition. Unless otherwise specified, each command takes a coords= argument to specify the molecule under examination. and in some cases a result= argument to indicate the destination. Other arguments are used as indicated in the examples below.

List of Functions in this section:

set_molecule_charge
set_atom_charge
set_bq_charge
set_shell_charge
unset_charges
add_atom_entry
add_shell_entry
replace_atom_entry
replace_bq_entry
replace_shell_entry
delete_atom_entry
delete_shell_entry
add_connection
delete_connection
set_cell
set_element_data
extend_fragment
connect
c_merge_fragments
set_atom_residue
unset_residues

set_molecule_charge

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

charge real yes - charge to assign

Description:

Assign a charge to a fragment

set_atom_charge

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment

atom_number integer yes - atom index

charge real yes - atom charge

Description:

Sets the charge value for the atom

set_bq_charge

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment

bq_number integer yes - bq index

charge real yes - bq charge

Description:

Sets the charge value for the BQ centre

set_shell_charge

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment

shell_number integer yes - shell index

charge real yes - shell charge

Description:

Sets the charge value for the shell

unset_charges

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment

Description:

Resets the flag denoting that atomic charges are stored for the fragment object

add_atom_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_entry Tcl List yes - Atom data (Symbol,x,y,z)

atom_number integer no - atom number of required atom after insertion

Description:

Add a new atom, adding to the end of the list, unless atomnumber= was specified, in which case the new atom is inserted If the system is periodic, the fractional cell information is also updated (the latter assuming P1 symmetry, which may mean that warning messages are generated later if equivalent atoms are added.

add_shell_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

shell_entry Tcl List yes - Shell data (Symbol,x,y,z,charge,parent core)

position string yes - how shell position is input (absolute or relative coordinates)

Description:

Add a shell to the structural definition. If the system is periodic, the fractional cell information is also updated (the latter assuming P1 symmetry, which may mean that warning messages are generated later if equivalent atoms are added.

The shell coordinates can be given either as absolute values or relative to the corresponding core (the position argument must be given to specify which has been used). Note that if absolute values are used, the parent core will be assigned to the nearest core regardless of user input.

Internally the position is stored using relative coordinates (so the shell will move when the core is moved).

replace_atom_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

atom_number integer yes - index of atom to replace

atom_entry Tcl List yes - Atom data (symbol,x,y,z)

Description:

Replace the specified atom.

replace_bq_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

bq_number integer yes - index of bq to replace

bq_entry Tcl List yes - Bq data (Symbol,x,y,z,charge)

Description:

Replace the specified point charge.

replace_shell_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

shell_number integer yes - index of shell to replace

shell_entry Tcl List yes - Shell data (Symbol,x,y,z,charge,parent core)

position string yes - how shell position is input (absolute or relative coordinates)

Description:

Replace the specified MD Shell.

The shell coordinates can be given either as absolute values or relative to the corresponding core (the position argument must be given to specify which has been used). Internally the position is stored using relative coordinates (so the shell will move when the core is moved).

delete_atom_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

atom_number integer yes - index of atom to delete

Description:

Delete the specified atom. If a shell is attached it will also be deleted.

delete_shell_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

shell_number integer yes - index of shell to delete

Description:

Delete the specified shell and transfer the charge on it to the parent atom.

add_connection

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

i integer yes - first atom index

j integer yes - second atom index

Description:

Add a connection table entry between the specified atoms.

delete_connection

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

i integer yes - first atom index

j integer yes - second atom index

Description:

Deletes a connection table entry between the specified atoms.

set_cell

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

cell Tcl List yes - Unit cell

Description:

Modify periodic boundary conditions

set_element_data

Command Line Arguments

Argument Argument type Mandatory Default To specify

symbol text yes - Element symbol of required atom

field text yes - Element data entry to modify

value real yes - New value to assign.

Description:

Modify an entry from the element data table. Valid values for the field argument are covalent_radius, vdw_radius, atomic_number and atomic_symbol.

extend_fragment

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - origin fragment (must be periodic)

result Fragment tag yes - target fragment (will be non-periodic)

cell_indices Tcl List of 6 integers yes - Start/finish indices of cells required

Description:

Replicate a fragment using the unit cell vectors. The range of the extended lattice is given by six integers, specifying the start and end cell indices in the x,y, and z directions. The example below will generate a 3x3x3 block of cells.

extend_fragment coords=c result=c2  cell_indices= { -1 1 -1 1 -1 1}

connect

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

conn Fragment tag yes - resulting fragment with connectivity table

mode string no covalent Use covalent or ionic radii (see below)

scale real no - Scale factor for radii used for test

toler real no - Tolerance for test

Description:

Generates a connectivity table for a molecule, based on internuclear separation and atomic radii. Atoms i and j are considered to be connected when

R_ij < scale*(rad_i + rad_j) + toler

where R_ij is the internuclear distance, rad_i is the radius of i, and scale and toler take values from the input arguments, and if these are not presented, from the global variables chemsh_default_connectivity_scale and chemsh_default_connectivity_toler

By default covalent radii are used. An alternative ionic mode is available for use with ionic solids and clusters, which uses approximate ionic radii instead. In this mode the distance cut-off is scaled down for ions of the same sign to exclude "unintentional" coordination (therefore when using the ionic mode atomic charges should be set and all shells assigned to atoms).

c_merge_fragments

Command Line Arguments

Argument Argument type Mandatory Default To specify

base Fragment tag yes - fragment 1

add Fragment tag yes - fragment 2

result Fragment tag yes - sum of fragment 1 and fragment 2

Description:

This command merges the fragments c1 and c2 and generates a single fragment cmerged consisting of the overlay of the original fragments. The ordering of the atoms in the resulting fragment are as follows: first the atoms in fragment c1 in the same order as in that fragment, then the atoms in fragment c2, with the exception of atoms close to the atoms already defined in fragment c1. The atoms in c2 close to the atoms in c1 are assumed to be duplicate and are therefore discarded in the merging operation. The default values for the seed=, start=, and end= arguments are 1, 1, and the number of atoms in the fragment, respectively.

c_merge_fragments base=c1 add=c2 result=cmerged

set_atom_residue

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment

atom_number integer yes - atom index

residue integer yes - number of the residue (charge group) the atom belongs to

Description:

Sets the number of the residue (charge group) the atom belongs to

unset_residues

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment

Description:

Resets the flag denoting that residue (charge group) information for the atoms is stored for the fragment object

Inquiry

The following Tcl functions will return information on a molecule definition. Each command takes a coords= argument to specify the molecule under examination. Other arguments are used as indicated in the examples below.

List of Functions in this section:

get_number_of_atoms
get_number_of_bqs
get_number_of_exts
get_molecule_name
get_molecule_charge
check_for_bond
check_molecule connectivity
get_connected_atoms
get_molecule_members
interatomic_distance
angle
dihedral
get_atom_entry
get_atom_charge
get_atom_znum
atom_charge_defined
get_bq_entry
get_shell_entry
get_ext_entry
get_cell
get_molecule_centre
get_molecule_radius
get_element_data
compare_fragments
bang
get_atom_residue
get_electric_bq_field

get_number_of_atoms

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Returns the number of atoms in a fragment

get_number_of_bqs

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Returns the number of bqs (point charges) in a fragment

get_number_of_exts

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Returns the number of external sites in a fragment

get_molecule_name

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Returns the title of the fragment

get_molecule_charge

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Returns or modifies the internally stored charge, for example:

set old [get_molecule_charge coords=c ]
set_molecule_charge coords=c charge=2
set new [get_molecule_charge coords=c ]
puts stdout "old charge $old, new charge $new"

check_for_bond

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

i integer yes - first atom index

j integer yes - second atom index

Description:

Returns 1 if a connection is stored between two atoms, 0 otherwise.

check_molecule connectivity

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Returns 1 if a connectivity table is stored for the fragment, 0 otherwise.

get_connected_atoms

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_number integer yes - reference atom

Description:

Returns a Tcl list of atom numbers. The atom numbers listed are those connected to the atom specified through the atom_number= argument.

set mol_list [get_connected_atoms coords=c atom_number=4]
puts stdout $mol_list

get_molecule_members

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_number integer yes - reference atom

range integer no - number of bonds to search (default 9999)

Description:

Returns a Tcl list of atom numbers. The atom numbers listed are those connected to the atom specified through the atom_number= argument up to range= number of bonds from the specified atom. The default of the range= argument is 9999, which in principle suffices to get all the atoms belonging to a molecule.

set mol_list [get_molecule_members coords=c atom_number=4 range=3]
puts stdout $mol_list

interatomic_distance

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

i integer yes - first atom index

j integer yes - second atom index

unit text no - specification of output unit (default au)

Description:

Returns an interatomic separation in au.
set r12 [interatomic_distance coords=c i=1 j=2]
The unit=angstrom argument may be used to request the distance in Å.

angle

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

i integer yes - first atom index

j integer yes - second atom index

k integer yes - third atom index

Description:

Returns the angle defined by atoms i-j-k in degrees.

dihedral

Command Line Arguments

Description:

Returns the torsion angle defined by atoms i-j-k-l in degrees.

get_atom_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_number integer yes - index of atom to recover

Description:

Returns information about an atom, consisting of the atom symbol and x,y, and z coordinates for the requested atom. The following example loops over all atoms retrieving the the atomic symbol and coordinates.

set n [get_number_of_atoms coords=c ]
for {set i 0} {$i < $n} {incr i} {

set atom [ get_atom_entry atom_number=$i coords=c]
puts stdout $atom
}

get_atom_charge

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_number integer yes - index of atom

Description:

Returns atom charge, or the string "undefined" if the charge is not defined.

get_atom_znum

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_number integer yes - index of atom

Description:

Returns atomic number (Z) of the atom.

atom_charge_defined

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_number integer yes - index of atom

Description:

Returns 1 if the atom charge is defined, 0 otherwise.

get_bq_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

bq_number integer yes - index of bq to recover

Description:

Returns information about a bq (point charge), consisting of the charge and x,y, and z coordinates for the requested centre.

get_shell_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

shell_number integer yes - index of shell to recover

position string yes - how shell position is returned (absolute or relative coordinates)

Description:

Returns information about a shell, consisting of the symbol, x,y, and z coordinates, charge and parent core of the requested centre.

The shell coordinates can be returned either as absolute values or relative to the corresponding core (the position argument must be given to specify which to return). Internally the position is stored using relative coordinates (so the shell will move when the core is moved).

get_ext_entry

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

ext_number integer yes - index of external site to recover

Description:

Returns information about an external site, consisting of the charge and x,y, and z coordinates for the requested centre.

get_cell

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

Description:

Return simulation cell as a Tcl list 0 elements for a non-periodic system 6 for a slab 9 for a 3-d system

get_molecule_centre

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

Description:

Return the centroid of the fragment, as a Tcl list of three real values.

get_molecule_radius

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

Description:

Return the radius of the smallest sphere, which, when centred at the centroid of the fragment encloses all the atoms.

get_element_data

Command Line Arguments

Argument Argument type Mandatory Default To specify

symbol text no - Element symbol of required atom type

atomic_number integer no - Atomic number of required atom type

field text yes - Required element data entry

Description:

Return an entry from the element data table. It is possible to provide either the symbol or the atomic number. Valid values for the field argument are covalent_radius, vdw_radius, atomic_number and atomic_symbol.

compare_fragments

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords1 Fragment tag yes - First fragment

coords2 Fragment tag yes - Second fragment

toler real no - Tolerance for tests (default 0.01 au).

Description:

Check two fragments for matching coordinates and symbols.

bang

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - input structure

toler floating point yes - tolerance used for generating connectivity

unit string yes - unit to use

Description:

bang is a program to generate bond-length and angle listings. The bond lengths, inter-bond angles, and proper torsion angles are printed out. The tolerance is used in the same way as connect to determine which parameters are listed. The unit may be angstrom or au, (au is the default).

get_atom_residue

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

atom_number integer yes - index of atom

Description:

Returns the number of the residue (charge group) the atom belongs to, or the string "undefined" if the charge is not defined.

get_electric_bq_field

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

position Tcl List of 3 real numbers no - Position to calculate the potential and the electric filed.

file string no - File name to which an xyz file is written contining the atom positions and the electric field at that atom.

Description:

To be used with fragments containing point charges as bq entries. get_electric_bq_field calculates the electrostatic potential and the electric field that the bqs cause at the atomic positions. If position is specified, the potential and the field are calculated there.

If charges of the atoms are specified (e.g. by using fit_esp_charges), the command will also print the electrostatic force on that atom caused by the bq charges in the fragment.

IO Operations

List of Functions in this section:

write_xyz
read_xyz
write_pdb
read_pdb
write_xtl
read_xtl
write_msi
list_molecule
c_prepare_input

write_xyz

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Fragment to output

file text yes - Output file name

Description:

Write out a fragment to a file in xyz format.

read_xyz

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Fragment to create

file text yes - Input file name

Description:

Read in a fragment from a file in xyz format.

write_pdb

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Fragment to output

file text yes - Output file name

info_var keyword no none pdb meta info stored by read_pdb (specified there also by info_var)

residues Tcl List no none List of residues in the same format as required for hdlcopt (see there). Atoms with no residue in this list are assigned the residue "none".

Description:

Write out a fragment to a file in pdb format. If a previous call of read_pdb on a pdb file with the same number of atoms was made, meta-informations such as residue names are reused. Otherwise they are guessed.

read_pdb

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Fragment to create

file text yes - Input file name

info_var keyword no none save pdb meta info to be reused by write_pdb

Description:

Read in a fragment from a file in pdb format.

write_xtl

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Fragment to output

file text yes - Output file name

Description:

Write out a fragment to a file in xtl format. This format can be used to output periodic systems

read_xtl

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Fragment to create

file text yes - Input file name

Description:

Read a fragment object from a file in xtl format.

write_msi

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - Fragment to output

file text yes - Output file name

Description:

Write out a fragment to a file in msi format.

list_molecule

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Provide listing of fragment definition to stdout.

c_prepare_input

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to interrogate

Description:

Provide listing of fragment definition to stdout in form suitable for use by the c_create command. The resulting text is the return value, use as follows set data [ c_prepare_input coords=c ] set fp [ open data.txt w ] puts $fp $data close $fp

List of Functions in this section:

c_shuffle
c_reorder

c_shuffle

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

result Fragment tag yes - resultant fragment

indexlist Tcl List yes - re-ordering matrix

Description:

This command will change the order in which the cartesian atoms are listed. In the example, atoms 5, 12, 3, and 8 in the original fragment c will appear as atoms 1, 2, 3, and 4 in the resulting fragment cshuffled. The other atoms then follow: number 1 will be 5, number 2 will be 6, number 4 will be 7, etc.

c_shuffle coords=c result=cshuffled indexlist= {5 12 3 8}

c_reorder

Command Line Arguments

Argument Argument type Mandatory Default To specify

coords Fragment tag yes - denotes fragment to modify

result Fragment tag yes - resultant fragment

seed integer no - reference atom number

start integer no - start reordering from this atom

end integer no - finish reordering at this atom

Description:

This command will change the order in which the cartesian atoms are listed on the basis of their distance to a specific atom. The atom with respect to which the distance is measured is specified by the seed= argument. The reordering may be limited to a range of atoms in the original fragment by the start= and end= arguments. In the example, atoms 6 through 12 in the original fragment c will be reordered in increasing distance from atom 1 in the creordered fragment. The default values for the seed=, start=, and end= arguments are 1, 1, and the number of atoms in the fragment, respectively.

c_reorder coords=c result=creordered seed=1 start=6 end=12

This manual was generated using htp, an HTML pre-processor