Provided by: libxray-spacegroup-perl_0.1.1-4_all bug

NAME

       Xray::SpaceGroup - Symmetry operations for the crystal space groups

VERSION

       This documentation refers to libperlxray version 0.1.

SYNOPSIS

          my $sg = Xray::SpaceGroup -> new("Pm3m");
          $sg -> fix({a     => $a,     b    => $b,    c     => $c,
                      alpha => $alpha, beta => $beta, gamma => $gamma})
          @symmetry_ops  = $sg -> positions;
          @bravais_trans = $sg -> bravais;
          print $sg -> report;

       The two lists can be used to populate a unit cell, given a set of Wyckoff positions.  The
       report is a user-readable summary of the properties of the space group.

DESCRIPTION

       This provides an object-oriented interface to a database of space group symmetries
       transcribed from volume A of the International Tables for Crystallography.

METHODS

   Accessor Methods
       "new"
           This creates a new Xray::SpaceGroup object.

             my $sg = Xray::SpaceGroup -> new({group=>"Pm3m"});

           The space group symbol can be a Hermann-Maguin symbol, a Schoenflies symbol, the
           number of the space group, one of several nicknames (diamond, cscl, etc), or a few
           other symbols from the International Tables.

           The H-M symbol can contain any number of spaces and is case insensitive.  An overscore
           is indicated by a leading dash ("-") and a subscript is simply written as a normal
           character, as in "p 42 3 2" where "4 sub 2" is written as 42.  A slash is indicated by
           a forward slash ("/").

           The sub- and superscripts of the Schoenflies symbol can come in either order and are
           indicated by caret ("^") and underscore ("_").

           The nicknames are as follows:

               symbol       number        nicknames
              ------------------------------------------------------------
               p 63 m c      186        graphite, gra
               p 63/m m c    194        hex, hcp
               f -4 3 m      216        zincblende, zns
               p m -3 m      221        cubic, cscl, perov, perovskite
               f m -3 m      225        fcc, salt, nacl
               f m -3 d      227        diamond
               i m -3 m      229        bcc

       "fix"
           Set the crystal setting based on the values of the lattice constants and verify that
           the lattice constants make sense for the selected crystal class.

              $sg -> fix({a     => $a,     b    => $b,    c     => $c,
                          alpha => $alpha, beta => $beta, gamma => $gamma})

           The first chore of this method is quite necessary for a space group with multiple
           settings.  Selecting the correct setting requires knowledge of the lattice parameters.
           For many space groups, including all cubic groups, this is a no-op.

       "warning"
           This will return a non-empty string if a problem was found in the "fix" method.  Most
           such problems result from a mismatch between the lattice constant values and what is
           expected for the crystal class.  For instance, if a monoclinic space group symbol is
           given but all three angles are 90 degrees, a warning will be returned by this method.
           This sort of problem rarely requires that your program stops, so no explicit exception
           is thrown when "fix" finds a problem.  If you want to know whether a problem was
           found, you must explicitly call this method.

       "positions"
           This method is the meaty part of this module.  This returns a list of lists containing
           the symmetry operations for your space group and the appropriate crystal setting.
           Here is an example using a monoclinic space group, which has a short list of symmetry
           operations.

               use Data::Dumper;
               my $sg = Xray::SpaceGroup -> new({group=>'7'});
               my @positions = $sg->positions;
               print Data::Dumper->Dump([\@positions], [qw(positions)]);
                 ==prints==>
                   $positions = [
                                 [ '$x', '$y', '$z'      ],
                                 [ '$x', '-$y', '$z+1/2' ]
                                ];

           The elements of these lists are strings and are intended to be evaluated using perl's
           eval function.  For example, if you have a Wyckoff position of "(0.2, 0.3, 0.4)", then
           you might do this:

               ($x, $y, $z) = (0.2, 0.3, 0.4);
               @pos0 = (eval "$positions[0]->[0]",
                        eval "$positions[0]->[1]",
                        eval "$positions[0]->[2]"  );
               @pos1 = (eval "$positions[1]->[0]",
                        eval "$positions[1]->[1]",
                        eval "$positions[1]->[2]"  );

           This will result in "@pos0 = (0.2, 0.3, 0.4)" and "@pos2 = (0.2, -0.3, 0.9)".  You
           would, in practice, wrap these evaluations inside proper control structures.  You
           might also use a Safe compartment if you are worried about the possibility of the
           database having been tainted.

           For high symmetry groups and high symmetry Wyckoff positions, these evaluations will
           generate the same positions repeatedly.  It is the responsibility of your application
           to weed out these repetitions.

       There are also "set" and "get" methods, but properties of the space group should be
       obtained via the reporting methods listed below.

   Reporting Methods
       "report"
           This writes a summary of the properties of the space group in a human-readable form.

              my $space = Xray::SpaceGroup -> new({group=>7});
              print join(", ", $space->bravais), $/;
               ==prints==>
                  Space group: p c (7)
                    supplied symbol        : 7
                    crystal class          : monoclinic
                      Schoenflies symbol   : c_s^2
                      crystal setting      : b_unique_1
                      Bravais translations :
                        none
                      Positions :
                        $x           $y           $z
                        $x           -$y          $z+1/2

       "group"
           This returns the canonical space symbol for this space group.

              print $sg->group, $/;
               ==prints==>
                  p m -3 m

       "given"
           This returns the space symbol supplied when the object was created.

              print $sg->given, $/;
               ==prints==>
                  Pm3m

       "number"
           This returns the number of the space group as in the International Tables.

              print $sg->number, $/;
               ==prints==>
                  221

       "full"
           This returns the full symbol of the space group as in the International Tables.

              print $sg->full, $/;
               ==prints==>
                  p 4/m -3 2/m

       "schoenflies"
           This returns the Schoenflies symbol of the space group.

              print $sg->schoenflies, $/;
               ==prints==>
                  o_h^1

       "thirtyfive"
           This returns the symbol of the space group as it appeared in the 1935 edition of the
           International Tables, if it was different from the canonical symbol.  Otherwise this
           returns an empty string.

              print $sg->thirtyfive, $/;
               ==prints==>
                  p m 3 m

       "newsymbol"
           This returns the new symbol of the space group as introduced by the IUCr nomenclature
           report of 1992.  Only a handful of groups with glide planes have new symbols.  An
           empty string is returned for most groups.

              my $sgnew = Xray::SpaceGroup -> new({group=>"a b a 2"});
              print $sgnew->newsymbol, $/;
               ==prints==>
                  a e a 2

       "class"
           This returns the crystal class of the space group

              print $sg->class, $/;
               ==prints==>
                  cubic

       "setting"
           This returns the setting of the space group using the nomenclature of the database
           used by this module.  If there is only one setting, this returns 0.

           For rhombohedral space groups, this returns a string -- either "positions" or
           "rhombohedral" -- indicating which set of symmetry operations should be used.

           For most monoclinic groups, this returns one of "b_unique", "c_unique", or "a_unique",
           indicating which set of symmetry operations should be used.  If the beta angle is not
           90 degrees, the "b_unique" setting should be used.  If the gamma or alpha angles are
           not 90 degrees, the "c_unique" or "a_unique" settings should be used, respectively.

           For several monoclinic space groups, there are additional settings for each unique
           axis. These are indicated as "b_unique_1", "b_unique_2", "b_unique_3", and so on.

       "bravais"
           This returns a 0, 3, 6, or 9 element list containing the Bravais translation vectors
           associated with the space group.

              my $diamond = Xray::SpaceGroup -> new({group=>"f d -3 m"});
              print join(", ", $diamond->bravais), $/;
               ==prints==>
                   0.000, 0.500, 0.500, 0.500, 0.000, 0.500, 0.500, 0.500, 0.000

           Each triplet is a Bravais translation.

           The Bravais translations attempt to be sensitive to the specified crystal setting.  If
           you use ambiguous input (i.e. the number or the Schoenflies symbol) it is possible
           that a Bravais translation other than the one you want will be returned.  The
           telepathic interface is planned for version 2.0.

