0
# Symmetry & Crystallography
1
2
Space group analysis, point group operations, crystallographic symmetry detection, and high-symmetry k-point path generation for band structures. These tools provide comprehensive crystallographic analysis capabilities for materials science applications including structure refinement, symmetry-based property predictions, and electronic band structure calculations.
3
4
## Capabilities
5
6
### Space Group Analysis
7
8
Comprehensive space group detection and analysis using international crystallographic standards.
9
10
```python { .api }
11
class SpacegroupAnalyzer:
12
"""
13
Comprehensive space group analysis of crystal structures.
14
15
Parameters:
16
- structure: Structure object to analyze
17
- symprec: Symmetry precision tolerance
18
- angle_tolerance: Angle tolerance for symmetry detection in degrees
19
"""
20
def __init__(self, structure, symprec=0.01, angle_tolerance=5): ...
21
22
def get_space_group_number(self):
23
"""
24
Get International Tables space group number.
25
26
Returns:
27
int: Space group number (1-230)
28
"""
29
30
def get_space_group_symbol(self):
31
"""
32
Get Hermann-Mauguin space group symbol.
33
34
Returns:
35
str: Space group symbol (e.g., "Pm-3m")
36
"""
37
38
def get_hall_number(self):
39
"""
40
Get Hall space group number.
41
42
Returns:
43
int: Hall number (1-530)
44
"""
45
46
def get_point_group_symbol(self):
47
"""
48
Get crystallographic point group symbol.
49
50
Returns:
51
str: Point group symbol (e.g., "m-3m")
52
"""
53
54
def get_crystal_system(self):
55
"""
56
Get crystal system classification.
57
58
Returns:
59
str: Crystal system (cubic, tetragonal, etc.)
60
"""
61
62
def get_lattice_type(self):
63
"""
64
Get Bravais lattice type.
65
66
Returns:
67
str: Lattice type (P, I, F, C, etc.)
68
"""
69
70
def get_symmetry_operations(self, cartesian=False):
71
"""
72
Get all symmetry operations for the space group.
73
74
Parameters:
75
cartesian: Whether to return operations in Cartesian coordinates
76
77
Returns:
78
list: List of SymmOp objects
79
"""
80
81
def get_symmetry_dataset(self):
82
"""
83
Get complete symmetry dataset from spglib.
84
85
Returns:
86
dict: Complete symmetry information
87
"""
88
89
def get_symmetrized_structure(self):
90
"""
91
Get structure with symmetry information attached.
92
93
Returns:
94
SymmetrizedStructure: Structure with symmetry data
95
"""
96
97
def is_laue(self):
98
"""
99
Check if structure has Laue symmetry (inversion center).
100
101
Returns:
102
bool: True if structure has inversion symmetry
103
"""
104
105
def find_primitive(self, keep_site_properties=False):
106
"""
107
Find primitive cell using symmetry analysis.
108
109
Parameters:
110
keep_site_properties: Whether to keep site properties
111
112
Returns:
113
Structure: Primitive cell structure
114
"""
115
116
def get_conventional_standard_structure(self, international_monoclinic=True,
117
symprec=None, angle_tolerance=None):
118
"""
119
Get conventional standard structure.
120
121
Parameters:
122
international_monoclinic: Whether to use international monoclinic setting
123
symprec: Symmetry precision override
124
angle_tolerance: Angle tolerance override
125
126
Returns:
127
Structure: Conventional standard structure
128
"""
129
130
def get_primitive_standard_structure(self, international_monoclinic=True,
131
symprec=None, angle_tolerance=None):
132
"""
133
Get primitive standard structure.
134
135
Parameters:
136
international_monoclinic: Whether to use international monoclinic setting
137
symprec: Symmetry precision override
138
angle_tolerance: Angle tolerance override
139
140
Returns:
141
Structure: Primitive standard structure
142
"""
143
144
def get_refined_structure(self, keep_site_properties=True):
145
"""
146
Get refined structure with idealized atomic positions.
147
148
Parameters:
149
keep_site_properties: Whether to keep site properties
150
151
Returns:
152
Structure: Refined structure
153
"""
154
155
def get_ir_reciprocal_mesh(self, mesh=(10, 10, 10), is_shift=(0, 0, 0)):
156
"""
157
Get irreducible k-points in reciprocal space mesh.
158
159
Parameters:
160
mesh: K-point mesh dimensions
161
is_shift: K-point mesh shift
162
163
Returns:
164
tuple: (k_points, weights, grid_address, grid_mapping)
165
"""
166
167
def get_ir_reciprocal_mesh_map(self, mesh=(10, 10, 10), is_shift=(0, 0, 0)):
168
"""
169
Get mapping of reducible to irreducible k-points.
170
171
Parameters:
172
mesh: K-point mesh dimensions
173
is_shift: K-point mesh shift
174
175
Returns:
176
numpy.ndarray: Mapping array
177
"""
178
179
def get_kpoint_weights(self, kpoints, is_time_reversal=True, is_mesh_symmetry=True,
180
is_eigenvectors=False):
181
"""
182
Get weights for k-points based on symmetry.
183
184
Parameters:
185
kpoints: List of k-point coordinates
186
is_time_reversal: Whether to consider time reversal symmetry
187
is_mesh_symmetry: Whether to consider mesh symmetry
188
is_eigenvectors: Whether to return eigenvectors
189
190
Returns:
191
list: K-point weights
192
"""
193
194
@property
195
def symprec(self):
196
"""Symmetry precision tolerance."""
197
198
@property
199
def angle_tolerance(self):
200
"""Angle tolerance in degrees."""
201
```
202
203
### Point Group Analysis
204
205
Point group determination and analysis for molecular and crystalline systems.
206
207
```python { .api }
208
class PointGroupAnalyzer:
209
"""
210
Point group analysis for molecules and crystals.
211
212
Parameters:
213
- mol: Molecule object to analyze
214
- tolerance: Distance tolerance for symmetry detection
215
- eigen_tolerance: Eigenvalue tolerance for rotation analysis
216
- matrix_tolerance: Matrix element tolerance
217
"""
218
def __init__(self, mol, tolerance=0.3, eigen_tolerance=0.01,
219
matrix_tolerance=0.1): ...
220
221
def get_pointgroup(self):
222
"""
223
Get point group classification.
224
225
Returns:
226
str: Point group symbol (e.g., "C2v", "D3h", "Oh")
227
"""
228
229
def get_symmetry_operations(self):
230
"""
231
Get all point group symmetry operations.
232
233
Returns:
234
list: List of SymmOp objects
235
"""
236
237
def is_linear(self):
238
"""
239
Check if molecule is linear.
240
241
Returns:
242
bool: True if molecule is linear
243
"""
244
245
def is_valid_op(self, symm_op):
246
"""
247
Check if symmetry operation is valid for the molecule.
248
249
Parameters:
250
symm_op: SymmOp object to validate
251
252
Returns:
253
bool: True if operation is valid
254
"""
255
256
def get_rotational_symmetry_number(self):
257
"""
258
Get rotational symmetry number.
259
260
Returns:
261
int: Rotational symmetry number
262
"""
263
264
def get_equivalent_atoms(self):
265
"""
266
Get symmetry-equivalent atoms.
267
268
Returns:
269
list: List of equivalent atom groups
270
"""
271
272
@property
273
def tolerance(self):
274
"""Distance tolerance for symmetry detection."""
275
276
@property
277
def eigen_tolerance(self):
278
"""Eigenvalue tolerance."""
279
280
@property
281
def matrix_tolerance(self):
282
"""Matrix element tolerance."""
283
```
284
285
### Symmetrized Structures
286
287
Structures with explicit symmetry information and equivalent site groupings.
288
289
```python { .api }
290
class SymmetrizedStructure:
291
"""
292
Structure with symmetry information and equivalent site groupings.
293
294
Parameters:
295
- structure: Structure object
296
- spacegroup: SpaceGroup object
297
- equivalent_indices: List of equivalent site groups
298
- wyckoff_symbols: Wyckoff symbols for each site
299
"""
300
def __init__(self, structure, spacegroup, equivalent_indices,
301
wyckoff_symbols): ...
302
303
def copy(self):
304
"""
305
Create copy of symmetrized structure.
306
307
Returns:
308
SymmetrizedStructure: Copy of the structure
309
"""
310
311
def find_equivalent_sites(self, site):
312
"""
313
Find all sites equivalent to given site.
314
315
Parameters:
316
site: Site object or site index
317
318
Returns:
319
list: List of equivalent sites
320
"""
321
322
def get_space_group_info(self):
323
"""
324
Get space group information.
325
326
Returns:
327
tuple: (space_group_number, international_symbol)
328
"""
329
330
@property
331
def equivalent_indices(self):
332
"""List of equivalent site index groups."""
333
334
@property
335
def wyckoff_symbols(self):
336
"""Wyckoff symbols for each site."""
337
338
@property
339
def spacegroup(self):
340
"""SpaceGroup object."""
341
342
@property
343
def equivalent_sites(self):
344
"""List of equivalent site groups."""
345
```
346
347
### Space Group Objects
348
349
Representation of crystallographic space groups with symmetry operations.
350
351
```python { .api }
352
class SpaceGroup:
353
"""
354
Crystallographic space group representation.
355
356
Parameters:
357
- int_symbol: International (Hermann-Mauguin) symbol
358
- int_number: International Tables space group number
359
- symmetry_ops: List of symmetry operations
360
"""
361
def __init__(self, int_symbol, int_number, symmetry_ops): ...
362
363
@classmethod
364
def from_int_number(cls, int_number, hexagonal=True):
365
"""
366
Create SpaceGroup from international number.
367
368
Parameters:
369
int_number: International Tables number (1-230)
370
hexagonal: Whether to use hexagonal setting for rhombohedral groups
371
372
Returns:
373
SpaceGroup: SpaceGroup object
374
"""
375
376
def are_symmetrically_equivalent(self, sites1, sites2, symm_prec=1e-3):
377
"""
378
Check if two sets of sites are symmetrically equivalent.
379
380
Parameters:
381
sites1, sites2: Lists of sites to compare
382
symm_prec: Symmetry precision
383
384
Returns:
385
bool: True if sites are equivalent
386
"""
387
388
def is_compatible(self, lattice, tol=1e-5, angle_tol=None):
389
"""
390
Check if lattice is compatible with space group.
391
392
Parameters:
393
lattice: Lattice object
394
tol: Length tolerance
395
angle_tol: Angle tolerance
396
397
Returns:
398
bool: True if lattice is compatible
399
"""
400
401
def is_subgroup(self, supergroup):
402
"""
403
Check if this space group is a subgroup of another.
404
405
Parameters:
406
supergroup: SpaceGroup object
407
408
Returns:
409
bool: True if this is a subgroup
410
"""
411
412
def is_supergroup(self, subgroup):
413
"""
414
Check if this space group is a supergroup of another.
415
416
Parameters:
417
subgroup: SpaceGroup object
418
419
Returns:
420
bool: True if this is a supergroup
421
"""
422
423
@property
424
def int_number(self):
425
"""International Tables space group number."""
426
427
@property
428
def symbol(self):
429
"""Hermann-Mauguin symbol."""
430
431
@property
432
def point_group(self):
433
"""Associated point group symbol."""
434
435
@property
436
def crystal_system(self):
437
"""Crystal system."""
438
439
@property
440
def order(self):
441
"""Order of the space group (number of symmetry operations)."""
442
443
@property
444
def symmetry_ops(self):
445
"""List of symmetry operations."""
446
```
447
448
### K-Point Path Generation
449
450
High-symmetry k-point path generation for electronic band structure calculations.
451
452
```python { .api }
453
class HighSymmKpath:
454
"""
455
High-symmetry k-point paths for band structure calculations.
456
457
Parameters:
458
- structure: Structure for which to generate k-paths
459
- has_magmoms: Whether structure has magnetic moments
460
- magmom_axis: Magnetic moment axis
461
- path_type: Type of k-path generation algorithm
462
- symprec: Symmetry precision
463
- angle_tolerance: Angle tolerance
464
- atol: Absolute tolerance
465
"""
466
def __init__(self, structure, has_magmoms=False, magmom_axis=None,
467
path_type="setyawan_curtarolo", symprec=0.01,
468
angle_tolerance=5, atol=1e-5): ...
469
470
@property
471
def kpath(self):
472
"""
473
Dictionary containing k-path information.
474
475
Returns:
476
dict: K-path with 'path', 'kpoints', and 'explicit_kpoints_abs'
477
"""
478
479
@property
480
def conv(self):
481
"""Conventional structure used for k-path generation."""
482
483
@property
484
def prim(self):
485
"""Primitive structure."""
486
487
@property
488
def conventional(self):
489
"""Conventional structure."""
490
491
@property
492
def prim_rec(self):
493
"""Primitive reciprocal lattice."""
494
495
@property
496
def conv_rec(self):
497
"""Conventional reciprocal lattice."""
498
499
def get_kpoints(self, line_density=20):
500
"""
501
Get k-points along high-symmetry lines.
502
503
Parameters:
504
line_density: Number of k-points per Angstrom^-1
505
506
Returns:
507
Kpoints: VASP KPOINTS object for line-mode calculation
508
"""
509
```
510
511
```python { .api }
512
class KPathSetyawanCurtarolo:
513
"""
514
Setyawan-Curtarolo k-point paths for all crystal systems.
515
516
Parameters:
517
- structure: Structure object
518
- symprec: Symmetry precision
519
- angle_tolerance: Angle tolerance
520
- atol: Absolute tolerance
521
"""
522
def __init__(self, structure, symprec=0.01, angle_tolerance=5, atol=1e-5): ...
523
524
@property
525
def kpath(self):
526
"""K-path dictionary."""
527
528
@property
529
def lattice_type(self):
530
"""Lattice type classification."""
531
532
@property
533
def kpoint_coords(self):
534
"""High-symmetry k-point coordinates."""
535
536
@property
537
def path_strings(self):
538
"""K-path segment strings."""
539
```
540
541
```python { .api }
542
class KPathSeek:
543
"""
544
SeeK-path implementation for k-point path generation.
545
546
Parameters:
547
- structure: Structure object
548
- symprec: Symmetry precision
549
- angle_tolerance: Angle tolerance
550
- atol: Absolute tolerance
551
"""
552
def __init__(self, structure, symprec=0.01, angle_tolerance=5, atol=1e-5): ...
553
554
@property
555
def kpath(self):
556
"""K-path dictionary from SeeK-path."""
557
558
@property
559
def conv(self):
560
"""Conventional structure from SeeK-path."""
561
562
@property
563
def prim(self):
564
"""Primitive structure from SeeK-path."""
565
```
566
567
### Symmetry Operations
568
569
Individual symmetry operations and their mathematical representations.
570
571
```python { .api }
572
class SymmOp:
573
"""
574
Symmetry operation consisting of rotation matrix and translation vector.
575
576
Parameters:
577
- rotation_matrix: 3x3 rotation matrix
578
- translation_vec: 3D translation vector
579
- tol: Numerical tolerance for operations
580
"""
581
def __init__(self, rotation_matrix, translation_vec, tol=0.01): ...
582
583
def operate(self, point):
584
"""
585
Apply symmetry operation to a point.
586
587
Parameters:
588
point: 3D point coordinates
589
590
Returns:
591
numpy.ndarray: Transformed point coordinates
592
"""
593
594
def operate_multi(self, points):
595
"""
596
Apply symmetry operation to multiple points.
597
598
Parameters:
599
points: Array of 3D point coordinates
600
601
Returns:
602
numpy.ndarray: Transformed point coordinates
603
"""
604
605
def apply_rotation_only(self, vector):
606
"""
607
Apply only the rotation part to a vector.
608
609
Parameters:
610
vector: 3D vector
611
612
Returns:
613
numpy.ndarray: Rotated vector
614
"""
615
616
def are_symmetrically_related(self, point_a, point_b, tol=0.001):
617
"""
618
Check if two points are related by this symmetry operation.
619
620
Parameters:
621
point_a, point_b: 3D point coordinates
622
tol: Tolerance for comparison
623
624
Returns:
625
bool: True if points are symmetrically related
626
"""
627
628
def transform_tensor(self, tensor):
629
"""
630
Transform a tensor using this symmetry operation.
631
632
Parameters:
633
tensor: Input tensor
634
635
Returns:
636
numpy.ndarray: Transformed tensor
637
"""
638
639
@classmethod
640
def from_axis_angle_and_translation(cls, axis, angle, angle_in_radians=False,
641
translation_vec=(0, 0, 0)):
642
"""
643
Create symmetry operation from rotation axis and angle.
644
645
Parameters:
646
axis: Rotation axis vector
647
angle: Rotation angle
648
angle_in_radians: Whether angle is in radians
649
translation_vec: Translation vector
650
651
Returns:
652
SymmOp: Symmetry operation object
653
"""
654
655
@classmethod
656
def from_origin_axis_angle(cls, origin, axis, angle, angle_in_radians=False):
657
"""
658
Create rotation about axis through origin.
659
660
Parameters:
661
origin: Origin point for rotation
662
axis: Rotation axis vector
663
angle: Rotation angle
664
angle_in_radians: Whether angle is in radians
665
666
Returns:
667
SymmOp: Symmetry operation object
668
"""
669
670
@classmethod
671
def reflection(cls, normal, origin=(0, 0, 0)):
672
"""
673
Create reflection symmetry operation.
674
675
Parameters:
676
normal: Normal vector to reflection plane
677
origin: Point on reflection plane
678
679
Returns:
680
SymmOp: Reflection operation
681
"""
682
683
@classmethod
684
def inversion(cls, origin=(0, 0, 0)):
685
"""
686
Create inversion symmetry operation.
687
688
Parameters:
689
origin: Inversion center
690
691
Returns:
692
SymmOp: Inversion operation
693
"""
694
695
@classmethod
696
def rotoreflection(cls, axis, angle, origin=(0, 0, 0)):
697
"""
698
Create rotoreflection (improper rotation) operation.
699
700
Parameters:
701
axis: Rotation axis
702
angle: Rotation angle
703
origin: Center point
704
705
Returns:
706
SymmOp: Rotoreflection operation
707
"""
708
709
@property
710
def rotation_matrix(self):
711
"""3x3 rotation matrix."""
712
713
@property
714
def translation_vector(self):
715
"""3D translation vector."""
716
717
@property
718
def inverse(self):
719
"""Inverse symmetry operation."""
720
721
@property
722
def affine_matrix(self):
723
"""4x4 affine transformation matrix."""
724
```
725
726
### Magnetic Symmetry
727
728
Symmetry operations and analysis for magnetic structures.
729
730
```python { .api }
731
class MagSymmOp:
732
"""
733
Magnetic symmetry operation with time reversal.
734
735
Parameters:
736
- rotation_matrix: 3x3 rotation matrix
737
- translation_vec: 3D translation vector
738
- time_reversal: Whether operation includes time reversal
739
- tol: Numerical tolerance
740
"""
741
def __init__(self, rotation_matrix, translation_vec, time_reversal=False,
742
tol=0.01): ...
743
744
def operate_magmom(self, magmom):
745
"""
746
Apply magnetic symmetry operation to magnetic moment.
747
748
Parameters:
749
magmom: Magnetic moment vector or Magmom object
750
751
Returns:
752
numpy.ndarray or Magmom: Transformed magnetic moment
753
"""
754
755
def operate_magmom_on_site(self, site):
756
"""
757
Apply operation to magnetic moment on a specific site.
758
759
Parameters:
760
site: Site object with magnetic moment
761
762
Returns:
763
Site: Site with transformed magnetic moment
764
"""
765
766
@property
767
def time_reversal(self):
768
"""Whether operation includes time reversal."""
769
770
@property
771
def is_identity(self):
772
"""Whether operation is the identity operation."""
773
774
@property
775
def inverse(self):
776
"""Inverse magnetic symmetry operation."""
777
```
778
779
### Crystallographic Analysis Functions
780
781
Utility functions for crystallographic analysis and structure manipulation.
782
783
```python { .api }
784
def cluster_sites(struct, tol, give_only_index=False):
785
"""
786
Cluster sites in structure based on distance.
787
788
Parameters:
789
struct: Structure object
790
tol: Distance tolerance for clustering
791
give_only_index: Whether to return only indices
792
793
Returns:
794
list: Clustered sites or site indices
795
"""
796
797
def iterative_symmetrize(struct, tolerance=0.001, max_n=5):
798
"""
799
Iteratively symmetrize structure to ideal positions.
800
801
Parameters:
802
struct: Structure to symmetrize
803
tolerance: Symmetry tolerance
804
max_n: Maximum number of iterations
805
806
Returns:
807
Structure: Symmetrized structure
808
"""
809
810
def check_magnetic_symmetry(struct, magmoms, precision=0.001):
811
"""
812
Check magnetic symmetry of structure with magnetic moments.
813
814
Parameters:
815
struct: Structure object
816
magmoms: List of magnetic moments
817
precision: Precision for symmetry detection
818
819
Returns:
820
dict: Magnetic symmetry analysis results
821
"""
822
823
def get_shared_symmetry_operations(struct1, struct2, tol=0.01):
824
"""
825
Get symmetry operations shared between two structures.
826
827
Parameters:
828
struct1, struct2: Structure objects to compare
829
tol: Tolerance for operation comparison
830
831
Returns:
832
list: Shared symmetry operations
833
"""
834
835
def get_symmetry_equivalent_miller_indices(structure, miller_index,
836
max_index=6):
837
"""
838
Get all symmetry-equivalent Miller indices.
839
840
Parameters:
841
structure: Structure object
842
miller_index: Reference Miller index
843
max_index: Maximum index to consider
844
845
Returns:
846
list: Symmetry-equivalent Miller indices
847
"""
848
849
def get_point_group_operations(mol, tolerance=0.3):
850
"""
851
Get point group operations for a molecule.
852
853
Parameters:
854
mol: Molecule object
855
tolerance: Distance tolerance
856
857
Returns:
858
list: Point group symmetry operations
859
"""
860
861
def find_in_coord_list(coord_list, coord, atol=1e-8):
862
"""
863
Find coordinate in list with tolerance.
864
865
Parameters:
866
coord_list: List of coordinates to search
867
coord: Target coordinate
868
atol: Absolute tolerance
869
870
Returns:
871
int or None: Index of coordinate if found
872
"""
873
874
def in_array_list(array_list, a, tol=1e-5):
875
"""
876
Check if array is in list of arrays.
877
878
Parameters:
879
array_list: List of arrays
880
a: Target array
881
tol: Tolerance for comparison
882
883
Returns:
884
bool: True if array is in list
885
"""
886
```
887
888
### Wyckoff Position Analysis
889
890
Analysis of Wyckoff positions and site symmetries within space groups.
891
892
```python { .api }
893
def get_wyckoff_symbols(struct, space_group_number, symprec=0.01):
894
"""
895
Get Wyckoff symbols for all sites in structure.
896
897
Parameters:
898
struct: Structure object
899
space_group_number: International space group number
900
symprec: Symmetry precision
901
902
Returns:
903
list: Wyckoff symbols for each site
904
"""
905
906
def get_wyckoff_multiplicities(space_group_number):
907
"""
908
Get Wyckoff position multiplicities for space group.
909
910
Parameters:
911
space_group_number: International space group number
912
913
Returns:
914
dict: Wyckoff symbols and their multiplicities
915
"""
916
917
def get_wyckoff_positions(space_group_number):
918
"""
919
Get all Wyckoff positions for space group.
920
921
Parameters:
922
space_group_number: International space group number
923
924
Returns:
925
dict: Wyckoff positions with coordinates and site symmetries
926
"""
927
```