0
# Core Materials Representation
1

2
Fundamental classes for representing crystal structures, molecules, compositions, and lattices that form the foundation of all materials analysis in pymatgen. These classes provide rich manipulation capabilities, property calculations, and serve as the basis for all higher-level analysis functions.
3

4
## Capabilities
5

6
### Structure Classes
7

8
Primary classes for representing atomic arrangements in crystals and molecules with comprehensive manipulation and query methods.
9

10
```python { .api }
11
class Structure:
12
    """
13
    Mutable 3D crystal structure representation.
14
    
15
    Parameters:
16
    - lattice: Lattice object or 3x3 matrix representing the unit cell
17
    - species: List of species at each site
18
    - coords: List of fractional coordinates for each site
19
    - charge: Optional net charge of the structure
20
    - validate_proximity: Whether to check for unreasonably close atoms
21
    - to_unit_cell: Whether to map sites to unit cell
22
    - coords_are_cartesian: Whether coordinates are in Cartesian form
23
    - site_properties: Dict of site properties
24
    - labels: Optional site labels
25
    - properties: Additional structure properties
26
    """
27
    def __init__(self, lattice, species, coords, charge=None, 
28
                 validate_proximity=False, to_unit_cell=False,
29
                 coords_are_cartesian=False, site_properties=None, 
30
                 labels=None, properties=None): ...
31
    
32
    def get_primitive_structure(self, tolerance=0.25, use_site_props=False, 
33
                              constrain_latt=None): ...
34
    def get_reduced_structure(self, reduction_algo="niggli"): ...
35
    def get_conventional_structure(self, international_monoclinic=True): ...
36
    def get_neighbors(self, site, r, include_index=False, include_image=False): ...
37
    def get_neighbors_in_shell(self, origin, r, dr): ...
38
    def get_sites_in_sphere(self, pt, r, include_index=False, include_image=False): ...
39
    def get_all_neighbors(self, r, include_index=False, include_image=False): ...
40
    def get_distance(self, i, j, jimage=None): ...
41
    def get_angle(self, i, j, k): ...
42
    def get_dihedral(self, i, j, k, l): ...
43
    def copy(self): ...
44
    def __mul__(self, scaling_matrix): ...
45
    
46
    # Site manipulation methods
47
    def insert(self, i, species, coords, coords_are_cartesian=False, 
48
               validate_proximity=False, properties=None): ...
49
    def append(self, species, coords, coords_are_cartesian=False, 
50
               validate_proximity=False, properties=None): ...
51
    def remove_sites(self, indices): ...
52
    def remove_species(self, species): ...
53
    def replace(self, i, species, coords=None, coords_are_cartesian=False, 
54
                properties=None): ...
55
    def substitute(self, index, func_group, bond_order=1): ...
56
    def add_site_property(self, property_name, values): ...
57
    def remove_site_property(self, property_name): ...
58
    
59
    # Transformation methods
60
    def apply_operation(self, symm_op, fractional=False): ...
61
    def apply_strain(self, strain): ...
62
    def perturb(self, distance, min_distance=None): ...
63
    def make_supercell(self, scaling_matrix, to_unit_cell=True): ...
64
    def scale_lattice(self, volume): ...
65
    def translate_sites(self, indices, vector, frac_coords=True, to_unit_cell=True): ...
66
    def rotate_sites(self, indices=None, theta=0, axis=None, anchor=None): ...
67
    
68
    # Analysis properties
69
    @property
70
    def volume(self): ...
71
    @property
72
    def density(self): ...
73
    @property
74
    def formula(self): ...
75
    @property
76
    def composition(self): ...
77
    @property
78
    def charge(self): ...
79
    @property
80
    def num_sites(self): ...
81
    @property
82
    def lattice(self): ...
83
    @property
84
    def species(self): ...
85
    @property
86
    def sites(self): ...
87
    @property
88
    def frac_coords(self): ...
89
    @property
90
    def cart_coords(self): ...
91
```
92

