0
# Structure Analysis & Manipulation
1
2
Comprehensive tools for structure comparison, local environment analysis, Voronoi tessellation, bond analysis, and advanced structural characterization methods. These capabilities enable detailed analysis of crystal structures, defect identification, surface analysis, and molecular recognition.
3
4
## Capabilities
5
6
### Structure Comparison and Matching
7
8
Advanced algorithms for comparing and matching crystal structures with tolerance for symmetry operations and lattice transformations.
9
10
```python { .api }
11
class StructureMatcher:
12
"""
13
Class for matching structures using various algorithms and tolerances.
14
15
Parameters:
16
- ltol: Fractional length tolerance for lattice matching
17
- stol: Site tolerance for matching sites
18
- angle_tol: Angle tolerance in degrees for lattice matching
19
- primitive_cell: Whether to reduce to primitive cells first
20
- scale: Whether to scale volumes to match
21
- attempt_supercell: Whether to attempt supercell matching
22
- allow_subset: Whether to allow subset matching
23
- comparator: Comparison method for sites
24
- supercell_size: Supercell size limit for matching
25
- ignored_species: Species to ignore during matching
26
"""
27
def __init__(self, ltol=0.2, stol=0.3, angle_tol=5, primitive_cell=True,
28
scale=True, attempt_supercell=False, allow_subset=False,
29
comparator=ElementComparator(), supercell_size="num_sites",
30
ignored_species=None): ...
31
32
def fit(self, struct1, struct2):
33
"""
34
Check if two structures match.
35
36
Returns:
37
bool: True if structures match within tolerances
38
"""
39
40
def fit_anonymous(self, struct1, struct2):
41
"""
42
Check if structures match using anonymous species comparison.
43
44
Returns:
45
bool: True if structures match anonymously
46
"""
47
48
def get_rms_dist(self, struct1, struct2):
49
"""
50
Get RMS distance between matched structures.
51
52
Returns:
53
list: RMS distances for each matching configuration
54
"""
55
56
def get_supercells(self, struct1, struct2, max_supercell=1, include_primitive=True):
57
"""
58
Get supercells that can be used for matching.
59
60
Returns:
61
list: Possible supercells for matching
62
"""
63
64
def get_transformation(self, struct1, struct2):
65
"""
66
Get transformation matrix between matched structures.
67
68
Returns:
69
numpy.ndarray: Transformation matrix
70
"""
71
72
def group_structures(self, s_list, anonymous=False):
73
"""
74
Group structures by similarity.
75
76
Parameters:
77
s_list: List of Structure objects
78
anonymous: Whether to use anonymous matching
79
80
Returns:
81
list: Grouped structures
82
"""
83
```
84
85
```python { .api }
86
class StructureAnalyzer:
87
"""
88
General structure analysis tools.
89
"""
90
91
@staticmethod
92
def get_oxide_type(structure, relative_cutoff=1.1, return_nbonds=False):
93
"""
94
Determine oxide type (ionic, covalent, etc.).
95
96
Parameters:
97
structure: Structure to analyze
98
relative_cutoff: Relative cutoff for bond determination
99
return_nbonds: Whether to return bond counts
100
101
Returns:
102
str: Oxide type classification
103
"""
104
105
@staticmethod
106
def get_dimensionality_larsen(structure, tolerance=0.45):
107
"""
108
Get structural dimensionality using Larsen algorithm.
109
110
Returns:
111
int: Dimensionality (0D, 1D, 2D, or 3D)
112
"""
113
114
@staticmethod
115
def get_dimensionality_cheon(structure, tolerance=0.45, ldict=None):
116
"""
117
Get structural dimensionality using Cheon algorithm.
118
119
Returns:
120
int: Dimensionality classification
121
"""
122
```
123
124
### Local Environment Analysis
125
126
Comprehensive neighbor-finding algorithms for analyzing local coordination environments and bonding patterns.
127
128
```python { .api }
129
class VoronoiNN:
130
"""
131
Voronoi tessellation-based neighbor detection.
132
133
Parameters:
134
- tol: Tolerance parameter for neighbor detection
135
- targets: Target species to consider
136
- cutoff: Distance cutoff for neighbors
137
- allow_pathological: Whether to allow pathological cases
138
- weight: Weighting scheme ('solid_angle', 'volume', 'area')
139
- extra_nn_info: Whether to return extra neighbor information
140
"""
141
def __init__(self, tol=0, targets=None, cutoff=13.0,
142
allow_pathological=False, weight="solid_angle",
143
extra_nn_info=True): ...
144
145
def get_nn_info(self, structure, n):
146
"""
147
Get neighbor information for a site.
148
149
Parameters:
150
structure: Structure object
151
n: Site index
152
153
Returns:
154
list: List of neighbor dictionaries with site info and weights
155
"""
156
157
def get_cn(self, structure, n, use_weights=False):
158
"""
159
Get coordination number for a site.
160
161
Parameters:
162
structure: Structure object
163
n: Site index
164
use_weights: Whether to use weighted coordination number
165
166
Returns:
167
float: Coordination number
168
"""
169
170
def get_nn(self, structure, n):
171
"""
172
Get neighbor sites for a given site.
173
174
Returns:
175
list: List of neighboring PeriodicSite objects
176
"""
177
```
178
179
```python { .api }
180
class JmolNN:
181
"""
182
Jmol-based neighbor detection using covalent radii.
183
184
Parameters:
185
- tol: Tolerance factor for covalent radius cutoffs
186
- min_bond_distance: Minimum bond distance
187
- el_radius_updates: Custom element radius updates
188
"""
189
def __init__(self, tol=0.45, min_bond_distance=0.4, el_radius_updates=None): ...
190
191
def get_nn_info(self, structure, n): ...
192
def get_cn(self, structure, n, use_weights=False): ...
193
```
194
195
```python { .api }
196
class CrystalNN:
197
"""
198
Neural network-based neighbor detection optimized for crystals.
199
200
Parameters:
201
- weighted_cn: Whether to return weighted coordination numbers
202
- cation_anion: Whether to consider only cation-anion bonds
203
- distance_cutoffs: Custom distance cutoffs
204
- x_diff_weight: Weight for electronegativity differences
205
- porous_adjustment: Adjustment for porous materials
206
"""
207
def __init__(self, weighted_cn=False, cation_anion=False,
208
distance_cutoffs=None, x_diff_weight=3.0,
209
porous_adjustment=True): ...
210
211
def get_nn_info(self, structure, n): ...
212
def get_cn(self, structure, n, use_weights=False): ...
213
def get_cn_dict(self, structure, n, use_weights=False):
214
"""
215
Get coordination number dictionary with species breakdown.
216
217
Returns:
218
dict: Coordination numbers by species
219
"""
220
```
221
222
```python { .api }
223
class MinimumDistanceNN:
224
"""
225
Simple distance-based neighbor detection.
226
227
Parameters:
228
- tol: Distance tolerance
229
- cutoff: Maximum neighbor distance
230
"""
231
def __init__(self, tol=0.1, cutoff=10.0): ...
232
233
def get_nn_info(self, structure, n): ...
234
def get_cn(self, structure, n, use_weights=False): ...
235
```
236
237
### Bond Analysis
238
239
Tools for analyzing chemical bonds, bond valences, and bonding patterns in structures.
240
241
```python { .api }
242
class BVAnalyzer:
243
"""
244
Bond valence analysis for determining oxidation states and bond strengths.
245
246
Parameters:
247
- symm_tol: Symmetry tolerance
248
- max_radius: Maximum ionic radius for analysis
249
- max_permutations: Maximum oxidation state permutations to try
250
- distance_scale_factor: Scaling factor for bond distances
251
- charge_neutrality_tolerance: Tolerance for charge neutrality
252
- forbidden_species: Species not allowed in analysis
253
"""
254
def __init__(self, symm_tol=0.1, max_radius=4, max_permutations=100000,
255
distance_scale_factor=1.015, charge_neutrality_tolerance=1e-4,
256
forbidden_species=None): ...
257
258
def get_oxi_state_decorated_structure(self, structure):
259
"""
260
Get structure decorated with oxidation states.
261
262
Parameters:
263
structure: Structure to analyze
264
265
Returns:
266
Structure: Structure with oxidation states assigned
267
"""
268
269
def get_valences(self, structure):
270
"""
271
Get bond valences for all sites in structure.
272
273
Returns:
274
list: Bond valences for each site
275
"""
276
277
def get_oxi_state_guesses(self, structure, max_sites=-1):
278
"""
279
Get possible oxidation state assignments.
280
281
Returns:
282
list: List of possible oxidation state dictionaries
283
"""
284
```
285
286
```python { .api }
287
class BondDissociationEnergies:
288
"""
289
Analysis of bond dissociation energies in molecular systems.
290
"""
291
292
def __init__(self, molecule_entry, fragments=None,
293
fragment_entries=None, allow_additional_mvs=True): ...
294
295
def build_new_entry(self, name, molecule, additional_charge=0,
296
additional_spin_multiplicity=0, level_of_theory=None,
297
return_ia_data=False, nbo_data=None): ...
298
299
def fragment_and_process(self, molecule_entry, edges,
300
depth=1, open_rings=True, opt_steps=10000): ...
301
```
302
303
### Voronoi Analysis
304
305
Advanced Voronoi tessellation analysis for coordination environments and pore analysis.
306
307
```python { .api }
308
class VoronoiAnalyzer:
309
"""
310
Voronoi tessellation analysis of crystal structures.
311
312
Parameters:
313
- cutoff: Cutoff distance for Voronoi analysis
314
- qhull_options: Options for Qhull Voronoi computation
315
"""
316
def __init__(self, cutoff=5.0, qhull_options="Qbb Qc Qz"): ...
317
318
def analyze(self, structure, n=0):
319
"""
320
Perform Voronoi analysis on a structure.
321
322
Parameters:
323
structure: Structure to analyze
324
n: Site index to focus analysis on (0 for all sites)
325
326
Returns:
327
dict: Voronoi analysis results
328
"""
329
330
def analyze_structures(self, structures, step_freq=10, most_frequent_polyhedra=15):
331
"""
332
Analyze multiple structures for Voronoi polyhedra statistics.
333
334
Parameters:
335
structures: List of structures to analyze
336
step_freq: Frequency of analysis steps
337
most_frequent_polyhedra: Number of most frequent polyhedra to track
338
339
Returns:
340
dict: Statistical analysis of polyhedra across structures
341
"""
342
```
343
344
```python { .api }
345
class VoronoiConnectivity:
346
"""
347
Connectivity analysis using Voronoi tessellation.
348
349
Parameters:
350
- structure: Structure to analyze
351
- cutoff: Distance cutoff for connectivity
352
"""
353
def __init__(self, structure, cutoff=10): ...
354
355
@property
356
def connectivity_array(self):
357
"""
358
Get connectivity matrix between sites.
359
360
Returns:
361
numpy.ndarray: Connectivity matrix
362
"""
363
364
@property
365
def max_connectivity(self):
366
"""
367
Get maximum connectivity in structure.
368
369
Returns:
370
float: Maximum connectivity value
371
"""
372
373
def get_connections(self):
374
"""
375
Get all connections in the structure.
376
377
Returns:
378
list: List of connected site pairs
379
"""
380
```
381
382
### Graph-Based Structure Analysis
383
384
Structure and molecule graphs for topological analysis and similarity comparison.
385
386
```python { .api }
387
class StructureGraph:
388
"""
389
Graph representation of crystal structures.
390
391
Parameters:
392
- structure: Structure object
393
- graph_data: Optional pre-computed graph data
394
"""
395
def __init__(self, structure, graph_data=None): ...
396
397
@classmethod
398
def with_empty_graph(cls, structure, name="bonds",
399
edge_weight_name=None, edge_weight_units=None):
400
"""
401
Create StructureGraph with empty graph.
402
403
Returns:
404
StructureGraph: Empty graph for the structure
405
"""
406
407
@classmethod
408
def with_local_env_strategy(cls, structure, strategy):
409
"""
410
Create StructureGraph using local environment strategy.
411
412
Parameters:
413
structure: Structure object
414
strategy: Local environment strategy (e.g., VoronoiNN)
415
416
Returns:
417
StructureGraph: Graph built using the strategy
418
"""
419
420
def add_edge(self, from_index, to_index, from_jimage=(0, 0, 0),
421
to_jimage=(0, 0, 0), weight=None, warn_duplicates=True): ...
422
423
def remove_edge(self, from_index, to_index, from_jimage=(0, 0, 0),
424
to_jimage=(0, 0, 0)): ...
425
426
def get_connected_sites(self, n, jimage=(0, 0, 0)):
427
"""
428
Get sites connected to site n.
429
430
Parameters:
431
n: Site index
432
jimage: Periodic image
433
434
Returns:
435
list: Connected sites
436
"""
437
438
def get_coordination_of_site(self, n):
439
"""
440
Get coordination number of site.
441
442
Returns:
443
int: Coordination number
444
"""
445
446
def draw_graph_to_file(self, filename="graph", diff=None,
447
hide_unconnected_nodes=False, hide_image_edges=True,
448
edge_colors=False, node_labels=False, weight_labels=False,
449
image_labels=False, color_scheme="VESTA",
450
keep_dot=False, algo="fdp"): ...
451
452
def get_subgraphs_as_molecules(self, use_weights=False):
453
"""
454
Get disconnected subgraphs as Molecule objects.
455
456
Returns:
457
list: List of Molecule objects for each subgraph
458
"""
459
460
def types_and_weights_of_connections(self):
461
"""
462
Get types and weights of all connections in graph.
463
464
Returns:
465
dict: Connection types and their weights
466
"""
467
```
468
469
```python { .api }
470
class MoleculeGraph:
471
"""
472
Graph representation of molecular structures.
473
474
Parameters:
475
- molecule: Molecule object
476
- graph_data: Optional pre-computed graph data
477
"""
478
def __init__(self, molecule, graph_data=None): ...
479
480
@classmethod
481
def with_empty_graph(cls, molecule, name="bonds",
482
edge_weight_name="weight", edge_weight_units=""): ...
483
484
@classmethod
485
def with_local_env_strategy(cls, molecule, strategy): ...
486
487
@classmethod
488
def from_edges(cls, molecule, edges): ...
489
490
def add_edge(self, from_index, to_index, weight=1, warn_duplicates=True): ...
491
def remove_edge(self, from_index, to_index): ...
492
493
def get_connected_sites(self, n):
494
"""
495
Get sites connected to site n.
496
497
Returns:
498
list: Connected sites
499
"""
500
501
def get_coordination_of_site(self, n): ...
502
503
def find_rings(self, including=None):
504
"""
505
Find rings in the molecular graph.
506
507
Parameters:
508
including: Sites that must be included in rings
509
510
Returns:
511
list: List of rings (cycles) in the graph
512
"""
513
514
def get_disconnected_fragments(self):
515
"""
516
Get disconnected molecular fragments.
517
518
Returns:
519
list: List of MoleculeGraph objects for each fragment
520
"""
521
522
def split_molecule_subgraphs(self, bonds_to_break, allow_reverse=False):
523
"""
524
Split molecule by breaking specified bonds.
525
526
Parameters:
527
bonds_to_break: List of bonds to break
528
allow_reverse: Whether to allow reverse bond breaking
529
530
Returns:
531
list: Resulting molecular fragments
532
"""
533
```
534
535
### Molecular Analysis
536
537
Tools for molecular structure analysis, comparison, and property calculation.
538
539
```python { .api }
540
class MoleculeMatcher:
541
"""
542
Class for matching and comparing molecular structures.
543
544
Parameters:
545
- tolerance: Distance tolerance for matching
546
- mapper: Atom mapping algorithm
547
"""
548
def __init__(self, tolerance=0.3, mapper=None): ...
549
550
def fit(self, mol1, mol2):
551
"""
552
Check if two molecules match.
553
554
Parameters:
555
mol1, mol2: Molecule objects to compare
556
557
Returns:
558
bool: True if molecules match
559
"""
560
561
def get_rmsd(self, mol1, mol2):
562
"""
563
Get RMSD between matched molecules.
564
565
Returns:
566
float: RMSD value
567
"""
568
569
def group_molecules(self, mol_list):
570
"""
571
Group molecules by similarity.
572
573
Parameters:
574
mol_list: List of Molecule objects
575
576
Returns:
577
list: Grouped molecules
578
"""
579
```
580
581
```python { .api }
582
class FunctionalGroupExtractor:
583
"""
584
Extract functional groups from molecular structures.
585
"""
586
587
def __init__(self, molecule): ...
588
589
def get_functional_groups(self, func_groups=None, catch_basic=True):
590
"""
591
Identify functional groups in molecule.
592
593
Parameters:
594
func_groups: List of functional groups to look for
595
catch_basic: Whether to catch basic functional groups
596
597
Returns:
598
list: Identified functional groups
599
"""
600
601
def categorize_functional_groups(self, func_groups):
602
"""
603
Categorize functional groups by type.
604
605
Returns:
606
dict: Categorized functional groups
607
"""
608
```
609
610
### Surface and Interface Analysis
611
612
Specialized tools for analyzing surfaces, slabs, and interfaces.
613
614
```python { .api }
615
class AdsorbateSiteFinder:
616
"""
617
Find adsorption sites on surfaces.
618
619
Parameters:
620
- slab: Slab structure for adsorption analysis
621
- selective_dynamics: Whether to use selective dynamics
622
- height: Height above surface to place adsorbates
623
- mi_vec: Miller index vector
624
"""
625
def __init__(self, slab, selective_dynamics=False, height=0.9, mi_vec=None): ...
626
627
def find_adsorption_sites(self, distance=1.0, put_inside=True,
628
symm_reduce=1e-2, near_reduce=1e-2,
629
positions=("ontop", "bridge", "hollow"),
630
no_obtuse_hollow=True):
631
"""
632
Find adsorption sites on the surface.
633
634
Parameters:
635
distance: Distance from surface atoms for site generation
636
put_inside: Whether to put sites inside unit cell
637
symm_reduce: Symmetry reduction tolerance
638
near_reduce: Distance reduction tolerance
639
positions: Types of adsorption sites to find
640
no_obtuse_hollow: Whether to exclude obtuse hollow sites
641
642
Returns:
643
dict: Adsorption sites by type
644
"""
645
646
def add_adsorbate(self, molecule, ads_sites_dict, repeat=None,
647
min_lw=5.0, translate=True, reorient=True):
648
"""
649
Add adsorbate molecules to adsorption sites.
650
651
Parameters:
652
molecule: Adsorbate molecule
653
ads_sites_dict: Dictionary of adsorption sites
654
repeat: Repeat pattern for adsorbate placement
655
min_lw: Minimum layer width
656
translate: Whether to translate adsorbate
657
reorient: Whether to reorient adsorbate
658
659
Returns:
660
list: Structures with adsorbates added
661
"""
662
```
663
664
### Utility Functions
665
666
Helper functions for structure analysis and manipulation.
667
668
```python { .api }
669
def obtain_all_bond_lengths(structure, max_bond_length=3.0):
670
"""
671
Obtain all bond lengths in a structure.
672
673
Parameters:
674
structure: Structure to analyze
675
max_bond_length: Maximum bond length to consider
676
677
Returns:
678
dict: Bond lengths by species pairs
679
"""
680
681
def get_bond_length(sp1, sp2, bond_order=1):
682
"""
683
Get expected bond length between two species.
684
685
Parameters:
686
sp1, sp2: Species objects or symbols
687
bond_order: Bond order (1, 2, 3, etc.)
688
689
Returns:
690
float: Expected bond length in Angstroms
691
"""
692
693
def get_bond_order(sp1, sp2, dist, check_exists=False):
694
"""
695
Get bond order from bond distance.
696
697
Parameters:
698
sp1, sp2: Species objects or symbols
699
dist: Bond distance in Angstroms
700
check_exists: Whether to check if bond type exists
701
702
Returns:
703
float: Estimated bond order
704
"""
705
706
def solid_angle(center, coords):
707
"""
708
Calculate solid angle subtended by points at center.
709
710
Parameters:
711
center: Center point coordinates
712
coords: Array of coordinates
713
714
Returns:
715
float: Solid angle in steradians
716
"""
717
718
def contains_peroxide(structure, relative_cutoff=1.1):
719
"""
720
Check if structure contains peroxide anions.
721
722
Parameters:
723
structure: Structure to check
724
relative_cutoff: Relative cutoff for peroxide detection
725
726
Returns:
727
bool: True if peroxide is present
728
"""
729
730
def oxide_type(structure, relative_cutoff=1.1, return_nbonds=False):
731
"""
732
Determine oxide type (ionic, covalent, etc.).
733
734
Parameters:
735
structure: Structure to classify
736
relative_cutoff: Relative cutoff for bond classification
737
return_nbonds: Whether to return bond counts
738
739
Returns:
740
str: Oxide type classification
741
"""
742
```