ChimeraX docs icon

Command: hbonds

hbonds  atom-spec1  [ saltOnly  true | false ] [ restrict  cross | both | any |  atom-spec2 ] [ select  true | false ] [ reveal  true | false ] [ showDist true | false ] [ color  color-spec ] [ radius  r ] [ dashes  N ] [ name  name ]  other-options

hbonds deletename  name ]
– or –
~hbondsname  name ]

The hbonds command uses atom types and geometric criteria to identify hydrogen bonds (H-bonds) involving the specified atoms. It is the command-line implementation of the H-Bonds tool. See also: H-bond-related features, distance, addh, clashes/contacts, pbond, interfaces, altlocs, Molecule Display icons: , Protein-Ligand Binding Sites tutorial

The saltOnly option allows finding just the salt bridges, and the restrict option allows finding only H-bonds within the specified set of atoms or between them and a second set. The total number of H-bonds found is reported in the Log. The total includes all H-bonds consistent with the criteria, even if they could not coexist simultaneously. Distances and other details can be logged and/or saved to a file.

By default, the H-bonds are shown as pseudobonds. The reveal true option can be used to display atoms as needed so that all of the H-bond pseudobonds will be shown. The pseudobonds can be labeled by distance, and their color, radius, and number of dashes can be specified.

The pseudobonds can be removed with the hbonds delete or ~hbonds command. The default name of the pseudobond model(s) for creation and removal is hydrogen bonds. When multiple pseudobond models have the same name, specific models can be removed with the close command.


hb ligand restrict protein reveal true
– hide all atoms, then identify H-bonds between ligand and protein, showing atoms as needed to show all H-bonds
hb /a:nad restrict cross log true reveal true
– calculate H-bonds between the NAD residue in chain A and everything else, write results to the Log
hide; cartoon suppress f
hb (/a & protein) restrict (/b & protein) reveal t show t
– hide all atoms and show cartoon (enabling coincident backbone-atom display), then identify H-bonds between chain A protein and chain B protein, displaying atoms as needed to show all H-bonds, labeled by distance; the parentheses are not required, just included for clarity
del solvent; hide protein
hb sidechain restrict both reveal t color yellow radius .08
hb sidechain restrict both salt t name "salt bridges" col magenta radius .1
– delete solvent, hide protein atoms, and calculate all sidechain-sidechain H-bonds and their salt bridge subset as two separate pseudobond models, displaying the involved residues and making the salt-bridge pseudobonds fatter so that they are clearly visible over the others

H-Bond-Related Features

By default, H-bonds are shown as pseudobonds in a model named hydrogen bonds. The command-line specifier hbonds (not to be confused with the command) refers to such pseudobonds, which can also be generated by:

Analysis and alternative display:

Some other commands evaluate H-bonds but do not show them:


saltOnly  true | false
Whether to limit the results to salt bridges, that is, H-bonds between formally charged functional groups. Such groups are identified by their atom types, where possible. In the absence of explicit hydrogens, a histidine sidechain is assumed to be formally charged unless one of its nitrogens is coordinating a metal ion or identified unambiguously as an H-bond acceptor.
restrict  cross | both | any | atom-spec2
Limit H-bond detection to one of the following:    See also options: interSubmodel, interModel, intraModel, intraMol, intraRes
makePseudobonds  true | false
Whether to show the H-bonds in 3D by creating a pseudobond model. The pseudobonds will be drawn between the donor and acceptor atoms, or if hydrogens are present, between the hydrogens and acceptor atoms. H-bond pseudobonds are only displayed when both endpoint atoms are displayed, but the reveal option can be used to ensure showing all H-bonds.

The number of H-bonds found may exceed the apparent number of pseudobonds because the same pair of atoms could be identified as both donor-acceptor and acceptor-donor, even if only one of those interactions could form at a time.