93
```python { .api }
94
class IStructure:
95
    """
96
    Immutable version of Structure. Same interface but cannot be modified.
97
    """
98
    # Same properties and analysis methods as Structure
99
    # No mutation methods (insert, append, remove_sites, etc.)
100
```
101

102
```python { .api }
103
class Molecule:
104
    """
105
    Mutable molecular structure representation for non-periodic systems.
106
    
107
    Parameters:
108
    - species: List of species in molecule
109
    - coords: List of Cartesian coordinates
110
    - charge: Net charge of molecule
111
    - spin_multiplicity: Spin multiplicity
112
    - validate_proximity: Whether to check for close atoms
113
    - site_properties: Dict of site properties
114
    """
115
    def __init__(self, species, coords, charge=0, spin_multiplicity=None,
116
                 validate_proximity=False, site_properties=None): ...
117
    
118
    def get_distance(self, i, j): ...
119
    def get_angle(self, i, j, k): ...
120
    def get_dihedral(self, i, j, k, l): ...
121
    def get_neighbors(self, site, r): ...
122
    def get_boxed_structure(self, a, b, c, images=(2, 2, 2), 
123
                           random_rotation=False, min_dist=1.0, 
124
                           cls=None, offset=None, reorder=True, 
125
                           rotations=None): ...
126
    
127
    # Center-of-mass operations
128
    def get_centered_molecule(self): ...
129
    def get_covalent_bonds(self, tol=0.2): ...
130
    
131
    @property
132
    def center_of_mass(self): ...
133
    @property
134
    def charge(self): ...
135
    @property
136
    def spin_multiplicity(self): ...
137
    @property
138
    def nelectrons(self): ...
139
```
140

141
```python { .api }
142
class IMolecule:
143
    """
144
    Immutable version of Molecule.
145
    """
146
    # Same interface as Molecule but immutable
147
```
148

149
### Composition Analysis
150

151
Chemical composition representation with element counting, formula manipulation, and compositional analysis tools.
152

153
```python { .api }
154
class Composition:
155
    """
156
    Chemical composition representation with element counting and analysis.
157
    
158
    Parameters:
159
    - *args: Flexible arguments - dict, formula string, or key-value pairs
160
    - strict: Only allow valid Elements and Species (default: False)
161
    - **kwargs: Additional keyword arguments for composition data
162
    """
163
    def __init__(self, *args, strict=False, **kwargs): ...
164
    
165
    def get_atomic_fraction(self, el): ...
166
    def get_wt_fraction(self, el): ...
167
    def get_reduced_composition_and_factor(self): ...
168
    def get_reduced_formula_and_factor(self): ...
169
    def get_integer_formula_and_factor(self, max_denominator=10000): ...
170
    def get_el_amt_dict(self): ...
171
    def fractional_composition(self): ...
172
    def add_charges_from_oxi_state_guesses(self, oxi_states_override=None, 
173
                                         target_charge=0, all_oxi_states=False, 
174
                                         max_sites=None): ...
175
    def oxi_state_guesses(self, oxi_states_override=None, target_charge=0, 
176
                         all_oxi_states=False, max_sites=None): ...
177
    def replace(self, replacements_dict): ...
178
    def __add__(self, other): ...
179
    def __sub__(self, other): ...
180
    def __mul__(self, other): ...
181
    
182
    @property
183
    def formula(self): ...
184
    @property
185
    def alphabetical_formula(self): ...
186
    @property
187
    def element_composition(self): ...
188
    @property
189
    def fractional_composition(self): ...
190
    @property
191
    def reduced_composition(self): ...
192
    @property
193
    def reduced_formula(self): ...
194
    @property
195
    def elements(self): ...
196
    @property
197
    def num_atoms(self): ...
198
    @property
199
    def weight(self): ...
200
    @property
201
    def average_electroneg(self): ...
202
    @property
203
    def total_electrons(self): ...
204
    @property
205
    def charge(self): ...
206
    @property
207
    def anonymized_formula(self): ...
208
    @property
209
    def chemical_system(self): ...
210
    @property
211
    def hill_formula(self): ...
212
    @property
213
    def iupac_formula(self): ...
214
```
215

216
### Lattice Operations
217

