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.