Extended support for subperiodic groups

[bfield1]

Since the advent of 2D materials, subperiodic groups have been steadily growing in relevance. Spglib recently implemented a method to identify the layer groups of 2D crystals [1]. The new editor of the International Tables for Crystallography Vol. E has been considering revisions in light of the popularity of 2D materials [2,3]. Bilbao Crystallographic Server also has features tailored specifically for subperiodic groups [4]. Yet, Cryst's support for subperiodic groups is presently minimal.

Subperiodic groups are those with a translation basis with fewer dimensions than the space it occupies. Named examples are layer groups (2D translation in 3D space), rod groups (1D translation in 3D space), and frieze groups (1D translation in 2D space). They can represent lower-dimensional crystals or grain boundaries and line defects in crystals. Cryst can represent subperiodic groups, but many operations available for space groups are not available for subperiodic groups.

This pull request adds support for subperiodic groups to many parts of Cryst. I have been using this fork extensively in my own research, have tested the new functions broadly, and wish to contribute it upstream. Key additions are a database of subperiodic groups from the International Tables and support for Wyckoff positions of subperiodic groups. While this pull request does not add subperiodic group support to every space group function, it should provide a foundation upon which such features can be added.

In the text below, I first detail the new features this pull request adds.
I then note some of the missing features and a niche bug. While I do not believe these issues to be detrimental, if you think these are critical issues, please let me know.
I then discuss the documented interface to the new functions, and highlight a few points where discussion on how to configure these features would be useful.
Finally, I close with a few comments on the challenges of dealing with subperiodic groups which this pull request addresses.

Thank you in advance for your consideration. I welcome any questions or suggestions. I have found Cryst to be useful in my research and I hope that these additions will help others in their study of crystallographic symmetries.

New features

I have two major additions to Cryst. The first is an equivalent to SpaceGroupIT for subperiodic groups. The second is enabling WyckoffPositions to handle subperiodic groups. I also add a new attribute which is important for handling subperiodic groups.

International Tables references

Being able to pull a crystallographic group from the International Tables is incredibly convenient. A good interface should allow specifying the type of group and the setting in a manner compatible with the International Tables.

Here, I create such an interface for subperiodic groups, mimicking the function of SpaceGroupIT and related functions.

I document the following new functions:

• SubPeriodicGroupSettingsIT
• SubPeriodicGroupOnRightIT
• SubPeriodicGroupOnLeftIT
• SubPeriodicGroupIT
• FriezeGroupIT
• RodGroupIT
• LayerGroupIT

The SubPeriodicGroup* functions take a string as the first argument. This string may be either "Frieze", "Rod", or "Layer".
SubPeriodicGroupSettingsIT returns a List of settings for a given group, as SpaceGroupSettingsIT.
The other SubPeriodicGroup* functions return a crystallographic group, as SpaceGroup* functions do. Their second argument is an integer, the IT number of the group. Their optional third argument is the setting, as defined in the International Tables. The returned group has a name of the form SubPeriodicGroupOnRightIT(Layer,10,'a').
FriezeGroupIT, RodGroupIT, and LayerGroupIT are aliases for SubPeriodicGroupIT with the respective first arguments.

The chief design ambiguity was how to represent some of the settings. For layer groups with settings (a,b,c) and (b,-a,c), I abbreviated them to the single characters 'a' and 'b'. For orthorhombic rod groups, with six settings of the form (a,b,c) or permutations (with signs), I opted to use the strings "abc" and permutations, omitting minus signs. The use of strings as the setting breaks with previous design, but the alternative was to use an arbitrary mapping with no obvious correlation to the International Tables.

Wyckoff compatibility

Computing the Wyckoff positions can be useful for understanding the high-symmetry positions and directions in a crystal. Bilbao crystallographic server [5] and the International Tables for Crystallography Volume E [6] present Wyckoff positions for tabulated subperiodic groups in conventional settings. The challenge for Cryst is computing the Wyckoff positions for arbitrary subperiodic groups in arbitrary settings.

WyckoffPositions now supports subperiodic groups of arbitrary dimension in arbitrary settings (although I have only tested tabulated subperiodic groups, but still with arbitrary settings). The other Wyckoff* functions should also work; I have only used WyckoffTranslation, WyckoffBasis, and to a lesser extent WyckoffStabilizer in my own research, but have done cursory testing of the other functions.

