Find(3)

📦 version 0.23, in fedora 44

okay bestie, welcome to Find(3) — it's giving User Contributed Perl Documentation, and it's all about bonds. buckle up, we're doing chemistry. 💅✨

✨ NAME ✨

Chemistry::Bond::Find — detects bonds in a molecule from atomic 3D coordinates, and assigns formal bond orders. that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

use Chemistry::Bond::Find ':all'; # export all available functions

# $mol is a Chemistry::Mol object
find_bonds($mol);
assign_bond_orders($mol);

💖 DESCRIPTION 💖

so this module hands you functions that sniff out the bonds in a molecule using its 3D coordinates and some simple cutoffs, and then it also guesses the formal bond orders for you. lowkey iconic of it. 😌

this module is part of the PerlMol project, <http://www.perlmol.org/>. 🧚

🔥 FUNCTIONS 🔥

these functions can be exported, but nothing is exported by default, bestie. you gotta ask for it.

⭐ find_bonds($mol, %options)

finds the bonds in a molecule and adds them. 🎀

okay so important: only use this on molecules that have no explicit bonds. like, for example, right after you read a file that had 3D coordinates but no bond orders. don't be out here double-bonding your molecule, it's not the move. 😭

🌈 the options

  • tolerance — defaults to 1.1. two atoms are considered bound if the distance between them is less than the sum of their covalent radii multiplied by the tolerance. simple math, slay.
  • margin — NOTE: in general, setting this option is not recommended, unless you know what you are doing. 🙈 it's used by the space partitioning algorithm to figure out the "bucket size". it defaults to 2 * Rmax * tolerance, where Rmax is the largest covalent radius among the elements found in the molecule. for example, if a molecule has C, H, N, O, and I, then Rmax = R(I) = 1.33, so the margin defaults to 2 * 1.33 * 1.1 = 2.926. this margin ensures that no bonds are missed by the partitioning algorithm.

using a smaller value gives you faster results, but at the risk of missing some bonds. in that same example, if you are certain your molecule doesn't contain I-I bonds (but it does have C-I bonds), you can set margin to (0.77 + 1.33) * 1.1 = 2.31 and you still won't miss any bonds (0.77 is the radius of carbon). this only has a significant impact for molecules with a thousand atoms or more, but it can reduce the execution time by 50% in some cases. okay that's kind of a big deal. 💀

  • orders — if true, assign the bond orders after finding them, by calling assign_bond_orders($mol, %opts). teamwork!
  • bond_class — the class that will be used for creating the new bonds. the default is the bond class returned by $mol->bond_class.

💜 assign_bond_orders($mol, %opts)

assigns the formal bond orders in a molecule. 🫶

the bonds must already be defined — either by find_bonds, or because the molecule was read from a file that included bonds but no bond orders. and bestie, listen: if the bond orders were already defined (maybe the molecule came from a file that did include bond orders after all), then the original bond orders get erased and the whole process begins from scratch. no survivors. 💅

there are two different algorithms available, and you pick one with the method option:

assign_bond_orders($mol, method => 'itub');
assign_bond_orders($mol, method => 'baber');

🧚 itub

this is the default if no method is specified. developed from scratch by the author of this module, this algorithm only needs the connection table information, and it requires that all hydrogen atoms be explicit. it looks for an atom with unsatisfied valence, increases a bond order, and then does the same recursively for the neighbors. if everybody's not happy at the end, it backtracks and tries another bond. the recursive part doesn't cover the whole molecule, only the contiguous region of "unhappy" atoms next to the starting atom and their neighbors. this lets it separate the molecule into independent regions, so that if one is solved and there's a problem in another, we don't have to backtrack to the first one. it's giving divide and conquer, honestly. 👑

the itub algorithm has these extra options:

  • use_coords — even though the algorithm doesn't require 3D coordinates, it uses them by default to improve the initial guesses of which bond orders should be increased. to avoid using coordinates, add the use_coords option with a false value:
assign_bond_orders($mol, use_coords => 0);

the results are the same most of the time, but using good coordinates improves the results for complicated cases such as fused heteroaromatic systems. 🦋

  • scratch — if true, start the bond order assignment from scratch by assuming that all bond orders are 1. if false, start from the current bond orders and try to fix the unsatisfied valences. this option is true by default.

🌸 baber

a bond order assignment algorithm based on Baber, J. C.; Hodgkin, E. E. J. Chem. Inf. Comp. Sci. 1992, 32, 401-406 (with some interpretation).

this algorithm uses the 3D coordinates along with various cutoffs and confidence formulas to guess the bond orders. then it tries to resolve conflicts by looping through the atoms (but it is not recursive or backtracking). it does not require explicit hydrogens (although it's better when they are available) because it was designed for use with real crystallographic data, which often doesn't have hydrogen atoms.

ngl this method doesn't always give a good answer, especially for conjugated and aromatic systems. 💀 the variation used in this module adds some random numbers to resolve some ambiguities and break loops, so the results are not even entirely deterministic. (the 'itub' method is deterministic, but its result may depend on the input order of the atoms.)

🎀 VERSION 🎀

0.23

🦋 TO DO 🦋

  • some future version should let the user specify the desired cutoffs, and not always create a bond but call a user-supplied function instead. this way these functions could be used for other purposes, such as finding hydrogen bonds or neighbor lists. manifesting it. ✨
  • add some tests. 😭

🌈 SEE ALSO 🌈

Chemistry::Mol, Chemistry::Atom, Chemistry::Bond, <http://www.perlmol.org/>.

👑 AUTHOR 👑

Ivan Tubert-Brohman<itub@cpan.org>

the new find_bonds algorithm was loosely based on a suggestion by BrowserUK on perlmonks.org (<http://perlmonks.org/index.pl?node_id=352838>). credit where credit is due, periodt. 💖

Copyright (c) 2009 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie 🫶 this was perl v5.42.0, dated 2026-01-17, and yeah — it's Find(3). go forth and find some bonds. 🍓✨

📦 where this page comes from