|
The
Chains module contains a template for the force
field assembler of chain models and two utility
functions. This module is called Chains and is
located in Yup.Tools, so the import statement is
some variant of:
from
Yup.Tools.Chains import
*:
this imports three objects, the initialization
function for the Chains class Chains() and the
functions AtomList() and
AtomNumberList().
The
Chains Force Field Assembler class
(Chains)
is based on the standard Force Field Assembler
(FFA)
template
in Yup.Tools.
Data
Attributes
There
are several data attributes but most are not meant
to be manipulated and these are not described here.
The two attributes that can be set are:
|
Attribute
|
Description
|
|
Xfactor
|
The
preset value is 2.0. For Exclusion
terms, the integral floor of the ratio
of the nonbond to the sum of the ideal
bond lengths is multiplied by this
factor to yield the number of closest
neighbors to be excluded in the nonbond
term. For Inclusion terms, the nearest
such neighbors are excluded.
|
|
Sfactor
|
The
preset value is 0.5. This is for
Inclusion terms only. After skipping so
many atoms as determined by
Xfactor,
subsequent atoms are added to the
interaction but only every so many;
this defines the interval between these
atoms. The interval is the integral
floor of the nonbond diameter
multiplied by
Sfactor
and divided by the sum of the ideal
bond lengths that separate a pair of
atoms.
|
Exclusions
are determined separately for each and every
candidate pair.
The
following attributes must be treated as
"read-only".
|
Attribute
|
Description
|
|
ATOMS
|
This
is a tuple containing the AtomMaps of
the chain atoms in sequence
order.
|
|
CHAINS
|
This
contains the parent AtomMap and all
atoms for the model that is being
built.
|
Methods
Use
Chains() as a template to create an assembler for a
model type that can be based on a chain. Then use
the startchain() method to start a chain. Use one
of addtracttochain() or addtracttogroups() to add
links to the chain. This can be done as many times
as is necessary but use one of addtracttogroups()
or addtracttochain() only, not both. When all the
links have been added, call addfieldtochain(),
getchaincoords() and closechain() to complete the
chain. More chains can be added by calling
startchain(), addtracttochain() (or
addtracttogroups()), addfieldtochain() and
closechain() for each of the additional chains. Add
methods to assemble the specific features of your
model. The methods that you add must be called
after startchain() and before
closechain().
Note
that the methods from the parent class are
essential members of this class. In particular the
finish()
method must be called to retrieve the finished
model.
The
constructor function initializes the parent class
FFA (which creates a Model
object filled with a Potential
object, which in turn is filled with four
Energy
objects, and a root AtomMap).
Then, the version string in the parameter library
is checked. The new object is then prepared for
use.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
__init__
|
9
|
-
|
|
Argument
|
Type
|
Preset
Value
|
|
paramdir
|
string
|
-
|
|
poterms
|
list
of tuples
|
-
|
|
verlist
|
tuple
of strings
|
-
|
|
constants
|
tuple
of tuples
|
-
|
|
bonds
|
Bonds
object
|
-
|
|
angles
|
Angles
object
|
-
|
|
torsions
|
Impropers
or Torsions object
|
-
|
|
nonbonds
|
VanderWaalsI,
VanderWaalsX, SoftSphereI or
SoftSphereX object
|
-
|
|
SZ
|
integer
|
1000
|
The
paramdir argument must hold the pathname to
a parameter library. This is usually the path to a
standard library supplied by the subclass. However,
it is possible to supply the name of any library
(e.g. while developing parameters for a new model).
The parameter library is used to create the root
atom map which is then added to the Model
object.
The
poterms argument must contain a list of
tuples. Each tuple must contain a pair of items:
the constructor function for an Energy
object and the string label for the
object.
The
verlist argument must contain a tuple of
strings. Each string identifies a parameter library
and affirms it to be properly specified for the
model.
The
constants argument must be a tuple of
tuples. The inner tuples must each contain four
items: (1) one character that identifies the atom
type, (2) the name of the inclusion atom type, (3)
the name of the exclusion atom type and (4) the
atomic mass. The character in the first item is
used to identify the atom in the sequence; the
sequence is written out as a string of such
characters. The same character is used to label the
atom. Any character, except the digits '0' to '9'
can be used.
The
bonds argument must contain a
Bonds
object.
The
angles argument must contain an
Angles
object.
The
torsions argument must contain a
Torsions
or Impropers
object.
The
nonbonds argument must contain a
SoftSphereI,
SoftSphereX,
VanderWaalsI
or VanderWaalsX
object.
The
SZ argument is used to provide a hint of the
size of the system. Memory is reallocated as
necessary to accommodate an expanding model. If a
good hint can be provided, the number of
reallocations can be minimized and it may even
avoid fragmentation of memory.
The
startchain() method starts a new chain. This must
not be called if another chain is already being
built.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
startchain
|
1
|
-
|
|
Argument
|
Type
|
Preset
Value
|
|
parent
|
AtomMap
|
-
|
The
parent argument must be provided. This is
the parent AtomMap for the chain: the atoms and
groups for the tracts that make up the chain will
be created here.
The
addtracttogroups() method adds a tract to the end
of the current chain. This method can be called as
many times as is needed to construct a chain. It
must not be called until startchain() has been
called.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
addtracttogroups
|
2
|
-
|
|
Argument
|
Type
|
Preset
Value
|
|
tract
|
tuple
|
-
|
|
groups
|
tuple
|
-
|
The
tract argument must be specified. This is a
tuple produced by LinSeq.parseq().
Each component of the tuple consists of an index to
the sequence type and the repeat count.
The
groups argument is a list of Group AtomMaps.
There must be as many groups as the atom count in
tracts.
Each
atom in tract is created inside a
corresponding group in groups.
The
addtracttogroups() and addtracttochain() methods
are mutually exclusive. Although, either method can
be called repeatedly, the calls cannot be mixed.
One must use one method to the exclusion of the
other.
The
addtracttochain() method adds a tract to the end of
the current chain. This method can be called as
many times as is needed to construct a chain. It
must not be called until startchain() has been
called.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
addtracttochain
|
2
|
-
|
|
Argument
|
Type
|
Preset
Value
|
|
sequence
|
string
|
-
|
|
group
|
AtomMap
|
-
|
The
sequence argument must be specified. This is
a string that may consist entirely of digits which
is then taken to be the length of a homogeneous
tract with the first atom type defined in the
constants argument passed to the constructor
of this class. Otherwise, sequence must
start with a legal character (also defined in the
constants argument), followed by digits and
legal characters. This is then taken, to be the
composition of a heterogeneous tract. The
characters are sequence letters and the numbers
that follow are repeat counts.
The
group argument supplies a group AtomMap to
hold the atoms of the tract. This could be the
AtomMap that holds the chain or a group within this
AtomMap.
The
addfieldtochain() method adds interactions (among
the chain atoms) to the Energy objects.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
addfieldtochain
|
2
|
-
|
|
Argument
|
Type
|
Preset
Value
|
|
onterms
|
tuple
of integers
|
(
1, 1, 0, 0 )
|
|
closed
|
integer:
0 or 1
|
0
|
The
onterms argument is a tuple of four
integers. If the first integer is not zero, then
Bonds interactions will be added. If the
second integer is not zero, Angles
interactions will be added and Torsions or
Impropers will be added if the third integer
is not zero. Torsions or Impropers
are added only if Angles are also added and
Angles are added only if Bonds are
added. If the last integer is not zero, then
SoftSphereI, SoftSphereX,
VanderWaalsI or VanderWaalsX terms
are added. If an Exclusion type term is used
exclusions are set to the value of the
Exclusion attribute multiplied by the whole
number ratio (zero if less than one) of the
non-bond radius to the Bonds radius for the
first atom. The non-bond distance is twice the van
der Waals radius in the case of VanderWaalsX
or the exclusion distance in the case of
SoftSphereX. If an Inclusion type term is
used, the closest bonded pair to be added is
separated by Exclusion bonds; thereafter
every SkipEvery atom is added.
The
closed argument specifies whether the chain
is to be closed into a circle (if not zero) or not
(if zero). To close the chain, one Bonds
interaction, two Angles interactions and
three Torsions interactions are
added.
The
getchaincoords() method initialize the coordinates
and returns the coordinate Atom Vector.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
getchaincoords
|
1
|
Atom
Vector
|
|
Argument
|
Type
|
Preset
Value
|
|
arcfile
|
string
|
(blank
string) ''
|
The
arcfile argument specifies the name of an
archive file if it is not a blank string. The
starting coordinates (the Coordinates attribute of
the Model) are read from this file. The default
setting for this argument is the blank string which
means that random coordinates will be generated as
starting coordinates. This is of two varieties. If
closed is zero, then the generated
coordinates are that of a more-or-less straight
line. If closed is not zero, then the generated
coordinates are that for a more-or-less flat
circle. The coordinate Atom Vector is
returned.
The
closechain() method closes out the current chain.
At the completion of this method, the startchain()
method can be called to start a new
chain.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
closechain
|
1
|
-
|
|
Argument
|
Type
|
Preset
Value
|
|
C
|
Atom
Vector
|
-
|
The
C argument specifies an Atom Vector. This
and the CHAIN attribute are saved in an assembly
list and the class is prepared for another chain.
(The assembly list is processed by the finish()
method from the FFA class.)
Functions
The
AtomList()
function returns a list of atom AtomMaps for chain
atoms that are found in the specified AtomMap and
in the descendants.
|
Function
Name
|
Number
of Arguments
|
Return
Value
|
|
AtomList
|
1
|
Tuple
of atom AtomMap
|
|
Argument
|
Type
|
Preset
Value
|
|
atomap
|
AtomMap
|
-
|
The
list of AtomMaps contains chain atoms, i.e., atoms
whose name match a pattern defined in this module:
the first character is anything except a digit, the
second character is always a tilde '~' and the rest
of the name is entirely a number. Non-chain atoms
should not be given a name that fits this pattern,
or they will be mistaken for chain atoms. The
number corresponds to the sequence order and the
list is sorted according to this number.
If
the atomap argument encompasses only a part
of a chain, the returned list will contain
fragments of the chain. The list will contain
discontinuous fragments but it will still be
sorted. If the atomap argument encompasses
more than one chain, the returned list will contain
the atoms of more than one chain. Since the list is
sorted by sequence number, the chains will be
interleaved. It is possible to untangle the chains,
for example, by sorting the list by atom number,
but it is easier to specify an argument that
encompasses only one chain to begin
with.
The
AtomNumberList()
function returns a list of atom numbers for chain
atoms that are found in the specified AtomMap and
in the descendants.
|
Function
Name
|
Number
of Arguments
|
Return
Value
|
|
AtomNumberList
|
1
|
Tuple
of integers
|
|
Argument
|
Type
|
Preset
Value
|
|
atomap
|
AtomMap
|
-
|
This
function first calls AtomList()
to obtain a list of atoms, and then returns a list
containing the corresponding atom
numbers.
|