The chief change was to properly treat the difference between the internal basis and the translation basis. The core idea was to calculate Wyckoff positions as though the subperiodic group was a space group, but then filtering out the Wyckoff positions which violated the smaller translation basis (and any potential origin shifts) before accepting them. I also made minor modifications to ReduceAffineSubspaceLattice. All changes have been made in such a way that the logic for space groups should be unaffected and the performance for space groups should be roughly unchanged.

Undocumented attribute: SymmetricInternalBasis

The attribute InternalBasis returns the TranslationBasis with a few extra vectors to ensure it spans the full space. These vectors are chosen to be simple Cartesian vectors (e.g. [0,0,1]) with no consideration of the symmetries of the system. However, some operations are sensitive to the symmetries of the system. If the chosen vectors do not align with the high symmetry directions of the crystal, then operations using InternalBasis can give spurious results.

To resolve this, I provide the new attribute SymmetricInternalBasis. This functions similarly to InternalBasis, except the added vectors are chosen to align with high symmetry directions of the group. This won't make a difference for groups in a conventional setting, but for groups in arbitrary settings this is important. Naturally, it returns the TranslationBasis for space groups, where no extra vectors are needed.

Throughout the logic for the Wyckoff positions, I have used SymmetricInternalBasis wherever we needed a basis spanning the full space, which is where we had either InternalBasis or, situationally, TranslationBasis. I also created the undocumented function NiceToCrystStdRepSymmetric, which is a counterpart to NiceToCrystStdRep which works reliably for subperiodic groups.

I made this a different attribute to InternalBasis for two reasons. The first was that I didn't want to alter the behaviour of the documented attribute InternalBasis. The second was that SymmetricInternalBasis is much more expensive to evaluate than InternalBasis.

Known deficiencies

Here I note a known bug in this pull request along with numerous unimplemented features. Nevertheless, I do not believe any of these issues to be an impediment to releasing this code.

There is a bug in WyckoffStabilizer and WyckoffOrbit where, if a group has its standard origin outside the span of its translation basis, it can give spurious results. I've noted this bug in a comment in the code. However, I believe this to be a low priority bug because it is probably unusual to handle groups with such origin shifts. It can probably be patched later (but speak up if you feel differently).

While cached Wyckoff positions are retained during conjugation of space groups, I do not retain them during conjugation of subperiodic groups. This is because of the ambiguity in handling out-of-span components, especially when out-of-span symmetry directions are not unique. It was easier and safer to discard the cache than to attempt a potentially-unreliable transformation.

I have not added support for the normalizers of subperiodic groups. While I surmise that normalizers are important from a group-theoretical perspective, my research so far has not needed them so I haven't spent time developing it. It would be better for someone who uses normalizers to work on this as they would know what the proper use cases are.

The algorithms I have implemented may not be of the highest performance. SymmetricInternalBasis and my added filter to WyckoffPositions are based on linear algebra because that was what I felt confident implementing. However, there may exist some clever group-theoretical algorithm which can do the same thing but faster. Nevertheless, these algorithms function satisfactorily.

ConjugatorSpaceGroups does not have a subperiodic group equivalent. My preliminary in-house development suggests a way to convert it. In finding the mapping between two point groups using RepresentativeAction, one must restrict the matrix group to a subset of GL (or even SL) which keeps separate the subspaces in the translation basis and outside the translation basis. Then, in ConjugatorSpaceGroupsStdSamePG, when getting the normalizer of the point group, one needs to filter its elements to just those which keep the two subspaces separate (one must consider all its elements, not just the generators, as two illegal generators could combine to give a new legal element). However, my current implementation is fragile and non-portable, so is not included in Cryst.

Design decisions

Here I detail important decisions to be made regarding the documented behaviour of the new functions.

The new functions which were added to the documentation are those related to the International Tables. I describe their behaviour in an earlier section. Because they are documented, we need to agree on the public interface.

The names for the functions were determined by replacing Space with SubPeriodic, Frieze, Rod, or Layer. I believe this to be a sensible naming convention. Although one might also consider Subperiodic instead of SubPeriodic, as it is nominally one word. I had no special reason for picking the latter, besides that being what I felt like at the time. If you have a preference for one over the other, let me know.

I decided to identify the different dimensionalities of subperiodic group using strings, giving their named descriptions. This is unlike space groups, where they could be identified by a single integer. Subperiodic groups would require two integers to represent by dimensionality. As there are only three different cases of tabulated subperiodic group, this would be rather bloated. As such, I went with the more straight-forward string representations "Layer", "Rod", and "Frieze".

