0
# Periodictable
1
2
An extensible periodic table of the elements with comprehensive support for mass, density, X-ray and neutron scattering information. This package enables scientific calculations including neutron activation analysis, X-ray scattering factor computations, and chemical formula processing with composite material property calculations.
3
4
## Package Information
5
6
- **Package Name**: periodictable
7
- **Language**: Python
8
- **Installation**: `pip install periodictable`
9
- **Documentation**: https://periodictable.readthedocs.io
10
11
## Core Imports
12
13
```python
14
import periodictable
15
```
16
17
Access the main periodic table:
18
19
```python
20
from periodictable import elements
21
```
22
23
Direct element imports:
24
25
```python
26
from periodictable import H, He, Li, Fe, Ni # Individual elements by symbol
27
from periodictable import hydrogen, helium, iron # Individual elements by name
28
```
29
30
## Basic Usage
31
32
```python
33
import periodictable as pt
34
35
# Access elements by symbol, name, or atomic number
36
iron = pt.Fe # or pt.iron or pt.elements[26]
37
nickel = pt.elements.Ni
38
39
# Access isotopes and ions
40
iron56 = pt.Fe[56] # Iron-56 isotope
41
iron2plus = pt.Fe.ion[2] # Fe2+ ion
42
deuterium = pt.D # Special symbol for deuterium
43
44
# Element properties (lazy-loaded)
45
print(f"Iron mass: {iron.mass} {iron.mass_units}")
46
print(f"Iron density: {iron.density} {iron.density_units}")
47
48
# Chemical formulas and calculations
49
water = pt.formula("H2O")
50
print(f"Water molecular mass: {water.mass} u")
51
52
# Neutron scattering length density
53
sld_real, sld_imag, sld_inc = pt.neutron_sld(water, density=1.0)
54
print(f"Water neutron SLD: {sld_real:.4f} × 10⁻⁶ Ų⁻²")
55
```
56
57
## Architecture
58
59
The periodictable package uses a modular architecture with lazy loading for performance:
60
61
- **PeriodicTable**: Central table containing all elements, isotopes, and ions
62
- **Element/Isotope/Ion Classes**: Core data structures with dynamic property loading
63
- **Formula System**: Chemical formula parser with composition and property calculations
64
- **Scattering Modules**: Specialized calculations for neutron (nsf) and X-ray (xsf) scattering
65
- **Property System**: Extensible lazy-loading mechanism for element attributes
66
- **Data Integration**: Authoritative data from NIST, NCNR, and other scientific sources
67
68
This design enables efficient memory usage through on-demand loading while providing comprehensive access to elemental data and scientific calculations.
69
70
## Capabilities
71
72
### Element and Isotope Access
73
74
Core functionality for accessing elements, isotopes, and ions from the periodic table with comprehensive property data including mass, density, and atomic structure information.
75
76
```python { .api }
77
# PeriodicTable access methods
78
elements[atomic_number: int] -> Element
79
elements.symbol(symbol: str) -> Element
80
elements.name(name: str) -> Element
81
elements.isotope(isotope_str: str) -> Isotope
82
83
# Element properties and methods
84
Element.symbol: str
85
Element.name: str
86
Element.number: int
87
Element.mass: float
88
Element.density: float
89
Element[mass_number: int] -> Isotope
90
Element.ion[charge: int] -> Ion
91
```
92
93
[Elements and Isotopes](./elements.md)
94
95
### Chemical Formula Processing
96
97
Parse chemical formulas, calculate molecular properties, create mixtures by weight or volume, and perform isotope substitutions with full support for composite material calculations.
98
99
```python { .api }
100
def formula(compound: str = None, density: float = None,
101
natural_density: float = None, name: str = None) -> Formula
102
def mix_by_weight(*args, **kwargs) -> Formula
103
def mix_by_volume(*args, **kwargs) -> Formula
104
105
# Formula class properties and methods
106
Formula.atoms: dict
107
Formula.mass: float
108
Formula.density: float
109
Formula.charge: int
110
Formula.replace(source, target, portion: float = 1) -> Formula
111
```
112
113
[Chemical Formulas](./formulas.md)
114
115
### Neutron Scattering Calculations
116
117
Comprehensive neutron scattering calculations including scattering length densities, cross sections, and penetration depths for elements, isotopes, and compounds with energy-dependent and activation analysis support.
118
119
```python { .api }
120
def neutron_sld(compound, density: float = None, wavelength: float = None) -> tuple
121
def neutron_scattering(compound, density: float = None, wavelength: float = None) -> dict
122
def neutron_wavelength(energy: float) -> float
123
def neutron_energy(wavelength: float) -> float
124
```
125
126
[Neutron Scattering](./neutron-scattering.md)
127
128
### X-ray Scattering Calculations
129
130
X-ray scattering factor calculations, scattering length densities, form factors, and optical properties including refractive indices and mirror reflectivity for crystallographic and materials science applications.
131
132
```python { .api }
133
def xray_sld(compound, density: float = None, energy: float = None,
134
wavelength: float = None) -> tuple
135
def xray_wavelength(energy: float) -> float
136
def xray_energy(wavelength: float) -> float
137
def index_of_refraction(compound, density: float = None, energy: float = None,
138
wavelength: float = None) -> complex
139
```
140
141
[X-ray Scattering](./xray-scattering.md)
142
143
### Physical Constants and Utilities
144
145
Fundamental physical constants, crystallographic calculations, uncertainty parsing, and periodic table data visualization tools for scientific applications.
146
147
```python { .api }
148
# Constants module
149
avogadro_number: float = 6.02214076e23
150
planck_constant: float = 6.62607015e-34
151
electron_volt: float = 1.602176634e-19
152
speed_of_light: float = 299792458
153
154
# Utility functions
155
def parse_uncertainty(s: str) -> tuple
156
def cell_volume(a: float = None, b: float = None, c: float = None,
157
alpha: float = None, beta: float = None,
158
gamma: float = None) -> float
159
160
# Core utility functions
161
def default_table(table=None) -> PeriodicTable
162
def change_table(atom, table) -> Union[Element, Isotope, Ion]
163
def isatom(val) -> bool
164
def iselement(val) -> bool
165
def isisotope(val) -> bool
166
def ision(val) -> bool
167
```
168
169
[Constants and Utilities](./constants-utilities.md)
170
171
## Types
172
173
```python { .api }
174
class PeriodicTable:
175
"""Periodic table containing all elements, isotopes, and ions."""
176
def __getitem__(self, key: int) -> Element: ...
177
def __iter__(self) -> Iterator[Element]: ...
178
def symbol(self, symbol: str) -> Element: ...
179
def name(self, name: str) -> Element: ...
180
def isotope(self, isotope_str: str) -> Isotope: ...
181
182
class Element:
183
"""Individual element with properties and access to isotopes/ions."""
184
symbol: str
185
name: str
186
number: int
187
mass: float
188
mass_units: str
189
density: float
190
density_units: str
191
def __getitem__(self, mass_number: int) -> Isotope: ...
192
def add_isotope(self, mass_number: int) -> Isotope: ...
193
@property
194
def ion(self) -> dict: ...
195
196
class Isotope(Element):
197
"""Element isotope with specific mass number."""
198
isotope: int
199
@property
200
def ion(self) -> dict: ...
201
202
class Ion(Element):
203
"""Charged element or isotope."""
204
charge: int
205
206
class Formula:
207
"""Parsed chemical formula with calculation capabilities."""
208
atoms: dict
209
mass: float
210
molecular_mass: float
211
density: float
212
charge: int
213
hill: str
214
mass_fraction: dict
215
def replace(self, source, target, portion: float = 1) -> 'Formula': ...
216
def neutron_sld(self, wavelength: float = None, energy: float = None) -> tuple: ...
217
def xray_sld(self, energy: float = None, wavelength: float = None) -> tuple: ...
218
def change_table(self, table) -> 'Formula': ...
219
def __add__(self, other: 'Formula') -> 'Formula': ...
220
def __iadd__(self, other: 'Formula') -> 'Formula': ...
221
def __rmul__(self, multiplier: float) -> 'Formula': ...
222
```