218
Crystal lattice representation with vector operations, reciprocal lattice calculations, and crystallographic transformations.
219

220
```python { .api }
221
class Lattice:
222
    """
223
    Crystal lattice representation with vector operations.
224
    
225
    Parameters:
226
    - matrix: 3x3 lattice matrix where rows are lattice vectors
227
    """
228
    def __init__(self, matrix): ...
229
    
230
    @classmethod
231
    def cubic(cls, a): ...
232
    @classmethod
233
    def tetragonal(cls, a, c): ...
234
    @classmethod
235
    def orthorhombic(cls, a, b, c): ...
236
    @classmethod
237
    def hexagonal(cls, a, c): ...
238
    @classmethod
239
    def rhombohedral(cls, a, alpha): ...
240
    @classmethod
241
    def monoclinic(cls, a, b, c, beta): ...
242
    @classmethod
243
    def triclinic(cls, a, b, c, alpha, beta, gamma): ...
244
    @classmethod
245
    def from_parameters(cls, a, b, c, alpha, beta, gamma): ...
246
    
247
    def get_cartesian_coords(self, fractional_coords): ...
248
    def get_fractional_coords(self, cart_coords): ...
249
    def get_points_in_sphere(self, frac_points, center, r, zip_results=True): ...
250
    def get_all_distances(self, fcoords1, fcoords2): ...
251
    def get_distance_and_image(self, frac_coords1, frac_coords2, jimage=None): ...
252
    def get_vector_along_lattice_directions(self, cart_coords): ...
253
    def find_neighbors(self, label, cutoff, get_length=True): ...
254
    def get_points_in_spheres(self, all_fcoords, all_centers, all_r, 
255
                            zip_results=True, return_fcoords=False): ...
256
    
257
    # Analysis properties
258
    @property
259
    def a(self): ...
260
    @property
261
    def b(self): ...
262
    @property
263
    def c(self): ...
264
    @property
265
    def alpha(self): ...
266
    @property
267
    def beta(self): ...
268
    @property
269
    def gamma(self): ...
270
    @property
271
    def volume(self): ...
272
    @property
273
    def matrix(self): ...
274
    @property
275
    def inv_matrix(self): ...
276
    @property
277
    def metric_tensor(self): ...
278
    @property
279
    def reciprocal_lattice(self): ...
280
    @property
281
    def reciprocal_lattice_crystallographic(self): ...
282
    @property
283
    def parameters(self): ...
284
    @property
285
    def lengths(self): ...
286
    @property
287
    def angles(self): ...
288
    @property
289
    def is_orthogonal(self): ...
290
    @property
291
    def norm(self): ...
292
```
293

294
### Sites and Species
295

296
Atomic sites and chemical species representations with properties and neighbor information.
297

298
```python { .api }
299
class Site:
300
    """
301
    Generic site with Cartesian coordinates and species information.
302
    
303
    Parameters:
304
    - species: Species at the site
305
    - coords: Cartesian coordinates of the site
306
    - properties: Dict of site properties
307
    - label: Optional site label
308
    """
309
    def __init__(self, species, coords, properties=None, label=None): ...
310
    
311
    def distance(self, other): ...
312
    def distance_from_point(self, pt): ...
313
    
314
    @property
315
    def species(self): ...
316
    @property
317
    def species_string(self): ...
318
    @property
319
    def coords(self): ...
320
    @property
321
    def x(self): ...
322
    @property
323
    def y(self): ...
324
    @property
325
    def z(self): ...
326
    @property
327
    def properties(self): ...
328
    @property
329
    def label(self): ...
330
```
331

