## jmol-users

 [Jmol-users] 11.1.15 molecular math Part II -- data types] From: Bob Hanson - 2007-02-27 21:45:15 ```Jmol Users -- initial documentation for new 11.1.15 capabilities are given here. Part II. USING VARIABLES IN JMOL ----------------------- The standard way of defining selection sets is still in place. "@x" is the same as "define x" at the beginning of a command: @x oxygen and atomno < 3;select x define atoms1 within(hkl,{1 1 1}); center atoms1 In addition, one still can name objects that are drawn with DRAW, ISOSURFACE, LCAOCARTOON, MO, and PMESH: draw line1 {atomno=1} {atomno=2} draw plane1 PLANE PERP line1\$ But now we have nine data types: 1. atom expressions 2. bond expressions 3. booleans 4. integers 5. decimal numbers 6. strings 7. points in space 8. planes in space 9. named objects All commands can now use the same syntax in relation to atom/bond sets, points, planes, and other objects. The recommended syntax will be: 1. ATOM EXPRESSIONS ------------------- {atom expression} {atom expression}[n] # selects only item n {atom expression}[n][m] # selects items n through m ({i j k:l}) # OVERALL atom indices, starting with 0 select { (oxygen or atomno < 3) and molecule=1 } center {oxygen}[3] draw line1 {oxygen}[1] {oxygen}[2] select ({0:8 10 12}) connect {oxygen}[1] {oxygen}[2] double measure {carbon}[3] {carbon}[4] "%a1--%a2 %VALUE %UNITS" Note: No use of comma as OR is allowed within braces. You may use commas in coordinates: x = {1,2,3} but the Chime method of addressing residues as select 1,2,3 is not allowed in this new syntax. You can still use that old syntax, but if you use the new syntax, you must use OR: select {1 or 2 or 3} This is important in terms of distinguishing between: center {1, 2, 3} # the coordinate point {1.0 2.0 3.0} center {1 or 2 or 3} # the first three residues or select within(3.0, {1, 2, 3}) select within(3.0, {1 or 2 or 3}) I would suggest that use of comma in any of these situattions be DEPRECATED. Comma should be used only between parameters in a function: select within(3.0, {1 2 3}) just reads a lot better. 2. BOND EXPRESSIONS (new) ------------------------- One of the really new things here is the ability to address bonds and sets of bonds. connected(dMin, dMax, "type",{atoms1},{atoms2}) # like the connect command, a list of bonds {atom expression}.bonds # specifically the bonds associated with these atoms {atom expression}.bonds[2] # specifically the second of these [{i j k:l}] # OVERALL atom indices, starting with 0 The .bonds modifier operates based on the setting of set BONDMODE OR/AND. The connected() function returns a set of bonds. This can be used in the SELECT command to select specific bonds: x = {oxygen or carbon}.bonds.ident; message %{x} select connected(1.2,1.3,{oxygen},{carbon}); connect double red; select [{0:10}]; color green; wireframe 0.10 3. BOOLEANS ----------- Just standard operating procedures here. There are some nuances of mixed type that I won't get into here. moreOx = ({oxygen} > 2) haveChain = (substructure("[CH2][CH2][CH2]") > 0); 4. INTEGERS (new) ----------------- x = (3 + 5) * 8 # 64 x = 3 / 2 # 1 x = {oxygen} + {nitrogen} x = {carbon} / 2 ringCount = ( 2 * {_C} + {_N} + 2 - {_H} ) / 2.0 - connected("double")/2 - connected("triple") 5. DECIMAL NUMBERS (new) ------------------------ x = 3.50 x = 3.50E-3 x = {carbon} / 2.0 6. STRING PARAMETERS -------------------- "in quotes" select within(1.0,3.0, "single",{oxygen},{carbon}) select within("AGGGA") x = "this number of oxygen atoms is " + {oxygen}.size Note that there is automatic conversion of string numbers to actual numbers based on left-preference: x = 3 + "3.5" # 6 x = 3.2 + "3.5" # 6.7 but: x = "3.5" + 3.2 # "3.53.2" 7. POINTS IN SPACE ------------------ {x y z} # cartesian coordinates {i/j k/l m/n} # fractional coordinates Coordinates can be given a integers, reals, or fractions. center {0 0 0} draw line {2.0 3.0 5.0} {C5} unitcell {1/2 1/2 1/2} 8. PLANES IN SPACE ------------------ {a b c d} # standard format -- ax + by + cz + d = 0 hkl {h k l} # Miller indices xy, xz, yz # in context, of course! x=?, y=?, z=? # where ? is some number mo 3 PLANE xy isosurface plane1 PLANE {1 1 1 0} isosurface plane2 HKL {2 1 0} isosurface plane3 PLANE xy 9. DEFINED VARIABLES -------------------- In math, just use the variable name: x = 3 y = x + 5 select {oxygen}[x] If x is an atom or bond set, add "_set" to the name to address the set itself: x = {oxygen} select {x_set or nitrogen} x = {carbon}.bonds or connected(1.2,1.5,{_O},{_C}) connect {x_set} double color {x_set} white; wireframe 0.02 In addition, in just about any place in any command, a parameter can be replaced by variable by prefixing the variable name with an @ sign: bradius = 0.5 select *;wireframe @bradius This does not apply to strings: x="testing"; echo "this is my @x string" echos just "this is my @x string". But there are two ways around this limitation. First, you can define a variable and just use it: x = "testing" y = "this is my "+ x + " string" echo @y echos "this is my testing string" In addition, we have; message @x label @x etc. The second method is to use %{x} in a message or echo (not a label). This substitutes the value of x at that position in the label and allows for a more general introduction of anything that can be evaluated: message there are %{{oxygen}.size} oxygen atoms. Note that for echo text, which might be showing in the applet window, the values are DYNAMIC. Here's a pretty strange script: load caffeine.xyz set echo top left echo %{{oxygen}[1].distance({oxygen}[2])} message _here; if ({oxygen}[1].distance({oxygen}[2]) > 0.1) select {oxygen}[1] if ({oxygen}[1].x > {oxygen}[2].x) translateSelected {-0.1 0 0} else translateSelected {0.1 0 0} endif if ({oxygen}[1].y > {oxygen}[2].y) translateSelected {0 -0.1 0} else translateSelected {0 0.1 0} endif if ({oxygen}[1].z > {oxygen}[2].z) translateSelected {0 0 -0.1} else translateSelected {0 0 0.1} endif refresh goto _here endif echo Contact! 10. NAMED OBJECTS (as in 11.0) ------------------------------ Named objects are addressed using \$ before the name: draw line1 {_O}[1] {_O}[2] draw line2 PERP \$line1 center \$line1 ---------------------------- Bob Hanson ```
 Re: [Jmol-users] 11.1.15 molecular math Part III -- .modifiers From: Bob Hanson - 2007-03-01 04:40:43 ```Jmol Users -- initial documentation for new 11.1.15 capabilities are given here. Part III. The new syntax for Jmol scripting "molecular math" allows selection of sets of atoms and bonds using {...}. By itself, this is not particularly useful. Yes, you can "save" sets of atoms for later use, and you can know how many atoms or bonds are there. But the real power of this syntax comes from what you can do with it on the back end, with the "." operator, which I will call the "modifier" operator. First, a few practical examples; then the full list. Note that these modifiers cannot be used in the SELECT command. They are specifically for doing operations on the resultant selections. Basically, you can think of {....} itself as a localized "select" that is used as a basis for the modifiers. Examples only: x = {C10}.ident # the identity of C10 in a standard format x = {C*}.size # the number of atoms with names starting with C x = {*}.bondcount # the average bond count x = {35}.structure # the structure of residue 35 (turn = 1, sheet = 2, helix = 3, unspecified = 0) set bondmode OR;x = {C10}.bonds #the bonds to carbon 10 Here's the full list, sorted by the TYPE of variable they operate on (before the ".") and, within that grouping, the type of return value: ATOM SETS --------- integer: .atomID .atomIndex .atomno .bondcount .elemno .element .file .formalCharge .groupID .model .molecule .occupancy .polymerLength .resno .site .size .structure .symop decimal: .atomX .atomY .atomZ .distance() .radius .partialCharge .phi .psi .surfacedistance .temperature .x .y .z string: .ident .label() point: .xyz set of atoms: .max .min set of bonds: .bonds Many of these are the same as the atom properties that can be used in the SELECT command: select atomno < 3 and atomX > 4.0 x = {atomno < 3} y = {atomX > 4.0} All "." operators operate by measuring a quantity for each atom individually in the atom set. A few are new: .distance(x) the distance in Angstroms to point x x can be anything that can be evaluated to be a point or atom set center: d = {molecule=1}.distance({0 0 0}) gives the AVERAGE distance of the atoms in molecule 1 to the origin. d = {molecule=1}.distance({molecule = 2}) gives the AVERAGE distance of the atoms in molecule 1 to the CENTER of molecule 2. Note that this different from d = {molecule=2}.distance({molecule = 1}) which is different from the following, which gives a center-to-center distance: d = distance({molecule=1}, {molecule=2}) .x .y .z same as .atomX .atomY .atomZ .size just gives the overall count of atoms in the set .min and .max These two modifiers return atom sets. They are shortcuts to the first and last elements of the set. They are used in a variety of contexts. x = {oxygen}.min # the first oxygen atom, same as {oxygen}[1] x = {oxygen}.max # the last oxygen atom, same as {oxygen}[{oxygen}] .ident and .label("formatString") These two modifiers return string data. ".ident" delivers the default identity label for atoms .label("format") delivers a label based on the format string. Mostly this is the format string used for all labels in the LABEL command, but with a couple of special options. %# is the index starting with 1 FOR THIS SET OF ATOMS. So, say you have a model that has several molecules in it. Then, for example, if you used: x = {molecule=1}.label("%# %a") You would get a list that looks like this: 1 C12 2 C13 3 H33 etc. The first line will start with 1 regardless of the actual atom number. The other special character is %D, which is very special. It only makes sense in a very specific bond context, discussed below. For example, XYZ file format for the selected atoms is simply: data = "" + {selected}.size + "\n\n"+{selected}.label("%-2e %10.5x %10.5y %10.5z") That is, the number of atoms, a blank line, and then one line for each atom, consisting of the element symbol, x, y, and z coordinates. The list generated is a new-line character-separated set of information. .xyz returns the AVERAGE position as a point. x = {molecule=1}.xyz; y = {molecule=2}.xyz; draw line1 @x @y BOND SETS --------- Bond sets created using .bonds on an atom set, from the connected(dMin, dMax...) function, or by use of an explicit bond selector of the format [{...}]. integer .size decimal .length string .ident .label() atom set .atoms bond set .min .max .size just returns the number of bonds in the set. .length returns the AVERAGE length of the bond. .ident and .label("formatString") return formatted strings. The trick here is that because bonds are assocated with atoms, a bond set retains information about these atoms. All the atom properties are available, as for atom format strings. One simply adds "1" or "2" after the format code to indicate which atom is of interest. In addition, the special codes %D1 and %D2 give the index of the atom IN THIS SET OF ATOMS. In addition, the two keywords %ORDER and %LENGTH can be used. For example, MOL file format is: x = "line1\nline2\nline3\n" +(""+{selected}.size)%-3+(""+{selected}.bonds.size)%-3 + " 0 0 0\n" + {selected}.labels("%10.4x%10.4y%10.4z %-2e 0 0 0 0 0") + {selected}.bonds.labels("%3D1%3D2%3ORDER 0 0 0") String modifiers ---------------- x.find("...") finds the location of "..." in the string (or strng equivalent) of x. x.lines produces a set of strings based on new-line characters in the string x.size returns the number of characters in the string. String arrays ------------- x.lines actually creates an array of strings. These can also be the basis for .find("...") and .size, in which case .find() returns the set of lines containing the found information, and .size returns the number of lines. String arrays can also be created using the following syntax: x = ["line1", "line2", "line3"] y = x + ["line4"] + {*}.ident.lines Modifiers of modifiers ---------------------- You can string any number of modifiers together: x = {*}.bonds.ident.lines.find("C3") xMax = {*}.bonds.length.max theLongestBond = {*}.bonds.label("%a1 %a2 %LENGTH").lines.find(xMax) nMolecules = {*}.molecule.max Note that, in particular, "max" and "min" can be used as special modifiers that direct Jmol to return something other than the average value for any atom property or for bond length. Bob ```