The
surface
command is the generic command used to manipulate surface patches. The syntax of this command follows the standard schema of
command/subcommand/majorhandle/minorlabel
.
Surface properties begin with an O_, not S_ (which is reserved for sigma systems). The mnemonic behind this is that these are Oberfläche properties (German for surface).
Pseudo surface system labels first , last and random are special values, which select the first surface patch in the surface patch list, the last, or a random patch.
surface get $ehandle 1 O_COLOR
This is the list of officially supported subcommands:
surface append ehandle label ?property value?...
o.append({?property:value,?...})
o.append(?property,value,?...)
Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.
surface append $ehandle 1 O_ID “_accessible”
surface atoms ehandle label ?filterset? ?filtermode?
o.atoms(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the atoms in the surface patch. This is explained in more detail in the section about object cross-references. Note that patches may not be associated with any atom.
surface atoms $ehandle 1 carbon
returns the labels of the carbon atoms associated with the patch.
surface bonds ehandle label ?filterset? ?filtermode?
o.bonds(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the bonds between the atoms associated with a patch. This is explained in more detail in the section about object cross-references. In many cases, patches are associated with one or no atom. In that case, there are no bonds to retrieve.
surface bonds $ehandle 1
surface bonds $ehandle 1 {1 doublebond triplebond} count
The first example returns all labels of the bonds between the atoms in patch one. The second example returns the number of double or triple bonds between the atoms in the patch.
surface create ehandle ?atom/atomlist?...
Surface(eref,?aref/arefsequence/alabel?,...)
Surface(aref,...)
Surface.Create(eref,?aref/arefsequence/alabel?,...)
Surface.Create(aref,...)
Define a new surface patch from an atom set, which may be empty. A new patch is always created, even if one with the same atoms already exists. Adding a new patch invalidates properties which are sensitive to patch set changes.
The command returns the label or reference of the new patch.
surface defined ehandle label property
s.defined(property)
This command checks whether a property is defined for the surface patch. This is explained in more detail in the section about property validity checking. Note that this is not a check for the presence of property data! The
ens valid
command is used for this purpose.
surface delete ehandle ?label?...
surface delete ehandle all
o.delete()
Surface.Delete(eref,?oref/olabel/orefsequence?,...)
Surface.Delete(oref,...)
Surface.Delete(eref,“all”)
This command removes surface patches from the ensemble patch set. A surface property invalidation event is generated and thus the command may indirectly change the ensemble data.
surface dget ehandle label propertylist ?filterset? ?parameterdict?
o.dget(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
surface get
command. The difference between
surface get
and
surface dget
is that the latter does not attempt computation of property data, but rather initializes the property values to the default and returns that default if the data is not yet available. For data already present,
surface get
and
surface dget
are equivalent.
surface exists ehandle label ?filterlist?
o.exists(?filters=?)
Surface.Exists(eref,label,?filters=?)
Check whether this patch exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns boolean 0 if the patch does not exist, or fails the filter, and 1 in case of successful testing.
surface exists $ehandle 99
surface expr ehandle label expression
o.expr(expression)
Compute a standard SQL -style property expression for the surface patch. This is explained in detail in the chapter on property expressions.
surface fill ehandle label ?property value?...
o.fill({property:value,...})
o.fill(?property,value?,...)
Standard data manipulation command for setting data, ignoring possible mismatches between the lengths of the lists of objects associated with the property and the value list. It is explained in more detail in the section about setting property data.
surface filter ehandle label filterlist
s.filter(filters)
Check whether a surface patch passes a filter list. The return value is boolean 1 for success and 0 for failure.
surface filter $ehandle 1 [list carbon doublebond]
checks whether patch is associated with one or more carbon atoms and one or more double bonds. The double bond does not need to contain a carbon atom.
surface get ehandle label propertylist ?filterset? ?parameterdict?
o.get(property=,?filters=?,?parameters=?)
o[property]
o.property
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
surface groups ehandle label ?filterset? ?filtermode?
o.groups(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the groups the surface patch overlaps with. This is explained in more detail in the section about object cross-references. An overlap between a surface patch and a group is established when there are common atoms which are contained in both objects.
surface groups $ehandle 1
surface index ehandle label
o.index()
Get the index of the surface patch. The index is the position in the patch set of the ensemble. The first position is index 0.
surface index $ehandle 99
surface jget ehandle label propertylist ?filterset? ?parameterdict?
o.jget(property=,?filters=?,?parameters=?)
This is a variant of
surface get
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
surface jnew ehandle label propertylist ?filterset? ?parameterdict?
o.jnew(property=,?filters=?,?parameters=?)
This is a variant of
surface new
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
surface jshow ehandle label propertylist ?filterset? ?parameterdict?
o.jshow(property=,?filters=?,?parameters=?)
This is a variant of
surface show
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
surface local ehandle label propertylist ?filterset? ?parameterdict?
o.local(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading and recalculating object data. It is explained in more detail in the section about retrieving property data.
surface mols ehandle label ?filterset? ?filtermode?
o.mols(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels of the molecules a patch is contained in. This is explained in more detail in the section about object cross-references. It is possible to have patches which span more than one molecule. Patches which are not associated with any atom also have no molecule association.
surface new ehandle label propertylist ?filterset? ?parameterdict?
o.new(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
The difference between
surface get
and
surface new
is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.
surface nget ehandle label propertylist ?filterset? ?parameterdict?
o.nget(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
surface get
command. The difference between
surface get
and
surface nget
is that the latter always returns numeric data, even if symbolic names for the values are available.
surface pis ehandle label ?filterset? ?filtermode?
o.pis(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the π systems the surface patch overlaps with. This is explained in more detail in the section about object cross-references.
surface pis $ehandle 1
Surface.Ref(eref,identifier)
Python
only method to get a surface reference. See
surface surface
command.
surface rings ehandle label ?filterset? ?filtermode?
o.rings(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels of the rings or references the surface patch is associated with. This is explained in more detail in the section about object cross-references. Rings which only partially overlap with the patch are included.
surface rings $ehandle 1
surface rings $ehandle 1 [list heterocycle aroring]
The first example returns the labels of all rings the patch overlaps with. If the patch does not overlap with any ring, an empty list is returned. Only labels of rings in the SSSR or ESSSR set are returned, even if the currently computed ring set is larger. The second example filters the rings - only heteroaromatic rings are reported.
surface ringsystems ehandle label ?filterset? ?filtermode?
o.ringsystems(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the ringsystems the surface patch overlaps with. This is explained in more detail in the section about object cross-references.
surface set ehandle label ?property value?...
o.set(?property,value?,...)
o.set({property:value,...})
o.property = value
o[property] = value
Standard data manipulation command. It is explained in more detail in the section about setting property data.
surface show ehandle label propertylist ?filterset? ?parameterdict?
o.show(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
surface get
command. The difference between
surface get
and
surface show
is that the latter does not attempt computation of property data, but raises an error if the data is not present and valid. For data already present,
surface get
and
surface show
are equivalent.
surface sigmas ehandle label ?filterset? ?filtermode?
o.sigmas(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the σ systems the surface patch overlaps with. This is explained in more detail in the section about object cross-references.
surface sigmas $ehandle 1
σ systems are a rather exotic feature and not commonly used. These are essentially descriptions of bonding interactions which use s orbitals, such as normal, covalent single bonds, or the central bond in multiple bonds. A simple double bond is described with one σ system and one π system in this representation.
surface sqldget ehandle label propertylist ?filterset? ?parameterdict?
o.sqldget(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
surface get
command. The differences between
surface get
and
surface sqldget
are that the latter does not attempt computation of property data, but initializes the property value to the default and returns that default, if the data is not present and valid; and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
surface sqlget ehandle label propertylist ?filterset? ?parameterdict?
o.sqlget(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the s
urface get
command. The difference between
surface get
and
surface sqlget
is that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
surface sqlnew ehandle label propertylist ?filterset? ?parameterdict?
o.sqlnew(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
surface get
command. The differences between
surface get
and
surface sqlnew
are that the latter forces re-computation of the property data, and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
surface sqlshow ehandle label propertylist ?filterset? ?parameterdict?
o.sqlshow(property=,?filters=?,?parameters=?)
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
surface get
command. The differences between
surface get
and
surface sqlshow
are that the latter does not attempt computation of property data, but raises an error if the data is not present and valid, and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
surface subcommands
dir(Surface)
Lists all subcommands of the
surface
command. Note that this command does not require an ensemble handle, nor a surface label.
surface surface ehandle label
Surface.Ref(eref,identifer)
Standard cross-referencing command to obtain the label or reference of the surface patch as stored in property O_LABEL . This is explained in more detail in the section about object cross-references.
surface surface $ehandle #0
returns the label of the first surface patch of the ensemble patch set.