Chemis...ormula(3pm)

✨ NAME ✨

Chemistry::Formula — Enumerate elements in a chemical formula 💖

(yes bestie, it's a Perl module, from the User Contributed Perl Documentation, section 3pm — we love a glow-up 🦋)

---

🌸 SYNOPSIS 🌸

use Chemistry::Formula qw(parse_formula);
parse_formula('Pb (H (TiO3)2 )2 U [(H2O)3]2', \%count);

okay so that is obviously not a real compound, but it's literally just flexing what the routine can do, no cap. It returns:

%count = (
          'O' => 18,
          'H' => 14,
          'Ti' => 4,
          'U' => 1,
          'Pb' => 1
         );

iconic behavior, honestly. 🎀

---

💅 DESCRIPTION 💅

So this module gives you one function that parses a string holding a chemical formula and hands back how many of each element are in that string. It handles nested parentheses and square brackets, and it correctly computes stoichiometry when there are numbers hanging out outside the (possibly nested) parentheses. Obsessed. 🫶

Fair warning: it makes zero effort to evaluate the chemical plausibility of the formula. That example up top parses just fine with this module even though it is clearly not a viable compound. Charge balancing, bond valence, and so on? beyond the scope of this module, bestie. Not its job. 🙈

Only one function is exported: parse_formula. It takes a string and a hash reference as its arguments, and it returns 0 or 1.

$ok = parse_formula('PbTiO3', \%count);

• If the formula got parsed without any trouble, parse_formula returns 1. ✨
• If there was any problem, it returns 0, and $count{error} gets filled with a string describing what went wrong.
• Heads up: it throws an error after the first error it hits without testing the rest of the string. So it's not gonna collect all your mistakes for you, it's gonna stop at the first one and dip. 😭

If the formula was parsed correctly, the %count hash has element symbols as its keys and the number of each element as its values. Simple as that. 💜

---

🧪 A lil example program 🧪

Here's a program that reads a string off the command line and, for the formula unit described in that string, writes out the weight and the absorption in barns:

use Data::Dumper;
use Xray::Absorption;
use Chemistry::Formula qw(parse_formula);

parse_formula($ARGV[0], \%count);

print  Data::Dumper->Dump([\%count], [qw(*count)]);
my ($weight, $barns) = (0,0);
foreach my $k (keys(%$count)) {
  $weight +=
    Xray::Absorption -> get_atomic_weight($k) * $count{$k};
  $barns  +=
    Xray::Absorption -> cross_section($k, 9000) * $count{$k};
};
printf "This weighs %.3f amu and absorbs %.3f barns at 9 keV.\n",
  $weight, $barns;

Pretty simple. 💖

---

📝 The ground rules 📝

ngl, the parser is not brilliant. Here's the whole vibe:

1. Element symbols must be first letter capitalized. (Ti, not TI, not ti — periodt. 👑)
2. Whitespace is unimportant — it will be removed from the string. So will dollar signs, underscores, and curly braces (that's an attempt to handle TeX). Also, a sequence like this: '/sub 3/' will be converted to '3' (that one's an attempt to handle INSPEC).
3. Numbers can be integers or floating point numbers. Things like 5, 0.5, 12.87, and .5 are all acceptible, as is exponential notation like 1e-2. Note: exponential notation must use a leading number to avoid confusion with element symbols. That is, 1e-2 is ok, but e-2 is not. 🚫
4. Uncapitalized symbols or unrecognized symbols will flag an error.
5. An error will be flagged if the number of open parens is different from the number of close parens. (Balance your brackets, bestie, it's giving self-care 🌸)
6. An error will be flagged if any unusual symbols are found in the string.

---

🌈 ACKNOWLEDGMENTS 🌈

This was written at the suggestion of Matt Newville, who tested early versions. 🫶

The routine matchingbrace was swiped from the C::Scan module, which can be found on CPAN. C::Scan is maintained by Hugo van der Sanden.

---

👑 AUTHOR 👑

Bruce Ravel <bravel AT bnl DOT gov>

http://cars9.uchicago.edu/~ravel/software/

SVN repository: http://cars9.uchicago.edu/svn/libperlxray/

---

aaaand that's the whole page, bestie 💅 ok so this was perl v5.32.0, dated 2021-01-07, and it lives in the manual as Chemis...ormula(3pm). go parse something cursed, ily 🎀🦋✨