Jmol/JSmol Interactive Script Documentation

Jmol/JSmol interactive scripting documentation

dipole or dipoles

   ID [object id]
   [modifying parameters]
   [positions]

The dipole command allows for the drawing of a bond or molecular dipole arrow with or without a cross near the tail. Note that without the cross, since it can be drawn from any point in molecular space to any other, a "dipole" can be used by a web page developer for a simple arrow in order point to some particular aspect of the model having nothing to do whatsoever with dipole moments.The values of each dipole can be set by the user or will be estimated using partial charge data or molecular dipole information if available in the loaded model file. Only a very crude calculation is used to estimate at least the direction of all bond dipoles. The general syntax of the dipole command is as follows:

dipole [objectID] [modifying parameters] [positions]

ID [object id]    back

The optional identifier such as "bond1" that can be referred to in later scripts as $bond1. These words are arbitrary and if preceded by the optional keyword ID may be any string. The special identifier BONDS (without the keyword ID) refers to the entire collection of bond dipoles -- those dipoled defined specifically as between two atoms. Similarly, the special identifier MOLECULAR (without the keyword ID) is primarily for files for which molecular dipole information is available. The value and placement of this dipole can also be set using the dipole command.

[modifying parameters]    back

The dipole is defined using a small set of parameters. These include:

CROSS
NOCROSS include (default) or do not include a 3D cross near the tail of the arrow.
DELETE Deletes the specified dipole if an identifier is given or all dipoles if no identifier is given; not used with any other parameters.
WIDTH x.xx The width of the dipole in Angstroms. The default value is 0.005 Angstroms.
OFFSET x.xx
OFFSET n Dipoles are by default centered between the two endpoints. The OFFSET value sets the offset of the dipole from this position along the axis of its endpoints. In Angstroms if a decimal number is given; in percent of the distance between the two endpoints if an integer is used.
OFFSETSIDE x.xx The offset of the dipole in Angstroms perpendicular to the axis of its endpoints. The default value is 0.4 Angstroms for atom-based dipoles and 0 for the molecular dipole.
VALUE x.xxx A decimal number indicates the value of the dipole. Overall scaling is accomplished either by setting this number or using set dipoleScale. The VALUE keyword is optional.

[positions]    back

The positions of the endpoints of the dipole are set either using embedded atom expressions in parentheses, such as (atomno=1), or using a specific point in molecular space, {x y z}, either as a cartesian coordinate or a fractional unit cell coordinate. If two atoms are designated, then the dipole becomes a member of the "bonds" dipole collection and can be colored with that group. If a set of atoms is indicated, the geometric center is used. Thus, (*) indicates the geometric center of the molecule.

dipole ID [object id] ALL [atom-expression]

Defines a dipole based on the given subset of atoms.

Examples:

See examples-11/dipole.htm

top

index

Index (full)

dipole or dipoles
dipole ID [object id] ALL [atom-expression]

last updated: May 04, 2025 11:01:10

html

xml docbook