332
```python { .api }
333
class PeriodicSite:
334
    """
335
    Site in a periodic structure with fractional coordinates and lattice.
336
    
337
    Parameters:
338
    - species: Species at the site
339
    - coords: Fractional coordinates
340
    - lattice: Lattice object
341
    - to_unit_cell: Whether to wrap to unit cell
342
    - coords_are_cartesian: Whether coords are Cartesian
343
    - properties: Dict of site properties
344
    - label: Optional site label
345
    """
346
    def __init__(self, species, coords, lattice, to_unit_cell=False,
347
                 coords_are_cartesian=False, properties=None, label=None): ...
348
    
349
    def distance(self, other, jimage=None): ...
350
    def distance_and_image(self, other, jimage=None): ...
351
    def is_periodic_image(self, other, tolerance=1e-8, check_lattice=True): ...
352
    
353
    @property
354
    def frac_coords(self): ...
355
    @property
356
    def coords(self): ...
357
    @property
358
    def lattice(self): ...
359
    @property
360
    def a(self): ...
361
    @property
362
    def b(self): ...
363
    @property
364
    def c(self): ...
365
```
366

367
```python { .api }
368
class Element:
369
    """
370
    Chemical element from periodic table.
371
    
372
    Parameters:
373
    - symbol: Element symbol (e.g., 'Fe', 'O')
374
    """
375
    def __init__(self, symbol): ...
376
    
377
    @property
378
    def symbol(self): ...
379
    @property
380
    def name(self): ...
381
    @property
382
    def atomic_mass(self): ...
383
    @property
384
    def atomic_radius(self): ...
385
    @property
386
    def atomic_radius_calculated(self): ...
387
    @property
388
    def van_der_waals_radius(self): ...
389
    @property
390
    def mendeleev_no(self): ...
391
    @property
392
    def electrical_resistivity(self): ...
393
    @property
394
    def velocity_of_sound(self): ...
395
    @property
396
    def reflectance(self): ...
397
    @property
398
    def refractive_index(self): ...
399
    @property
400
    def poissons_ratio(self): ...
401
    @property
402
    def molar_volume(self): ...
403
    @property
404
    def electronic_structure(self): ...
405
    @property
406
    def atomic_orbitals(self): ...
407
    @property
408
    def thermal_conductivity(self): ...
409
    @property
410
    def boiling_point(self): ...
411
    @property
412
    def melting_point(self): ...
413
    @property
414
    def critical_temperature(self): ...
415
    @property
416
    def superconduction_temperature(self): ...
417
    @property
418
    def liquid_range(self): ...
419
    @property
420
    def bulk_modulus(self): ...
421
    @property
422
    def youngs_modulus(self): ...
423
    @property
424
    def brinell_hardness(self): ...
425
    @property
426
    def rigidity_modulus(self): ...
427
    @property
428
    def mineral_hardness(self): ...
429
    @property
430
    def vickers_hardness(self): ...
431
    @property
432
    def density_of_solid(self): ...
433
    @property
434
    def coefficient_of_linear_thermal_expansion(self): ...
435
```
436

437
```python { .api }
438
class Species:
439
    """
440
    Chemical species with oxidation state.
441
    
442
    Parameters:
443
    - symbol: Element symbol
444
    - oxidation_state: Oxidation state (int or float)
445
    - properties: Additional properties dict
446
    """
447
    def __init__(self, symbol, oxidation_state, properties=None): ...
448
    
449
    @property
450
    def element(self): ...
451
    @property
452
    def oxi_state(self): ...
453
    @property
454
    def ionic_radius(self): ...
455
    @property
456
    def spin(self): ...
457
```
458

459
```python { .api }
460
class Ion:
461
    """
462
    Ionic species with charge.
463
    
464
    Parameters:
465
    - symbol: Element symbol or Species
466
    - charge: Ionic charge
467
    - properties: Additional properties dict
468
    """
469
    def __init__(self, symbol, charge, properties=None): ...
470
    
471
    @property
472
    def charge(self): ...
473
    @property
474
    def element(self): ...
475
    @property
476
    def formula(self): ...
477
```
478

479
### Physical Units
480

481
Unit handling and conversion for physical quantities used in materials science calculations.
482

483
```python { .api }
484
class Unit:
485
    """
486
    Physical unit representation and conversion.
487
    
488
    Parameters:
489
    - unit_def: Unit definition string or dict
490
    """
491
    def __init__(self, unit_def): ...
492
    
493
    def __mul__(self, other): ...
494
    def __div__(self, other): ...
495
    def __pow__(self, i): ...
496
    
497
    @property
498
    def as_base_units(self): ...
499
```
500

