Skip to content

Commit 613c50f

Browse files
shyuepshyuep
committed
More AI doc improvements.
1 parent f00582a commit 613c50f

File tree

1 file changed

+66
-61
lines changed

1 file changed

+66
-61
lines changed

‎src/pymatgen/core/periodic_table.py‎

Lines changed: 66 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -61,71 +61,76 @@
6161
@functools.total_ordering
6262
@unique
6363
class ElementBase(Enum):
64-
"""Element class defined without any enum values so it can be subclassed.
65-
66-
This class is needed to get nested (as|from)_dict to work properly. All emmet classes that had
67-
Element classes required custom construction whereas this definition behaves more like dataclasses
68-
so serialization is less troublesome. There were many times where objects in as_dict serialized
69-
only when they were top level. See https://github.com/materialsproject/pymatgen/issues/2999.
70-
"""
64+
"""Element class defined without any enum values so it can be subclassed."""
7165

7266
def __init__(self, symbol: SpeciesLike) -> None:
73-
"""Basic immutable element object with all relevant properties.
74-
75-
Only one instance of Element for each symbol is stored after creation,
76-
ensuring that a particular element behaves like a singleton. For all
77-
attributes, missing data (i.e., data for which is not available) is
78-
represented by a None unless otherwise stated.
79-
80-
Args:
81-
symbol (str): Element symbol, e.g. "H", "Fe"
67+
"""
68+
This class provides a basic, immutable representation of an element, including
69+
all relevant chemical and physical properties. It ensures that elements are
70+
handled as singletons, reducing redundancy and improving efficiency. Missing
71+
data is represented by `None` unless otherwise specified.
8272
8373
Attributes:
84-
Z (int): Atomic number.
85-
symbol (str): Element symbol.
86-
long_name (str): Long name for element. e.g. "Hydrogen".
87-
A (int) : Atomic mass number (number of protons plus neutrons).
88-
atomic_radius_calculated (float): Calculated atomic radius for the element. This is the empirical value.
89-
Data is obtained from https://wikipedia.org/wiki/Atomic_radii_of_the_elements_(data_page).
90-
van_der_waals_radius (float): Van der Waals radius for the element. This is the empirical value determined
91-
from critical reviews of X-ray diffraction, gas kinetic collision cross-section, and other experimental
92-
data by Bondi and later workers. The uncertainty in these values is on the order of 0.1 Å.
93-
Data are obtained from "Atomic Radii of the Elements" in CRC Handbook of Chemistry and Physics,
94-
91st Ed.; Haynes, W.M., Ed.; CRC Press: Boca Raton, FL, 2010.
95-
mendeleev_no (int): Mendeleev number from definition given by Pettifor, D. G. (1984). A chemical scale
96-
for crystal-structure maps. Solid State Communications, 51 (1), 31-34.
97-
electrical_resistivity (float): Electrical resistivity.
98-
velocity_of_sound (float): Velocity of sound.
99-
reflectivity (float): Reflectivity.
100-
refractive_index (float): Refractive index.
101-
poissons_ratio (float): Poisson's ratio.
102-
molar_volume (float): Molar volume.
103-
electronic_structure (str): Electronic structure. e.g. The electronic structure for Fe is represented
104-
as [Ar].3d6.4s2.
105-
atomic_orbitals (dict): Atomic Orbitals. Energy of the atomic orbitals as a dict. e.g. The orbitals
106-
energies in Hartree are represented as {'1s': -1.0, '2s': -0.1}. Data is obtained from
107-
https://www.nist.gov/pml/data/atomic-reference-data-electronic-structure-calculations.
108-
The LDA values for neutral atoms are used.
109-
atomic_orbitals_eV (dict): Atomic Orbitals. Same as `atomic_orbitals` but energies are in eV.
110-
thermal_conductivity (float): Thermal conductivity.
111-
boiling_point (float): Boiling point.
112-
melting_point (float): Melting point.
113-
critical_temperature (float): Critical temperature.
114-
superconduction_temperature (float): Superconduction temperature.
115-
liquid_range (float): Liquid range.
116-
bulk_modulus (float): Bulk modulus.
117-
youngs_modulus (float): Young's modulus.
118-
brinell_hardness (float): Brinell hardness.
119-
rigidity_modulus (float): Rigidity modulus.
120-
mineral_hardness (float): Mineral hardness.
121-
vickers_hardness (float): Vicker's hardness.
122-
density_of_solid (float): Density of solid phase.
123-
coefficient_of_linear_thermal_expansion (float): Coefficient of linear thermal expansion.
124-
ground_level (float): Ground level for element.
125-
ionization_energies (list[Optional[float]]): List of ionization energies. First value is the first
126-
ionization energy, second is the second ionization energy, etc. Note that this is zero-based indexing!
127-
So Element.ionization_energies[0] refer to the 1st ionization energy. Values are from the NIST Atomic
128-
Spectra Database. Missing values are None.
74+
Z (int): Atomic number of the element.
75+
symbol (str): Element symbol (e.g., "H", "Fe").
76+
long_name (str): Full name of the element (e.g., "Hydrogen").
77+
A (int, optional): Atomic mass number (sum of protons and neutrons).
78+
atomic_radius_calculated (float, optional): Calculated atomic radius (Å).
79+
van_der_waals_radius (float, optional): Van der Waals radius (Å).
80+
mendeleev_no (int, optional): Mendeleev number based on crystal-structure maps.
81+
electrical_resistivity (float, optional): Electrical resistivity (Ω·m).
82+
velocity_of_sound (float, optional): Velocity of sound (m/s).
83+
reflectivity (float, optional): Reflectivity (%).
84+
refractive_index (float, optional): Refractive index.
85+
poissons_ratio (float, optional): Poisson's ratio.
86+
molar_volume (float, optional): Molar volume (cm³/mol).
87+
electronic_structure (str): Electronic structure (e.g., "[Ar].3d6.4s2").
88+
atomic_orbitals (dict): Orbital energies (Hartree units).
89+
atomic_orbitals_eV (dict): Orbital energies in electron volts (eV).
90+
thermal_conductivity (float, optional): Thermal conductivity (W/m·K).
91+
boiling_point (float, optional): Boiling point (K).
92+
melting_point (float, optional): Melting point (K).
93+
critical_temperature (float, optional): Critical temperature (K).
94+
superconduction_temperature (float, optional): Superconducting transition temperature (K).
95+
liquid_range (float, optional): Temperature range for liquid phase (K).
96+
bulk_modulus (float, optional): Bulk modulus (GPa).
97+
youngs_modulus (float, optional): Young's modulus (GPa).
98+
brinell_hardness (float, optional): Brinell hardness (MPa).
99+
rigidity_modulus (float, optional): Rigidity modulus (GPa).
100+
mineral_hardness (float, optional): Mohs hardness.
101+
vickers_hardness (float, optional): Vickers hardness (MPa).
102+
density_of_solid (float, optional): Density in solid phase (g/cm³).
103+
coefficient_of_linear_thermal_expansion (float, optional): Thermal expansion coefficient (K⁻¹).
104+
ground_level (float, optional): Ground energy level of the element.
105+
ionization_energies (list[Optional[float]]): Ionization energies (kJ/mol), indexed from 0.
106+
107+
Examples:
108+
Create an element instance and access its properties:
109+
>>> hydrogen = Element("H")
110+
>>> hydrogen.symbol
111+
'H'
112+
>>> hydrogen.Z
113+
1
114+
>>> hydrogen.electronic_structure
115+
'1s1'
116+
117+
Access additional attributes such as atomic radius:
118+
>>> hydrogen.atomic_radius_calculated
119+
0.53
120+
121+
Notes:
122+
- This class supports handling of isotopes by incorporating named isotopes
123+
and their respective properties.
124+
- Attributes are populated using a JSON file that stores data about all
125+
known elements.
126+
- Some attributes are calculated or derived based on predefined constants
127+
and rules.
128+
129+
References:
130+
- Atomic radius data: https://wikipedia.org/wiki/Atomic_radii_of_the_elements_(data_page)
131+
- Van der Waals radius: CRC Handbook of Chemistry and Physics, 91st Ed.
132+
- Mendeleev number: D. G. Pettifor, "A chemical scale for crystal-structure maps,"
133+
Solid State Communications, 1984.
129134
"""
130135
self.symbol = str(symbol)
131136
data = _pt_data[symbol]

0 commit comments

Comments
 (0)