0
# Elements and Isotopes
1
2
Core functionality for accessing elements, isotopes, and ions from the periodic table with comprehensive property data including mass, density, atomic structure, and specialized scientific properties.
3
4
## Capabilities
5
6
### Element Access
7
8
Access elements from the periodic table using atomic number, symbol, or name with comprehensive property data loaded on demand.
9
10
```python { .api }
11
def __getitem__(self, atomic_number: int) -> Element:
12
"""
13
Get element by atomic number.
14
15
Args:
16
atomic_number: Atomic number (1-118)
17
18
Returns:
19
Element instance
20
"""
21
22
def symbol(self, symbol: str) -> Element:
23
"""
24
Lookup element by chemical symbol.
25
26
Args:
27
symbol: Chemical symbol (e.g., 'Fe', 'Ni', 'H')
28
29
Returns:
30
Element instance
31
"""
32
33
def name(self, name: str) -> Element:
34
"""
35
Lookup element by name.
36
37
Args:
38
name: Element name (e.g., 'iron', 'nickel', 'hydrogen')
39
40
Returns:
41
Element instance
42
"""
43
44
def isotope(self, isotope_str: str) -> Isotope:
45
"""
46
Lookup isotope by string specification.
47
48
Args:
49
isotope_str: Isotope string (e.g., '56-Fe', '58-Ni')
50
51
Returns:
52
Isotope instance
53
"""
54
```
55
56
Usage examples:
57
58
```python
59
import periodictable as pt
60
61
# Different ways to access iron
62
fe1 = pt.elements[26] # By atomic number
63
fe2 = pt.elements.Fe # By symbol attribute
64
fe3 = pt.elements.symbol('Fe') # By symbol method
65
fe4 = pt.elements.name('iron') # By name method
66
67
# Access specific isotopes
68
fe56 = pt.elements.isotope('56-Fe') # Iron-56
69
ni58 = pt.elements.isotope('58-Ni') # Nickel-58
70
71
# Special isotopes available directly
72
deuterium = pt.D # Deuterium (2-H)
73
tritium = pt.T # Tritium (3-H)
74
```
75
76
### Element Properties
77
78
Each element provides core properties and access to isotopes and ions with lazy loading for specialized data.
79
80
```python { .api }
81
class Element:
82
"""Individual element with properties and access to isotopes/ions."""
83
84
# Core properties (always available)
85
symbol: str # Chemical symbol (e.g., 'Fe')
86
name: str # Element name (e.g., 'iron')
87
number: int # Atomic number
88
mass: float # Atomic mass in u
89
mass_units: str # Units for mass (typically 'u')
90
density: float # Density at STP in g/cm³
91
density_units: str # Units for density
92
93
# Container properties
94
isotopes: dict # Available isotopes
95
ions: dict # Available ions
96
97
def __getitem__(self, mass_number: int) -> Isotope:
98
"""Get isotope by mass number."""
99
100
def add_isotope(self, mass_number: int) -> Isotope:
101
"""Add new isotope with given mass number."""
102
103
@property
104
def ion(self) -> dict:
105
"""Access ions via element.ion[charge]."""
106
```
107
108
Lazy-loaded properties (loaded when first accessed):
109
110
```python { .api }
111
# Structural properties
112
covalent_radius: float # Covalent radius for bonding
113
covalent_radius_units: str # Units for covalent radius
114
covalent_radius_uncertainty: float # Uncertainty in covalent radius
115
crystal_structure: str # Crystal lattice structure
116
117
# Scattering properties
118
neutron: Neutron # Neutron scattering data
119
xray: Xray # X-ray scattering data
120
121
# Spectroscopic properties
122
K_alpha: float # K-alpha X-ray line wavelength
123
K_beta1: float # K-beta1 X-ray line wavelength
124
K_alpha_units: str # Units for K-alpha
125
K_beta1_units: str # Units for K-beta1
126
127
# Magnetic properties
128
magnetic_ff: dict # Magnetic form factors
129
130
# Nuclear properties (isotopes only)
131
neutron_activation: dict # Neutron activation data
132
```
133
134
Usage examples:
135
136
```python
137
import periodictable as pt
138
139
# Basic element properties
140
iron = pt.Fe
141
print(f"Symbol: {iron.symbol}") # Fe
142
print(f"Name: {iron.name}") # iron
143
print(f"Atomic number: {iron.number}") # 26
144
print(f"Mass: {iron.mass} {iron.mass_units}") # Mass in atomic mass units
145
print(f"Density: {iron.density} {iron.density_units}") # g/cm³
146
147
# Lazy-loaded properties (trigger data loading)
148
print(f"Covalent radius: {iron.covalent_radius} {iron.covalent_radius_units}")
149
print(f"Crystal structure: {iron.crystal_structure}")
150
151
# Check if neutron data is available
152
if hasattr(iron, 'neutron') and iron.neutron:
153
sld = iron.neutron.sld()
154
print(f"Neutron SLD: {sld}")
155
```
156
157
### Isotope Access and Properties
158
159
Access specific isotopes with detailed nuclear and scattering properties beyond the natural abundance data.
160
161
```python { .api }
162
class Isotope(Element):
163
"""Element isotope with specific mass number."""
164
165
# Isotope-specific properties
166
isotope: int # Mass number
167
abundance: float # Natural abundance (if available)
168
169
# Nuclear properties (when available)
170
nuclear_spin: float # Nuclear spin quantum number
171
magnetic_moment: float # Nuclear magnetic moment
172
173
@property
174
def ion(self) -> dict:
175
"""Access ions of this isotope via isotope.ion[charge]."""
176
```
177
178
Usage examples:
179
180
```python
181
import periodictable as pt
182
183
# Access isotopes
184
iron56 = pt.Fe[56] # Iron-56
185
nickel58 = pt.Ni[58] # Nickel-58
186
187
# Isotope properties
188
print(f"Isotope: {iron56.isotope}") # 56
189
print(f"Mass: {iron56.mass}") # Isotope-specific mass
190
191
# Nuclear properties (if available)
192
if hasattr(iron56, 'abundance'):
193
print(f"Natural abundance: {iron56.abundance}%")
194
195
# Neutron scattering for isotopes
196
if hasattr(iron56, 'neutron') and iron56.neutron:
197
b_coh = iron56.neutron.b_c
198
print(f"Coherent scattering length: {b_coh} fm")
199
```
200
201
### Ion Access and Properties
202
203
Access charged states of elements and isotopes with mass corrections for electron loss/gain.
204
205
```python { .api }
206
class Ion(Element):
207
"""Charged element or isotope."""
208
209
charge: int # Ion charge (positive for cations, negative for anions)
210
211
@property
212
def mass(self) -> float:
213
"""Mass adjusted for electron mass based on charge."""
214
```
215
216
Usage examples:
217
218
```python
219
import periodictable as pt
220
221
# Access ions
222
fe2_ion = pt.Fe.ion[2] # Fe²⁺ cation
223
fe3_ion = pt.Fe.ion[3] # Fe³⁺ cation
224
cl_ion = pt.Cl.ion[-1] # Cl⁻ anion
225
226
# Ion properties
227
print(f"Charge: {fe2_ion.charge}") # 2
228
print(f"Mass: {fe2_ion.mass}") # Mass corrected for electrons
229
230
# Isotope ions
231
fe56_2plus = pt.Fe[56].ion[2] # ⁵⁶Fe²⁺
232
print(f"Isotope: {fe56_2plus.isotope}") # 56
233
print(f"Charge: {fe56_2plus.charge}") # 2
234
```
235
236
### Table Iteration and Listing
237
238
Iterate through elements and create formatted property tables for data exploration and analysis.
239
240
```python { .api }
241
def __iter__(self) -> Iterator[Element]:
242
"""Iterate through all elements in atomic number order."""
243
244
def list(self, *props, **kwargs) -> None:
245
"""
246
Print formatted table of element properties.
247
248
Args:
249
*props: Property names to display
250
**kwargs: Formatting options
251
"""
252
```
253
254
Usage examples:
255
256
```python
257
import periodictable as pt
258
259
# Iterate through all elements
260
for element in pt.elements:
261
print(f"{element.number:3d} {element.symbol:2s} {element.name}")
262
263
# Create property tables
264
pt.elements.list('mass', 'density') # Mass and density table
265
pt.elements.list('symbol', 'covalent_radius') # Covalent radius table
266
267
# Filter elements (first 20)
268
for element in list(pt.elements)[:20]:
269
if element.density:
270
print(f"{element.symbol}: {element.density} g/cm³")
271
```
272
273
### Type Checking Utilities
274
275
Utility functions to test the type of atomic objects for safe property access and method dispatch.
276
277
```python { .api }
278
def isatom(val) -> bool:
279
"""Test if value is any atomic object (element, isotope, or ion)."""
280
281
def iselement(val) -> bool:
282
"""Test if value is an element (not isotope or ion)."""
283
284
def isisotope(val) -> bool:
285
"""Test if value is an isotope."""
286
287
def ision(val) -> bool:
288
"""Test if value is an ion."""
289
```
290
291
Usage examples:
292
293
```python
294
import periodictable as pt
295
from periodictable.core import isatom, iselement, isisotope, ision
296
297
# Test different atomic objects
298
iron = pt.Fe
299
iron56 = pt.Fe[56]
300
iron2_ion = pt.Fe.ion[2]
301
302
print(isatom(iron)) # True - all atoms
303
print(isatom(iron56)) # True
304
print(isatom(iron2_ion)) # True
305
306
print(iselement(iron)) # True - element only
307
print(iselement(iron56)) # False - isotope
308
print(iselement(iron2_ion)) # False - ion
309
310
print(isisotope(iron56)) # True - isotope
311
print(isisotope(iron)) # False - element
312
313
print(ision(iron2_ion)) # True - ion
314
print(ision(iron)) # False - element
315
```
316
317
## Types
318
319
```python { .api }
320
class PeriodicTable:
321
"""Container for all elements, isotopes, and ions."""
322
def __getitem__(self, key: int) -> Element: ...
323
def __iter__(self) -> Iterator[Element]: ...
324
def symbol(self, symbol: str) -> Element: ...
325
def name(self, name: str) -> Element: ...
326
def isotope(self, isotope_str: str) -> Isotope: ...
327
def list(self, *props, **kwargs) -> None: ...
328
329
class Element:
330
"""Individual element with properties and access to isotopes/ions."""
331
symbol: str
332
name: str
333
number: int
334
mass: float
335
mass_units: str
336
density: float
337
density_units: str
338
isotopes: dict
339
ions: dict
340
def __getitem__(self, mass_number: int) -> Isotope: ...
341
def add_isotope(self, mass_number: int) -> Isotope: ...
342
@property
343
def ion(self) -> dict: ...
344
345
class Isotope(Element):
346
"""Element isotope with specific mass number."""
347
isotope: int
348
abundance: float
349
nuclear_spin: float
350
magnetic_moment: float
351
352
class Ion(Element):
353
"""Charged element or isotope."""
354
charge: int
355
@property
356
def mass(self) -> float: ...
357
```