COERCIONS

       When the reference to the Xray::SpaceGroup object is used in string context, the "group"
       method is returned.  When used in numerical context, the "number" method is returned.

CONFIGURATION AND ENVIRONMENT

       This requires that the space_groups.db file, which is generated by the space_groups.db.PL
       script, be installed in the correct location.  There are no other configuration options.

DEPENDENCIES

       This module uses several things from the standard distribution along with:

       Class::Std

       List::MoreUtils

       Readonly

       Regexp::List

BUGS AND LIMITATIONS

       Missing features:

       •   Groups 5, 8, 12 list 9 symbols, but 3 sets of positions.  What's up with that?

       •   Groups 12 - 15, short notation is ambiguous, requires angles to resolve.

       •   "_determine_monoclinic" should use alpha/beta/gamma, "_canonicalize_group" already
           parsed the given_group

       •   Recognize setting for R groups

       •   Rotate symmetry ops for orthorhombic groups to the setting specified by the symbol.
           In atoms, I rotate the coordinates and rotate them back.  Rotating the symmetry ops is
           a better, more general purpose solution.

       •   Handle alternate tetragonal group settings here rather than in the application.

       Please report problems to Bruce Ravel (bravel AT bnl DOT gov)

       Patches are welcome.

AUTHOR

       Bruce Ravel (bravel AT bnl DOT gov)

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

ACKNOWLEDGEMENTS

       Julie Cross and Matt Newville gave me a copy of volume A of the International Tables for
       Crystallography as a graduation present from grad school.  Was that a blessing or a curse?

       Saulius Grazulis, whose useful feedback inspired this most recent rewrite of this code.
       Earlier versions of Atoms benefited from the help and criticism of Shelly Kelly, Daniel
       Haskel, Chuck Bouldin, Hannes Fischer, Glenn Forney, Chris Glover, John Rehr, Hubert
       Renevier, Julia Wienold, Andrzej Wilamowski, Boyan Boyanovich, Ed Stern, Hans Stragier,
       Kalle Voss, Steve Zabinsky, and Yanjun Zhang.  All the users of my codes over the years
       have driven me to provide the best possible code.

LICENCE AND COPYRIGHT

       Copyright (c) 1999-2008 Bruce Ravel (bravel AT bnl DOT gov). All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself. See perlartistic.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.