select  true | false
Whether to select the H-bonding atoms (and deselect all other atoms).
reveal  true | false
Whether to display all H-bonding atoms to ensure displaying the H-bond pseudobonds between them. (Hiding an atom also hides its bonds and pseudobonds.) To avoid showing disconnected atoms, the entire residues will be shown, except that amino acid and nucleic acid residues are split into sidechain and backbone moieties separately displayed by this option. Displayed backbone atoms may still be invisible where cartoon is shown, unless their simultaneous display has been enabled with cartoon suppress false.
showDist  true | false
Whether to label the pseudobonds with the corresponding distances. Label color, height, and font can be adjusted with the label command, which can also be used to add the labels later or to delete them. Label height can also be set beforehand in the Labels preferences. The number of decimal places and whether to show the Å symbol can be changed with distance style or set beforehand in the Distances preferences. The distances (pseudobond lengths) can also be plotted as a histogram with crosslinks histogram.
color  color-spec
Color to use for pseudobonds depicting H-bonds (default deep sky blue
), but see also twoColors and slopColor. The color can be changed later, for example with command: color hbonds goldenrod
radius  r
Radius in Å to use for pseudobonds depicting H-bonds (default 0.075); can be changed later with size.
dashes  N
Number of dashes to use for pseudobonds depicting H-bonds (default 6). Only whole numbers are accepted, with 0 indicating solid sticks. Currently, odd numbers are rounded down to give an even number of dashes. The number of dashes can be changed later with style.
name  name
Name for the pseudobond model created to show interactions (default hydrogen bonds, also the default name for deletion). Using a new name creates a separate model that can be hidden/shown/closed independently. Names containing spaces must be enclosed in quotation marks.
interSubmodel  true | false
Whether to look for H-bonds between direct sibling submodels of the same model (those with identical model numbers at all levels except the last, finest level). For example, this setting would affect finding H-bonds between #1.2.1 and #1.2.2 but not between #1.2.1 and #1.3.1.
interModel  true | false
Whether to look for H-bonds between models.
intraModel  true | false
Whether to look for H-bonds within models.
intraMol  true | false
Whether to include intramolecular H-bonds, where a molecule is defined as a covalently bonded set of atoms.
intraRes  true | false
Whether to include intraresidue H-bonds.
cacheDa  true | false
Whether to cache and reuse donor and acceptor information rather than regenerating it each time the command is used; useful for calculations on different conformations of the same structure. The default is true for a trajectory, otherwise false.
coordsets  true | false
Whether to calculate and retain H-bonds for each frame of a trajectory, instead of just the current frame. The default is true for a trajectory if it is the only atomic model present or specified in the command.
relax  true | false
Whether to relax the precise criteria for hydrogen bonding.
distSlop  tolerance
How much to relax the distance criteria if relax is true; tolerance is 0.4 Å by default.
angleSlop  tolerance
How much to relax the angle criteria if relax is true; tolerance is 20.0 degrees by default.
twoColors  true | false
Whether to use different colors for H-bonds meeting and not meeting the precise criteria (i.e., whether a different color should be used for H-bonds outside the precise criteria but within the tolerance values).
slopColor  color-spec
If twoColors is true, the color to use for H-bonds not meeting the precise criteria but within the tolerance values (default dark orange
retainCurrent  true | false
Whether to keep the pseudobonds depicting a previously determined set of H-bonds through a subsequent round of detection (as opposed to replacing the old with the new). Regardless of this setting, however, pre-existing H-bond pseudobonds will not be replaced if the new pseudobond model is given a different name.
updateGroup  true | false
If true, replace H-bond pseudobonds for the currently specified atoms but retain any others (overrides retainCurrent true). Regardless of this setting, however, pre-existing H-bond pseudobonds will not be replaced if the new pseudobond model is given a different name.
saveFile  file
Save H-bond information to a file. The information includes donor and acceptor atom specifications (see namingStyle), donor-acceptor distances, and when hydrogens are present, hydrogen atom specifications and hydrogen-acceptor distances. File is the output file pathname, enclosed in quotation marks if it includes spaces, or the word browse to specify it interactively in a file browser window.
log  true | false
Whether to write H-bond information (as described above for saveFile) to the Log.
namingStyle  simple | command | serial
How to describe atoms in H-bond information written to a file or the log: Model number will be included when multiple models are present. The Labels preference Balloon-help specifier style sets which is the default.
batch  true | false
Whether to suppress error messages that would otherwise appear when  atom-spec1 or  atom-spec2 (given with the restrict option) does not specify any atoms; useful for no-GUI batch processing.

Method and Geometric Criteria

Distance and angle cutoffs for H-bonding are based on a survey of small-molecule crystal structures, as described in

Three-dimensional hydrogen-bond geometry and probability information from a crystal survey. Mills JE, Dean PM. J Comput Aided Mol Des. 1996 Dec;10(6):607-22.
There are many different sets of geometric criteria, corresponding to the many different donor-acceptor combinations (see Tables 5-8 in the reference). There is an upper bound on distance and one or more angular range criteria for each category of H-bond. It is generally useful to relax the criteria since most structures are not as high-resolution as those used in the survey. User-specified tolerances are added to each criterion's upper bound and/or subtracted from its lower bound (depending on the particular criterion).

ChimeraX uses atom and residue names, or if these are not “standard,” the coordinates of atoms, to determine connectivity and atom types, which in turn determine which geometric criteria are appropriate for detecting a hydrogen bond between specific atoms. Possible donor groups are hydrogen-bearing nitrogen, oxygen, and sulfur atoms, and possible acceptor groups are nitrogen, oxygen, and sulfur atoms with a lone pair. H-bonds involving other types of atoms are not considered. Not all of the possible donor-acceptor combinations were listed in the Mills and Dean parameter tables; some categories of sulfur were not surveyed, and several combinations of the surveyed types were not observed frequently enough to collect good statistics on their geometries. In such cases, estimated H-bond criteria are applied.

When there are no explicit hydrogens on a potential donor atom, the donor atom type will be used to infer their presence. For functional groups where the hydrogen positions are well-determined by the positions of the nonhydrogen atoms, the H-bonds detected in the presence and absence of explicit hydrogen atoms should be virtually identical. For functional groups where the hydrogen position is not well-determined (such as rotatable hydroxyls), the presence of an explicit hydrogen atom will limit the detected H-bonds to those appropriate for the observed position, instead of all of its possible positions.

UCSF Resource for Biocomputing, Visualization, and Informatics / November 2023