On representing the setting, probably the most contentious issue is representing the settings of the orthorhombic rod groups. The six settings, according to the International Tables [7], are (a,b,c), (b,-a,c), (-c,b,a), (b,c,a), (a,-c,b), and (-c,-a,b). I chose to represent these with the strings "abc", "bac", "cba", "bca", "acb", and "cab". The International Tables do not offer any more compact representation, so I chose these strings for compatibility with the International Tables. This is a break from the existing convention of all settings in Cryst being single characters, which are distinct objects from strings in GAP. If we had to use a single character, we could assign them a number from 1 to 6, but this would require the user to dig in the documentation to interpret.

Regarding SymmetricInternalBasis, I have kept it undocumented for now. The choice of extra basis vectors is not necessarily unique, so a change in algorithm might change the result. It always starts with TranslationBasis. I choose the extra vectors such that the basis is right-handed (i.e. Determinant(SymmetricInternalBasis(G)) = 1) and forms a lattice that obeys the group symmetries. Otherwise, I make no particular guarantee about the exact choice of added basis vectors. I used ReducedLatticeBasis on the Orbit of the point group on the vectors to improve consistency, but there are some semi-arbitrary degrees of freedom and possibilities of algorithmic tweaks that will change results.

Why subperiodic groups are difficult

The chief challenge in dealing with subperiodic groups is that their translation basis does not span the full space. This results in many ambiguities not present in space groups. How do you transform to standard form? What is standard form? How do you handle origin shifts not in the span of the translation basis? How do you respect symmetry directions outside the span of the translation basis? How do you handle different basis vectors being inequivalent?

To transform to standard form, I use SymmetricInternalBasis and transform such that it becomes the identity. Using SymmetricInternalBasis respects all the symmetry directions, not just those in the span of the translation basis. It should be noted, though, that this "standard form" might not be unique. One could pick other basis vectors which respect the symmetries, which would give a different "standard form". Care must then be taken in any algorithm which compares subperiodic groups in "standard form". (This can happen for space groups too; you can standardise using any primitive unit cell. But the problem has extra freedom in subperiodic groups.)

Finding this symmetry-preserving internal basis takes care. It cannot be deduced from the translation basis alone. Instead, one must identify the rotation axes, mirror planes, mirror normals, and rotation planes of all the symmetry operations, or at least the generators. This can be found by their eigenvectors. Then one must choose the most specific directions and select lengths such that the vectors lie within each others' orbits where applicable. But this is a solved problem now.

The possibility of the crystal not intersecting the coordinate origin is another insidious issue. I address it in calculating the translation and basis of Wyckoff positions, using the extensive logic in the new internal function IsTranslationInBasis. However, an off-axis origin may still cause issues in other parts of the code base. This is a harder problem to make a generic solution for, because how precisely it is an issue depends on the task at hand. It will need to be considered in future development.

That subperiodic groups are non-trivial to deal with is precisely why having a code-base which handles them is so valuable. Including this pull request in Cryst will help in the research of symmetries in defects and 2D materials as well as our fundamental understanding of crystallographic symmetries.

[codecov]

Codecov Report

Attention: Patch coverage is 97.44483% with 44 lines in your changes missing coverage. Please review.

Project coverage is 95.22%. Comparing base (87ba2fd) to head (7b6c019).
Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
gap/wyckoff.gi	85.65%	32 Missing ⚠️
grp/subgrp.gi	90.16%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #53      +/-   ##
==========================================
+ Coverage   94.50%   95.22%   +0.72%     
==========================================
  Files          24       27       +3     
  Lines        7582     9285    +1703     
==========================================
+ Hits         7165     8842    +1677     
- Misses        417      443      +26     

Files with missing lines	Coverage Δ
gap/cryst.gi	86.92% <100.00%> (+1.15%)	⬆️
gap/hom.gd	100.00% <100.00%> (ø)
gap/hom.gi	85.91% <100.00%> (+3.77%)	⬆️
gap/wyckoff.gd	100.00% <100.00%> (ø)
grp/subgrp.gd	100.00% <100.00%> (ø)
grp/subgrp.grp	100.00% <100.00%> (ø)
grp/subgrp.gi	90.16% <90.16%> (ø)
gap/wyckoff.gi	88.24% <85.65%> (+0.45%)	⬆️

... and 1 file with indirect coverage changes