NAME

       Chemistry::Formula - Enumerate elements in a chemical formula

SYNOPSIS

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

       That is obviously not a real compound, but it demonstrates the capabilities of the
       routine.  This returns

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

DESCRIPTION

       This module provides a function which parses a string containing a chemical formula and
       returns the number of each element in the string.  It can handle nested parentheses and
       square brackets and correctly computes stoichiometry given numbers outside the (possibly
       nested) parentheses.

       No effort is made to evaluate the chemical plausibility of the formula.  The example above
       parses just fine using this module, even though it is clearly not a viable compound.
       Charge balancing, bond valence, and so on is beyond the scope of this module.

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

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

       If the formula was parsed without trouble, "parse_formula" returns 1. If there was any
       problem, it returns 0 and $count{error} is filled with a string describing the problem.
       It throws an error afer the first error encountered without testing the rest of the
       string.

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

       Here is an example of a program that reads a string from the command line and, for the
       formula unit described in the string, writes the weight and 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 parser is not brilliant.  Here are the ground rules:

       1.  Element symbols must be first letter capitalized.

       2.  Whitespace is unimportant -- it will be removed from the string.  So will dollar
           signs, underscores, and curly braces (in an attempt to handle TeX).  Also a sequence
           like this: '/sub 3/' will be converted to '3' (in 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 that 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.

       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/