Xray::SpaceGroup(3pm)

💖 Xray::SpaceGroup 💖

perl's User Contributed Documentation — welcome to the Xray::SpaceGroup(3pm) page, bestie. Buckle up, we're doing crystallography 💅

---

✨ NAME ✨

Xray::SpaceGroup — symmetry operations for the crystal space groups 🦋

✨ VERSION ✨

This documentation refers to libperlxray version 0.1. Yes, one whole version. Baby steps, periodt.

✨ 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;

So the two lists — positions and bravais — are literally the blueprint you use to populate a unit cell once you've got yourself a set of Wyckoff positions. And report? That's the user-readable glow-up summary of everything your space group is about. Obsessed. 💖

✨ DESCRIPTION ✨

Okay so here's the vibe: this module is an object-oriented interface to a whole database of space group symmetries. And where did those symmetries come from? They were transcribed from volume A of the International Tables for Crystallography. Academic. Iconic. No cap. 📚👑

✨ METHODS ✨

🌸 Accessor Methods 🌸

new

Creates a brand new Xray::SpaceGroup object. Fresh out of the box, main character energy ✨

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

Now, the space group symbol you hand over can be a lot of things, and honestly she's flexible:

• 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 is case insensitive and can have literally any number of spaces in it, she does not care. Here's the notation tea:

• an overscore is written as a leading dash (-)
• a subscript is just written as a normal character — like in p 42 3 2 where "4 sub 2" gets typed as 42
• a slash is written as a forward slash (/)

For the Schoenflies symbol, the sub- and superscripts can show up in either order, and they're marked with a caret (^) and an underscore (_).

And now the nicknames, bestie, the fun part 🎀:

 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

Sets the crystal setting based on your lattice constants, and then double-checks that those lattice constants actually make sense for the crystal class you picked. It's giving responsible friend who reads the terms and conditions 💅

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

Why does this matter? Because for a space group with multiple settings, you need to know the lattice parameters to pick the right one. So yeah, this first chore is genuinely necessary. For a ton of space groups though — including literally every cubic group — this is a total no-op. Nothing happens. She just vibes. 😌

warning

Returns a non-empty string if fix ran into a problem. Most of those problems are a mismatch between the lattice constant values and what the crystal class expects. Classic example: you hand her a monoclinic space group symbol but all three angles are 90 degrees — boom, this method has something to say about it.

But here's the important bit: this kind of problem rarely means your program should stop, so no exception gets thrown when fix finds trouble. If you wanna know whether something went wrong, you have to explicitly call this method yourself. She will not come to you. You come to her. 🫶

positions

Okay THIS one is the meaty part of the whole module. 🍓

This returns a list of lists containing the symmetry operations for your space group, in the appropriate crystal setting. Here's an example with a monoclinic space group, since those have a nice short list of symmetry ops:

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 those lists are strings, and they're meant to be evaluated with perl's eval function. So if you've got a Wyckoff position of "(0.2, 0.3, 0.4)", you'd do something like:

($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]"  );

And that gives you "@pos0 = (0.2, 0.3, 0.4)" and "@pos2 = (0.2, -0.3, 0.9)". ✨

In practice you'd want to wrap those evaluations inside proper control structures, okay? Don't just raw-dog eval out here. And if you're worried the database might have been tainted, a Safe compartment is your friend. Stay safe bestie 🙈

One more thing: for high symmetry groups and high symmetry Wyckoff positions, these evaluations are gonna generate the same positions over and over. Weeding out those repetitions? That's your application's job, not hers. She's just handing you the math.

There are also set and get methods hanging around, but honestly, properties of the space group should be gotten via the reporting methods listed below. That's the move. 💅

🌈 Reporting Methods 🌈

report

Writes a summary of the space group's properties in a human-readable form. Cute and informative, the total package 🎀

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

Returns the canonical space symbol for this space group.

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

given

Returns the space symbol that was supplied when the object was created. The receipts, basically 🧾

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

number

Returns the number of the space group, exactly as it appears in the International Tables.

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

full

Returns the full symbol of the space group as in the International Tables.

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

schoenflies

Returns the Schoenflies symbol of the space group.

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

thirtyfive

Returns the symbol of the space group as it appeared in the 1935 edition of the International Tables — but only if it was different from the canonical symbol. If it wasn't different, you get an empty string. Throwback edition, love that for her 🕰️

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

newsymbol

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 got new symbols, so for most groups you just get an empty string. Exclusive club, honestly 👑

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

class

Returns the crystal class of the space group.

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

setting

Returns the setting of the space group, using the nomenclature of the database this module uses. If there's only one setting? You get 0. Simple as that.

For rhombohedral space groups, this returns a string — either "positions" or "rhombohedral" — telling you which set of symmetry operations to use.

For most monoclinic groups, you get one of "b_unique", "c_unique", or "a_unique", again telling you which set of symmetry operations to use. Here's the tea on which one:

• if the beta angle isn't 90 degrees → use "b_unique"
• if the gamma angle isn't 90 degrees → use "c_unique"
• if the alpha angle isn't 90 degrees → use "a_unique"

And for several monoclinic space groups there are extra settings for each unique axis, which show up as "b_unique_1", "b_unique_2", "b_unique_3", and so on. The saga continues 💅

bravais

Returns a 0, 3, 6, or 9 element list holding 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 in there is one Bravais translation. 🦋

Now, these Bravais translations try to be sensitive to the crystal setting you specified. But if you feed her ambiguous input — like the number, or the Schoenflies symbol — it's possible you'll get back a Bravais translation that isn't the one you actually wanted. Oops.

The telepathic interface is planned for version 2.0. 😭 (yes, really, that's in the docs, we love a cheeky author)

✨ COERCIONS ✨

When the reference to the Xray::SpaceGroup object gets used in string context, you get the group method back. When it's used in numerical context, you get the number method back. She adapts. Versatile queen 💅

✨ CONFIGURATION AND ENVIRONMENT ✨

This requires the space_groups.db file — which is generated by the space_groups.db.PL script — to be installed in the correct location. That's it. There are no other configuration options. Very low maintenance, we stan 🌸

✨ DEPENDENCIES ✨

Uses a few things from the standard distribution, plus:

• Class::Std
• List::MoreUtils
• Readonly
• Regexp::List

✨ BUGS AND LIMITATIONS ✨

Missing features, aka the "to-do list but make it chaotic" section:

• 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 🫶

Okay so bestie, we gotta give credit where credit is SO deserved, because this page did not write itself and neither did the code 💖

• 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? 😭 honestly still undecided, no cap.
• Saulius Grazulis, whose useful feedback inspired this most recent rewrite of this code. king behavior, fr fr 👑
• 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. the whole squad 🫶✨
• And literally all the users of my codes over the years have driven me to provide the best possible code. y'all are the main character energy that keeps this repo alive 💅

---

📜 LICENCE AND COPYRIGHT 📜

Copyright (c) 1999-2008 Bruce Ravel (<code>bravel AT bnl DOT gov</code>). 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. 🙈 like, it's giving "use at your own risk" but make it legally binding.

---

that's the whole page bestie!! you made it to the end, iconic behavior, truly ate 💖✨👑

This lil gem lives in the perl v5.34.0 docs and got stamped 2022-06-28 under the name Xray::SpaceGroup(3pm) in the User Contributed Perl Documentation section. go forth and space-group responsibly 🦋🌸💜