|
The
Atoms
module provides utilities to deal with lists of
atom AtomMaps.
The
Atoms
module is located in Yup.Tools. Thus, the required
import statement is some variant of:
from
Yup.Tools.Atoms import
*.
All
the following functions except the last return a
flat list of atom AtomMaps. The AtomMaps are
obtained from the specified parent AtomMap and
recursively from any group AtomMaps within the
parent AtomMap. The AtomMap is traversed
depth-first and from left to right starting from
the parent AtomMap. Thus, the selected atom
AtomMaps will be in atom index (or atom number)
order. The functions differ only in the selection
criteria which are summarized below:
|
EveryAtom()
|
All
atoms are selected.
|
|
MatchedAtoms()
|
Atoms
whose name match the given atom name
pattern are selected.
|
|
MatchedGroups()
|
All
atoms whose parent AtomMap have names that
match the given group pattern are
selected.
|
|
MatchedGroupAtoms()
|
Atoms
whose name match the given atom name
pattern and whose parent AtomMap have
names that match the given group pattern
are selected.
|
|
MaskedAtoms()
|
This
function operates in one of two modes: (1)
Atoms that have mask values that are in
the supplied inclusion list are selected.
(2) Atoms that have mask values that are
not in the supplied exclusion list are
selected.
|
|
AtomNumbers()
|
Given
a list of atom AtomMaps, returns a list
with the corresponding atom indices (also
known as atom numbers).
|
The
EveryAtom()
function searches in the given parent AtomMap and
recursively in any group AtomMaps. The search is
depth-first from left to right. Any atom AtomMap
that is found is appended to a list which is then
returned as a tuple. Thus, the atoms are in atom
index (or atom number) order.
|
Function
Name
|
Number
of Arguments
|
Return
Value
|
|
EveryAtom
|
1
|
Tuple
of atom AtomMap
|
|
Argument
|
Type
|
Preset
Value
|
|
parent
|
AtomMap
|
-
|
If
parent is an atom AtomMap, the return value
is None.
The
MatchedAtoms()
function carries out the same search as the
EveryAtom
function. However, only atom AtomMaps with names
that match the given pattern are added to the
list.
|
Function
Name
|
Number
of Arguments
|
Return
Value
|
|
MatchedAtoms
|
2
|
Tuple
of atom AtomMap
|
|
Argument
|
Type
|
Preset
Value
|
|
parent
|
AtomMap
|
-
|
|
pattern
|
string
|
r'.+'
|
If
the parent argument contains an atom
AtomMap, the return value is None.
The
preset value of the pattern argument is a
raw string that matches a non-empty string of any
character except for newline. This argument must
contain a regular expression and should most likely
be expressed as a raw string.
The
MatchedGroups()
function carries out the same search as the
EveryAtom
function. However, all atom AtomMaps that occur in
any group with names that match the given pattern
are added to the list.
|
Function
Name
|
Number
of Arguments
|
Return
Value
|
|
MatchedGroups
|
2
|
Tuple
of atom AtomMap
|
|
Argument
|
Type
|
Preset
Value
|
|
parent
|
AtomMap
|
-
|
|
pattern
|
string
|
r'.+'
|
If
the parent argument contains an atom
AtomMap, the return value is None.
The
preset value of the pattern argument is a
raw string that matches a non-empty string of any
character except for newline. This argument must
contain a regular expression and should most likely
be expressed as a raw string.
Note
that this function returns atom AtomMaps and not
group AtomMaps contrary to what the function name
may imply.
The
MatchedGroupAtoms()
function carries out the same search as the
EveryAtom
function. However, only atom AtomMaps with names
that match the given atom pattern and whose
parents' names match the given group pattern are
added to the list.
|
Function
Name
|
Number
of Arguments
|
Return
Value
|
|
MatchedGroupAtoms
|
3
|
Tuple
of atom AtomMap
|
|
Argument
|
Type
|
Preset
Value
|
|
parent
|
AtomMap
|
-
|
|
gpattern
|
string
|
r'.+'
|
|
apattern
|
string
|
r'.+'
|
If
the parent argument contains an atom
AtomMap, the return value is None.
The
preset values of the gpattern and
apattern arguments are both raw strings that
match a non-empty string of any character except
for newline. These arguments must contain regular
expressions and should most likely be expressed as
raw strings. The returned list contains atoms whose
names match apattern and the parents' names
match gpattern.
The
MaskedAtoms()
function carries out the same search as the
EveryAtom
function. However, only atom AtomMaps with mask
values that occur in the given list of inclusion
masks, or do not occur in a given exclusion list,
are added to the list. Either the inclusion list or
the exclusion list must be supplied. It is an error
to supply neither or both.
|
Function
Name
|
Number
of Arguments
|
Return
Value
|
|
MaskedAtoms
|
3
|
Tuple
of atom AtomMap
|
|
Argument
|
Type
|
Preset
Value
|
|
parent
|
AtomMap
|
-
|
|
include
|
Tuple
of Short Integers
|
None
|
|
exclude
|
Tuple
of Short Integers
|
None
|
If
the parent argument contains an atom
AtomMap, the return value is None.
The
preset value of the include and
exclude arguments are both None. Exactly one
of these arguments must be specified and as a tuple
of short integers.
If
include is specified, exclude must be
left at its default value of None. Atoms that have
mask values that can be found in the include
list will be selected.
If
exclude is specified, include must be
left at its default value of None. Atoms that have
mask values that do not occur in the exclude
list will be selected.
The
AtomNumbers()
function translates a list of atom AtomMaps to a
list of corresponding atom numbers.
|
Method
Name
|
Number
of Arguments
|
Return
Value
|
|
AtomNumbers
|
1
|
Tuple
of integers
|
|
Argument
|
Type
|
Preset
Value
|
|
atomlist
|
Tuple
of atom AtomMap
|
-
|
|