|
In general, commands in Jmol start with a command word and continue with a set of parameters separated by white space and terminated by an end of line character or a semicolon, much as in JavaScript. Similar to JavaScript, a backslash just prior to the end of a line indicates a line continuation, and commands can "wrap" to the next line in a JavaScript-like fashion. In general, any unclosed (, [, or { on a line indicates that the command continues on to the next line. In addition, with print and set, lines can continue just after or before a mathematical operator such as +, -, * or /. This results in a more natural line formatting, which has strong similarities to JavaScript. For example:
function processInfo(f, i) {
var pdbid = (i ? f[i] : f)
load @{"="+pdbid}
var molinfo = ({protein} == 0 ? "nonprotein"
: {protein and not *.ca} == 0 ? "alpha carbon model"
: {*}[0].model != {*}[1].model ? "multi-model"
: "OK")
if (molinfo != "OK") {
print pdbid+" "+molinfo;
return;
}
var chaincount = script("select protein; show chain").trim().lines.length
var helixcount = script("show structure").lines.find("HELIX").length
var sheetcount = script("show structure").lines.find("SHEET").length
print pdbid+" "+molinfo
+" "+{*.ca}.size
+" "+chaincount
+" "+helixcount
+" "+sheetcount
}
There are two basic Jmol command types -- "RasMol-like" commands (shown in bold face, above), such as load and select, and JavaScript-like "Jmol math" commands. The distinction between these two command types has to do with parameter order and variable replacement, as discussed below. The RasMol-like commands are characterized by a leading command word that is intrinsic to molecular systems, serving to load models, select atoms, measure distances, write data to files, etc. For the most part, order of parameters in the RasMol-like commands is not important. The command processor simply cycles through the keywords, looking for ones it recognizes. (That said, the more complicated commmands do have some aspects of order -- especially load, isosurface, and write. String parameters in these commands are generally quoted using single or double quotes. Some older RasMol-like commands in Jmol do not require any quotes, though.
JavaScript-like commands have a very different look, starting with a command word such as for or if or simply starting with a variable name as part of an assignment statement, as illustrated above. These commands should look quite familiar to anyone who has done any JavaScript programming. However, be advised, they are not JavaScript. Like JavaScript, strings in Jmol can be delimited by either single or double quotes. Jmol math, however, makes a distinction between integers and floating-point numbers. Jmol has several data types not found in JavaScript, making it more like Java itself in some ways. The "Jmol Math" language was written specifically for Jmol, with JavaScript in mind, and with the idea of extending the relatively limited capabilities of RasMol script with a a rich layer of features. Differences between Jmol and JavaScript are summarized below. In this document, Jmol math commands are introduced using UPPER CASE HEADINGS.
|
See also:
|
[Jmol Math] [Jmol Parameters] [atom expressions] [atom properties] [functions] case default echo for if message reset set set (misc) switch while undefined |
 top  search  index |
Jmol Variables
Examples of Variable Use
Indirect referencing and use of @
Global and Local Scope
Read-Only Variables
Jmol Math Variable Types
Differences Between Jmol Math and JavaScript
Jmol Quaternion Math
Operators and Operands
Operation Rules
|
Jmol incorporates a rich JavaScript-like math environment including multiple variable types and a wide variety of functions. This section of the documentation details the use of variables and the sorts of operations that are allowed with them.
Jmol Variables back
Variables may be assigned using standard mathematical expressions and used throughout Jmol in standard Java/JavaScirpt-like statements such as:
x = y + 3
for (var i = 1; i < 10; i++){...}
print x
In addition, the at-symbol, @, can be used in any Jmol-specific command (LOAD, SELECT, etc.) in order to switch into "math mode" temporarily to obtain a variable, as in
x = "ala or gly"; select @x
echo "@{'file=' + _modelFile}"
x = 0.2; wireframe @x
zoom @{x * 3}
Likewise, math expressions can temporarily switch into "atom select mode" using just { } without the @ sign:
x = {ala or cys}
print {*}.length
for(var i in {*}) { print i.label() }
Examples of Variable Use back
Variables may be combined with settings to adjust parameters:
x = bondModeOR; set bondModeOr @{!x}
set showBoundBox @{!showBoundBox}
Variables may be used to extract information from a model:
x = {carbon}.bonds.length.min
Variables may be used to introduce atom-related property data from external files into the model:
x = load("chargeData.txt");select 2.1;data "property_charges @x";select 2.1 and property_charges < 0.5
Variables may be inspected using print x, show x, or message @x where x is a variable name. You can use message or echo to transmit this information to the user or to the web page via a JavaScript callback function or use the Jmol.js function jmolEvaluate(). If using the Jmol stand-alone application or the signed applet, you can write a variable to a file using the write command. Variables and math expressions can be checked using the print command.
Standard C++/Java in-place assignments such as x++, x--, ++x, --x are allowed, along with assignments +=, -=, *=, /=, \= (integer division), |=, and &=.
Indirect referencing and use of @ back
Jmol math allows for one variable referencing the value contained in another variable. This is accomplished using the @ sign in a math context rather than an atom selection context. Thus, if y = 3 and x = "y", then print @x prints "3" because @x means "the value of the variable named by x" which in this case is y. The use of @ is summarized below:
| select @x | In implicit atom expression commands such as select, display, and delete in which x must represent an atom expression, either in the form of a string, x = "ala or cys", or as an actual expression, x = {ala or cys}. | | y = {@x} | Similarly, within selection mode within a math expression, to have a variable atom expression. | | select chain=@x | In an atom expression comparison, @ substitutes a variable's value directly. For example, select chain=X selects for chain X; x="A";select chain=@x selects for chain A. | | echo "model=@{_modelNumber}" | Specifically for the commands echo and hover, if a math expression is present, the text will be dynamically generated every time the screen is refreshed, thus automatically updating when variables are changed. | | load @x | In all other commands that accept parameters as any sort of variable parameter. | | y = @x | when x is a string, an indirect reference, with @x representing the contents of the variable named by x; when x is an array or associative array, carries out a deep copy of all elements and elements of elements. | | @36 | @ sign followed by a number n is a shortcut in any context for {atomno=n}. | | @@36 | @@ sign followed by a number n is a shortcut in any context for {atomno=n and thisModel}, returning the subset of atoms with this atom number that are in the current frame set as determined using with the frame or animation frames command. For example, model 3;select @@2 would be the same as select atomno=2 and model=3. | | @myGroups ala or cys | @ sign followed by a name in the context of a command is a substitute for the define command, which is an early Jmol syntax. In this case, "myGroups" is defined as "ala or cys", so we can now say select myGroups in place of select ala or cys. A difference between this usage and @myGroups, where myGroups is a Jmol Math variable, is that all definitions created with the DEFINE command are temporary definitions that will be deleted when a new model is loaded or appended. Such is not the case for Jmol Math variables. |
Users are cautioned to be careful using @, particularly because of indirect referencing and the need to switch into the proper mode before using a variable. The following statements probably will not do what you think they will do: select x; print @x; x = @y + 2.
The table below lists all JavaScript-like commands as well as the RasMol commands not requiring quotes.
| These JavaScript-like commands do not require @ with expressions. | CASE CATCH FOR IF/ELSEIF LOG PRINT PROMPT RETURN SWITCH THROW VAR WHILE | | These commands, many of which predate Jmol math, accept exactly one string parameter. For these specific commands, quotes are optional. The distinction with and without quotes in these cases only has to do with simple variable substitution. echo @x will echo the contents of variable x; echo "@x" will echo @x. (However, variable expressions, such as @{x + 3}, are processed in these cases even if quoted. | cd echo goto help hover javascript label message pause |
Global and Local Scope back
Variables in Jmol have one of two scopes -- global or local. Global variables hold values that need to persist across scripts or functions. Local variables override the values previously assigned to the same name for some limited extent. In general, variables defined in Jmol are global variables. Note that no variables are recorded in the state. It is good programming practice to define variables locally as much as possible, but there are times when global assignments are needed. Just be aware that any global variables created and not destroyed using the reset command consume memory and may slow script processing. The following rules govern the scope of local variables:
| applet localization | all variables in Jmol are localized to a specific applet. Note that this is not necessarily true for functions. Specifically, functions beginning with static_ are common to all non-Java applets. These static functions, though able to be used by any applet, will not share variables. | script localization
Variables defined using the keyword VAR within a script file that is read by the script command are localized to that script and scripts that that script calls. | var x = 30
var d = {atomno=1}.xyz.distance({atomno=2}.xyz) | function localization
The parameters of a function and any variables defined within a function using VAR are local to that function. The Jmol script on the right will print
a=1 b=2
testing now | a = "testing"; c = "now"
function checkX(a, b) {
var c = 15;
print "a="+a + " b=" + b
}
checkX(1,2)
print "" + a + " " + c | FOR/WHILE localization
Variables defined using VAR within the context of a FOR or WHILE loop will be local to that loop. The script on the right will print
5
6
7
3 |
x = 3
for (var x = 5; x < 8; x++) {
print x
}
print x | { ... } localization
Variables defined using VAR can be localized to a section of a script by bracketing that section of the script with { and }. This script will print
10
3 |
x = 3
{
var x = 10;print x
}
print x |
Read-Only Variables back
fome variables have preset meanings, as shown in the table below. A subset of these variables can be used in math expressions. If you create your own variables, their names must not begin with an underscore. Variables starting with underscore are defined by Jmol and can be used but not set in a script. To check the settings of all available read-only variables, use show _?. Read-only variables include:
| _animating | whether or not Jmol is currently running through the frames as a result of animation on or animation play (true or false) | | _animTimeSec | The time in seconds required for an animation to complete one cycle. | | _applet | whether or not Jmol is running as an applet | | _atomHovered | the overall atom index of the atom that was most recently hovered over (or -1) | | _atomPicked | the overall atom index of the atom that was most recently picked (or -1). Can be used, for example, with select atomIndex = _atomPicked | | _currentFileNumber | the number of the currently displayed file, starting with 1 (value will be 0 if more than one file is displayed) | | _currentModelNumberInFile | the number of the currently displayed model in its file (or 0 if more than one model is displayed) | | _depthPlane | The plane defining the back limit of the model for the current orientation and slabbing. See also _slabPlane | | _fileType | The file type of the most recently loaded file | | _firstFrame | The first frame in the current animation frame range expressed in x.y notation | | _frameID | A numerical frame number equal to 1000000 times the file number plus the model index in the file | | _height | the height of the applet or application window in pixels | | _lastFrame | The last frame in the current animation frame range expressed in x.y notation. | | _hoverLabel | Gives the general hover label set by hover command. | | _hoverEnabled | Indicates if hover is enabled or not. | | _loadPoint | a number indicating the load status, usually 3 indicating successful load, possibly 0 indicating load failure.
| | _M | a shortcut for getProperty("modelInfo").models[_modelindex+1], providing easy access to detailed information about just the current model
| | _memory | the amount of memory allocated to the applet or application | | _modelFile | the filename of the model (or "" if more than one model is displayed) | | _modelName | the name of the model (or "" if more than one model is displayed) | | _modelNumber | the current model number as a string in file.model notation (or "file1.model1 - file2.model2" if more than one model is currently displayed) | | _modelTitle | information from the file reader interpreted as a title | | _mouseAction | a number associated with the current mouse/key state | | _mouseModifiers | a number associated with the current key combination associated with the mouse | | _mouseX | the current X-position of the mouse | | _mouseY | the current Y-position of the mouse | | _multiTouchClient | indicates if Jmol is operating as a Sparsh-UI client and has connected with the Sparsh-UI server (possibly itself). | | _multiTouchServer | indicates whether Jmol is functioning as a Sparsh-UI server. (Requires a specialized Jmol Sparsh-UI driver) and has successfully connected to a multi-touch device. | | _navigating | TRUE if navigation is on | | _nProcessors | the number of available processors | | _picked | The set of atoms most recently picked. This buffer is cleared when the user clicks twice off the molecule. | | _pickedList | The _picked atoms as an ordered array. Thus, _pickedList[0] is the last-picked atom; _pickedList[-1] is the second-to-last-picked atom; _pickedList[-2][0] are the three last-picked atoms. | | _pickInfo | information about the last atom picked, including a description of the atom, its atom number, and its x y z coordinates. For example:
[GLN]25:A.O/2.1 #175 40.271 8.524 2.615 | | _signedApplet | whether or not Jmol is running as an signed applet | | _slabPlane | The plane defining the front limit of the model for the current orientation and slabbing. See also _depthPlane | | _spinning | whether or not the model is currently spinning (true or false). The _spinning variable can be used, for example, to toggle spinning on and off:
if (_spinning);spin off;else;spin on;endif; | | _useCommandThread | TRUE if Jmol is using an independent command thread. | | _version | the version of Jmol expressed as an integer: vvrrxxx for Jmol vv.rr.xxx. For example, for Jmol 11.2.38, _version = 1102038 | | _versionDate | the version of Jmol expressed in the form of 14.5.4_2016.04.03 2016-04-03 14:35 . | | _width | the width of the applet or application window in pixels |
Jmol Math Variable Types back
Jmol math allows for several distinct variable types, some of which are common types (boolean, integer, decimal, string, serial array, byte array, associative array, binary associative arrays), and some of which are special types of particular use in molecular calculations (point, plane, quaternion, 3x3 matrix, 4x4 matrix, atom bitset, bond bitset). Variable types may be combined in mathematical expressions. Array types may include any number of any combination of these data types. Examples include:
| array | Standard arrays in Jmol are created using x = [...] or x = array(...). For example:
xlist = array(true,3,3.5,"testing",{2.3,3.4,4.5});
xlist = [true,3,3.5,"testing",{2.3, 3.4, 4.5}]
xlist = [3 -3 5 -5]
Note that arrays may contain a mix of any variable type. Commas between elements are not required. The two methods of defining an array are slightly different. The array() function always defines an array, regardless of its contents. The a = [....] notation, on the other hand, will define a matrix, not an array, if the elements are numerical and the array is of the correct form (3 rows and 3 columns, or 4 rows and 4 columns).
Arrays are stored, saved, and manipulable as objects, and all array assignments are by reference, as for JavaScript and Java, meaning that if x = ["a", "b", [3, 4, 5]], and we assign y = x[3], then y is x[3], not a copy of it, and if we later assign y[4] = "new", then at x[3] = ["a", "b", [3, 4, 5], "new"] as well. The functions x.push(y) and x.pop() can be used to add and remove elements from a Jmol array.
The notation a[2][3] generally refers to the subarray consisting of the second and third elements of a. However, in the assignment context a[2][3] = ..., these numbers refer to the third element of the second element of the multidimensional array.
To specify a specific element of a multidimensional array in other contexts, you can use parentheses: print (a[2])[3] or, starting in Jmol 14.3.13, you can use "." separation to indicate nested array elements: print a[2].[3].
| | byte array | A byte array holds data in the form of 8-bit bytes. Starting with Jmol 14.2, byte arrays can be created from base64-encoded data using x = array(";base64,...") where "..." is base64-encoded data or loaded from a file using load(fileName, TRUE). When loaded from a file, the byte array takes the form of one or more entries in a "binary associative array" (below). A byte array x will give x.type = "byteArray". | | associative array | Associative arrays store information retrievable by string-based keys. The information may be any type, including another associative array. Empty associative arrays are created using x = {}. Reference or retrieval is accomplished one of three ways:
| arrayName["keyName"] | The guaranteed way to get a key is the same as JavaScript notation. If a key is absent, the empty string is returned. | | arrayName..keyName | Alternatively, wo consecutive periods can be used, provided the key is a simple alphanumeric quantity such as "key1" or "x". Keys can be chained: myData..atoms[1]..x | | arrayName.keyName | Finally, similarly to JavaScript and Java, one can use simple "dot" notation -- with just one caveate. In Jmol the three functions a.keys, a.size, and a.type return an array of keys, the number of keys, and the string "hash" for an associative array. If your array has those keys, you must use a..keys, a..size, or a..type, or a["keys"], a["size"], or a["type"], to access them. |
Thus,
x = {}
x.atoms = {visible}
x["file"] = _modelFile. The functions x.push(key,value) and x.pop(key) can be used to add and remove elements from a Jmol associate array .
Jmol's associative arrays are, strictly speaking, a superset of JSON arrays, consisting of a bracketed comma-separated list of key-value pairs, involving a key, a colon, and an expression. The key does not have to be quoted if it is a simple alphanumeric key such as "x" or "x2" and square brackets [...] are used rather than braces {...}. For example:
b = [test : 34, "my test": "OK"]
b.test = 100
b.test3 =["one", 3, 4, 5]
print b["my test"] + " -- " + ++b.test +" -- "+b.test3[1]
OK -- 101 -- one
show b
b = [ "my test":"OK","test":101,"test3":[ "one",3,4,5 ] ]
b -= "test3"
show b
b = ["test" : 101, "my test" : "OK"]
The key can always be quoted, as in JSON, and, as noted, an alternative syntax involving braces insead of brackets, as in JavaScript, can be used, in which case the key must be quoted. Note that an empty associative array must be created using {}, not [ ]. | | binary associative array | Jmol 14.2 introduces the binary associative array type. This data type is a form of associative array that allows data to be preserved as raw bytes. For example, image or zip file data can be saved in an array without need for translation to base64. Any associative array is a binary array if it contains the key "$_BINARY_$". The value of this key is never checked, but Jmol will then assume that all other values MAY be in byte form. (They can be any values, but if they are byte arrays, then they will be preserved as such.)
The three forms of binary associative arrays are given in the table below:
| keys | contents | write VAR | | $_BINARY_$, _DATA_ | generic binary data as a single byte array | binary file | | $_BINARY_$, (filenames) | byte arrays keyed by filename | ZIP file; created by x = write("ZIP") or x = write("Jmol") | | $_BINARY_$, _IMAGE_ , (filenames) | PNG image with associated files | PNGJ file, if created as such using x = write("PNGJ") |
Combined with Jmol's capability to read and write ZIP files, the manipulation of associative arrays allows Jmol scripts to read or create, modify, append to, and save ZIP files and PNGJ images as well as any binary data format. For example, the following script creates a ZIP file relating to the currently loaded structure:
a = {}
a.push("file.dat",show("file"))
a.push("state.spt",show("state"))
a.push"image.png", getProperty("image"))
a.push("$_BINARY_$",true)
write var a myfile.zip | | bitset | x = {atomno < 30};
x = ({0:28 45 56:62})
Atom bitsets specify a group of atoms in the overall collection (not just one model). Numbers are atom indices, which start with 0 and run through all atoms in all models. | | bondset | x = {atomno < 30}.bonds;
x = [{0:4 6 9:12}]
Bondsets specify groups of bonds in the overall collection. Numbers are bond indices, which start with 0 and go through all bonds in all models. There are only a few contexts in which bond bitsets can be used. Examples include:
color @{ {ala}.bonds } green; select [{3:300}]; color BONDS white; connect @{ {dna}.bonds } radius 0.1;. | | boolean | Boolean values include TRUE and FALSE. Case is not sensitive, so TRUE == True == true:
isOK = TRUE; if(isOK) { print "all is good" } | | decimal | averX_nm = {atomno < 10}.x * 100.0;
Decimal numbers in Jmol are stored as 32-bit floating-point values, with critical calculations carried out as 64-bit double values. | | integer | for (var i = 1; i < 10; i = i + 1){ print i }
| | 3x3 matrix | Rotation matrices in Jmol are indicated either as a 3-row, 3-column array or by 9 numbers set off by double brackets.
m = [[1.0 2.0 3.0],[4.0 5.0 6.0],[7.0 8.0 9.0]];
m = [[0.57010806 -0.0516641 0.8199437 0 -0.5407497 0.72776425 0.42183995 -0.6185197 -0.68387866 0.3869669]]
m = axisAngle({1 0 0},30)%-9
rotate @m
Note that commas are required between rows, if they are indicated. | | 4x4 matrix | Translation/rotation matrices in Jmol are indicated either as a 4-row, 4-column array or by 16 numbers set off by double brackets.
m = [[0.57010806 -0.0516641 0.8199437 0],[-0.5407497 0.72776425 0.42183995 0],[-0.6185197 -0.68387866 0.3869669 0][0 0 0 1]];
m =[[0.57010806 -0.0516641 0.8199437 0 -0.5407497 0.72776425 0.42183995 0 -0.6185197 -0.68387866 0.3869669 0 0 0 0 1]] ;
rotate @m
Commas are required between rows, but indicating rows is optional. | | point | pt = {3.2 3.3 3.4};
Commas are optional. | | plane | xyPlane = {0 0 1 0};
Planes are defined as {a b c d}, where the equation of the plane is ax + by + cz + d = 0. | | quaternion | q = quaternion({1 0 0}, 30);
q = {0.25881904 0.0 0.0 0.9659258};
(see next section) Quaternions are saved internally in Jmol using the same format as for planes, as single-precision floating point four-element vectors, with parameter order {x y z w} or {q1 q2 q3 q0}. Ordering the parameters in this way is consistent with Java Quat4f format and allows both quaternions and planes to contain axis information in the first three parameters. The common storage format for planes and quaternions works because typical quaternion operations are not common to operations involving planes. | | string | myLabel = "this is a test";
Strings may be enclosed in either single or double quotes. |
Differences Between Jmol Math and JavaScript back
Jmol Math is mostly an extension of JavaScript, with some differences, most notably:
| Jmol | JavaScript | | String comparisons in Jmol are not case sensitive, so "test" == "TEST". (But see the "like" operator, where "test" like "TEST" evaluates to false.) Note that this means that cases "f" and "F" in switch both match "f" and "F". | String comparisons are case sensitive; there is no "like" operator. | | Variable and function names are not case sensitive. test == Test. | Variable and function names are case sensitive. | | Boolean values in Jmol are not case sensitive: TRUE == true. | Booleans are specifically true and false. | | Use of undefined variables in Jmol is not an error; undefined variables are simply returned as empty strings. | Reference to undefined variables throws an error. | | Integers are distinct from decimals in Jmol | All numbers outside of specialized array buffers are double-precision 64-bit floating-point values. | | Decimal values are 32-bit floating-point values in Jmol/Java and 64-bit floating-point values in JSmol. | All numbers are double-precision 64-bit floating-point values. | | Array indices are 1-based in Jmol; 0 is the last element of an array, -1 is the next-to-last element, etc. If a is an array, then a[1][2] generally represents the first two elements of a. To specify a specific element of a multidimensional array, use parenthesis: (a[1])[2]. However, in the assignment context a[1][2] = ..., this notation refers to the second element of the first element of the multidimensional array a. | Array indices are 0-based; negative array indices are not meaningful.. If a is an array, then a[1][2] represents the third element of the second element of the multidimensional array a. | | In Jmol, 3x3 and 4x4 matrices are distinct subsets of arrays. If m is a matrix, then m[1][2] addresses the matrix element in column 1, row 2. | No distinction between arrays and matrices. | | Associative arrays in Jmol are expressed as {"key":value} or [key:value]. The {} notation is compatible with JSON, so JSON object and array string data can be used directly as Jmol associative and serial arrays, respectively. Quotation marks, are required when braces { } are used (as in JSON), but are optional when brackets [ ] are used (as in JavaScript objects). | Associative arrays are JavaScript Objects and as such are expressed as {key:value} only. Quotation marks around key are generally optional. [ ] notation is for serial arrays only. | | Bitsets in Jmol serve as highly compressed boolean arrays, with logical operations AND, OR, and NOT. | No equivalent data type. | | Operations in Jmol such as a + b on variables of different types depend upon the types involved and the order used, with the one on the left of principal importance, coercing the result (see below). For example, 3 + "3" == 6; "3" + 3 = "33". | Operations such as a + b on variables of different types depend upon the types involved, but do not depend upon order: 3 + "3" and "3" + 3 both equal "33". | | Binary operations in Jmol include +, -, *, /, % (modulus), \ (integer division), ** (exponentiation), && (or AND or just &), || (or OR or just |), ! (or NOT), == (or just =), other standard comparison operators, and like. Jmol math does not support bitwise operations such as &, |, or ^, although bitwise and, or, and not are all used with bitsets. | Operations include +, -, *, /, %, ++, --, && (logical AND), || (logical OR), == and === (strict equivalence, as distinct from == or the assignment operator, =), and bitwise operations &, | ^, ~, <<, >>, and >>>. | | Inline assignment in Jmol, such as x = (y = 3), or just x = y = 3, is not supported. (In this case, x will end up true or false, depending upon the value of y. | Inline assignment such as x = (y = 3),or just x = y = 3, is supported. |
Jmol Quaternion Math back
All quaternions in Jmol are unit quaternions, which are four-dimensional vectors that can be used to define the relative rotational aspects of a protein or nucleic acid structure as well as overall molecular orientation. This means that they can be used in a variety of commands, including navigate, moveto, and rotate to rotate the model or selected atoms of the model around specific axes and to specific orientations. Each quaternion can be thought of as representing a unique axis and angle which will transform a reference frame (either the molecular reference frame or the window reference plane to a given orientation. If n is the axis and theta is the angle (measured in a right-handed, counter-clockwise direction), then q(theta/2, n) = (cos(theta/2), n sin(theta/2)). For storage, the vector n is broken out into its x, y, z components, giving a total of four numbers, (q0, q1, q2, q3), where q0 = cos(theta/2), q1 = nx sin(theta/2), q2 = ny sin(theta/2), and q3 = nz sin(theta/2). Jmol reports a quaternion as a four-vector with q0 listed last: {q1, q2, q3, q0} in order to be consistent with Java's {x, y, z, w} notation.
The quaternion() function constructs quaternions using a variety of starting points, including no parameters (the current model rotation), the four numbers q0-q3, quaternion(q0, q1, q2, q3), axis-angle information, quaternion({0 0 01}, 30), and 3x3 rotation matrices, quaternion(mat). The quaternion() function also can deliver the spherical mean rotation of a set of rotations, quaternion([qa, qb, qc, ....]), or its standard deviation, quaternion([qa, qb, qc, ....], TRUE) based on Samuel R. Buss and Jay Fillmore, "Spherical Averages and Applications to Spherical Splines and Interpolation", ACM Transactions on Graphics 20 (2001) 95-126.
In addition, quaternions representing the orientation of specific amino acid residues and nucleic acid bases can be constructed automatically based on the setting of the Jmol parameter quaternionFrame, and certain commands and functions such as show rotation and script("show rotation") deliver quaternions. These quaternion values can be depicted visually using the draw and plot commands and can be listed or saved to a file using the show and write commands, respectively.
An interesting feature of quaternions that makes them different from the more common 3x3 rotation matrices is that they can encode rotations up to 720 degrees. For example, quaternion({0 0 1}, 30) = {0.0 0.0 0.25881904 0.9659258} (a 30-degree CCW rotation around the Z axis), while quaternion({0 0 1}, 390) = {0.0 0.0 -0.25881904 -0.9659258} (because sin(195) and cos(195) are both negative). While rotations of 0 degrees, {0 0 1 1}, and 360 degrees, {0 0 -1 -1} represent the same final state, in certain cases they can represent different processes and can thus be significantly different. In addition, quaternion differences (or "derivatives") can be quantified in ways that cannot be done for 3x3 rotation matrices. For example, the mean and standard deviation of a set of quaternions can be determined: print [a,b,c,d,e].average, print [a,b,c,d,e].stddev, where a-e are quaternions, providing, for example, the average helical axis for a protein helix structure, or a measure of how "ideal" that helix is.
The quaternion q = quaternion() measures how much the model has been rotated from its reference position (with x to the right, y to the top, and z toward the user). It can be used to align any axis or plane with any other "window-frame" axis. For example, here is a quaternion recipe for the shortest rotation that takes atom "X" and puts it between the center of the model and the user, that is, "in the forefront:"
q = quaternion(script("show rotation"))
toAtom = {C1}.xyz - {*}.xyz
toUser = (!q)%{0 0 1}
axis = cross(toAtom, toUser)
a = angle(toAtom, {0 0 0}, axis, toUser)
rotate MOLECULAR {0 0 0} @axis @a
The idea here is to apply the reverse model rotation quaternion to the z axis, {0 0 1} to give a vector that is pointing straight at the user. Then we get an axis that is perpendicular to both that and the vector we want to assume this position. The directed angle around that axis is obtained as a dihedral angle relating our atom, the origin, that axis, and the point in space directed toward the user. Then we rotate in a MOLECULAR frame to get the desired effect.
For another example, let's line up the plane through atoms C1, C5, and C8 such that, relative to the user, C1 is directly to the right of C5, and C8 is in the plane of the screen, above the other two atoms. This is trivial using quaternions:
x = quaternion({c5}, {C1}, {c8})
q = quaternion(script("show rotation"))
rotate molecular quaternion @{(!q) * (!x)}
This basically says, "Move this plane into the position currently occupied by the xy plane (!x), then move that plane back to the original position of the xy plane (!q)."
Operators and Operands back
Jmol expressions can include standard operators: +, -, *, /, \(integer division), **(exponentiation) %(modulus), and (&, &&, and), or (|, ||, or), not (!, not), and all standard comparison operators. The SQL-like operator LIKE can be used to compare strings in a case-sensitive manner. So, for example, while "a" == "A" is true, "a" LIKE "A" is false. (This design admittedly is a bit odd; it derives from legacy Jmol and SELECT expressions, where "=" has never been case-sensitive.) LIKE supports wildcards ("xxx*", "*xxx", and "*xxx*", for "starts with", "ends with", and "contains", respectively).
Also supported are the unary operators x++, x--, ++x, --x, which can stand alone or be part of an expression:
a = ++b
print "i=" + ++i
++a
In addition, assignments +=, -=, *=, /=, \=, |=, and &= are supported:
a += 2
b = {ala}; b |= {gly}
In general, expressions are evaluated from left to right using standard operator precedence (*,/,\ before +/-; +/- before AND/OR/NOT). For example:
twoPI = 3.14159 * 2;
minBondDistance = minBondDistance * 0.5 + 0.1;
In addition, you can set variables to be the number of atoms that match an atom expression. For example:
nNC = {_N and */1 and connected(_C)}.size
nAtoms = {*}.size;
nCH = {_H} + {_C};
Since Jmol math does not include strict typecasting, it uses a relatively complex set of rules to determine the result of operations on mixed variable types. When two different variables are operated upon, the resulting variable type depends upon the operator used, the order of the variables, and sometimes the value of the variables. See misc/operations.txt for details. In general, when conversion is required for a string, point, plane, bitset, or array, Jmol will attempt to convert it to a variable type compatible with the left-hand operand prior to operating. These conversions generally involve:
| string | to boolean | The strings "", "FALSE", "0", and decimal strings such as "0E1" and "0.0" that equal 0 are converted to FALSE; all other strings are converted to TRUE. | | string | to integer | A string evaluating to an integer is converted to that integer; all other strings are converted to 0. | | string | to decimal | A string evaluating to a number is converted to that number; all other strings are converted to the decimal value "not a number", or "NaN". | | string | to other | Jmol saves all states as simple strings, so certain character sequences are automatically turned back into other variable types when operated upon. Jmol automatically converts:
| {x y z} | to a point | | {x y z w} | to a plane or quaternion | | ({i j k l:m ... }) | to an atom bitset | | [{i j k l:m ... }] | to a bond bitset |
| | point | to integer | The distance from the point to {0 0 0} rounded DOWN to the nearest integer. | | point | to decimal | The distance from the point to {0 0 0}; same as x.distance({0 0 0}). Note that this means that 0.0 + {3 4 0} or 1.0 * {3 4 0} both give 5.0, sqrt(3*3 + 4*4 + 0*0), because the point is first converted to a decimal, then operated upon by + or *. | | plane | to integer | The distance from the plane to {0 0 0} rounded DOWN to the nearest integer | | plane | to decimal | The distance from the plane to {0 0 0}; same as x.distance({0 0 0}) | | quaternion | to decimal | cotangent(abs(theta)/2), where theta is the angle of the rotation associated with this quaternion | | bitset | to decimal or integer | The number of selected atoms or bonds in the bitset; same as x.size | | array | to decimal or integer | The number of elements in the array; same as x.size |
Operation Rules back
Rules for operations with the given types include:
+ | addition | a + b produces a decimal number EXCEPT:
| string + b | string | If b is not a string, the closest string representation will be used. | | integer + b | integer | unless b is a decimal. | | array + b | array | adds b (or all the elements of b, if b is also an array) to the end of the array to form a new array. Thus, to add a full array b as a single element to the array a, use a + [b], and to add an element b to the beginning of array a, use [b] + a. | | associative array + associative array | associative arrray | creates a new array that has all of the keys of both associative arrays. (See also array.push(array).) | | point + b | point | If b is another point then adds the two; if b is a quaternion or plane, extracts the {x y z} component of b and adds that; otherwise adds the decimal equivalent of b to all coordinates of the point. | | matrix3x3 + matrix3x3 | matrix3x3 | sum of individual elements of the two matrices | | matrix3x3 + point | matrix4x4 | adds a translation vector to a rotation matrix to give a 4x4 matrix | | quaternion + b | quaternion | If b is a quaternion, generates the product of the two quaternion rotations; otherwise adds the decimal equivalent of x to the angle of rotation associated with this quaternion. |
|
- | subtraction | a - b produces a decimal number EXCEPT:
| string - b | integer | specifically when the string is not a string representation of a decimal, such as "3.5", and b is not a decimal itself. | | integer - b | integer | unless b is a decimal. | | point - b | point | subtraction of one point from another if both are points; subtraction of the {x y z} components of b if b is a quaternion or plane; otherwise subtaction of the decimal equivalent of b from each of the coordinates of the point. | | associative array - x | associative arrray | creates a new array that is the same as the original but does not contain key x. (See also array.pop(x).) | | matrix3x3 - matrix3x3 | matrix3x3 | difference of individual elements of the two matrices | | matrix4x4 - matrix4x4 | matrix4x4 | difference of rotational parts of the two matrices, with no change in the translational component | | quaternion - b | quaternion | If b is a quaternion, generates the divides b into the quaternion; otherwise subtracts the decimal equivalent of x from the angle of rotation associated with this quaternion |
|
* | multiplication | a * b produces a decimal number EXCEPT:
| string * integer | integer | when the string is the string representation of an integer | | integer * b | integer | unless b is a decimal | | point * b | point | producing the point scaled by the decimal equivalent of b, unless b is also a point, in which case the result is the dot product producing a decimal, or a matrix, in which case the result is the transform of the point | | array * matrix3x3 | array | when the array has 3 elements; the transpose of the matrix is used for the transformation | | array * matrix4x4 | array | when the array has 4 elements; the transpose of the matrix is used for the transformation | | matrix3x3 * matrix3x3 | matrix3x3 | product of two matrices | | matrix3x3 * b | point | if b is a representation of a point, the matrix transformation of that point. | | matrix3x3 * array | array | if the array is a 3-element array; generates a 3-element array transformed by the matrix. | | matrix4x4 * matrix4x4 | matrix4x4 | product of two 4x4 matrices | | matrix4x4 * b | point | if b is a represenation of a point, the matrix transformation of that point. | | matrix4x4 * array | array | if the array is a 4-element array; generates a 4-element array transformed by the matrix. | | quaternion * quaternion | quaternion | quaternion multiplication q2 * q1 results in a composite rotation resulting from first rotating by q1, then by q2. | | quaternion * (decimal)x | quaternion | multiplication of the angle associated with this quaternion by x | | quaternion * matrix3x3 | quaternion | quaternion product |
|
/ | division | a / b produces a decimal number EXCEPT:
| integer / integer | integer | | point / b | point | if b is a point, then a is scaled by the magnitude of b; thus a/a when a is a point produces a normalized vector in the direction from {0 0 0} to point a | | quaternion / (decimal)x | quaternion | division of the angle associated with this quaternion by x | | quaternion / quaternion | quaternion | q2 / q1 = q2 * q1-1 (absolute difference in rotation, in the molecular frame) |
|
\ | left division | a \ b produces integer division EXCEPT:
| quaternion \ quaternion | quaternion | q1 \ q2 = q1-1 * q2 (relative difference in rotation, in the q1 frame) |
|
** | exponentiation | a**b takes a to the power of b; if both a and b are integers, the result is an integer, otherwise the result is a decimal number. |
% | modulus | a % b is fully defined only for integer b and produces an integer EXCEPT:
| decimal % 0 | integer | decimal a rounded to nearest integer, with n.5 rounding to (n + 1) and -n.5 rounding to -(n + 1) | | decimal % b | string | decimal a rounded to b digits after the decimal point when b > 0; decimal a rounded to b significant digits in scientific notation when b < 0 | | matrix4x4 % 1 | matrix3x3 | extract the 3x3 rotation matrix from a 4x4 rotation/translation matrix | | matrix4x4 % 2 | point | extract the translational vector from a 4x4 rotation/translation matrix | | quaternion %"w" | decimal | (also q.w or q%0) extract q0 | | quaternion %"x" | decimal | (also q.x or q%1) extract q1 | | quaternion %"y" | decimal | (also q.y or q%2) extract q2 | | quaternion %"z" | decimal | (also q.z or q%3) extract q3 | | quaternion (or plane) %"normal" | point | (also q%4) plane normal or quaternion axis; in the case of a plane, the vector from this point to {0 0 0} is directed toward the plane; for quaternions, the axis is defined such that the angle would be between -180 and 180 degrees. | | quaternion %"eulerZXZ" | point | (also q%5) Euler Z-X-Z equivalent angles, as {z x z}. | | quaternion %"eulerZYZ" | point | (also q%6) Euler Z-Y-Z equivalent angles, as {z y z}. | | quaternion %"vector" | point | (also q%-1) extract the rotational axis ({q1 q2 q3} or {x y z}) as a point (vector from {0 0 0}) | | quaternion %"theta" | decimal | (also q%-2) extract the angle in degrees for the rotation associated with this quaternion | | quaternion %"axisX" | point | (also q%-3) extract the first column of the rotation matrix associated with this quaternion (what {1 0 0} is transformed to) | | quaternion %"axisY" | point | (also q%-4) extract the second column of the rotation matrix associated with this quaternion (what {0 1 0} is transformed to) | | quaternion %"axisZ" | point | (also q%-5) extract the third column of the rotation matrix associated with this quaternion (what {0 0 1} is transformed to) | | quaternion %"axisangle" | point4 | (also q%-6) extract the related axis-angle for this rotation as {x, y, z, theta(degrees)} | | quaternion %"matrix" | 3x3 matrix | (also q%-9) rotation matrix equivalent. | | quaternion % {x y z} | point | transform {x y z} by the rotation associated with this quaternion | | string % b | string | when b > 0, right-justified in a field b characters wide; when b < 0, left-justified in a field b characters wide. Special values 9999 and -9999 return upper case and lower case, respectively. b = 0 trims the string of white space. | | point % b | point | generates the unitcell coordinate corresponding to the point, offset from {0 0 0} by {b/1 b/1 b/1}. | | bitset % b | bitset | a truncated to first b items; same as a[1][b] | | array % b | array | each element treated as a string and justified individually |
|
&& || ! | AND/OR/NOT | In a logical AND operation (as opposed to a bitset AND operation) if the operand on the left is FALSE, the operand on the right will not be evaluated; likewise for logical OR -- if the left operand evaluates to TRUE, then the right operand is not evaluated. This is the same as in most programming languages, including JavaScript and Java. The following are equivalent:
a AND/OR b as well as NOT b produce a boolean except for the following cases:
| array OR x | array | adds the element x to the array. If x itself is an array, the operation appends the elements of x as individual elements, concatenating the two arrays. To append one array onto another as a single element, simply surround the array being added with brackets: a = [1,2,3]; a |= [4, 5 6] leaves a as [1,2,3,4,5,6]; a = [1,2,3]; a |= [ [4, 5 6] ] leaves a as [1,2,3,[4,5,6] ]. | | bitset AND bitset | bitset | the intersection of the two bitsets | | bitset OR bitset | bitset | including all selections from both bitsets | | NOT bitset | bitest | the inverse of the bitset, based on the total atom count for an atom bitset or the total bond count for a bond bitset | | bitset OR integer | bitset | turns on the specified bit in the bitset. For example, ({2}) | 4 evaluates to ({2 4}). | | bitset OR array | bitset | turns on the specified bits in the bitset. For example, ({2}) | [4,5,6] evaluates to ({2 4:6}). | | !m | matrix | matrix inversion | | !q | quaternion | quaternion inverse, {-x -y -z w} |
|
== != | equal/not equal | == (or just "=") and != test for equality based on the following rules:
| string == string | true if the strings are identical | | array == array | true if the two arrays (including associative arrays) are the same length and each of their elements are identical. (In this test numerical identity does not distinguish between integers and decimals, so, for example, [4 5 6] == [4.0 5.0 6.0].) | | bitset == bitset | true if their bits are identical | | point == point | true if the distance between the points is less than 1E-6. | plane == plane
quaternion == quaternion | true if the four-vector distance between the quaternions or planes is less than 1E-6. | | others | all other comparisons are processed by first converting the two values to decimals and then testing to see if these values are within 1E-6 of each other. Note that this conversion follows the rules given in Operators and Operands. So, for example, 4.0 == 4, 5 == "5", 1.0000005 == 1, {1 1 1} == 1.7320508, [1 4 5] == 3, and ({9:12}) == 4. If a strict identity test is desired, use array notation: [5] != ["5"], since array equality does not use these conversions. |
|
|
See also:
|
[Jmol Command Syntax] [Jmol Parameters] [atom expressions] [atom properties] [functions] case default echo for if message reset set set (misc) switch while undefined |
top search index |
|
A note about precision. The issue of double or float (aka "single") precision has a long history in Jmol. Early on, using floats seemed reasonable, as it was the more memory-efficient than using double. And it seemed unnecessary to do anything more precise.
But it has always been a problem (and boon!) that JavaScript is DOUBLE precision by design. This resulted in very slight differences between Jmol and JSmol, particularly for loading crystal structures, where there is often a very thin line between being "in" the unit cell and being "out" or being close to a symmetry element or not. Or being the same atom produced by two different symmetry operations or not. The problem was largely solved in 2014 for Jmol 14.3.5 by trimming float and double precision in both Java and JavaScript down to common level during the reading of crystal structures. This "legacy" normalization of coordinates and other key values in file reading allowed Java and JavaScript to load files identically.
Then in 2022 we started to see crystal structures derived from computation, where full double precision is expected. The question was how to get JavaScript working in double precision even if its originating Java was in float precision. This was a significant challenge. The solution was to create the "doublePrecision" setting in Jmol 14.32.42 (2022.03.24), which specifically allows Jmol legacy JavaScript to retain its full double precision without doing anything in Java.
Of course, that meant that PNGJ files and other scripts might read a structure differently in Java than in JavaScript, particularly if there are atoms present that are very close to a unit cell face when LOAD...PACKED is used. But that was still a good solution for browser based applications such as the Q-Studio crystal building web interface we were developing for PWMAT. The problem has been that of not finding all the places where Jmol was normalizing the double values of JavaScript with the float values of Java.
The current situation is as follows: "legacy" JSmol JavaScript will handle double precision properly after issuing SET doublePrecision TRUE. "legacy" Java Jmol (Jmol.jar) cannot process crystal structures in full double precision. Thus, the default value of doublePrecision for legacy Java Jmol is FALSE, and it cannot be changed. In contrast, Jmol-SwingJS (Java "JavaD.jar" and "JmolD" JavaScript) are both completely double-precision and unaffected by this setting. Their default is TRUE, and that value cannot be changed.
So this is primarily about legacy JavaScript JSmol. Two file readers, CIF and PMAT, will set doublePrecision automatically. These readers detect the precision of the data from the number of decimal places in the fractional coordinates. "0.6667" would indicate four digits of precision, for example. If a CIF file has 10 or more decimal digits, doublePrecision will be set TRUE while reading. In addition, if a PWMAT file is read, doublePrecision will always be set TRUE. These are temporary settings, only for a single file reading. So if this is all you are using it for, you do not need to set doublePrecision TRUE yourself.
If you are solely using JavaScript and you have less interest in JavaScript/Java compatibility (or you plan to use double-precision JmolD.jar), you might want to set this value true when you start up JSmol in any of the following situations:
You are finding the space group for a structure using CALCULATE SPACEGROUP
You are building a crystal structure using the Jmol ModelKit
You are setting the space group using MODELKIT SPACEGROUP
You are dragging symmetry-equivalent atoms of a crystal structure using set DRAGATOM
You are labeling atoms or selecting them using Wyckoff positions
All of these crystal structure-related operations are best done with the lowest tolerances possible -- that is, the highest precision. But it is also quite possible that you will not notice any particular issue here. The problem occurs because experimentally based CIF files by nature have low precision -- perhaps only four or five significant digits. For these structures, we do NOT want to have high precision all the time. If we did, the values in the files might not be mathematically close enough to the ideal to make these functions work reliably.
|
See also:
|
[Jmol and Symmetry] [Jmol/JSpecView/MagresView] cache initialize load set (files and scripts) zap undefined |
top search index |
|
Jmol supports a full implementation of Open SMILES and Daylight SMARTS along with powerful Jmol SMILES and Jmol SMARTS extensions, allowing the SMARTS syntax to be used for biomolecular substructure searching, three-dimensional conformation searching, and polyhedra searching.
The Jmol bioSMILES, Jmol bioSMARTS, Jmol PolySMILES, and Jmol SMARTS syntaxes are relatively simple extensions of the Open SMILES definitions, including all stereochemistry and "primitive" syntax in those definitions.
Importantly, Jmol can compare and search SMILES strings themselves (independent of any loaded structure). This feature allows, for example, checking of student answers to questions that require the entry of structures using 2D drawing programs such as JSDraw and JME.
Jmol implements several aromaticity models using Jmol SMILES prefix "directives," including /strict/, /open/, /mmff94/, /noaromatic/, as well as the default aromaticity model, /jmol3d/. These models are described more fully in Jmol-OpenSmiles.pdf. Note that Jmol SMILES is not canonical, but the /nci/ directive, as in {*}.find("SMILES/nci"), allows retrieving a canonical SMILES string from the NCI CACTVS resolver. Additional directives include:
| /hydrogen/ | Generate a fully elaborated SMILES, making all hydrogens explicit, and include chirality at both CH2 and CH3. For example:
load :caffeine
print {*}.find("SMILES")
O=C1c2c3N(C)C(=O)N1C.[n]2(C)c[n]3
print {*}.find("SMILES/hydrogen")
O=C1c2c3N4[C@@]([H])([H])[H].N51[C@@]([H])([H])[H].C54=O.[n]62[C@]([H])([H])[H].c6([H])[n]3
While it may seem odd to add chirality descriptors at CH2, and CH3, this can be important. Certainly when mapping models in relation to NMR spectroscopy, CH2 hydrogens may not be magnetically equivalent and so need to be distinguished. And, if we are looking for a full 3D conformationally mobile comparison of the two structures, we must be sure to not map a clockwise winding of the CH3 hydrogens in one model to a counterclockwise winding in the other. | | /hydrogen2/ | Generate a SMILES that makes all CH2 explicit (but not CH3) and includes chirality at CH. For example:
load :2-bromo-4-methylpentane
show smiles/hydrogen2
Br[C@]1([H])C.[C@@]1([H])([H])[C@]2([H])C.C2
Notice that in this mode, chirality is shown at ALL carbon atoms except CH3, even if they are isopropyl or tert-butyl groups, because these groups could be magnetically or 3-dimensionally inequivalent. | | /invertStereo/ | allows a quick check for enantiomers. Example: select search("/invertStereo/C[C@H](Br)CC") will match (R)-2-bromobutane even though that SMILES is for (S)-2-bromobutane. | | /bio/ | Jmol bioSMILES with header and chain comments | | /bionocomments/ | no chain comments (but still one header with comments) | | /bioatomcomments/ | full atom comments | | /biocovalent/ | indicates covalent S-S crosslinking using ":" notation | | /biohbond/ | indicates hydrogen bonds using ":" notation (requires calculate hbonds) | | /biounmatched/ | allows unmatched rings |
Examples of using Jmol SMILES and Jmol SMARTS include:
| Creating a 1:1 atom mapping between two models from different sources | load files "$caffeine" ":caffeine"
print {1.1}.find({2.1},"map", "name").MAP1to2.format("JSON")
[ [ "O1","O14" ],[ "O2","O4" ],[ "N3","N5" ],[ "N4","N10" ],[ "N5","N1" ],
[ "N6","N8" ],[ "C7","C12" ],[ "C8","C7" ],[ "C9","C13" ],[ "C10","C3" ],
[ "C11","C9" ],[ "C12","C6" ],[ "C13","C11" ],[ "C14","C2" ] ] | In this example, we create a 1:1 mapping of atom names for the caffeine model from two sources -- NIH/CADD ($caffeine), and PubChem (:caffeine) -- by correlating them both to the same SMILES string, which is not shown but is the basis for the mol1.find(mol1,"map") method invocation. In this case, we do not include hydrogen atoms, but if we wanted to do that, we could use "map hydrogen" or "map hydrogen2" instead of just "map" here. | | Using a reference SMILES to create a 1:1 atom mapping between two or more models | load $caffeine
s = show("smiles/hydrogen2")
print s
N12C.C2(=O)N3C.c43c5C1=O.[n]56C.c6([H])[n]4
print {*}.find(s,"map").format("JSON")
[ [ 0,1,2,3,4,5,6,11,12,13,9,10,7,8,20 ] ]
load :caffeine
print {*}.find(s,"map").format("JSON")
[ [ 4,13,9,1,2,11,7,6,8,0,3,12,5,10,14 ] ] | In this example we create a 1:1 mapping of atoms for the caffeine model from two sources -- NIH/CADD, and PubChem -- by correlating them both to the same reference SMILES string. The result gives the list of atom indices in the model in order of their position in the SMILES. Note that if this reference SMILES were included in an NMR data set with analysis, it would be possible to then use any model of the compound from any source, whether 2D or 3D, | | substructure search | select search("[r4]") | search for all atoms in 4-membered rings | | selective substructure search | x = a.find("SMARTS","{C}C=O") | using a here to specify a subset of the matching atoms to select; in this case, load the variable x with all alpha-carbons. | | variable bond distance search | print {1.1}.find("[H]{O}[$3-4(C)]{O}[H]",true,true) | return an array of all pairs of oxygen atoms that are part of OH groups that are 3 to 4 carbons away from each other. | | conformational search | x = {1.1}.find("[!H](.t:-55,-65)CC[!H] || [!H](.t:55,65)CC[!H]", true) | fill array x with all non-hydrogen "gauche" interactions (torsions between -55 and -65 degrees or between 55 and 65 degrees). distance (.d), angle (.a), and torsion(.t) may all be queried. These designations do not have to be sequential; they can be disconnected or expressed across SMILES "." notation. if they are not sequential, then they should be given an index -- .d2 .a1 -- and then refered back to that designation by the participating atoms. For example,
load $cyclohexane
select on search("{[H](.d1:2.4,2.6)}CCC{[H](.d1)}")
will highlight all axial hydrogen atoms, and
load $1-methylcyclohexane
select on search("C(.t2:170, 180)C(.t2)C(.t2)C(.t2)")
will highlight one of the anti relationships involving the equatorial methyl group. | | Map one structure onto another using SMILES | load files ":2-butanol" "$2-butanol"
m = compare({1.1},{2.1},"map", "CC(O)CC")[1] | The resultant array of five [a1,a2] atomIndex pairs is ordered by position in the SMILES string. In this case, m[3] (the oxygen atom) is [0 19]. That is, the oxygen is the first atom in the the first model (from PubChem) and the 5th atom in the second model (from NCI/CADD). (There are 15 atoms in the first model {1.1}; 19 - 15 = 4, so the other model's oxygen is the fifth atom in the file.) | | Align two structures on top of each other using SMILES | load files ":2-butanol" "$2-butanol"
frame all
compare {1.1} {2.1} SMILES "CC(O)CC" rotate translate | SMILES is used to determine a 1:1 mapping of atoms between the two structures, and then the second structure is rotated and translated to give the lowest RMSD. | | Align two structures on top of each other using SMILES, rotating dihedrals to match. | load files ":2-butanol" "$2-butanol"
frame all
compare {1.1} {2.1} BONDS "CC(O)CC" rotate translate | SMILES is used to determine a 1:1 bond mapping between the two structures, and then the second structure is fitted to the first structure by using the first structure's dihedrals as targets to give the lowest RMSD flexible alignment. | | Map structure onto SMILES | load :2-butanol;x = compare({*},{*},"CC(O)CC")[1] | Here we are comparing a structure with itself. The resultant array reads [ [ 3,3 ],[ 1,1 ],[ 0,0 ],[ 2,2 ],[ 4,4 ] ]. Thus, the oxygen is the first atom (atomIndex 0), and the carbon it is connected to is the second atom in the file, with atomIndex 1. | | generate a Jmol SMILES string | x = {1.1}.find("SMILES") | Return the SMILES string for model 1.1; same as select 1.1; show SMILES. Note that when creating a SMILES string from a 3D model, Jmol may "over-express" chirality centers. The SMILES algorithm identifies local stereochemistry; it does not run down two paths to see if they are the same or not. Jmol will check only for the following, and only for carbon: (a) two atoms that are identical and have only one connection (H, F, Cl, Br, for example) and (b) two CH3 groups. Thus, for example, Jmol will not tag an isopropyl group as R[C@H](C)C, but it will tag RCHEt2 as R[C@H](CC)CC. This is intentional. Jmol's aromaticity model is based on 3D structure (a flat ring with all sp2 hybridization). | | generate an OpenSMILES string | x = {1.1}.find("SMILES/open") | Return a SMILES string that utilizes the OpenSMILES aromaticity model, which roughly follows Huckel's_rule but includes some structures that are not cyclic pi systems, such as 3,6-dimethylidenecyclohexa-1,4-diene, though not p-quinone.In addition the OpenSMILES implementation of SMILES allows for querying an (arbitrary) "class" property of an atom. To generate atom classes in SMILES/open, first populate atom.property_atomclass. For example:
load $2-butanol
@2.property_atomclass=2
@3.property_atomclass=3
@5.property_atomclass=5
print {*}.find("smiles/open")
C[C@H:2]([OH:5])[CH2:3]C
| | generate a "strict" SMILES string | x = {1.1}.find("SMILES/strict") | Return a SMILES string that applies a more strict definition of "aromatic" that is more familiar to organic chemists. This model requires that the pi system be cyclic, not allowing for double bonds to atoms outside the cycle. In this model, neither 3,6-dimethylidenecyclohexa-1,4-diene nore p-quinone would be considered aromatic. | | generate a nonaromatic (Kekulé) SMILES string | x = {1.1}.find("SMILES/noaromatic") | Return a SMILES string that contains no indication of aromaticity. | | generate a canonical SMILES string | {1.1}.find ("SMILES/nci") | retrieves a canonical SMILES string from the NCI CACTVS resolver. | | generate a topological SMILES string | {1.1}.find("SMILES","top") | Creates a topology SMILES, involving just * and connections. The string does not include stereochemistry. It is designed to allowing comparison of connection patterns without respect to any other consideration and can be used to check equivalences in inorganic crystal structures. Example: load $caffeine;print {*}.find("SMILES","top") giving *1(*)*(*)*2*3*(*)*1*.*2(*)**3. | | canonical and noncanonical SMILES strings | smiles1 = "C1=C(NC(=O)C)C=CC(=C1)O"
smiles2 = "CC(=O)NC1=CC=C(C=C1)O"
if(smiles2.find("SMILES", smiles1) > 0) {
print "These are the same."
} | Various programs and web services can produce what are referred to as "canonical SMILES" strings. "Canonical" here does not mean a unique standard. Rather, it means that a given molecular structure given as input to this particular program or service will always return the same string regardless of how atoms in the structure are ordered or how the structure is drawn. For example, for acetaminophen, we have:
| service | canonical SMILES | | PubChem | CC(=O)NC1=CC=C(C=C1)O | | NCI/CADD | C1=C(NC(=O)C)C=CC(=C1)O | | JSME | CC(=O)Nc1ccc(O)cc1 |
|  |
Clearly there is a need to be able to compare SMILES strings across different servers, canonical or not. Jmol accomplishes this using the find() function, which can compare structures with structures, structures with SMILES strings, and SMILES string with SMILES strings. | | matching student-drawn structures | x = Jmol.evaluateVar(jmolApplet0,"'" + stringAnswer + "'.find("'SMILES','" + stringKey + "') > 0") | JavaScript call to a Jmol applet to find out if a given SMILES string that a student has entered using a 2D drawing object matches the key. If required stereochemistry indicated in the key is missing in the answer, the result will be FALSE. If the student's answer has unnecessary stereochemistry indicated, the result will be TRUE. |
Examples of using Jmol BioSMILES and Jmol BioSMARTS include:
| Jmol BioSMILES search | x = {*}.find("~r~{*:1}[$2-4(*())]{*:1}", true) | create an array variable x that lists all RNA (~r~) loops ( {*:1}...{*:1} ) that involve from 2 to 4 un-paired bases ( [$(*())2-4] ). | | generate a Jmol BioSMILES string | x = {*:A}.find("SMILES",true); | display the sequence for chain A in bioSMILES format://* Jmol bioSMILES 12.0.RC25 2010-07-14 15:28 1 *//
//* chain A protein 1 *// ~p~GRRIQGQRRGRGTSTFRAPSHRYKADLEHRKVEDGDV //* 37 *// | | generating a Jmol BioSMILES string without comments | x = {selected}.find("SEQ") | returns the Jmol bioSMILES sequence without any comments: load =3LL2;print {carbohydrate}.find("seq")
~c~[MAN][MAN][MAN].~c~[MAN][MAN].~c~[MAN][MAN][MAN] | | generating a Jmol BioSMILES string with crosslinking | x = {selected}.find("SEQUENCE", true) | returns the Jmol bioSMILES sequence for the specified atoms (same as .find("SMILES",true), but without the header comment; "SEQ" here would give no comments at all.) Adding the optional second parameter TRUE adds crosslinking (for 1CRN)://* chain A protein 1 *//~p~TTC:1C:2PSIVARSNFNVC:3RLPGTPEAIC:3ATYTGC:2IIIPGA
TC:1PGDYAN //* 46 *// | | generating a Jmol BioSMILES string with hydrogen bonding | x = {selected}.find("SEQUENCE", "H") | returns the Jmol bioSMILES sequence for the specified atoms with pre-calculated hydrogen bonds indicated as SMILES connection. After load =1crn;calculate HBONDS:
//* chain A protein 1 *// ˜p˜T:1TC:2:3:4C:5:6:7PS:8I:9V:%10A:%11R:8:%12S:9:%13
N:%10:%14F:%11:%15N:%12:%16V:%13:%17C:%14:%18R:%15:%19L:%17:%16PG:%19TP:%20:%21
E:%22A:%23I:%20:%24C:%21:%25:%18A:%22:%26T:%23Y:%24T:%25G:%26C:7I:3:2II:1
PGATC:4P:%27GDY:%27AN:6:5 //* 46 *// |
Jmol PolySMILES allows searching polyhedral faces of inorganic compounds or crystal structures rather than bond networks. The search is a local search, just of the atoms in the coordination sphere of a central atom. The SMILES string includes a "PH" chirality indicator, such as [Ru@PH7] for the central atom, specifing the number of attached atoms forming the corners of the polyhedron. the next n atoms (7 in this case) are appended using SMILES "." notation as though not connected to the central atom, instead showing connections to all associated edge atoms of that polyhedron. This listing is generated in a counterclockwise order looking toward the central atom from the specified corner. Jmol PolySMILES are generated by first creating polyhedra and then issuing calculate symmetry polyhedra. After this, a call to {atomset}.polyhedra.polySmiles gives the Jmol PolySMILES string.
load $P(Br)(Cl)(C)(O)(F);
polyhedra 5;
calculate symmetry polyhedra;
print @1.polyhedra.polySmiles
[P@PH5].[F]1234.[O]5672.[C]8496.[Cl]185.[Br]379
Searching for Jmol PolySMILES involves {*}.polyhedra(@1.polyhedra.polySmiles), which in this case delivers ({0}), indicating that the first atom in the model (the phosphorus atom) matches this polyhedron.
This last example illustrates how we can invert the stereochemistry of the Jmol PolySMILES simply by changing "@PH5" to "@PH5@".
load $P(Br)(Cl)(C)(O)(F)
polyhedra 5
calculate symmetry polyhedra
x= @1.polyhedra.polySmiles
print x
[P@PH5].[F]1234.[O]5672.[C]8496.[Cl]185.[Br]379
// swap the axial ligands of the trigonal bipyramid (Br and Cl in this model)
{_Br}.element = "B"
{_Cl}.element = "Br"
{_B}.element = "Cl"
polyhedra delete
polyhedra 5
calculate symmetry polyhedra
print @1.polyhedra.polySmiles
[P@PH5].[F]1234.[O]5672.[C]8496.[Br]185.[Cl]379
print {*}.polyhedra(x)
({}) // failed!
print {*}.polyhedra(x.replace("@PH5","@PH5@")); // invert stereochemistry
({0}) // success!
All the connections are the same, but all the winding is opposite -- the enantiomer.
|
top search index |
|
Jmol has a relatively complete set of algorithms to assign Cahn-Ingold-Prelog chirality descriptors, including R/S/r/s, E/Z, and M/P/m/p (axial chirality, such as for cumulenes and the single bonds between aromatic compounds with restricted rotation -- that is, atropisomerism). There are several ways to access this information:
| labeling | The LABEL and SET LABELFOR commands with format %[chirality] display the chirality of all selected atoms, if it exists. Bond chirality is shown at both ends. | | x = {*}.label("%[chirality]") | The label("%[chirality]") function returns an array of chirality descriptors, with empty strings for atoms with no descriptor. | | @1.chirality or {*}.chirality | You can access the chirality for one or more centers directly as an atom property. | | CONNECT {atom1} {atom2} ATROPISOMER | the CONNECT command can be used to add atropisomer indicators to Jmol SMILES and SMARTS. These are ^nm- and ^^nm- (similar to [@] and [@@]), where ^ indicates a negative dihedral angle, and ^^ indicates positive. :
load :bipyridyl
CONNECT @3 @4 ATROPISOMER
SHOW SMILES
[n]1ccccc1^22-c2cccc[n]2
The designations n and m are one of 1, 2, or 3, with n indicating the index of the bond for the atom on the left, and m the same for the atom on the right. In this case, the first "2" points to ring connection 1, connecting to nitrogen, and the second "2" points to the second connection to the carbon on the right, that is to ring connction 2, again a nitrogen. The defaults "^22-" and "^^22-" can be left simply as "^-" and "^^-". | | Jmol SMILES and SMARTS | You can use Jmol SMILES and SMARTS to query a structure and check its chirality. Several methods, particularly FIND and COMPARE and especially powerful in this regard, allowing all sorts of highly sophisticated analysis. |
|
top search index |
|
Jmol can generate InChI strings and InChIKeys natively in Java, and InChI strings (but not InChIKeys in JavaScript. Examples are given below.
| SHOW INCHI | Reports the InChI for currently selected atoms. For example, select *;show inchi | | x = atoms.inchi(flags) | Returns an InChI for the specified atoms. flags are from inchi faq are case-insensitive and include:
| perception flags | DoNotAddH SNon NEWPSOFF | | stereo flags | SRel SRac SUCF | | more flags | NEWPSOFF SUU SLUUD RecMet FixedH KET 15T | | (Java only) | outputsdf |
For example: load $morphine; print {*}.inchi("srel"). | | x = atoms.inchi("key") | Returns an InChIKey for the specified atoms (Java only; in JavaScript, you can use show("chemical inchi"), which gets the key from NCI/CADD.) | x = "CCCC".inchi() or
print "$caffeine".inchi() | Retrieves the structure internally from NCI/CADD, then calculates the InChI in Jmol. | | x = ":caffeine".inchi() | Retrieves the structure internally from PubChem, then calculates the InChI in Jmol. | | x = load("foo.mol").inchi() | Creates the InChI from MOL file data. | | x = inchi.inchi("key") | InChIKey from InChI (Java only, not JavaScript). |
Note that because InChI initialization is asynchronous in JavaScript, it is recommended that INITIALIZE INCHI be invoked on start-up or in a separate script before InChI is used in scripts. Otherwise, the first call to create an InChI may not work. Alternatively, a null call to create an InChI can be made followed by a short delay. For example: show inchi;delay 0.01;print "CCCC".inchi();. The delay allows for the asynchronous loading of InChI WASM.
|
top search index |
|
Jmol has a full set of analysis and visualization tools for space group and point group symmetry. All standard and magnetic space group operations are covered, including "3+N" higher-dimensional symmetry for incommensurately modulated crystal structures. Features are concentrated in four command options and one function:
LOAD .... SPACEGROUP .... UNITCELL ....
SHOW SYMOP ....
DRAW SYMOP ....
DRAW POINTGROUP or SPACEGROUP
x = symop(....)
With these features, you can:
-- load any model while applying any actual or conceivable space group or subset of a space group
-- tabulate and visualize all space group operations associated with that model
-- retrieve an associative array indicating all aspects of the operation, including point, rotation axis, plane, glide vector, lattice offset vector, and 4x4 matrix
-- visualize all aspects of an operation, including proper and improper rotations inversion centers, mirror lanes, glideplanes, translations, and magnetic spin time reversal
-- apply any operation to any atom or any point in space
-- given any combination of two atoms or two points in space, determine and/or depict the operation(s) that relate those to atoms or positions.
|
See also:
|
[Jmol Precision] [Jmol/JSpecView/MagresView] cache draw initialize load polyhedra set (files and scripts) set (visibility) zap undefined |
top search index |
|
Jmol maintains a large amount of information about atoms, bonds, shapes, files, and many other aspects of the models loaded into it. For example, getProperty("atomInfo") returns an array giving the information for each atom that is loaded:
load $caffeine
x = getProperty("atomInfo")
print x.count
24
print x[1]
{
"_ipt" : 0
"atomIndex" : 0
"atomno" : 1
"bondCount" : 3
"clickabilityFlags" : 48
"colix" : -32761
"color" : "[x3050f8]"
"coord" : {1.312 -1.0479 0.0025}
"element" : "nitrogen"
"elemno" : 7
"formalCharge" : 0
"info" : "N1 #1"
"model" : "1"
"partialCharge" : 0.0
"radius" : 0.7416667
"shape" : "trigonal planar"
"spacefill" : 0.3565
"sym" : "N"
"visibilityFlags" : 63
"visible" : true
"x" : 1.312
"y" : -1.0479
"z" : 0.0025
}
JmolSQL is a Jmol math syntax that is designed to query this sort of information. The idea is that maps, with key/value pairs, and especially arrays of maps, are data, and those arrays themselves can be thought of as a mini database. These sorts of data can be found in Jmol in the a model's auxiliary info (variable _M), including validation data returned from LOAD =xxxx/val (_M.validation), sequence domain data returned from LOAD =xxxx/dom (_M.domains), and secondary structure information returned from LOAD =xxxx/dssr (_M.dssr, see JmolSQLforDSSR.pdf) or LOAD=xxxx/rna3d (_M.rna3d). In addition, the getProperty() function returns a wide variety of data relating to model attributes, including getProperty("atomInfo") and getProperty("bondInfo") among several others. (See getProperty.) In addition, you can add your own database-like information to a model in the form of arrays and maps. The JmolSQL search query language syntax allows you to examine and analyze all of this information using a structured query language similar to MySQL. Any array or key/value paired "map" or "map" data can be interrogated.
The original conception of JmolSQL was an extension of the getProperty() function -- for example:
load $caffeine
print getProperty("atomInfo[SELECT atomno,coord WHERE shape LIKE 'trigonal planar']")
{
"atomno" : 1
"coord" : {1.312 -1.0479 0.0025}
}
{
"atomno" : 3
"coord" : {1.7906001 0.20809999 9.999999E-4}
}
...24 of these...
The within(dssr,...) syntax also uses JmolSQL. See JmolSQLforDSSR.pdf for details. The following selection finds and highlights RNA base pairs that are not standard Watson-Crick base pairs:
load =4fe5/dssr
select on within(dssr, "pairs WHERE name!='WC'");
More recent development widens this use to any array data, and use of the .select() function rather than getProperty() is recommended for general use. Thus, alternatively we can use:
print getProperty("atomInfo").select("atomno,coord WHERE shape LIKE 'trigonal planar' ")
object.SELECT("keys WHERE/WHEREIN phrase")
There are three parts to JmolSQL: object, keys, and an optional WHERE or WHEREIN phrase. The object can be either a map [key1:value1, key2:value2, key3:value3] or, quite commonly, an array of maps, usually all having the same set of keys.
Maps
When the top-level object is a map, .select() can be used to select out subsets of that array, either as a single map or as an array of values.
map.select("...")
The simplest form of .select() returns a subset of map. Wild cards can be interspersed with additional keys, for example, "a*,b" or "*_id". In each such case, the case-sensitive LIKE operation is used to match keys.
map = [ A:[b:1],B:[b:2],AA:[b:3, d:50] ]
print map.select("A").format("JSON")
{ "A": { "b": 1 } }
map = [ A:[b:1],B:[b:2],AA:[b:3, d:50] ]
print map.select("A*").format("JSON")
{ "A": { "b": 1 },"AA": { "b": 3,"d": 50 } }
map.select("(...)")
Using parentheses around the list of keys delivers an array of just the values rather than the full key/value pair:
map = [ A:[b:1],B:[b:2],AA:[b:3, d:50] ]
print map.select("(A,B)").format("JSON")
[ { "b": 1 },{ "b": 2 } ]
Arrays of Maps
Properties such as AtomInfo, BondInfo, and ModelInfo are arrays of maps. A list of data for each atom, each bond, or each model. This is the essence of a database. JmolSQL can operate on these as well.
array.select("...")
JmolSQL will operate on an array of maps the same as on the map itself. But this time, the results will be in the form of an array of maps still. For example, we can create a sublist of maps having the selected subset of keys:
array = [ [a:1,b:11],[a:2,b:22],[a:3,b:33] ]
print array.select("b").format("JSON")
[ { "b": 11 },{ "b": 22 },{ "b": 33 } ]
print x.select("atomno,element")
{
"atomno" : 1
"element" : "nitrogen"
}
{
"atomno" : 2
"element" : "carbon"
}
{
"atomno" : 3
"element" : "carbon"
}
{
"atomno" : 4
"element" : "oxygen"
}
...
array.select("(...)")
Adding parentheses creates a list of only the values for the specified keys:
array = [ [a:1,b:11],[a:2,b:22],[a:3,b:33] ]
print array.select("(b)").format("JSON")
[ 11,22,33 ]
array = [ [a:1,b:11],[a:2,b:22],[a:3,b:33] ]
print array.select("(a,b)").format("JSON")
[ 11,1,22,2,33,3 ]
Let's catalog all the elements in a caffeine model:
load $caffeine
print getProperty("atomInfo").select("(element)").pivot
{
"carbon" : 8
"hydrogen" : 10
"nitrogen" : 4
"oxygen" : 2
}
The assumption when using (keys) is that you want to know all these values, but you don't need the keys themselves, An example is a list of bonds for which we just want to know all the atoms involved, but the atoms are listed under "atom1" and "atom2" in each bond array.
load =1ehz/dssr
select on @{_M.dssr.hbonds.select("(atom1_id,atom2_id)")}
206 atoms selected
By the way, the reason we can go so directly from DSSR data structures to atom selections is that DSSR atom and residue descriptions use Unit IDs. The _M.dssr.hbonds structure looks like this:
{
"atom1_id" : "|1|A|G|1|OP2|||"
"atom1_serNum" : 4
"atom2_id" : "|1|A|C|2|OP2|||"
"atom2_serNum" : 27
"atom_pair" : "O:O"
"distance" : 2.991
"donAcc_type" : "questionable"
"index" : 1
"res_long" : "|1|A|G|1||||,|1|A|C|2||||"
"res_short" : "GC"
"residue_pair" : "nt:nt"
}
Jmol can interpret Unit IDs natively, and, because Unit IDs have such a unique signature, Jmol can even select atoms based on any text that contains them. They do not have to be given individually.
Using WHERE
WHERE is used to select a subset of the elements of an array based on specific key-value relationships.
array.select("... WHERE ...")
Delivers all key/value pairs in the subset of array element maps for which the WHERE clause is true for that element.
array = [ [a:1,b:11],[a:2,b:22],[a:3,b:33] ]
print array.select("* WHERE a<3 and b<20").format("JSON")
[ { "b": 11,"a": 1 } ]
load $caffeine
print getProperty("atomInfo").select("atomno,element WHERE shape LIKE 'trigonal planar' ").format("JSON")
[ { "element": "nitrogen","atomno": 1 },{ "element": "carbon","atomno": 3 },{ "element": "nitrogen","atomno": 5 },{ "element": "carbon","atomno": 7 },{ "element": "carbon","atomno": 9 },{ "element": "nitrogen","atomno": 10 },{ "element": "carbon","atomno": 12 },{ "element": "carbon","atomno": 13 } ]
array.select("(...) WHERE ...")
Using parentheses around the list of keys delivers a list of values for only the subset of array for which the WHERE clause is true:
array = [ [a:1,b:11],[a:2,b:22],[a:3,b:33] ]
print array.select("(b) WHERE a>1").format("JSON")
[ 22,33 ]
This next example quantifies the various atomic orbital hybridizations that in the caffeine molecule:
load $caffeine
print getProperty("atomInfo").select("(shape) WHERE shape").pivot
{
"bent" : 1
"tetrahedral" : 3
"trigonal planar" : 8
}
Note that "WHERE shape" here just excludes all cases where shape is the empty string, since empty strings in Jmol evaluate as FALSE. (In this case that involves hydrogen atoms.)
This next example finds all the hydrogen bonds created by DSSR for residue 72, listing and averaging them. Note that the DSSR report uses Unit IDs to represent residues:
load =1ehz/dssr
x = _M.dssr.hbonds.select("(distance) WHERE res_long LIKE '*|A|C|72|*'");
print x.format("JSON")
print format("%5.3f",x.average)
[ 2.832,2.879,2.838 ]
2.850
Array Drilling
WHERE will "drill down" through arrays of arrays to find elements that are maps.
array = [ [[a:1,b:11], [a:0,b:0]],[[[a:2,b:22]]],[[a:3,b:33,aa:44]] ]
print array.select("a* WHERE a>0").format("JSON")
[ [ { "a": 1 } ],[ [ { "a": 2 } ] ],[ { "a": 3,"aa": 44 } ] ]
We use array.join() here to produce a flat one-dimensional array of those objects:
array = [ [[a:1,b:11], [a:0,b:0]],[[[a:2,b:22]]],[[a:3,b:33,aa:44]] ]
print array.select("a* WHERE a>0").join().format("JSON")
[ { "a": 1 },{ "a": 2 },{ "a": 3,"aa": 44 } ]
Note how effective array.join() is in this next case:
array = [ [[a:1,b:11], [a:0,b:0]],[[[a:2,b:22]]],[[a:3,b:33,aa:44]] ]
print array.select("(b) WHERE a>0").join().format("JSON")
[ 11,22,33 ]
Using WHEREIN
Using select(... WHEREIN...), you can select key value pairs where the values of the selected keys themselves are tested. For example:
x = [key_1:[type:"a"],key_2:[type:"b"],key_3:[type:"a"]]
print x.select("* WHEREIN type='a'").format("JSON")
{ "key_1":{ "type":"a" },"key_3":{ "type":"a" } }
Note that the resultant array now only has entries for key_1 and key_3, because only they have values for which type == "a". (Had we used WHERE here, nothing would be returned, because "type" is not a key in x itself.)
This next example checks the symmetry of occupied orbitals in Gausian output using WHEREIN:
load https://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz 2 filter "alpha"
print _M.moData.select("mos WHEREIN occupancy>0").select("(symmetry)").pivot
{
"(A1)--O" : 6
"(A2)--O" : 1
"(B1)--O" : 1
"(B2)--O" : 4
}
We needed to use WHEREIN here because the symmetry information is not in _M.moData itself; it is in _M.moData.mos. Admittedly, in this case, we could have accomplished this more directly with WHERE, using _M.moData.mos rather than _M.moData itself:
load https://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz 2 filter "alpha"
print _M.moData.mos.select("(symmetry) WHERE occupancy>0").pivot
{
"(A1)--O" : 6
"(A2)--O" : 1
"(B1)--O" : 1
"(B2)--O" : 4
}
This next example identifies all orbitals in a Gaussian output with B2 symmetry using WHEREIN:
load https://chemapps.stolaf.edu/jmol/jsmol/data/no2_nbo.log.gz 2 filter "alpha"
x= _M.moData.select("mos WHEREIN occupancy>0 and symmetry LIKE '(B2)*' ")
print x.select("(index)").format("JSON")
[ 1,5,8,10 ]
chaining .select()
Note that JmolSQL can be chained:
x = getProperty("measurementInfo").select("(atoms) WHERE value > 1.4").select("(atomno)");
In this case, the first selection returns an array of atom records, and the second selection pulls out only the values for atomno, producing something such as [ [ 12,13 ],[ 2,1 ],[ 6,5 ],[ 11,10 ] ].
using select([keys])
Here is another example. It produces a listing of all atoms involving double bonds in the NCI/CADD caffeine model:
load $caffeine
print getProperty("bondInfo").select("(atom1,atom2) WHERE type='double'").select("(info)").format("JSON")
[ "C3 #3","O4 #4","N8 #8","C9 #9","C7 #7","C12 #12","C13 #13","O14 #14" ]
This is OK, but wouldn't we want to have those paired by bonds? Changing (atom1,atom2) to [atom1,atom2] solves this issue:
load $caffeine
print getProperty("bondInfo").select("[atom1,atom2] WHERE type='double'").select("(info)").format("JSON")
[ [ "C3 #3","O4 #4" ],[ "N8 #8","C9 #9" ],[ "C7 #7","C12 #12" ],[ "C13 #13","O14 #14" ] ]
The first SELECT finds all the double bonds, creating an array of [atom1,atom2] data. The second SELECT then replaces the full atom record with just the info value for each atom.
Thus, when working with arrays, whether SELECT returns just values or a full set of matching key:value pairs (as in standard SQL) is determined by how the keys are listed. If keys are simply listed, without [...] or (...), then what is returned is a flat array containing the specified keys with their values. Thus, array.select("nt1,nt2") creates an array containing maps that are a subset of array that contain keys nt1 and nt2 and their associated values. array.select("(nt1,nt2)") creates a single array that holds all matching values, and array.select("[nt2,nt1]") creates an array of arrays of [nt2,nt1] values. (By the way, we could use xxx.format(["nt2","nt1"]) to give the same result.)
|
top search index |
sequence domain annotations
structure validation annotations
|
Jmol has the capability to load "annotations" -- additional information relating to a database-derived structure that is from other databases. For example, the command load *1crn/val loads PDB ID 1crn from PDBe along with structure validation information (see below).
sequence domain annotations back
Using the /dom extension for RCSB or PDBe (load *1cbs/dom or load =1cbs/dom), Jmol will load an mmCIF file along with sequence domain data from the European Bioinformatics Institute (EBI) using the PDBe JSON api, for example, https://wwwdev.ebi.ac.uk/pdbe/api/mappings/sequence_domains/1cbs?metadata=true&pretty=false. For example:
load *1cbs/dom
Domains loaded:
CATH 2.40.128.20
GO GO:0001972 GO:0005215 GO:0005501 GO:0005634 GO:0005730 GO:0005737 GO:0005783 GO:0006355
GO:0006810 GO:0007165 GO:0008289 GO:0008544 GO:0016918 GO:0019841 GO:0035115 GO:0042573 GO:0070062
InterPro IPR000463 IPR000566 IPR011038 IPR012674
Pfam PF00061
SCOP 50847
UniProt P29373
show domains
metadata restapi_version=0.8
metadata date=20140801
metadata url=https://wwwdev.ebi.ac.uk/pdbe/api/mappings/1cbs?pretty=false&metadata=true
1cbs SCOP 50847 identifier=Fatty acid binding protein-like
1cbs SCOP 50847 fold description=Lipocalins
1cbs SCOP 50847 fold sunid=50813
1cbs SCOP 50847 description=Fatty acid binding protein-like
1cbs SCOP 50847 class description=All beta proteins
1cbs SCOP 50847 class sunid=48724
1cbs SCOP 50847 superfamily description=Lipocalins
1cbs SCOP 50847 superfamily sunid=50814
1cbs UniProt P29373 name=RABP2_HUMAN
1cbs UniProt P29373 identifier=RABP2_HUMAN
1cbs GO GO:0005215 name=transporter activity
1cbs GO GO:0005215 identifier=transporter activity
1cbs GO GO:0005215 definition=Enables the directed movement of substances (such asmacromolecules,small molecules, ions) into, out of or within a cell, or between cells.
1cbs GO GO:0005215 category=Molecular_function
...
1cbs CATH 2.40.128.20 architecture=Beta Barrel
1cbs CATH 2.40.128.20 identifier=Lipocalin
1cbs CATH 2.40.128.20 name=Cellular retinoic acid binding protein type ii. Chain: a.Engineered:yes
1cbs CATH 2.40.128.20 homology=Lipocalin
1cbs CATH 2.40.128.20 class=Mainly Beta
1cbs CATH 2.40.128.20 topology=Lipocalin
1cbs Pfam PF00061 identifier=Lipocalin / cytosolic fatty-acid binding protein family
1cbs Pfam PF00061 description=Lipocalin / cytosolic fatty-acid binding protein family
1cbs InterPro IPR012674 name=Calycin
1cbs InterPro IPR012674 identifier=Calycin
1cbs InterPro IPR000566 name=Lipocalin/cytosolic fatty-acid binding domain
1cbs InterPro IPR000566 identifier=Lipocalin/cytosolic fatty-acid binding domain
1cbs InterPro IPR011038 name=Calycin-like
1cbs InterPro IPR011038 identifier=Calycin-like
1cbs InterPro IPR000463 name=Cytosolic fatty-acid binding
1cbs InterPro IPR000463 identifier=Cytosolic fatty-acid binding
Following this loading, you can select groups using JmolSQL syntax: select within(domains,"InterPro where domain.identifier='calycin'").
structure validation annotations back
When a structure is deposited with the Protein Data Bank it must pass a set of tests that validate as an acceptable structure. In the process, PDB maintains in its database the results of those tests. A summary report is available for each structure deposited (for example, for 1CBS). During the summer of 2014, in collaboration with the European Bioinformatics Institute, Jmol's capabilities were extended to read the JSON version of these reports, incorporating the data as a set of atom properties. For example:
load *1crn/val; show validation
Validations loaded:
property_types_of_outliers (residues: 3)
property_bond_lengths (atoms: 2, max: 5.38)
property_bond_angles (atoms: 6, max: 7.83)
After such loading, the validation values are available as for any atom property. For example:
load =1crn/val
select property_bond_lengths > 0
display property_types_of_outliers > 0
color property_rsrz
These properties may be expanded over time. As of 10/2014 they include:
| property_bond_angles | bond angle outliers | | property_bond_lengths | bond length outliers | | property_chirals | inverted side-chain chirality | | property_clashes | clashes | | property_planes | nonplanar aromatic ring systems | | property_rama | Ramachandran outliers | | property_RNA_suite | RNA base issues | | property_RNA_pucker | RNA sugar pucker outliers | | property_rsrz | missing or mismatched electron density (r-value for short range zones) | | property_sidechains | residue side-chain issues | | property_types_of_outliers | = 1 for residues that are outliers of any type |
|
top search index |
Atom selectors
Selection functions
RasMol biomolecular residue specifications
Wildcards
Atom names for other file types
|
In Jmol, an atom expression is a mathematical expressions that represent a collection of atoms in one or more models. Examples include
select on protein or water
display add carbohydrate
color {ala24} red
zoomto {ligand} 0
contact {e20} surface
isosurface select {within(5, HEM)} only vdw map property temperature
print "the center is at " + {*}.xyz
Notice that some of these commands require braces { } surrounding the atom expression and some do not. The basic rule is that you can always use braces, but you must use braces when a command can take arguments that are not atom expressions. So, for example, you can also color cartoons and isosurfaces and drawn objects; you can zoomto {ligand} 80 as well as 0. But what you select are atoms, and only atoms can be added to a display. Most commands DO require braces. The only ones that do not are the following ten: center, define, delete, display, fix, hide, restrict, select, subset, and zap. These are the only commands in Jmol that act specifically on atom sets.
All terms in and atom expression can be preceeded by the keyword NOT, joined by AND, OR, or XOR, and surrounded by parentheses. Terms in atom expressions include:
| general terms |
| all | all atoms; same as * | | bonded | covalently bonded | | clickable | actually visible -- having some visible aspect such as wireframe, spacefill, or a label showing, or the alpha-carbon or phosphorus atom in a biomolecule that is rendered with only cartoon, rocket, or other biomolecule-specific shape. | | connected | bonded in any way, including hydrogen bonds | | displayed | displayed using the display or hide command; not necessarily visible | | hidden | hidden using the display or hide command | | none | no atoms | | selected | atoms that have been selected; defaults to all when a file is first loaded | | solvent | PDB "UREA", "SO4", "PO4", "HOH", "DOD", "WAT"; in any model the connected set of H-O-H | | thisModel | atoms in the current frame set, as defined by frame, model, or animation commands. If more than one model is in this set, "thisModel" refers to all of them, regardless of atom displayed/hidden status. | | visible | visible in any way, including PDB residue atoms for which a cartoon or other such rendering makes their group visible, even if they themselves are not visible. |
| | file.model | as, for example, select 3.2, a specific model in a specific file. Note that select 3.0 selects all atoms in all models of the third file of the most recent load. | | subset | the currently defined subset. Note that if a subset is currently defined, then select/display all is the same as select/display subset, restrict none is the same as restrict not subset. In addition, select not subset selects nothing. | | specialPosition | atoms in crystal structures that are at special positions - that is, for which there is more than one operator that leads to them. | | symmetry-related | These selections relate to the unit cell and space group symmetry. See also atom properties fx, fy, fz, fxyz, ux, uy, uz, uxyz, and symop.
| symmetry | all atoms that are derived from the asymmetric unit (!symmetry or symop=1555) by symmetry operations or lattice translations | | unitcell | atoms of the current unitcell, which may be offset. this includes atoms on all faces, edges, and vertices of the unitcell | | within(unitcell) | atoms "within" the current unitcell -- that is, atoms with fractional coordinates ≥0 and <1 |
| | polyhedra | all central atoms for which polyhedra have been created. See also polyhera(n), below. | | chemical elements | element_name (including "deuterium and tritium"), _Xx (an element symbol preceeded by underscore, possibly with isotope number listed, such as _Cu, _Fe, _2H, _31P) | | terms based on the periodic table of the elements |
| nonmetal | _H,_He,_B,_C,_N,_O,_F,_Ne,_Si,_P,_S,_Cl,_Ar,_As,_Se,_Br,_Kr,_Te,_I,_Xe,_At,_Rn | | metal | !nonmetal | | alkaliMetal | _Li,_Na,_K,_Rb,_Cs,_Fr | | alkalineEarth | _Be,_Mg,_Ca,_Sr,_Ba,_Ra | | nobleGas | _He,_Ne,_Ar,_Kr,_Xe,_Rn | | metalloid | _B,_Si,_Ge,_As,_Sb,_Te | | transitionMetal | (includes La and Ac) elemno>=21 and elemno<=30, elemno=57, elemno=89, elemno>=39 and elemno<=48, elemno>=72 and elemno<=80, elemno>=104 and elemno<=112 | | lanthanide | (does not include La) elemno>57 and elemno<=71 | | actinide | (does not include Ac) elemno>89 and elemno<=103 |
| | isaromatic | atoms connected with the AROMATIC, AROMATICSINGLE, or AROMATICDOUBLE bond types | | non-protein/nucleic groups | carbohydrate, hetero, ions (specifically the PDB designations "PO4" and "SO4"), ligand (originally "hetero and not solvent"; changed to "!(protein,nucleic,water,UREA)" for Jmol 12.2), sidechain | | nucleic acid residues |
| nucleic | any group that (a) has one of the following group names: G, C, A, T, U, I, DG, DC, DA, DT, DU, DI, +G, +C, +A, +T, +U, +I; or (b) can be identified as a group that is only one atom, with name "P"; or (c) has all of the following atoms (prime, ', can replace * here): C1*, C2*, C3*, O3*, C4*, C5*, and O5*. | | purine | any nucleic group that (a) has one of the following group names: A, G, I, DA, DG, DI, +A, +G, or +I; or (b) also has atoms N7, C8, and N9. | | pyrimidine | any nucleic group that (a) has one of the following group names: C, T, U, DC, DT, DU, +C, +T, +U; or (b) also has atom O2. | | dna | any nucleic group that (a) has one of the following group names: DG, DC, DA, DT, DU, DI, T, +G, +C, +A, +T; or (b) has neither atom O2* or O2'. | | rna | any nucleic group that (a) has one of the following group names: G, C, A, U, I, +U, +I; or (b) has atom O2* or O2'. |
| | protein residues |
| protein | defined as a group that (a) has one of the following group names: ALA, ARG, ASN, ASP, CYS, GLN, GLU, GLY, HIS, ILE, LEU, LYS, MET, PHE, PRO, SER, THR, TRP, TYR, VAL, ASX, GLX, or UNK; or (b) contains PDB atom designations [C, O, CA, and N] bonded correctly; or (c) does not contain "O" but contains [C, CA, and N] bonded correctly; or (d) has only one atom, which has name CA and does not have the group name CA (indicating a calcium atom). | | acidic | ASP GLU | | acyclic | amino and not cyclic | | aliphatic | ALA GLY ILE LEU VAL | | amino | all twenty standard amino acids, plus ASX, GLX, UNK | | aromatic | HIS PHE TRP TYR (see also "isaromatic" for aromatic bonds) | | basic | ARG HIS LYS | | buried | ALA CYS ILE LEU MET PHE TRP VAL | | charged | same as acidic or basic -- ASP GLU, ARG HIS LYS | | cyclic | HIS PHE PRO TRP TYR | | helix, helixalpha, helix310, helixpi | secondary structure-related. | | hetero | PDB atoms designated as HETATM | | hydrophobic | ALA GLY ILE LEU MET PHE PRO TRP TYR VAL | | large | ARG GLU GLN HIS ILE LEU LYS MET PHE TRP TYR | | medium | ASN ASP CYS PRO THR VAL | | negative | same as acidic -- ASP GLU | | neutral | amino and not (acidic or basic) | | polar | amino and not hydrophobic | | positive | same as basic -- ARG HIS LYS | | sheet | secondary structure-related | | small | ALA GLY SER | | surface | amino and not buried | | turn | secondary structure-related |
| | protein/nucleic acid-related |
| alpha | (*.CA) | | base | nucleic acid bases | | backbone (or "mainchain") | (*.C, *.CA, *.N, and all nucleic other than the bases themselves) | | sidechain | ((protein or nucleic) and not backbone) | | spine | (*.CA, *.N, *.C for proteins; *.P, *.O3', *.O5', *.C3', *.C4', *.C5 for nucleic acids) | | leadatom | (*.CA, *.P, and terminal *.O5') |
| | DSSR structure | Available after load =xxxx/dssr.
| bulges | within(dssr,"bulges") | | coaxStacks | within(dssr,"coaxStacks") | | hairpins | within(dssr,"hairpins") | | hbonds | within(dssr,"hbonds") | | helices | within(dssr,"helices") | | iloops | within(dssr,"iloops") | | isoCanonPairs | within(dssr,"isoCanonPairs") | | junctions | within(dssr,"junctions") | | kissingLoops | within(dssr,"kissingLoops") | | multiplets | within(dssr,"multiplets") | | nonStack | within(dssr,"nonStack") | | nts | within(dssr,"nts") | | naChains | within(dssr,"naChains") | | pairs | within(dssr,"pairs") | | ssSegments | within(dssr,"ssSegments") | | stacks | within(dssr,"stacks") | | stems | within(dssr,"stems") |
|
The comparison operators <, <=, =, >, >=, !=, and LIKE operate with many keywords. Note that = and != are not case-sensitive in Jmol, so select group="ARG" is the same as select group="arg". If you want to compare cases, use LIKE: select chain like "D". See atom properties.
Atom selectors back
An atom expression is simply a list of atoms. You can select a single atom or a range of atoms from an atom expression. The way to do this is simply to suround the atom expression with parentheses and follow it with one or two numbers in brackets: select (carbon)[3][5].This says, "Select the third through fifth carbon atoms." If the second selector is not present, then only a single atom is selected; the selector [0] indicates the last atom in the set, and negative numbers count back from that atom. Thus, select (*)[0] selects the last atom, and select (carbon and 2.3)[-1][0] selects the last two carbon atoms in model 2.3. Atom selectors can be used for any expression embedded in another command. In that case an additional set of parentheses or braces is required around the whole expression: measure {(_O)[1]} {(_O)[2]}.
Selection functions back
The following functions are also supported for the selection and specification of atom sets:
| CONNECTED() | allows for selection of specific atoms based on their connectivity to other atoms. The general format is: connected([optional min # bonds], [optional max # bonds], [optional bond type], [optional atom expression]) Bond type may be any described for connect. See groups.txt for many examples of using connected() with define | | POLYHEDRA(n) | all central atoms for polyhedra with n vertices. | | SEARCH(pattern) | selects atoms that match SMARTS pattern such as "[C,N]" or "a". The pattern may be prefixed with any Jmol SMILES directives as described in Jmol SMARTS/SMILES. | | SMILES(smiles) | selects atoms if and only if there is only one model loaded and that model matches the SMILES string such as "CCC" (propane) or "c1ccccc1" (benzene). The pattern may be prefixed with any Jmol SMILES directives as described in Jmol SMARTS/SMILES. | | WITHIN(setName,atomExpression) | any atom within a given set. The setName can be any one of the words BOUNDBOX, CHAIN, ELEMENT, GROUP, MODEL, MOLECULE, POLYMER, SITE, or STRUCTURE, or it can be a protein or nucleic acid sequence expressed in single-letter notation surrounded by quotation marks as, for example, "GGCCCTT" or "MAACYXV" (in which case the sequence is found within the expression). (SITE refers to all crystallographic sites common to the specified atom set; BOUNDBOX refers to the smallest box containing the atom set.) Additional options, including "BASEPAIR", "SMILES", and "SMARTS", are discussed below. | | WITHIN(distance, withinAllModels, atomExpression) | any atom within the specified distance of any atom in the atomExpression. The optional TRUE/FALSE flag withinAllModels (by default FALSE) may be set TRUE to allow finding atoms in one model that may be within some distance of another model. If the distance is negative, then the operation applies to all atoms having normalized unit cell coordinates within the given distance of the designated atoms. If withinAllModels is TRUE, matching atoms within atomExpression itself are excluded. | | WITHIN(distance, {x y z}) | any atom within the specified distance of the given fractional or Cartesian coordinate. If the distance is negative, then the operation applies to all atoms having normalize unit cell coordinates within -distance of the designated atoms. | | WITHIN(distance, $surfaceObject) | any atom within the given distance of a point on the specified surface. | | WITHIN(x.x, VDW, {atomset}) | Selects atoms that have overlapping van der Waals surfaces with {atomset}. The distance parameter is optional, and its meaning depends upon its magnitude. If it is > 10, then it is assumed to be a percent, such as 110%, 100%, 90%; otherwise it is assumed to be a distance to be added to the van der Waals radii of both atoms under consideration. So, for example, select GROUPS within(1.4, VDW, {*:A}) selects all groups with solvent-accessible surfaces overlapping with chain A, and select GROUPS within(100, VDW, {ligand}) selects all groups "clashing" with any ligand. | | WITHIN(nResidues,GROUP,{atoms}) | groups that are within a given number of residues of a specified group of atoms. | | WITHIN(0,planeType, planeDesignation) | selects for any atoms within 0.01 Angstroms of a plane. If planeType is HKL, then planeDesignation is in the form {h k l}, where h, k, and l are Miller indices. If planeType is PLANE, then planeDesignation should be of the form @{plane(a,b,c)}, where a, b, and c are atom expressions or coordinates. | | WITHIN(distance,planeType, planeDesignation) | selects for atoms within the given distance in Angstroms from the plane. Positive distances are on one side; negative distances are on the other side. Experimentation may be necessary to determine which side is which for these purposes. In all cases the atoms in the plane itself (within 0.01 Angstroms of the plane on either side) are included. | | WITHIN(distance,$P) | where $P is a polyhedron ID. Options include on or within the polyhedron (distance == 0), angstroms within the polyhedron (distance < 0), and within distance angstroms of the polyhedron (distance > 0). | | WITHIN(ATOMNAME,"aa,bb,ccc") | any atom having a listed atom name | | WITHIN(ATOMTYPE, "atomType,atomType,..." | selects for atoms of one or more atom type. Atom type is defined in certain file types, including MOL2 model files and AMBER topology files. For other file types, atom types are the same as atom names. For example, select within(ATOMTYPE,"HW,OW") selects all water atoms an AMBER topology file. | | WITHIN(BASEPAIR("XY...") | finds all atoms within hydrogen-bonded DNA or RNA basepairs. Any number of pairs can be indicated. For example, display within(BASEPAIR,"GCAU") would select only G-C and A-U pairs. (Note that the RasMol-derived predefined sets "gc" and "at" refer simply to "G or C" and "A or T", respectively, and do not relate to base pairing.) | | WITHIN(BOUNDBOX) | selects all atoms within the currently defined boundbox | | WITHIN(BRANCH,{first atom}, {second atom}) | selects the second atom and all atoms in the molecular branch starting with the second atom but not including the first atom. | | WITHIN(DSSR,type) | For more information on this function, see JmolSQLforDSSR.pdf. Provided DSSR information is loaded, this function selects atoms within the given type of secondary structure of RNA or DNA. Options include bulges, coaxStacks (coaxial stacks), hairpins, hbonds, helices, iLoops (internal loops), isoCanonPairs (isocanonical pairs), junctions, kissingLoops, isolatedPairs, multiplets, nonStack, nts (nucleotides), pairs, ssSegments (single-stranded segments), stacks, and stems. For example, the following script produces a "3D stem diagram" for a nucleic acid:
load =1msy/dssr
set cartoonSteps
backbone -0.2
select within(dssr,"helices")
color blue
select within(dssr,"stems")
color red
select within (dssr,"ssSegments")
color white
select within (dssr,"multiplets")
color green
select within (dssr,"isolatedPairs")
color orange
select leadatom
spacefill 1.5
label $P%[group1]
font label 24 bold
set labeloffset 0 0
color label grey
In addition, the type may be followed by one of the following:
| .n | where n is a number starting with 1, to designate a specific region of that type: select within(dssr,"bulges.3") | | [SQL phrase] | to be more specific: select within(dssr,"pairs[WHERE name != 'WC']") |
| | WITHIN(HELIX) | Selects groups that would be selected using select helix but are not at either end of a helix section. | | WITHIN(SEQUENCE,"sequence") | a protein or nucleic acid sequence expressed in single-letter notation surrounded by quotation marks as, for example, "GGCCCTT" or "MAACYXV" (the entire sequence must be found; as indicated above, the keyword SEQENCE is optional). | | WITHIN(SHEET) | Selects groups that would be selected using select sheet but are not at either end of a sheet section. | | WITHIN(SMARTS,"smartsString") | all atoms that conform to the given SMARTS string are found. When used as a math function, this method returns a list of all matching sets of atoms; when used in a selection context (SELECT, DISPLAY, HIDE, etc.), all matching atoms are returned. Only hydrogen atoms that are explicitly indicated as [H] are returned. Extensive details on Jmol 3D-SEARCH SMARTS capability may be found on-line. | | WITHIN(SMILES,"smilesString") | all atoms that conform to the given SMILES string are found. When used as a math function, this method returns a list of all matching sets of atoms, including any indicated hydrogen atoms or hydrogen atoms required to complete the valence on an atom. When used in a selection context (SELECT, DISPLAY, HIDE, etc.), all matching atoms are returned. Note that for substructure searches, WITHIN(SMARTS,"smartsString") is recommended. | | WITHIN(UNITCELL) | selects atoms with fractional coordinates within the range [0, 1) and effectively returns the set of points that are periodic; atoms in models without unit cells will not be included | | WITHIN(UNITCELL,u) | where u is a math variable that is the result of the unitcell() function. (That is, u is an array [o a b c] of origin and three lattice vectors.) Same as within(unitcell), except uses the specified unitcell, regardless of the unit cell of the atom's model. | | WITHIN(unitid) | all atoms matching the given Unit ID. Unit IDs consist of nine fields separated by |:
pdbid|model|chain|RESNAME|resno|ATOMNAME|altcode|inscode|symmetry
They can be truncated on the right, but not the left: 1ehz|1|A|G|15, |1|A|G|15|C2. At a minimum, they require model number, chain, and residue number: |1|A||15. A blank ATOMNAME field specifies a full residue, with altcode indicating "this alt_id or no alt_id" (a configuration). A nonblank ATOMNAME field specifies one atom, with altcode indicating "exactly this alt_id" (a location). Unit IDs will be identified by their signature, disregarding white space, commas, "]", "[", and double quote: select within("1ehz|1|A|G|15||||,1ehz|1|A|U|59||||,1ehz|1|A|C|60|||"); |
RasMol biomolecular residue specifications back
The general specification of atoms in PDB "residues" follows the method used in RasMol. While the order of specifiers is somewhat flexible, the following order is generally applicable:
[residueType]seqRange ^insertionCode :chainLetter .atomName %altLoc /modelNumber
| [residueType] | [ALA] [G] [2E1] [L??] When used without any other specifiers it is possible in some but not all cases to leave off the brackets around the residue type. However, leaving off the brackets is not recommended and is known to fail when the residue type begins with a number. | | seqRange | 1 1-30 40- Note that ranges refer to physical ranges of data in the file. If residues corresponding to both the starting and ending residue numbers are not present in the file, selection returns no atoms. If residues with numbers between the starting and ending numbers are out of place in the file -- not physically between those two file positions -- they will not be included in the selection. If there is a desire to include such residues, or the selection should allow starting or ending residues to not be present, then use the resno comparison method instead. In this case, for example: select resno >=1 and resno <=30 or select resno >= 40. | | ^insertionCode | ^A ^B ^? | | :chainLetter | :A :B :? | | .atomName | .Ca .C? .? .?? | | %altLoc | %1 %A %? | | /modelNumber | /1 /2 /* refer to the number on the MODEL record in multimodel PDB files or the sequential number of the model in the file otherwise. When multiple files are loaded, these numbers refer to the file number, indicating "all models in that file." Specific models in specific files can be specified using a decimal notation: file.model as, for example, select *.CA/2.1 -- all alpha carbons in the first model of the second file listed in the load command. |
Wildcards back
Unspecified components of the atom specification are indicated in some cases using a question mark and in others using an asterisk.
For PDB files specifically, the wildcard * can be used in place of [residueType]seqRange to indicate "any." For example: select *.CA. Wildcards can be used elsewhere in the specification, but it is preferred simply to not include a specifier altogether. Thus, select [ALA].* is the same as select [ALA]. Note that in the case of PDB files and MOL2 files with residues indicated, * may be used in the form x* only in the case of residue names, not atom names. Thus, select AS* selects aspartate and asparagine. When used for an atom, for example, with the unremediated PDB file 1bkx select A.O?* the * is not wild and selects atoms A.O1* and A.O4*. (In remediated PDB files, this * becomes a single quote or "prime" character -- AO1', AO4'.) Asterisks cannot be used in place of insertionCode or altLoc.
Question marks are used to indicate "some character": select *.C??. Note that the number of question marks is significant. ".?" only finds atoms with single-letter names such as "O" and "C"; ".??" finds atoms with single-letter or double-letter names. The specification :?, ^?, and %? mean SOME chain, SOME insertion code or SOME alternate location; use :, ^, and % alone to indicate "atoms without chain indication," "atoms without insertion code," and "atoms without alternate location," respectively.
You can use \? to match an actual ? in an atom name. For instance, if there are two atoms, one with the name "O1" and one with the name "O1?" then select O1? will select both atoms, but select O1\? will select only the second atom. You cannot use \* to escape an actual * in an atom name.
For other file types, ? can be used anywhere in an atom name, and * can be used at the end of a name. To use * at the beginning of a name, use ?*, not just *.
General matching of atom names is not case sensitive. Note that the LIKE operator allows full support for standard use of ? and *, and it is case sensitive. So, for example: search atomName LIKE "*15".
Atom names for other file types back
Atom names can also be used for some non-PDB file types. For example, in CIF files, the atom_site_label field is used for the atom name. If an atom has the label "C34" you can select it using select *.C34 or select C34 or even select C*. Note that in this case, the wildcard * is no problem, since non-PDB file types do not include residue names, which might conflict with atom names. Similarly, Jaguar, NWChem, Tripos MOL2, Wavefunction Odyssey, SHELX, and Wavefunction Spartan files list atoms as "H3" and "O2". Atoms for these file types can be selected using these names, and the names can be displayed in labels using the format code %a. For file types such as XYZ that do not indicate a number with the atom symbol, Jmol constructs an atom name from the element symbol and the sequential number of the atom in the file.
|
See also:
|
[Jmol Command Syntax] [Jmol Math] [Jmol Parameters] [atom properties] [functions] [plane expressions] case default echo for if message reset set set (misc) switch while undefined |
top search index |
|
Over 120 atom properties can be selected or retrieved from model data, and most of these can be set as well. The older, more limited Rasmol notation [group].atomName^insertion:chain%altloc can still be used, but equally well one can combine any subsets of those using a more natural notation. For example, select group="ARG" and atomname="CA" and chain="A" is equivalent to select [ARG].CA:A. Mostly, the newer xxxx=y notation generalizes better in terms of additional parameters not unique to Rasmol. The comparison operators <, <=, =, >, >=, !=, and LIKE operate with many keywords. Note that = and != are not case-sensitive in Jmol, so select group="ARG" is the same as select group="arg". If you want to compare cases, use LIKE: select chain like "D". If you want to do case-sensitive string comparisons, use LIKE: select chain like "D". Note that LIKE is only for string comparison. select atomono like 3 returns nothing.
Atom properties may also be set directly using {atom expression}.xxxx = y. For example, {_H}.radius = 0 or {*}.radius = for(x;{*};x.adpmax - x.adpmin) or {*}.radius = {*}.temperature.all.mul(0.03). An associative array of all matching atom properties can be created using {atom expression}.xx?, where "xx" is the beginning of a property name, or even just {atom expression}.? for all atom properties. (for example, print {atomno=3}.a? or print @3.?).
Starting in Jmol 14.2, you can apply operations to arrays of values. For example, select atomno=[1,2,4] or display color !=["red","white"]. These can be read "select atoms for which the atomno is 1, 2, or 4" and "display all atoms for which the color is not red or white."
For labels, the %[xxx] notation extends the original single-character %x code of early Jmol versions. For example, label %[atomno] or label %8.2[xyz]. Within labels, %% will be interpreted as "%" to avoid its being treated as a special character. This is only needed in the rare case where its context could be interpreted as a variable token, for example, in label 30%x, if that needed to be displayed exactly like that for some reason.
The full list of atom properties is given below.
| property | select xxx=y | label %[xxx] | label %x | print {*}.xxx | {*}.xxx = y | description | | adpmax | yes | yes | | yes | | the maximum anisotropic displacement parameter for the selected atom | | adpmin | yes | yes | | yes | | the minimum anisotropic displacement parameter for the selected atom | | altloc | yes | yes | %A | yes | | PDB alternate location identifier | | altname | yes | yes | | yes | | an alternative name given to atoms by some file readers (for example, P2N) | | atomID | yes | yes | | yes | yes | special atom IDs for PDB atoms assigned by Jmol | | atomIndex | yes | yes | %D | yes | | atom 0-based index; a unique number for each atom regardless of the number of models loaded | | atomName | yes | yes | %a | yes | yes | atom name | | atomno | yes | yes | %i | yes | yes | sequential number; you can use "@" instead of "atomno=" -- for example, select @33 or Var x = @33 or @35 | | atomType | yes | yes | %B | yes | yes | atom type (mol2, AMBER files) or atom name (other file types) | | atomX | yes | yes | %x | yes | yes | Cartesian X coordinate (or just X) | | atomY | yes | yes | %y | yes | yes | Cartesian Y coordinate (or just Y) | | atomZ | yes | yes | %z | yes | yes | Cartesian Z coordinate (or just Z) | | bondcount | yes | yes | | yes | | covalent bond count | | bondingRadius | yes | yes | %I | yes | yes | radius used for autobonding, in Angstroms. Setting this value to 0 returns it to its default value. Synonymous with ionic and ionicRadius | | cell | yes | | | | | crystallographic unit cell, expressed either in lattice integer notation (111-999) or as a coordinate in ijk space, where {1 1 1} is the same as 555. ANDing two cells, for example select cell=555 and cell=556, selects the atoms on the common face. (Note: in the specifc case of CELL, only "=" is allowed as a comparator.) | | configuration | yes | | | | | Only in the context {configuration=n}, this option selects the set of atoms with either no ALTLOC specified or those atoms having this index into the array of altlocs within its model. So, for example, if the model has altloc "A" and "B", select configuration=1 is equivalent to select altloc="" or select altloc="A", and print {configuration=2} is equivalent to print {altloc="" or altloc="B"}. Configuration 0 is "all atoms in a model having configurations", and an invalid configuration number gives no atoms. (Note: in the specifc case of CONFIGURATION, only "=" is allowed as a comparator.) | | chain | yes | yes | c/s | yes | | protein chain. For newer CIF files allowing multicharacter chain specifications, use quotations marks: select chain="AA". For these multicharacter desigations, case is not checked unless the CIF file has lower-case chain designations. | | property | select xxx=y | label %[xxx] | label %x | print {*}.xxx | {*}.xxx = y | description | | chainNo | yes | yes | | yes | | chain number; sequentially counted from 1 for each model; chainNo == 0 means"no chain" or PDB chain identifier indicated as a blank. | | chirality | yes | yes | | yes | | Uses Cahn-Ingold-Prelog rules to assign the chirality designation (R, S, E, Z, r, s) to a carbon center. | | cipRule | yes | yes | | yes | | The CIP Rule that finally deciding the chirality of a center (1a-5). | | color | yes | yes | | yes | yes | the atom color | | covalentRadius | yes | yes | | yes | | covalent bonding radius, synonymous with covalent. Not used by Jmol, but could be used, for example, in {*}.spacefill={*}.covalentRadius.all. | | cs | yes | yes | | yes | | chemical shift calculated using computational results that include magnetic shielding tensors. | | element | yes | yes | %e | yes | yes | element symbol. The value of this parameter depends upon the context. Used with select structure=x, x can be either the quoted element symbol, "H", "He", "Li", etc. or atomic number. In all other contexts, the value is the element symbol. When the atom is a specific isotope, the string will contain the isotope number -- "13C", for example. | | elemno | yes | yes | %l (el) | yes | yes | atomic element number | | eta/theta | yes | yes | | yes | | Based on Carlos M. Duarte, Leven M. Wadley, and Anna Marie Pyle, RNA structure comparison, motif search and discovery using a reduced representation of RNA conformational space, Nucleic Acids Research, 2003, Vol. 31, No. 16 4755-4761. The parameter eta is the C4'[i-1]-P[i]-C4'[i]-P[i+1] dihedral angle; theta is the P[i]-C4'[i]-P[i+1]-C4'[i+1] dihedral angle. Both are measured on a 0-360 degree scale because they are commonly near 180 degrees. Using the commands plot PROPERTIES eta theta resno; select visible;wireframe only one can create these authors' "RNA worm" graph. | | file | yes | yes | | yes | | file number containing this atom | | formalCharge | yes | yes | %C | yes | yes | formal charge | | format | yes | yes | | yes | yes | format (label) of the atom. | | fXYZ | | yes | | yes | yes | fractional XYZ coordinates | | fX | yes | yes | %X | yes | yes | fractional X coordinate | | fY | yes | yes | %Y | yes | yes | fractional Y coordinate | | fZ | yes | yes | %Z | yes | yes | fractional Z coordinate | | fuXYZ | | yes | | yes | yes | fractional XYZ coordinates in the unitcell coordinate system | | fux | yes | yes | | yes | yes | fractional X coordinate in the unitcell coordinate system | | fuy | yes | yes | | yes | yes | fractional Y coordinate in the unitcell coordinate system | | fuz | yes | yes | | yes | yes | fractional Z coordinate in the unit cell coordinate system | | group | yes | yes | %n | yes | | 3-letter residue code | | group1 | yes | yes | %m | yes | | single-letter residue code (amino acids only) | | groupID | yes | yes | | yes | | group ID number: A unique ID for each amino acid or nucleic acid residue in a PDB file.
| 0 | noGroup
| | 1-5 | ALA, ARG, ASN, ASP, CYS
| | 6-10 | GLN, GLU, GLY, HIS, ILE
| | 11-15 | LEU, LYS, MET, PHE, PRO
| | 16-20 | SER, THR, TRP, TYR, VAL
| | 21-23 | ASX, GLX, UNK
| | 24-29 | A, +A, G, +G, I, +I
| | 30-35 | C, +C, T, +T, U, +U
|
Additional unique numbers are assigned arbitrarily by Jmol and cannot be used reproducibly. | | property | select xxx=y | label %[xxx] | label %x | print {*}.xxx | {*}.xxx = y | description | | groupindex | yes | yes | %G | yes | | overall group index | | hydrophobicity | yes | yes | | yes | | Aminoacid residue scale of hydrophobicity based on Rose, G. D., Geselowitz, A. R., Lesser, G. J., Lee, R. H., and Zehfus, M. H. (1985). Hydrophobicity of amino acid residues in globular proteins, Science, 229(4716):834-838. | | identify | yes | yes | %U | yes | | for a PDB/mmCIF file, a label such as [ILE]7^1:A.CD1%A/3 #47, which includes the group ([ILE]), residue number with optional insertion code (7^1), chain (:A), atom name (CD1), alternate location if present (%A), PDB model number (/3, for NMR models when one file is loaded; /file.model such as /2.3 if more than one file is loaded), and atom number (#47). For non-PDB data, the information is shorter -- for example, H15/2.1 #6, indicating atom name (H15), full file.model number (/2.1), and atom number (#6). If only a single model is loaded, %[identify] does not include the model number. | | insertion | yes | yes | %E | yes | | protein residue insertion code | | label | yes | yes | | yes | yes | current atom label (same as format) | | mass | yes | yes | | yes | | atomic mass -- especially useful with appended .max or .sum | | model | yes | yes | %M | yes | | model number | | modelindex | yes | yes | | yes | | a unique number for each model, starting with 0 and spanning all models in all files | | modO | | yes | | yes | | currently calculated occupancy from modulation (0 to 100; NaN if atom has no occupancy modulation) | | modXYZ | | yes | | yes | | currently calculated displacement modulation (for incommensurately modulated structures). Also modX, modY, modZ for individual components. For atoms without modultion, {xx}.modXYZ is -1 and {xx}.modX is NaN, and in a label %[modXYZ] and %[modX] are blank. | | molecule | yes | yes | %N | yes | | molecule number | | monomer | yes | yes | %g | yes | | monomer number (group number) in a polymer (usually a chain), starting with 1, or 0 if not part of a biopolymer -- that is, not a connected carbohydrate, amino acid, or nucleic acid (Jmol 14.3.15) | | ms | yes | yes | | yes | | magnetic shielding calculated from file-loaded tensors. | | nbo | | yes | | | | a resonance structure configuration found in an NBO .46 or .nbo file; requires the previous issuing of connect NBO. | | occupancy | yes | yes | %q/%Q | yes | yes | CIF file site occupancy. In SELECT command comparisons ("select occupancy < 90"), an integer n implies measurement on a 0-100 scale; also, in the context %[occupancy] or %q for a label, the reported number is a percentage. In all other cases, such as when %Q is used in a label or when a decimal number is used in a comparison, the scale is 0.0 - 1.0. | | partialCharge | yes | yes | %P | yes | yes | partial charge | | phi | yes | yes | %f | yes | | protein group PHI angle for atom's residue | | polymer | yes | yes | | yes | yes | sequential polymer number in a model, starting with 1. | | polymerLength | yes | yes | %L | yes | | polymer length | | property_xx | yes | yes | | yes | yes | a property created using the DATA command | | psi | yes | yes | %p | yes | | protein group PSI angle for the atom's residue | | radius | yes | yes | | yes | yes | currently displayed radius -- In SELECT command comparisons ("select radius=n"), integer n implies Rasmol units 1/250 Angstroms; in all other cases or when a decimal number is used, the units are Angstroms. | | property | select xxx=y | label %[xxx] | label %x | print {*}.xxx | {*}.xxx = y | description | | resno | yes | yes | %R | yes | | PDB residue number, not including insertion code (see also seqcode, below) | | selected | yes | | | yes | yes | 1.0 if atom is selected; 0.0 if not | | sequence | yes | yes | | yes | | PDB one-character sequence code, as a string of characters, with "?" indicated where single-character codes are not available | | seqcode | yes | yes | %r | yes | | PDB residue number, including insertion code (for example, 234^2; "seqcode" option added in Jmol 14.3.16) | | seqid | yes | yes | | yes | | (mmCIF only) the value from _atom_site.label_seq_id; a pointer to _entity_poly_seq.num in the ENTITY_POLY_SEQ category specifying the sequence of monomers in a polymer. Allowance is made for the possibility of microheterogeneity in a sample by allowing a given sequence number to be correlated with more than one monomer id. (Jmol 14.2.3) | | shape | yes | yes | | yes | | hybridization geometry such as "tetrahedral" | | site | yes | yes | %S | yes | | crystallographic site number | | spacefill | yes | yes | | yes | yes | currently displayed radius | | straightness | yes | yes | %T | yes | | quaternion-derived straightness (second derivative of the quaternion describing the orientation of the residue. This quantity will have different values depending upon the setting of quaternionFrame as "A" (alpha-carbon/phosphorus atom only), "C" (alpha-carbon/pyrimidine or purine base based), "P" (carbonyl-carbon peptide plane/phosphorus tetrahedron based), or "N" (amide-nitrogen based). The default is alpha-carbon based, which corresponds closely to the following combination of Ramachandran angles involving three consecutive residues i-1, i, and i+1: -psii-1 - phii + psii + phii+1. | | strucno | yes | yes | | yes | | a unique number for each helix, sheet, or turn in a model, starting with 1. | | structure | yes | yes | | yes | | The value of this parameter depends upon the context. Used with select structure=x, x can be either the quoted keyword "none", "turn", "sheet", "helix", "dna", "rna", or "carbohydrate" or a respective number 0-6. In the context {*}.structure, the return value is a number; in the context label %[structure], the return is one of the six keywords. | | substructure | yes | yes | | yes | | like structure, the value of this parameter depends upon the context. Used with select substructure=x, x can be either the quoted keyword "none", "turn", "sheet", "helix", "dna", "rna", "carbohydrate", "helix310", "helixalpha", or "helixpi", or the respective number 0-9. In the context {*}.substructure, the return value is a number; in the context label %[substructure], the return is one of the nine keywords. | | surfacedistance | yes | yes | %u | yes | | A value related to the distance of an atom to a nominal molecular surface. 0 indicates at the surface. Positive numbers are minimum distances in Angstroms from the given atom to the surface. The "surface" is not a surface, per se. It is a set of geodesic points using SET dotDensity 1;DOTS 3.0. Atoms that contribute one or more dots to this geodesic are given a value of 0; other atoms are checked for distance to each dot, and assigned that distance - 3.0. | | sXYZ | | yes | | yes | | screen XYZ coordinates, in pixels from the left, bottom, and camera, respectively | | sX | yes | yes | | yes | | screen X coordinate, in pixels from the left | | sY | yes | yes | | yes | | screen Y coordinate, in pixels from the bottom | | sZ | yes | yes | | yes | | screen Z coordinate, 0 at the camera, increasing with depth | | symop | yes | | | yes | | the first symmetry operation code that generated this atom by Jmol; an integer starting with 1. See also symmetry, below. This operator is only present if the file contains space group information and the file was loaded using the {i, j, k} option so as to generate symmetry-based atoms. To select only the original atoms prior to application of any symmetry (including no lattice translations), use NOT symmetry. Alternatively, one can use SYMOP=1555, corresponding to "x,y,z" and without any lattice translations.
The general form select SYMOP=nijk selects a specific translation of atoms from the given crystallographic symmetry operation, with ijk = 555 meaning "no additional translations. Comparators <, <=, >, >=, and != can be used and only apply to the ijk part of the designation. Note that the ijk values are relative, not absolute. Thus, symop=2555 selects for atoms that have been transformed by symop=2 but not subjected to any further lattice translation. Be aware that other than 1ijk, the result of this operation depends upon how the model was loaded. If the model was loaded using load "filename.cif" {444 666 1}, where the 1 indicates that all symmetry-generated atoms are to be packed within cell 555 and then translated to fill the other 26 specified cells, then select symop=3555 is the same as select symop=3 and within(unitcell). However, the situation is different if instead the model was loaded using load "filename.cif" {444 666 0}, where the 0 indicates that symmetry-generated atoms are to be placed exactly where their symmetry operator would put them, with x,-y,z being different then from x, 1-y, z. In that case, select symop=3555 is for all atoms that have been generated using symmetry operation 3 but have not had any additional translations applied to the x,y,z expression found in the CIF file.
If, for example,
load =ams/quartz 1 {555 555 0}
select on silicon and symop=4555
selects for the atom at {-0.4697 -0.4697 1/3}, the result of the operation -x,-x+y,-z+1/3 on the CIF file fractional coordinate (0.4697 0 0). But
load =ams/quartz 1 {555 555 1}
select on silicon and symop=4555
(or load =ams/quartz 1 PACKED) selects for the atom at {0.5303 0.5303 1/3}, the result of the normalized operation -x+1,-x+y+1,-z+1/3 on the same CIF atom.
Note that atoms in special positions will have multiple operator matches. Atoms in special positions can be selected using the boolean atom expression term SPECIALPOSITION, as in select specialposition or x = {specialposition}. | | property | select xxx=y | label %[xxx] | label %x | print {*}.xxx | {*}.xxx = y | description | | symmetry | | yes | %o/%O | yes | | as "symmetry" or in a label as lower-case "o" gives list of crystallographic symmetry operators generating this atom with lattice designations,such as 3555; upper-case "%O" in a label gives a list without the lattice designations. See also symop, above. | | temperature | yes | yes | %b/%t | yes | yes | temperature factor (B-factor) | | translucent | yes | | | yes | | 0.0 to 1.0, with 0 being opaque and 1 being transparent | | unitid | | yes | | | | Unit ID. Unit IDs consist of nine fields separated by |. unitid is allowed specfically in the %[unitid-MODE] context, where -MODE is a flag to indicate what aspects of the Unit ID to express:
| unitid | same as unitid-ra | |1|A|G|1|OP1|||
| | unitid-ra | include chain, residue, and atom | |1|A|G|1|OP1|||
| | unitid-r | chain,residue only | |1|A|G|1||||
| | unitid-mr | PDB model,chain,residue | 1EHZ|1|A|G|1||||
| | unitid-mra | full unitID | 1EHZ|1|A|G|1|OP1|||
| | unitid-mrat | full unitID, right-trimmed | 1EHZ|1|A|G|1|OP1
|
Note that the use of unitid is not just for display. You can also generate them using {xxx}.label("%[unitid]") and use them in searching DSSR data structures. | | uXYZ | | yes | | yes | | unit cell XYZ coordinates | | uX | yes | yes | | yes | | unit cell X coordinate normalized to [0,1) | | uY | yes | yes | | yes | | unit cell Y coordinate normalized to [0,1) | | uZ | yes | yes | | yes | | unit cell Z coordinate normalized to [0,1) | | valence | yes | yes | | yes | yes | the valence of an atom (sum of bonds, where double bond counts as 2 and triple bond counts as 3 | | vanderwaals | yes | yes | %V | yes | yes | van der Waals radius | | vectorScale | yes | yes | | yes | | vibration vector scale | | volume | yes | yes | | yes | | approximate van der Waals volume for this atom. Note, {*}.volume gives an average; use {*}.volume.sum to get total volume. | | vXYZ | | yes | %v | yes | yes | vibration vector, or individual components as %vx %vy %vz. For atoms without vibration vectors, {xx}.vXYZ is -1; in a label, %[vXYZ] is blank. | | vX | yes | yes | | yes | yes | vibration vector X coordinate; for atoms without vibration vector, {xx}.vX is NaN (same for vY and vZ) | | vY | yes | yes | | yes | yes | vibration vector Y coordinate | | vZ | yes | yes | | yes | yes | vibration vector Z coordinate | | x | yes | yes | %x | yes | yes | Cartesian X coordinate | | y | yes | yes | %y | yes | yes | Cartesian Y coordinate | | z | yes | yes | %z | yes | yes | Cartesian Z coordinate | | xyz | | yes | | yes | yes | Cartesian XYZ coordinates; select xyz > 1.0 selects atoms more than one Angstrom from the origin. | | | | | %W | | | PDB residue designator with x, y, z included: [%n]%r %x %y %z |
|
See also:
|
[Jmol Command Syntax] [Jmol Math] [Jmol Parameters] [atom expressions] [functions] case default echo for if message reset set set (misc) switch while undefined |
top search index |
x = f(y) functions
coordinate transforming .xxx functions
general .xxx functions
[array].xxx or .propertyName.xxx modifiers
{atomExpression}.propertyName
x.f(y) functions
item-selector [i][j]
user-defined functions
special variables for functions
customized command functions
|
Jmol math allows for two general syntaxes for functions, x = f(y) and x.f(y). The first simply operate on their given parameters. For example, x = load("myfile.dat") loads the variable x with the contents of the file "myfile.dat". The second operate on the elements of a variable individually in some way and are referred to here as item selector functions. In the listings below, these functions all begin with a period character. For example, x = {carbon}.bonds operates so as to deliver the bond set associated with the carbon atoms; x = "this is a test".replace("s","S") operates on the individual characters of the string "this is a test"; x = {oxygen}.label("%U") assigns x the list of labels for the oxygen atoms in the model. Some functions can be used in both contexts. For example, x = distance({oxygen}, {carbon}) delivers the distance from the CENTER of the oxygens to the CENTER of the carbons. x = {oxygen}.distance{carbon} delivers the AVERAGE distance of an oxygen atom to the CENTER of the carbons. These are subtly different. Some functions require parentheses; some do not. Basically, if a function CAN have parameters, for example, .join(), .split(), or .label(), then it MUST have at least empty (); if a function CANNOT have parameters, for example, .atoms, .bonds, or .ident, then it NEVER uses parentheses.
x = f(y) functions back
Several of these functions are described more fully under the heading atom expressions, as they can also be used in commands such as select and display.
| x = abs(y) | the absolute value of y | | x = acos(y) | the arccosine of y, in degrees in the range 0 to 180 . | | x = angle(a,b,c) | the a-b-c angle, where a, b, and c can be points or atom sets. | | x = angle(a,b,c,d) | the dihedral angle a-b-c-d is measured. | | x = cache() | returns an array describing the contents of the file cache in the format {filename: nBytes, filename: nbytes,...} | | x = color(color1,color2,nColors,asHSL) | Returns a color scheme string spanning the distance between color1 and color2 with nColors colors. The last parameter, asHSL, if TRUE does the gradient in terms of hue, saturation, and lightness (HSL), which is better for cross-color gradients such as red-to-blue; if FALSE, uses RGB, which is better for single-color gradients such as white to red. The standard Jmol "rgb" color scheme is very close to color("red","blue",33,true). Once a variable is defined as a color scheme string, it can be used in commands such as color property temperature @x and isosurface vdw map property temperature colorScheme @x. | | x = color(schemeName, min, max) | (Note: To get just the {r g b} color value of a named color, use the .color function rather than the function described here: print "red".color reports {255.0 0.0 0.0}.) Coloring by atom property and mapping of isosurfaces utilize mapped color schemes, which are sets of colors that are associated with given ranges of values. The color function returns information relating to these schemes. The basic form of the function, with one or three parameters returns an associatvie array describing a color scheme such as "rwb" or "roygb" that has been mapped from value min to value max with the keys listed below. If schemeName is "", then the current property scheme (default "roygb") is used.) The parameters min and max are optional and, if absent, will take the numbers 1 and N, where N is the number of colors in the color scheme if no property has been mapped, or the most recent range of values, if a property has been mapped.
| "colors" | an array of points giving {r g b} on a 0 to 255 scale | | "max" | the maximum value being mapped | | "min" | the minimum value being mapped | | "name" | the name of the color scheme | | "reversed" | TRUE if min > max | | "values" | an array of values associated with the two ends and each boundary between individual color of the scheme. (Note that if there are N colors, then there will be N + 1 values.) |
Thus, for example, print color("rwb", 0, 100)["colors"][1] prints the first color of the color scheme, and print color("rwb", 0, 100)["values"][0] prints the last value (max). | | x = color(schemeName, min, max, value) | Returns a color as {r g b} on a 0 to 255 scale from a specified color scheme that has been mapped using the specified minimum and maximum values. For example: print color("rwb", 0, 100, 30) returns {255.0 144.0 144.0}. | | x = color("toHSL",RGBcolor) | From an RGB color expressed as a point, {100 50 100} or color(100, 50, 100), or a hex name such as "[xFF00FF]", or a JavaScript color name such as "chartreuse", returns an {h s v} point with hue ranging from 0 to 360, saturation ranging from 0 to 100, and lightness ranging from 0 to 100. | | x = color("toRGB",colorNameOrHSLcolor) | From a color name or hex code such as [xFF00FF] or an HSL color expressed as a point, {100 50 100} or using color(100, 50, 100), returns an {r g b} point with red, green, and blue ranging from 0 to 255. (Note that you can also use colorName.color to get the color of a JavaScript color: print "red".color, for example.) | | x = color("$isosurfaceID") | Returns the color scheme associative array (see above) associated with this isosurface. | | x = color("$isosurfaceID", value) | Returns the color as {r g b} associated with the given value of a mapped isosurface. | | x = compare({atomset1}, {atomset2}) | Returns a 4x4 matrix that gives the optimal rotation (x%1) and translation (x%2) to superimpose the atoms in {atomset1} onto the atoms in {atomset2} using the closed-form quaternion method. One or the other or both of the atom sets may be replaced by an array of points. The number of atoms/points must be the same in each set, or "NaN" will be returned instead. | | x = compare({atomset1}, {atomset2}, "stddev") | Returns the standard deviation of atom positions for the optimal rotation and translation to superimpose the atoms in {atomset1} onto the atoms in {atomset2}. The number of atoms must be the same in each set, or "NaN" will be returned instead. | | x = compare({atomset1}, {atomset2}, "ISOMER") | Carries out a comparisons of atoms in the two atom sets and returns one of the following strings:
| CONSTITUTIONAL ISOMERS | having the same molecular formula but not the same connectivity | | ENANTIOMERS | configurationally enantiomeric (mirror images) | | DIASTERIOMERS | differing in one or more stereocenters (including double bonds) | | CONFORMATIONAL ISOMERS | having the same constitution and configuration, but differing significantly in conformation (having root-mean-square deviations greater than a threshold value | | IDENTICAL | the same, constitutionally, configurationally, and conformationally | | NONE | no relationship |
| | x = compare({atomset1}, {atomset2}, "SMARTS", SMARTSstring) | Uses a SMARTS (substructure) description to find the first instance of atoms in the first structure that correlate one-for-one with atoms in the second structure, then finds the rotation and translation that best aligns them. Returns a 4x4 matrix. | | x = compare({atomset1}, {atomset2}, "SMARTS", SMARTSstring, "stddev") | Same as above, but returns the standard deviation. | | x = compare({atomset1}, {atomset2}, SMARTSstring, "BONDS") | Carries out a SMARTS match (or SMILES if the string is "SMILES" itself) on the two atom sets. Returning an array of n*6 elements, where n is the number of dihedral angle matches. Each set of six elements indicates the four atoms involved in the dihedral, the angle in the first atom set, and the angle in the second atom set. If there is no match, the string "NaN" is returned. This function is run internally by Jmol when carrying out flexible fits using the compare command and the BONDS option. | | x = compare({atomset1}, {atomset2}, "SMILES", SMILESstring) | Same as "SMARTS", but does a whole-molecule comparison. | | x = compare({atomset1}, {atomset2}, "SMILES", SMILESstring, "stddev") | Same as "SMARTS", but does a whole-molecule comparison. | | x = compare({atomset1}, {atomset2}, "MAP", SMILESstring)[1] | Reports a mapping of atoms in one model to the atoms in another model, using SMILES. The result is array of [a1 a2] correlations, ordered by atom position in the SMILES string. a1 and a2 are atomIndex values. (AtomIndex is zero-based, running from the first atom of the first-loaded model to the last atom of the last-loaded model.) | | x = connected(...{atomSet}) | See the discussion of connected() at atom expressions. | | x =connected(...{atomset1}, {atomset2}) | Specifying two atom sets in a CONNECTED function returns the bond set [{...}] including all such bonds. This bond set can be selected, colored, sized using wireframe, and hidden or displayed. | | x = connected({bondSet},...) | returns a subset of the specified bonds that match additional criteria, for example: x = connected({*}.bonds, "DOUBLE");connect @x radius 0.1 or x = connected({*}.bonds, 1.3, 1.5);color @x blue. | x = contact({atomset1}, {atomset2})
x = contact(nPercent, {atomset1}, {atomset2})
x = contact(distance, {atomset1}, {atomset2}) | returns the atoms in {atomset2} within van der Waals contact of {atomset1}. {atomset2} is optional and defaults to "not atomset1". Optional parameters include a percent van der Waals radius expressed as an integer or a distance in Angstroms do be added to the van der Waals radius, expressed as a decimal number. | | x = cos(y) | the cosine of y, where y is in degrees. | | x = cross(a,b) | the cross product of two vectors or points. | | x = data({atomset},type) | creates model file data of the type "MOL", "PDB", or "XYZ" for the selected atom set. Starting with Jmol 14.4, if type is lower case "xyz", then only the atom data lines are written, not the header lines of the XYZ file format. | | x = data({atomset},type,TRUE) | Adding a third parameter TRUE specifies that all trajectories should be returned. | | x = data("dataset_name") | places the text of the data set created using the data command into variable x. | | x = data(stringData,fieldOrColumn,columnCount,firstLine) | separates stringData into lines, then reads lines starting from firstLine (1 being the first line). Data are read from free-format field or column fieldOrColumn. If the data are free-format, then set columnCount = 0, otherwise columnCount indicates the number of columns to read for each data point. The data() function returns a newline-separated list, which can be read directly into atomic properties, for example, using {*}.partialCharge = data(load("mydata.mol2"),9,0,7). | | x = data("xxx*") | returns an array of data keys starting with "xxx". For instance,
x = data("property_MYKEYS_*") to retrieve all your custom keys
then y = data(x[1]) would return the data for the first item in the array of keys | | x = distance(a,b) | The distance from the geometric center of a to the geometric center of b, where a and b are atom expressions, coordinates, or planes. | | x = dot(a,b) | the dot product of two vectors (or points). | | x = eval(expr) | indirect evaluation of a Jmol math expression. | | x = eval("JSON",json) | evaluate a JSON string to give an associative or serial array; for the reverse, see format("JSON",data) | | x = file("filename") | the full path to the indicated file name. Note that file("?") displays a file dialog, which allows the user to navigate to a different directory, and file("") returns the full path to the current default directory. | | x = format("ARRAY",data) | Makes a copy of the data in array form, turning string and byteArrays into integer arrays based on characters or bytes, respectively. | | x = format("BYTEARRAY",data) | Copies the data into a byteArray. Data may be an array, a byteArray, a string, or a base64-encoded array. | | x = format("BASE64",data) | Generates base64 code for data contained in a variable, prepending the string with ";base64,". | | x = format("JSON",data) | Generates JavaScript Object Notation (JSON) code for data contained in a variable; for the reverse, see eval("JSON",json). | | x = format(sprintfFormat, a, b, c, ...) | This function creates a string using a format similar to that used in C++ to format a set of variables into a string with special codes that start with %. While not an exact implementation of this format, there are strong similarities. Here a, b, and c are variable names, and sprintfFormat is the format string containing a %n.mX code for each variable. As for labels, n and m indicate column formatting and precisions. Both n and .m are optional. Here, X indicates the variable type , whereas in, for example, {*}.label("%a"), X represents an atom property, and the type of formatting is determined automatically from that. The options for X include:
| i or d | integer. Either i or d can be used synonymously. | | f | float/decimal. A negative value for m indicates to use scientific notation with a total of -m digits. The default is full width, full precision. | | e | exponential (scientific notation). "%8.3e" is equivalent to "%8.-3f". | | p | point. Each of the three coordinates is formatted according to the specified width and precision. The default is %6.2p. | | q | quaternion/plane/axisangle. Each of the four elements of the vector {x y z w} are formatted according to the specified width and precision. The default is %6.2q | | s | string. Values for precision, m, determine maximum number of characters starting from the left (m > 0) or right (m < 0). So, for example, print format("%0.-3s","testing") prints "ing". |
For example: calculate straightness;print format("average straightness = %4.2f", {*}.straightness) | | x = getProperty(infotype,parameters...) | The property of the given infotype is returned as a Jmol math list; print getProperty() by itself giving the list of available types. Each property type has its own intrinsic structure, but in general the parameters may include an initial atom set specification followed by one or more key values and, in the case of arrays, an item selector. For example,
print getProperty("boundboxInfo","center")
x = getProperty("atomInfo",{atomno=3})
x = getproperty("bondInfo",{*},2,"atom1", "sym")
| | x = getProperty("cifInfo",CifFileName) | Retrieve the full CIF metadata structure from a CIF file in the form of a Jmol associative array. If no file name is given, the metadata is from the current model's file. See getProperty CIFInfo for details. | | x = getProperty("JSON",infotype,parameters...) | An optional format "JSON" may be included in the getProperty function as the first parameter to indicate that the data should be converted to JSON format. The JSmol call from JavaScript Jmol.evaluateVar(app,expr) uses the getProperty method to evaluate an expression and return its value in JavaScript format, via JSON. | | x = getProperty(array,query) | Use JmolSQL to extract information from a serial or associative array. | | x = hkl(a,b,c) | generates the plane associated with a given set of Miller plane indices. | | x = intersection(plane1, plane2) | returns the line of intersection between two planes in the form of an array: [point,vector] or "" if the planes are parallel. | | x = intersection(point,plane) | returns the nearest point on a plane to a given point. | | x = intersection(point,vector,plane) | returns the point of intersection of a plane with a line trough the given point with in the direction of the given vector. | | x = intersection(point1, vector1, point2) | returns the nearest point to point2 on the line through point1 along the vector vector1. | | x = intersection(point1, vector1, point2, radius2) | returns an array of 0 to 2 points of intersection of a line through point1 along vector1 with a sphere of radius radius2 centered on point2 | | x = javascript("...") | returns the result of evaluating the specified JavaScript. Applet only; disallowed if the applet has been started with Info.allowJavaScript = false. | | x = javascript("...") | returns the result of evaluating the specified JavaScript. Applet only; disallowed if the applet has been started with Info.allowJavaScript = false. | | x = label(...) | See x = format(...), above. | | x = load("filename") | Load the data from the specified file into variable x. | | x = load("filename","JSON") | loads JSON data into a variable | | x = load("filename", nBytesMax) | Load the data from the specified file into variable x, but no more than the specified number of bytes. Since this function returns "java.io.FileNotFoundException: ..." when working from a local drive, the function x = load("filename", 0) can be used to test for the existance of a file. If the function returns the empty string "", then the file exists; if it returns an error message, then the file does not exist. So, for example, the following code loads a PDB file from the RCSB only if not found on the local drive:
if (load(pdbid + ".pdb", 0) == "") {load @{pdbid + ".pdb"} } else {load @{"=" + pdbid} }
| | x = load("filename",TRUE) | Adding a second parameter TRUE creates a binary associative array variable x that contains the contents of the file. Data are stored as raw bytes (but will appear as a string in the PRINT command). If the file is a standard file, the key "_DATA_" will hold the file data. If the file is a PNGJ file, the key "_IMAGE_" will hold the image data and additional files will be keyed by file name. If the file is a zip file, the files will be keyed by file name, but no "_IMAGE_" key will be present (presumably). Note that x = load("myfile") without TRUE loads just the file list for PNGJ or ZIP files, not the actual data. | | x = matrix(source) | Creates a 3x3 or 4x4 matrix from several sources, including strings and arrays.
| | matrix("x-y+1/2,x+y,z") | 4x4 from row-based string | | matrix("a+b+1/2,b-a,c") | 4x4 from column-based string | | matrix(spacegroupName) | returns the 4x4 transformation matrix (P,p) for the given space group setting. Name can be space group number 1-230, a "number.setting" such as 12.1 or 12.2, a Hermann-Mauguin name, or a Hall symbol. For example, print matrix("A2/m").format("abc") reports -a-c,b,a. | | matrix("a+b,b-a,c;1/2,0,0") | 4x4 from International Tables transform(P,p) notation, col-based | | matrix([1,2,3,4,5,6,7,8,9]) | 3x3 from array[9] | | matrix([1,2,3] [4,5,6] [7,8,9]) | 3x3 from array[3][3] | | matrix([1,2,3,4,5,6,7,8,9,0,1,2,3,4,5,6]) | 4x4 from array[16] | | matrix([1,2,3,4] [5,6,7,8] [9,0,1,2] [3,4,5,6]) | 4x4 from array[4][4] |
For example, transforming a point from one basis to another:
P = matrix("c,a,b;1/2,0,0");
f = {0.5 0.25 0.5};
print P*f;
{0.75 0.5 0.5}
| | x = matrix(..., "abc") | Adding "abc" expresses the matrix as a string in column format. Accepts all options discussed above as well as a matrix as first parameter. | | x = matrix(source, "abc") | returns the string form of a 4x4 matrix in abc column format. For eample, "a,b,c+1/2". | | x =matrix(source, "xyz") | returns the string form of a 4x4 matrix in xyz row format. For eample, "x,y,z+1/2". | | x = matrix("!b,c,a > a-c,b,2c;0,0,1/2 > a,-a-c,b") | Calculates the overall transformation for a CLEG chain; same as matrix("!b,c,a")*matrix(">a-c,b,2c;0,0,1/2")*matrix("a,-a-c,b"). Also works with x,y,z (rows rather than columns). | | x = measure(source) | The measure function requires from two to four atom expressions and/or points in space and returns associated measurements in a string, one measurement per line. Additional optional parameters include minimum and maximum ranges, the designations "connected" or "notConnected", the units "nm", "nanometers", "pm", "picometers", "angstroms", "ang", or "au", and a format string in quotes similar to that used by the measure command. | | x = now() | returns the time in milliseconds since some old date; can be used for timing scripts. | | x = now(n) | (n integer) returns the number of milliseconds since time n: x = now();.......;print now(x);. | | x = now(msg) | (String msg) returns the date in the Java SimpleDate format "EEE, d MMM yyyy HH:mm:ss Z" followed by tab and the message. | | x = now(msg, format) | (String msg) returns the date in the specified Java SimpleDate format followed by a tab and the message. Special formats include "iso8601" ("yyyy-MM-dd'T'HH:mm:ss") and "iso8824" ("D:YYYYMMddHHmmssX'00'"). Note: With JSmol prior to Jmol 15, if the format is provided, it must be one of these two special formats. | | x = pattern(smarts) | compiles a SMARTS pattern for later use. Used along with search(atomset) and the search(target,pattern) or {atomset}.search(pattern) functions. For example:
load $caffeine
x = search({*})
y = pattern('NCN')
foundAtoms = search(x, y)
| | x = plane(pt1, pt2) | the plane that bisects the line connecting pt1 and pt2. | | x = plane(pt1, pt2, f) | the plane perpendicular to the line connecting pt1 and pt2 and containing the point that is fraction f of the way from pt1 to pt2. | | x = plane(pta,ptb,ptc,ptd) | creates an {x y z w} plane from the first three points, and assigns the signs of x, y, z, and w to correspond to a positive distance to ptd as measured with the distance() function. Parameters may be mathematical expressions. | | x = plane(a, b, c, d) | creates the four-vector {a b c d}, which represents a plane satisfying the equation ax + by + cz + d = 0 | | x = plane("{a b c d}") | creates an plane satisfying the equation ax + by + cz + d = 0 from a string equivalent. As for all Jmol math expressions, parameters may be mathematical expressions. | | x = plane(pta,ptb,ptc) | creates an {x y z w} plane through the three given points, which may themselves be mathematical expressions that evaluate to {x y z} points or atom expressions. | | x = plane(r,theta,phi) | generates a plane that is perpendicular to the vector from {0 0 0} to the point defined by the given r, theta, and phi. The vector is generated by sequential rotation of a vector along the Z axis first by phi around the X axis, then by theta around the Z axis: v = R[z,theta]R[x,phi]{0 0 r}. | | x = point(a,b,c) | Creates an {x y z} point. Parameters may be mathematical expressions. | | x = point({x,y,z}, true) | gives the screen coordinates {sx, sy, sz} corresponding to the 3D coordinates {x, y, z}. | | x = point({sx,sy,sz}, false) | gives the 3D coordinates {x, y, z} corresponding to the screen coordinates {sx, sy, sz}. | | x = point("{x,y,z}") | creates an {x y z} point from the string equivalent. | | x = point("(x,y,z)") | creates a point from the string equivalent where the string contains fractions such as 1/2 or other mathematical expressions. The opposite of {x,y,z}.rxyz. | | x = point(["{1,2,3}" ,"{2,3,4}", ...]) | Create an array of points from an array of string equivalents. | | x = point(x) | Rounds x down (toward 0) to the nearest integer. Note that x%0 rounds+I18 to the NEAREST integer value, instead. | | x = point(unitcell, {i, j, k}) | returns the Cartesian point corresponding to a specific coordinate in a unit cell system. unitcell is an array of the form [origin, va, vb, vc]. {i j k} is a point in fractional coordinates. Does not require actual setting of the model's unit cell. | | x = pointgroup([array of points],center) | Analyzes the point group of a set of points; center is optional and defaults to the geometric center of the array of points. Creates a map with and extensive list of keys, including (if appropriate): C2, C3, Ci, Cs, S6, detail, distanceTolerance, linearTolerance, nAtoms, nC2, nC3, nCi, nCn, nCs, nS6, nSn, nTotal, name, points, principalAxis, and principalPlane. | | x = pointgroup("spacegroup",@1) | Analyzes the point group (crystal class) of a crystal using three irrational coordinate points to generate all possible operators. Creates a map with and extensive list of keys, including (if appropriate): C2, C3, Ci, Cs, S6, detail, distanceTolerance, linearTolerance, nAtoms, nC2, nC3, nCi, nCn, nCs, nS6, nSn, nTotal, name, points, and principalAxis, and principalPlane. | | x = polyhedra(); x = polyhedra(n) | the atom centers for all polyhedra or polyhedra with a specific number of vertices, respectively. | | x = polyhedra(smilesString); x = polyhedra(smartsString) | These two functions can be used search for matching polyhedra (atom environments), either topologically (using a SMARTS string; only *) or including atom identity (SMILES string; with atom names). An atom set is returned. Note that the SMILES and SMARTS strings created by Jmol in association with polyhedra describe the connectivity of the faces and do not include the central atom itself. | | x = prompt(message) | displays a pop-up message box and waits for the user to press OK. | | x = prompt(message,defaultInput) | displays an input dialog allowing the user to enter some text and press OK (or ESCAPE to cancel). If canceled, returns "null". | | x = prompt(message,buttonText,TRUE) | displays a message box with buttons and returns the label of the button that was pressed. The parameter is a list of button labels separated by |, for example: "Yes|No" or "OK|cancel" or "Spacefill|Wireframe|Ball&Stick". | | x = prompt(message,buttonArray) | displays a message box with buttons based on the values in the array parameter and returns an integer indicating which button was pressed (starting with 1, or -1 if ESCAPE was pressed). | | x = quaternion() | The current model rotation in the form of a quaternion. Same as x = quaternion(script("show rotation")) | | x = quaternion("best") | The "best" model rotation in the form of a quaternion. Same as x = quaternion(script("show best rotation")) | | x = quaternion({x y z},theta) | the quaternion {x y z w} associated with a rotation of theta degrees (counter-clockwise) around axis {x y z}. {x y z} need not be a unit vector -- Jmol will normalize it automatically. | | x = quaternion("{x y z w}") | the unit quaternion {x y z w} produced by normalizing the specified quaternion. That is, where theta is the rotation angle, and q0 = w = cos(theta/2), {x y z} = sin(theta/2) * unitNormal. | | x = quaternion(q0, q1, q2, q3) | the unit quaternion {x y z w} produced by normalizing the specified quaternion. Note that q0 is first in the list of parameters, even though Jmol will store the quaternion in the form {q1/f, q2/f, q3/f, q0/f} where f is sqrt(q0*q0 + q1*q1 + q2*q2 + q3*q3). | | x = quaternion({m00 m10 m20}, {m01 m11 m21}) | the unit quaternion corresponding to the rotation matrix having the first two column vectors indicated. | | x = quaternion({center},{x-axis point}, {xy-plane point}) | the unit quaternion associated with a frame that has a center at the first parameter position, an x axis in the direction of the second parameter position, and a y axis in the plane of the three parameter positions. These parameters may be atom expressions. For example, x = quaternion({215.CA},{215.C},{215.N}) creates the "standard" quaternion for residue 215. The z axis will be generated using the x and y axes and the right-hand rule. | | x = quaternion({atom}) | the quaternion associated with the an atom (or the first atom in the atom set) based on the setting of set quaternionFrame. | | x = quaternion({atomset}, nMax) | an array of quaternions, one per residue, up to nMax long (or all if nMax is <=0). Quaternions are created based on the setting of set quaternionFrame. | | x = quaternion({atom1}, {atom2}) | the quaternion difference of the two residues containing the specified atoms (or the first atom in each set, if applicable), created based on the setting of set quaternionFrame. An optional last parameter "relative" utilizes quaternion left-division. The quaternion relative difference represents the necessary rotation to get from q1 to q2 within the reference frame of q2 rather than the standard reference frame | | x = quaternion({atomset1}, {atomset2}, nMax) | an array up to nMax long (or all if nMax is <=0) of quaternion differences, one per residue pair in the two sets, created based on the setting of set quaternionFrame. An optional last parameter "relative" utilizes quaternion left-division. | | x = quaternion(quaternionArray) | calculates the spherical mean (see Buss and Fillmore, 2001) of the array of quaternions. | | x = quaternion(quaternionArray, true) | returns the standard deviation for the calculated spherical mean (see Buss and Fillmore, 2001) of the array of quaternions. | | x = quaternion(quaternionArray1, quaternionArray2) | an array of quaternion differences of the two array elements, taken a pair at a time. An optional last parameter "relative" utilizes quaternion left-division. | x = random()
x = random(n)
x = random(m,n)
x = random(m,n,seed) | Generate a random number in the range [0,1), [0, n), or [m, n). Optionally set the seed (resetting the generator to a predefined point). | | x = script("...") | returns the output from the specified script command; particularly informative script commands include getProperty and show. | | x = script("...", appletName) | returns the output from the specified script command run in one or more applets. For example, print script("show orientation moveto", 2) will print the orientation moveto command for an applet with name "2" or, if that does not exist, "jmolApplet2". See script for details. | | x = search(smilesString) | find atoms matching the given smiles string, which may include bond types such as = or - between atoms. More powerful SMILES/SMARTS functions include find() and search(). | | x = search({atomset}) | predefines a target for repetitive SMARTS searching. Does not actually carry out the search. Used along with pattern() and search(target,pattern) functions. For example:
load $caffeine
x = search({*})
y = pattern('NCN')
foundAtoms search(x, y)
| | x = search(target, pattern) | carries out a SMARTS search using a predefined target with a precompiled pattern. Used along with search(atomset) and pattern(smarts) functions. For example:
load $caffeine
x = search({*})
y = pattern('NCN')
foundAtoms = search(x, y)
| | x = select(x;{a};b) | selects atoms from the atom expression {a} based on the boolean expression b. Note the use of semicolons, not commas, to separate the three components of this function. The variable x is local to the function, and when it appears in the boolean expression in the form x.property represents a single atom of the atom expression. For example, x = select(a;{*};a.distance({0 0 0}) > 3 and a.elemno > 18). select() functions can be nested -- just use two different variable names: x = select(x;{*.ca};x.phi < select(y; {*.ca}; y.resno = x.resno + 1).phi). The select() function provides a powerful selection mechanism that can utilize any Jmol math expression involving properties of an atom. (In contrast, select command comparisons are limited to =, <, >, <=, and >=, and values are rounded to the nearest 1/100th). | | x = show(y) | returns the result of the show command; the same as x = script('show y') but simpler to implement. | | x = sin(y) | the sine of y, where y is in degrees | | x = spacegroup("4:c,a,b") | Finds the ITA spacegroup setting with this specific canonical CLEG setting. Text match so must be exact form [rotation;translation], e.g. "a,b,c;0,0,0,", "2/3a+1/3b+1/3c,-1/3a+1/3b+1/3c,-1/3a-2/3b+1/3c" ,"a+b,-a+b,c;-1/4,-1/4,-1/4" | | x = spacegroup(n) | where n is an integer or its string equivalent returns a map of space group information for the the ITA space group with this number. The map contains three entries:
| sg | the space group number, from 1-230
| | n | the number of ITA settings for this space group (including any additional Wyckoff-only settings)
| | its | a list of maps, one for each setting, with detailed information about the setting.
|
| | x = spacegroup("n.m") | Retrieves the JSON structure for the mth setting of the ITA space group No. n in JSON format, for example: its_155.json. This information is a summary of information at the Bilbao Crstallographic Server as reported by the GENPOS and WYCKOFF programs, ordered by its listing order a the BCS. | | x = spacegroup("ITA/ALL") | provides detailed information about general positions, generators, and Wyckoff positions for all space groups and their additional ITA settings (611 in all) found at the Bilbao Crystallographic Server. Keys include:
| clegId | canonical CLEG notation for this setting
| | det | determinant
| | gen | array of generators in Jones-Faithful notation
| | gp | array of general positions in Jones-Faithful notation
| | hall | the Hall notation for this setting (only for default ITA settings)
| | hm | the Hermann-Mauguin name of this setting
| | id | a unique ID for this setting
| | jmolId | if one of Jmol's built-in settings, it's Jmol id, such as 8:b1 or 227:2
| | set | the 1-based index of this setting in its space group
| | sg | the space group associated with this setting
| | trm | the 4x4 transformation matrix for this setting
| | wpos | details of this setting's Wyckoff positions, a map with keys:
| cent | an array of centerings (if applicable)
| | pos | the Wyckoff positions as an array of maps with keys:
| coord | an array of strings describing the coordinates of this position
| | desc | the ITA description, such as "1" or "m.."
| | geom | the type of position, one of "point", "line" or "plane"
| | label | the single-character label [a-zA]
| | mult | the multiplicity
|
|
|
| | x = spacegroup(6, [a, b, c, alpha, beta, gamma]) | adding an array of unit cell parameters will distinguishing among space group settings for a space group, delivering the one that matches the specified unit cell, provided there is a match. | | x = spacegroup("x,y,z;-x,y,z") | similar to spacegroup("2:a,b,c") or spacegroup("2.1"), but finds the space group based on this specific set of operations rather than a CLEG id or an ITA setting index. | | x = spacegroup("x,y,z&-x,y,z") | using "&" instead of ";" or adding "&" at the beginning or end of the string delivers an array of space group CLEG identifiers for space groups that have AT LEAST these operators, perhaps more for example:
print spacegroup("-x,-y,-z;-x,y,z;-x,-y,z;x,y,-z;-x,-y,-z;-x,-y,z;-y,-x,z+1/2&").format("JSON")
reports [ "131:a,b,c","132:a-b,a+b,c","226:a,b,c" ]. | | x = spacegroup("&x,y,z;-x,y,z", [a, b, c, alpha, beta, gamma]) | adding an array of unit cell parameters to a spacegroup() function with an operator list (with or without &) will ensure that the return is consistent with the given unit cell. For example:
print spaceGroup("&x,y+1/2,z+1/2", [5,5,5,90,90,90]).count
print spaceGroup("&x,y+1/2,z+1/2", [5,5,6,90,90,90]).count
print spaceGroup("&x,y+1/2,z+1/2", [5,5,6,90,90,120]).count
The first case reports 86 bc face-centered groups. The second case reports 72 because it excludes 14 cubic groups where a=b=c. The third reports 0 because there are no bc face-centered trigonal or hexagonal groups. | | x = spacegroup("Hall:p 32 2\" (0 0 4)") | Specifies a space group given a Hall description and optinally (as in this case) a nonstanddard offset. In this case the same as spacegroup("154:a,b,c;0,0,-1/3") using CLEG notation. | | x = spacegroup("AFLOWLIB/A3B14C2D3*") | Returns an array of "=aflowlib/n.mAFLOWID" entries, which can be split to give either the load string. or the AFLOW iD. For example:
$ print spacegroup("AFLOWLIB/A7B2_*")
=aflowlib/63.34 A7B2_oC36_63_cgh_f-001
=aflowlib/164.13 A7B2_hP9_164_ac2d_d-001
=aflowlib/164.14 A7B2_hP9_164_ai_d-001
=aflowlib/227.18 A7B2_cF144_227_2ef_e-001
$ print spacegroup("AFLOWLIB/A7B2_*").split("\t",true).col(1)
=aflowlib/63.34
=aflowlib/164.13
=aflowlib/164.14
=aflowlib/166.44
/=aflowlib/227.1
$print spacegroup("AFLOWLIB/A7B2_*").split("\t",true).col(2)
A7B2_oC36_63_cgh_f-001
A7B2_hP9_164_ac2d_d-001
A7B2_hP9_164_ai_d-001
A7B2_hR18_166_a2cdh_2c-001
A7B2_cF144_227_2ef_e-001
Note that the ID starts with the empirical cell formula ending with "_".
Check of empirical cell formula for =aflowlib/63.34 A7B2_oC36_63_cgh_f-001:
$ load =aflowlib/63.34 packed
$ print {cell=555}.find("CELLFORMULA", true)
Ca 2 Ag 7
and full cell formula:
$ print {cell=555}.find("CELLFORMULA")
Ca 8 Ag 28 | | x = spacegroup("AFLOWLIB/all") | returns array of arrays of information maintained in aflow_structures.json. Note that whenever there is an AFLOW Encyclopedia update, this information could go stale and "=aflow/3.10" might change. However, it is unlikely that the AFLOW ID will change. | | x = spacegroup(itaNo, itaTo, index1, index2,"subgroups") | Returns information on group-subgroup relationships, based on Bilbao Crystallographic Server public data, uses a set of JSON data files. See. Return depends upon values:
| spacegroup(4,"subgroups") | all maximal subgroup data for space group 4
| | spacegroup(4,0,"subgroups") | an array of known subgroup numbers
| | spacegroup(4,5,"subgroups") | list of all 4 >> 5
| | spacegroup(4,5,1,"subgroups") | first-listed 4 >> 5 as a map
| | spacegroup(4,0,2,"subgroups") | second listed subgroup as a map
| | spacegroup(4,0,2,1,"subgroups") | second listed subgroup, first,transformation
| | spacegroup(4,5,1,2,"subgroups") | first listing for 4>>5, second transformation
| | spacegroup(4,0,0,0,"subgroups") | an array of arrays of [isub, ntrm, subIndex, type], where
| isub | subgroup ITA number
| | ntrm | transformation count
| | subIndex | index of this group-subgroup relationship
| | idet | determinant if determinant >= 1; -1/determinant if determinant < 1
| | trType | 1 translationengelieche, 3 klassengleiche with loss of centering translation, 4 klassengleiche enlarged unit cell
|
|
| | x = sqrt(y) | the square root of y | | x = symop(matrix,option) | Allows introduction of a matrix as a symmetry operation. Accepts various reporting options, including:
| "axisPoint" | an arbitrary point along the axis of rotation or the normal to a plane
| | "axisVector" | the axis vector for a rotation or the normal to a plane
| | "cartesianTranslation" | the cartesian translation of a translation, screw axis, or glide plane
| | "centeringVector" | the centering vector, if present
| | "draw" | the DRAW commands for this operations
| | "fractionalTranslation" | the fractional translation of a translation, screw axis, or glide plane
| | "invariant" | retrns an object that describes the invariant nature of this symmetry operation. The return depends upon the type of operation:
| plane | returns {a, b, c, d} describiing the plane's equation ax + by + cz + d = 0.
| | axis | returns [point, vector], where point is on the line, and vector is the unit vector for the axis
| | center of inversion or an n-bar axis | returns the center point
| | any operation involving a translation | returns "none"
| | for the identity operation | returns "identity"
|
See also @1.symop("invariant") , which delivers an array of symop numbers for axes, planes, and centers of inversion for which this current model's atom position is invariant.
| | "label" | the descriptive label for this operation, for example "2 (-1/4 0 0) screw axis"
| | "matrix" | the 4x4 matrix for this operation
| | "plane" | the 4-vector for this plane in the form {x,y,z,u}
| | "rxyz" | rational matrix (rotatation|translation) string representation
| | "rotationAngle" | the rotation angle of a rotation
| | "timeReversal" | the time reversal of a magnetic space group operation
| | "type" | the type of this operation, for example, "inversion center"
| | "xyz" | the Jones-Faithful string representation
|
| | x = symop(3, [1 1 0]) | adds a specified "cif2-style" lattice translation to the symmetry operation, in this case {1,1,0}. same as x = symop(3) + {1 1 0}. Note that symop(3, {1 1 0}), using { } instead of [ ], would instead apply symmetry operation 3 to the point {1 1 0}. | | x=symop("wyckoff") | retrieves full list of current space group's Wyckoff positions, same as but simpler than {*}.symop("wyckoff") | | x = symop("wyckoff", "c") | gives the list of coordinates for the "c" Wyckoff position as a string. | | x = symop(pointGroupOperation, atom, pointGroupInfoObject) | where pointGroupOperation is a string of the form "S6" or "S6.1" or "S6^3" or "S6.1^3", .i indicates ith element of this type, and ^n indicates the nth power of this operation. Returns the point that is the result of this operation on the atom. Without pointInfoGroupObject, defaults to the point group of the current model, pointGroup(). For example:
print symop("C2.1", @3)
without atom, returns the 3x3 matrix for the point group operation, for example:
print symop("C2.1")
| | x = symop("wyckoff","G") | returns general position coordinates as a string, for example:
modelkit spacegroup 20
print symop("wyckoff", "G")
(x,y,z) (-x,-y,z+1/2) (-x,y,-z+1/2) (x,-y,-z) (x+1/2,y+1/2,z) (-x+1/2,-y+1/2,z+1/2) (-x+1/2,y+1/2,-z+1/2) (x+1/2,-y+1/2,-z) | | x=symop("wyckoff","C") | returns centering as an array, possibly empty, for example:
modelkit spacegroup 20
print symop("wyckoff", "C")[1]
{0.5, 0.5, 0} | | x = symop(...) | same as {thismodel}.symop(...) | | x = unitcell() | returns a "unit cell" array containing [origin, va, vb, vc] suitable for use in the command UNITCELL @x. | | x = unitcell(uc) | returns a copy of a unit cell. | | x = unitcell(uc, "reciprocal") | returns the reciprocal lattice for specified unit cell. | | x = unitcell("reciprocal") | returns the reciprocal lattice for current model's unit cell. | | x = unitcell("primitive") | returns the primitive unit cell for the current model. (Assumes current unit cell is conventional.) | | x = unitcell("primitive", centering) | returns the primitive unit cell for the current model using the specified centering, which may be one of "P", "A", "B", "C", "I", "F", "R", "BCC", or "FCC". (Assumes current unit cell is conventional.) | | x = unitcell("conventional") | returns the conventional unit cell for the current model. (Assumes current unit cell is primitive.) | | x = unitcell("conventional", centering) | returns the primitive unit cell for the current model using the specified centering. (Assumes current unit cell is primitive.) | | x = unitcell(ucconv, "primitive",centering) | converts conventional to primitive based on a centering. | | x = unitcell(ucconv, "conventional",centering) | converts primitive to conventional based on a centering. | | x = unitcell("a=10, b=10, c=20, alpha=90, beta=90, gamma=129") | returns a unit cell specified by a string. | | x = unitcell(origin, [va, vb, vc]) | returns a user-defined unit cell; just the array [origin, va, vb, vc]. | | x = unitcell(origin, pta, ptb, ptc) | returns a user-defined unit cell as [origin, pta - origin, ptb - origin, ptc - origin]. | | x = within("SMARTS", smartsString,{searchSet}) | returns any array of subsets of the atoms that match the given smarts string. If provided, only atoms in {searchSet} will be checked. More powerful SMILES/SMARTS functions include find() and search(). | | x = within("SMILES", smilesString,{searchSet}) | returns any array of atom sets that match the given smiles string. If provided, only atoms in {searchSet} will be checked. More powerful SMILES/SMARTS functions include find() and search(). | | x = within(distance, point, [arrayOfPoints]) | Returns a subarray of points (not necessarily in the same order) that are within a given distance of a given point. | | x = within(distance, TRUE, "UNITCELL", {atomset}) | This function iterates over all the atoms that could be loaded using crystallographic symmetry even if they have not been created. It returns an associative array with two keys: "atoms" and "points", each of which is an array. For example, x = within(4, true, "unitcell", {selected}).The atoms array lists atom indices for the equivalent originating atoms present in the model; the points array lists the coordinates of the atoms. The following DRAW command visualizes these points: draw width 0.2 points @{x["points"]} color red mesh nofill. | | x = within(tolerance, [arrayOfPoints]) | Returns a subarray of points that have no points within tolerance Angstroms of each other. | | x = within(distance, TRUE, "UNITCELL", {atomset}) | This function iterates over all the atoms that could be loaded using crystallographic symmetry even if they have not been created. It returns an associative array with two keys: "atoms" and "points", each of which is an array. For example, x = within(4, true, "unitcell", {selected}).The atoms array lists atom indices for the equivalent originating atoms present in the model; the points array lists the coordinates of the atoms. The following DRAW command visualizes these points: draw width 0.2 points @{x["points"]} color red mesh nofill. | | x = within(unitcell) | returns atoms with fractional coordinates within the range [0, 1) and effectively returns the set of points that are periodic; atoms in models without unit cells will not be included | | x = within(unitcell, u) | where u is the result of the unitcell() function. (That is, u is an array [o a b c] of origin and three lattice vectors.) Same as within(unitcell), except uses the specified unitcell, regardless of the unit cell of the atom's model. | | x = write(...) | the output of the write command is loaded into variable x. The parameters are those of the write command. For example, x = write("PDB") or x = write(quaternion, "r", "difference2"). Note that x = write("PNGJ") creates a binary associative array for which the keys are file names and the values are their associated file data, equivalent to writing a PNGJ file. The image for this PNGJ file will be the value associated with the "_IMAGE_" key. Likewise, write("ZIP") and write("JMOL") create ZIP files that can be loaded back into Jmol using the LOAD command. The difference between the ZIP and JMOL options is that the JMOL option stores all files necessary to recreate the visualization regardless of source, whereas ZIP saves only local files, leaving only references to remote resources involving http: or https:. Note that since more key/value pairs can be added to x using x.push(key,value) or can be removed using x.pop(key), this mechanism allows one to add (or remove) files from a PNGJ, ZIP, or JMOL collection. A subsequent WRITE VAR x ... command can then be used to save the modified PNGJ, ZIP, or JMOL file to disk. |
coordinate transforming .xxx functions back
These functions operate on coordinates, either the geometric center of a set of atoms expressed as {atom expression} or a coordinate point expressed as {x y z}. The unit cell system used is the currently defined unitcell for the current model. If more than one model is visible, all coordinates are considered Cartesian coordinates, and these functions are not distinguishable. For the examples below, we use the case of an orthorhombic unit cell with a = 28.0, b = 5.04, c = 6.04.
Note that fractional notation {1 1/2 1} is immediately converted to Cartesian coordinate {28.0 2.52 6.04}. And {1/2 3/2 1}.y = 7.56, whereas {1/2 3/2 1}.fy = 1.5, and {1/2 3/2 1}.uy = 0.5. Note that if vibration vectors are set using, for example, {atomno=3}.vxyz = {1/2 1/2 1/2}, then the frame command should be sent so as to update the popup menu so that the vibration menu item is enabled.
| pt.xyz | the Cartesian coordinates for the point. For example, if pt = {1/2 3/2 1} In the case described above, pt.xyz would equal {14.0 7.56 6.04}. | | pt.x, pt.y, pt.z | The x, y, or z component of the point, regardless of the unit system. | | pt.fxyz | the fractional coordinates of a point. In the same case, pt.fxyz would be {0.5 1.5 1.0}. | | pt.fx, pt.fy, pt.fz | The fractional x, y, and z coordinates, respectively. | | fpt.rxyz | given a fractional coordinate, returns a string such as "(1/2 1/2 1/2)" representing the coordinate as a rational fraction if within +/- 0.001 of and integer n divided by 2,3,4,6,8,12,24, or 48. If not, returns the value rounded to three decimal places. Note that there is no corresponding rx, ry, or rz attribute, only rxyz. | | pt.sxyz | the screen pixel coordinates of the point in space. A pt.sxyz of {0 0 1000} is in the bottom left corner, with a z-value of 1000. All z-value are ≥ 1, with 1 indicating "clipped" because the point is too close to the user. These values depend upon screen size and the sort of perspective model being used. | | pt.sx, pt.sy, pt.sz | The screen x, y, and z coordinates, respectively. | | pt.uxyz | the unit-cell normalized point in the range [0,1). In this case, pt.uxyz would be {0.5 0.5 0}. | | pt.ux, pt.uy, pt.uz | The unit cell x, y, and z coordinates, respectively. |
general .xxx functions back
These modifiers can be used with a number of different variable types.
| x = y.array | Forces y into an array format. If y is already an array just returns that; otherwise returns an array created from y. Variables of type matrix3f and matrix4f are converted to standard 3x3 or 4x4 arrays; others are returned as [ xxx ]. This function can be used to force an array where a string or other single value might be returned. In this way it is similar to y.all, but whereas y.all only works on atom properties, y.array works on any type of value. | | x = y.count | Not defined for associative arrays; for other types, same as y.size, but see also x.count(), below. | | x = y.color | Returns the color point {red, green, blue} with values ranging from 0 to 255 for a given value y. If y is a string, then it should correspond to a color, such as "red" or "[xFF0000]". If y is a numerical value, then the color returned will be based on the current property color scheme and range if the propertyColorScheme has been set and it has been used. For example with color atoms property partialcharge "rwb" range -1 1 or color "roygb" range 0 10, then y can be a number, as in x = 3.color. Using this mechanism a key can be generated within the Jmol applet using echo text appropriately positioned on the screen. Leaving the echo blank but coloring the background of the echo as well as the echo itself produces a horizontal bar of the desired color. | | x = y.keys | Returns the set of keys in associative array y. In addition, y.keys.all gives a full listing of all keys within an associative array that may have multiple depths, such as that returned by getProperty("modelInfo"). | | x = y.length | In the case of x a set of bonds, the average length of the bonds (but see modifiers, below -- for example: x = {carbon}.bonds.length.min). Specific data types return specific values:
| array | the number of elements in the array | | {atom set} | the number of atoms in the set | | byte array | the number of bytes in the array | | string | the number of characters in the string | | associative array | the number of keys in the array | | other | a negative number indicating the type of the variable (see y.size). |
| | x = y.lines | Not defined for associative arrays. For all other types, splits y into a set of lines based on new-line characters, appending a new-line character onto the end if necessary so that there is one new-line character per line. | | x = matrix4.rxyz | Speciifically for 4x4 matrices, returns a 3x4 (rotation|translation) string representationaion. Rational fraction are returned for values within +/- 0.000001 of n/2,3,4,6,8,12,24,48. For other values, returns the decmial value. For example:
$ print matrix("x,y,z;1/2,1/3,1/4")
[
[1.0 0.0 0.0 0.5]
[0.0 1.0 0.0 0.33333334]
[0.0 0.0 1.0 0.25]
[0.0 0.0 0.0 1.0] ]
$ print matrix("x,y,z;1/2,1/3,1/4").rxyz
(
1 0 0 | 1/2
0 1 0 | 1/3
0 0 1 | 1/4
) | | x = y.size | The nominal "size" of y, which depends upon its data type -- number of characters in a string, number of elements of an array, number of keys in an associative array, number of selected atoms or bonds in a bitset. Negative numbers indicate boolean (-1), integer (-2), decimal (-4), point (-8), or plane (-16). If y is a DRAW or ISOSURFACE id, such as $draw1, then $draw1.size returns a point {a b c} where a is the index of the object in the set of objects, b is the total number of such objects, and c is the number of vertices. | | x = y.type | the type of variable; one of: "array", "bitset", "bondset", "boolean", "context", "decimal", "hash" (an associative array), "integer", "matrix3f", "matrix4f", "point", "point4", or "string" . |
[array].xxx or .propertyName.xxx modifiers back
Several modifiers can be added to property functions {atoms}.y or arrays, such as [1.2, 1.4, 1.6].
| .all | If a property, such as {selected}.vanderwaals, then appending .all creates a list of those measures. This list can be used to transfer one property to another, as in: {*}.partialCharge = {*}.temperature.all, which would allow temperature data to be used for partial charges in an isosurface molecular map MEP command, for instance. Note that the "list" is really an array of string values. | | .average | the average value (the default modifier). | | .max | the maximum value, for example: {*}.temperature.max | | .min | the minimum value, for example: {*}.partialCharge.min | | .pivot | Creates a pivot table from an array . For example:
print {*}.element.all.pivot
{
"Ag" : 1561
"Cd" : 1360
}
load $caffeine
print {_N}.bondCount({_C}).pivot
{
"2" : 1
"3" : 3
}
| | .reverse | reverses an array IN PLACE (does not make a copy). Thus, the preferred command is simply xxx.reverse. | | .sort | sorts an array IN PLACE (does not make a copy). Thus, the preferred command is simply xxx.sort. An optional parameter allows for sorting a multidimensional array based on a specific "column" of data: For example, x = [ [1,"orange"], [2,"apple"], [3, "banana"] ]; x.sort(2) sorts this array to read: [[2,"apple"], [3, "banana"], [1,"orange"] ] | | .stddev | the standard deviation, for example: print {helix}.straightness.stddev | | .sum | the sum of the values | | .sum2 | sum of squares |
{atomExpression}.propertyName back
These functions operate on each atom in an atom expression. In addition to these are all of the atom properties described under the heading atom expressions, in which case they give the average value. For example: x = {oxgyen}.temperature. Several more functions that act on atom expressions are in the section below.
| x = y.atoms | The atoms associated with a set of bonds. | | x = y.bonds | The bonds associated with the specified atoms, using the current setting of bondModeOr (true, bonds having one OR the the other atom within this set; or false, bonds having BOTH atoms within the set) | | x = y.boundbox | A Jmol math list containing the boundbox center, vector to corner, and two opposite corners associated with this atom set | | x = y.color | The average color of the atoms in the set y expressed as a {r,g,b} coordinate in color space. If y is already a point, then .color converts this to a string of the form [[xRRGGBB]]. See also general x = y.color, above. | | x = y.ident | a list of the standard identity labels for the elements of y, either atoms or bonds. | | x = y.length | In the case of x a set of bonds, the average length of the bonds. In all other cases, the length of the data. For example: x = {carbon}.bonds.length, x = {*}.length. To check the size of a bondset, use .size. | | x = y.size | The number of selected atoms or bonds in a bitset. |
x.f(y) functions back
These functions operate on the individual elements of some group or listing, returning a modified listing.
| x = data1.add(data2) | Specifically for use with data set lists, adds each element of data1 to its corresponding element in data2 and returns the result. If data2 is a simple number, adds that number to each element of data1. | | x = data1.add("\t",data2) | Specifically for use with data set lists, creates a new column separated from the previous with a tab. ("\t" may be replaced with whatever separation one desires. | | x = mapOfMaps.array(key, asCopy) | This powerful method creates an array from a map of maps, moving the top-level keys of mapOfMaps to values of the specified key. Thus, starting with
x = {
"a": { "aa": 1,"ab": 2 },
"b": { "ba": 3,"bb": 4 },
"c": { "ca": 5,"cb": 6 }
}
array("id") = [
{ "aa": 1,"ab": 2,"id": "a"},
{ "ba": 3,"bb": 4,"id": "b" },
{ "ca": 5,"cb": 6,"id": "c" }
]
For this function to be successful, all values in mapOfMaps must be maps themselves. | | x = arrayOfMaps.array(key) | This method can be used to sort an array of maps based on a given index key such as "id". Given an array of no more than 10000 maps all having the index key with associated unique values that fill the range [0,n-1] or [1,n], with no missing values, this method produces a sorted array of maps based on that key and with that key removed. If the values are not integers, or there are gaps in the numbers, or the length is > 10000, a map instead of an array is returned, with keys that are the string equivalent of the index key. By default, the function creates a copy of the original maps; a second parameter, if present and FALSE, directs Jmol to operate on the original maps and not make copies. The index key must be found in each element map of the array, and each of the key values must be unique, or an error is thrown. For example:
a = [
{ "id": 3,"label": "C3" },
{ "id": 2,"label": "C2" },
{ "id": 1,"label": "C1" }
]
a.array("id") = [
{ "label": "C1" },
{ "label": "C2" },
{ "label": "C3" } ]
and
a = [
{ "id": "c","label": "C3" },
{ "id": "b","label": "C2" },
{ "id": "a","label": "C1" }
]
a.array("id") = {
"a": { "label": "C1" },
"b": { "label": "C2" },
"c": { "label": "C3" }
} | | x = arrayOfMaps.pivot(key) | Produces a map with keys that are the values found in the maps for that selected key. If a containing map does not have the specified key, it is grouped under a key that is the empty string "". For example:
a = [
{"label":"C3","id":"1"},
{"label":"C3","id":"2"},
{"label":"C2","id":"3"}
]
a.pivot("label") = {
"C3":[{"label":"C3","id":"1"}, {"label":"C3","id":"2"}],
"C2":[{"label":"C2","id":"3"}]
} | | x = arrayOfMaps.pivot(key1,key2,..sep) | Produces a map with keys that are the string formed by combining the values of the given keys, separated by the given separator. The result is a sorting by the equivalence of multiple keys, not just one. For example:
a = [
{"label":"C3","id":"1"},
{"label":"C3","id":"2"},
{"label":"C2","id":"3"}
]
a.pivot("label","id","+") = {
"C2+3": [ { "id": "3","label": "C2" } ],
"C3+1": [ { "id": "1","label": "C3" } ],
"C3+2": [ { "id": 2,"label": "C3" } ]
} | | x = array.bin(low,high,binSize,asArray) | Operating on an array, delivers an array that counts the number of values in specific bins defined by a low limit, a high limit, and a bin size. If the fourth parameter is TRUE, then creates an array of arrays for which the first value is the lower limit and second value is the count. Values equal to the lower limit of a bin are included in that bin. Values less than the low limit or higher than or equal to the upper limit are ignored. | | x = array.bin(low,high,binSize,fieldName, asArray) | For an array of associative arrays, creates a pivot table of bins from one of the associative array's values. Also adds keys "_bin", "_binMin", and "_binMax" to the initial arrays. For example, if x = [{"energy":2.345,"model":1},{"energy":1.5,"model":2},{"energy":2.36,"model":3}], then x.bin(1,3,0.5,"energy") will be [ 0,1,2,0 ].. Similarly for sequential arrays, adding TRUE for the fourth parameter, creates an array of arrays. | | x = {atomset1}.bondCount({atomset2}) | Counts bonds to a specific set of atoms. | | x = arrayOfArrays.col(n) | selects out the nth column from an array of arrays. For example, retrieving the third column from CSV data: col3 = load("data.csv").split("",true).col(3). | | x = array.count() | Operating on an array, .count() returns an array of [value, count] pairs. Thus, for example, {*}.radius.all.count() would return a list of all the radii of all the atoms and how many of each radius value there are. | | (array-of-hash).pivot(key1, key2, ...,sep) | returns a (hash-of-array-of-hash) of the array elements grouped by the values of these keys, combined as a string using the separator given as the last parameter. For example:
settings = spacegroup("ITA/all")
bysg = settings.pivot("sg")
print bysg[25].select("(hm)").format("JSON")
This code retrieves the 746 space group settings of the ITA and sorts them into sets by space group. It then reports the Hermann-Mauguin names of the three ITA settings for space group 25:
[ "P m m 2","P 2 m m","P m 2 m" ] | | x = y.count(z) | returns how many z there are in y, which should be either an array or a string. | | x = a.cross(b) | the cross product of two vectors or points. | | x = y.distance(z) | The evaluation of this function depends upon the type of variables y and z:
| y type | z type | evaluation | | atomset | atomset | The average distance from atoms of y to the geometric center of z; same as y.distance(z.xyz). | | atomset | point | The average distance from atoms of y to the point z. | | point | atomset | The distance from the point y to the geometric center of z. | | point | plane | The distance from point y to plane z. The absolute value of the result depends upon the winding of the points used to create the plane, using a right-hand winding rule. |
| | x = y.distance() | where y is an atom, an atomset, or a coordinate. y.distance({0 0 0}) . | | x = y.distance(plane, point) | The distance of y to a plane, using a point for a reference, giving a positive value if the y and the point are on the same side of the plane and a negative number if they are on opposite sides of the plane. | | x = {atomset1}.distance.all({atomset2} | Generates an array of arrays of distances indicating distances from every atom in {atomset1} to every atom in {atomset2}. | | x = {atomset1}.distance.min({atomset2}, asAtomSet) | If asAtomSet is true, returns the closest atom in atomset1 to any atom of atomset2; if false or omitted, returns an array listing the distance of each atom in atomset1 to the closest atom in atomset2. This array can be used to assign properties to atomset1: {1.1}.property_d = {1.1}.distance.min({2.1}); color {1.1} property_d. | | x = {atomset1}.distance.min({point}, asAtomSet) | If asAtomSet is true, returns the atom in atomset1 closest to the specified point;if false or omitted, returns the closest distance to the specified point from any atom in atomset1. | | x = {atomset1}.distance.min({atomset2}).min | returns the shortest distance from any atom in atomset1 to any atom in atomset2. | | x = {atomset1}.distance.max({atomset2}, asAtomSet) | If asAtomSet is true, returns the furthest atom in atomset1 to any atom of atomset2; if false or omitted, returns an array listing the distance of each atom in atomset1 to the furthest atom in atomset2. | | x = {atomset1}.distance.max({point}, asAtomSet) | If asAtomSet is true, returns the atom in atomset1 furthest from the specified point;if false or omitted, returns the furthest distance to the specified point from any atom in atomset1. | | x = {atomset1}.distance.max({atomset2}).max | returns the furthest distance from any atom in atomset1 to any atom in atomset2. | | x = data1.div(data2) | See data1.add(). Division by 0 results in the value "NaN", meaning "not-a-number". | | x = a.dot(b) | the dot product of two vectors or two points or a point with a plane (as its normal). | | x = array.find() | returns an array that has been cleared of all "empty" elements -- ones that are empty strings, empty arrays, or empty associative arrays. For example, [0 3 4 "" 5 {} [] 6].find() returns [0 3 4 5 6]. | | x = array.find("") | returns an array that has been cleared of all "nonempty" elements -- ones that are not empty strings, empty arrays, or empty associative arrays. For example, [0 3 4 "" 5 {} [] 6].find("") returns ["" [] {}]. | | x = array.find(ns) | where ns is not a string value. Returns an array that points to the positions of array that are equal to ns. For example, [11,1,2,3,1].find(1) == [2,5]. | | x = test.find("pattern","flags") | Searches string or list text for a Java regular expression pattern. The second parameter is a set of flags. This parameter must be included, even if it is the blank string "" so as to distinguish this command from the standard .find() command. Flags include:
| | (no flags) Returns the position in the string containing the pattern, starting with 1, or 0 if the pattern is not found. For lists, returns a sublist containing the elements that match. | | i | (case-insensitive) Match upper or lower case letters. | | v | (reverse match) With a string, v returns "false" if the string contains the match or "true" if it does not; with lists, v returns all elements of the list that do not contain the match. | | m | (return match) The m option allows returning only the portion of the string that matches (or, with vm, only the portion of the string that does NOT match). With lists, both m and vm return only elements that contain the match, but, as for strings, each element is returned as just the matching phrase or the reverse. |
Note that special characters such as \S and \d must be escaped with two back-slashes, and if they are introduced via JavaScript, they will need double escaping (four back-slashes). Examples include:
| "this test is a Test".find("Test","") | 16 | | print "this test is a Test".find("Test","i") | 6 | | print "this test is a Test".find("Test","m") | Test | | print "this test is a Test".find(" a test","v") | true (because it was not found) | | print "this test is a Test".find(" Test","ivm") | this is a Test | | print "this test is a Test".find("\\stest","m") | test | | print "this test is a Test".find("\\stest","vm") | this is a Test | print script("show spacegroup all").split()
.find("Hall symbol:") | Hall symbol: P 1
primitive Hall symbol: P 1
Hall symbol: -P 1
primitive Hall symbol: P 1 -1
Hall symbol: P 2y
primitive Hall symbol: P 2y
... | print script("show spacegroup all").split()
.find("Hall symbol:").find("primitive","v") | Hall symbol: P 1
Hall symbol: -P 1
Hall symbol: P 2y
... | print script("show spacegroup all").split()
.find("Hall symbol:").find("primitive","v")
.find("Hall symbol:","vm")[1][3] | P 1
-P 1
P 2y
|
| | x = {CELL=nnn}.find("CELLFORMULA") | calculates cell formula for specified unit cell, weighing interior 1, face 1/2, edge 1/4, vertex 1/8; selection should be a single packed unit cell; fails with "?" if end result is not integral. For example, load quartz.cif packed;print {*}.find("cellFormula") gives "O 6 Si 3". | | x = {CELL=nnn}.find("CELLFORMULA", TRUE) | calculates the empirical cell formula for specified unit cell, for example: load quartz.cif packed;print {*}.find("cellFormula", TRUE) gives "O 2 Si 1". | | x = {atomExpression}.find("chemical",type) | Determines or looks up the specific type of information for this subset of atoms. type may be one of: "smiles", "inchi", or "inchikey". In the case of InChIs, the return includes the prefix "InChI=". | | x = {atomExpression}.find("crystalClass", pt) | Generates a list of points based on a model's crystal class (point group). Uses {atoms} to find the unit cell and space group; pt is an optional generator, which defaults to x[1]. For example:
load =ams/calcite 1
x = {*}.find("crystalClass",@3)
draw points @x
polyhedra ID p {0 0 0} to @x
| | x = {atomExpression}.find("smartsString", "BONDS") | Finds the first match in the structure to the given SMARTS string and returns an array of all the dihedrals involving the matching atoms. Each dihedral is expressed as an ordered list of the four atom indices. | | x = {atomExpression}.find("MF") | finds the molecular formula of the atom expression. | | x = {atomExpression}.find("MF",formula) | finds the subset of atoms in this atom expression that matches the given formula, for example: {xxx}.find("MF","CH2O"). | | x = {atomExpression}.find("MF",TRUE) | finds the empirical formula for the specified atoms. For example, load $glucose; print {*}.find("MF",true) displays "H 2 C 1 O 1". | | x = {atomExpression}.find("SEQUENCE") | returns the Jmol SMARTS/bioSMILES sequence for the specified atoms. An optional second parameter TRUE adds crosslinking. | | x = {atomExpression}.find("spacegroup", "parent") | reduces to the parent unit cell if currently a supercell. For example, to show the parent cell of a supercell:
load =ams/quartz 1 supercell {3 3 3}
{*}.find("spacegroup", "parent")
PRINT {*}.find("spacegroup", "parent")
unitcell @{{*}.find("spacegroup", "parent").unitcell}
| | x = smilesString2.find("SMILES",smilesString1, exactMap, allMappings) | Checks to see if a structure created from smilesString1 would match the structure associated with smilesString2, thus allowing Jmol to match two SMILES strings without need of "canonicalization." Boolean parameters exactMap and allMappings determine the value returned:
| exactMap | allMappings | return value | | false | true | (default) Returns -1 if a SMILES parsing error is found, or the number of atoms in smilesString2 matched. For example, "O[C@](F)(Cl)I".find("SMILES","[C@](O)(F)(Cl)I", false, true) would return the value 5, meaning all 5 atoms of O[C@](F)(Cl)I were a match. A return value of 0 means the pattern was not found; a return of -1 indicates there was a problem parsing one or the other of the SMILES strings. | | false | false | 1 if a SMILES parsing error is found, 0 if no structure is found, or 1 if any match is made. | | true | true | an array of integer arrays listing all possible mappings of atoms in smilesString1 onto smilesString2. | | true | false | an integer array of the first match of atoms in smilesString2. Numbers refer to positions along smilesString1. So, for example, "CCCO".find("SMILES", "OCCC", true, false) evaluates to [3,2,1,0]. |
| | x = smilesString.find("SMARTS",pattern, exactMap, allMappings) | Checks to see if a substructure created from pattern would be found in the structure associated with smilesString. Boolean parameters exactMap and allMappings determine the value returned:
| exactMap | allMappings | return value | | false | true | (default) -1 if a SMILES parsing error is found, empty array if no substructure is found, or the array of all atoms in smilesString matched by any possible mapping of the atoms in pattern. So, for example, "CCCC".find("SMARTS","CC",false,true) evaluates to [0, 1, 2, 3]. | | false | false | -1 if a SMILES parsing error is found, 0 if no substructure is found, or 1 if any substructure is made. | | true | false | an integer array of the first match of atoms in smilesString. Numbers refer to positions along smilesString. So, for example, "CCCO".find("SMARTS","OCC",true,false) evaluates to [3,2,1]. | | true | true | an array of integer arrays listing all possible mappings of atoms in pattern into smilesString. |
| | x = smilesString.find("chemical",type) | Determines or looks up the specific type of information for this SMILES string. type may be one of: "smiles", "inchi", or "inchikey". In the case of InChIs, the return includes the prefix "InChI=". | | x = smilesString.find("smiles","chirality") | creates an array indicating the stereochemical designator (R,S,r,s,M,P,m,p,E,Z) at each atom in the SMILES string. No structure is necessary. For example:
load $1,4-dihydroxycyclohexane
calculate chirality
show smiles
"O[C@@H]1CC[C@@H](O)CC1"
print "O[C@@H]1CC[C@@H](O)CC1".find("smiles","chirality").format("JSON")
[ "","r","","","r","","","" ]
print "[C@@H]1(C)CC[C@H]2C(C)C.C1[C@@H]2O".find("smiles","chirality").format("JSON")
[ "R","","","","S","","","","","S","" ] | | x = smilesString.find("SMILES","MF") | returns the canonical molecular formula for smilesString, including all implicit H atoms. | | x = smilesString.find("SMARTS", "MF") | returns the canonical MF for the smilesString, not including implicit H atoms. | | {*}.find("spacegroup") | discovers the space group for a model using the current unit cell, finds a compatible spacegroup or returns P1. Uses a novel algorithm that efficiently scans all known operators to rapidly iterate to the only compatible spacegroup for a given unit cell. Automatically reduces to the parent unit cell if currently a supercell. Assumes the specified atoms are within(unitcell) or packed as (cell=555). Returns one of 611 ITA space group settings known to Jmol a tab-separated list that includes Jmol's internal id, the Hermann-Mauguin name, and the CLEG setting. For example:
load =ams/quartz 1 packed
print {*}.find("spacegroup")
giving "HM:P 32 2 1 154:a,b,c;0,0,-1/3" | | {*}.find("inchi") | generates a standard InChI for a model. Jmol/Java integrates jni-inchi-0.7-jar-with-dependencies.jar; JSmol/JavaScript uses inchi-wasm for JavaScript R.Apodaca . | | {*}.find(""inchi"",flags) | generates InChIs from modelset atoms. Flags include:
| perception flags | DoNotAddH SNon NEWPSOFF
| | stereo flags | SRel SRac SUCF
| | more flags | NEWPSOFF SUU SLUUD RecMet FixedH KET 15T
| | java-only flags | key outputsdf (Java only; still no InChIKey for JavaScript)
|
| | x = {*}.find(smartsString,"map") | returns an array of arrays of atom indices (0-based). Indicates exact correlation between atoms in {*} and atoms of smartsString. Only unique sets of atoms are found, not every possibility. For example:
load $caffeine
print {*}.find("*1*****1", "map").format("JSON")
[ [ 0,2,4,6,11,12 ] ]
In this second example, we create a 1:1 mapping of atoms for the caffeine model from two sources -- NIH/CADD, and PubChem -- by correlating them both to the same SMILES string.
load $caffeine // from NCI/CADD
s = show("smiles")
// N1(C)C(=O)c2c3N(C)C1=O.[n]2(C)c[n]3
print {{*}}.find(s,"map").format("JSON")
// [ [ 0,1,12,13,11,6,4,5,2,3,9,10,8,7 ] ]
load:caffeine // from PubChem
print {{*}}.find(s,"map").format("JSON")
// [ [ 4,13,8,0,6,7,2,11,9,1,3,12,10,5 ] ]
| | x = {xxx}.find("SMILES/molecule", smilesString) | returns an array of matching molecules in {xxx}. | | x = {xxx}.find("SMARTS/molecule", smartsString) | returns an array of molecules in {xxx} the the specified substructure. | | x = {mol1}.find({mol2}, "map"+flags,format) | Uses SMILES mapping to create a correlation map of atoms of mol1 to atoms of mol2. Similar to compare({mol1},{mol2},"map", options) but more flexible in terms of return value. Creates a correlation map of atoms of mol1 to atoms of mol2, for example {1.1} and {2.1}. Jmol SMILES directive flags such as "hydrogen" or "open" can be added. The format to use for the results can be "name", "index", "number" or any valid label, such as "%a %i", defaulting to "number". Returns a map (an associative array) containing keys:
| smiles | the SMILES string used for the match
| | BS1 | atomset for mol1
| | BS2 | atomset for mol2
| | SMILEStoBS1 | array correlating SMILES atoms to BS1
| | SMILEStoBS2 | array correlating SMILES atoms to BS2
| | BS1toBS2 | array correlating BS1 to BS2 (indexes are for mol1; values are mol2)
| | MAP1to2 | array of [a,b] pairs, where a is format for mol1, b is format for mol2
| | key | format used in mapping
|
For example:
load files ":caffeine" "$caffeine"
info = {{1.1}}.find({{2.1}},"map", "name")
print info.SMILES
// O=C1N(C)C(=O)N(C)c2c1[n](C)c[n]2
// was // O=C1c2c3N(C)C(=O)N1C.[n]2(C)c[n]3
print info.key + ": " + info.MAP1to2.format("JSON")
// name: [ [ "O1","O14" ],[ "O2","O4" ],[ "N3","N5" ],[ "N4","N10" ],[ "N5","N1" ],
// [ "N6","N8" ],[ "C7","C12" ],[ "C8","C7" ],[ "C9","C13" ],[ "C10","C3" ]
// [ "C11","C9" ],[ "C12","C6" ],[ "C13","C11" ],[ "C14","C2" ] ]
info = {{1.1}}.find({{2.1}},"map hydrogen", "number")
print info.SMILES
//hydrogen/O=C1c2c3N4[C@@]([H])([H])[H].N51[C@@]([H])
// ([H])[H].C54=O.[n]62[C@]([H])([H])[H].c6([H])[n]3
print info.key + ": " + info.MAP1to2.format("JSON")
// number: [ [ 1,14 ],[ 2,4 ],[ 3,5 ],[ 4,10 ],[ 5,1 ],[ 6,8 ],[ 7,12 ],[ 8,7 ],
// [ 9,13 ],[ 10,3 ],[ 11,9 ],[ 12,6 ],[ 13,11 ],[ 14,2 ],[ 15,21 ],[ 16,18 ],[ 17,20 ],
// [ 18,19 ],[ 19,22 ],[ 20,23 ],[ 21,24 ],[ 22,15 ],[ 23,17 ],[ 24,16 ] ]
| | x = {atoms}.find(smartsString, "map") | Returns an array of arrays of atom indices (0-based) that indicates the exact correlation between atomIndex and position in the SMARTS string. Only unique sets of atoms are found, not every possibility. In this example we create a 1:1 mapping of atoms for the caffeine model from two sources -- NIH/CADD, and PubChem -- by correlating them both to the same SMILES string.
load $caffeine
s = show("smiles") // N1(C)C(=O)c2c3N(C)C1=O.[n]2(C)c[n]3
print {*}.find(s,"map").format("JSON")
[ [ 0,1,12,13,11,6,4,5,2,3,9,10,8,7 ] ]
load:caffeine
print {*}.find(s,"map").format("JSON")
[ [ 4,13,8,0,6,7,2,11,9,1,3,12,10,5 ] ]
| | x = array.find() | returns an array that has been cleared of all "empty" elements -- ones that are empty strings, empty arrays, or empty associative arrays. For example, [0 3 4 "" 5 {} [] 6].find() returns [0 3 4 5 6]. | | x = array.find("") | returns an array that has been cleared of all "nonempty" elements -- ones that are not empty strings, empty arrays, or empty associative arrays. For example, [0 3 4 "" 5 {} [] 6].find("") returns ["" [] {}]. | | x = array.find(ns) | where ns is not a string value. Returns an array that points to the positions of array that are equal to ns. For example, [11,1,2,3,1].find(1) == [2,5]. | | (array of SMILES strings).find("SMARTS" or "SMILES", pattern) |
efficiently searches each target SMILES in array for pattern, returns array of same length with 1 (found) or 0 (not found) for each target SMILES.
For example:
print ["CCCC","C(O)CC","C(N)CC","CC(N)CC"].find("SMARTS","CCO").format("JSON")
[ 0,1,0,0 ]
print ["CCCC","C(O)CC","C(N)CC","CC(N)CC"].find("SMILES","CCCN").format("JSON")
[ 0,0,1,0 ] | | {atoms}.find("equivalent") | returns all atoms with the same site value as any of the atoms specified. These atoms may or may not be within the unit cell. Returns at least all atoms in {atoms}
| | new feature: {point}.find("equivalent") | returns all equivalent positions by applying all symmetry operators to this point. These points will be only WITHIN the unit cell -- fractional coordinates [0,1). May or may not return {point} itself
| | new feature: {point}.find("equivalent", "packed") | returns all equivalent positions by applying all symmetry operators to this point. These points will include points in the packing layer around the cell -- fractional coordinates [0,1]-- may or may not return {point} itself | | matrix4.format("xyz") | Formats a 4x4 matix representing a space group operation as a Jones-Faithful string, such as x,y+1/2,z. | | matrix4.format("abc") | Formats a 4x4 matix representing a space group basis transformation as an ITA concise form of a transformation matrix, for example: a,b+1/2,2c;0,1/2,0. | | x = array.format("JSON") | Formats a serial or associative array as JSON. | | x = array.format("%5.3f %5s") | Formats an array or array of arrays into a multiline string using sprintf format. See also the format(sprintfFormat, a, b, c) description. | | x = arrayOfArrays.format([headings]) | Transform an array of arrays into an array of associative arrays based on an array of "column" headings. For example, if y = [[1,2],[3,4]], then z = y.format(["a","b"]) will set z to [ { "a": 1,"b": 2 },{ "a": 3, "b": 4 } ]. | | x = arrayOfMaps.format([headings] | The reverse of arrayOfArrays.format([headings]). z.format(["a","b"]), where z is an array of maps, and the maps have keys "a" and "b", will create an array of arrays having the values of these keys in the order listed. For example, if z is [ { "a": 1,"b": 2 },{ "a": 3, "b": 4 } ], then z.format(["a","b"]) will return [[1,2],[3,4]]. | | x = array.getProperty(key) | same as getproperty(array, key); looks in associative array elements of array to return an array of values associated with key. | | x = {atomset}.getProperty("xxx") or x = {atomset}._("xxx") | shortcut for getProperty("atominfo.xxx", {atomset}). For example:
print {*}._("visible")
print {*}._("coord")
A list of available keys xxx can be shown using print @1._(). "[SELECT ... WHERE ...]" syntax can be used. | | x = $id.getProperty(intoType) | retrieve a property of type infoType for shape with ID specified. The specific information available depends upon the shape. ("+meshCollection" here means "and also those listed under meshCollection"):
| CGO | command +meshCollection | | draw | command type +meshCollection | | isosurface | area atoms colorEncoder command contours cutoff dataRange dataRangeStr jvxlDataXml jvxlFileInfo message minMaxInfo moLinearCombination moNumber nSets plane pmesh value volume +meshCollection | | measures | count countPlusIndices info infostring pointInfo stringValue | | meshCollection | bsVertices count data ID info list values vertices | | polyhedra | atomIndex atomName atomNames atomNumber bsFlat center collapsed color colorEdge element elemNos energy face_areas face_points face_types faceCount faces faceTriangles id info modelIndex modelNumber normals offset pointGroup pointGroupFamily pointScale polySmiles r scale smarts smiles triangleCount triangles vertexCount vertexIndices vertices volume |
| | x = array.join() | Makes a flat array copy of a multidimensional array. creating an array of dimension 1. For example, if a = [1,2,[3,4,5],6], then a.join() will be [1,2,3,4,5,6]. | | x = x.join(y) | For string x, joins lines of x using the string equivalent of y into one line. For array x and string y , joins elements of x into one string, separating elements of x by s. For array x and array y , joins the two arrays into an array of arrays. (Adding a new column, effectively). If x is already an array of arrays or y is already an array of arrays, carries out an add operation on pairs of elements to maintain one array per element of the resulting array. If both x and y are arrays, the resultant array has the minimum number of elements common to x and y. For example, if x = [1, 2, 3] and y = [4, 5, 6], then x.join(y) = [ [1, 4], [2, 5], [3, 6] ], and x.join(y).join(y) = [ [1, 4, 4], [2, 5, 5], [3, 6, 6] ]. Note that x.join(y) is particularly valuable when tables of data are ultimately desired, but one does not want to go immediately into strings using x.add(s,y) (see above). | | x = y.join("", TRUE) | joins an array of arrays into line-delimited comma separated value (CSV) data. Reversed using y.split("", TRUE). | | x = y.join("\t", TRUE) | joins an array of arrays into line-delimited tab separated data. | | x = y.label(format) | A list of labels for atoms or bonds using format strings. (see label) | | x = atomset.modulation(type,t) | For a given (optional) type (displacement "D", magnetic "M", occupancy "O" is implemented), returns an array of values related to one or more atoms' modulation. For displacement and magnetic, returns a vector cooresponding to the relevant phase of the modulation, t (irrespective of the setting of set modulationScale) or -1 if not modulated. For occupancy, returns a number from 0 to 100 or, if not modulated, "NaN." If t is not given, as in @33.modulation()[1], (or, alternatively, if t >= 1E6), then the unmodulated position/magnetic spin is returned for "D" or "M" or the currently calculated occupancy for "O". | | x = data1.mul(data2) | See data1.add() | | x = pt1.mul3(pt2) | returns {pt1.x*pt2.x, pt1.y*pt2.y, pt1.z*pt2.z}, or the equivalent of taking the dot product of a coordinate in space with one in reciprocal space. If either pt1 or pt2 is not a point, reverts to simple multiplication. | | x = array.pivot() | Creates a pivot table of the values in the array in the form of an associative array with keys that are the set of unique values in the array, and with values that are counts of those values. | | (array-of-hash).pivot(key) | turns an array of hashes into a hash of arrays of hashes like a pivot table for an array, but based on the value of a hash. The key within each hash element of the array, not the element itself. Returns a (hash-of-arrays-of-hashes) of the array elements grouped by the stringified values of the specified key. For example:
a = [
{label:"C3", id:1},
{label:"C3", id:2},
{label:"C2", id:3}
]
a.pivot("label") = {
"C3":[{label:"C3", id:1}, {label:"C3", id:2}],
"C2":[{label:"C2", id:3}]
}
| | x = {associative array}.pivot() | Creates an inverted associative array, where the values of the original associative array are now keys, with values that are arrays of the original keys having given values. Switches keys for values. Result is an associative array of lists. Allows quick filtering based on values of a simple associative array. For example:
load =2fk3
print {*}.chain.all.pivot().pivot()
{
"A" : 504
"B" : 500
"C" : 512
"D" : 493
"E" : 490
"F" : 492
"G" : 508
"H" : 491
} | | {associative array}.pivot("count") | switches keys for values and reports count of each list, not the list itself. Allows quick filtering based on values of a simple associative array. For example:
load =2fk3
print {*}.chain.all.pivot().pivot("count")
{
"490" : 1
"491" : 1
"492" : 1
"493" : 1
"500" : 1
"504" : 1
"508" : 1
"512" : 1
} | | {atoms}.pointGroup() | returns the point group object for the specified atoms, for example: {!_H}.pointGroup() will ignore hydrogen atoms. load :methane;print (!@2).pointGroup().name will report "C3v", and print (!@2&!@3).pointGroup().name<.b> will report "C2v". | | @1.pointgroup("spacegroup") | same as pointgroup("spacegroup", @1) . Consistent with @1.spacegroup() | | x = a.pop() | array pop -- removes the last entry of an array and returns its value. If the array is empty, returns an empty string. If the array is an associative array, a.pop() empties it of all keys and returns the empty array a. | | x = a.pop(key) | removes and returns from an associative array the value associated with the specified key; (same as y = a - key, but does not create a new array). | | x=string.pop() | pops a character off a string | | x=string.push("xx") | appends a string to a string | | a.push(key, value) | adds the specified key/value pair to an associative array. | | a.push(x) | array push -- adds an entry of an array and returns the array. If a and x are associative arrays, adds all entries of x to a. | | x = y.replace() | return a cleaned-up version of y with whitespace reduced to a single space and trimmed. | | x = y.replace(s1,s2) | replaces all occurances of s1 with s2 in y. If y is a number, this function first converts the number to a string, then does the replacement. | | x = y.replace(chars,s,TRUE) | replaces all occurrences of each character of chars with s. | | x={atomset}.search(pattern) | Carry out a SMARTS search using a predefined target with a precompiled pattern. Used along with search(atomset) and pattern(smarts) functions. For example:
x = pattern('NCN')
foundAtoms = {*}.search(x)
| | search(target, pattern) | search a predefined target with a precompiled pattern
For example:
x = search({*})
y = pattern('CCCC')
atoms = {*}.search(y)
print search(x, y)
| | {associative array}.select("... WHEREIN KEY...") | "WHEREIN KEY" allows selection of associative array items by key, especially handy as [array].pivot.pivot() and can be combined with a VALUE checker. For example:
load =1d66
print {*}.chain.pivot()
{
"A" : 483
"B" : 482
"D" : 400
"E" : 397
}
print {*}.chain.pivot.select("(*) wherein key = 'B' or key = 'A' ")
482
483
print {*}.chain.pivot.select("(*) wherein key = 'B' or key = 'A' ").sum
965.0 | | {associative array}.select("... WHEREIN VALUE...") | "WHEREIN VALUE" allows a section of associative array items by value, especially handy as [array].pivot.pivot(). For example:
load =1d66
print {*.CA|*.P}.chain.pivot.select("* wherein value > 40").format("JSON")
gives an accounting of number of residues for the larger chains
{ "A": 57,"B": 57 } | | x = y.split(s) | splits y into lines by replacing all occurances of s with a new-line character and converting the string to a set of lines. | | x = y.split(TRUE) | splits y into tokens based on standard white space (space, tab, line endings). | | x = y.split("", TRUE) | splits line-delimited comma separated value (CSV) data into an array of arrays. y may be either a single string or an array of strings, one for each line. Reversed using x.join("", TRUE). | | x = y.split("\t", TRUE) | splits line-delimited tab separated data into an array of arrays. y may be either a single string or an array of strings, one for each line. Reversed using x.join("\t", TRUE). | | x = data1.sub(data2) | See data1.add(). | | x = y.substring() | Jmol math does not include a .substring() function. Instead, this is handled using the more general item-selector [i][j] syntax, described below. | | x = a.symop(op,atomOrPoint) | Returns the point that is the result of the transformation of atomOrPoint via a crystallographic symmetry operation. The atom set a selects the unit cell and spacegroup to be used. If only one model is present, the symop() command alone, without "a." can be used. For the current model, @@1.symop() can be used. The first parameter, op, is a symmetry operation. This can be the 1-based index of a symmetry operation in a file (use show spacegroup to get this listing) or a specific Jones-Faithful expression in quotes such as "x,1/2-y,z". | | x = a.symop(op) | This form of the a.symop() function return the 4x4 rotation-translation matrix for this symmetry operator; same as just symop(op) if for the current model | | x = a.symop(n,type) | For a given symmetry operation, final parameter that determines the form of the return. Possibilities include:
| "array" | Returns an associative array that contains critical information relating to this operation. Keys include axisVector axispoint cartesianTranslation fractionalTranslation id label matrix plane rotationAngle timeReversal xyz xyzOriginal. These keys can be used for the type as well: x = @@1.symop(3, "axisVector") | | "atom" | Returns the atom that is the target of this operation. | | "draw" | Returns the Jmol script illustrating this operation with DRAW commands. These DRAW commands describe the symmetry operation visually, in terms of rotation axes, inversion centers, planes, and translational vectors. The draw objects will all have IDs starting with "draw_", which can be substituted using .replace("draw_","xxx"). | | "full" | Returns the tab-separated Jones-Faithful string and descriptor for this operation. For example:
print symop(3,"full")
-x,-y,-z(mx,my,mz) Ci: 0 0 0
| | "label" | Returns a short description of the operation, such as c-glide plane|translation: 0 0 1/2 | | "lattice" | Returns the lattice type associated with the space group involving this operation. | | "list" | Specifically when two atoms or points are specified, returns a string list of all operations taking the first to the second.
print symop(@3,@21,"list")
5 x+1/2,-y+1/2,-z+1/2(-mx,my,mz) 2-fold screw axis|translation: 1/2 0 0|time-reversed
7 -x+1/2,y+1/2,z+1/2(-mx,my,mz) n-glide plane|translation: 0 1/2 1/2|time-reversed | | "point" | Returns the point that is the target of this operation. |
| | x ={atom}.symop("invariant") | Delivers an array of integers, the symmetry operator indexes other than identity (numbers 2-N) for which the specified atom is unchanged in position when operated upon. For example, the position of an atom on a rotation element or on a mirror plane is unchanged upon rotation or reflection, respectively. Used internally to determine when ModelKit MOVETO can allow a change in position | | x = {atom}.symop(2, "invariant") | same as symop(2, "invariant"), except adjusts return to be through the given atom.Presumes the atom is in a special position and not fixed. Returns the "true" plane or axis or center of inversion, not just the one for the generating operator. | | x = pt.symop("invariant") | similar to @1.symop("invariant") . Returns an array of symop numbers for axes, planes, and centers of inversion, for which this position is invariant. | | x = pt.symop(2, "invariant") | same as @1.symop(2, "invariant"), but for a point rather than an atom. Adjusts return to be through the given point. Presumes the point is in a special position and not fixed. Returns the "true" plane or axis or center of inversion, not just the one for the generating operator. | | x = y.tensor("type","property") | returns one of several tensor properties using tensors read by certain file readers (CASTEP, QuantumEspresso, Magres). "type" might be "charge" or "isc" or "ms", for example. Eigenvectors are sorted based on their corresponding eigenvlues, using the convention: |v3 - v1| >= |v3 - v2| > |v2 - v1|. Implemented "property" values include:
| "anisotropy" | v3 - (v1 + v2)/2 | | "asymmetry" | (v2 - v1)/(v3 -v_iso) | | "asymMatrix" | matrix representation of the asymmetric tensor component | | "chi" | specific to electric field gradient (efg) tensors, the quadrupolar constant | | "dc" | dipolar coupling constant; tensor type ignored | | "eigenvalues" | [v1,v2,v3] | | "eigenvectors" | [V1,V2,V3] | | "eulerzxz" | [alpha,beta,gamma] for z-x-z convention | | "eulerzyz" | [alpha,beta,gamma] for z-y-z convention | | "indices" | [modelIndex,atomIndex1,atomIndex2], with atomIndex2 = -1 if this tensor is single-atom based | | "isotropy" | (v1 + v2 + v3)/3 | | "j" | J-coupling constant;specific to indirect spin coupling (isc) tensors, in hz | | "quaternion" | the quaternion representing the rotation assoicated with the symmetric matrix | | "span" | abs(v2 - v0) | | "skew" | (3 (v1 - isotropy) / span) | | "symMatrix" | the symmetric matrix. | | "value" | v3, the eigenvalue furthest from the mean | | "string" | a listing of selected readable data | | "type" | the tensor type, such as "charge" or "isc" or "ms" |
Note that any other property name results in the entire set of properties to be returned in an associative array. | | x = y.trim("chars") | trims any one of the characters specified from both ends of the string y, or from every line of y if y is a set of lines. | | x = {atoms}.within("branch", {first atom}, {second atom}) | selects the second atom and all atoms in the molecular branch starting with the second atom but not including the first atom, ANDing the result with {atoms}. | | x = {atoms}.within(distance,[points]) | returns the subset of {atoms} that are within the specified distance of any point in the array of points. .Allows tracking groups of atoms by position after reloading files in a way that might change atom indexes.
| | x = {atoms}.within(distance, "$" + surfaceObjectId) | return the subset of {atoms} within the given distance of a point on the specified surface id, prepended with "$". | | x = {atoms}.within(distance,{otheratoms}) | returns the subset of {atoms} that are within the specified distance of any atom in {otheratoms}. Atoms in {otheratoms} are excluded.Compare to within(distance, {atoms}), which does not exclude other atoms or within(distance, TRUE, {atoms}), which excludes other atoms but does not limit return to the {atoms} subset.
For example, easy check for atoms that have the same position using distance = 0.001 | | x = {atoms}.within(ENTITY) | equivalent to the atoms selected by within(ENTITY), where ENTITY is one of "SHEET", "HELIX", "BOUNDBOX", "BASEPAIR", or "UNITCELL", where the result is ANDed with {atoms}. | | x = {atoms}.within("SEQUENCE",s) | return those atoms of {atoms} that are in a protein or nucleic acid sequence s expressed in single-letter notation, for example, "GGCCCTT" or "MAACYXV". The entire sequence must be found, and, if it is, its atoms will be ANDed with {atoms}. | | x = {atoms}.within("unitcell", u) | where u is the result of the unitcell() function. (That is, u is an array [o a b c] of origin and three lattice vectors.) Same as {atoms}.within(unitcell), except uses the specified unitcell, regardless of the unit cell of the atom's model. |
item-selector [i][j] back
Specific elements of lists and strings can be selected using a square bracket notation similar to that used for atom expressions. Positive numbers select for the specified element. For example, x = "testing"[3] selects for the third letter of the string, "s"; Zero selects for the last element: x = "testing"[0] selects "g". Negative numbers count from the end of the string backward, so x = "testing"[-1] selects "n". Two selectors select an inclusive range of items. x = "testing"[2][4] acts similar to a "substring()" method and selects characters 2 through 4 -- "est"; x = "testing"[-1][0] selects the last two characters, "ng". Similarly, for arrays, array("this", "test", 3)[0] selects the number 3, and x = array("this", "test", 3); print x[1][2] prints
this
test
user-defined functions back
Jmol allows for user-defined functions. Functions can appear in math expressions and can also be used as stand-alone "commands" without parentheses or commas. For example, function test(a,b,c){...} can be used in print test(1,2,3) or as the command TEST 1 2 3, without parentheses or commas. The only difference is that the return value from the function is disarded when the function is used as a command. Functions are not part of the state, so saving a state does not save user functions. Examples follow.
function rotateModel {
rotate {atomno=1} {atomno=2} 10
}
rotateModel | Without any parameters listed, any commands within the function declaration are processed with a single command word. | function rotateModelX(i,j,n) {
a[2] = getProperty("orientationInfo.moveTo")
var x = 10
rotate {atomno=i} {atomno=j} @{n + x}
a[2] = getProperty("orientationInfo.moveTo")
}
a = [];rotateModelX(10,11,30, a);print a[1]; | Any number of parameters may be passed into a function. The variable names are local to that function. Note that, like JavaScript, if an array is passed, it is passed "by reference," meaning that if its value is changed within the function, then that change is a global change. Variables preceded by "var" as in this example are local to that function. | function getDistance(i,j) {
var d = ({atomno=i}.distance({atomno=j})*100)%0
return d
}
print "the distance is " + getDistance(3,5) | The return command works as one might expect, returning the value of its expression. | function getXplusY {
return _x.x + _x.y
}
print {atomno=3}.getXplusY
print {*}.getXplusY.min
print {*}.getXplusY.max
print {*.CA}.getXplusY.all
| You can define atom selector functions. The local variable _x will represent the selected atom within the function. Such function references may include parameters in parentheses provided qualifiers such as .min, .max, or .all are not used within the function itself. |
Functions must be defined prior to use. Similar to the JavaScript language, a function must be declared prior to its inclusion in a script command. Unlike JavaScript, function names are not case-sensitive.
The PRIVATE keyword prior to a function definition (for example, private function test(){...}, introduced in Jmol 14.32 and 15.2) specifies that the function is private to the script in which it is being defined. If you wish to make all functions in a script private, add the one-line comment //@private at the top of the script. All functions defined in a Jmol state are implicitly private to that state script.
You can redefine a function as many times as you wish. In addition, you can save a function's definition using myFunctionDef = script("show function myFunction") where function myFunction has been defined. This can be useful if a function definition is to be replaced and later returned to its original value using script inline @myFunctionDef. In JavaScript, if a function name starts with "static_", then the function defined in one app will also be defined for all HTML5 apps, not just the one running the script.
special variables for functions back
You have access to several variables in scripts and functions that are being called.
| _arguments | the array of arguments delivered to this function | | _argCount | number of arguments delivered to this function | | _caller | an associative array listing all the local VARs defined in the calling function; note that _caller._caller is not valid. But you can define var caller = _caller, and then that will be passed to the next level of function calls. Perhaps surprisingly, these local variables to the called function are modifiable by that function even though they are local to the function or script making the call. |
customized command functions back
You can replace standard Jmol commands with commands of your own, and you can call functions just like any Jmol command, without the need for parentheses or commas. For example:
function measure (a,b) {
prompt "measuring " + a + " " + b
measure @a @b
}
measure {atomno=1} {atomno=2} | The function "measure" replaces the Jmol measure command, allowing now just two parameters and displaying a message box when executed. |
|
See also:
|
[Jmol Command Syntax] [Jmol Math] [Jmol Parameters] [atom expressions] [atom properties] case default echo for if message reset set set (misc) switch while undefined |
top search index |
|
See animation.htm
|
Sets selected animation parameters or turns animation on or off. Note that there are four distinct animation types that can be employed using Jmol: (1) files may contain multiple structures that are "played" sequencially, (2) models may contain vibrational modes that can be animated, (3) certain Jmol script commands (namely move, moveTo, navigate, restore ORIENTATION and zoomTo), can create the illusion of motion over a period of time, and (4) Jmol scripts can be run through in a predefined way, involving loop and delay. The "animation" command only refers to method (1). See also set backgroundModel.
|
| animation ON/OFF{default: ON} |
Turns on or off animation. With animation ON, the frame range is also reset to all frames. (An implicit frame range ALL command is executed. This functionality is for backward compatibility with Chime.) If this resetting is not desired because the frame range has been set, then frame PLAY or frame PLAYREV should be used instead of animation ON.
|
| animation DIRECTION 1 |
Sets the animation direction to be first frame to last frame.
|
| animation DIRECTION -1 |
Sets the animation direction to be from last frame to first frame.
|
| animation DISPLAY {atom set} |
Applies a filter to a running animation to display only a certain set of atoms.
|
| animation FPS [frames-per-second] |
Sets the animation frames per second (maximum 50).
|
| animation FRAMES [ array of model numbers ] |
animation frames allows defining of a set of models to be displayed in any desired order. For example, anim frames [ 1 2 3 4 5 10 9 8 7 6 ] . You can specify a range of values using negative numbers. For example, the sequence "1-5, then 10-6" can also be written [ 1 -5 10 -6]. This functionality is useful, for example, when output from an IRC (intrinsic reaction coordinates) calculation is being used. See additional frame options at the frame command.
|
| animation MODE LOOP |
Sets the animation mode to restart the sequence automatically when the last frame has played.
|
| animation MODE LOOP [time-delay1] [time-delay2] |
Allows for a time delay at the start and end of the loop.
|
| animation MODE ONCE |
Sets the animation to play once through and then stop (the default mode).
|
| animation MODE PALINDROME |
Sets the animation to play forward and back endlessly.
|
| animation MODE PALINDROME [time-delay1] [time-delay2] |
Allows for a time delay at the start and end of the palindrome.
|
| animation MORPH (integer) |
The animation MORPH option interpolates between conformations in a trajectory or between two models from different sources, generating intermediate points to display. In either case, the option requires a previous LOAD TRAJECTORY. animation MORPH creates a linear morph consisting of the designated number of representations inserted between trajectories. For example, load test.pse;animation morph 3. For two models, one might use load trajectory "test1.pdb" "test2.pdb"; animation morph 32. Note that, by itself, animation MORPH does not play the animation. To do that, it must be followed by commands such as animation mode palindrome; animation on;. The animation frames and animation display commands do not apply when a trajectory morph is animated.
|
|
Examples: |
See animation.htm
|
See also:
|
capture file frame invertSelected move moveto rotateSelected set (misc) spin translate translateSelected write (images and frames) zoom zoomto undefined |
top search index |
|
Turns on or off displayed axes, and determines their line style and line width (as a decimal number, in Angstroms).
|
| axes POSITION [x y] or [x y%] labels |
For crystal structures only, adds a second small axis set that is Cartesian. [x y] or [x y%] is the screen position. Uses the specified labels for the axes labels, for example "xyz" or "abc". The label can be one, two, or three characters, for showing just x, just xy, or xyz, respectively. Cleared using AXES POSITION OFF (restoring the axes to their default labels and set on the unit cell only).
|
See also:
|
boundbox measure set (visibility) unitcell undefined |
top search index |
|
See structure.htm
|
Shows the backbone of a protein or nucleic acid macromolecule by connecting the alpha carbons. The selection of backbone units to display depends upon the currently selected atoms and the bondmode setting.
|
| backbone ON/OFF{default: ON} |
Turns the backbone on or off
|
| backbone ONLY |
Turns backbone rendering on and all other rendering (including labels) off.
|
| backbone [backbone-radius] |
Backbone radius can be specified in angstroms using a decimal number (1.0, 2.0, etc.). A negative number also implies ONLY.
|
|
Examples: |
See structure.htm
|
See also:
|
background cartoon dots ellipsoid geoSurface meshribbon ribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill strand trace vector wireframe undefined |
top search index |
|
Calculates specific quantities.
|
| calculate HBONDS STRUCTURE |
Calculates the hydrogen bonds that define the DSSP structures generated with calculate STRUCTURE. These are not all of the "hydrogen bonds" identified by DSSP; rather they are just the ones that define the helixes, sheets, and bridges.
|
| calculate HYDROGENS [atom-expression]{default: *} |
Adds hydrogens at calculated positions based on bonding patterns at the designated atoms or, if no atoms are specified, at all atoms. Note that this command is not intended to be used for the assignment of hydrogen atoms in standard PDB files. All atoms must have any formal charges already designated, and all multiple bonds must be in place. If you want to add hydogen atoms to a standard PDB structure, use set pdbAddHydrogens prior to loading the file. Jmol will then do a proper hydrogen atom addition, to proteins, nucleic acids, carbohydrates, and all ligands. See set pdbAddHydrogens, below. Adding TRUE also includes connect aromatic modify; calculate aromatic to add multiple bonding.
|
| calculate STRUCTURE type [atom-expression] |
Calculates the secondary structure of proteins or nucleic acids . Options are based on the type keyword. The calculation is performed for all models containing any of the indicated atoms or, if no atoms are specified, the set of currently selected atoms. For these models all cartoons and other biomolecular shapes are turned off. The next cartoons on command will then show a complete set of cartoons. This command also recalculates the polymer chains making up a protein or nucleic acid. The results are affected by any bonding that has changed via the connect command. A typical use involves PDB files that load with incomplete bonding (because the author specified only a fraction of the bonds). After loading, one can issue connect to use Jmol's autobonding feature, then calculate structure to regenerate the secondary structure.
| DSSP | Calculates the secondary structure of proteins based on Jmol's implementation of DSSP. | | RAMACHANDRAN | Calculates protein secondary structure using a Ramachandran-angle-based method original to Jmol. The default DSSP setting is to ignore any file-based backbone amide hydrogens, but this can be changed using set dsspCalculateHydrogenAlways FALSE. | | DSSR | Defining the (Secondary) Structures of RNA. The calculation works equally well with DNA. ...TO DO... |
If no type is given, DSSP is assumed unless the global setting set defaultStructureDSSP is set FALSE, in which case RAMACHANDRAN is assumed.
|
|
See also:
|
delete hbonds set (files and scripts) undefined |
top search index |
|
See structure.htm
|
Cartoons are the classic shapes the are used to depict alpha helices and beta-pleated sheets. A combination of cartoons and rockets can be displayed using cartoons along with set cartoonRockets. The set rocketBarrels option removes the arrow heads from cartoon rockets. In addition, set cartoonLadders removes the bases from nucleic acid cartoons but leaves the ladder "rungs". The hermite level determines the overall cross-section of the helix and sheet renderings. Hermite levels 6 or higher produces a ribbon cross-section in the shape of an ellipse. Use set ribbonAspectRatio 4 rather than the default value of 16 for a more rounded ellipse.
|
| cartoon ON/OFF{default: ON} |
| cartoon ONLY |
Turns cartoon rendering on and all other rendering (including labels) off.
|
| cartoon [cartoon-radius] |
A negative number also implies ONLY.
|
|
Examples: |
See structure.htm
|
See also:
|
backbone background dots ellipsoid geoSurface meshribbon ribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill strand trace vector wireframe undefined |
top search index |
[object]
[translucent/opaque]
[color schemes and color PROPERTY xxx]
[color inheritance]
|
In general, the color command takes the following syntax:
color [object] [translucent/opaque] [color, property, or color scheme]
Colors can be designated as one of the [standard JavaScript colors], as a red-green-blue triplet in square brackets, [255, 0, 255], as a red-green-blue triplet expressed as a six-digit hexidecimal number in brackets, [xFF00FF], as a triplet expressed as a point in red-green-blue color space -- {255,0,255} or fractional {0.5, 0.5, 1} . To specifiy a set of atoms to color, you can either select them first -- select *.N?; color green -- or specify them using atom expression notation: color {*.N?} green.
[object] back
The color command takes several forms, depending upon the type of object being colored: an atom object, a bond object, a chemical element, or a model object. This section of the guide discusses each of these in turn:
Additional information external to this documentation can be found in relation to [Jmol color schemes] and [standard JavaScript color names and codes]. In addition, a page is available that lays out the [Jmol color command matrix]. Color schemes may be customized using the set userColorScheme command.
[translucent/opaque] back
The color command allows an optional color modifier of TRANSLUCENT or OPAQUE, which can be used with any object, either alone or with a color. TRANSLUCENT can take an integer in the range 0-8 (indicating eighths -- 0, 1/8, 2/8, etc.), 32-255 (indicating fraction of 256), or a decimal in the range 0.0 to 1.0. Larger numbers are more translucent -- dimmer. Currently implemented transclucencies are 0 (opaque), 0.125 (1, 32), 0.25 (2, 64), 0.375 (3, 96), 0.5 (4, 128), 0.625 (5, 160), 0.75 (6, 192), 0.875 (7, 224), and 1.0 (8, 256). Note that this last "fully transparent" option can be used to show "half" bonds to the selected atom, which are not visible themselves. (This is a common rendering for periodic structures to show bonding beyond the unit cell. In that case, we would make sure we had loaded the atoms near the unit cell, using something like load aflowlib/10 packed 1.0 followed by color {!cell=555} transparent 1.0.) The default, if no number is given, is TRANSLUCENT 0.5, which can be set using "defaultTranslucent = x.xx", where x.xx is a decimal number. For example:
color atoms TRANSLUCENT orange
color ribbons TRANSLUCENT 0.5 [255, 165, 0]
select oxygen; color opaque.
If neither TRANSLUCENT nor OPAQUE is specified, OPAQUE is assumed. Thus, color atoms red and color atoms OPAQUE red are synonymous.
[color schemes and color PROPERTY xxx] back
Besides the standard ways of representing a color, Jmol allows coloring based on properties or by one of the known Jmol color schemes, which include:
| general schemes | "roygb" (default rainbow), "bgyor" (reverse rainbow), "bwr" (blue-white-red), "rwb" (red-white-blue), "low" (red-green), "high" (green-blue), "bw" (black-white), "wb" (white-black), or "friendly" (an accessibility option for color-blind users) | | biomolecule schemes | "amino", "shapely", "chain", "structure", "group", "monomer" | | property schemes | "formalCharge", "partialCharge", "surfaceDistance", "absoluteTemperature", "relativeTemperature" (or just "temperature") | | user-defined schemes | "user" and its reverse, "resu"; see user-defined color schemes. |
The general color schemes can be used with any property. If color RELATIVETEMPERATURE is used, the color range will depend upon the setting of the rangeSelected flag.
You can also color atom-based objects based on user-defined properties read from an external file or standard Jmol atom properties such as partialCharge that Jmol has read from the model file. In the case of Jmol atom properties, use the keyword PROPERTY followed by the name the property, as in color atoms PROPERTY partialCharge. In the case of user-defined properties (created using the data command), which always start with "PROPERTY_", simply give the property name: x = load("mydata.txt");data "property_mydata @x";select model=2;color atoms property_mydata. When using either PROPERTY or PROPERTY_xxx, you can set the absolute range of values that will span the full spectrum of colors of the propertyColorScheme you have chosen. Simply add the keyword ABSOLUTE followed by the minimum and maximum values you wish to use for the two ends of the spectrum. So, for example: color atoms property temperature ABSOLUTE 0.0 30.0.
[color inheritance] back
Many objects inherit both color and opacity from the underlying associated atom (which, themselves "inherit" their color by default from their associated chemical element). For example, by default a bond will inherit the two colors+translucencies of its endpoint atoms. If you simply 'color atoms translucent', then both the atoms and the bonds will be translucent. But if you 'color bonds opaque' or 'color bonds red' and also 'color atoms translucent' only the atoms will be translucent.
The level of 'translucent' can be controlled. The algorithm allows for proper mixing of colors for two translucent objects and approximately correct mixing for more than two overlapping translucent objects.
|
| color [color-scheme] |
Sets the previously selected atom set to a color based on a color name or value or one of the [Jmol color schemes]. The color name "CONTRAST" is either white or black, selected specifically to best contrast with the current background color.
|
Examples: |
define ~myset (*.N?)
select ~myset
color green
select *
color cartoons structure
color rockets chain
color backbone blue |
|
| color [color-scheme] TRANSLUCENT |
The additional parameter TRANSLUCENT creates a gradient of translucency from transparent to opaque across the color scheme.
|
Examples: |
define ~myset (*.N?)
select ~myset
color green
select *
color cartoons structure
color rockets chain
color backbone blue |
|
| color SCALE |
Sets the color of the scale.
|
|
top search index |
|
Sets the color of atom-related objects (atoms, backbone, cartoons, dots, halos, labels, meshribbon, polyhedra, rockets, stars, strands, struts , trace, and vibration vectors).
|
| color [atom-associated-object] [color-scheme] |
Sets the color of atom-related objects based on a previously selected atom set to a specific color, a color scheme, or back to its default color (CPK), or to inherit the color of its associated atom (NONE). In the case of "color atoms", CPK and NONE both revert to the default color. In the case of "color labels", coloring a label to the background color automatically uses the background contrast color, not the actual background color (white or black, depending upon the background color). This effect also can be produced for atoms, bonds, and other objects using the color CONTRAST. The If it is desired for some reason to color a label the background color, then the label should be colored using a color very close to the background color but not it exactly. For instance, to color labels black with a black background, use [0,0,1] instead of [0,0,0].
|
Examples: in new window using caffeine.xyz |
select oxygen;color atoms green
select carbon;color atoms TRANSLUCENT white;color bonds green;
select carbon;color bonds OPAQUE [255,196,196] |
|
See atoms.htm bonds.htm
|
| color BALLS [color-scheme] |
Sets the color of the space-fill sphere of an atom without coloring the bonds leading to that atom or other atom-based objects such as stars and polyhedra.
|
|
See also:
|
background color (bond object) color (element) color (model object) color (other) color (scheme) color labels color measures label set (visibility) set userColorScheme show undefined |
top search index |
|
Three types of bonds are distinguished by Jmol for coloring purposes: regular bonds, disulfide bonds, and hydrogen bonds. Each can be colored independently, and hydrogen bond colors in proteins can take on a special coloring scheme based on their connectivity.
|
| color HBONDS TYPE |
Colors hydrogen bonds specifically in proteins based on how many residues one end is from the other. Note that to get this effect, one must first execute "hbonds ON" and then issue "color hbonds TYPE".'+' The colors assigned are based on the number of redidues between the interacting H atoms. This TENDS to indicate secondary structure, but is not perfect.The correlation between color and offset are as follows:'+'
| Color | Offset | | green | -4 | | cyan | -3 | | white | +2 | | magenta | +3 (turns) | | red | +4 (alpha-helix) | | orange | +5 | | yellow | other (e.g. beta-pleated sheet) |
|
See also:
|
background color (atom object) color (element) color (model object) color (other) color (scheme) color labels color measures hbonds set (visibility) set userColorScheme show undefined |
top search index |
|
Jmol uses a variety of predefined and user-defined color schemes. Nine additional standard color schemes are available, including five "universally readable" scientific palettes (batlow,cividis,kry,thermal,viridis) as discussed in the paper The misuse of colour in science communication and four (inferno,magma,plasma,turbo) that are from the
R-Project viridis package. For example: load *1crn; color property atomno "viridis" Scheme palettes can be found in the src/org/jmol/util/colorschemes/ directory.Also reads files using https://... from any online source in binary or ASCII color scheme formats:
| binary | [optional 32-bit header ignored][rrrr...(256)][gggg...(256)][bbbb...(256)] 768 or 800 bytes total
| | ASCII | either three columns of r g b per line, or four columns index r g b
|
For example:
load *1crn;
color property atomno ""https://github.com/fiji/fiji/blob/master/luts/cool.lut?raw=true"";
Filenames also work in the color() function:
print color(""viridis"").colors
print color(""https://github.com/Image-Py/imagepy/blob/master/imagepy/data/luts/Others/morgenstemning.lut?raw=true"").colors;
For more color palette look-up table files, see fiji-luts, Py-luts, and imagej-luts."
The following commands can be used to directly map those schemes to atoms and shapes based on a given range of values. In each case, the default property color scheme and range is set. So, for example, if color {*} property temperature "rwb" range 0 100 is issued, then after that one can use color {*} property_xxx , and color scheme RWB will be used again with the range 0 to 100. Note that using the color() function you can design your own color schemes based on progressions of RGB or HSL (hue/saturation/lightness).
|
| color {atomSet} PROPERTY DSSR "dssrStructureType" RANGE [min] [max] |
Colors a selection of nucleotides having the DSSR specified type by a color scheme based on entry in the DSSR data structure for the model: 1 for first entry, 2 for second entry, etc. With 0 (gray) for "not of this type" based on a standard atom property such as temperature or occupancy using a specific color scheme and range. Allowed types are plural and include: bulges, coaxStacks, hairpins, hbonds, helicies, iloops, isoCanonPairs, junctions, kissingLoops, multiplets, nonStack, nts, pairs, ssSegments, stacks, and stems. For example: load =4fe5/dssr; cartoons only;set cartoonSteps; color property dssr junctions.
|
See also:
|
background color (atom object) color (bond object) color (element) color (model object) color (other) color labels color measures set (visibility) set userColorScheme show undefined |
top search index |
|
Compares two models and optionally reorients the first model relative to the second based on a given atom-atom coordinate pairing or quaternion-based group-group orientation pairing. References to the atom-atom correlation algorithm can be found in the literature [1] and [2]. Quaternion-based orientation pairing is an unpublished technique specific to Jmol at this point. It minimizes the standard deviation of the correlated quaternion frames for groups in the two models using spherical averaging. (Quaternion comparison is based on minimizing the difference in orientation, not position. Results of this option depend upon the setting of set quaternionFrame).
Except for the BONDS option, by default the command does not move any atoms and just reports RMSD. A return of "NaN" indicates that the specified atom sets could not be matched because there was not a 1:1 correlation of atoms. The independent options ROTATE and TRANSLATE allow the option to do just rotation, do just center-of-mass translation, or do both. An optional number of seconds can be added and can be 0 to effect no animation. (The default is 1 second.) For example:
| compare {2.1} {1.1} SUBSET {*.CA} | reports RMSD for the comparison of two models based on alpha carbons only. | | compare {2.1} {1.1} ROTATE TRANSLATE 2.0 | Compares the second model to the first and rotates and translates it into superposition with the first model over the course of 2 seconds. | load files "$tyrosine" "$lysergamide";frame *;
compare {1.1} {2.1} BONDS "c1ccccc1CCN" rotate translate | flexibly fits tyrosine onto lysergamide based on the aromatic ring and C-C-N atoms only, overlaying the structures over 1 second. Note that the required initial internal bond rotations are carried out even if ROTATION and TRANSLATION are not indicated. |
See also the compare() function. [1] Berthold K. P. Horn, "Closed-form solution of absolute orientation using unit quaternions" J. Opt. Soc. Amer. A, 1987, Vol. 4, pp. 629-64. [2] G. R. Kneller, "Superposition of Molecular Structures Using Quaternions" Molecular Simulation, 1991, Vol. 7, pp. 113-119.
|
| compare A B map "stddev" |
A or B can be atom set or array of points, and map is an integer array indicating the ordering of A that matches B. For example, if A is [@1,@2,@3] and B is in order [@2,@3,@1] then the map array would be [2 3 1], since B[1](i.e. @2) matches a[2] and B[2] matches A[3], and B[3] matches A[1]. A may have more elements than B, provided the map has the same elements as B.
|
| compare {2.1} {1.1} BONDS SMILES HYDROGEN |
Adds HYDROGEN check for aligning methyl and methylene groups properly.
|
| compare FRAMES |
compare FRAMES is a powerful method that allows the automated alignment of a set of frames such that each model in a sequence is repositioned to have the closest fit to the model before it. This option is particularly useful for visualizing the results of intrinsic reaction coordinate (IRC) calculations, where each model closely resembles the previous model. In the animations of a cyclohexane ring flip, below, on the left we see the animation as it came from the calculation. It is not at all easy to see what is happening here. On the right, we see the same animation after compare FRAMES. Now it is much clearer (especially when you explore it in 3D) that the ring flip is a smooth transition from chair to half chair to twist boat and back, without having to go through a boat transition state.
 |  | | frame PLAY | compare FRAMES
frame PLAY |
All of the options described below are also available for compare FRAMES. A subset of models can also be specified by adding the models to be aligned before the FRAMES keyword. For example: compare {file=2} {1.1} FRAMES.
|
| compare {model1} {model2} SUBSET {atomSet} ATOMS [paired atom list] |
Compares the specified subset of atoms of two models, minimizing the RMSD of paired atom coordinates. If the SUBSET option is not specified, the models are matched atom-for-atom based on "SPINE" atoms (*.CA, *.N, *.C for proteins; *.P, *.O3*, *.O5*, *.C3*, *.C4*, *.C5 for nucleic acids). The keyword ATOMS is optional and may be followed by any number of specific pairs of atom sets to be correlated. For example, compare {2.1} {1.1} SUBSET {*.CA} ATOMS {10-20} {50-60} {30-40} {20-30} ROTATE TRANSLATE will correlate the positions of alpha carbon atoms in groups 10-20 and 30-40 of model 2.1 with corresponding atoms in groups 50-60 and 20-30 of model 1.1 and move all atoms in model 2.1 in the process. The result of this atom-atom pairing comparison is essentially the same as the PyMol pair_fit command, though easier to implement and using an exact form of the structure-structure correlation rather than an iterative process.
|
| compare {model1} {model2} SMARTS or SMILES "smartsString" |
This option allows the alignment of two structures based on SMILES or SMARTS atom matching. The basic idea is to use a SMILES (whole molecule) or SMARTS (substructure) description to find the atoms in one structure that correlate one-for-one with atoms in the second structure, then find the rotation and translation that best aligns them.
|
| compare {atomSet} [array of coordinates] |
Compares a set of atom coordinates to a corresponding ordered set of points.
|
| compare {atomSet} ATOMS {subset1} [coords1] {subset2} [coords2]. . . |
Compares a subset of atom coordinates to a corresponding ordered set of points.
|
| compare {model1} {model2} BONDS "smartsString" |
The BONDS option does a flexible fit by first constructing a list of matching dihedrals based on the SMARTS (substructure) string, rotating the bonds into position, then doing a COMPARE operation based on the matching atoms. The preliminary rotation is carried out even if ROTATE and TRANSLATE are not present. In the case of compare {1.1} {2.1} BONDS "c1ccccc1CCN", the initial internal rotation can be done in a prelminary step using the following command: rotate branch @{compare({1.1},{2.1},"c1ccccc1CCN","BONDS")} 0. See rotate BRANCH for details.
|
| compare {model1} {model2} ORIENTATIONS [paired atom list] |
Compares the specified subset of atoms of two models, minimizing the RMSD of paired group quaternion orientations. If no other parameters are included, the models are matched group for group based on the current setting of quaternionFrame. The keyword ORIENTATIONS may be followed by any number of specific pairs of atom sets to be correlated. For example, set quaternionFrame "C"; compare {2.1} {1.1} QUATERNIONS {10-20 or 30-40} {50-60 or 80-90} ROTATE TRANSLATE will correlate the orientations of alpha carbon atoms in groups 10-20 and 30-40 of model 2.1 with corresponding orientations in groups 50-60 and 80-90 of model 1.1 and move all atoms in model 2.1 in the process. The result of this orientation pairing comparison gives the best fit of orientations and the best translation, but not necessarily the best rotation to fit coordinate positions. The ORIENTATION option has no corresponding PyMol command.
|
| compare {model1} {model2} ORIENTATIONS [paired quaternion array list] |
The ORIENTATION option allows for explicit comparison of quaternion arrays rather than atom lists. The result is independent of the setting of quaternionFrame. These arrays can be specified in terms of variables. For example: qset1 = quaternion({10-20:A/1.1}); qset2 = quaternion({20-30:D/2.1}); compare {2.1} {1.1} ORIENTATIONS @qset2 @qset1.
|
| compare {atomSet1} {atomSet2} POLYHEDRA |
After creating polyhedra with the {#.polyhedra} command with or without the UNITCELL option, this command compares two atom sets (perhaps two models) by first mapping atoms between the sets using a specialized polyhedral SMARTS analysis, then calculates an RMSD and, if the ROTATE and/or TRANSLATE options are included, move atom sets to overlay them in the best possible way.
|
| compare {atomSet1} {atomSet2} SUBSET {polyhedraCenters} POLYHEDRA |
Same as COMPARE ... POLYHEDRA, but only compares a subset of polyhedra.
|
| compare {model1} {model2} ATOMS @atom1 @atom2 POLYHEDRA |
Specifically compares two models based on two specific atoms, which must be one in {atomSet1} and one in {atomSet2}. This allows direct comparison of two crystal structures based on local polyhedron coordinates and atom identies.
|
| compare FRAMES POLYHEDRA |
Compare two or more models one in each frame, based on the current set of polyhedra.
|
top search index |
|
File types PDB, mmCIF, CIF, and SHELX RES all allow for the designation of certain atoms to be in "alternative locations" or in "disorder groups". This leads to two or more possible structures, or "configurations". While full treatment of this issue is not possible, Jmol can display the different possible configurations described in these files. The configuration command selects the specified configuration (but does not {#.restrict}#.display#.atomPropertiesconfiguration
|
| configuration [configuration number] |
For CIF files CONFIGURATION 2 selects for all atoms that either have no disorder group indicated or have atom_site_disorder_group 2 or -2. atom_site_disorder_assembly is not read. (Atom property_part is assigned the signed value 2 or -2. For SHELX files, CONFIGURATION 2 selects for property_part=0 or property_part=2. For PDB and mmCIF files, a positive configuration number n gives the nth entry in the set of altlocs for a given residue.Also for biomolecules, select config=0 selects for all atoms that have fewer than two alternate locations. These are the atoms that, using an atom-based (FirstGlance) rather than a residue-based (PDB spec) interpretation of "conformation" will be included in every conformation. See below for negative n.
|
| configuration "A" |
Allows checking specific lettered configurations.
|
| configuration -n |
Indicating a negative number for a configuration has different meanings depending upon the file type.
| CIF, SHELX | CIF and SHELX allow negative PART values. These symmetry-based occupancy issues arise, for example, when a solvent is alternatively on one side or another of a C2 rotation CONFIGURATION -2 selects for property_part=0 or property_part=2 or property_part=-2. The atoms with negative part will be rendered translucent (since they are a bit ghost-like). | | PDB, mmCIF | For biomolecules, CONFIGURATION -n For n from 1 to the number of alternative locations in a model (whatever their designation), the configuration is set to (all atoms with nth altloc) + (first listed entry for chain, residue, insertion code, and atom name when altloc for this atom is not found). |
|
top search index |
[minimum and maximum distances]
[source and target atom sets]
[bond type]
[radius option]
[color option]
[modify/create option]
|
The connect command allows real-time bond manipulation, allowing the user or application to connect and disconnect specific atom sets. The general syntax is as follows:
connect [minimum and maximum distances] [source and target atom sets] [bond type] [radius option] [color option] [modify/create option]
(connect by itself deletes all bonds and then creates bonds based on Jmol default bond-generating algorithms, all as single bonds, without respect to what bonding patterns might have been indicated in the model file.)
[minimum and maximum distances] back
Distances are given in Angstroms, either as decimals or integers. If only one distance parameter is given, it represents a maximum distance. If neither the minimum nor the maximum distance parameter is given, all connections between the two atom sets are made, regardless of distance. The option to connect atoms based on ranges of percentage of bonding/ionic radii instead of fixed values can be specified using a % sign after a distance.
[source and target atom sets] back
The source and target atom sets are embedded atom expressions and therefore must be enclosed in parentheses. If the source atom set is not given, it is taken to be the currently selected atom set, "(selected)". If neither atom set is given, "(selected) (selected)" is assumed. The atom expression "_1" in the second selection set signifies "the atom selected in the first set". Thus, it is possible to select something like (_N) (_O and not within(chain, _1)) -- meaning "all nitrogens and all oxygens not in the same chain as the selected nitrogen." Of course, this would be used with a distance qualifier.
[bond type] back
Unless otherwise specified, connections are automatically introduced as single bonds. Any one of the following bond types may be specified: SINGLE, DOUBLE, TRIPLE, QUADRUPLE, QUINTUPLE, SEXTUPLE, AROMATIC, PARTIAL, PARTIALDOUBLE, HBOND, STRUT or UNSPECIFIED. In appearance, AROMATIC and PARTIALDOUBLE are identical except for which side of the bond is represented by a dashed line. PARTIAL and HBOND are both dashed, but they have different patterns, and newly created hydrogen bonds are only thin lines. Additional bond types include ATROPISOMER (the single bond between two aromatic rings with restricted rotation), AROMATICSINGLE, AROMATICDOUBLE, partial numeric bond order (including -1 for PARTIAL, 1.5 for AROMATIC, -1.5 for PARTIALDOUBLE, 2.5 for PARTIALTRIPLE, and -2.5 for PARTIALTRIPLE2), as well as a fully generalized set of partial bonds indicated with
connect ... partial N.M
where N is the number of lines (from 1 to 5) and M is a binary mask indicating which lines are dashed:
| M | binary | meaning | | 1 | 00001 | first line dashed | | 2 | 00010 | second line dashed | | 3 | 00011 | first and second lines dashed | | 4 | 00100 | third line dashed | | ... | ... | ... | | 31 | 11111 | all lines dashed |
So, for example, we have:
| partial 1.0 | single | | partial 1.1 | same as "partial" | | partial 2.0 | double | | partial 2.1 | same appearance as "aromatic", though not "aromatic" | | partial 2.2 | partialDouble | | partial 3.0 | triple | | partial 3.1 | partialTriple | | partial 3.4 | parialTriple2 |
[radius option] back
Addition of the keyword "radius" followed by a distance in angstroms allows definition of the radius of a modified or newly created bond. If the modify/create option is absent, then "modify" is assumed; if the bond type is absent, then bonds of any type are set, but their bond type is not changed.
[color option] back
Addition of a color name or designation optionally along with the keyword "translucent" or "opaque" allows definition of the color and/or translucency of a modified or newly created bond. If the modify/create option is absent, then "modify" is assumed; if the bond type is absent, then bonds of any type are set.
[modify/create option] back
Five additional mutually exclusive options relate to what sort of connections are made. The default when a radius or color option is present is "Modify"; otherwise the default is "ModifyOrCreate". These include:
| Auto | Adjusts bonding using the Jmol autobonding algorithms, specifically applicable to bond types AROMATIC or HYDROGEN, or when no bond type is given. | | Create | Only new bonds will be created. If a bond of any type already exists between two matching atoms, it will not be affected. | | Modify | Only pre-existing bonds will be modified. No new bonds will be created. | | ModifyOrCreate | If the connection fits the parameters, it will be made. Bonds already present between these atoms will be replaced. | | Delete | Delete the specified connections. |
|
| connect NBO nbotype |
Connect atoms in the currently visible model using a resonance structure configuration found in an NBO .46 or .nbo file, where nbotype is one of alpha, beta, 46, 46a, 46b, nrtstr_n, nrtstra_n, rs_n, rsa_n, or rsb_n.
|
Examples: in new window using caffeine.xyz |
# delete all bonds WITHIN a selected atom set
connect (selected) (selected) DELETE
# two ways to link atom #5 with atom#11
connect @5 @11 DOUBLE
select atomno=5,atomno=11; connect (selected)
# connect all carbons with hydrogens that are within the range 1.0 to 1.2 angstroms and are not already connected
connect 1.0 1.2 (carbon) (hydrogen) PARTIAL CREATE
# change all bonds to single bonds
connect (all) (all) SINGLE MODIFY
# connect every atom with every other atom that is within 1.5 angstroms whether it is connected already or not
connect 1.5 (all) (all) ModifyOrCreate
connect {*} {*} aromatic modify; calculate aromatic
# delete all bonds TO a selected atom set
connect (selected) (not selected) DELETE |
|
See also:
|
bondorder hbonds set (bond styles) set (files and scripts) ssbonds wireframe undefined |
top search index |
Setting atom properties
Properties set during file reading
|
The data command allows data to be introduced in-line or via a variable. The command consists of two statements, data "label" and end "label", between which the data are presented on as many lines as desired. "label" may be any string, though strings starting with "property_" are special (see below). Quotes must be used in both the data line and the end line. The first word of the label defines the data type, but the label itself may be any number of words. If the data type is "model" as in the following example, then the data is interpreted as an in-line model (and loaded using the default lattice, if crystallographic). If the data type is "append", then the data is interpreted as a model, and the model is appended either into a new frame or into the last existing frame, based on the setting of set appendNew. Additional data types may be loaded and later shown, but they will be ignored by Jmol.
background red;
data "model example"
2
testing
C 1 1 1
O 2 2 2
end "model example";show data |
Note that the data statement itself should not include a semicolon at the end. In the specific case of a model file, if it is desired to use no new-line characters, you can start the data with | (vertical bar) and then use a vertical bar to separate all lines: data "model example"|2|testing|C 1 1 1|O 2 2 2|end "model example";show data. For this option you MUST start the data with a vertical bar immediately following the quotation mark closing the label or on the very next line. If the first character is a vertical bar or a new-line character, it is not part of the model. To include data representing more than one file, first define a data separator using set dataSeparator, for example, set dataSeparator "~~~". Then use that separator between data sets. The data command thus provides an alternative to the JavaScript Jmol.js (applet-only) loadInline() function. It can be included in any script, and commands can come before and after it for further processing. Note that model data in the system clipboard can also be pasted into the applet console or endered into the application using Edit...Paste for direct introduction into Jmol. Using load data instead of just data you can load model data with all of the loading options of the standard LOAD command. See also show data, getProperty data, and load "@x".
Setting atom properties back
If you just want to assign a set of properties to a set of atoms, and you have the properties in a file as a list of numbers, you do not need the DATA command. Simply load the values straight into an atom property directly from the file:
{*}.property_xxx = load("myfile.dat")
Atom property data may be loaded into Jmol using the DATA command. In addition, when reading some model file types (CRYSTAL, specifically) Jmol will create property_xxx data automatically -- check the Java console after file loading to see a report of what properties were assigned. To assign properties using the DATA command, first select the atoms to which data are to be assigned. Then, to assign the data, use DATA "property_xxx"...end "property_xxx", where "xxx" is any alphanumeric string. Properties are assigned sequentially to the currently selected atom set, and will be assigned to atoms in the selection set one after another until either the data or the atom list is exhausted. If the data are exhausted before the selected atoms, then the value 0 is recorded for each of the remaining selected atoms. In this way, if only a few atoms need data, only a few can be selected and assigned values. Properties can be checked using atom labels: (label %[property_xxx]). The following special values for xxx read data into Jmol exactly as though read from a model file: atomName, atomType, coord, element, formalCharge, occupancy (0 - 100), partialCharge, temperature, valence, vanDerWaals, and vibrationVector. Any other label will be saved simply under its property name.
To read selected data that is in tab- or space-separated format (for example, from a spreadsheet), specify which column the data is in using set propertyDataField = n, (n = 1 being the first column), prior to the data command. Lines having fewer than n tokens will be ignored. If the data is fixed-column format, then n is the starting column number, and set propertyDataColumnCount to be the number of columns to assign to this field. Lines shorter than the required number of characters will be ignored. Setting propertyDataField to 0 indicates that no data field is present, and data are to be read sequentially.
Atom selection need not be contiguous. If you want to associate specific data with specific atom numbers, a column containing these atom numbers (starting with 1 for each model loaded) can be specified using propertyAtomNumberField = m. If the data is fixed-column format, then m is the starting column number, and also set propertyAtomColumnCount to be the number of columns to assign to this field. Specifying 0 for m indicates that the set of currently selected atoms should be assigned values from the data.
Atom property data may also be loaded from variables. To do this, use add "@x", where x is a variable name within the quotation marks defining the first parameter of the data command: DATA "property_partialCharge @x" or DATA "property_mydata 66 3 @x". No end line is required. The variable x should already contain a list of numbers, perhaps from using the x = load("myfile.dat"); perhaps just by creating a string of numbers: x = "2.3 3.4 5.6 7.8...".
The data() function also allows direct conversion of data into arrays, which can be directly stored in an atom property using, for example,
{*.CA/2.1}.temperature = data(load("mydata.dat"),6,0,3)
meaning, "Read the file mydata.dat and store the sixth free-format field of each line starting from the third line as the temperature of the C-alpha carbons of model 2.1."
Properties set during file reading back
property_xxxx fields are also sometimes created during the loading of certain file types. specifically:
| CASTEP | property_spin | The CASTEP reader saves spin density data as property_spin. | | CIF, SHELX | property_part | the "PART" field of a SHELX .res file or the atom_site_disorder_group value in a CIF file. For a negative part, indicating fragment relation by symmetry operation, the fragments are given unique altloc values that range [1-9A-Za-z]. "A" and "a" can be distinguished using LIKE, as in select altloc LIKE "a", which will match "a" but not "A". For space groups with m symmetry operations and n parts, if m*n > 53 then altloc values will restart at "A" after reaching "z". This may result in undesired bonding between parts. property_part overrides altloc value for WRITE CIF. | | CRYSTAL | property_irreducible, property_spin, property_magneticMoment | The CRYSTAL reader stores the presence of "T" on an atom coordinate line as property_irreducible = 1. "ATOMIC SPINS SET" data are saved as property_spin; "TOTAL ATOMIC SPINS" data are saved as property_magneticMoment. | | Gaussian | property_spin, property_J | The Gaussian file reader saves calculated spin densities and NMR J-coupling values as property_spin and property_J. (The latter is an array of arrays.) | | MMCIF | validation properties | Loading an MMCIF file using load =xxxx/val adds validation metrics for atoms and residues, including property_bond_angles, property_bond_lengths, property_chirals, property_clashes, property_planes, property_rama, property_RNA_suite, property_RNA_pucker, property_rsr, property_sidechains, and property_types_of_outlier. For more information, see structure validation annotations. | | PDB | property_tlsGroup | For PDB files with TLS (translation, libration and screw-rotation displacement) refinement data in "REMARK 3 TLS DETAILS". Full TLS information is added to the auxiliaryInfo for the model under key "TLS"; property_tlsGroup for an atom identifies the ID within this listing where details can be found. | | PWMAT | property_pwm_* | The PWMAT reader saves magnetic and other named data block scalar data with the prefix property_pwm_ followed by the name of the data block. Vector data are saved with suffixes _x, _y, and _z. | | SDF V3000 | SGROUP data | FIELDDATA within a V3000 connection table file SGROUP block is read into property_xxx, where xxx is the FIELDNAME. |
|
| data "label" |
Defines a set of data in line, ending with a matching end "label", where "label" is any string. Quotes are required. Certain labels have special meaning and are described more fully below.
|
| data "label @x" |
Defines a set of data with the given label from a variable (variable x in this case). Quotes are required, but no end command is required.
|
| data "data2d_xxx" |
Defines a data set to be paired x,y data inline and ending with end data2d_xxx, where xxx can be any alphanumeric string.
|
| data "property_xxx propertyAtomField propertyDataField" |
Defines an atom property based on data provided next inline and ending with end property_xxx, where xxx can be any alphanumeric string. propertyAtomField and propertyDataField are optional, and if provided override the set values for propertyAtomField and propertyDataField.
|
| data "property_xxx propertyAtomField propertyAtomColumnCount propertyDataField propertyDataColumnCount" |
Defines an atom property based on data provided next inline and ending with end property_xxx, where xxx can be any alphanumeric string. propertyAtomField, propertyAtomColumnCount, propertyDataField, and propertyDataColumnCount override set values for these parameters.
|
| data CLEAR |
Clears the data table.
|
| data "element_vdw" 6 1.7; 7 1.8 END "element_vdw" |
Defines the USER set of van der Waals radii on an element-by element basis. Entries may be separated by semicolons or entered one per line. . In the example given here, carbon (atomic number 6) is given a radius of 1.7, and nitrogen (atomic number 7) is given a radius of 1.8.
|
See also:
|
set (misc) spacefill undefined |
top search index |
Note: The display command does not require { ... } around Jmol atom expressions.
|
The opposite of hide. Display is similar to restrict in its action, but it is far more flexible. Atoms can be added to the displayed set using display displayed or ... or removed from the hidden set using display displayed and not .... Unlike restrict, the display command does not delete the hidden shapes. Thus, after restrict none all cartoons, traces, spacefill spheres, and bond sticks are effectively deleted. In contrast, display none is easily reversed using display all. or deselected with select not hidden. Atoms can be added to the hidden set using hide hidden or ... or removed from the hidden set using hide hidden and not ..... In addition, bonds can be hidden or displayed.
|
| display [atom-expression] |
Displays a set of atoms. Displays atoms and associated structures (bonds, halos, stars, cartoons, etc.) and hides all others. The optional parameters ADD and REMOVE prior to the atom expression allow quick alternatives to "displayed or..." and "displayed and not...".
|
|
Examples: in new window using 1blu.pdb |
display protein
display not solvent
display within(3.0,[FS4]102) |
|
See also:
|
hide restrict select subset undefined |
top search index |
ID [object id]
[modifying parameters]
[positions]
[display options]
|
See examples-11/draw.htm
|
The draw command allows for the insertion of points, lines, and planes to a model. Objects with IDs that start with "_!_" indicates that the object should be displayed when only one frame is visible. The general syntax of the draw command is as follows:
draw [objectID] [modifying parameters] [positions]
ID [object id] back
The optional identifier such as "line1" or "plane2" that can be referred to in later scripts as $line1 or $plane2. These words are arbitrary and if preceded by the optional keyword ID may be any string. Specifically for the options ON, OFF, and DELETE, the id may include a wildcard character (asterisk). Thus, draw v* off turns off all drawn objects having an ID starting with the letter "v".
[modifying parameters] back
Several options allow for modifications of some or all of the object types described below. These include:
| COLOR (color) | Sets the color of the drawn object at the time it is created. (The color command can be used retroactively as well.) | | CROSSED | Two lines (already drawn objects) specified next are crossed; switch the order of vertices for defining a plane. | | DELETE | Deletes the object if an identifier is given or all drawn objects if none is given; not used with any other parameters. "*" can be used as a wild card either at the beginning or end of the identifier. For example, DRAW pt* DELETE. | | DIAMETER n | Sets the number of pixels for the diameter of points, lines, arrows, and curves. Note that this means that zooming of the model does not change the width of these objects. n may be a decimal value x.x, same as WIDTH x.x. | | DIAMETER n [x y %] | Draws a sphere in the 2D window (in front of atoms) of size n x% from the left and y% from the bottom of the screen. For example, to create a key of elements and their colors:
background white
load $caffeine
function createElementKey() {
var y = 90
var fontSize = _height*20/400
for (var e in {*}.element.pivot){
var c = {element=@e}.color
draw ID @{"d_"+ e} diameter 2 [90 @y %] color @c
set echo ID @{"e_" + e} [91 @{y-2} %]
echo @e;
font echo @fontSize bold sansserif
color echo black
y -= 5
}
}
createElementKey()
| | DIAMETER n [x y] | Draws a sphere in the 2D window (in front of atoms) of size n x pixels from the left and y pixels from the bottom of the screen. | | FIXED/MODELBASED | Sets whether the surface generated is to be associated with the fixed window -- and thus appear with all frames/models -- or is to be associated with the currently displayed model (the default). | | LIST | Lists all DRAW objects. Not used with any other parameters. | | ON/OFF | Turns on or off the identified object or all drawn objects if no identifier is given; not used with any other parameters. | PERP
PERPENDICULAR | Draw this object perpendicular to the next indicated object. | | REVERSE | Reverse the order of vertices used if the next object listed is a line. | | ROTATE45 | Rotate a perpendicular plane to a line by 45 degrees. | | LENGTH (decimal) | The length for a line/axis in Angstroms. The keyword LENGTH is optional. | | OFFSET {x y z} | offsets the object by the given x, y, and z distances. | SCALE (decimal)
SCALE (integer) | SCALE with a decimal value indicates a scaling factor for the drawn object. For example, draw SCALE 1.5 (atomno=1) (atomno=2) draws a line with length 1.5 times the distance from atom 1 to atom 2. The line is centered on the two atoms. The keyword SCALE is required in this case. Note that a draw command can consist of just an identifier and a scale. Thus, if $line1 is already defined, draw line1 SCALE 1.3 will rescale that line to 130% of the distance between its defining points. SCALE with an integer number indicates a percent scale. The keyword SCALE is optional in this case. | | VERTICES | Generally the geometric center of an atom expression or drawn object is used for positioning. Added just before the atom set or object name reference, VERTICES indicates to use all vertices, not just the center point of the atoms in the expression or the points in the object. | | WIDTH x.x | Sets the diameter of points, lines, arrows, and curves to a given width in Angstroms. Objects drawn will be scaled based on perspective and zoom setting.
| | TITLE "text" | A simple text label can accompany drawn objects. The text appears near the first point. Text starting with ">" will be associated with the last point instead of the first. The ">" character will be stripped before the text is displayed. If set drawHover TRUE has been issued, this text will appear only when the object is hovered over. (Not applicable to composite drawn objects such as SYMOPS and SPACEGROUP.)
| | TITLE COLOR color | sets the color of the title font.
| TITLE FONT size face stylesets the font for the title. See the font command for details.
|
[positions] back
Positions define position of the point, the endpoints of the line/axis, or the corners of a plane. Positions can be indicated in any combination of any of the following four ways. Mixed types are processed in the order given on the command line.
| {x, y, z} | a model-frame cartesian coordinate, in braces, | | {x, y, z/} | for crystal structures, a unit-cell fractional coordinate, in braces, | | $object | a previously defined drawing object such as $line1 or $plane2, preceded by "$". | | (atom expression) | an atom expression, in parentheses. | | @{ {atomExpression}.split()} | atom expressions split based on model index . |
In addition, if two parameters are given, where the first evaluates to a point and the second is a four-vector {a b c d}, a line is drawn from the point to the nearest point on the plane defined by ax + by + cz + d = 0. (Note that because quaternions and axisAngle are stored in quaternion format, which is internally the same as that used for planes, if a quaternion or axisAngle is used in this context, the line will be along the axis of rotation represented by the quaternion or axisAngle q to a point on a plane defined by d = q.w = cos(theta/2), where theta is the rotation angle).
[display options] back
Display options for DRAW are indicated in the following table. These may be given at the end of the definition or in a later command having just these keywords and the identifier (or "ALL") of the desired draw object.
| FILL/NOFILL | Display the drawn opject as a smoothly filled surface. | | FRONTONLY/NOTFRONTONLY | Display only the front half of the surface. This can be useful when the options mesh nofill are used. | | FRONTLIT /BACKLIT /FULLYLIT | In some cases the object may appear flat. Using BACKLIT will fix this; FULLYLIT makes exterior and interior surfaces bright; FRONTLIT is the default setting. | | MESH/NOMESH | Display a mesh of lines intersecting at the vertexes used to construct the object. For cylinders, the combination MESH NOFILL creates a cylinder with no end caps. | | ON/OFF | Turn the object ON or OFF, but do not delete it. | | OPAQUE/TRANSLUCENT n | Display the object as an opaque or translucent object. Several translucent options are available; see the color command. |
|
| draw ARC {pt1} {pt2} {ptRef} {nDegreesOffset theta fractionalOffset} |
Draws a theta-degree arc in a plane perpendicular to the line pt1--pt2 starting at nDegreesOffset degrees rotation from reference point {ptRef} at a point fractionalOffset from pt1 to pt2. The SCALE parameter is used to set the diameter of the overall circle containing the arc; the DIAMETER parameter sets the diameter of the curved arc line itself. ARROW ARC adds an arrow head.
|
| draw ARC {pt1} {plane} {ptRef} {nDegreesOffset theta fractionalOffset} |
As above, but uses the plane as a reference to define a perpendicular axis.
|
| draw ARROW {pt1} {pt2} {pt3} ... |
Draws a straight (two-point) or curve (more than two-point) arrow. The keyword BARB indicates "fish-hook" half-arrows as for organic chemistry mechanisms involving radicals.
|
| draw ARROW [array of points] |
Draws an ARROW based on an array of points.
|
| draw ARROW ATOM/BOND |
The DRAW command can be used to draw organic "mechanistic arrows." You need to specify two atoms, two bonds, an atom and a bond, or a bond and an atom. Atoms are identified using the keyword ATOM followed by an atom expression; bonds are identified using the keyword BOND followed by two atom expressions. For example: draw ID "arrow1" ARROW ATOM @1 BOND @1 @2, which draws a curved arrow from atom 1 (atomno=1) to the middle of the bond connecting that atom to atom 2. These drawn objects are then "connected" to the atoms, so if the atoms are not displayed, the arrow is not displayed either. Of course, individual arrows can be hidden independently of their associated atoms as well.
|
| draw BEST BOUNDBOX atoms |
Draws the best boundbox through a set of atoms. The atoms can be given as one or more atomsets.
|
| draw BEST LINE atoms |
Draws the best line through a set of atoms. The atoms can be given as one or more atomsets.
|
| draw BEST PLANE atoms |
Draws the best plane through a set of atoms. The atoms can be given as one or more atomsets.
|
| draw BOUNDBOX |
Draws the currently defined boundbox. Note that by default this is a solid. To show just edges, use options MESH NOFILL.
|
| draw BOUNDBOX BEST |
Draws the (approximately) best box around the selected set of atoms, not necessarily oriented by the x,y,z axes. Note that by default this is a solid. To show just edges, use options MESH NOFILL.
|
| draw BOUNDBOX atoms |
Draws a boundbox with edges in the x, y, and z directions through a set of atoms, which may be given as one or more atomsets.
|
| draw BOUNDBOX $isosurfaceID |
Draws a boundbox around the specified isosurface
|
| draw BOUNDBOX BEST $isosurfaceID |
Draws the best boundbox around he specified isosurface
|
| draw CIRCLE {pt1} {pt2} |
Draws a circle with center at pt1 (which may be an atom expression) in the plane perpendicular to the line between pt1 and pt2. If pt2 is not specified, the circle appears in 2D and remains in the plane of the screen when the model is manipulated. Together, the SCALE and DIAMETER parameters set the overall size of the circle. If no DIAMETER is given and an atom expression is given for pt1, the default diameter is one that includes those atoms; otherwise the default diameter is 1.0 Angstrom. The circle will be filled to form a solid disk unless the MESH NOFILL option is given.
|
| draw CIRCLE {pt1} {plane} |
Draws a circle around pt1 in the indicated plane.
|
| draw CURVE {pt1} {pt2} {pt3} ... |
Draws a smooth curve through the given positions.
|
| draw CURVE [array of points] |
Draws a curve based on the array of points.
|
| draw CYLINDER {pt1} {pt2} |
Draw CYLINDER creates a cylinder of the designated diameter. End caps can be set to closed/flat (FILL, the default) or open (MESH NOFILL).
|
| draw DIAMETER -1 .. |
For lines or mesh option. Draws a simple line with 1-pixel width.
|
| draw DIAMETER -n .. |
For lines or mesh option. Draws a dotted 1-pixel line with alternating n on, n off pixels.
|
| draw FRAME [atom-expression] {quaternion} |
Draws a frame (an x,y,z axis set) at the given center with the given quaternion orientation. Quaternions are expressed using the quaternion() function within a math @{...} wrapper. For example, draw ID "q1" frame {0 0 0} @{quaternion(1,0,1,0)} draws a frame at the origin that has been rotated 90 degrees relative to the Y axis. (Jmol automatically normalizes the quaternion to q0=0.70710677, q1=0, q2=0.70710677, q4=0, which represents a 90-degree rotation about the Y axis.)
|
| draw HELIX AXIS |
Draws a vector representing the local helical axis for the selected amino acid or nucleic acid residue, connecting it to the previous residue in its chain. The length of the arrow is the vertical height per residue.
|
| draw HKL {1 1 1 x.x} |
Offsets an HKL plane from the origin by x.x Angstroms.
|
| draw HKL {1 1 1} OFFSET x.x |
Alternative to HKL {1 1 1 x.x}
|
| draw HOVERLABEL " xxx " |
Allows for a hover label that appears whether or not drawHover is on.
|
| draw "hover>xxx.... " |
Used for saving the hover label in a state.
|
| draw INTERSECTION BOUNDBOX (plane expression) |
Draws the portion of a plane that intersects the current boundbox based on a plane expression.
|
| draw INTERSECTION [unitcell or boundbox description] [line or plane description] |
Intersects all types of boundboxes and unitcells with any type of plane or line.
|
| draw INTERSECTION [unitcell or boundbox description] ON [line or plane description] |
Projects a unitcell or boundbox on any plane.
|
| draw INTERSECTION [unitcell or boundbox description] LINE @1 @2 |
Extends the specified line to intersect a unitcell or boundbox
|
| draw INTERSECTION UNITCELL (plane expression) |
Draws the portion of a plane that intersects the current unit cell based on a plane expression.
|
| draw LINE [array of points] |
Draws a set of line segments through the points. See also DRAW VERTICES.
|
| draw *xxx* ONLY |
Shortcut for DRAW * OFF; DRAW *xxx* ON. Hides all but the designated DRAW objects.
|
| draw INTERSECTION UNITCELL uc LATTICE {na nb nc} |
Draws a set of lattice points that are on a given plane; mostly for debugging. xxx can be an array [o a b c] or absent; plane can be PLANE or HKL and appropriate parameters.
|
| draw PLANE {pt1} {pt2} {pt3} |
Creates a four-vertex quadrilateral even if only three points are given.
|
| draw POINTGROUP [parameters] |
Calculates and draws point group symmetry planes and axes for a symmetrical or nearly symmetrical molecule. As for calculate pointgroup, the calculation is carried out only on the currently selected atoms and is limited to at most 100 selected atoms. Parameters include specification of a subset to draw (Cn, C2, C3, C4, C5, C6, C8, Sn, S3, S4, S5, S6, S8, S10, S12, Cs, Ci) optionally followed by an index (for example, draw POINTGROUP C3 2 draws the second C3 axis only). A second option, SCALE x, allows adjusting the scale of the drawn planes and axes. The default scale of 1 puts the edge of planes directly through the outermost atoms. This command automatically sets perspectiveMode OFF so as to properly represent the planes and axes.
|
| draw POINTGROUP {atoms} CENTER [atom-expression-or-coordinate] |
Calculates and draws point group symmetry, optionally allowing only a subset of atoms to be used, for example ignoring hydrogens with {!_H}. Also optionally allows the center to be set to a specific coordinate or atom.
|
| draw POINTGROUP POLYHEDRON |
Calculates and draws point group symmetry planes and axes for a polyhedron. One atom (one polyhedron) should be selected prior to this command.
|
| draw POINTGROUP SPACEGROUP |
Draws the crystal class symmetry operations for a space group
|
| draw POINTS [array of points] |
The POINTS option creates a set of points. For example, load $caffeine; draw POINTS [@5 @7 @12 @13 @1 @3].
|
| draw POLYGON [array of points] |
This simple POLYGON option creates a polygon from a list of points. For example, load $caffeine; draw polygon [@5 @7 @12 @13 @1 @3].
|
| draw POLYGON [array of indices] [array of points] |
This POLYGON option draws one polygon based on an array of integers (the "face") and an array of points that the indices of the face point to. The array of points is optional and defaults to {*}.xyz.all. For example,
load $p4
x = {*}.find("*1**1","map")
draw ID p4r polygon @{x[1]} color red
draw ID p4b polygon @{x[2]} color blue
draw ID p4y polygon @{x[3]} color yellow
draw ID p4g polygon @{x[4]} color green
|
| draw POLYGON [polygon definition] |
This POLYGON option draws one or more polygons based on a set of vertices and a set of faces. This capability allows drawing any number of flat triangular (not quadrilateral, but read on...) faces with or without edges around each face. The description is somewhat like that for PMESH files and involves (a) giving the number of vertices, (b) listing those vertices, (c) giving the number of faces, and (d) listing the faces with a special array syntax. Each face is described as an array indicating the three (0-based) vertex indices followed by a number from 0 to 7 indicating which edges to show a border on when the mesh option is given:
| 0 | no edge | | 1 | edge between first and second vertex | | 2 | edge between second and third vertex | | 4 | edge between third and first vertex | | 3, 5, 6, 7 | combinations of the above. |
For example: draw POLYGON 4 {0 0 0} {1 1 1} {1 2 1} {0 5 0} 2 [0 1 2 6] [0 3 2 6] mesh nofill. The points and faces can be provided as arrays: draw POLYGON @points @faces mesh nofill, where in this example, points is an array of the four points, and faces is [[0 1 2 6] [0 3 2 6]].
|
| draw POLYHEDRON [array of arrays of atom indices] [array of points] |
This POLYHEDRON option creates a set of polygons, collectively forming (possibly) a polyhedron from an array of arrays of indices (that is, an array of faces) and an optional array of points, which defaults to {*}.xyz.all. For example, load $caffeine; draw POLYHEDRON @{{*}.find("*1****1||*1*****1","map")} fills in the 5- and 6-membered aromatic rings with a colored surface. load $p4; draw POLYHEDRON @{{*}.find("*1**1","map")} fills in the faces of tetrahedral tetraphosphorus. The faces need not be wound correctly.
|
| draw QUATERNION [parameters] |
Draws vectors for the previously selected residues representing the quaternion frame and rotational axis for each residue. The parameters for this command are the same as for plot quaternion or the quaternion command. Vectors are named based on the axis (x, y, z, q), residue number, and chain.
|
| draw RAMACHANDRAN |
Draws curved arrows marked with PHI and PSI angles in planes perpendicular to the N-CA and CA-C bonds of the selected amino acids, respectively.
|
| draw SLAB $id PLANE (plane expression) |
Creates a DRAW object based on DRAW object $id, which must be of POLYGON type, that is slabbed based on a plane definition. For example: draw p4 polygon 4 {0 0 0} {0 3 0} {3 3 0} {0 3 3} 2 [0 1 2 0] [2 3 0 0]; draw p4 slab $p4 PLANE @{plane({0 0 0}, {5 0 0})}
|
| draw SPACEGROUP |
 Draws the symmetry elements of the representative set of symmetry operations (the operations generally given in a CIF file) for the current space group.
|
| draw SPACEGROUP ALL |
 Draws symmetry elements of the representative operations of the current space group, including all translations of those operations that intersect with the unit cell. Essentially a 3D interactive "space group diagram."
|
| draw SPACEGROUP @n |
 Draws symmetry elements of all representative operations for which the specified atom (in the current model only) is invariant except for lattice translation. If the atom is in a general position, nothing is drawn. For example:
load =ams/marcasite 1 packed
draw spacegroup @3
-x,y,z mirror plane
x,-y,-z C2 axis
-x,-y,-z Ci: 0 0 0
|
| draw SPACEGROUP @n i |
 Draws the i-th operation for which the specified atom (in the current model only) is invariant except for lattice translation. If the atom is in a general position, nothing is drawn. For example:
load =ams/marcasite 1 packed
draw spacegroup @3
x,-y,-z C2 axis
|
| draw SYMOP [n or "x,y,z"] {atom expression} |
Draws a graphic representation of a crystallographic space group symmetry operation. Operations include simple rotations, screw rotations, rotation-inversions, mirror planes, and glide planes, Either a number (for one of the model's symmetry operations) or a string indicating a Jones-Faithful operation may be used. The position may be an atom expression may be a point. If a point, it can be expressed either as a cartesian coordinate or a fractional coordinate (using a "/" in at least one position -- for example, { 1/2 0 0}. The ID of the draw command is prepended to the drawn object IDs. For example, draw ID "s1" SYMOP "x,1/2-y,z" {1/2 1/2 1/2}. See also the Jmol Crystal Symmetry Explorer.
|
| draw SYMOP {atom expression} {atom expression} |
Draws the symmetry relations between any two atoms or groups or any two positions in space. For example, draw SYMOP {molecule=1} {molecule=2}.
|
| draw SYMOP (integer) {atom expression} {atom expression} |
Draws the symmetry relation associated with the specified symmetry operator between any two atoms or groups or any two positions in space. For example, load =ams/quartz 1 packed;draw symop 2 @1 @3.
|
| draw SYMOP {atom expression} {atom expression} (integer) |
Draws the nth symmetry operator for special positions, where multiple symmetry operations relate two positions in space. For example, load =ams/quartz 1 packed;draw symop @1 @3 1.
|
| draw SYMOP [3,4,5] @1 |
Draws the given array of symmetry operations (1-based) for atom 1.
|
| draw SYMOP @2 OFFSET {lattice offset} |
Draws the symmetry operation targeting a given normalized lattice offset, where {0 0 0} is always into the unitcell [0, 1).
|
| draw SYMOP [matrix] |
Draws the symmetry operation associated with the given 4x4 matrix, which most likely comes from a variable, for example here the symmetry operation that is the product of two other symmetry operations: draw SYMOP @{symop(11)*symop(14)}.
|
| draw UNITCELL |
Draws the currently defined unitcell. Note that by default this is a solid. Default rendering for UNITCELL is MESH NOFILL.
|
| draw UNITCELL xxx LATTICE {default: na nb nc} |
Draws a set of lattice points, including lattice centering; mostly for debugging; possibly useful
|
| draw UNITCELL AXES |
Draws the currently defined unitcell along with colored axes.
|
| draw VECTOR {pt1} {pt2} |
This option is similar to ARROW, and accepts two points. The first point is the origin; the second is of the form {dx,dy,dz}, indicating a vector to the next point rather than the point itself.
|
|
Examples: |
See examples-11/draw.htm
|
See also:
|
[Jmol and Symmetry] [plane expressions] isosurface lcaoCartoon mo pmesh set (misc) show write (object) undefined |
top search index |
|
See animation.htm
|
Sets the current frame or frame set. Numbers refer to the physical position of the model in the file or set of files (1 being the first). Same as the animation frame command. See also model. Note that you can show specific pairs or sets of frames or models by using frame all followed by display (*/n,*/m,*/p), where n, m, and p are frame numbers. See also set backgroundModel. For the applet, if AnimFrameCallback is enabled, a message indicating the frame change is sent to the associated JavaScript function. The simple command frame has no observable effect but forces an animFrameCallback message to be sent, which also serves to update the pop-up context menu. This is sometimes useful if scripting has changed something in the structure such as the addition of vibration vectors that would alter menu options .
|
| frame (integer >= 1) |
Go to a specific model in the case of loading a single file with multiple models. The number used here is the sequential index of the model in the file, starting with 1. If more than one file is loaded, the number indicates the file, and all models in that file are overlaid.
|
| frame (positive decimal) |
Go to a specific model in a specific file when one or more files are loaded. The format for specifying which model to go to is the same as for select or display: file.model. For example, frame 2.3 goes to the third model in the second file listed in the most recent load command. Note that atoms in models chosen with the frame command must also be in the current display set in order to be visible. So, for example, display 2.1;frame 2.2 will display nothing; display connected(hbond);frame 2.2 will display only the hydrogen-bonded atoms in model 2.2.
|
| frame (decimal) - (decimal) |
Sets the animation range and displays a range of models, possibly spanning multiple files. The hyphen is optional. If the hyphen is present but the second model number is missing, then all models from the designated model forward are assumed.
|
| frame (negative decimal) |
Using a negative decimal indicates that one of the linear morphs between trajectory frames is to be shown. Files must have been loaded using the TRAJECTORY option.
|
| frame 0 |
Overlay all frames of the current frame range set. Note that this may not be all the models if the frame range has been set to a subset of the models or if multiple files are loaded and only models within one file have been specified with a previous frame command.
|
| frame 0.0 |
Same as frame ALL.
|
| frame [ array of model numbers ] |
Sets the current frame set; same as anim frames [ ... ] followed by frame *. Ranges of frames can be written with hyphenes: [ 1-5 7-11]. The atom selector thisModel selects for atoms in the current frame set. Note that these models can be in any order.
|
| frame {atomSet} |
This syntax allows setting of a model by an atom set. The first atom in the set determines which model is displayed. For example, model {within(smarts,"[r3]")} would bring into frame the first model with a 3-membered ring.
|
| frame "id" |
Recalls a frame with the given ID assigned with the frame ID command option.
|
| frame ALIGN [atom-expression] |
Provides a way to align structures across a set of frames. This is important for certain animations. The atom expression is evaluated per frame, and the resultant point is aligned in each case.
|
| frame ALIGN [atom-expression] FIXED |
Addition of FIXED ensures that atom alignment continues even when multiple models are showing. Note, however, that in this first implementation, objects such as isosurfaces and drawn objects are not shifted (as they would be when TRUE is not present).
|
| frame modelID ALIGN {x y z} |
aligns a model at a specific coordinate rather than at an atom. TRUE is assumed; the same issues as above involving objects are the case here.
|
| frame ALL |
Resets the frame range to all models and overlays them.
|
| frame CREATE (integer) |
Creates one or more "empty" models. If no parameter is given, 1 is assumed.
|
| frame ID "id" |
Assigns an ID to a frame that can later be used to recall the frame using FRAME "xxx" where xxx is a frame ID.
|
| frame LAST |
Go to the last frame in the frame range set.
|
| frame MO |
Go to the first frame with a molecular orbital.
|
| frame NEXT |
Go to next frame in the frame range set.
|
| frame PAUSE |
Pause animation at the current frame.
|
| frame PLAY (starting frame) |
Start playing at the specified frame number (current frame if number is omitted). Direction, speed of play, and mode of animation (ONCE, LOOP, or PALINDROME) are set using animation mode.
|
| frame PLAYREV (starting frame) |
Start playing at the specified frame number (current frame if number is omitted), reversing the direction.
|
| frame PREVIOUS |
Go to previous frame in the current frame set.
|
| frame RANGE (starting frame) (ending frame) |
Sets the range of frames to play as an animation and sets the current frame to the first number given. If the starting frame number is larger than the ending frame number, then play is in reverse. If only one number is given, then the range is set from that frame through the last frame in the file. If both numbers are omitted, then the range is set to include all frames in the file.
|
| frame RESUME |
Resume playing from the current frame. (Same as PLAY.)
|
| frame REWIND |
Return to the first frame in the frame range set.
|
| frame TITLE "title" |
Sets a title for all frames currently visible, which appears in the bottom left corner of the applet or application. If the title includes an expression such as "@{_modelName}", then that expression is evaluated whenever the model is rendered (for example, when the frame is changed). To set all titles at once, first make all frames visible. with frame all, then issue the frame title command.
|
| frame TITLE (array) |
Sets the title for all visible frames at once using an array of strings. For example, this sequence might give each frame title that shows the minimum energy for the files, converting energies to kJ/mol in the process:
x = getproperty("modelinfo.models.energy")
y = x.sub(x.min).mul(2625.5) # relative energies, in kJ
frame *;frame title @y
|
|
Examples: in new window using cyclohexane_movie.xyz |
model 1
model NEXT
model PREVIOUS
model 0;select *;wireframe 0.1;spacefill 0.2
anim on
model 0;select *;wireframe off;spacefill off;
select 1.1 # in Jmol10 use */1
wireframe 0.1;spacefill 0.2;color atoms red;
select 1.35;wireframe 0.1;spacefill 0.2;color atoms blue |
|
See animation.htm
|
See also:
|
animation file invertSelected model move moveto rotateSelected set (misc) spin translate translateSelected zoom zoomto undefined |
top search index |
|
The getProperty command sends information to the Jmol console or message callback function defined for a Jmol applet using the jmolSetCallback("messageCallback", funcName) function in Jmol.js or via the set command. Either a simple text string in the case of a file property or a valid JSON (JavaScript Object Notation) string in the case of a molecular property is returned. Such callbacks are asynchronous, meaning they do not return a value immediately. An alternative synchronous method for the applet is to use one of the JSmol built-in JavaScript commands Jmol.getPropertyAsArray(), Jmol.getPropertyAsString(), Jmol.getPropertyAsJSON(), or Jmol.getPropertyAsJavaObject(), all of which take three parameters: applet, infoType, and params. For example, in JavaScript:
var modelInfo = Jmol.getPropertyAsArray(jmolApplet0, "modelInfo")
alert(modelInfo.modelCount)
for (int i = 0; i < modelInfo.modelCount; i++)
alert(modelInfo.models[i].name)
.
In addition, when using the Jmol application, see the note at show regarding setting the output to go directly into a file on your system.
This information is also available using the Jmol math getProperty() function.
|
| getProperty animationInfo |
Structure describing the current state of animation. See animationInfo.txt.
|
| getProperty appletInfo |
Structure describing the applet, including, for example, the applet version, compile date, Java version, and name of the applet object. See appletInfo.txt.
|
| getProperty atomInfo [atom-expression] |
Structure describing the atoms in the model. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See atomInfo.txt.
|
| getProperty auxiliaryInfo |
Structure describing auxiliary information that is in the loaded file. This information is file-dependent and might include, for example, symmetry information, molecular orbital coefficients, dipole moments, partial charges, and/or vibrational modes. See auxiliaryInfo.txt.
|
| getProperty bondInfo [atom-expression] |
Structure describing the bonds in the model. A second (optional) parameter specifies a subset of the atoms that are involved in the bonds. The default is (visible). Parentheses are required. See bondInfo.txt.
|
| getProperty chainInfo [atom-expression] |
Structure describing the chains in a biomodel (PDB or mmCIF, for example). Information for each residue of the chain is provided. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See chainInfo.txt.
|
| getProperty cifInfo filepath |
The contents of a CIF file (or for the current file if no filepath parameter is given) in a structured data format. The corresponding getProperty("cifinfo",filename) function produces this result in a Jmol structure. For example:
print getProperty("cifinfo", "=ams/quartz").keys.all
models
models..45.name
models..45["_atom_site_fract_x"]
models..45["_atom_site_fract_y"]
models..45["_atom_site_fract_z"]
models..45["_atom_site_label"]
models..45["_atom_site_u_iso_or_equiv"]
models..45["_cell_angle_alpha"]
models..45["_cell_angle_beta"]
models..45["_cell_angle_gamma"]
models..45["_cell_length_a"]
models..45["_cell_length_b"]
models..45["_cell_length_c"]
models..45["_cell_volume"]
models..45["_chemical_compound_source"]
models..45["_chemical_formula_sum"]
models..45["_chemical_name_mineral"]
models..45["_database_code_amcsd"]
models..45["_exptl_crystal_density_diffrn"]
models..45["_journal_name_full"]
models..45["_journal_page_first"]
models..45["_journal_page_last"]
models..45["_journal_volume"]
models..45["_journal_year"]
models..45["_publ_author_name"]
models..45["_publ_section_title"]
models..45["_space_group_symop_operation_xyz"]
models..45["_symmetry_space_group_name_h-m"]
|
| getProperty extractModel [atom-expression] |
The extractModel keyword delivers text in the form of a MOL file, allowing up to 999 atoms and 999 bonds to be "extracted" from the model as an independent structure.
|
| getProperty ligandInfo |
Structure indicating ligand information, including and array of "ligands", each containing items "reslist", "atoms", and "groupNames".
|
| getProperty measurementInfo |
Structure describing the currently-defined measurements for the model, including the atoms involved, the measurement type, and the value of the measurement in decimal and in string formats. See measurementInfo.txt.
|
| getProperty modelInfo |
Structure describing each model in the loaded model collection. See modelInfo.txt.
|
| getProperty modelkitInfo |
Structure listing current modelkit properties.
|
| getProperty moleculeInfo [atom-expression] |
Structure describing each molecule (covalent set of atoms) in the model, including the number of atoms, the number of elements, and the molecular formula. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See moleculeInfo.txt.
|
| getProperty nmrinfo |
Structure describing NMR calculation data including (a) a table of isotope masses (negative if these are default parameters for a nucleus), gyromagnetic ratio, and quadrapolar coupling constant, and (b) assigned shift references in PPM. See nmrInfo.txt.
|
| getProperty orientationInfo |
Structure describing the moveTo command required to return to the currently displayed orientation. See orientationInfo.txt.
|
| getProperty polymerInfo [atom-expression] |
Structure similar to chainInfo describing the residues in a biomodel. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See polymerInfo.txt.
|
| getProperty shapeInfo |
Structure listing a small amount of information relating to shapes displayed with the model (molecular orbitals, isosurfaces, cartoons, rockents, dipoles, etc.) See shapeInfo.txt.
|
| getProperty transformInfo |
Structure representing the current transformation matrix describinng the current orientation of the model. See transformInfo.txt.
|
|
See also:
|
boundbox javascript script set (callback) set (visibility) show undefined |
top search index |
Note: The hide command does not require { ... } around Jmol atom expressions.
|
The opposite of display. Hides atoms and associated structures (bonds, halos, stars, cartoons, etc.). Hide is similar to select or restrict in its syntax. Unlike restrict, though, hide is completely reversible using hide none. (Restrict acts by setting the "size" of the object to 0; hide leaves the size the same, but just hides the object until unhidden. Group-based structures such as cartoons and traces are hidden whenever their lead atom (the one that determines their position in space) is hidden. Hidden atoms can be selected with select hidden or deselected with select not hidden. Atoms can be added to the hidden set using hide hidden or ... or removed from the hidden set using hide hidden and not ..... In addition, bonds can be hidden or displayed.
|
| hide [atom-expression] |
Hides a set of atoms. Displays atoms and associated structures (bonds, halos, stars, cartoons, etc.) and hides all others. The optional parameters ADD and REMOVE prior to the atom expression allow quick alternatives to "hidden or..." and "hidden and not..." In addition, the keyword GROUP prior to the atom expression provides a quick alternative to "within(group, ...)".
|
| hide BONDS |
Hides all bonds.
|
| hide [{...}] |
Hides a set of bonds.
|
|
See also:
|
display restrict select subset undefined |
top search index |
ID [object id]
[construction/mapping parameters] -- molecular/solvent surfaces
[construction/mapping parameters] -- molecular orbitals
[construction/mapping parameters] -- general shapes and volumetric (cube file) data
[construction/mapping parameters] -- general file loading
[sets and slabbing options]
[color and contour options]
[surface object] -- molecular/solvent surfaces
[surface object] -- atomic and molecular orbitals
[surface object] -- general shapes
[surface object] -- file-derived isosurfaces
[surface object] -- PDB x-ray diffraction and cyro-EM surfaces
[surface object] -- volume file-derived isosurfaces
[surface object] -- surface data-derived isosurfaces
[surface object] -- additional surface sources
[additional mapping-only parameters]
MAP [color mapping dataset]
[display options]
|
See examples-11/isosurface.htm
|
 Jmol can generate a large variety of objects using the method of isosurfaces. Many of these surfaces can be color-mapped. Two Jmol commands (isosurface and mo) render isosurfaces. The isosurface command itself provides ultimate control over these surface renderings. Before using the isosurface command, if you are interested in rendering molecular orbitals, you should first take a look at the mo command.
The general syntax of the isosurface command is as follows:
isosurface ID [object id] [construction/mapping parameters] [surface object] [additional mapping-only parameters] MAP [color mapping dataset] [display options] .
The isosurface command is complex, and while the order of parameters is flexible within these groups, parameters in different groups should not be swapped in terms of order within the command, or the result is unpredictable or will cause an error message to be displayed. While the id is optional, it is highly recommended. Specifically for the options ON, OFF, and DELETE, the id may include a wildcard character (asterisk). Thus, isosurface pl* on turns on all isosurface objects having an ID starting with "pl".
Data for these surfaces can be from several sources (see below). In addition, atom-based data from a variety of sources can be mapped onto an isosurface.
The isosurface itself represents the points in space where scalar values cross a specified "cutoff" value. Inside the surface, values are greater or equal to a specified positive cutoff or less than or equal to a specified negative cutoff. The default cutoff depends upon the type of object displayed. Note that positive and negative surfaces may be created separately, or, using the SIGN keyword, they can be generated together.
Color mapping of one object onto another is a simple as listing both an object and a dataset within the same isosurface command. Several keywords affecting the mapping are allowed. The default color scheme uses a red-->orange-->yellow-->green-->blue rainbow, where red represents minimum values and blue represents maximum values, but several other schemes are available (see below). Mapped data can be expressed as a series of contour lines.
ID [object id] back
The optional identifier allows you to refer back to this isosurface later for turning the surface on or off, deleting the surface, or changing display options. It must be either the first parameter or the second, just after DELETE. If the identifier is missing, behavior depends upon version. The ID keyword is optional but recommended, because then one can use any name for the ID; otherwise the name must not be one of the many Jmol command or keyword names. Leaving off the ID when creating an isosurface replaces the current isosurface with the new one.
[construction/mapping parameters] -- molecular/solvent surfaces back
| ADDHYDROGENS | For a solvent or sasurface object, accounts for missing hydrogens on carbon atoms only just prior to generating the surface. A simple sp3 model is used, and for that reason this option is not recommended. Instead, use set pdbAddHydrogens to load a PDB file and automatically add hydrogen atoms to ATOM and HETATM records. | | IGNORE {atom expression} | Specifies a set of atoms to completely ignore when generating a solvent-related surface (SOLVENT or SASURFACE). Typically these might be solvent molecules or atoms: IGNORE {solvent}. Note that SASURFACE and SOLVENT surfaces by default ignore solvent molecules; VDW and MOLECULAR do not. | | IONIC radius | Atom radius relative to the ionic radius. Options include:
| x.x | specific absolute number of Angstroms for every atom | | +/-x.x | offset greater(+) or less(-) than the ionic radius | | nn% | percent of the ionic radius | | +/-nn% | percent offset from the ionic radius |
| | SELECT {atom_exp} | Selects a specific subset of the atoms for this surface. Same as select atom_exp; isosurface.... except the atoms are selected only within the isosurface command, not the overall script. | | SELECT {atom_exp} ONLY | Selects a specific subset of the atoms for this surface and also applies IGNORE {not atom_exp}. | | VDW radius | Atom radius relative to the van der Waals radius. Options include:
| x.x | specific absolute number of Angstroms for every atom | | +/-x.x | offset greater(+) or less(-) than the van der Waals radius | | nn% | percent of the van der Waals radius | | +/-nn% | percent offset from the van der Waals radius |
| | WITHIN x.xx {atomExpression or point} | only creates a surface within the specified distance in Angstroms from the specified atoms or point. |
[construction/mapping parameters] -- molecular orbitals back
| COLOR color1 color2 | Specifically for molecular orbitals. (for CUBE and other volume data files, use SIGN.) Specifies the two colors to use for the positive and negative lobes of a molecular orbital. Note that this and all other options in this classification must be given prior to the option that actually generates the surface. | | IGNORE {atom expression} | Specifies a set of atoms to completely ignore when generating a molecular orbital, thus showing only selected atomic contributions. | | SCALE x.xxx | In the case of molecular orbitals, scales the volume around the orbital. It may be useful in cases where Jmol misjudges the full extent of an orbital, thus truncating it. | | SELECT {atom expression} | Selects a specific subset of the atoms for this molecular orbital. (Essentially the opposite of IGNORE.) | | SIGN | For molecular orbitals derived from cube files, indicates that the data have both positive and negative values and that they should both be displayed. | | SQUARED | Data are to be squared prior to surface generation. |
[construction/mapping parameters] -- general shapes and volumetric (cube file) data back
| ANISOTROPY {a b c} | Sets the anisotropic distortion of an object in the x, y, and z directions. | | CACHE | Caches the isosurface in memory and replaces it with its JVXL equivalent. The CACHE option along with isosurface creation or alone instructs Jmol to immediately create JVXL data for the specified surface and to load that data instead. The surface remains in memory and can be used again, even after a new file is loaded using cache://isosurface_ where is the isosurface ID such as "isosurface1". The command ISOSURFACE CACHE alone will cache the current isosurface. If the cache is no longer needed, then RESET CACHE will release the memory used to hold the JVXL data for the isosurface. The result should be essentially equivalent to the original command. (It is recommended that the original be a relatively simple command, because not all nuances of an isosurface may be stored in the JVXL data.) Note that this option is not compatible with saving the state as an SPT file. Instead, use WRITE PNGJ or WRITE JMOL, in which case the cached isosurface will be saved in JVXL format within the PNGJ or JMOL zip directory. | | CENTER {x y z} | Centers an atomic orbital, sphere, ellipsoid, or lobe at a specific point in molecular space. In the case of crystal structures, these may be fractional coordinates. | | CENTER (atom_exp) | Centers an atomic orbital, sphere, ellipsoid, or lobe on a certain atom or at the geometric center of this set of atoms. | | CENTER $object | Centers an atomic orbital, sphere, ellipsoid, or lobe on a certain drawn object such as a point, line, or plane. | ECCENTRICITY
{cx cy cz f_ab} | Sets the eccentricity of a sphere, ellipsoid, atomic orbital, or lobe. The first three numbers define the "principal" axis; the fourth parameter defines the ratio of the other two perpendicular axes to this main axis. | | PHASE "type" | Indicates that an orbital or other object is to be colored based on the position of the voxel in space. With an atomic orbital and no parameters, indicates regions of (+) and (-) oribital value with different colors. Valid types include "x", "y", "z", "xy", "xz", "yz", "z2", and "x2-y2". | | SCALE x.xxx | In the case of objects for which eccentricity can apply (spheres, ellipsoids, atomic orbitals, lobes, and volumetric data), scales the object (default 1.0). |
[construction/mapping parameters] -- general file loading back
| ANGSTROMS | For a cube file or user-defined function f(x,y), indicates that the volumetric definitions are in Angstroms instead of Bohr (default). | | BLOCKDATA | Indicates that data for surfaces in multiple-surface CUBE files are in sequential blocks rather than the Gaussian standard of being interspersed, where all data values for a coordinate point are listed together. | | BOUNDBOX | Specifies that the surface to be generated must be within the currently defined boundbox. | | BOUNDBOX {atomExpression or point} {atomExpression or point} | Specifies that the surface to be generated must be within a volume defined by the specified two diagonal end points. | | COLOR DENSITY | Allowing rendering of the actual grid of numbers (volume rendering) of the data rather than an isosurface. With CUTOFF 0.0, this setting delivers the entire set of data points. It is recommended that the BOUNDBOX parameter be used with a relatively small boundbox setting or the WITHIN parameter is used in order to not have an out-of-memory condition resulting from this option. For example: boundbox scale 1.2 {tyr};isosurface color density cutoff 1.6 boundbox "3hyd_map.ccp4.gz" mesh nofill If a range of values is desired, use CUTOFF [min, max] to indicate the minimum and the maximum values to be included; for example: isosurface color density cutoff [-5,10] within 4.0 {*} "apbs.dx". | | CUTOFF x.xxx | Sets the cutoff value defining an isosurface. Typically, smaller values correspond to a larger object. Cutoffs can be either positive or negative. In the case of a molecular orbital, a positive number indicates to use both positive and negative cutoffs. Adding an explicit "+" sign before the number indicates that only the positive part of the surface is desired. (See also RMSD, below.) | | CUTOFF [min,max] | see COLOR DENSITY, above | | DEBUG | Produces voluminous detail for program debugging. | | DOWNSAMPLE n | "Downsampling" is the process by which an image or other data set is selectively sampled, producing a result that is grainier and has less resolution than the original data set. This option for the isosurface command indicates that only a portion of the data for a file should be used for the surface, creating an isosurface with lower resolution but with the full range of the original data. n is an integer -- downSample 2 uses only every other data point; downSample 3 takes only every third data point, etc. Supported for cube-based data sets only. | | FIXED/MODELBASED | Sets whether the surface generated is to be associated with the fixed window -- and thus appear with all frames/models -- or is to be associated with the currently displayed model (the default). | | FULLPLANE | for PLANE objects, indicates that color mapping should be extended to complete the plane. | | GRIDPOINTS | Adds the specific gridpoints used by the "marching cubes" algorithm for the calculation of the isosurface. Primarily for discussion and debugging of the isosurface algorithm. | | INSIDEOUT | For certain datasets it sometimes happens that the surface rendered appears inside-out (dark on the outside and bright on the inside). If this is the case, add INSIDEOUT to the isosurface command prior to specification of the file to load. Jmol will reverse the sense of what is inside and what is outside the surface. This flag only affects rendering in Jmol, not export to PovRay. | | MODEL n | Sets the identity of the model with which this isosurface is to be associated. (Defaults to the currently displayed model.) | | RESOLUTION x.x | Sets the resolution of a constructed isosurface three-dimensional grid of "voxels", in points per Angstrom. Does not apply to CUBE or JVXL files, which have a resolution defined by internal file parameters. | | RMSD x.x | Sets the cutoff based on the root mean square deviation of the data. (MRC/CCP4 file format; equivalent to SIGMA in Jmol 14.4; previous versions require SIGMA instead of RMSD, which is technically not a correct term.) | | SIGN c1 c2 | Indicates that cube data have both positive and negative values, and that they should both be displayed using the value given for CUTOFF and its negative. The two colors to use may be given optionally. | | SIGMA x.x | See RMSD, above. | | SQUARED | Data are to be squared prior to surface generation. | | SYMMETRY | Applies file-based symmetry operators to isosurface creation, resulting in more efficient creation and rendering. The default selection is {symop=1} ONLY, and default coloring is to color by symop based on the current setting of propertyColorScheme. For example: load =1stp filter "biomolecule 1";color property symop;isosurface ID sa RESOLUTION 0.8 SYMMETRY SASURFACE 0. | | WITHIN x.xx {atomExpression or point} | only creates the portion of the surface within the specified distance in Angstroms of the specified atoms or point. | | WITHIN x.xx {atomExpression or point} | only creates a surface within the specified distance in Angstroms from the specified atoms or point. | | WITHIN -x.xx {atomExpression or point} | a negative value for the WITHIN distance indicates not within x.xx Angstroms of the specified atoms or point. |
[sets and slabbing options] back
In the case of isosurfaces with artifacts or fragments or multiple independent sets of triangles in general, options MINSET, MAXSET, SET, and SUBSET specify which sets of triangles to include. CAP and SLAB allow slicing of the isosurface based on the current boundbox or unit cell, the proximity to a point, or side of a plane. Each slab or cap creates a new fragment that can be selected or unselected using the various SET options. These commands are reversible, SET 0 specifying "all sets" again, and SLAB NONE specifying "no slabbing or capping." All of these options can be given anywhere in an ISOSURFACE command or as part of any number of additional ISOSURFACE commands. They can be strung together with no punctuation: ISOSURFACE MOLECULAR;ISOSURFACE slab none slab plane x=0 cap plane y=0 cap plane z=0.
MINSET n
MAXSET n | Discard subsets of the surface that have at least n (MINSET) or fewer than n (MAXSET) triangles. | | SET n | The SET option specifies a single set of triangles composing one specific surface fragment, where n is the 1-based set number, in decreasing order of number of triangles. | | SET 0 | Reset to display all sets. | | SUBSET [i,j,k,...] | Display only the specified sets, where the numbers i, j, k, ... indicate the 1-based index of the set, in order of decreasing number of triangles. So, for example, SUBSET [1] is the same as SET 1. | | | | CAP/SLAB BOUNDBOX | CAP or SLAB along the boundaries of the current boundbox. | | CAP/SLAB UNITCELL | CAP or SLAB along the boundaries of the current unit cell. | | CAP/SLAB [plane definition] | CAP or SLAB based on a standard Jmol plane description, such as "x=3" or "xy". | | SLAB within x.y {point} | SLAB within a give distance in Angstroms from a specified point, such as or {1 0 0 -3}, or an atom, such as @10 or {protein}. | | SLAB WITHIN RANGE x.x y.y | SLAB based on the value of a mapped parameter. | | SLAB nn | SLAB dynamically at nn% of the distance from the back to the front of the isosurface. This special slab dynamically changes as the model is rotated, always slabbing based on the plane of the screen, producing a dramatic view into an isosurface regardless of the orientation of the model. | | SLAB NONE | Reset the slab, removing all results of SLAB or CAP. |
[color and contour options] back
Jmol can color isosurfaces in a wide variety of ways, from simple single colors to mapped contours based on a second data set. See also the color ISOSURFACE command for additional options and changing the color of an isosurface after creation.
| COLOR <color> | Colors an isosurface the specified color name or value, such as [xFF0000]. | | COLOR "c1 c2 c3..." | Where c1, c2, etc. are color names or values, such as red or [xFF0000] within double quotes, this option allows specification of descrete colors to be used for contour mapping. | | COLOR c1 TO c2 n | (also color isosurface ......) colors an isosurface with a range of n colors from color c1 to color c2. For example, color isosurface red to white 30. | COLOR RANGE
x.xxx y.yyy | (or color absolute) Indicates to color the specified range of value from one end to the other end of the color scheme. If numbers are not included or COLOR RANGE ALL is specified, then the minimum and maximum data values in the file are used. | | COLORSCHEME "xxx" | Sets the color scheme to one of "roygb" (default rainbow), "bgyor" (reverse rainbow), "bw" (black/white), "bwr" (blue-white-red), "rwb" (red-white-blue), "wb" (white/black), "low" (red-green), or "high" (green-blue). An optional parameter TRANSLUCENT prior to the color scheme name creates a gradient of translucency from transparent to opaque across the color scheme. An additional scheme "sets" colors the isosurface different colors for different surface fragments (for example, internal cavities). | | CONTOUR n | Specifies to display the object as a set of contour lines. Then number of lines is optional; 9 contour lines are shown by default. Using the CONTOUR keyword sets the default display to be CONTOURLINES NOFILL. Note that isosurface contour 0 "t.jvxl" will override contour selected in JVXL file. | | CONTOUR n i | Same as CONTOUR n but draws only the ith contour line. | | CONTOUR -n | With a negative number, specifies for a plane or f(x,y) object the specific single contour to depict. | CONTOUR DISCRETE
[a,b,c,d,e,...] | Sets the contour levels to discrete values. In addition, see the COLOR option, above, for the discrete coloring option. | CONTOUR INCREMENT
{from,to,step} | Sets the contour values starting with the from value to the to value in increments of step. In addition, see the COLOR option, above, for the discrete coloring option. | | REVERSECOLOR | For colorschemes in particular, the REVERSECOLOR option switches the direction of the color scheme. This parameter should be given just prior to the COLORSCHEME parameter. | | SCALE3D x.x | generates a 3D plot of the desired scale from a mapped plane. It can be introduced either with the original definition of the isosurface or later, after the plane has been created and displayed. Negative numbers invert the graph (forming valleys instead of mountains); 0 removes the 3D scaling. Note that this rendering can be combined with CONTOUR to form a 3D "topo map". |
[surface object] -- molecular/solvent surfaces back
Several isosurface options relate specifically to molecular or solvent-related surfaces.
CAVITY
cr er | Renders a depiction of a molecular cavity. The optional parameters cr and er determine the overall properties of the cavity. cr (cavity radius, default 1.2) sets the radius in Angstroms of the "probe" molecule that would fit into the cavity. er (envelope radius, default 10) sets the radius of the probe used to define the outer limits of the molecule. Smaller numbers for the cavity radius lead to more detailed cavities; smaller numbers for the envelope radius lead to cavities that are more internal and extend less toward the outer edge of the molecule. Qualifier INTERIOR CAVITY creates isosurfaces only for cavities that do not extend to the outer surface of the molecule. Qualifier POCKET CAVITY creates isosurfaces only for pockets that extend to the outer surface of the model, showing them more as troughs or open "pockets". Qualifiers MINSET , MAXSET, SET and SUBSET can all be given prior to CAVITY. | | MEP | Depicts the molecular electrostatic potential, as calculated by SUM(q_i/r_i), where q_i is the partial charge on atom i (as found in the loaded model file) and r_i is the distance from atom i to a particular point in space. The molecular electrostatic potential is not typically displayed itself. Rather, it is usually mapped onto a molecular surface. For example: isosurface resolution 6 SOLVENT map MEP produces a smooth surface at the van der Waals distance around the molecule colored by the molecular electrostatic potential. | | MOLECULAR | Same as SOLVENT 1.4, but solvent moleules are not ignored. | | SASURFACE radius | Depicts the "solvent-accessible" surface based on the currently selected atom set. This surface is described by the center of the solvent probe as it rolls along the surface. It is larger than the "molecular" surface. The radius is optional. Solvent molecules are ignored by default. If either the VDW or the IONIC keywords are present, sasurface 0 is assumed, but solvent is not ignored. | | SOLVENT radius | Depicts the "solvent-excluded" or "molecular" surface around the currently selected atoms (or the entire model if no atoms are selected). If only a subset of the atoms is selected, then only the corresponding subset of the molecular surface is depicted. This surface is defined as the surface formed by rolling a spherical solvent "probe" around the molecule at the distance of the van der Waals radii of the atoms. The specification of the radius of this probe is optional; its default setting is determined by the set radius command (Jmol default 1.2). Solvent molecules are ignored by default. |
[surface object] -- atomic and molecular orbitals back
Both atomic orbitals and molecular orbitals can be displayed in Jmol. Note that molecular orbitals in particular can be generated more effectively using the mo command rather than the isosurface command. Alternatively, the "LCAO cartoon" option creates the sort of dumbbell-shaped cartoonish orbitals seen in textbooks in discussion of pi bonding and hybridization.
ATOMICORBITAL
n l m Zeff | The Schroedinger solution to the hydrogen atom wavefunction. The three quantum numbers n, l, and m, must be such that abs(m) <= l < n. For solutions with imaginary roots, the two m values simply designate the two real linear combinations of these imaginary solutions. The optional effective nuclear charge, Zeff, determines the overall size of the orbital (default is 6, carbon). Add the keyword PHASE for a two-color orbital, which can be colored using the SIGN keyword followed by two color names or values. | ATOMICORBITAL
n l m Zeff POINTS nPoints radius seed | Creates a "pointilist" probability-based visualization of an atomic orbital using the specified number of points and optional radius extent and random seed. The radius parameter, if present, must be a decimal number. The integer setting DOTSCALE can be increased from its default value of 1 to increase the size of the displayed points. | LCAOCARTOON
"type" (atom_exp) | Draws a lobe or p orbital (two lobes) centered at the FIRST atom of the specified expression. (Typically this would be an expression for a single, specific atom, such as atomno=3). See the lcaoCartoon command for a discussion of the possible types of LCAO cartoons (as well as a simpler way to create them). | LOBE
{cx cy cz f_ab} | Draws a single tear-drop shaped object (an xy-compressed center lobe of a dz2 orbital) anywhere at any size in any direction with any amount of distortion. The first three numbers define the axis of the lobe; the fourth parameter defines its eccentricity -- the ratio of the other two perpendicular axes to this main axis. | | MO n | Denotes the n-th molecular orbital described in the file that is currently loaded. Adjusting the CUTOFF to suit the situation is recommended. Molecular orbitals are automatically bicolor; color them one specific color using COLOR and just one color name or value. RESOLUTION can be used to good effect to increase or decrease the precision of the rendering. Note that only the atom-based orbitals for the currently selected atoms are utilized. Thus, one can selectively see how atomic orbitals from each atom in the molecule are contributing to any given molecular orbital. | | MO HOMO/LUMO +/-n | Selects for display a molecular orbital based on energy-proximity to the highest-occupied or lowest-unoccupied molecular orbital. For example, isosurface MO HOMO or isosurface MO LUMO +3. | | MO ... POINTS nPoints seed | Produces a "pointilist" probability-based visualization of a molecular orbital using the specified number of points and an optional random seed. |
[surface object] -- general shapes back
There are several general shapes that can be created as "isosurfaces". These include:
ELLIPSOID
{cx cy cz f_ab} | Draws an ellipsoid having a single unique axis. The first three numbers define the "principal" axis; the fourth parameter defines the eccentricity of the ellipsoid -- the ratio of the other two perpendicular axes to this main axis. | | HKL {h k l} | Creates a plane through a crystal based on the Miller indices hkl. Adding map molecular creates a slice through the crystal highlighting atomic positions. | | PLANE | Indicates that what is desired is not really an isosurface but rather a planar slice through the data set. Using RESOLUTION 0.001 with planes allows for minimum number of triangles. Using COLOR RANGE, the range of mapped values can be changed. The range -0.008 0.008 is recommended for molecular orbitals. Planes, like other surface objects, can be mapped or left unmapped and just colored. Planes are designated using one of the methods for plane expressions. If a BOUNDBOX keyword is given prior to PLANE (see above), then the plane will be created within that box. | | SPHERE radius | Draws a sphere of the given radius in Angstroms. |
[surface object] -- file-derived isosurfaces back
Isosurfaces can be created in Jmol using external file-based "volume" or "polygon" data. Note that any of the formats that are volume data (APBS, CUBE, Chem3D, DSN6/OMAP, MRC/CCP4, XPLOR/CNS) can all be used either to generate the surface itself or (after the MAP keyword) to color a surface.
FILE "filename" n can be used in either case to depict the n-th isosurface from the specified file. Empty quotes indicate that the loaded structure file already has surface data present (CUBE files, for example, contain coordinates), and that that data should be used for construction of the surface. Thus, for example, load test.cube.gz;isosurface FILE "" will load the coordinates from the GZIPped cube file, then display its first isosurface. A default directory can be set using set defaultDirectory, and for applets a proxy server can be set for non-host file loading using set appletProxy. The keyword FILE is not required. The optional number "n" specifies which volume or surface should be used in the case of a CUBE file with multiple orbitals with multiple surfaces. All files read by Jmol may be gzip-compressed.
Isosurfaces can be created as linear combinations of volume data, provided all grids are identical. This is done using ISOSURFACE [f1, filename1, f2, filename2, ...], described below.
[surface object] -- PDB x-ray diffraction and cyro-EM surfaces back
Jmol can import x-ray diffraction and cyro-EM volume data maps from the European Bioinformatics Institute Density Server, either for full structures or for localized sets of atoms. For x-ray diffraction maps, use prefixes "=" or "*" and the PDB ID, ISOSURFACE "=2gc2", for standard (2fo-fc) maps. Use "==" or "**" for difference (fo-fc) maps -- ISOSURFACE "==2gc2". (There is no difference between "=" and "*" here; "=" and "==" are legacies from when the Uppsala server was active.) If the surface is for the currently loaded PDB model, the PDB id may be omitted or the keywords eds and edsdiff may be used directly: ISOSURFACE "=" or ISOSURFACE eds. An empty string file name also is the same as eds. Default RMSD (sigma) values for x-ray diffraction maps are +1.0 for 2fo-fc maps and +/-3.0 for fo-fc maps. The difference map option automatically sets the SIGN option, returning positive and negative differences in two colors.
Cryo-electron microscopy maps are available from EBI starting with Jmol 14.31.51. To access cryo-EM maps, use the prefix "=emdb/nnnn", where nnnn is the EMDB id number. For example: ISOSURFACE "=emdb/9357" (the cryo-EM map for 6nef). A default SIGMA 10.0 will used, which is only a guess. For a specific PDB ID, use the prefix "=em/=" and the PDB ID for the EMDB id: ISOSURFACE "=em/=6nef". This queries the EMDB for the author-suggested cutoff value and uses that as the default CUTOFF. You can override that default cutoff, though, using SIGMA or CUTOFF: ISOSURFACE CUTOFF 0.03 =em/=6nef. As for x-ray volume data, use "=em/=", "=em/", or just "=em" to indicate the volume data for the current PDB model.
The DENSITY option, ISOSURFACE DENSITY, allows either cryo-EM or x-ray diffraction data to be used, first checking if cryo-EM data is available and, if not found, then checking for x-ray data. Use ISOSURFACE "=density/=xxxx", where xxxx is a PDB ID, for a model other than the current model. Which type of map was used will be indicated in the Jmol Script Console. It is also available using the GETPROPERTY ISOSURFACE command or the getproperty("isosurfaceInfo") function or, more specifically, getProperty("isosurfaceInfo.jvxlFileTitle"), which will report the type of isosurface (2FO-FC, FO-FC, or EM) as, for example, for 6NEF, "BCifDensity reader type=EM".
A default WITHIN 2.0 {...} isosurface option is automatically applied in all of these case. These requests use a very efficient Density Server API to retrieve just the data for the volume containing the atoms specified by WITHIN (or the full current model, if WITHIN is not specified), resulting in significant speed and bandwidth improvements. If the full set of volume data is desired -- for example, the full unit cell data for x-ray diffraction, add the suffix "/full" to the filename. For example: ISOSURFACE "=em/full" or ISOSURFACE "=em/=6nef/full".
[surface object] -- volume file-derived isosurfaces back
Current volume file formats supported include:
| APBS | APBS DX volume data files | | CASTEP | CASTEP density files | | BCIF | Binary CIF volume data maps in MessagePack format served from the European Bioinformatics Institute density server. | | CUBE | Gaussian cube format volume data files. Units of Bohr are assumed unless the keyword ANGSTROMS precedes the FILE keyword. | | Chem3D | chem3d 3dxml structure files may contain volume data | | DSN6/OMAP (CCP4) | binary files used, for example, to deliver x-ray defraction and cryo-EM map data. | | GRASP/DELPHI | GRASP grid files. | | Jaguar PLT | Jaguar plt orbital files | | NCI | Jmol has support for displaying results of NCIPLOT "noncovalent interactions" calculations. See "Revealing Noncovalent Interactions", Erin R. Johnson, Shahar Keinan, Paula Mori-Sanchez, Julia Contreras-Garcia, Aron J. Cohen, and Weitao Yang, J. Am. Chem. Soc., 2010, 132, 6498-6506 and "NCIPLOT: A Program for Plotting Noncovalent Interaction Regions" Julia Contreras-Garcia, Erin R. Johnson, Shahar Keinan, Robin Chaudret, Jean-Philip Piquemal, David N. Beratan, and Weitao Yang, J. of Chemical Theory and Computation, 2011, 7, 625-632. For consistency with the mapping colors of these articles, the specific color scheme shown below is recommended. Without reading any files, the NCI keyword specifies to carry out an NCI promolecular calculation. However, if the output files from NCIPLOT are available, they can be used as well, for example: ISOSURFACE parameters [0 0 0 0 0 0.01] NCI dens.cube. Note that only the density file is required; Jmol can generate the reduced density gradient data from that density file alone. Any CUBEGEN or other format density file that Jmol can read can be used here. (The 0.01 parameter is required only when reading the density file created by NCIPLOT, because that file is scaled up by a factor of 100 relative to standard density files. If using both NCIPLOT output files, then the command is simply: ISOSURFACE parameters [0.5] grad.cube MAP dens.cube fullylit.Parameters are [cutoff, p1, p2, p3, p4, p5], described below. Zero for any parameter specifies to use the default value.
| p1 | -2 to 2 | 0(all, default), 1(intramolecular), 2(intermolecular), -1(intramolecular NCIPLOT grad/dens filtering), -2(intermolecular NCIPLOT grad/dens filtering). | | p2 | rhoMin | (min rho cutoff to remove very low density points) | | p3 | rhoPlot | (cutoff used to remove covalent density, default 0.07 for promolecular, 0.05 for SCF) | | p4 | rhoParam | (fraction of total rho that defines intramolecular, default 0.95) | | p5 | dataScaling | (default 1, but set to 0.01 to read back in NCIPLOT -dens.cube file) |
For more information, see misc/iso-nci.txt. | | MRC/CCP4 | binary AMI MAP files have the advantage that they contain information about the root mean square deviation for the data set, allowing use of the SIGMA keyword . In some cases the keyword MRC just precede the FILE keyword in order to force MRC format reading because the file does not have the expected identifying characters M A P in the proper location. | | NFF | neutral file format for electron microscopy data exported from IMOD using the ISOSURFACE command | | UHBD | University of Houston Brownian Dynamics files. | | XPLOR/CNS | XPLOR MAP files |
[surface object] -- surface data-derived isosurfaces back
Current surface file formats supported include:
| EFVET | eF-site EFVET format surface files. Indicating a number from 0-5 after the file name specifies which type of data to map onto the surface:
| 0 | color indicated in file | | 1 | electrostatic_potential | | 2 | hydrophobicity | | 3 | temperature_factor | | 4 | minimum_curvature | | 5 | maximum_curvature |
| | JVXL | Jmol Voxel format files are highly compressed surface files created by Jmol using the write command. The JVXL format allows for saving the data for a selection of a specific surface cutoff from a volume file in a way that can be delivered very efficiently over the web and loaded very quickly into Jmol. | | KINEMAGE | Jmol reads contact-point Kinemage files created by MolProbity See misc/kinemage.txt for details. | | MSMS | Jmol can read an isosurface from a set of MSMS output files. Both the .vert and the .face files must be in the same directory, or only dots will be generated. The keyword MSMS must precede the FILE keyword -- MSMS FILE "xxx.vert" -- because these files do not contain identifying information. | | OBJ | AutoDesk Wavefront Advanced Visualizer OBJ surface data files. (See also Wavefront Object format. In this case the keyword OBJ must precede the FILE keyword or the first line of the file must start with #pmesh. Jmol uses the vertex and face records of this file in order to create a set of polygons that are colored using the name of the group record, which is assumed to have the hexidecimal format g kRRGGBB. Note that Jmol does not read material (.mtl) files and so instead relies on this simpler method of assigning colors. Polygons are limited to triangles and quadrilaterals. An optional number after the file name --OBJ FILE "filename" n -- specifies a group from the OBJ file. isosurface OBJ "sample.obj" 3, for instance, reads only the third group of faces. | | PMESH | Jmol can read and write both ASCII and binary JmolPmesh surface formats. This format does not allow for colored vertices and does not shade by vertex, so it is generally appropriate for polyhedra, meshes, and contours only, not filled triangulated arbitrary surfaces. In the case of an ASCII JmolPmesh file with no header line (see below), the PMESH keyword is required. Otherwise Jmol can discern the data type from the first bytes of the file contents. A "pmesh" is a surface data set consisting of a set of vertices and a set of polygons defining the "facets" of the surface. Polygons are limited to triangles and quadrilaterals. See also PMESH INLINE, below. File formats readable by Jmol include:
| numeric pmesh | This relatively simple format can be found in 10x10pmesh.txt. Jmol reads this file in free format -- values simply need to be separated by some sort of white space.#JmolPmesh
100
3.0000 3.0000 1.0000
2.3333 3.0000 1.0000
...(98 more like this)
81
5
0
10
11
1
0
...(80 more sets like this)
- The first line identifies the file as a Jmol Pmesh file. It is optional but recommended.
- The second line defines the number of grid points defining the surface (integer, n)
- The next n lines define the Cartesian coordinates of each of the grid points (n lines of x, y, z floating point data points)
- The next line specifies the number of polygons, m, to be drawn (81 in this case). Setting this number to -1 indicates that some number of polygons follows, terminated by a polygon with 0 points indicated.
- The next m sets of numbers define the polygons. In each set, the first number, p, specifies the number of points and format for the polygon. This number may be 0 (end of polygon list), 1 (point), 2 (edge), 3 (triangle), 4 (triangle with edges marked) or 5 (quadrilateral with edges marked) or its negative. If negative, the polygon is followed by a color written as a hexadecimal or decimal integer (0xFF00FF or 16711935). The next p numbers specify indexes into the list of data points (starting with 0). The first and last of these numbers must be identical for formats 4 and 5, in order to "close" the polygon.
| | binary pmesh | A more compact binary pmesh format is described in pmesh.bin.txt. The format has the following specification:
4 bytes: P M \1 \0
4 bytes: (int) 1 (test for bigEndian)
4 bytes: (int) vertexCount
4 bytes: (int) polygonCount
64 bytes: reserved
---then for each vertex:
12 bytes: (float) x,(float) y,(float) z
---then for each polyhedron,
the number of vertices (from 1 to 4)
followed by the index of the vertex
in the vertex list, starting with 0:
[(int)nVertices,(int)v1,(int)v2,...,(int)vn]
|
|
[surface object] -- additional surface sources back
 Several additional sources of surfaces besides external files are available. For functionXY and functionXYZ, the extent and resolution of the grid can be set using the keywords ORIGIN, STEPS, and POINTS. For example, isosurface origin {-5 -5 -5} steps {0.2 0.2 0.2} points {50 50 50} functionxy = "x * y * cos(x * 100)" or isosurface cutoff 2.0 origin {-5 -5 -5} steps {0.2 0.2 0.2} points {50 50 50} functionxyz = "x * y * cos(z*100)" map functionxy = "x * y" (shown here on the right.
| FUNCTIONXY = "..." | graphs a function of x and y with a default range in x and y from -10 to 10 every 0.25 Angstroms. For example, isosurface functionXY = "x * y" | FUNCTIONXY
"functionName"
{originXYZ}
{ni xi yi zi}
{nj xj yj zj}
{nk xk yk zk} | The FUNCTIONXY keyword specifies that the Z-value at a given X,Y coordinate will be provided via a JavaScript function in the case of the applet or via a JmolStatusListener call in an application or, if the function name begins with file:, the numbers will be read from that file (relative to the current directory). The parameters mirror the parameters in the header of a CUBE file. Units of ANGSTROMS are assumed. Thus, we require an origin of the voxel space and for each nominal direction x, y, and z, the number of grid points and the direction of the unit vector along that edge. These four quantities must be in braces. In the case of the Jmol applet, there are three reading options.
| ni>0 and nj>0 | functionName(app, ix, iy) | one point is returned for each call to the function. | | ni<0 and nj>0 | functionName(app, ni, nj) | an entire set of z values separated by white space will be returned as a string. Data are read from low to high coordinates, with X changing in the outer loop (slowly) and Y changing in the inner loop: a11, a12, a13,...,a21, a22, a23,..., etc. | | ni<0 and nj<0 | functionName(app, ni, nj, Fxy) | the Fxy[-ni][-nj] array will be filled with z values in the case of the applet or functionXY(functionName, ni, nj, Fxy) will be called in the case of the application. |
If the functionName starts with the string "file:", then Z value data will be loaded from a file instead of a JavaScript function in the order described above for reading data from a returned string. | | FUNCTIONXYZ = "..." | Graphs an isosurface through a block of data defaulting to -10 to 10 Angstroms range in x, y, and z with step every 0.25 Angstroms. For example: FUNCTIONXYZ = "x * x + y + z" . | FUNCTIONXYZ
"functionName"
{originXYZ}
{ni xi yi zi}
{nj xj yj zj}
{nk xk yk zk} | Similar to FUNCTIONXY, except that in this case the X,Y,Z cube data will be provided in the order (for x = 1 to ni)(for y = 1 to nj)(for z = 1 to nk). The first two options listed for FUNCTIONXY are not available, and the signs of ni and nj are ignored. The data structure Fxyz[ni][nj][nk] must be filled with data by the function call functionName(app, ni, nj, nk, Fxyz) in the case of the applet or functionXYZ(functionName, ni, nj, nz, Fxyz) in the case of the application. | | INLINE @varName | The isosurface data may be in a variable already. For example: x = load("mydata.dat"); isosurface INLINE @x first loads the data into the variable x, then displays the isosurface from that data, possibly giving the opportunity to peek at the data first. It is advisable to reset the variable after use to improve performance, however note that the state will only be preserved if the value of the variable is left unchanged. | | PMESH INLINE "pmesh-data" | The INLINE keyword can be used with PMESH to directly create a small isosurface. Numeric pmesh data may be specified "in-line" without reference to a separate file. This is particularly useful for pmesh objects with few vertices. Note that the draw command also can be used for this purpose. |
[additional mapping-only parameters] back
If any parameters spefically relate to the mapping of the surface, not the generation of it, then they can come after the specification of the surface object. Keywords such as COLOR RANGE, CONTOUR, DEBUG, FIXED, FULLPLANE, MODELBASED, MAP, REVERSECOLOR, SCALE3D, and SELECT (when it relates to the color mapping) fall into this category.
MAP [color mapping dataset] back
Except for SPHERE, ELLIPSOID, LOBE, and LCAOCARTOON, which have no CUBE-file equivalent, all the other surface types (including FUNCTIONXY) can be used as CUBE-type data sets in order to color map another surface, because they all involve the intermediate generation of voxel data within Jmol. Used with PLANE as a surface object, a slice through a set of data can be color-contoured.The keyword MAP is optional, recommended for readability. The set isosurfacekey option displays a vertical color key that can be hovered over with the mouse to display the values associated with mapped colors and contours. Existing isosurfaces can be mapped or remapped. To do this, simply start the isosurface command with the MAP keyword (with optional ID). The keyword set MAP SQUARED indicates that the values should be squared prior to mapping . The Jmol parameter isosurfacePropertySmoothing (default TRUE) determines whether the property is smoothed out over the isourface or assigned specifically to the nearest atom.
Atom based-properties can be mapped onto a surface using one of the following options. If MEP or MEP functionType is followed by PROPERTY xxx or property_xxx or variable..., that data will be used instead of partialCharge data.
| MEP | molecular electrostatic potential, using partial charge data within the file or assigned to atoms using the {...}.partialCharge = ... or data command syntax. A standard Coulomb function is used (1/d). | | MEP functionType | allows setting the function used for the mapping as for Chime, where functionType is the number 0, 1, 2, or 3:
| 0 | 1/d | Coulomb's law distance function (same as rasmol potential distance function) | | 1 | e^(-d/2) | Gaillard, P., Carrupt, P.A., Testa, B. and Boudon, A., J.Comput.Aided Mol.Des. 8, 83-96 (1994) | | 2 | 1/(1+d) | Audry, E.; Dubost, J. P.; Colleter, J. C.; Dallet, P. A new approach to structure-activity relations: the "molecular lipophilicity potential". Eur. J. Med. Chem. 1986, 21, 71-72 | | 3 | e^(-d) | Fauchere, J. L.; Quarendon, P.; Kaetterer, L. Estimating and representing hydrophobicity potential. J. Mol. Graphics 1988, 6, 203-206. |
These additional functions thus allow Jmol to use isosurface...MAP MEP to visualize molecular lipophilic potential (MLP) as well. | | PROPERTY xxx | where xxx is an atom-based property value such as partialCharge or temperature or vanderwaals. The COLOR option applies atom-based color to an isosurface, as commonly done in PyMOL. | | property_xxxx | The linking underscore signifies that the property was provided separately using the DATA command and is not model-file based. A previous SELECT ...; DATA "property_xxxx"....end "property_xxxx" or, if the data are from a variable, SELECT...; DATA "property_xxxx @x", must have already been issued. Note that when data is created in this way, only the selected atoms are assigned data values. Atoms thus selected need not be contiguous, but the data will be read from the variable or DATA command line contiguously, disregarding spaces, tabs, line ends, and any string that would not evaluate to a number. This allows for targeting just a specific set of atoms for an isosurface and associated data. After the property name the keyword WITHIN and a distance in Angstroms can be added to speed the calculation. The default for set isosurfacePropertySmoothing FALSE is 5.0 Angstroms. | | VARIABLE x | The property is in a varible named "x", possibly from a command such as x = load("mydata.txt"). In this case, the variable must contain a value for every atom in the model, even if only a subset of the atoms is being used for the surface. |
[display options] back
Display options are indicated in the following table. These may be given at the end of the definition of the surface or in a later command having just these keywords and the identifier (or "ALL") of the desired isosurface.
| BACKSHELL/NOBACKSHELL | Opposite of FRONTONLY; displays only the back of the isosurface. | | CONTOURLINES/NOCONTOURLINES | turns on and off contour lines generated using the CONTOUR option (see bove). | | DOTS/NODOTS | Display dots at each mesh vertex point. The integer setting DOTSCALE can be increased from its default value of 1 to increase the size of these dots. | | FILL/NOFILL | Display the isosurface as a smoothly filled surface. | | FRONTONLY/NOTFRONTONLY | Display only the front half of the surface. This can be useful when the options mesh nofill are used. | | FRONTLIT /BACKLIT /FULLYLIT | In some cases the isosurface may appear flat. Using BACKLIT will fix this; FULLYLIT makes exterior and interior surfaces bright; FRONTLIT is the default setting. | | MESH/NOMESH | Display a mesh of lines intersecting at the vertexes used to construct the isosurface. | | OFFSET {x y z} | Offset the isosurface by the specified absolute amount. | | ROTATE quaternion/NONE | Rotate the isosurface by a given amount around a given axis. Rotations are about {0 0 0} and are cumulative; ROTATE NONE returns the isosurface to its original orientation. For example: isosurface s1 ROTATE @{quaternion({1 0 0}, 90)} | | ON/OFF | Turn the isosurface ON or OFF, but do not delete it. | | OPAQUE/TRANSLUCENT n | Display the isosurface as an opaque or translucent object. Several translucent options are available; see the color command. | | TRIANGLES/NOTRIANGLES | Display separated triangles (primarily for debugging purposes). |
|
| isosurface AREA SET (integer) |
Calculates the area of the current isosurface in Å2 and stores that value in the isosurfaceArea variable. The AREA parameter may also accompany any other parameters in the construction of an isosurface. The result is an array unless the optional specific surface set has been specified., in which case it is a decimal number. Sets are ordered from largest to smallest. SET 0 gives the sum of all areas. SET -1 returns the calculation to report the full array.
|
| isosurface CAVITY 1.2 50 vdw |
Increases maximum envelope radius from 10 to 50. Note that large envelope radii can produce artifacts for pocket cavities. For example:
load =1wp1 filter "biomolecule 1"
isosurface set 1 select {protein} only pocket cavity 3 20
isosurface slab none slab plane x=0
|
| isosurface CONNECT [atom-expression] |
Connects an isosurface to a specific reference atom so that if that atom is moved (using rotateSelected, for instance) or hidden the isosurface moves or is hidden with it. Typically the atom expression is a model, for example {2.1}, but only the first atom in the atom expression is used. Use isosurface connect {none} to disconnect an isosurface from its atom. Note that if more than one model (frame) is visible and this surface is for a specific model only, it is still necessary to add both the isosurface MODEL and SELECT options: frame *;isosurface model 1.2 connect {1.2} select all vdw.
|
| isosurface LATTICE {a b c} |
You can duplicate isosurface areas based on the unit cell lattice. This is a rendering option, so it can be applied any time after an isosurface is created. It is best done with packed unit cells and slabbed isosurfaces. For example: load quartz.cif {1 1 1}; isosurface slab unitcell vdw; isosurface lattice {3 3 3} creates an isosurface that spans nine unit cells. The LATTICE keyword may also appear after the MAP keyword, indicating that the mapped data is periodic and should be mapped for multiple unit cells.
|
| isosurface LATTICE {a b c} FIXED |
Creates an isosurface from periodic volumetric data with the specified number of unit cells. The FIXED option "fixes" the isosurface in the sense that the operation is at load time not at rendering, allowing slabbing and use of WITHIN. You can duplicate isosurface areas based on the unit cell lattice. This is a rendering option, so it can be applied any time after an isosurface is created. It is best done with packed unit cells and slabbed isosurfaces. For example: load quartz.cif {1 1 1}; isosurface slab unitcell vdw; isosurface lattice {3 3 3} creates an isosurface that spans nine unit cells. The LATTICE keyword may also appear after the MAP keyword, indicating that the mapped data is periodic and should be mapped for multiple unit cells.
|
| isosurface LIST |
Lists all isosurfaces
|
| isosurface VAL [points or atoms] |
Calculates isosurface values for a set of points or atoms. Values are created during surface constructions, not after, so this option must come before any keyword that initiates construction such as a file name or SOLVENT or MOLECULAR. For solvent and molecular surfaces, negative value is "inside"; positive is "outside". Surfaces that are not calculated will give 0 for all values.
|
| isosurface SET (integer) |
When an isosurface consists of more than one set of surfaces (perhaps from isosurface internal cavity), specifying a SET displays just that single subset of the overall isosurface. SET 0 returns the display to all sets. Sets are ordered from largest (1) to smallest.
|
| isosurface SUBSET (array) |
Similar to ISOSURFACE SET but displays one or more subsets of the overall isosurface. For example, ISOSURFACE SUBSET [1 2 3] CAVITY VDW will display the three largest sets.
|
| isosurface SLAB (parameters) |
Isosurface SLAB provides an extensive mechanism allowing for the trimming of an isosurface using a wide variety of methods. Isosurfaces can be "slabbed" based on planes, spheres, bounding boxes, unit cells, proximity to a set of atoms, a range of mapped values, or a dynamic z-plane relative to the user (as in Rasmol slabbing of models, but with isosurfaces instead). The section removed can be removed completely or, using isosurface SLAB TRANSLUCENT, left as a translucent "ghost" surface. An isosurface may be slabbed any number of times in any number of ways. The slabbing is reversible using isosurface SLAB NONE for general slabbing and isosurface SLAB OFF for dynamic z-plane slabbing. Options include:
| (plane expression) | a plane. Note that plane definitions starting with "-" switch sides of the plane
| | BOUNDBOX | within the currently defined bounding box
| | UNITCELL | within the currently defined unit cell
| | WITHIN x.y {atom expression} | within the given distance of the specified atom set
| | WITHIN x.y (point) | within the given distance of the specified point (a spherical slab)
| | WITHIN RANGE x.x y.y | within the mapped value range x.x and y.y.
|
|
| isosurface UNITCELL (fraction) |
Isosurface UNITCELL x.x is for periodic lattices only. It adjusting the grid by x.x in fractional coordinates. Caution is advised, as the grid is expanded in this process, leading to more grid points and more memory required. Negative x.x results in a selection of a subset of the data centered on the center of the unit cell.
|
| isosurface VAL [atom-expression] or array of points |
The VAL option, indicated prior to the specification of the surface type, calculates isosurface values for a set of points or atoms. For solvent and molecular surfaces, negative values are "inside"; positive are "outside". Surfaces that are not calculated (as from CUBE files) will give 0 for all values. These values can be retrieved as an array using $s1.getproperty("value"), where s1 is an isosurface ID. For example:
load $caffeine
isosurface s1 value {*} select {!_H} only vdw 50% translucent
{*}.property_d = $s1.getproperty("value")
color property_d.
|
| isosurface VOLUME SET (integer) |
Calculates the volume of the current isosurface in cubic Angstroms and stores that value in the isosurfaceVolume variable. The VOLUME parameter may also accompany any other parameters in the construction of an isosurface. The result is an array unless the optional specific surface set has been specified., in which case it is a decimal number. Sets are ordered from largest to smallest. SET 0 gives the sum of all volumes. SET -1 returns the calculation to report the full array.
|
| isosurface [f1, filename1, f2, filename2, ...] |
Creates an isosurface that is the linear combination of volume data. All grids must be identical. (This is not checked internally, and no error is thrown if this is not the case.) f1 and f2 are scalar factors. For example, comparing a crystal surface struture with and without binding of a surface molecule: ISOSURFACE [1, "PtO.cube", -1, "Pt.cube", -1, "O.cube"]. A plane can be mapped as well: ISOSURFACE PLANE x=0.1 map [1, "PtO.cube", -1, "Pt.cube", -1, "O.cube"]. It is recommended to use ISOSURFACE CACHE to convert to JVXL before saving in PNGJ format to allow for much smaller PNGJ files.
|
|
Examples: |
isosurface pos05 0.05 "ethene-HOMO.cub.gz";isosurface neg05 -0.05 "ethene-HOMO.cub.gz";
# now load some other surface further out;
isosurface pos01 0.01 "ethene-HOMO.cub.gz";
isosurface neg01 -0.01 "ethene-HOMO.cub.gz";color isosurface translucent; # make neg01 translucent
isosurface pos01 nofill mesh; # make pos01 a mesh;
color isosurface translucent; # make the pos01 mesh translucent, too
isosurface neg01 dots; # make neg01 show dots, too
isosurface neg01 nofill; # only dots
isosurface nodots nomesh fill; #everybody is back to a solid ...;color isosurface opaque; # ... and opaque
isosurface neg01; #select neg01;
color isosurface green;
isosurface pos01;color isosurface violet;
slab on; slab 50; # slab in order to see the inside
slab off; # all done! |
|
See examples-11/isosurface.htm
|
See also:
|
[plane expressions] lcaoCartoon mo pmesh undefined |
top search index |
|
Executes the specified javascript command. Applet only; may be disallowed by setting Info.allowJavaScript = false for the Info structure used when creating the applet. Note that double quotes or no quotes are required; single quotes are not appropriate in this context.
|
See also:
|
getProperty script set (callback) undefined |
top search index |
load
(v. 13.00) [File types]
[ZIP/JAR files and JmolManifest]
[General Options]
[Crystallographic Options]
|
See examples-11/sym.htm
|
Loads the specified file or URL or string data. A wide variety of file types are supported. In general, resolution of file type is based on internal file cues, not the filename or file extension. However, this resolution process can be overridden by specifying a prefix to the file name consisting of the file type followed by two colon characters: load "molpro(xml)::myfile". PDB-type files can be loaded with automatic addition of hydrogen atoms and multiple bonds using SET pdbAddHydrogens. For PDB, PQR, and mmCIF files that contain HELIX, SHEET, or TURN records provided by the author, those structures are created (though not initially displayed); for PDB, PQR, and mmCIF files that do not contain this information, Jmol will generate secondary structure using DSSP (W. Kabsch and C. Sander, Biopolymers, vol 22, 1983, pp 2577-2637; http://swift.cmbi.ru.nl/gv/dssp) for chains that contain backbone atoms and the method of Levitt and Greer [J.Mol.Biol.(1977) 114, 181-293] for alpha-carbon-only chains. (See also calculate STRUCTURE.)
Multiple files and a selected model from a multi-model file can be read as well. Files may be Gzipped, and multiple files can be read from compressed ZIP and JAR collections. A default directory can be set using set defaultDirectory, and for applets a proxy server can be set for non-host file loading using set appletProxy. After the filename, the options listed below are available. These options must appear in the order given in the table below. In addition, the load command can take parameters that specify the number of unit cells to generate, the the space group or Jones-Faithful operators to use, and the unit cell dimensions. Using these parameters, the space group and unit cell information within a file can be overridded, and even simple XYZ data files can be turned into crystallographic data sets. The FILTER keyword allows selective loading of atoms as well as construction of the biologically relevant molecule (PDB "BIOMOLECULE" records. See also the headings load APPEND, load FILES, load MENU, load MODELS, and load TRAJECTORY. Note that with the Jmol application (not the applet) you can also use Edit...Paste to load molecular coordinate from the system clipboard. The same capability for the applet can be had using data "model".
[File types] back
Jmol reads a wide variety of data formats. Example files can be found at http://jmol.svn.sourceforge.net/viewvc/jmol/trunk/Jmol-datafiles. Supported file types include:
| $identifier | Jmol can utilized the SMILES-to-3D and database service at the NIH Cactus server to load 3D models based simply on SMILES strings or chemical identifiers such as chemical names, CAS registry numbers, and InChI keys. For example, load $CCC loads the structure of propane, load $C1CCCCC1 loads a chair cyclohexane model, and load $tylenol loads a model of acetaminophen. Using "$?" offers a prompt to the user. | | :name | Load a model directly from PubChem. A name or a PubChem ID may be given. Using ":?" offers a prompt to the user. For example, load ":tylenol" or load ":1983" loads a model of acetaminophen. More specifically the syntax load :xxx:yyyy, where xxx is CAS, CID, NAME, INCHI or SMILES, specifies the exact sort of compound identifier yyyy that follows the second colon. Note that INCHI must be a standard inchi key, as perhaps generated using {*}.find("chemical", "stdinchikey") | | =XXXX | a PDB file directly from RCSB. For example, load "=1crn". Using "=?" offers a prompt to the user. | | =XXXX.cif | a CIF file directly from RCSB. | | =xxxx.bcif | Specifies to read a Binary CIF file from RCSB. VERY large files can be loaded successfully. The recommendation is to load large protein files with filter "*.C" for backbone only, without autobonding:
set autobond off;
load =8glv.bcif filter "*.C";
spacefill on;
color chain;
| | =XXXX.mmtf | an MMTF file directly from RCSB. The The Macromolecular Transmission Format is a new compact binary format to transmit and store biomolecular structural data quickly and accurately. | | ==XXX | a ligand from RCSB. For example, load ==hem. Using "==?" offers a prompt to the user. | | =XXXX/dssr | Adding /DSSR instructs Jmol to also obtain the nucleic acid secondary structure 3DNA from Columbia University. For a full discussion of Jmol in relation to DSSR see Robert M. Hanson, Xiang-Jun Lu, DSSR-enhanced visualization of nucleic acid structures in Jmol, Nucleic Acids Research, Volume 45, Issue W1, 3 July 2017, Pages W528-W533. | | =XXXX/rna3d | loads mmCIF data from RCSB, also fetching RNA secondary structure annotations from http://rna.bgsu.edu/rna3dhub indicating hairpinLoops, internalLoops, and junctions. Allows for such constructs as
select within(rna3d,"hairpinLoops")
select within(rna3d,"hairpinLoops where index=5")
x = getproperty("auxiliaryInfo.models[1].rna3d.internalLoops.5")
x = getproperty("auxiliaryInfo.models[1].rna3d.internalLoops")[5]
print x
{
_atoms : ({3023:3062 3639:3706})
_isres : true
_path : "internalLoops"
index : 5
units : "1S72|1|0|C|153,1S72|1|0|C|154,1S72|1|0|G|182,1S72|1|0|A|183,1S72|1|0|G|184"
}
y = x._atoms
select y | | =XXXX/dom | see *XXXX/dom; mmCIF data retrieved from RCSB | | =XXXX/val | see *XXXX/val; mmCIF data retrieved from RCSB | | *XXXX | Similar to =XXXX, but retrieving data from http://www.ebi.ac.uk/pdbe. Using "*?" offers a prompt to the user. | | *XXXX/dssr | see =XXXX/dssr; mmCIF data retrieved from PDBe | | *XXXX/rna3d | see =XXXX/rna3d; mmCIF data retrieved from PDBe | | *XXXX/dom | mmCIF + domain annotations from PDBe. | | *XXXX/val | mmCIF + validation annotations from PDBe. | | ADF/AMS | Amsterdam Density Functional/Amsterdam Modeling Suite output file | | =ams/nnnnnnn | (seven-digit number) loads data from American Mineralogist Crystal Structure Database, fetching data from http://rruff.geo.arizona.edu/AMS; employs "#_DOCACHE_" flag, indicating to save the full structure in a state file, because this number is not a permanent reference in the database.For example: LOAD =ams/0014673 same as LOAD http://rruff.geo.arizona.edu/AMS/viewJmol.php?amcsd=14673&action=showcif#_DOCACHE_ | | =ams/nnnnn | (five-digit number) loads that specific structure based on sequential id code.For example: LOAD =ams/10000 same as LOAD http://rruff.geo.arizona.edu/AMS/viewJmol.php?id=10000&action=showcif#_DOCACHE_ | | =ams/mineralName | loads all AMS structures for a specified named mineral. For example: LOAD =ams/diamond same as LOAD http://rruff.geo.arizona.edu/AMS/viewJmol.php?mineral=diamond&action=showcif#_DOCACHE_ | | =chebi/nnnnnn | Chemical Entities of Biological Interest 2D model with minimal 100-step minimization | | =cod/number | For example, load =cod/1000041. Loads Crystallographic Open Database files by number | | =AFLOWLIB/nnn.m | The AFLOW Encyclopedia of Crystallographic Prototypes is a collection of CIF files organized by space group. The encyclopedia "provides a complete description of each structure, including formulas for the primitive vectors, basis vectors, and AFLOW commands to generate the standardized cells." This load option retrieves the m-th AFLOW prototype in space group nnn. Each of the 230 space groups has at least one example structure. A full listing of the AFLOW codes in the encyclopedia (subject to updates) can be found in aflow_structures.json. Providing only a space group number retrieves the first structure for that space group. For example: load =AFLOWLIB/147.3 or load =AFLOWLIB/145 PACKED. References:[1] [2] [3] [4] | | =AFLOWLIB/aflowlibid | Loads a structure from the AFLOW Encyclopedia of Crystallographic Prototypes by its AFLOW id. For example, load =aflowlib/A3BC_tP5_99_ac_b_a-002 packed. | | AIMS | Ab Initio Molecular Simulation Package (input files only) | | AMPAC | AMPAC file | | Argus(XML) | ArgusLab AGL file | | Bilbao(BCS) | Bilbao Crystallographic Server file format. This simple format is similar to XYZ file format, but including International Tables space group number (first line), the unit cell parameters (second line), an atom count (third line), and then a list of atom names and positions. (examples) | | CDX,CDXML | Jmol Reads CDX and CDXML files, either to 2D or 3D. The reader cleans files of unattached "phantom" atoms that appear in stored warnings to users. Partial bonds and multiple-attachment bonds (e.g. ferrocene) are recognized and converted to partial bonds in Jmol. The reader can be used to generate SMILES, InChI, InChIKey, and 2D-MOL files. | | CGD | Gavrog Systre Crystal Graph Data file format, as produced by TOPOS topological analysis of crystal structures. | | Chem3D(XML) | CambridgeSoft Chem3D C3XML file | | CASTEP | CASTEP input, .md, .geom, .phonon, .magres, and .ts file formats. .phonon files are read as trajectories -- see the FILTER specifications, below, to load specific q-point mode sets. | | CIF | International Union of Crystallography Crystallographic Information File, versions CIF 1.1 and CIF 2.0, including Macromolecular Crystallographic Information files (mmCIF), Binary CIF (a binary version of mmCIF), Modulated Structure files (msCIF), and Bilbao Magnetic structure files (mCIF). NOTE: The default for loading CIF files that have GEOM_BOND records is to make loading more similar to the way Mercury opens files. Such files are loaded by default as full molecules based on the idea that a "molecule" is "symop=1 or connected(symop=1)". The model is displayed WITHOUT a unit cell, and no unit cell information is made available. The standard load xxx.cif {1 1 1} is still available if a unit cell is desired. Jmol will accept CIF files with duplicate atom_site_label entries (even though those are technically invalid, since that key is an index key) by adding numbers to the label when two identical atom_site_label values are found. A warning message is reported in the Java console only. | | CML(XML) | Chemical Markup Language files. | | CRYSTAL | Crystal solid state computation output, including support for 1D (polymer) and 2D (slab) periodicity. This file format creates the atom properties property_spin and property_magneticMoment. Jmol reads TOPOND TRHO and TLAT data for Bader analysis. | | CSF | Fujitsu Sygress Explorer (formerly CAChe) chemical structure file, including the reading of ab initio, semiemperical, gaussian, and density functional molecular orbitals | | CUBE | Gaussian cubegen output file | | DCD | single precision binary (FORTRAN unformatted) DCD trajectory files (Jmol 12). These files require the COORD keyword and a file giving atom information, such as a PDB file. For example: load trajectory "t.pdb" coord "t.dcd" | | DGRID | DGRID file reader (Jmol 12). These files are generalized representations of output from a variety of quantum mechanical calculation packages, including especially ADF. | | FCHK | Gaussian formatted check-point file format | | FoldingXYZ | XYZ file created by the Folding@home project | | GAMESS | General Atomic and Molecular Electronic Structure System output file | | Gaussian | Gaussian output file. spin density will be read into an atoms's property_spin property . | | GhemicalMM | Ghemical molecular mechanics file (MM1GP) | | GRO | GROMACS .gro file format | | GULP | GULP file format | | HIN | HyperChem native file | | Jaguar | National Center for Supercomputing Applications Jaguar output file | | JANA2006 | Jana2006 M40/M50 files can be read, and incommensurate structures can be displayed. Commensurately and incommensureately modulated structures can be read. Not supported to date: X-harmonic and Legendre polynomial modulation specifications, crenel-orthogonalized Fourier modulation functions. | | JCAMP-DX | Jmol can read specialized JCAMP-DX files containing ##$MODELS records and automatically sychronize user picking actions based on ##$PEAKS record information. See Jmol-JSpecView-specs.pdf. | | JME | Java Molecular Editor file format (a 2D, not a 3D, format) | | JSON | Starting with Jmol 14.0, Jmol can read (and writemodel) JavaScript Object Notation-formatted data. The format is compatible with that developed for ChemDoodle, specifically implementing the "a" and "b" keys, but also adding optional keys "_is2D" and "_scale" (see below). Data must be wrapped in a JSON object named "mol": {"mol":{ "a":[...], "b":[...]} }. White space is allowed, but only after the opening seven characters, which identify the file type as JSON.
| _is2D | true if data are to be converted to 3D automatically
| | _scale | scale of data in x, y, and z directions. {"x":20,"y":-20,"z":20}, for example, indicates that the data need to be scaled down by a factor of 20, and the y axis needs to be reversed.
| | a | an array of atom records of the format {"l":atomSymbol,"x":xCoord,"y":yCoord,"z":zCoord}, where "z" and "l" (the lower-case letter "L", for "label"; defaulting to "C") are optional.
| | b | an array of bond records of the format {"b":atomIndex,"e":atomIndex,"o":order}, for "begin", "end", and optional "order" (defaults to 1). atom indexes are 0-based.
|
| | MAGRES | Magres files | | MDTOP, MDCRD | AMBER Molecular dynamics topology files and associated coordinate files. | | MOL, MOL2 | Accelrys (formerly Symyx, formerly Molecular Design) structure data files, including SDF and CTAB V2000 files. Starting with Jmol 14.1.12, using the forcing prefix MOL3D, as in load "MOL3D::xxx.mol" one can cause Jmol to throw an error if a 2D MOL file is attempted to be read. Starting with Jmol 14.9.2, Jmol will interpret a MOL file bond order 14 as bond order 4 (as in [Re2Cl8]2-), 15 as bond order 5 ([Mo2Cl8]4-), and 16 as bond order 6 (Mo2). | | MOLDEN | Molden data file. Jmol 14.4 allows an extended version of MOLDEN files to be read that contains crystallographic information (from CASTEP), specifically [SpaceGroup], [Operators], and [Cell] or [CellAxes] (but not both). For example:
[SpaceGroup] (Number)
1
[Operators]
x, y, z
[Cell] (Angs)
2.96340697 6.51358688 -1 90.0000 90.0000 90.0000
(or)
[CellAxes] (Angs)
2.963407 0.0 0.0
0.0 6.513587 0.0
0.0 0.0 0.0
...
| | MOLPRO(XML) | Molpro structure file | | Mopac | OpenMopac output file (MOPOUT) | | MopacGraphF | OpenMopac GRAPHF output file (for molecular orbitals) | | NWCHEM | Pacific Northwest National Laboratory NWChem output file | | Odyssey | WaveFunction Odyssey data file (ODYDATA) | | Odyssey(XML) | WaveFunction Odyssey XODYDATA file | | OPTIMADE | The Open Databases Integration for Materials Design (OPTIMADE) consortium aims to make materials databases inter-operational by developing a common REST API. Using the explicit file type optimade::, Jmol will read files generated from various sources. For example, load Optimade::https://optimade.materialsproject.org/v1/structures?filter=nelements=6&page_limit=1. | | PDB | Protein Data Bank files. PDB reading of X-PLOR using hybrid-36 and NAMD files using hex is also supported. See http://www.schrodinger.com/AcrobatFile.php?type=supportdocs&type2=&ident=530 and http://cci.lbl.gov/cctbx_sources/iotbx/pdb/hybrid_36.py. | | PQR | Position/Charge/Radius data file produced by the Adaptive Poisson-Boltzmann Solver project | | P2N | R.E.D. input files, also reading the AltName field and allowing label %[altName] | | PSI | PSI3 output reader (coordinates only) | | PyMOL PSE | PyMOL session files. Jmol will read most PyMOL session files, creating a very close representation of the view as seen in PyMOL 1.6. This ongoing project aims to faithfully reproduce the key features of PyMOL sessions. A representative sampling of how well this works can be found at http://ispcbck.weizmann.ac.il/a2jmolb/browse and misc/PyMOL2Jmol_browse.pdf. FILTER options "nosurface" and "docache" are explained below. | | QCHEM | Q-Chem output file | | QuantumEspresso | see http://www.quantum-espresso.org; XML files readable in Jmol. | | SHELX RES | SHELX output file. Jmol will read Q points as element Xx, assigning the labels Q1, Q2, ... etc. Both PART n and PART -n are recognized. Part -n (symmetry-related occupational disorder) atom are shown translucent by default. | | Spartan | WaveFunction Spartan data file | | SMILES | See $smilesString, above. | | SpartanSmol | WaveFunction binary Spartan SMOL data file, including full MacSpartan Spartan directories in ZIP format | | Tinker | tinker files are simple coordinate files similar to XYZ format files, but including atom type and bonding information. If the first line only contains an atom count then the filename must be preceded by tinker::. | | V3000 | Symyx (formerly Molecular Design) V3000 Connection Table (CTAB or SDF) data file. Starting with Jmol 14.2, Jmol supports DATA Sgroups for reading atom properties:
M V30 BEGIN SGROUP
M V30 1 DAT 0 ATOMS=(1 1) FIELDNAME=pc FIELDDATA=-0.2344
M V30 1 DAT 0 ATOMS=(1 2) FIELDNAME=pc FIELDDATA=0.3344
M V30 1 DAT 0 ATOMS=(1 3) FIELDNAME=pc FIELDDATA=-0.4344
M V30 END SGROUP
If the field name contains "partial" then Jmol will assign atom partial charges directly. Other properties will be read as {*}.property_xxx, where xxx is the field name. | | WebMO | WebMO molecular orbital file reader | | VASP | Vienna Ab Initio Simulation Package VASP vasprun.xml, CHGCAR, and OUTCAR files. | | Wien2k | Wien2k data files. WIEN2k performs electronic structure calculations for solids using density functional theory. Using the option spacegroup "none" disregards symmetry information given in the file and simply reads the atom coordinates given in the file, including MULT atom records. For example, load t.struct {1 1 1} spacegroup "none" | | XYZ | Minnesota Supercomputer Institute XMol file format. Various extensions to this file format allow reading of the following information separated by whitespace:
| element | x | y | z
| | element | x | y | z | vibX | vibY | vibZ
| | element | x | y | z | charge
| | element | x | y | z | charge | radius
| | element | x | y | z | charge | vibX | vibY | vibZ
| | element | x | y | z | charge | vibX | vibY | vibZ | atomNumber
|
If the charge is an integer, it is read as formalCharge; if it is decimal, then as partialCharge. Any information past x y z is optional, and if missing or uninterpretable as a number (for example, "X" or "--") will be ignored. The element may be either an atomic symbol or an isotope symbol such as 13C or an atomic number such as 6. | | ZMatrix | The Z-Matrix format allows for molecules to be described by internal coordinates (distances, angles, and dihedrals) rather than in terms of actual Cartesian coordinates. Jmol can read several forms of Z-matrix data, including MOPAC and Gaussian format as well as a format designed for Jmol that allows also the simple introduction of bond order. Details are given in the Z-Matrix reader code itself. The reader supports dummy atoms, atom labels, symbolic variable definitions, Cartesian coordinates or a mix of Cartesian and internal coordinates, alternative distance + two angles rather than distance + angle + dihedral, and specification of bond order. (Jmol 12.3.8). Gaussian and MOPAC file names must be preceded with ZMATRIX:: to bypass attempted format identification, as those file formats have no easily recognizable internal characteristics. |
[ZIP/JAR files and JmolManifest] back
Jmol can read specific files within compressed ZIP and JAR collections. In addition, for the load command specifically, Jmol will look for a file within the collection with the name JmolManifest and follow the directives within it. These directives may be as simple as a list of files to be loaded, one filename per line (which will be read in the order listed). Lines starting with # are comment lines, which may contain any text, but also may contain one or more of the following keywords:
| #EXCEPT_FILES | The list of files specifies files to ignore, not files to load; all other files will be loaded. | | #IGNORE_ERRORS | Try to read files, but ignore errors when a file is not recognized as a valid model format that Jmol can read. This option allows easy "mining" of ZIP collections for files that Jmol can recognize, ignoring all others. | | #IGNORE_MANIFEST | Ignore this manifest in its entirety -- simply read all files in the order retrieved by the ZIP file iterator. |
[General Options] back
The following options may be indicated after specifying the filename. Each is optional, but if more than one option is indicated, options must be given in the order listed in this table.
| MANIFEST "manifestOptions" | If the file being loaded is a ZIP or JAR file, Jmol will search for a file in that compressed file collection with the name "JmolManifest" and process it accordingly (see above). However, in the load command, if the keyword MANIFEST and a quoted string follows the filename, then Jmol will use this string as the manifest instead, with lines of the manifest separated by vertical bar "|" characters. In this way, standard ZIP collections can be read, and the order of file loading can be specified. For example: load "test.zip" manifest "CH3CL.MOL|CH4.MOL" reads only these two files from the ZIP collection, in this order. If the file contains a manifest and that manifest is simply to be ignored, the quoted string should read "IGNORE_MANIFEST". | | (integer) | Loads only the specified model number (if positive) or vibration number (if negative), skipping the others. For PDB files, the number indicated is the number specified in the MODEL record. (Not supported by all file types.) See also load MODELS. | | {unitCell(s)} | see Crystallographic Options, below | | OFFSET {x y z} | You can offset atoms in a file by a given amount at load time. The offset can be expressed in fractional coordinates, such as {1/2 1/2 1/2}, and although primarily intended for CIF file reading, can be applied to any file type. If a space group and/or unit cell are specified, the OFFSET parameter must follow that specification. | | FILTER | The FILTER parameter specifies file-type specific load options (see below). Options should be separated by commas. For atom selection, more than one specification may be made using a comma between specifications: *:1,*:2, but * and ! may not be mixed within any one type (atom name, group name, or chain ID). "|" indicates OR in a broader context: load 1blu.pdb filter "*.CA | HETATM,![HOH]" selects for alpha carbons OR (HETATM and not HOH). |
[Crystallographic Options] back
The following crystallographic options may be indicated, starting with the specification of the unit cell. If more than one option is indicated, options must be given in the order listed in this table.
| {lattice} | Jmol can read unit cell and symmetry information from selected file types (for example, CIF, PDB, or SHELX). The specific set of unit cells to load can be specified one of two ways -- either using the notation {i j k} or the notation {ijk i'j'k' n}.
| {i j k} | Loads a block of unit cells between the origin, {0 0 0} and the specified unit cell system coordinate. Used alone, {i j k} is only for working with files containing both unit cell and space group information (CIF, SHELX, CML, for example). The particular choice {3 3 3} is significant, in that it loads 27 unit cells, forming a solid block around a central cell. The unit cell display can then be moved to the origin of this central cell using unitcell {1 1 1}, and the display of atoms can be restricted to that center cell using restrict cell=666 or restrict cell={2 2 2}. Multiple unit cell loading can be combined with the single-model loading by indicating the model number first, then the number of unit cells: load "myfile.cif" 15 {3 3 3}. Quotes are not required. There is no restriction other than memory on the size of i, j, and k (except that all must be positive).
| | {ijk i'j'k' -1} |  Loads a block of unit cells within the range ijk and i'j'k' (which should include 555) and packs all atoms into the designated set of cells. If atoms are on faces, those atoms will be duplicated at each equivalent face.
| | {ijk i'j'k' 0} |  Loads a block of unit cells within the range ijk and i'j'k' (which should include 555) WITHOUT normalizing the operators. All symmetry-generated atoms are placed based on the exact definition of the symmetry operations found in the file or designated using the spacegroup keyword (see option below). Note, however, that if explicit operations are not provided and therefor must be generated from a spacegroup name, they will be normalized. The list of operations used can be obtained using show symmetry.
| | {ijk i'j'k' 1} |  Loads a block of unit cells within the range ijk and i'j'k' (which should include 555), normalizing the operators to move the geometric center of the generated set of atoms into cell 555, then applying the lattice translation. Thus, load "filename" {555 555 1} is equivalent to load "filename" {1 1 1}. For example, load "myfile.cif" {444 666 1} loads a block of 27 unit cells, with the geometric center of all units with the bounds of the fractional coordinate range {-1 -1 -1/} to {2 2 2/}.
|
| | CENTROID x.x | The CENTROID keyword specifies that molecular crystal models should be created consisting of all molecules having their center of geometry, or centroid, within the specified block of unit cells (or {1 1 1} if not specified). The result is full molecules that are not broken across unit cell boundaries, with no duplication from one crystal face to another. Followed x.x allows expanding the range within which the geometric center of the molecule must lie. For example, load =aflowlib/45.2 CENTROID 0.5. The presence of a range forces packing; if packing is wanted without a range, use CENTROID PACKED. Note that only one shell of unit cells is added around the 555-unit cell in order to find molecular fragments. If atoms in a molecule extend beyond this range, they are truncated. To extend the number of molecules beyond this range, add a lattice range, as in load aflowlib/45.2 {2 2 2} CENTROID PACKED. | | PACKED x.x | The keyword PACKED may be used in place of {555 555 -1} or after a designated set of cells: load t.struct {2 2 2} PACKED in order to load a set of atoms packed into the unit cell. If atoms are on faces, those atoms will be duplicated at each equivalent face. An optional range in fractional coordinates can be specified for including atoms that are outside the specified unit cell (default 0.02). | | SUPERCELL {na nb nc} | The SUPERCELL option allows reassigning the unit cell as any multiple of the actual unit cell. If this option is used, the final loaded symmetry is automatically set to P1, and cell parameters a, b, and c will be modified. A larger lattice can still be indicated, in which case they refer to how many supercells will be loaded. For example: load "quartz.cif" {2 2 2} supercell {5 5 1} will create a supercell that is 5x5x1 standard unit cells in size and then load a set of eight of those. SUPERCELL defaults to PACKED, but simply adding a lattice overrides this: load ... {1 1 1} SUPERCELL ... . | | SUPERCELL "axisFormula" | This supercell option allows creating a supercell using a linear combination of the x, y, and z vectors of the file-based unit cell. If this option is used, the final loaded symmetry is automatically set to P1, and cell parameters a, b, c, alpha, beta, gamma will be modified. For example, load "quartz.cif" packed supercell "2x, x + 2y, z" will load a rectangular unit cell instead of the hexagonal cell indicated in the file. You can add an origin offset to this specification as well: load quartz.cif supercell "2a,2b+a,c;1/2,0,0" allows adjusting origin without changing symmetry operations. The supercell option is equivalent to FILTER with cell=: load quartz.cif filter "cell=2a,2b+a,c;1/2,0,0". Note that the default lattice is set to {555 555 -1} (i.e., PACKED) with a range based on the supercell dimensions. To indicate a specific range for packing that is not the default of 0.02, simply indicate that explicitly: load quartz.cif PACKED 0.10 supercell "2a,2b+a,c;1/2,0,0". | | RANGE x.x | Restricts the atoms loaded to those within a given range in angstroms. If x.x is positive, then this range is relative to the entire set of atoms that would be generated using load "filename" {1 1 1}, and all atoms within the given distance from ANY atom in that set is loaded; if x.x is negative, then the range is relative to the atoms that would be generated using just load itself (the base x,y,z symmetry set), and the atoms loaded are all those within a box that is the designated distance larger than that needed to just contain the set of atoms. Then, to later select atoms actually within a given distance from the base set, use within with select or display: load 1crn.pdb {1 1 1} range -4; display within(4.0, symop=1555). (This two-step sequence is very efficient.) Note that Jmol will expand the load box by one number in each direction in order to find atoms that are outside of {i j k} but still within the designated range: load {555 555 1} range 2 actually checks all atoms within the 27-cell range 444 through 666. | | FILL | Fills (packs) a 10x10x10 Angstrom box (bounded by {0 0 0} and {10 10 10}) with atoms, regardless of the unit cell. This option allows comparing and visualizing crystal structures in a common range of space. | | FILL x.y | fills cubic box of the specified dimension. For example, load quartz.cif FILL 20.0. | | FILL BOUNDBOX | Fill the space defined by the current boundbox. | | FILL UNITCELL | Fill the space defined by the current unit cell. additional options include FILL UNITCELL PRIMITIVE and FILL UNITCELL CONVENTIONAL. Usually used with load "", as the current unit cell is defined for the model currently loaded. | | FILL [o vabc] | Fill a rectangular space bounded by two corners of a diagonal. For example, load quartz.cif FILL [ {0 0 0} {10 10 10} ]. Note that the parameter after FILL is an array, not just two coordinates. Fractional coordinates are allowed, and if present refer to the current unit cell, not the one being loaded. | | FILL [o va vb vc] | Fill an arbitrary unit cell defined by an origin and three crystallographic axis vectors. | | SPACEGROUP "name" | Loads a block of unit cells between the origin, {0 0 0} and the specified unit cell system coordinate. If the name is empty quotes, the space group of the currently loaded file will be used. In addition, the symmetry inherent in the file is ignored, and the specified space group is applied. Quotes are required around the space group name. If the space group name itself includes double quotes, use two single quotes or an "escaped double quote" (\") instead. For example: P 32 2" (single quotes here) or P 32 2\", not P 32 2". Generally Jmol reads the Jones-Faithful operators from a file, however if the spacegroup name is specified as "ignoreOperators", Jmol will ignore any explict file-based Jones-Faithful operators and instead create the symmetry based on parsing of the space group symbol in the file (Hermann-Mauguin, Hall, or international table number). If the name is a semicolon-separated list of Jones-Faithful operators, such as "x,y,z;x+1/2,y,z", Jmol will ignore any explict file-based operators and instead create the symmetry based on the list provided. | UNITCELL [a,b,c,alpha,beta, gamma] or
"a=...,b=...,c=...,alpha=...,beta=...,gamma=...." | Specifies the unit cell to use for models in this file. If a unit cell is specified in a file, then this option allows overriding that specification. A 0 for b implies polymer (1D) periodicity (and c is ignored), otheriwse a 0 for c indicated slab (2D) periodicity. When both SPACEGROUP and UNITCELL are provided, Jmol can display molecules found in standard Cartesian coordinate files (XYZ, MOL, PDB) as packed unit cells. The second (string) format, if used, must specify the parameters in the indicated order. | | UNITCELL [ax, ay, az, bx, by, bz, cx, cy, cz] | Specifies the unit cell in terms of the XYZ coordinates for the vectors a, b, and c. If bx = by = bz = 0, then cx, cy, and cz are ignored, and polymer (1D) periodicity is implied; otherwise, if cx = cy = cz = 0, then slab (2D) periodicity is implied. UNITCELL "" uses the unit cell of the currently loaded file. This allows, for example, adding of atoms to a crystal model using fractional coordinates:
set appendNew false
LOAD DATA "append"
1
testing
Na 0.5 0 0.5
end "append" {1 1 1} spacegroup "" unitcell ""
| | UNITCELL "a=...,b=...,c=...,alpha=...,beta=...,gamma=...." | Specifies the unit cell from a string such as "a=10,b=10,c=20,alpha=90,beta=90,gamma=129". |
|
| load |
The load command by itself or with empty quotes reloads the current file.
|
| load keyword "filename" |
An optional keyword, APPEND, DATA, FILES, MENU, MODELS, or TRAJECTORY, may be supplied prior to the quoted filename. Other keywords are ignored. (Jmol does not use the Chime-style keyword to specify "file format". Rather, file format can be forced by prefixing a filename with "xxxx::" where "xxxx" is a Jmol file type. However, this should not be necessary in most cases, since Jmol determines file type by scanning the first lines of a file for file-type-specific content. (In certain cases, where there are extensive comments at the beginning of a file, it is possible for Jmol to fail to discover the file type or to misassign it. In that case, xxxx:: should be used.)
|
| load "filename" (integer) |
Jmol automatically determines file type based upon the contents of the file. Quotes are recommended. Files containing fractional coordinates are displayed with their unit cell visible. load "" reloads the current file. For files containing multiple models, an optional integer after the file name will load only the specified model. If this number is negative, it refers to a specific vibrational mode in files that contain that information . If this number is 0, it refers to the last model in the set . In the case of PDB and mmCIF files, this number refers to the model number specied in the MODEL record or _atom_site.pdbx_PDB_model_num field, respectively.
|
| load "filename" [i j k l m...] |
An additional way to load a specific set of models involes using an array just after the file name, starting with model 1 for the first. The order of models is not significant. Thus, [1 2 3] is the same as [3 2 1] and loads the first three models only. (Note that if you want to display models in a different sequence then they appear in a file, you can do that with the frame command.) In the case of PDB and mmCIF files, these numbers refer to the model number specied in the MODEL record or _atom_site.pdbx_PDB_model_num field, respectively. A comparison of load options using just a model number or an array is given below:
| load "" | loads the first model in a file when not PDB or mmCIF or the model with MODEL 1 record for a PDB file or the model with _atom_site.pdbx_PDB_model_num = 1 for an mmCIF file. | | load "" [1] | same as load "" 1; brackets allow for more than one model. | | load MODELS ({1}) "" | (see load MODELS) always loads the SECOND model in a file, regardless of its indicated model number. |
|
| load "filetype::filename" |
File format can be forced by prefixing a filename with "xxxx::" where "xxxx" is a Jmol file type. This should not be necessary in most cases, since Jmol determines file type by scanning the first lines of a file for file-type-specific content. In certain cases, however, where there are extensive comments at the beginning of a file, or a file type (such as MDCRD) does not have any distinguishing characteristics, it is possible for Jmol to fail to discover the file type or to misassign it. In that case, adding "xxxx::" is necessary.
|
| load "remoteFilename" AS "localFileName" |
Loads a remote file and then also saves it locally. For use with the Jmol application and signed applet only.
|
| load @variableName |
Loads the file with the name specified by variable variableName. You can load a set of files that are defined in an array variable.
|
| load INLINE "fileData" |
Loads the file data given in quotes. Generally this would be a small molecule in JME or XYZ format.
|
| load "@variableName" |
You can load a model from data contained in a variable. This allows modification of the data prior to display, for example. Quotes are necessary, as without them -- load @x -- it is the file name that is expected in variable x, not the file contents. For example: x = load("quartz.cif");load "@x" {2 2 2};reset x. Note that to save memory, it is a good idea to clear the variable using reset x just after loading. An interesting aspect of this option is that it allows data from a remote file to be saved in the state. This means that if you use write state "somefile.spt", then that single state script will contain the full file data in a DATA statement. It will be "transportable" and no additional model file will be required. (See also the PNGJ format for the write command, which is even better.)
|
| load VAR x |
Loads the file data given in variable x; same as load "@x" but in the same syntax as write VAR x.
|
| load *XXXX |
You can load mmCIF files directly from http://www.ebi.ac.uk/pdbe. Simply preface the four-letter PDB id code with "*", and Jmol will load the file. Using load "*?" offers the user a prompt for a PDB id. As for other file laoding, you can adding "AS ." ("as" with a period) you can save that file automatically in the default directory (as xxxx.cif), and using, for example, load *1crn AS "myfile.cif", you can save it to some other local file name. Starting with Jmol 14.4, you can add "/dssr" to the PDB id to also read RNA/DNA secondary structure information from Columbia University, "/rna3d" for RNA secondary structure annotations from http://rna.bgsu.edu/rna3dhub, sequence domain annotations using "/dom", and structure validation annotations using "/val".
|
| load *XXXX* |
Appending a * to a PDBe ID loads a PDBe "updated" CIF file, which allows PDB CONECT-like bond creation. An example of such a file can be found here. This is a suitable replacement for PDB CONECT, integrating information found in _chem_comp_bond and _struct_conn categories. Note that the presence of _chem_comp_bond records in these files will enable processing of _struct_conn as well, regardless of filter "addbonds".
|
| load =XXXX |
You can load PDB files directly from http://www.rcsb.org or another server of your choice. (This depends upon the setting of set loadFormat). Simply preface the four-letter PDB id code with "=", and Jmol will load the file. Using load "=?" offers the user a prompt for a PDB id. Adding "AS ." ("as" with a period) you can save that file automatically in the default directory (as xxxx.pdb.gz), and using, for example, load =1crn AS "myfile.pdb", you can save it to some other local file name. The default is to transfer the file in g-zipped format; If you add ".pdb" to the expression -- load =1crn.pdb, for example -- then Jmol will transfer and save the uncompressed PDB file. Starting with Jmol 14.2, you can add "/dssr" to the PDB id to also read RNA/DNA secondary structure information from Columbia University. Starting with Jmol 14.4, you can load "/rna3d" for RNA secondary structure annotations from http://rna.bgsu.edu/rna3dhub, sequence domain annotations using "/dom", and structure validation annotations using "/val".
|
| load ==XXX |
You can load PDB ligand (chemical component) files directly from http://www.rcsb.org or another server of your choice. (This depends upon the setting of set loadLigandFormat). Simply preface the three-letter PDB id code with "==", and Jmol will load the file. Using load "==?" offers the user a prompt.
|
| load =database/id |
You can load files from a named database. Options (Jmol.4.6) include:
| mp | load =mp/24972 | loads a file from http://www.materialsproject.org | | ligand | load =ligand/hem | RCSB chemical component file | | nci | load =nci/CC | NCI CACTVS Resolver | | pdb | load =pdb/1crn | RCSB pdb files | | iucr | load =iucr/wf5113sup1 | IUCr Acta Cryst B supplemental files | | cod | load =cod/1000002 | Crystallography Open Database | | iucr | load =pdbe/1crn | CIF file from PDBe | | iucr | load =pdbe2/1crn | CIF file from PDBe (alternative) | | aflow | load =aflow/AgAu | AFLOW binary metal alloy file | | magndata | load =magndata/1.1.3 | MAGNDATA magnetic crystal database (Bilbao Crystallographic Server | | ams | load =ams/quartz | American Mineralogist Crystal Structure Database |
|
| load ":chemical name" |
You can load models from PubChem. Preface the compound name with colon. Quotes are only required if nonalphanumeric characters are present in the name.
|
| load $smilesString |
You can load SMILES strings, and Jmol will turn them into 3D models using the NIH Cactus server. As for reading files from any source outside your domain, you will have to use the signed applet or Jmol application to do this. These files can be saved as MOL files using write xxx.mol or load $xxxx AS "myfile.mol", and if the conformation is not to your liking, switching to set modelkitMode or using set picking dragMinimize you can quickly adjust the model to the desired conformation. Quotation marks should be used for names that include the space character: load "$ethyl acetate".
|
| load $identifier |
The service at https://cactus.nci.nih.gov is not limited to SMILES strings. The database includes several million known compounds, which are accessible by CAS registry number, InChI codes, and chemical name as well. For example, load $57-88-5 loads a model of chlolesterol, and load $taxol as "taxol.mol" loads a model of taxol and saves it on your hard drive. This service taps into the OPSIN service of Cambridge University to return structures from IUPAC or IUPAC-like names.
|
| load $? |
Loads structure from NCI/CADD with prompt.
|
| load ==? |
Loads chemical component from RCSB with prompt.
|
| load =? |
Loads PDB ID from RCSB with prompt.
|
| load *? |
Loads PDB ID from EBI with prompt.
|
| load :? |
Loads structure from pubChem with prompt.
|
| load $ |
Using just LOAD $ will load the current structure from NCI/CADD by passing a SMILES string to that service. The NCI/CADD service will create 3D models directly from SMILES using CORINA, if necessary. Using load "$?" offers the user a prompt.
|
| load : |
Using just LOAD : will load the current structure from PubChem by passing a SMILES string to that service. Note that PubChem, unlike NCI/CADD, will only deliver models that have been deposited in its database. Using load ":?" offers the user a prompt.
|
| load chebi/nnnnnn |
chEBI 2D molecule load, with minimal 100-step minimization.
|
| load .. CENTROID |
Use for molecular crystal structures and loads one or more unit cells (as specified by {nx ny nz})
exploring covalent bonding so that molecules that have their centroid (center of geometry) within the specified block of cells are built. For example:
load =cod/1001253 {1 1 1} centroid
Note that {1 1 1} here is unnecessary, as it is the default.
|
| load .. SPACEGROUP "Hall:P 2y" |
Allows prefix "Hall:" to specify Hall notation along with SPACEGROOUP 3 or SPACEGROUP "10:b". Allows for experimentation with different space groups.
|
| load SPACEGROUP 213 UNITCELL [5 5 5 90 90 90] |
Creates an empty structure with the designated space group and unit cell; User is expected to match the correct type of unit cell to the given space group.
|
| load ORIENTATION |
The ORIENTATION keyword specifies that after the file is loaded, the orientation should be returned to its original value. This orientation can be restored later using restore orientation PRELOAD.
|
| load SMILES "smilesString" |
An alternative to the $ syntax for loading SMILES strings.
|
| load "filename" FILL .. |
The FILL option, described more fully under Crystallographic Options, allows filling an arbitrary space with a set of atoms from a crystallographic file. When the file has no unit cell, this option simply loads the file with the specified boundbox.
|
| load "filename" FILTER "filter specification" |
For individual file types, it is possible to filter the data in the file as it is loaded. The FILTER keyword followed by a quoted string allows for this. The FILTER keyword must be the last keyword in the LOAD command. Specific filters include:
| General file types | | all | FILTER "NAME=..." | loads only those models with a name that contains a specified set of characters. | | all | FILTER "CENTER" | centers all models in a file based on the first model"s position. | | all | FILTER "REVERSEMODELS" | delivers the models in reverse order . Useful for intrinsic reaction coordinate (IRC) animations. | | 2D data | FILTER "NOH" or FILTER "noHydrogen" | For 2D structures (MOL, V3000, CDX, CDXML, JME), loads the structure as is, without adding H or converting to 3D. This may be useful for automated processes that simply need to create SMILES or InChI but not actually display any structure. | | 2D data | FILTER "NOMIN" | For 2D structures (MOL, V3000, CDX, CDXML, JME), loads the structure with added hydrogens but without converting to 3D. Atoms may be adjusted in preparation for minimization, but no minimization is carried out. | | many | FILTER "NOVIB" | skips the reading of vibrations for any file that contains them. | | Small molecule file types | | CDX, CDXML | FILTER "NO3D" | Some CDX and CDXML files contain both 2D and 3D coordinates. The default for Jmol is to read the 3D coordinates if they are present. This is not generally advisable, however, as they can be quite odd, particularly if abbreviations such as Ph or t-Bu have been used. This setting forces any 3D coordinates in the file to be ignored, loading the model in 2D followed by conversion to 3D in Jmol. The combination filter "no3d noH nomin" will display the CDX or CDXML file as it would be drawn, using only the 2D coordinates, adding no hydrogen atoms, and doing no minimization. | | MOL | FILTER "2D" | indicates to consider the file a 2D file and to apply a automatic hydrogen addition and 2D-to-3D conversion immediately upon loading. "2D-noMIN" does the hydrogen addition but no minimization. | | MOL | FILTER “no 3D” | Loads a 2D model with no conversion to 3D, particularly for V3000 and ChemDraw; no effect for standard 3D models. | | MOL | FILTER “noHydrogen”(Or just “NOH”) | Loads a 2D model with no additional hydrogens and no minimization; allows for SMILES and InChI creation directly from the 2D model. | | Biomolecular file types | | PDB, mmCIF, MMTF, binCIF | FILTER "ALLHET" | By itself, does nothing, but in conjunction with any other atom filter, such as /=2 or *.CA passes any HETATM regardless of that atom filter. | | mmCIF | FILTER "ADDBONDS" | One of the deficiencies of of the mmCIF format as originally defined is that it does not reproduce the CONECT records of PDB files. The ADDBONDS filter instructs Jmol to process mmCIF_struct_conn records. These records are similar to PDB CONECT records, but they indicate only inter-group connections, connecting one group with another. Types included by Jmol include covale, covale_base, covale_phosphate, covale_sugar, disulf, and metalc. Ignored types include hydrog, mismat, modres, and saltbr. This filter is not necessary when reading updated CIF files from PDBe (See *xxxx*, above). | | mmCIF, PDB, MMTF | FILTER "ADDHYDROGENS" | Add hydrogens regardless of the setting of pdbAddHydrogens. | | mmCIF, PDB, MMTF | FILTER "ASSEMBLY n" | loads a specific CIF assembly. (Same as BIOMOLECULE.) For example, load =1vif.cif filter "ASSEMBLY 1". Specific label_asym_id can be selected as well: load =1vif.cif filter "ASSEMBLY 1;$A" (just label_asym_id A); load =1vif.cif filter "ASSEMBLY 1;!$C" (just label_asym_id values not C). | | mmCIF, PDB, MMTF | FILTER "ATOM" | selects only ATOM records (see also FILTER "HETATM") | | mmCIF, PDB, MMTF | FILTER "BIOMOLECULE n" | where n is a number > 0 indicating which biomolecule to load. In addition, #<n or any number of # n or !#n can be indicated in order to load just a specific subset of biomolecular transformations related to the specified biomolecule. Adding "NOSYMMETRY" along with BIOMOLECULE, indicates that the symmetry transformations in the REMARK 350 BIOMT records should be ignored. See also the BMCHAINS filter option. | | mmCIF, PDB, MMTF | FILTER "BMCHAINS=mode" | Rename chains when applying symmetry operations so that they have distinct names. "BMCHAINS=0" appends the symmetry operation number (2,3,...) to chain identifiers of all generated atoms, so {A B A B A B} mitght become {A B A2 B2 A3 B3}. "BMCHAINS=1" extends the single-character alphabetization, so {A B A B A B} might become {A B C D E F}. | | mmCIF, PDB, MMTF | FILTER "BYCHAIN" | designed for extremely large high-symmetry biological assemblies, this filter loads a file in a coarse-grained fashion, assigning one pseudoatom per chain. The size of this atom can be made larger than the atom-size maximum of 16 Angstroms using set particleRadius with a larger value and then setting spacefill 30 (or any number greater than 16). Normally accompanied by BIOMOLECULE or ASSEMBLY, for example: load =3j3q.cif filter "ASSEMBLY 1;BYCHAIN". | | mmCIF, PDB, MMTF | FILTER "BYSYMOP" | similar to BYCHAIN, but one pseudoatom per symmetry operation. For example: load =1m4x.cif filter "ASSEMBLY 1;BYSYMOP". | | mmCIF, PDB, MMTF | FILTER "HETATM" | selects only HETATM records (see also FILTER "ATOM") | | mmCIF, PDB, MMTF, GROMACS, MDTOP | FILTER "[XXX], .XXX, :X, %X" | to specify inclusion or exclusion of specific residue types, atom types, chains, or alternative locations. The prefix "!" indicates NOT. Within each of these four sets, multiple selections are treated as "OR" without "!" and "AND" when "!" is present. With % (alternative location), atoms with no alternative location marking are ALWAYS loaded regardless of this filter. For example, load "1sva.pdb" filter "*.CA,%B" loads only alpha carbons that correspond to the conformation involving alternative location B; filter "![HOH]" filters out water molecules. | | PDB | FILTER "CONF n" | Loads only a specific configuration based on alternative locations. "CONF 1" loads only atoms in the first configuration -- usually %A and % ("undesignated") | | PDB | FILTER "TYPE i,n" | loads customized column data into the atomType property of the atoms. The two numeric parameters are 1-based column number and number of columns. For example: load xxx.pdb filter "TYPE 73,4". | | PDB | FILTER "TYPE i,n=XXX" | loads customized column data into the atomType property of the atoms, selecting only those atoms starting with the specified characters in the specified field. | | P2N | FILTER "ALTNAME" | Use the altName field of the P2N file for atom names. | | PYMOL | FILTER "DOCACHE" | caches surface data, creating a JVXL equivalent, specifically useful for JSmol. When using the "doCACHE" option (in the Jmol Java application), file loading should be followed immediately with WRITE PNGJ "xxx.PNG". The PNGJ file can then be loaded much more efficiently than the PSE file on a web page using JSmol/HTML5. | | PYMOL | FILTER "NOSURFACE" | load a PyMOL file without surface creation, which can be slow. | | PyMOL | FILTER "ShowValence" | May be needed for PyMOL files that have not been saved with valence setting ON in order to show multiple bonds in Jmol. Note that the PyMOL valence_mode setting is NOT implemented in Jmol. | | Crystallographic file types | | CIF, various | FILTER "CELL=abc;offset" | specifies a specific cell in relation to the unit cell given in the file using MCIF parent/standard cell notation. For example, filter "CELL=a/2,2b,c;0,0,1/2" (see unitcell). | | CIF, various | FILTER "LATTICESCALING=1.2" | Scales the model based on a crystal lattice expansion factor, allowing direct comparison of related structures with slightly different lattice scalings. | | CIF, various | FILTER "POLYMERX" | Loads a crystal structure as a linear polymer, packing only in the X direction. Compatible only with P1 symmetry. For example: load =ams/quartz 1 packed;load inline @{write("CIFP1")} {3 1 1} filter "POLYMERXY" | | CIF, various | FILTER "Precision=n" and FILTER "lowPrecision" | "PRECISION=n" where n is up to 16 digits specifies the precision to use for a given file, possibly lowering the precision from what is in the file. For example, AFLOWLIB files tend to have their precision hidden by padding with zeros:U1 U 4 a 0.00000 0.00000 0.00000 1.00000 B1 B 48 i 0.50000 0.66600 0.66600 1.00000 This could cause trouble with some edge cases or when determining Wyckoff positions. One could prevent the problem using filter "PRECISION=3" in this case, explicitly ignoring the padding and turning "0.666" into "0.66666667". Using filter "lowPrecision", one can set the precision to 4 (+/-0.0001) for fractional coordinates. This filter specifies that crystal structure readers should not attempt to raise the precision to single- or double-precision even if the file contains double-precision data. It also sets PACKED 0.0001 rather than the standard default value of 0.02 (which tends to allow too many atoms to be included) in some cases. | | CIF, various | FILTER “SLABXY” or “POLYMERX” | Loads a crystal structure as a slab (SLABXXY) or polymer (POLYMERX). Packs only in the periodic direction (xy or x). This option is compatible only with P1 symmetry. For example:
load =ams/quartz 1 packed
x = write("CIFP1")
load INLINE @x {3 3 1} filter "SLABXY"
| | CIF, various | FILTER "SYMOP=n" | loads just the atoms that are the result of the nth symmetry operator. | | CIF | FILTER "MOLECULAR" | instructs Jmol to attempt to complete molecules using either the bonding information in the CIF file or standard van der Waals radii. If this filter is not present and no lattice is indicated either, if bonding information is present in the file, Jmol will use that information to automatically complete molecules. | | CIF | FILTER "NOIDEAL" | for mmCIF chemical composition files (for example, load ==HEM) uses the _chem_comp_atom.pdbx_model_Cartn_x set of coordinates rather than the default _chem_comp_atom.pdbx_model_Cartn_x_ideal set | | CIF | FILTER "NOWYCKOFF" | Skip reading atom_site_wyckoff_label, allowing Jmol to calculate these positions itself. (For Jmol development testing purposes, primarily). | | CIF | filter "StopOnSHELXHKL" | Improves load time by stopping reading when a _shelx_hkl_file tag is found. This filter should not be used with multiple structures. Prior to Jmol 16.2.19, this filter was effectively set, but that causes problems for multiple-structure CIF files. | | CIF, JANA2006 | FILTER "NOSYM" | do not apply symmetry | | mCIF | FILTER "CELL=parent" | loads and packs the parent cell, if designated in the file. If packing is not desired, use "nopackcell" instead of "cell". | | mCIF | FILTER "cell=standard" | loads and packs the standard cell, if designated in the file. If packing is not desired, use "nopackcell" instead of "cell". | | msCIF, JANA2006 | FILTER "MODAVERAGE" | do not read modulation | | msCIF, JANA2006 | FILTER "MODAXES=xyz" | read modulation only along specific axes -- x, y, and/or z | | msCIF, JANA2006 | FILTER "MODCELL=n" | use subsystem n for initially created unit cell, generating the command unitcell {%1} for instance upon file loading. | | msCIF, JANA2006 | FILTER "MODNOPACK" | do not pack subsystem cells | | msCIF, JANA2006 | FILTER "MODT=t" | set initial (zero-point) modulation to t, where t can be a decimal number or a fraction such as 1/3. | | msCIF, JANA2006 | FILTER "MODTUV=t,u,v" | set initial (zero-point) modulations for up to three cell wave vectors, where t,u,v can be decimal numbers or fractions such as 1/3. | | BCS | FILTER "NONORM" | reads displacement data from BCS files (particularly in relation to AMPLIMODES files) without normalization, allowing comparison of displacement magnitudes between different models. | | CGD | FILTER "NOBONDSYM" | Do not apply symmetry operators to bonds -- just create the ones present in the file. | | CGD | FILTER "NOPACK" | Do not pack cell (default for this type is to pack the cell). | | topoCIF | FILTER "TOPOL"
FILTER "TOPOLNET" | For topological CIF files, reads the net from the _topol_* data blocks. Displays net 1 by default. load "xxx" {1 1 1} filter "TOPOL" will do the same, constructing the {1 1 1} unit cell, with symmetry. Also works with fill or packed. Displays net 1 by default. load "xxx" {1 1 1} filter "TOPOLNet=2" displays net.id=2; load "xxx" {1 1 1} filter "TOPOLNet=Net_2" displays net.name="Net_2". Additional filters include filter "topos_type=x" where x is v, vw, hb, or some concatenation of those using "+", and filter "topos_ignore", which skips reading of _topol records, reading as a standard CIF file. | | Quantum computing file types | | many | FILTER "NOMO" | skips the reading of molecular orbitals for any file that contains them. | | CASTEP | FILTER "Q=..." | for .phonon files, filter "q=n" loads the nth q-point frequency modes. "q=all" reads all phonon modes. For files with multiple extrapolations to q=0, "q=0.1", "q=0.2", etc... loads a specific extrapolation. Q-points can also be specified in terms of fractions, "q=(1/2 1/2 1/2)", or decimals, "q=(0.333 0.111 0.333)". If no filter is specified, but the SUPERCELL keyword is used, Jmol will attempt to find the appropriate matching q-point data for that supercell. | | CRYSTAL | FILTER "CONV" | load conventional, not primitive cells. | | CRYSTAL | FILTER "INPUT" | load input coordinates only. | | CSF, SPARTAN | FILTER "NOORIENT" | prevents application of the rotation matrix found in the file as the default rotation. | | GAMESS, GAUSSIAN, GenNBO, Jaguar, Molden, NWChem, PSI, and QCHEM | FILTER "xxx" | where "xxx" is a word on the line Jmol uses to identify a molecular orbital. This allows selective loading of specific types of molecular orbitals -- such as "alpha", "beta", or "NBO" -- for any of these file types, "POPULATION" or "EDMISTON" or "PIPEK" for GAMESS. ("NBO" refers to orbitals generated with the NBO 5.0 option AONBO=P; "EIGEN" or "!NBO" will skip loading of these orbitals.) | | GAMESS, Gaussian, QChem, NWChem | FILTER "NBOCHARGES" | specifies to use atomic partial charges from the NBO calculation. Note that this flag is independent of the NBO filter option. To use both, separate them with a comma: load "myfile.out" filter "NBO,nboCharges". | | GAMESS (US) | CHARGE=LOW | indicates to load Lowden charges rather than Mulliken charges. | | Gaussian | FILTER "ORIENTATION:..." | Orientation filters returning the specified orientation, one of filter "orientation:input" (includes Z-Matrix), filter "orientation:standard", filter "orientation:all". Note that vibrations are only returned if orientation is ALL or STANDARD. | | Molden | FILTER "NOSORT" | Do not sort MOs by energy. | | Molden | FILTER "OPTONLY" | Load optimized structure only. | | Molden | FILTER "SYM=xxx" | Load only molecular orbitals for which the Sym= line in the [MO] block contains the text "xx". | | Molden | FILTER "VIBONLY" | Load vibrations only, not the base geometry. | | SPARTAN | FILTER "MULLIKEN" | loads Mulliken charges rather than the default ESP charges. (ESP charges are better for displaying molecular electrostatic potential maps using isosourface molecular map MEP.) |
|
Examples: |
See examples-11/sym.htm
|
See also:
|
[Jmol Precision] [Jmol and Symmetry] [Jmol/JSpecView/MagresView] cache define initialize set (files and scripts) zap undefined |
top search index |
|
Adding FILES to the load command indicates that a set of files are to be loaded . Filenames must be quoted. Each model encountered is put into a new "frame." No additional parameters other than COORD are allowed (see below).
|
| load FILES "filename1" =+ "filename2" |
If a + is used between file names, Jmol will load the files as a single stream based on the first file's type. This can be useful when part of the required information for the file loading is in a second file. For example, if a PDB file and its associated DSSR data are in two files, one can use load files "xxx.pdb"+"xxx.dssr" to load the structure and process the DSSR data. (One can also use load =1crn/dssr do accomplish this particular task if the PDB and DSSR files are not available locally.)
|
top search index |
|
See structure.htm
|
A mesh ribbon is similar to a strand, but is more the quality of a loosely woven fabric.
|
| meshribbon ON/OFF{default: ON} |
| meshribbon ONLY |
Turns meshribbon rendering on and all other rendering (including labels) off.
|
| meshribbon [mesh-ribbon-radius] |
A negative number also implies ONLY.
|
|
Examples: |
See structure.htm
|
See also:
|
backbone background cartoon dots ellipsoid geoSurface ribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill strand trace vector wireframe undefined |
top search index |
|
Minimizes the structure using the MMFF94 force field (T. A. Halgren, J. Comp. Chem. 5 & 6, 616-641 (1996) or an adapted UFF force field (Rappe, A. K., et. al.; J. Am. Chem. Soc. (1992) 114(25) p. 10024-10035). The default force field is MMFF94, but the UFF force field will automatically be used if atoms are not fo types recognized by MMFF94 or if set forceField "UFF" is issued. enerally the minimization runs in its own thread. If it is desired to wait until the process has completed prior to continuing, use set useMinimizationThread false. You can retrieve a detailed report of the minimization energy using the "high debug" setting and then either show minimization or x = script("show minimization");print x:
set loglevel 6
minimize steps 0
x = script("show minimization")
set debug off
print x
Minimization always runs on the currently displayed frame or set of frames. Generally, this allows selective minimization of the currently displayed model. If sequential minimization of multiple models independently is desired, one can do this two ways:
(1) Issue a frame command to call up the desired model, then issue MINIMIZE;
(2) Make visible all models using FRAME *, and then selectively minimize just the models you want to minimize.
The following two scripts minimize all models in a collection sequentially and independently:
set useMinimizationThread false
var n = {*}.model.max
for (var i = 1; i <= n; i++) {
frame @i
minimize
}
set useMinimizationThread false
var n = {*}.model.max
frame *
for (var i = 1; i <= n; i++) {
minimize {model=i}
}
Note that in either case we must use set useMinimizationThread FALSE because we are doing sequential minimizations within a script.
|
| minimize |
Carries out a minimization using the default convergence criterion specified by set minimizationCriterion or until the maximum number of steps specified by set minimizationSteps is reached. If set minimizationRefresh is TRUE, then the model refreshes after each minimization step, producing a sort of animated minimization.
|
| minimize [atom-expression] |
Carries out a minimization using the specified atom set and assumes the SELECT and ONLY options, thus ignoring all other atoms. Bonds to atoms connected to this set are ignored and may lengthen or shorten during the minimization.
|
| minimize ADDHYDROGENS |
First adds hydrogen atoms, then minimizes the structure.
|
| minimize CANCEL |
Stops a running minimization.
|
| minimize CLEAR |
Stops a running minimization and clears all constraints
|
| minimize CONSTRAINT CLEAR |
Clears any current constraints.
|
| minimize CONSTRAINT (two to four atom expressions) (decimal) |
Constrains the distance, angle, or dihedral angle invoving two to four atoms. If a given atom expression involves more than one atom, only the first atom in the set is made part of the constraint.
|
| minimize CRITERION |
Overrides the setting of minimizationCriterion for this minimization.
|
| minimize ENERGY |
Do no minimization -- just calculate the energy
|
| minimize FIX [atom-expression] |
Specifies a set of atoms to remain in fixed positions during this minimization and future minimizations (if additional parameters are present) or only in future minimizations (if not). Use minimize fix NONE to clear this setting.
|
| minimize GROUP [atom-expression] |
Carries out a minimization using the specified group of atoms, fixing all other atoms. The positions of any atoms in the group that are bonded to atoms outside this set are also fixed, such that bonds only within the group are changed. Note that the UFF forcefield will likely be used, because the resulting subgroup of atoms may be only a fragment of a molecule. For example
load :caffeine
minimize GROUP {within(smarts, "[C][H]")}
|
| minimize ONLY [atom-expression] |
Minimizes a set of atoms ignoring all other atoms. Useful if minimizing a small molecule near a surface, for example, without having it drift away from the surface due to VDW repulsion. If a molecular fragment, UFF force field will be used. Default option for MINIMIZE {atoms} - for example:
load $caffeine
minimize ONLY {within(smarts, "C=O")}
# the C=O groups will be moved around as though
# they were not connected to the rest of the molecule
minimize ONLY {water} // atoms are minimized independently of any other atoms
minimize GROUP {water} // same as {water} but connected bonds are not changed
minimize SELECT {water} // atoms are minimized, but forces of nearby atoms are included
minimize {water} // same as minimize ONLY {water}
|
| minimize SELECT [atom-expression] |
Minimizes a set of atoms within the context of atoms around those atoms. The surrounding atoms will not be moved, but the forces they apply to the selected atoms will be part of the calculation. Any previous or additional setting of FIX is respected. If FIX is not explicitly given, the specified atoms are minimized by fixing all other atoms in the molecule and then internally setting the set of atoms to minimize to be ALL. In this example the water molecule is moved away from the acetone molecule during minimization. The acetone molecule will not be moved.
load :water
set appendnew false
load append :acetone
minimize SELECT {water}
|
| minimize SELECT [atom-expression] ONLY |
Minimizes only the specified atom set, specifically ignoring all other atoms, even if they are connected to the selected atoms. Note that the UFF forcefield will likely be used, because the atom set may be only a fragment of a molecule.
|
| minimize STEPS (integer) |
Overrides the setting of minimizationSteps for this calculation.
|
| minimize STOP |
Same as CANCEL.
|
|
top search index |
|
The MODELKIT command (introduced in Jmol 14.32.2) allows scripted access to the Jmol ModelKit without using set modelkitMode. modelkit ASSIGN and modelkit CONNECT can be used to build or change a any model. modelkit MUTATE modifies the residue structure of proteins and alllows the construction of simple peptides with defined secondary structure. Modelkit options can be set using modelkit SET followed by a modelkit configuration option. Many new options were added in Jmol 15 and 16, particularly in relation to space groups and symmetry. These options add, move, and connect atoms along with their symmetry-equivalent counterparts. In addition, the MODELKIT SPACEGROUP option allows switching among space groups and space group settings.
|
| modelkit ON/OFF |
MODELKIT ON/OFF displays/hides the modelkit menu in the top-left edge of the viewing rectangle.
|
| modelkit ADD {xxx} PACKED |
Packs the unit cell just for the specified subset of atoms.
|
| modelkit ADD @1 PACKED |
Complete the set of atoms in a unit cell, possibly changing element.
|
| modelkit ADD @1 "N" PACKED |
Complete the set of atoms in a unit cell, possibly changing element; will not change space group.
|
| modelkit ADD element fractionalPoint PACKED |
Adds a new atom at the specified position; complete the set of atoms in a unit cell; will not change space group.
|
| modelkit ADD element [array of points] |
Efficient adding of many points of the same type. For example:
load =ams/quartz 1 packed
polyhedra unitcell {_Si}
pts = {_Si}.polyhedra.all.select("(vertices)").join()
ModelKit ADD N @pts
|
| modelkit ADD @1 "Cl" {default: 1/2 1/3 1/3} PACKED |
Adds a new atom at the specified position and connects it to @1; Complete the set of atoms in a unit cell; will not change space group
|
| modelkit ADD @2 [PACKED] |
Completes the equivalent positions for an atom in a crystal; will add only as many atoms as necessary; updates {thismodel}.site values; optionally packs the unit cell.
|
| modelkit ADD @2 [PACKED] |
Completes the equivalent positions for an atom in a crystal; will add only as many atoms as necessary; transforms all specified atom sites to this element; updates {thismodel}.atomName values ("O2" becomes "C2", for instance); updates {thismodel}.site values; optionally packs the unit cell.
|
| modelkit ADD element WYCKOFF |
Adds an atom of the given element at the specified WYCKOFF position.
|
| modelkit ASSIGN ATOM [symbol|pl|mi] point |
For example: Modelkit ASSIGN ATOM "C" {3 3 3} adds a carbon at {3 3 3} but does not bond anything to it.
|
| modelkit ASSIGN ATOM @1 [symbol|pl|mi] point |
For example: Modelkit ASSIGN ATOM @3 "C" changes atom 3 to carbon, with concomitant bond distance change and addition of H.
|
| modelkit ASSIGN ATOM @1 [symbol|pl|mi] |
For example: Modelkit ASSIGN ATOM @25 "O" {3 4.2 3} adds an O atom connected to @25 and at the default distance on the line between @25 and {3 4.2 3}
|
| modelkit ASSIGN BOND {atom1 atom2} type |
Where type can be 0,1,2,3,4,5,p,m; p indicates +, increment (cycles 1 2 3 1); m indicates -, decrement (stops at 0) with associated changes in hydrogen count.
|
| modelkit ASSIGN BOND @1 @2 type |
Where type can be 0,1,2,3,4,5,p,m; p indicates +, increment (cycles 1 2 3 1); m indicates -, decrement (stops at 0) with associated changes in hydrogen count.
|
| modelkit ASSIGN BOND (integer) type |
Assigns a type to a bond for which the bond index is known
|
| modelkit ASSIGN ATOM {atom} "element" |
Assign an atom a new element.
|
| modelkit CONNECT {atom} {atom} |
Connects two atoms and all of their equivalent atoms in the same way.
|
| modelkit DELETE {atoms} |
Deletes all symmetry-equivalent atoms (all atoms with the same .site value as any atoms in this set);
use x = {atoms}.find("equivalentAtoms").length to check how many atoms this will be
|
| modelkit DRAW SPACEGROUP [name or number] PACKED |
Clears the model with ZAP, then draws the full set of symmetry elements for the space group. Optionally (with PACKED) adds a blue (nitrogen) atom in a default general position, along with all of its symmetry-equivalent atoms. Essentially a shortcut for
zap;
modelkit spacegroup "P 21/c" ;
draw spacegroup ALL;
modelkit add N;
coding examples:
function showAllSpaceGroups() {
for (var i = 1; i <= 230; i++) {
modelkit draw spacegroup @i packed;
set echo top right;
echo @i;
refresh;
}
}
showAllSpaceGroups; // note that some cubics take quite a bit of time
function makeSpaceGroupMovie() {
zap;
background white;
capture "spaceGroupMovie.gif";
for (var i = 1; i <= 230; i++) {
modelkit draw spacegroup @i packed;
set echo top right;
echo @i;
refresh;
}
capture end;
}
makeSpaceGroupMovie()
|
| modelkit FIXED VECTOR point1 point2 |
Constrains atom dragging to a given vector; atom will still not move if symmetry does not allow it; replaces any fixed plane; cleared by changing the value of set modelKitMode.
|
| modelkit FIXED PLANE plane |
Constrains atom dragging to a given plane; atom will still not move if symmetry does not allow it; replaces any fixed vector; cleared by changing the value of set modelKitMode.
|
| modelkit FIXED NONE |
Removes the atom dragging constraint
|
| modelkit MINIMIZE |
For crystal structures in the current model only; does not need anything more than the asymmetric unit atoms; carries out a minimization on the asymmetric unit within a 27-cell block {444 666 1} applies that minimization to all atoms in the current model temporarily creates a new CIF model, minimizes it, then deletes it can accept a limited number of additional parameters such as SILENT.
|
| modelkit MOVETO @atoms @points |
Bulk conversion of a set of atom positions, applying symmetry similar to MODELKIT MOVETO @atom @xyz, but for a set of atoms. Atoms may be just the asymmetric unit. Points is a set of points, same length as atoms.
|
| modelkit MOVETO @1 {default: 1/2 0 0} |
Moves the atom only if its invariant symmetry (Wyckoff position) is unchanged (that is, doesn't create or destroy atoms)
|
| modelkit MUTATE |
Same as MUTATE, but associated (and documented) with ModelKit.
|
| modelkit MUTATE (integer) options |
Mutate a specific protein residues. See the mutate command for details.
|
| modelkit MUTATE CREATE options |
Create a peptide with a specified sequence and secondary structure motif (various alpha-, beta-, and turn-forms) based on phi/psi angles. See the mutate command for details.
|
| modelkit PACKED |
Packs the current unit cell
|
| modelkit SET addHydrogens TRUE/FALSE |
Setting addHydrogens FALSE turns off the automatic addition of hydrogens during MODELKIT operations
|
| modelkit SET autoBond TRUE |
When dragging to create a new bond to a new atom, automatically check vicinity of the new atom for bonding. Default set to false.
|
| modelkit SET clickToSetElement FALSE/TRUE |
Setting clickToSetElement TRUE removes the ability to change elements other than H by clicking on them
|
| modelkit SET elementKey ON/OFF |
Adds or removes an element key as per SET ELEMENTKEY ON/OFF, but for the CURRENT model only. This setting is indirectly saved in the state in the form of its the associated DRAW objects. The key does NOT persist through ZAP, as that clears alll DRAW objects.
|
| modelkit SET hidden TRUE |
Hides the ModelKit menu but retains the picking and hover highlights.
|
| modelkit MUTATE {residues} options |
Mutate one or more protein residues. See the mutate command for details.
|
| modelkit SET showSymOpInfo TRUE/FALSE |
Setting showSymOpInfo FALSE stops the ModelKit from showing space group symmetry information
|
| modelkit SPACEGROUP 123 |
Allows setting of the space group after loading and accepts any name of a space group accepted by the spacegroup() function or a number from 1 to 230. Note that some space group names have extensions: "6:a", "6:b", "6:c". If these are given simply as "6" or the number 6, then one of these options will be used. Will not set the space group if the current unit cell is not appropriate for the given space group. Can accept semicolon-separated Jones-Faithful operation listing: "x,y,z;-x,-y,-z" which can be obtained for any space group by: x = spaceGroup(123).spaceGroupInfo.operationsXYZ.join(";") or for the current space group by x = _M.symmetryOperations.join(";"). Using operation lists is recommended over using names, as this covers all possible space groups and avoids any ambiguity in settings.
|
| modelkit SPACEGROUP "123" PACKED |
Also packs the unit cell after assigning the space group. Note that the PACKED option can be used with any MODELKIT SPACEGROUP option.
|
| modelkit SPACEGROUP n.m |
This option allows switching to different ITA space groups and settings using the ITA space group number and a 1-based setting index, such as "15.2" (A 2/n, as indicated in ita_settings.tab and by print spacegroup("15").its[2].hm). The index Jmol will automatically adjust unit cell if necessary; should be used after ZAP or LOAD
for example:, the following script opens an example AFLOW Encyclopedia of Crystallographic Prototypes, then switches to one of the available settings for its space group, packing the new unit cell and displaying all symmetry operations. Finally, the script does some clean up and goes to the standard ITA "c1" axis view (looing toward 0 along c axis in the top left corner).
function test(n,i) {
if (!i) {
load @{"=aflowlib/" + n} + " packed";
center unitcell;
print "nSettings=" + spacegroup("ITA/" + n).n;
test(n,1);
} else {
draw delete;
modelkit spacegroup @{"" + n + "."+i} packed;
draw ID @{"sg"+i} spacegroup all;
center visible;
axes 0.1;
connect auto;
moveto axis c1;
}
}
test(23)
|
| modelkit SPACEGROUP <CLEG expression> |
Uses CLEG notation to transform from the current crystallographic group setting (n) to a subgroup setting m. "n" here is optional, as is "sub". Thus, MODELKIT SPACEGROUP ">>3" calculates and carries out the transformation needed to convert the current space group setting and unit cell to P2. The subgroup need not be maximal, as Jmol can search the ITA subgroup tree for any space group setting. If more than one transformation is found, the first-found is chosen. Typically, this will be a translationengleichen (translation-preserving) transformation, in which case the unit cell volume will not be changed. However, in some cases the unit cell will be enlarged or reduced. If there is no structure or no current space group, the command will create the initial space group with a default unit cell and transform it.
CLEG notation allows for a wide variety of descriptions of settings, as shown in the table below.
| notation | meaning
| | 15:a,b,c;0,0,0 | the standard setting for space group 23, C 2c
| | 15:a,b,c | short-hand for 15:a,b,c;0,0,0
| | 15 | short-hand for 15:a,b,c
| | 15:a,b,c;1,0,0 | the standard setting for space group 15, but shifted one lattice position along the current a axis.
| | 15:b,c,a | the spacegroup setting B 2b 1 1
| | P222 | Hermann-Mauguin names can be used for common settings, however they may not be followed by a setting such as b,c,a, as they already specify a setting.
| | 12.3 | a Jmol extension of CLEG notation specifying the third setting of space group 12 as listed at the Bilbao Crystallographic Server and in the Jmol CLEG table
| | 20>>4 | carry out the transform from the default setting of space group 20 to the default setting of its subgroup space group 4
| | >>4 | carry out the transform from the current space group setting to the default setting of its (presumed!) subgroup space group 4
| | C 2 2 21 >> P 21 21 2 >> P1 21 1 | a detailed pathway from a group to one of its subgroups. Same as 20 > b,c,a;1/4,0,0 > 18 > c,a,b;1/4,0,0 > 4
|
function showSubgroup(i1, i2) {
if (!i2) {
print spacegroup(i1,"subgroups");
return;
}
save orientation o1;
zap;
modelkit spacegroup @i1;
restore orientation o1;
center unitcell;
draw uc1 unitcell color red;
draw sg1 spacegroup all;
modelkit add P wyckoff "G";
modelkit spacegroup @{"" + i1 + ">sub>" + i2} packed;
color property site;
draw uc2 unitcell color yellow;
draw sg2 spacegroup all;
delay 2;
for (var i = 0; i < 10; i++) {
delay 1;
draw sg1* on;
draw sg2* off;
delay 1;
draw sg1* off;
draw sg2* on;
}
draw sg1* on;
draw sg2* on;
}
showSubgroup 107
showSubgroup 107 42
|
| modelkit SPACEGROUP "HALL:xx xx xx" |
Creates a space group from a Hall or extended Hall description;see Space-group notation with an explicit origin, S. R. Hall, Acta Cryst. (1981). A37, 517-525
|
| modelkit SPACEGROUP "x,y,z;x,-y,z;..." |
Allows creating a space group from a full operation list
|
| modelkit SPACEGROUP UNITCELL [PACKED] |
After ZAP, creates a new space group with the given unit cell; Optionally packing it, if not after ZAP; if the unit cell is incompatible with the space group, a similar compatible cell is used. The UNITCELL option can optionally be followed with the PACKED option. However, note that just after ZAP there are no atoms to pack.
|
| modelkit SPACEGROUP UNITCELL [a b c alpha beta gamma] |
After ZAP, creates a new space group with the given unit cell; Optionally packing it, if not after ZAP; if the unit cell is incompatible with the space group, a similar compatible cell is used.
|
| modelkit UNITCELL [unitcell description] [PACKED] |
Same as the UNITCELL command, but also adjusts atom coordinates to retain same fractional positions. Equivalent to the following script:
var fxyz = {thismodel}.fxyz.all;
unitcell ....
{thismodel}.fxyz = fxyz;
|
| modelkit UNDO/REDO |
A separate undo/redo stack specifically for the ModelKit that undoes or redoes a ModelKit action. Can be disabled by SET PRESERVESTATE FALSE.
|
| modelkit VIBRATION WYCKOFF ON/OFF{default: ON} |
Atoms rattle in their Wyckoff position, but it is just for visual fun, and not an actual vibration.
|
| modelkit ZAP SPACEGROUP option |
Same as zap;modelkit spacegroup. Just a convenience option.
|
top search index |
|
The MODULATION command, introduced in Jmol 14.0, allows visualization of incommensurately modulated strutures that have been read from msCIF or JANA2006 files. An (nonrealistic) dynamic phased animation of the structure can be activated using vibration ON, with the magnitude of the oscillations governed by set modulationScale. Note that incommensurately modulated structures are never actually oscillating in such a way; different t values actually correspond to different physical unit cell positions in the crystal. This animation only serves as a visualization of the phasing correlations in a given unit cell.
|
| modulation ON |
Turns modulation on, moving atoms to their modulated positions and displaying the aperiodic structure.
|
| modulation OFF |
Turns modulation off, displaying the unmodulated, periodic structure.
|
| modulation [atom-expression] ON/OFF |
Turns modulation on or off for a specific set of atoms only, adding or removing those atoms to/from the set of atoms already modulated.
|
| modulation T (decimal) |
Specifies the parameter t, the coordinate along the hyperspace axis, setting the phase of the modulations and creating a projection of the (3+n)D structure in 3D. If n > 1, sets all hyperspace coordinates to t. Values range from 0.0 to 1.0. Note that using the integer 1 is NOT the same as using the number 1.0, as integers are used to give multiples of q (see below).
|
| modulation T {t1 t2 t3} |
Specifies distinct phase settings for up to three wave vectors. Values range from 0 to 1.
|
| modulation Q (integer) |
Specifies the parameter t as multiples of the wave vector q, the coordinate along the hyperspace axis, setting the phase of the modulations and creating a projection of the (3+n)D structure in 3D. If the modulation dimension n > 1, sets all hyperspace coordinates to m times the length of the wave vector . Values must be integers. The effect of this setting is to shift the displayed unit cell by m unit cells along the modulation vector.
|
| modulation Q {m1 m2 m3} |
Specifies distinct phase settings for up to three wave vectors. The second parameter TRUE distinguishes this from setting t values directly.
|
| modulation scale x.x |
Sets the scale of all modulations.
|
| modulation |
|
top search index |
|
See moveto.htm
|
 The moveto command rotates the molecule to a predefined orientation, as though the camera were moving smoothly to a new position. Two formats can be used. In each, the first (optional) parameter specifies the number of seconds during which the molecule should rotate smoothly from the current orientation to the new orientation. A 0 for this first parameter specifies an instantaneous reorientation. If the axis is {0 0 0} and the degrees are 0, then the molecule is not reoriented during the operation. In conjunction with "show orientation" this command allows reading and restoring specific user-specified orientations.
|
| moveto timeSeconds DIRECTION [a b c] |
Reorients a crystal structure along the given crystallographic direction, expressed as an array or any definition of a plane. "DIRECTION [1 0 0]" here means "down the axis {1 0 0/1} toward {0 0 0/1}"; uses a quaternion difference to calculate the most direct rotation.
|
Examples: in new window using 1crn.pdb |
moveto 0 1 0 0 -90; #view from top
moveto 0 0 1 0 90; #view from right
moveto 0 0 1 0 -90; #view from left
moveto 2 1 0 0 90; #view from bottom with smooth 2-second transition
moveto 0 0 0 0 0 200; #default orientation with instantaneous transition and a zoom of 200% |
|
See moveto.htm
|
See also:
|
animation file frame invertSelected move navigate rotate rotateSelected set (misc) set (navigation) set (perspective) spin translate translateSelected zoom zoomto undefined |
top search index |
|
The MUTATE command is used to replace one or more amino acids in the current model frame by another or to create polypeptides in a new frame with defined phi and psi angles. (See mutate_CREATE.) Jmol flexible fit using Jmol bioSMARTS (x = compare(res1,res0, "[*.N][*.CA][*.C][*.O]", "BONDS"); rotate branch @x 1) is used to set the backbone dihedral angle. Similarly, Jmol bioSMARTS is used to move atoms to their proper location (compare res1 res0 SMARTS "[*.N][*.CA][*.C]" rotate translate 0). Then, necessary atoms are removed and bonds are made. No attempt is made to optimize the side-chain conformation. However, using set picking dragMinimize, one can quickly reorient the side-chain to a more appropriate conformation if desired. The mutated structure can be saved using the write PDB option. The general format for the MUTATE command is:
mutate [target residue(s)] [amino acid or sequence]
Target residues may be indicated as an integer residue number, mutate 33..., a standard XXXnn mutation code, mutate ALA34..., or any atom expression that specifies one or more residues, mutate {1-3} ....
Amino acids may be indicated with their three-letter code (for example, mutate 33 LYS, loaded as "==LYS", from RCSB), a standard one-letter standard sequence code (for example, mutate ASP34 K), or as a filename in quotes: mutate 33 "myLYS.pdb".
Sequences can be given using single-letter or three-letter codes. In the unusual case where the three single letters spell a three-letter code, such as LYS or ALA, they must be prefixed with a tilde: ˜LYS, ˜ALA. When more than one target residue is indicated and a shorter sequence is given, the sequence will repeated as necessary to change all the residues. For example: mutate {1-4} "ALA-VAL" will suffice for "ALA-VAL-ALA-VAL", and mutate {1-3} V is equivalent to mutate {1-3} "VAL-VAL-VAL". The underscore character in a sequence means "no change". Similarly, for three-letter codes, use "UNK" to skip a residue.
Examples are given below:
| mutate 33 LYS | Change residue 33 to lysine. | | mutate ALA34 G | Change residue 34 to glycine. | | mutate {ALA.CA}[2] G | Change only the second ALA residue to glycine. Note the use of ".CA" to create a list of residues, then [2] to select the second of those. | | mutate {1-3} GAL | Change the first three residues to GLY-ALA-LEU. | | mutate {1-3} A | Change the first three residues to alanine. The specified sequence will be repreated as necessary to cover the indicated residues. | | mutate {1-3} ˜LYS | Change the first three residues to LEU-TYR-SER. Tilde is required in this case ony because the sequence spells the three-letter code for the amino acid lysine. | | mutate {1-3} G_L | Change the first residue to glycine and the third residue to leucine, making no change at the second. | | mutate {1-4} "GLY-AlA" | Modify the first four residues using 3-letter amino acid codes. The sequence in this case will be GLY-ALA-GLY-ALA. (Note that quotations are required for three-letter sequences because of the use of the hyphen.) | | mutate ALA34 "myAla.pdb" | Change ALA34 to the amino acid to be found in the single-residue PDB format file "myAla.pdb". | | mutate ALA34 "==SEP" | Specify a non-standard PDB component using "==" and the three-letter PDB code for the component, as for the load command. In this case, we are specifying phopshoserine. | | mutate @3 @res | Variables are allowed for target or sequence. |
|
top search index |
|
MUTATE CREATE creates a polypeptide in a new frame with a specified secondary structure using the same syntax as for direct mutation. The general format for the MUTATE CREATE option is:
mutate CREATE [sequence] [secondary structure specification]
Sequences can be given as described for mutate using single-letter or three-letter codes.
Secondary structure can be given using an array of phi/psi pairs, which will be replicated as necessary to complete the sequence. For example: mutate CREATE aaaaaaaa [-65, -40] creates a standard alpha helix of eight alanine residues, and mutate CREATE gggggggg "beta" generates an all-glyciine beta strand. Predefined motifs are given below and could easily be expanded upon request. They are not case-sensitive:
| "alpha" | [ -65, -40 ] | idealized alpha helix | | "3-10" | [ -74, -4 ] | 310 helix | | "pi" | [ -57.1, -69.7 ] | idealized pi helix | | "alpha-L" | [ 57.1, 4 ] | left-handed alpha helix | | "helix-II" | [ -79, 150 ] | proline Type-II helix | | "collagen" | [ -51, 153 ] | collagen wide-coil helix allowing for triple helix | | "beta" | [ -140, 130 ] | slightly twisted beta strand | | "beta-120" | [ -120, 120 ] | 120-degree beta strand | | "beta-135" | [ -135, 135 ] | perpendicular side-chain beta strand | | "extended" | [ 180, 180 ] | fully extended chain | | "turn-I" | [ -60, -30, -90, 0 ] | turn type I | | "turn-II" | [ -60, 120, 80, 0 ] | turn type II | | "turn-III" | [ -60, -30, -60, -30 ] | turn type III | | "turn-I'" | [ 60, 30, 90, 0 ] | turn type I' | | "turn-II'" | [ 60, -120, -80, 0 ] | turn type II' | | "turn-III'" | [ 60, 30, 60, 30 ] | turn type III' |
|
top search index |
|
The navigate command allows exploring of the model from the perspective of an airplane capable of flying through the model. In each case, an optional time in seconds determines the time to reach the objective. If no time is given, the change occurs over two seconds. (In the case of PATH, this is the time to each point along the path, not the total path.) Subcommands can be grouped in the same command by separating them with "/", for example: navigate 2 DEPTH 30 / 5 ROTATE 180 / DEPTH 20 / TRANSLATE X 10.
|
| navigate timeSeconds CENTER {x y z} |
Bring the observer to the specifed molecular coordinate, which may be fractional in the case of crystal structures.
|
| navigate timeSeconds TRACE [atom-expression] |
Navigates along the trace of a protein or nucleic acid. The "ride" can be changed depending upon the settings of set sheetsmoothing and set tracealpha.
|
|
See also:
|
moveto set (navigation) zoomto undefined |
top search index |
Polyhedron construction
Polyhedra and symmetry
[basis]
[selection sets]
[display options]
Polyhedron modification
|
See examples-11/poly.htm
|
Jmol will form a wide variety of polyhedral structures. The polyhedra command can be used for either construction of new polyhedra or modification of existing polyhedra. Starting with Jmol 14.4, you can create polyhedra for crystal structures for which symmetry has not been applied or necessary atoms have not been loaded (the UNITCELL option). All that is necesary is the central atom. In addition, you can get information about a polyhedron using getProperty("shapeInfo.polyhedra[1]").
Finally, you can select polyhedra and use the polyhedra() or polyhedra(n) functions to get the atom centers of all or selected polyhedra.
Polyhedron construction back
Used for construction of new polyhedra, parameters fall into five subsets:
polyhedra [basis] [selection sets] [display options].
Polyhedra and symmetry back
Starting with Jmol 14.4, polyhedra in crystal structures can be created where only the central atom may be loaded. (Answering, for example, the question: What is the atom environment around Au3 in this crystal structure?)
load t.cif // no symmetry applied just the unit cell, maybe just one atom
polyhedra 4-12 UNITECELL @1
In addition, Jmol can calculate, show, and draw the point group of a polyhedron:
load t.cif
polyhedron 12 unitcell @1
select @1
show pointgroup POLYHEDRON
draw pointgroup POLYHEDRON
You can also draw points from the derived array using the DRAW POINTS option along with getProperty():
draw diameter 0.2 POINTS @{getProperty("shapeInfo.polyhedra[1].vertices")}
[basis] back
Polyhedra involve a central atom and 3 or more outer "vertex" atoms. Polyhedra can be formed based either upon the number of atoms bonded to the central atom (polyhedra 4 BONDS) or upon the number of atoms within a specified range of distance from the central atom (polyhedra RADIUS 1.5 2.0), or a combination of these (polyhedra 4,5,6 BONDS RADIUS 1.5 2.0). Multiple possibilities for bonds can be indicated using commas (polyhedra 4,6,8) or with a hyphen (polyhedra 4-20) . If only one number is given with RADIUS, then it is considered a maximum distance. One or the other, number of vertices or radius range, must be indicated. If both BONDS and RADIUS are specified, then polyhedra of the given type(s) are constructed only to the specified set of connected atoms that are within the specified range of radius of the central atom. Finally, the keywords BONDS and RANGE may be omitted provided bonds are indicated as integers and distances are indicated as decimal numbers.
[selection sets] back
Potential polyhedra centers and vertex atoms are specified in the form of a standard Jmol embedded atom expression, such as {titanium} or {atomno<12 and not nitrogen} and as such must be specified in parentheses. The first set specifies the centers; the second set specifies the vertex atoms. The optional keyword TO can preceed the vertex set for clarity, as in polyhedra 4,6 BONDS {titanium} TO {oxygen or nitrogen}. If no atom sets are designated, the assumption is "{selected} TO {*}". A single designation indicates centers, with "TO {*}" implied. If only TO and an atom set is specified, then the centers are taken as the currently selected set of atoms.
[display options] back
Three sets of display options can be included when constructing polyhedra.- Polyhedra can be displayed either as traditional "FLAT" faces (the default) or as "COLLAPSED" faces, which display more clearly the central atom. An empirically adjustable parameter, distanceFactor can be set to a higher value to include more faces in a polyhedron if some do not form. Its default value is 1.85. For collapsed polyhedra, the distance in angstroms from the central atom to the point of collapse can be specified using faceCenterOffset=x.x where x.x is a distance in Angstroms.
- Polyhedra can be displayed either with no edges (NOEDGES, the default), or with a thick line on all edges (EDGES), or on just the front edges (FRONTEDGES) or edges only (EDGESONLY). The front-edge-only option is only meaningful when the polyhedra are translucent (see below).
- Polyhedra can be colored by indicating a valid color (e.g. red or yellow) or a hexadecimal RGB color triple (e.g. [xFF0000] or [xFFFF00]). The keywords TRANSLUCENT and OPAQUE can also be used. Alternatively, after polyhedra are created they can be colored using the color polyhedra command.
Polyhedron modification back
The polyhedra command can also be used to modify already-constructed polyhedra. Used in this way, the command can take only one atom set expression, and it must not indicate the number of vertices or the basis. If the atom set expression is omitted, "(selected)" is assumed.
To turn on, turn off, or delete selected polyhedra, use polyhedra ON, polyhedra OFF, or polyhedra DELETE, respectively. Any of the display options (FLAT, COLLAPSED, EDGES, FRONTEDGES, or NOEDGES) can also be similarly modified. Colors or translucency, however, cannot be applied this way. To color a set of polyhedra that are already formed or to make them translucent, first select the set of centers of the polyhedra to modify, then use the color polyhedra command.
|
| polyhedra AUTO |
Create polyhedra automatically, using the maximum gap methodSee Zur Abgrenzung der Koordinationssphäre und Ermittlung der Koordinationszahl in Kristallstrukturen, G. O. Brunner, D. Schwarzenbach, Zeitschrift fur Kristallographie - Crystalline Materials, 1971, vol 133, issues 1-6 127-133. See also {#.polyhedraPOLYHEDRA -x.x
|
| polyhedra ONLY |
Removes all renderings except polyhedra.
|
| polyhedra -x.x |
Set the maximum gap for POLYHEDRA AUTO to be x.x in Angstroms.
|
| polyhedra minDistance maxDistance |
Creates polyhedra based on minimum and maximum distances to vertices.
|
| polyhedra {centers} {vertices} |
Create all polyhedra at the specified centers to vertices that at in the specified set and also bonded to a specific center.
|
| polyhedra LIST |
Provides info on current polyhedra.
|
| polyhedra OFFSET {x,y,z} WIGNERSEITZ |
Creates a Wigner-Seitz unit cell that is centered on the given point. Afractional coordinates such as {1/2 1/2 1/2} or {1 1 1/1}
|
| polyhedra OFFSET 1.0 BRILLIOUN n |
Produces an exploded view of 1st nth BRILLOUIN zones.
|
| polyhedra {center} TO {vertices} |
Create one polyhedron with the specified center to the specified atoms. If more than one atom is in {center}, only the first atom will be used.
|
| polyhedra POINTS x.x |
Adds spheres of the given diameter to the points of a polyhedron, colored based on the atom at that position.
|
| polyhedra BRILLIOUIN n |
Generates the nth Brilliouin zone as a polyhedron (default 1); can be scaled by adding a SCALE x.x option: polyhedra scale 3.0 BRILLIOUIN 1
|
| polyhedra WIGNER |
Generates the Wigner-Seitz unit cell as a polyhedron
|
| polyhedra nRange UNITCELL |
Creates a polyhedron specified by the range of vertex count provided by nrange) around each of the currerntly selected atoms that has a matching bonding environment. Ranges can be single numbers (5), comma-separated options (4,6), or ranges (4-8). Does not require atoms at these positions, as long as the central atom is present, using the unit cell and periodicity to find the relevant atom positions. Will check bonding as necessary using autobonding parameters. Accepts all standard POLYHEDRA parameters.
|
| polyhedra nRange maxDistance UNITCELL |
Creates a polyhedron specified by the range of vertex count provided by nrange)around each of the currerntly selected atoms that has a matching bonding environment with a limit to the distance from the central atom to a vertex.
|
| polyhedra ID "id" {x y z} TO {vertices} |
Create a named polyhedron with arbitrary center and vertices.
For example:
polyhedra ID "myid" {0 0 0} TO [{1 1 -1}, {1 -1 1}, {-1 1 1}, {-1 -1 -1}] # tetrahedron around origin
polyhedra ID "myid" @{ {selected}.xyz} TO @{ {selected}.xyz.all} # polyhedron to center of selected atoms
|
| polyhedra ID "id" OFFSET {x y z} |
Allows a cartesian offset of the named polyhedron.
|
| polyhedra ID "id" SCALE x.x |
For x.x > 0 scales a named polyhedron by the given absolute amount; for x.x < 0, moves the polyhedron from the origin by -x.x times its offset.
|
| polyhedra ID "id" [faces] [points] |
Creates a polyhedron based on a set of faces (an array of array of integers, not necessarily wound correctly) and an (optional) set of points in the form of an atom bitset or an array of points (defaulting to {*}). For example:
load $p4
polyhedra ID p4 @{{*}.find("*1**1","map")} creates a fully faced tetrahedron.
|
Examples: in new window using caffeine.xyz |
select *;polyhedra {*} DELETE;polyhedra 4 BONDS; color polyhedra grey
select atomno=19;polyhedra (*) DELETE;polyhedra 4 RADIUS 2.0 ;color polyhedra yellow
polyhedra {*} DELETE;polyhedra 4 RADIUS 2.0 {*} COLLAPSED #all three
polyhedra {*} DELETE;polyhedra 4 RADIUS 2.0 {*} TO {not within (1.1225, carbon)} #note how this disallows one of the three
select *;color polyhedra translucent; # now we can see the carbons inside
polyhedra {*} EDGES; # highlight the edges
select *; color polyhedra translucent orange;
polyhedra {*} OFF;
polyhedra {*} ON;
polyhedra {*} DELETE; |
|
Examples: in new window using kaolin.mol |
# build tetrahedrons around silicon
polyhedra BONDS {silicon}
# make some of them green
select atomno<50; color polyhedra translucent green
# delete some of them
polyhedra {atomno>75 and atomno<100} DELETE
# now build octahedrons where oxygens are within 2.0 Angstroms of a central aluminum atoms
polyhedra RADIUS 2.0 {aluminum} FRONTEDGES
select aluminum and atomno > 75; color polyhedra red |
|
See examples-11/poly.htm
|
See also:
|
[Jmol and Symmetry] [plane expressions] isosurface lcaoCartoon mo pmesh set (visibility) undefined |
top search index |
|
Resets all model orientation or the value of a variable
|
| reset STRUCTURE |
Resets PDB HELIX, SHEET, and TURN designations to their default file settings after, for example, using calculate STRUCTURE DSSP.
|
See also:
|
[Jmol Command Syntax] [Jmol Math] [Jmol Parameters] [atom expressions] [atom properties] [functions] case default define echo for if initialize message refresh restore save set set (misc) switch unset while zap undefined |
top search index |
|
Restores information saved using the save command.
|
| restore STRUCTURE saveName |
Retores a previously saved secondary structure. saveName is optional; without it, this command restores the author-designated structure after use of the calculate structure command.
|
See also:
|
[immediate (!)] define delay exit goto initialize loop quit refresh reset save unset zap undefined |
top search index |
|
See structure.htm
|
Ribbons offer a representation the protein backbone or nucleic acid helix using a flat band. For proteins, control points are chosen to be the center of the peptide bond, and the ribbon is drawn in the direction of the carbonyl oxygen (thus roughly defining the peptide planes). For nucleic acids, the control points are the midpoints between adjacent backbone phosphorus atoms, and the ribbon is drawn in the direction of the C6 carbon. A hermite curve is used.
|
| ribbon ON/OFF{default: ON} |
| ribbon ONLY |
Turns ribbon rendering on and all other rendering (including labels) off.
|
| ribbon [ribbon-radius] |
Normally, ribbons vary in width according to the amino acid atom positions. This command sets the width of the ribbon to be a connstant value (a decimal, in Angstroms). A negative number also implies ONLY.
|
|
Examples: |
See structure.htm
|
See also:
|
backbone background cartoon dots ellipsoid geoSurface meshribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill strand trace vector wireframe undefined |
top search index |
|
See structure.htm
|
Creates a crude "rocket" cartoon. See also cartoon in association with set cartoonRockets for a more precise cartoon with rockets. The set rocketBarrels option removes the arrow heads from rockets.
|
| rocket ON/OFF{default: ON} |
| rocket ONLY |
Turns rocket rendering on and all other rendering (including labels) off.
|
| rocket [rocket-radius] |
A negative number also implies ONLY.
|
|
Examples: |
See structure.htm
|
See also:
|
backbone background cartoon dots ellipsoid geoSurface meshribbon ribbon set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill strand trace vector wireframe undefined |
top search index |
|
Saves a variety of sorts of information for later restoring either in the current model or a different model.
|
| save STRUCTURE saveName |
Temporarily saves the structural state of the model, including definitions of HELIX, SHEET, etc.; can be used before the structure or calculate STRUCTURE commands to restore the previous structural assignments.
|
See also:
|
[immediate (!)] define delay exit goto initialize loop quit refresh reset restore unset zap undefined |
top search index |
|
Loads and executes the specified script file/url. The hash/pound/sharp character (#) character marks a comment to the end of the line or a semicolon. The semicolon character (;) separates multiple statements on the same line. A script file may load another script file, up to 10 deep. Within the script, for any files indicated, prepending the file name with $SCRIPT_PATH$ indicates to use the path of script file, not the current path, to find the file. If the command CD $SCRIPT_PATH$ is given in a script, then all file references within that script and any scripts that script references will be relative to the path of that script.
Arguments can be passed to a script using the syntax:
xxx.spt(argument1, argument2,...)
where the script command word is not given, and the arguments are listed in parentheses, like a function. Within the script, these arguments are in the _arguments variable.
|
| script javascript:functionCall() |
Applet only: Evaluates the return of the indicated JavaScript function as the script to be executed. Execution is blocked by setting Info.allowJavaScript = false for the Info structure used when creating the applet. Note that this is different from the javascript command, which simply evaluates the specified JavaScript command. Here the function is evaluated on the embedding page, and the return from that function, which is presumed to be Jmol script, is evaluated within Jmol.
|
See also:
|
getProperty javascript set (callback) undefined |
top search index |
|
Jmol allows a wide range of settings to be changed using the SET command -- see the categories below for details. In all cases in Jmol, "ON" and "TRUE" are equivalent, as are "OFF" and "FALSE". Different words may be used simply because they seem more appropriate for a particular parameter -- to turn an effect on or off; to to enable a feature with true or false. There is really no distinction being made here.
The SET command has a rather convoluted relationship to Jmol math, having been developed long before Jmol math was introduced. In most cases the SET command is no longer necessary -- any simple value you can set with SET can be set simply using an assignment of a value to a variable name:
strandCount = 6
instead of SET strandCount 6. However, it is recommended that you use SET for all Jmol parameters, just as a way of clearly indicating in scripts that you are setting a Jmol parameter and not a user variable. Some SET commands accept Jmol math directly: set zDepth mydepth is exactly equivalent to both zDepth = mydepth and set zDepth = @mydepth. Some SET commands do not accept Jmol math directly and instead require the @ notation: set selectionHalos @haloFlag. It is most definitely confusing. A guiding principle is that when using the keyword SET, you can always use @ with one single variable or @{...} with an expression. And you can always use actual values; there is no need to use @ with a simple number or string. The table below summarizes the situation:
| These SET commands have full command replacements and are deprecated. These commands must use @x for variables, because their processing is routed through those specialized commands. Thus, set echo x will not work. For the most part, there is no xxx = counterpart. (The two exceptions being set frank, for which there is showFrank = TRUE/FALSE and set selectionHals, for which there is selectionHalos = ON/OFF.) | set axes, set background, set boundbox, set frank, set history, set highight, set labels, set selectionhalos, set timeout | | The set commands listed on the right require @ with a variable because they have a more complicated context or do not take simple boolean, integer, float, or string values. | set axescolor, set backgroundmodel, set bondmode, set debug, set defaultcolorscheme, set defaultlattice, set defaults, set defaultvdw, set echo, set energyunits, set fontsize, set formalcharge, set hbond, set historylevel, set measurements, set picking, set pickingstyle, set property, set scriptreportinglevel, set specular, set ssbond, set strands, set structure, set togglelabel, set usercolorscheme, set vanderwaals, set zslab |
|
| set xxx |
set followed by a Jmol parameter xxx is the same as set xxx TRUE.
|
| set xxx? |
set followed by characters ending in question mark lists all Jmol parameters starting with those characters and all Jmol read-only variables starting with underscore and those characters.
|
| set |
set by itself lists all Jmol parameters that can be set and all Jmol read-only variables (starting with underscore), along with their current values.
|
| set UNDOAUTO FALSE|TRUE |
Default value TRUE, enabling automatic saving of the state only in the Java application; setting false turns off Java application console automatic undo/redo and allows user-defined undo/redo states; disabled by SET PRESERVESTATE FALSE
|
| set macroDirectory |
Holds macros.json, which points to macro files accessible by the MACRO command. Default value is https://chemapps.stolaf.edu/jmol/macros
|
| set hiddenLinesDashed |
When set TRUE, hidden lines in unit cells and boundbox are rendered as dashed lines. Default is FALSE.
|
See also:
|
[Jmol Command Syntax] [Jmol Math] [Jmol Parameters] [atom expressions] [atom properties] [functions] case default echo for if message reset set (misc) switch while undefined |
variablestop search index |
|
Jmol allows for dynamic JavaScript callback function definition. You can specify the functions to receive callbacks, and you can change the functions at any time. Specific parameters sent to these functions are discussed more fully at http://jmol.sourceforge.net/jslibrary/#jmolSetCallback. To turn off callbacks of a given type, specify "NONE". The function name must be present in JavaScript on the page containing the applet. Specifying "alert" will send the message to the user via a JavaScript alert. Note that quotation marks are required around the function name. If the filename starts with "jmolscript:" then instead of JavaScript being run, Jmol executes the Jmol script that follows. For example, set hoverCallback "jmolscript:script hover.spt" executes the Jmol script "script hover.spt" when an atom is hovered over. The code in the file hover.spt can then respond to that hovering action without the need for JavaScript.
|
| set AnimFrameCallback "function name" |
Sends a message indicating a change of frame. For compatibility with Chime, the second parameter of this function returns a number ONE LESS than the actual frame number. This function returns nine parameters. The product of the last two parameters indicates the true direction of animation.
function animFrameCallback(app, frameNo, fileNo, modelNo, firstNo, lastNo, isAnimationRunning, animationDirection, currentDirection)
| app | String | The name of the applet | | frameNo | int | The current frame number (0-based) | | fileNo | int | The current file number (1-based) | | modelNo | int | The current model number within the current file (1-based) | | firstNo | int | The first frame of the animation range, expressed as fileNo*1000000+modelNo | | lastNo | int | The last frame of the animation range, expressed as fileNo*1000000+modelNo | | isAnimationRunning | int | 0 (animation is off) or 1 (animation is on) | | animationDirection | int | 1 (animation direction +1) or -1 (animation direction -1) | | currentDirection | int | 1 (forward) or -1 (reverse) |
|
| set EchoCallback "function name" |
Sends a message each time the echo command is executed. If an EchoCallback function is not defined, these messages go to the MessageCallback function.
|
| set EvalCallback |
Generally the Jmol applet is allowed to use the eval() function of the host page JavaScript using the javascript command (unless execution of JavaScript by the applet has been specifically disallowed by setting Info.allowJavaScript = false for the Info structure used when creating the applet). The setting of evalCallback function must be made prior to jmolAppletCall() using jmolSetCallback("evalCallback","someFunctionName"). It cannot be set using set evalCallback. The callback sends the JavaScript to be evaluated back to the web page for evaluation rather than initiating that evaluation within Jmol. This could be important for the signed applet in order to isolate threads or for debugging applet calls to eval(). It is used in http://chemapps.stolaf.edu/pe/protexpl.
|
| set AtomMovedCallback "function name" |
Sends a message indicating what atoms have been moved.
|
| set AudioCallback "function name" |
Called when an {#.audio} clip event occurs. The second parameter is a map containing information about the clip, including its id; the third parameter is its status as a single word. status firing depends upon various factors and may be unpredictable in indicating completion. (Java may report "pause" for both an actual pause and a termination, possibly not releasing resources)
|
| set HoverCallback "function name" |
Sends a message indicating what atoms is being hovered over, independently of whether hover is ON or OFF.
|
| set LoadStructCallback "function name" |
Sends a message each time a file is loaded.
|
| set MeasureCallback "function name" |
Sends a message indicating the status of measurements made by the user. If a MeasureCallback function is not defined, these messages go to the MessageCallback function.
|
| set MessageCallback "function name" |
Sends a wide variety of messages during script execution.
|
| set MinimizationCallback "function name" |
Sends a message that indicates the status of a currently running minimization.
|
| set ModelkitCallback "function name" |
Sends a message that indicates the status ("ON" or "OFF") of the model kit anytime that status is changed.
|
| set PickCallback "function name" |
Sends a message that depends upon the current status of set picking.
|
| set ResizeCallback "function name" |
Sends a message indicating changes of the window size.
|
| set ScriptCallback "function name" |
Sends messages indicating the status of script execution. Line-by-line script commands are sent if one has set debugScript TRUE. If a ScriptCallback function is not defined, these messages go to the MessageCallback function.
|
| set SelectCallback "function name" |
Sends a message indicating that a selection has been made.
|
| set StructureModifiedCallback "function name" |
Sends a message each time a structure is modified. Parameters include mode, atomIndex and modelIndex, where mode is one of:
| 1 | assignAtom element/charge change start | | -1 | assignAtom element/charge change end | | 2 | assignBond start | | -2 | assignBond end | | 3 | assignAtom position start | | -3 | assignAtom position end | | 4 | delete atom begin | | -4 | delete atom end | | 5 | delete model begin | | -5 | delete model end |
|
| set SyncCallback "function name" |
The SyncCallback method allows a JavaScript function to intercept and modify or cancel an applet-applet sync message. If the called function returns "" or 0, the synchronization is canceled; any other string is substituted for the script and sent to the other currently synchronized applets. For example, the following script sets atom color by proximity to the user:
set syncmouse
sync on
set synccallback "jmolscript:color atoms property sz"
|
See also:
|
getProperty javascript script undefined |
variablestop search index |
|
The following commands relate to how files and scripts are loaded and how scripts are executed.
|
| set defaultDropScript "script" |
Sets the default script to use for drag-drop and File|Open. The Jmol default is: zap; load ASYNC "%FILE";if (%ALLOWCARTOONS && _loadScript == " && defaultLoadScript == " && _filetype == 'Pdb') {if ({(protein or nucleic)&*/1.1} && {*/1.1}[1].groupindex != {*/1.1}[0].groupindex){select protein or nucleic;cartoons only;}if ({visible}){color structure}else{wireframe -0.1};if (!{visible}){spacefill 23%};select *};
|
| set forceAutoBond OFF |
set forceAutoBond ON tells Jmol to disregard any bonding information in a file and use its own internal algorithm for determining connectivity. Its effect is for all future file loads until set OFF. This setting is particularly useful for some PDB and mmCIF files that already have a threshold amount of bonding, so that a full set of bonding can be created automatically at load time. This is necessary for proper assignment of secondary structure.
|
| set nihResolverFormat "URL" |
The load format for reading information such as chemical names, inchikeys, standard inchi, and images from the NIH/NCI CACTVS server, default http://cactus.nci.nih.gov/chemical/structure/%FILE.
|
| set smilesURLformat "URL" |
The source of files when using the "$" or "SMILES" keyword in the load command. Defualt: "http://cactus.nci.nih.gov/chemical/structure/%FILE/file?format=sdf&get3d=True"
|
See also:
|
[Jmol Precision] [Jmol and Symmetry] [Jmol/JSpecView/MagresView] bondorder cache calculate cd connect delete exit hbonds initialize load quit set (bond styles) ssbonds wireframe zap undefined |
variablestop search index |
|
In all cases below, "ON" and "TRUE" are equivalent, and "OFF" and "FALSE" are equivalent.
|
| set allowGestures FALSE |
This parameter is primarily intended for a touch-screen context. Setting this parameter TRUE allows single-point gestures to be detected. Currently the only single-point gesture supported is a "swipe" or "flick" created by a motion of the mouse or finger that is continuing along a line at the time the mouse or finger is released.
|
| set allowKeystrokes FALSE |
Set this parameter TRUE to allow key strokes in the applet or application window to be interpreted as script commands. These keystrokes will be displayed if the showKeystrokes setting is TRUE.
|
| set allowModelKit TRUE |
Set this parameter FALSE to disable modelKitMode.
|
| set allowMoveAtoms FALSE |
This setting is used in association with set picking dragSelected, set picking dragMinimize, set allowRotateSelected, and set dragSelected. The default FALSE value ensures that whole molecules are shifted or rotated rather than individual atoms. Set this parameter TRUE to allow the moving of just the selected atoms (not whole molecules).
|
| set allowMultiTouch TRUE |
Set this parameter FALSE to disable multi-touch gestures (two-finger spread for zoom, two-finger drag for translation) within a multi-touch environment.
|
| set allowRotateSelected FALSE |
This setting is used in association with set picking dragSelected, set picking dragMinimize, set allowMoveAtoms, and set dragSelected. When set TRUE, it allows user rotation of selected atoms using the mouse; when FALSE, rotation is disabled.
|
| set animationFps (integer) |
Same as animation FPS -- sets the animation delay in frames per second; can be tested, for example, with "if (animationFPS > 10)..."
|
| set animationMode "ONCE" or "LOOP" or "PALINDROME" |
Same as animation MODE -- sets the animation replay mode; must be in quotes: "ONCE", "LOOP", or "PALINDROME"; can be tested, for example, with "if (animationMode == 'ONCE')..."
|
| set autoFPS FALSE |
Setting this parameter TRUE adjusts the rate of frame changes in an animation to a lower rate if the rendering cannot keep up with the frame changing.
|
| set axesColor "color_name" |
Sets the color of all axes. (Same as color axes ....)
|
| set axis1Color "color_name" |
Sets the color of the X axis.
|
| set axis2Color "color_name" |
Sets the color of the Y axis.
|
| set axis3Color "color_name" |
Sets the color of the Z axis.
|
| set atomPicking TRUE |
Setting this parameter FALSE disallows picking of atoms. See also set bondPicking and set drawPicking.
|
| set backgroundModel (integer >= 1) or "file.model" |
Sets a particular model or animation frame to be fixed in place during an animation or when displaying models loaded from a multi-model file. set backgroundModel 0 turns this feature off. For a multifile context, the model must be give in "file.model" format. Certain restrictions apply to scripts when a background model is displayed; in that case it may be important to turn the model off and then back on during selected scripting.
|
| set bondPicking FALSE |
Setting this parameter TRUE allows picking of bonds. If pickCallback is enabled, a message is sent to the callback function providing detailed information about the bond that was picked. See also set atomPicking and set drawPicking.
|
| set chainCaseSensitive FALSE |
[NOTE: This setting is deprecated. Starting in Jmol 14.4 you an simply use quotation marks to indicate desired chain case. For example, select :"A" will not select chain a.] Jmol can be set to read the chain designations in PDB, mmCIF, and related files either with or without case sensitivity. With the default set chainCaseSensitive FALSE, the chain designations are interpreted as case-insensitive. With set chainCaseSensitive ON, the chain designation is read in a case-sensitive manner -- chain "A" is different than chain "a". This supports PDB format model files with more than 26 chains. The default startup up mode is OFF -- chain designation "a" in a SELECT command will refer to chain "A" in a file.
|
| set checkCIR FALSE |
set checkCIR retrieves the NCI/CADD Chemical Identifier Resolver URL to contact chemapps.stolaf.edu/resolver . Jmol first load of or call to https://cactus.nic.nih/gov/chemical/structure does check and will resolve that name. [This setting is for future use, when the CIR may have alternative locations.]
|
| set cipRule6Full FALSE |
Sets calculate chirality to apply an advanced CIP Rule 6 that distinguishes "in" from "out" bicyclo fusion stereochemistry.
|
| set contextDepthMax 100 |
Sets the maximum depth of contexts, including {}, if{}, for{}, while{}, and function{}, as well as the SCRIPT command and a number of expression-related situations. Default is 100; minimum is 10.
|
| set colorRasmol FALSE |
Setting this parameter TRUEprovides an alternative way to set the default color scheme to RasMol; testable with Jmol math.
|
| set defaultColorScheme JMOL or RASMOL |
Sets the default color scheme to be the traditional Rasmol/Chime scheme or the newer, more subtle, Jmol scheme. This command does not actually change the display for an object unless that object is currently being displayed using the default color scheme. See the Jmol Colors page for default color scheme details.
|
| set defaultDrawArrowScale (decimal) |
Sets the default scale for the arrow tip for {#.draw} arrows.
|
| set defaults JMOL or RASMOL |
Sets the overall defaults to be Jmol standard or more similar to Rasmol, including default color scheme, axes orientation, zero-based XYZ numbering, no spacefill, and simple wireframe. Applied immediately; should be used prior to file loading.
|
| set defaults PyMOL |
Sets zoomHeight true and measurementUnits Angstroms
|
| set defaultVDW JMOL or BABEL or RASMOL or USER |
Sets the default van der Waals radius set for spacefill and related commands. For a detailed listing of the values used, see vdw_comparison.xls. USER refers to a set of data provided by the user using the data command.
|
| set dotDensity -3 to 3 |
When Jmol displays dots, the density of dots is determined by the scale of the display. At a small scale, Jmol may display as few as 12 dots; as zoom increases, this number increases to 42, then 162, and finally, at high zoom, it becomes 642 dots. The dotDensity setting allows control over how many dots are displayed at the various scale level cutoffs. (The actual calculation does not use zoom; rather, it uses a measure of pixels per micron). Setting dotDensity to -3 results in Jmol always displaying 12 dots; setting it to 3 results in Jmol always displaying 642 dots. Settings in between these values decrease or increase the number of dots relative to the default setting (0).
|
| set dotScale (integer) |
Sets the size of dots and the dots of isosurfaces and MOs.
|
| set dotsSelectedOnly FALSE |
Setting this paramter TRUE instructs the calculate surface command to disregard atoms that are not selected when calculating the position of the surface (which then determines the parameter surfaceDistance for each atom). Also tells Jmol to ignore nonselected atoms when creating a dot surface. set dotsSelectedOnly TRUE would allow, for example, a continuous set of dots around a ligand even if it is in contact with a protein.
|
| set dotSurface ON |
Setting this parameter OFF instructs Jmol to draw complete spheres of dots around each selected atom rather than only the dots that would be derived from that atom in a molecular "dot surface."
|
| set doublePrecision |
For legacy JavaScript specifically, designed for preserving full double precision in computational crystal structure. Allows JavaScript to operate in its native full double precision mode with no rounding. Basically returns to pre-14.3.5 behavior, disabling all float/double reconciliation in Java and JavaScript. This setting should be used with caution. Full double precision is best dealt with by using JmolD.jar or JmolDataD.jar (Jmol-SwingJS) in Java.
CAUTION! May result in state loading problems between Java and JavaScript
CAUTION! May result in problems loading older state scripts
CAUTION! PNGJ images may not load properly
|
| set doublePrecisioin OFF |
For JavaScript specifically, allows JavaScript to operate in its native full double precision mode with no rounding (returning it to pre-14.3.5 behavior). Important for some aspects of crystal structure processing, particularly for computed structures where "0.6666666" is not 2/3. This setting should be used with caution, as it removes Jmol's built-in float/double reconciliation between Java and JavaScript. It may result in state loading problems between Java and JavaScript. It may result in problems loading older state scripts. PNGJ images may not load properly. See the discussion at Jmol Precision.
|
| set dragSelected OFF |
When ON, allows the user to move selected atoms by pressing ALT-SHIFT-LEFT and dragging; when combined with set pickingstyle SELECT DRAG, just LEFT-dragging moves the atoms, and the ALT and SHIFT keys are not required. For a simpler alternative, see set picking dragSelected and set picking dragMolecule
|
| set drawFontSize 14 |
Sets the font size for draw object text.
|
| set drawHover OFF |
When ON, and the user hovers over a point associated with draw object, the name of the object is displayed next to the point.
|
| set drawPicking OFF |
When ON, Jmol reports picking of points associated with draw objects to the console, the messageCallback function, and the pickCallback function. In addition, setting drawPicking true enables measurement of distances and angles involving drawn objects such as points, lines, arrows, and planes. Measurements of this type only appear transiently; they are not saved. See also set atomPicking and set bondPicking.
|
| set energyUnits kJ or kcal |
Sets the units of energy for minimization reports in kJ/mol or kcal/mol.
|
| set exportDrivers "driver_list" |
Sets (or allows you to inspect, expand, or limit) the list of export drivers available to Jmol.
|
| set exportScale (decimal) |
Sets the export scale for VRML and X3D files created with the write command. This setting allows variable scale export to 3D printer CAD software. Defaults to 1.0.
|
| set forcefield "MMFF" or "UFF" |
Sets the forcefield for minimization to MMFF94 (default) or UFF. If MMFF94 is chosen and any atoms are of a type not recognized by MMFF94, then UFF is used instead.
|
| set formalCharge (integer) |
Sets the formal charge for the selected atoms.
|
| set helixStep (integer) |
Sets the step for calculating straightness and for draw helix axis. The default value is 1, but a value of 2, for example, allows calculating straightness and axes for structures based on pairs of residues.
|
| set helpPath "URL" |
Sets the web page for the help command.
|
| set hoverDelay (decimal) |
Sets the length of time in seconds before a hovering action is acknowledged.
|
| set hoverLabel (string) |
Sets the label displayed upon hovering.
|
| set imageState ON |
The imageState property, when TRUE, allows Jmol to insert into JPG and PNG files its state. This allows images to serve both as 2D and 3D models.
|
| set isKiosk OFF |
For a multi-touch screen, set this parameter ON if the Jmol applet is running in a browser with the kiosk mode enabled, indicating there are no other applets or applications running. This is a one-time setting -- Setting this parameter OFF is the same as setting it ON, and setting it ON disallows file saves other than logging, prompt dialogs, console, popup menu, and the application script editor.
|
| set isosurfaceKey OFF |
Displays a color key relating to the last-generated isosurface.
|
| set isosurfacePropertySmoothing ON |
In the case of an isosurface that is mapped using atom-based property data, the default action is to smooth out the coloring based on an averaging of color weighted by a factor of 1/distance^4 to atoms. Turning this parameter OFF tells Jmol not to do this and instead produce a patchwork mapping that assigns a color based on the property of only the nearest atom.
|
| set isosurfacePropertySmoothingPower 0 to 10 (7) |
When isosurfacePropertySmoothing is set ON, Jmol applies a function to data so as to reduce the harshness of the edges between data assigned to specific atoms. The setting of isosurfacePropertySmoothingPower allows adjustment of that smoothing from 0 (no smoothing) to 10 (strong smoothing). The default value is 7.
|
| set jmolInJalview TRUE |
Set by Jmol when a state is read that is before 14.2.6 or in the range 14.3.0 - 14.3.5; prevents fractional and cartesian coordinate rounding; used to ensure that states created in JavaScript work identically in Java, and vice versa. Cleared by ZAP or LOAD or loading of any later state script.
|
| set legacyJavaFloat FALSE |
(Java only) set FALSE for Jmol window to NOT be embedded in JSpecView when JSpecView is opened in Jmol for spectral viewing
|
| set loadAtomDataTolerance (decimal) |
Sets the maximum distance away from a point that that an atom can be found when applying atom data using the load [property] command. Default 0.01 Angstroms.Applies the data to all atoms in similar unit cells if the data being read . This allows applying the same data to atoms in all unit cells.
|
| set macroDirectory https://chemapps.stolaf.edu/jmol/macros |
Sets the location used by the macro command.
|
| set measureAllModels OFF |
In situations where there are multiple models, typically only one model is displayed at any given time. In that situation, if a user clicks on a pair of atoms to measure a bond distance, then only one measurement is made. Using set measureAllModels ON, when the user makes measurements in any one frame, ALL similar measurements in all models in hidden frames are generated at the same time. set measureAllModels ON thus allows for very efficient measuring and investigation of differences in a bond distance or bond angle or dihedral angle across multiple models.
|
| set meshScale 1 |
Adjusts the width of the lines in isosurface and molecular orbital MESH display
|
| set messageStyleChime FALSE |
Changes the style of message reporting by script callbacks to one similar to Chime.
|
| set minimizationCriterion (decimal) |
Sets the criterion for stopping a minimization. The default value is 0.001; the minimum value is 0.0001.
|
| set minimizationMaxAtoms (integer) |
Sets the maximum number of atoms that can be minimized using the MMFF-95 force field (default 200).
|
| set minimizationRefresh TRUE |
Set this flag FALSE to not display minimizations as they occur.
|
| set minimizationReportSteps (integer) |
Sets the number frequency of the minimizer reporting steps during a minimization. Range 1-20; default 10.
|
| set minimizationSilent FALSE |
Turns off messages reporting energies for the minimization.
|
| set minimizationSteps (integer) |
Sets the number of steps after which a minimization will stop even if the desired criterion has not been reached. Default value is 100.
|
| set minPixelSelRadius 6 |
The minimum number of pixels a click can be away from an atom on the screen before it is considered too far away to be a click on that atom.
|
| set modulationScale (decimal) |
Sets the scale of the modulation for incommensurately modulated structures. Minimum value is 0.10.
|
| set mouseDragFactor (decimal) |
Sets the sensitivity of the mouse when dragging. The default value of 1.0 for set mousedragFactor allows a 180-degrees rotation when the pointer drags across the full window width.
|
| set mouseWheelFactor (decimal) |
Sets the sensitivity of the mouse wheel. The default value of 1.0 for set mousedragFactor allows a 180-degrees rotation when the pointer drags across the full window width.
|
| set multiprocessor FALSE |
Turns on parallel multiprocessing. If this setting cannot be set true, then it means you do not have a multiprocessor machine. Used in association with the parallel and process commands.
|
| set nmrUrlFormat "URL" |
Determines the URL used for SHOW NMR.
|
| set particleRadius (decimal) |
Sets a global radius for all atoms with SPACEFILL set larger than the max radius value (16.0). Defaults to 20.0. (Any spacefill setting larger than 16 will instead be this setting.)
|
| set pdbGetHeader FALSE |
Setting this flag TRUE tells Jmol to keep the header portion of the last-loaded PDB file in memory for later retrieval using getProperty("fileHeader"). If FALSE (default), the header is not saved, and a call to this function is slower, since it requires reloading the PDB file and parsing it for its header.
|
| set pdbSequential FALSE |
Setting this flag TRUE tells Jmol to assume the groups listed for a given chain in a PDB file are in order already and that Jmol should not check for proper inter-group bonding when assigning polymer sequences that form the basis of secondary structure. This flag allows for custom PDB files where the groups of a chain may not be physically adjacent, yet it is still desired to represent them as single structures.
|
| set percentVdwAtom (integer) |
The default size of an atom created when a file is loaded as a percent of the atom's van der Waal radius (Jmol standard value: 20).
|
| set picking dragmodel |
Acts like set picking dragMolecule or dragSelected. LEFT-drag to translate; ALT-LEFT-drag to rotate. Useful for two more models not loaded using set appendNew FALSE.
|
| set pickingSpinRate (integer) |
The rate of spinning that occurs when a user clicks on the end of a line created using draw (default: 20).
|
| set pointGroupDistanceTolerance (decimal) |
Sets the tolerance for two atoms being considered identical after application of a rotation. See calculate pointgroup for details.
|
| set pointGroupLinearTolerance (decimal) |
Sets the tolerance for two axes being considered identical prior to application of a rotation. See calculate pointgroup for details.
|
| set pickLabel (string) |
Sets the format of the message sent to the console and callback functions when an atom is clicked.
|
| set preserveState TRUE |
This option turns off many memory-consuming features of Jmol that are necessary for preserving the state. It can be used in situations where memory is at a premium and there is no desire to write or save the current Jmol state.
|
| set propertyAtomNumberColumnCount (integer) |
An integer value of 0 or greater. Sets the number of columns to be read for propertyAtomNumberField.
|
| set propertyAtomNumberField (integer) |
An integer value of 0 or greater. Sets the column (when propertyAtomNumberColumnCount > 0) or free-format field (otherwise) for the atom numbers in a data set. These are the atom numbers designated in a PDB file or numbers starting with 1 otherwise. Setting the field to 0 indicates that there is no such field, and values should be read in sequentially.
|
| set propertyColorScheme "colorSchemeName" |
Sets the color scheme associated with properties. SchemeName, in quotes, may be one of "roygb" (default rainbow), "bwr" (blue-white-red), "rwb" (red-white-blue),"low" (red-green), "high" (yellow-blue), "bw" (black-white), "wb" (white-black), and "friendly" (an accessibility option for color-blindness), but may be any user-defined color scheme. In Jmol 11.4, this parameter was largely replaced by color "schemeName".
|
| set propertyDataColumnCount (integer) |
An integer value of 0 or greater. Sets the number of columns to be read for propertyDataField.
|
| set propertyDataField (integer) |
An integer value of 0 or greater. Sets the column (when propertyAtomNumberColumnCount > 0) or free-format field (otherwise) for the property data in a data set. Setting this value to 0 indicates that values are simply to be read sequentially from the data.
|
| set quaternionFrame A,B,C,N,P,Q,RC,RP,X |
Specifies the axes used to define the right-handed quaternion frame for proteins and nucleic acids . These frames (xyz axes and origin) define orientations of amino acid residues in proteins and nucleic acid residues in RNA and DNA. The minimum definition of a frame is an origin (only used for draw quaternion), a point that will define an axis (usually X, but in some cases Y), and a third point that will be used to generate the other two axes. Specifically, if O, A, and B are three points and VOA defines the direction of the X axis, then VC = VOA x VOB defines the direction of the Z axis, and VC x VOA defines the direction of the Y axis. If VOB defines the direction of the Y axis, then VC, as above, defines the direction of the Z axis, and VOB x VC defines the direction of the X axis. Different frames can used for different purposes, ranging from analyzing amino acid side-chain orientations to quantifying the "straightness" of helices and sheets. Most useful are relative and absolute differences of quaternions, which define local helical axes or the axis, angle, and translation required to move from one orientation to another.
| A | "alternative" | for proteins, same as N (see below) | for nucleic acids, an alternative backbone quaternion with O = P[i], B(Y) = C4'[i], and A = C4'[i-1], which is closely associated with eta and theta dihedral angles. | | B | "backbone" | for proteins, O = CA[i], A(X) = CA[i+1], B = CA[i-1] | for nucleic acids, O = P[i], A(X) = P[i+1], B = P[i-1] | | C | "carbon" | for proteins, O = CA, A(X) = C, and B = N, thus defining the orientation of the peptide sidechains | for nucleic acids, same as N, but with the origin shifted to the "center of heavy atoms" for the base (all atoms associated with the base other than H or C4') | | N | "nitrogen" | a frame based on the peptide N atom and useful specifically in the area of solid state NMR spectroscopy. O = N, and if VC = VN-NH, and VD = VN-CA, then VB(Y) = VA x VD, M = axisAngle(VB, -17 degrees), then VA = MVC, and VC = VA x VB defines the direction of the Z axis. | for nucleic acids, O = N9(purines) or N1(pyrimidines), B(Y) = O + VC1'O, and A = VO-C2 (toward the Watson-Crick edge) | | P | "peptide/phosphorus" | for proteins, O = C, A(X) = CA, and Y = N[i+1], thus defining the orientation of the peptide plane | for nucleic acids, O = P[i], A(X) = O3'[i-1], and B = O5'[i], thus defining the orientation of the phosphorus tetrahedron | | Q | "Quine" | defined as follows: O = (C[i] + N[i+1])/2 and if VX = VCA[i]-C[i] and VB = VN[i+1]-CA[i+1], then VZ = VX x VB, and VY= VZ x VX. This frame was an early definition of the orientation of the peptide plane and suffers from the fact that these two vectors are very nearly colinear, and can produce Z directions that are misdirected; provided for historical reference only (J. R. Quine, Journal of Molecular Structure: THEOCHEM, Volume 460, Issues 1-3, 26 February 1999, pages 53-66). | not used for nucleic acids | | RC and RP | "ramachandran" | These frame selections specify that straightness should be calculated from Ramachandran angle approximations rather than actual quaternionFrames "C" and "P", respectively | no nucleic acid equivalent | | X | "experimental" | Jmol development testing | Jmol development testing |
|
| set rangeSelected |
When this flag is set to TRUE, the range for color temperature is set to be adjustable based on the selected set of atoms being colored; when false (the defualt), the range of colors is set based on the range of values in the entire model. This parameter applies to any property.
|
| set repaintWaitMs 1000 |
Sets the number of milliseconds to wait before a timer expires signalling that Jmol should not wait any longer for a repaint operation. In some large memory-intensive operations, it is sometimes advisable to set this parameter to a higher number.
|
| set saveProteinStructureState TRUE |
Generally when Jmol writes the state, helix/sheet/turn data is saved. In some cases this may not be desired. Setting this flag FALSE prevents the saving of this information in the state.
|
| set selectAllModels TRUE |
Generally when selections are made in Jmol all matching atoms in all models are selected, regardless of which model is currently in frame. When set FALSE, this flag indicates that the subset of atoms to select should be automatically set to the current model when frame changes occur.
|
| set selectHetero ON |
When turned OFF, selections do not select HETATM atoms in PDB files
|
| set selectHydrogen ON |
When turned OFF, selections do not select hydrogen atoms
|
| set showKeyStrokes TRUE |
When set TRUE, and set allowKeyStrokes is TRUE, key strokes in the applet or application window to be interpreted as script commands and displayed in the bottom left corner of the window.
|
| set showModulationVectors FALSE |
Set this value TRUE if VECTORS command is to show modulation displacements instead of vibrations
|
| set showTiming FALSE |
When set TRUE, reports timings for isosurface creation in ms in the Jmol console, and in the Java console reports detailed timings for rendering of shapes.
|
| set slabRange (decimal) |
Sets a slab range that is independent of zoom.
|
| set smartAromatic ON |
Turning the smartAromatic parameter OFF reverts to a Jmol 10 style of drawing aromatic bonds as a paired solid and dashed line when loading subsequent files. (This command has no immediate effect. Use reset aromatic;calculate aromatic to see the effect of smartAromatic)
|
| set spinFps [frames-per-second] |
determines the number of frames per second between displays of the molecule -- a small number here results in a jerky stepwise rotation.
|
| set spinX [degrees-per-second] |
The set spinX, set spinY, and set spinZ commands allow for the setting of the spin axes -- x, y, and z -- independently as well as the rate of spin. The actual spinning axis is a complex combination of the three settings. No actual spinning occurs until the spin ON command is issued or the user turns spinning on using the mouse menu. Jmol has a much richer variety of spinning possibilities to this Chime/Rasmol-standard capability, allowing simple spinning around arbitrary molecular- and window-based axes. See the rotate command.
|
| set spinY [degrees-per-second] |
see set spinX
|
| set spinZ [degrees-per-second] |
see set spinX
|
| set starWidth (decimal) |
Sets the star line width in Angstroms.
|
| set stateVersion (integer) |
Displays the version of Jmol used to create the most recently run state script (a parameter rather than a read-only variable only because a script has to create it).
|
| set statusReporting ON |
When set OFF, this parameter prevents Jmol from recording status messages and reporting them to a requesting web page. When OFF, the JavaScript method Jmol.scriptWait() will function correctly, but it will not return status information from the applet.
|
| set stereoDegrees (decimal) |
Same as stereo (degrees), sets the angle for stereo images; can be checked using Jmol math.
|
| set strutDefaultRadius 0.3 |
For calculate STRUTS and the struts command, sets the default radius for new struts.
|
| set strutLengthMaximum 7 |
For calculate STRUTS, sets the maximum length for a new strut.
|
| set strutsMultiple OFF |
For calculate STRUTS, turn this flag ON to allow more than one strut on a given atom.
|
| set strutSpacing 6 [Jmol 16.2.1] |
For calculate STRUTS, sets the minimum spacing (in terms of residues) for new struts.
|
| set symmetryHM ON/OFF{default: OFF} |
For show/calculate/draw POINTGROUP, TRUE switches to Hermann-Mauguin (2m, 2/m2/m2/m) notation rather than the default Schoenflies (C2v, D2h) notation
|
| set syncMouse OFF |
When sync is ON, delivers mouse actions to the target applet.
|
| set syncScript OFF |
When sync is ON, delivers script events to the target applet.
|
| set UNDO |
Saves the current state on the UNDO stack. Clears the REDO stack and sets undoAuto FALSE.
|
| set undo ON |
Setting this flag FALSE disables the undo/redo buttons on the Jmol application console, saving memory.
|
| set undoauto ON |
Enables the default automatic saving of the state only in the Java application. Setting false turns off Java application console automatic undo/redo and allows the user full control over undo/redo states generated by sequences of SAVE STATE,UNDO/REDO, and REDO. Disabled by SET PRESERVESTATE FALSE.
|
| set undomax 20 |
Sets the maximum number of allowed saved states (default 20) when SET defaultAuto is FALSE. Setting this value to 0 clears both the UNDO and the REDO stacks.
|
| set useMinimizationThread ON |
Generally the minimize command runs in a separate thread. Setting this parameter FALSE instructs Jmol to use the same thread as is being used for commands. This is important in situations where one wants to wait for completion of the minimization before continuing.
|
| set useNumberLocalization ON |
Currently only applicable in the display of unit cell parameters, the useNumberLocalization setting determines whether or not local number formatting will be used (comma as decimal point, for example).
|
| set vectorScale (decimal) |
Sets the scale for vibration vectors.
|
| set vectorTrail (decimal) |
For spinning magnetic vectors, draw a Japanese fan-like trail for the specified number of animation frames.
|
| set vectorsCentered |
Sets vectors to be centered on an atom (as for showing magnetic spin vectors).
|
| set vdw JMOL or PROBE |
Sets the default VDW radius to be based on Jmol values (OpenBabel or Rasmol, depending upon file type) or the set used by the Duke University molProbity site as per Word, et al, J. Mol. Biol. (1999) 285, 1711-1733:
| 1.0 | {_H} | | 1.17 | {_H and connected(_C) and not connected(within(smiles,"[r6]"))} | | 1.75 | {_C} | | 1.65 | {_C and connected(3) and connected(_O)} | | 1.55 | {_N} | | 1.4 | {_O} | | 1.8 | {_P} | | 1.8 | {_S} |
|
| set vectorSymmetry FALSE |
Displays vibration vectors as double-ended arrows.
|
| set vibrationPeriod (decimal) |
Sets the default period of vibrations (in seconds). Setting this value to 0 disables vibration modeling.
|
| set vibrationScale (decimal) |
Sets the amplitude of vibrations.
|
| set waitForMoveto ON |
Setting this parameter OFF allows moveTo operations to continue independently while script commands are processing. An ongoing moveTo operation can then be stopped at any time using moveTo STOP Starting in Jmol 14.2.7, this action is extended to the rotate x.x y.y finite spin option.
|
| set wireframeRotation OFF |
Turning this parameter ON sets Jmol to not display spacefill and only display bonds as simple lines during user-based model manipulation.
|
|
See also:
|
[Jmol Command Syntax] [Jmol Math] [Jmol Parameters] [atom expressions] [atom properties] [functions] animation capture case cgo data default draw echo file for frame if invertSelected macro message move moveto nbo reset rotateSelected set show slab spacefill spin switch translate translateSelected while write (images and frames) write (object) zoom zoomto undefined |
variablestop search index |
|
This command group allows for customization of the rendering of PDB and mmCIF secondary structures. The default is set cartoonRockets OFF; set ribbonAspectRatio 16; set hermiteLevel 0; set ribbonBorder 0; set sheetSmoothing 1; set strands 5; set traceAlpha ON.
|
| set cartoonBaseEdges OFF |
Setting this parameter ON displays nucleic acid bases as triangles that highlight the sugar edge (red), Watson-Crick edge (green), and Hoogsteen edge (blue). See Nasalean L, Strombaugh J, Zirbel CL, and Leontis NB in Non-Protein Coding RNAs, Nils G. Walter, Sarah A. Woodson, Robert T. Batey, Eds., Chapter 1, p 6.
|
| set cartoonBlocks OFF |
Displays the nucleotides of RNA and DNA as blocks corresponding to the DSSR convention.
|
| set cartoonBlockHeight 0.5 |
Sets the thickness of the blocks representing the nucleosides when cartoonBlocks is set TRUE.
|
| set cartoonFancy OFF |
Setting this parameter ON produces cartoons that are not just flat ribbons.
|
| set cartoonLadders OFF |
Setting this parameter ON enables a PyMOL-like "cartoon_ladder_mode" rendering of nucleic acids, involving a simple stick representation for each base.
|
| set cartoonRibose OFF |
When ON, adds ribose rings to nucleic acid cartoons.
|
| set cartoonRockets OFF |
Setting this parameter ON sets the display of RasMol cartoons to be a mixture of three-dimensional sheet cartoons and alpha helix rockets. It is not a precise as a cartoon with respect to helices but more precise than rockets in relation to beta-pleated sheets.
|
| set cartoonSteps OFF |
Setting this parameter ON produces cartoons that have connectors for bases that look like those found in RNA step diagrams (requires load =xxxx/dssr).
|
| set defaultStructureDSSP TRUE |
Setting this parameter FALSE tells Jmol to not use DSSP for the calculation of secondary structure either upon loading a structure with no HELIX or SHEET information or when using the command calculate STRUCTURE.
|
| set dsspCalculateHydrogenAlways TRUE |
Standard DSSP secondary structure analysis disregards all backbone amide hydrogen atoms that might be in a file and instead calculates its own based on the direction of the C=O vector. Setting this parameter FALSE instructs Jmol to not calculate these file-based positions and to instead use the positions of the hydrogen atoms that are in the file.
|
| set hermiteLevel (integer, -8 to 8) |
Determines the amount of curve smoothing used in rendering protein and nucleic acid secondary structures involving cartoon, ribbbon, rocket, and trace. set hermiteLevel 0 uses a Jmol 10.2 method of rendering these structures, with rope-like traces and paper-thin ribbons and cartoons. Positive values produce more rounded but slower to render shapes, but only when the model is not in motion. Negative numbers produce the same, but also while rotating. A value of 4 or -4 might be a reasonable compromise between look and performance. Hermite levels 6 or higher (-6 or lower) produce a ribbon cross-section in the shape of an ellipse. Use set ribbonAspectRatio 4 rather than the default value of 16 for a more rounded ellipse.
|
| set highResolution OFF |
When set ON, and hermiteLevel is set, draws high-resolution hermite curves even if the diameter is small. Otherwise, small-diameter traces are shown in a faster-rendering fashion.
|
| set ribbonAspectRatio (integer) |
Sets the thickness of the ribbons in ribbon and cartoon renderings in terms of the width:height aspect ratio; only enabled in conjunction with set hermiteLevel to a non-zero value. set ribbonAspectRatio 0 turns off this feature; 8-16 is recommended; higher positive numbers leading to thinner ribbons.
|
| set ribbonBorder OFF |
Turning this parameter ON adds a slight border for ribbons.
|
| set rocketBarrels OFF |
Turning this parameter ON removes the arrow heads from rockets and cartoon rockets, turning them into simple cylindrical barrels.
|
| set sheetSmoothing (0 to 1) |
In conjunction with set traceAlpha, this parameter determines the "waviness" of beta-pleated sheets. set sheetSmoothing 0 creates wavy sheets, with the ribbon or trace going directly through the alpha carbons. The default is set sheetSmoothing 1, which produces a more averaged, smoother (standard) ripple. Has no effect unless set traceAlpha.
|
| set strandCount [strand-count] |
Sets the number of strands to display for the strand and meshribbon shapes both, with a maximum of 20.
|
| set strandCountForMeshRibbon [strand-count] |
Sets the number of strands to display for the meshribbon shape, with a maximum of 20.
|
| set strandCountForStrands [strand-count] |
Sets the number of strands to display for the strand shape, with a maximum of 20.
|
| set structure HELIX|SHEET|TURN [phi-psi ranges] |
Ideally, PDB files will contain header information relating to helix, sheet, or turn locations. When this information is not present, or when the calculate structure command is given, Jmol uses an admittedly crude Ramachandran angle range check to determine structure type. The set STRUCTURE command allows setting those Ramachandran angle ranges for helix, sheet, and turn. [phi-psi range] is a set of angles in groups of four. Each group of four numbers includes the minimum and maximum phi values followed by the minimum and maximum psi values that would be valid for this structure type. For example, set structure HELIX [-160, 0, -100, 45] sets "helix" to be defined as phi >= -160 and phi <= 0 and psi >= -100 and psi <= 45 (the Jmol default). The default setting for sheet (really just a strand, since we are not requiring cross-strand hydrogen bonding) and turn are set SHEET [-180, -10, 70, 180, -180, -45, -180, -130, 140, 180, 90, 180]; set TURN [30, 90, -15, 95]. It is recommended that this command be followed immediately with calculate structure;cartoons only.
|
| set traceAlpha TRUE |
When set TRUE (the default), along with set sheetSmoothing 0, directs Jmol to draw traces directly through all alpha-carbons. The effect is a wider, more standard alpha helix and a wavier beta-pleated sheet than in Jmol 10.2. Setting set sheetSmoothing 1;set traceAlpha ON directs Jmol to create smooth out the beta-pleated sheets but still follow the alpha carbons for other structure types. With set traceAlpha FALSE, Jmol draws traces through the midpoints of the lines connecting adjacent alpha-carbons, producing tighter alpha helices and smoothed beta-pleated sheets. Also used as the basis for drawing cartoons, meshRibbons, ribbons, rockets, and strands. Jmol has the default settings: set traceAlpha TRUE; set sheetSmoothing 1;set hermiteLevel 0.
|
|
variablestop search index |
|
This command group turns on or off specific sets of atoms and axes/cell-related options.
|
| set solventProbeRadius [probe-radius-in-angstroms]{default: 1.2} |
Sets the radius of the solvent "ball" that would run around the structure defining its outline. After set radius, you must (re)issue dots ON for it to take effect, and the solvent probe option for dots must be set on using set solvent ON (below).
|
|
See also:
|
[Jmol and Symmetry] axes backbone background boundbox cartoon color (atom object) color (bond object) color (element) color (model object) color (other) color (scheme) color labels color measures dots ellipsoid geoSurface getProperty meshribbon polyhedra ribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set userColorScheme show show (NMR) slab spacefill strand trace vector wireframe undefined |
variablestop search index |
|
The set picking command determines the response to clicking of atoms by the user. For those options for which they apply, the keywords MEASURE and SELECT are optional.
|
| set picking DRAGATOM |
Clicking and dragging an atom moves its position. For crystal structures, atoms are constrained by their Wyckoff position. So, for example, if an atom is at the intersection of a mirror plane and a perpendicular two-fold axis, it cannot be moved without breaking symmetry. All symmetry-equivalent atoms are moved accordingly. In addition, symmetry may not allow moving of full some of the atoms.
|
| set picking DRAGMODEL |
Clicking and dragging on any atom of the structure drags its entire model; using SHIFT with the drag rotates the model about its center.
|
| set picking DRAGMOLECULE |
Clicking and dragging on any atom of the structure drags its molecule only; using SHIFT with the drag rotates the molecule about its center. For crystal structures, all symmetry-equivalent moleules are moved accordingly. In addition, symmetry may not allow moving of full molecules.
|
| set picking DRAGSELECTED |
Clicking and dragging on any atom of the structure drags the selected atoms only; using SHIFT with the drag rotates the selected atoms about their center. See also set allowMoveAtoms and set allowRotateSelected, both of which modify the action of set picking DRAGSELECTED.
|
| set picking SELECT STRUCTURE |
When the user clicks an atom, the selection is toggled on or off for all atoms within the same structural unit (helix, sheet, turn -- PDB only).
|
top search index |
|
With set pickingStyle you can change the behavior of Jmol in response to user mouse actions relating to selecting atoms or measuring distances, angles, and torsions.
| SELECT | Sets the behavior of Jmol to different clicking styles. For the standard Jmol default selection behavior, use set pickingStyle SELECT toggle The actions of these options depend upon the setting of set picking SELECT. If picking has not been set to SELECT, then this command has no immediate effect. In the explanations given below, it is presumed that we have set picking SELECT GROUP. The SELECT keyword is recommended but not required. | | MEASURE | set pickingStyle MEASURE ON in conjunction with set picking MEASURE displays the measurements on the structure as they are generated by user clicking. If picking has not been set to MEASURE, then this command has no immediate effect. set pickingStyle MEASURE OFF returns to the default Jmol behavior. |
|
| set pickingStyle SELECT toggle |
left-click toggles that group selected/not selected (Chime style; Jmol default).
|
| set pickingStyle SELECT selectOrToggle |
left-click selects just that group
shift-left-click toggles the group selected/not selected (Rasmol style).
|
| set pickingStyle SELECT extendedSelect |
User mouse action is according to the following scheme, which is the style used by PFAAT.
| left-click | selects just that group, like rasmol | | shift-left-click | toggles the group selected/not selected | | alt-left-click | appends the group to the current selection | | alt-shift-left-click | removes the group from the current selection | | left-click off model | executes (select none) |
|
| set pickingStyle SELECT DRAG |
makes the LEFT button a click-and-drag button when associated also with set PICKING select (molecule, group, chain, etc.) and set dragSelected.
|
| set pickingStyle SELECT NONE |
Returns to the Jmol default toggle picking style.
|
| set pickingStyle MEASURE ON |
Clicking atoms measures and displays distance, angle, or torsions based on the setting of set picking MEASURE. By default the user sees this information displayed. Setting set pickingStyle measure OFF when set picking MEASURE is set to DISTANCE, ANGLE, or TORSION tells Jmol to stop indicating measurements on the model when the user clicks, even though the distance, angle, or torsion information is still sent to the message queue.
|
variablestop search index |
|
show sends information about the model to the MessageCallback function and to the Java or Jmol console. If using the application, using Jmol -ionx filename.spt modelfile.xyz > output.txt, you can put a show command in a script file (filename.spt), and have the output directed to output.txt. The command line options used in this example include -i (silent startup), -o (use standard output), -n (no display), -x (exit after running the specified script file). All of the parameters that can be set can be shown. They are not listed here. Adding "/xxxx" to the command, such as SHOW file/cell will filter the output only to lines containing the text after the slash character. Adding "/!xxxx" to the command, such as SHOW file/!cell will filter the output only to lines NOT containing the text after the slash character.
|
| show DRAWING |
Displays a drawing of the Jmol structure in a new browser window.
|
| show DSSP |
Displays a DSSP secondary structure analysis report, which includes regions of three kinds of helix (3/10, alpha, and pi), turns, sheets, and bridge groups (DSSP codes G, H, I, T, E, and B, respectively). Bends (DSSP "S") are not included. This report can be sent to a file using, for example: var x = script("show DSSP");write var x "dsspReport.txt".
|
| show VALIDATION |
Shows validation annotations that are available as properties, having been loaded from RCSB or PDBe with the /val option. For example,
load *1crn/val; show validation
Validations loaded:
property_types_of_outliers (residues: 3)
property_bond_lengths (atoms: 2, max: 5.38)
property_bond_angles (atoms: 6, max: 7.83)
|
See also:
|
background boundbox cache center centerAt cgo color (atom object) color (bond object) color (element) color (model object) color (other) color (scheme) color labels color measures delete draw getProperty set (misc) set (visibility) set userColorScheme write (object) undefined |
top search index |
|
Displays a predicted 1H NMR spectrum using JSpecView (Jmol application only). Atoms on the structure are correlated with signals in the spectrum. The spectrum is constructed using a service provided by http://nmrdb.org.
|
| show |
See also:
|
set (visibility) undefined |
top search index |
|
See structure.htm
|
Strands offer a representation the protein backbone or nucleic acid helix using lines. Curvature control points are as described for ribbon.
|
| strand ON/OFF{default: ON} |
| strand ONLY |
Turns strand rendering on and all other rendering (including labels) off.
|
| strand [strand-radius] |
Normally, strands vary in width according to the amino acid atom positions. This command sets the radius of the set of strands to be a constant value (a decimal, in Angstroms). A negative number also implies ONLY.
|
|
Examples: |
See structure.htm
|
See also:
|
backbone background cartoon dots ellipsoid geoSurface meshribbon ribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill trace vector wireframe undefined |
top search index |
|
The structure command allows customized definition of the secondary structure of a protein model as HELIX, SHEET, TURN, or NONE.
|
| structure HELIX|SHEET|TURN|NONE (atomExpression) |
The atom expression is optional and if missing defaults to the currently selected atoms. structure HELIX {4-10:B}, for example, sets residues 4-10 on chain B to be represented as a helix. Note that the file must be of PDB format (from a pdb, mmcif, or suitable mol2 file) as well.
|
top search index |
|
See structure.htm
|
A "trace" is a smooth hermite curve through the same control points used by ribbons.
|
| trace ON/OFF{default: ON} |
| trace ONLY |
Turns trace rendering on and all other rendering (including labels) off.
|
| trace [trace-radius] |
|
Examples: |
See structure.htm
|
See also:
|
backbone background cartoon dots ellipsoid geoSurface meshribbon ribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill strand vector wireframe undefined |
top search index |
|
Turns on or off the unit cell for crystal structures, and determines its line style and line width (as a decimal number, in Angstroms).
|
| unitcell ON/OFF{default: ON} |
Turns the unit cell on or off
|
| unitcell (decimal) |
Sets the unit cell line diameter in Angstroms.
|
| unitcell BOUNDBOX |
Sets the unit cell based on the current bound box.
|
| unitcell CENTER [atom-expression-or-coordinate] |
Sets the unit cell to be centered on a given atom or coordinate. The coordinate is assumed to be in fractional coordinates already, for example {0.5 0.5 0.5}.
|
| unitcell DOTTED |
Sets the axes style to a thin dotted line.
|
| unitcell FILL {na nb nc} |
Simple integer multiple unitcell option similar to RANGE {555 ijk 1} (meaning show block with lines for each contained unit cell).
|
| unitcell SUPERCELL {na nb nc} |
Simple integer option similar to RANGE {555 ijk 0} (meaning show as one large unit cell).
|
| unitcell NONE |
Completely removes the unit cell, spacegroup, and symmetry. Also removes unit cell and spacegroup information from model auxiliary info _M, and allows nonperiodic manipulation of atom positions.
|
| unitcell OFFSET {i j k} |
Sets the origin of the unit cell to be the specified coordinate (with braces). No matter how the coorinate is written (with or without "/"), it is interpreted as a fractional coordinate. For example, unitcell {0.5 0.5 0.5} sets the origin of the unit cell to {1/2, 1/2, 1/2}. This change is for display purposes only -- the actual "{0 0 0}" point remains where it was initially. The keyword OFFSET, introduced in Jmol 14.2, is optional.
|
| unitcell OFFSET @1 |
Quick offset to a specific atom.
|
| unitcell OFFSET {atoms} |
Quick offset to a center of atoms.
|
| unitcell RANGE {nnn yyy scale} |
Creates a block of unit cells, possibly scaled, using the "555" cell naming system, where 555 is the base cell, and digits 0-9 indicate cells -5 to +4 from relative to this for each axis. A negative scale, such as -0.5, fills the specified range of unit cells with unit cells of the specified size allowing, for instance, filling of a set of supercells with unit cells based on a primitive smaller unit cell. A scale of 0 creates the unit cell but does not fill it with smaller unit cells. Starting in Jmol 14.2, more complicated supercells can be generated using the "abc;offset" method (see below). The keyword RANGE, introduced in Jmol 14.2, is optional. Jmol implements extended versions of 555 in the form of 1505050 (range 0 to 99) and 1500500500 (range 0 to 999), allowing for descriptions of a much wider range of cells. Thus, 1505152 and 1500501502 are the same as 567, but 1505070, cell {1 1 21}, has no corresponding 555 representation.
|
| unitcell RESET |
Returns the unit cell to its original setting and resets its line width to a thin line. (Note that restore unitcell accomplishes the same without resetting the line width.)
|
| unitcell RECIPROCAL (integer) |
Sets the unit cell to be its reciprocal, indicating a multiple of pi using an integer.
|
| unitcell RECIPROCAL x.x |
Sets the unit cell to be its reciprocal, scaling by the indicated factor.
|
| unitcell RECIPROCAL 2 |
Sets the unit cell to be its reciprocal, scaled as integer multiples of pi.
|
| unitcell TICKS X|Y|Z {major,minor,subminor} FORMAT [%0.2f, ...] |
Sets the parameters for ticks along the a, b, and c edges of the unit cell. An optional specific axis (X, Y, or Z) can be indicated. There are three levels of ticks - major, minor, and "subminor." Only the major ticks have labels. Which of these tick levels are displayed and the distance between ticks depends upon the parameter that takes the form of a point. This point may be in fractional form, {1/2 0 0}. The optional keyword FORMAT allows formating of the labels for the major ticks. These are based on an array of strings given after the FORMAT keyword. If the array is shorter than the number of ticks, the formats in the array are repeated.
|
| unitcell [a,b,c,alpha,beta,gamma] |
Sets unit cell to the array of parameters, with no offset. Same as UNITCELL " a=...,b=...,c=...,alpha=...,beta=...,gamma=.... ".
|
| unitcell [ {origin} {a} {b} {c} ] |
An array of four points defines a new unit cell. Note that fractional units may be used, and if they are, then they are defined for the CURRENT unit cell. For example: unitcell [{0 0 0} {1/2 0 0}, {0 1/1 0} , {0 0 1/1}] is reversed by unitcell [{0 0 0} {2/1 0 0}, {0 1/1 0}, {0 0 1/1}]. Note that use of "/" in a ALL of these points, indicating fractional coordinates.
|
| unitcell "a=...,b=...,c=...,alpha=...,beta=...,gamma=...." |
Sets the unit cell from a string such as "a=10,b=10,c=20,alpha=90,beta=90,gamma=129".
|
| unitcell TRANSFORM [4x4 matrix] |
Sets the unit cell from a 4x4 rotation-translation matrix.
|
| unitcell "parent" |
Sets the unit cell to be the parent unit cell (MCIF reader only)
|
| unitcell "standard" |
Sets the unit cell to be the stanadard unit cell (MCIF reader only)
|
| unitcell "conventional" |
Sets the unit cell to be the conventional (file-based) unit cell. If the unit cell from the file is primitive, you can use UNITCELL @{unitcell("conventional")} to generate a conventional cell from it.
|
| unitcell "primitive" |
Sets the unit cell to be a primitive unit cell
|
| unitcell "abc;offset" |
Sets the unit cell to a new setting relative to its current setting. abc is an expression such as a/2,2b,c that relates the new setting to the current setting. offset is an optional fractional offset such as 0,1/2,0 relative to the current unit cell. Adding "!" at the beginning of the description reverses the notation. Thus, unitcell "!a,2b,c;0,1/2,0" reverses the effect of unitcell "a,2b,c;0,1/2,0". This command can be used to create completely different unit cells from that given in a file and allowing commands such as select cell=555 or draw unitcell or print {Fe1}.fxyz to operate on this new unit cell.
|
|
See also:
|
axes boundbox measure undefined |
top search index |
|
Draws vectors arising from vibrational mode data. Operates on whichever atoms have been selected. See also color (atom object). For msCIF or JANA2006 incommensurately modulated structures , turning "vectors on" displays an arrow from the unmodulated position to the modulated position when modulation is off, and the other direction when modulation is on.
|
| vector ON/OFF{default: ON} |
Turns vibration vector display on and off
|
| vector [diameter-pixels] |
Sets the diameter of the vector
|
| vector [radius-in-angstroms] |
Sets the diameter of the vector
|
| vector SCALE [vector-scale] |
Adjusts the scale of the vector independently of the vibration motion.
|
|
See also:
|
backbone background cartoon dots ellipsoid geoSurface meshribbon ribbon rocket set (highlights) set (lighting) set (navigation) set (perspective) set (visibility) slab spacefill strand trace wireframe undefined |
top search index |
|
Provided information is present in the file (xyz format with columns 6-8 indicating dx, dy, and dz, or Gaussian harmonic frequency output), turns on and off display of vibration animation and allows setting of the time period for the vibration (in seconds) and the scale of the motion relative to the default (1). For msCIF or JANA2006 incommensurately modulated structures , turning "vibration on" actuates a visualization of the modulations as totally nonrealistic (but still valuable) phased vibrations.
|
| vibration ON/OFF{default: ON} |
Turns vibration on with a 1-second time period or turns vibration off.
|
| vibration [time-period] |
Sets the time period for one full vibration in seconds and turns vibration on.
|
| vibration MAX (decimal) |
Rescales all vibration vectors to have a maximum value specified.
|
| vibration PERIOD [time-period] |
Sets the time period for one full vibration in seconds, but does not turn vibration on
|
| vibration SCALE [vibration-scale] |
Sets the scale of the vibration motion independently of the vector length.
|
|
See also:
|
load [property] undefined |
top search index |
|
The Jmol history, menu, currently defined functions, and variables may all be written to files. In addition, specific properities, quaternion analysis, and ramachandran information can also be saved in PDB format.
|
| write RAMACHANDRAN . . . "fileName" |
Creates a file in PDB format for the alpha carbons of a peptide, where the x, y, and z axis values are actually the PHI, PSI, and OMEGA values for each amino acid. An additional optional keyword DRAW writes a script file that would draw PHI and PSI angles on the structure. See the plot RAMACHANDRAN command for parameter options.
|
top search index |
[Jmol Command Syntax]