501
```python { .api }
502
class FloatWithUnit:
503
    """
504
    Float with associated physical unit.
505
    
506
    Parameters:
507
    - val: Numerical value
508
    - unit: Unit object or string
509
    """
510
    def __init__(self, val, unit): ...
511
    
512
    def to(self, new_unit): ...
513
    def as_base_units(self): ...
514
    
515
    @property
516
    def unit(self): ...
517
    @property
518
    def supported_units(self): ...
519
```
520

521
```python { .api }
522
class ArrayWithUnit:
523
    """
524
    NumPy array with associated physical unit.
525
    
526
    Parameters:
527
    - input_array: Array-like input
528
    - unit: Unit object or string
529
    """
530
    def __init__(self, input_array, unit): ...
531
    
532
    def to(self, new_unit): ...
533
    def as_base_units(self): ...
534
    
535
    @property
536
    def unit(self): ...
537
    @property
538
    def supported_units(self): ...
539
```
540

541
### Symmetry Operations
542

543
Basic symmetry operations for structure manipulation and analysis.
544

545
```python { .api }
546
class SymmOp:
547
    """
548
    Symmetry operation consisting of rotation and translation.
549
    
550
    Parameters:
551
    - rotation_matrix: 3x3 rotation matrix
552
    - translation_vec: Translation vector
553
    - tol: Tolerance for operations
554
    """
555
    def __init__(self, rotation_matrix, translation_vec, tol=0.01): ...
556
    
557
    def apply_rotation_only(self, vector): ...
558
    def operate(self, point): ...
559
    def operate_multi(self, points): ...
560
    def transform_tensor(self, tensor): ...
561
    def are_symmetrically_related(self, point_a, point_b, tol=0.001): ...
562
    
563
    @classmethod
564
    def from_axis_angle_and_translation(cls, axis, angle, angle_in_radians=False, 
565
                                      translation_vec=(0, 0, 0)): ...
566
    @classmethod
567
    def from_origin_axis_angle(cls, origin, axis, angle, angle_in_radians=False): ...
568
    @classmethod
569
    def reflection(cls, normal, origin=(0, 0, 0)): ...
570
    @classmethod
571
    def inversion(cls, origin=(0, 0, 0)): ...
572
    @classmethod
573
    def rotoreflection(cls, axis, angle, origin=(0, 0, 0)): ...
574
    
575
    @property
576
    def rotation_matrix(self): ...
577
    @property
578
    def translation_vector(self): ...
579
    @property
580
    def inverse(self): ...
581
    @property
582
    def affine_matrix(self): ...
583
```
584

585
### Utility Functions
586

587
Helper functions for working with core materials representations.
588

589
```python { .api }
590
def get_el_sp(obj):
591
    """
592
    Convert various inputs to Element or Species objects.
593
    
594
    Parameters:
595
    obj: Element symbol string, Element, Species, or Ion
596
    
597
    Returns:
598
    Element or Species object
599
    """
600

601
def reduce_formula(sym_amt, iupac_ordering=False):
602
    """
603
    Reduce chemical formula to simplest form.
604
    
605
    Parameters:
606
    sym_amt: Dict of {symbol: amount}
607
    iupac_ordering: Whether to use IUPAC ordering
608
    
609
    Returns:
610
    str: Reduced formula
611
    """
612

613
def get_bond_length(sp1, sp2, bond_order=1):
614
    """
615
    Get bond length between two species.
616
    
617
    Parameters:
618
    sp1, sp2: Species objects or symbols
619
    bond_order: Bond order (1=single, 2=double, etc.)
620
    
621
    Returns:
622
    float: Bond length in Angstroms
623
    """
624

625
def obtain_all_bond_lengths(structure, max_bond_length=3.0):
626
    """
627
    Get all bond lengths in a structure.
628
    
629
    Parameters:
630
    structure: Structure object
631
    max_bond_length: Maximum bond length to consider
632
    
633
    Returns:
634
    dict: Bond lengths organized by species pairs
635
    """
636
```