|
Two
mapping methods are defined: the length operator
and subscripting. A third mapping method,
assignment to a subscript is not
implemented.
The Python length function
len(),
returns the total number of
AtomGroup
objects contained in the target and the count
includes the target node itself. The is equal to
the value of the numnames
attribute. From the concrete example:
>>> print len( Top ), "-----", Top.numnames
26 ----- 26
>>>
|
The subscript operation can be applied to an
AtomGroup
object. This takes the form of
AG[pathname] where AG
is an AtomGroup
object and pathname is a string indicating
the path to the destination node. This result of
this operation is the AtomGroup
object pointing to the desired node.
There
are very few restrictions for node names. Node
names must not be blank, except for the top node
which must have a blank node name. Node names are
case-sensitive and may contain any characters
(including non-printing ones) except for three
characters. The forbidden characters are the colon
":", the forward slash "/" and the backslash "\".
Node names may not be exactly the following: "^",
"+" and "-", but a node name may contain these
characters.
The
pathname is a concatenation of the names of the
nodes leading to the destination, with each
intermediate pair of node names separated with the
colon ":". A pathname may terminate in a colon
which indicates that the pathname points to a
Group. A pathname may start with a colon which
means that the pathname is absolute; that it starts
from the top of the hierarchy. A pathname that does
not start with a colon is assumed to be relative;
it is assumed to start from the target node. The
absolute pathname of an
AtomGroup
object can be retrieved from the
pathname
data attribute.
In
the concrete example, we created a hierarchy and
saved the object representing each node into
variables. The top node is saved in a variable
called Top, Groups are saved in variables
with the name beginning with the uppercase G
followed by the node name. Similarly, Atom objects
are saved in variables with the name beginning with
the uppercase letter A. Taking the Atom at
the lower left corner with the node named "a4",
there are many ways to write the pathname of this
object. The absolute pathname starts from the top
of the hierarchy and would start with the colon.
Thus, Top[':b1:b2:a3:a4']. In the
example, we use the Python
is
operator to show that the result of the
subscripting operation is exactly the same as the
object pointed to by the variable Aa4. (The
result of the operation is 1 or true.) The second
example illustrates the use of a relative pathname.
We can subscript the "b2" Group and write a
pathname starting without a colon. Thus,
Gb2['a3:a4']. This again is exactly
the object pointing to the Atom "a4". In the third
example, we show that in writing an absolute
pathname, the target Group (Gb2) is
immaterial.
>>> Top[':b1:b2:a3:a4'] is Aa4
1
>>> Gb2['a3:a4'] is Aa4
1
>>> Gb2[':b1:b2:a3:a4'] is Aa4
1
|
The
components of the pathname may include the
forbidden node names; "^", "+" and "-". These names
have special meanings. "^" stands for the parent
node. "-" stands for the preceding node and "+"
stands for the succeeding node. Thus:
>>> Aa4['^:^:^:^:'] is Top
1
>>>
|
Starting
from the Atom "a4", i.e., the variable Aa4,
the first caret yields the parent or the Group
"a3". With four carets we reach the top of the
hierarchy which is compared with the variable
Top which points to this object. Notice the
final colon. It is correct but is not really
necessary.
The
following example shows the use of the "+" and "-"
special node names:
>>> Aa4["+"] is Ab4, Ab4['-'] is Aa4
(1, 1)
>>>
|
We
can use combinations of these names to reach any
part of the hierarchy. The following example uses
an unnecessarily complicated path:
>>> Ab4["^:+:+:+:d4:-"] is Ac4
1
>>>
|
A
pathname is incorrect if: a component name is blank
or illegal, a component name does not correspond to
an existing node, there is no preceding node
referenced by the "-" special node name, there is
no succeeding node referenced by the "+' special
node name, there is no parent referenced by the "^"
special node name and if the pathname for an Atom
ends with a colon.
Normally,
while a hierarchy is being built, we save each
Group to a variable. This makes it easier to fill
these Groups. On the other hand, we would rarely
need to deal with an Atom once it is added so there
is less of a need to save an Atom object in a
variable. Once a hierarchy is built there is no
need to save all the variables to every Group or
Atom node. However we must still save the variable
containing the top of the hierarchy. We can then
reach any point in the hierarchy by subscripting
the variable containing the top of the
hierarchy.
Since
the subscripting of an
AtomGroup
object returns another
AtomGroup
object, we can apply the subscripting operation
multiple times. Thus, we can write the very first
example on this page in another way.
>>> Top["b1"]["b2"]["a3"]["a4"] is Aa4
1
>>>
|
It
must be remembered that
AtomGroup
objects are indexed by strings. It is a common
mistake to leave out the quotation marks. The
following example shows that without the quotation
mark, the index is interpreted as a variable.
Fortunately the variable contains a string with a
proper pathname.
>>> pathtoa4 = ":b1:b2:a3:a4"
>>> Top[pathtoa4] is Aa4
1
>>>
|
Finally,
since subscripting an AtomGroup
object yields another AtomGroup
object we can apply a method to a subscripted
object:
>>> print Aa4
---+a4 2:10 1:0 -1:-1 0
>>> Top[":b1:b2:a3:a4"].modify( mass = 12, charge = -0.3 )
>>> print Aa4
---+a4 2:10 12:-0.3 -1:-1 0
>>>
|
The
modify()
method is applied to the subscripted object. We
print the object before and after the
modification.
|