Skip to content

Element

Module for static information about chemical elements.

Element

Storage class for information about a chemical element.

!!! examples
    >>> h = Element.from_string("H")
    >>> c = Element.from_string("C")
    >>> n = Element.from_atomic_number(7)
    >>> f = Element.from_string("F")

    Element implements an ordering for sorting in e.g.
    molecular formulae where carbon and hydrogen come first,
    otherwise elements are sorted in order of atomic number.

    >>> sorted([h, f, f, c, n])
    [C, H, N, F, F]

ball_stick_radius: float property readonly

The radius of this element in a ball and stick representation.

color property readonly

The color RGBA color of this element.

covalent_radius: float property readonly

The covalent radius in angstroms.

vdw_radius: float property readonly

The van der Waals radius in angstroms.

__eq__(self, other) special

Check if two Elements have the same atomic number.

Source code in chmpy/core/element.py
391
392
393
394
395
def __eq__(self, other):
    """Check if two Elements have the same atomic number."""
    if not self._is_valid_operand(other):
        raise NotImplementedError
    return self.atomic_number == other.atomic_number

__ge__(self, other, NotImplemented=NotImplemented) special

Return a >= b. Computed by @total_ordering from (not a < b).

Source code in chmpy/core/element.py
100
101
102
103
104
105
def _ge_from_lt(self, other, NotImplemented=NotImplemented):
    'Return a >= b.  Computed by @total_ordering from (not a < b).'
    op_result = self.__lt__(other)
    if op_result is NotImplemented:
        return op_result
    return not op_result

__gt__(self, other, NotImplemented=NotImplemented) special

Return a > b. Computed by @total_ordering from (not a < b) and (a != b).

Source code in chmpy/core/element.py
88
89
90
91
92
93
def _gt_from_lt(self, other, NotImplemented=NotImplemented):
    'Return a > b.  Computed by @total_ordering from (not a < b) and (a != b).'
    op_result = self.__lt__(other)
    if op_result is NotImplemented:
        return op_result
    return not op_result and self != other

__hash__(self) special

Hash of this element (its atomic number).

Source code in chmpy/core/element.py
384
385
386
def __hash__(self):
    """Hash of this element (its atomic number)."""
    return int(self.atomic_number)

__init__(self, atomic_number, name, symbol, cov, vdw, mass) special

Initialize an Element from its chemical data.

Source code in chmpy/core/element.py
270
271
272
273
274
275
276
277
def __init__(self, atomic_number, name, symbol, cov, vdw, mass):
    """Initialize an Element from its chemical data."""
    self.atomic_number = atomic_number
    self.name = name
    self.symbol = symbol
    self.cov = cov
    self.vdw = vdw
    self.mass = mass

__le__(self, other, NotImplemented=NotImplemented) special

Return a <= b. Computed by @total_ordering from (a < b) or (a == b).

Source code in chmpy/core/element.py
95
96
97
98
def _le_from_lt(self, other, NotImplemented=NotImplemented):
    'Return a <= b.  Computed by @total_ordering from (a < b) or (a == b).'
    op_result = self.__lt__(other)
    return op_result or self == other

__lt__(self, other) special

Check which element comes before the other in chemical formulae (C first, then order of atomic number).

Source code in chmpy/core/element.py
397
398
399
400
401
402
403
404
405
406
407
408
409
def __lt__(self, other):
    """Check which element comes before the other in chemical formulae (C first, then order of atomic number)."""
    if not self._is_valid_operand(other):
        raise NotImplementedError
    n1, n2 = self.atomic_number, other.atomic_number
    if n1 == n2:
        return False
    if n1 == 6:
        return True
    elif n2 == 6:
        return False
    else:
        return n1 < n2

__repr__(self) special

Represent this element as a string for REPL.

Source code in chmpy/core/element.py
380
381
382
def __repr__(self):
    """Represent this element as a string for REPL."""
    return self.symbol

from_atomic_number(n) staticmethod

Create an element from a given atomic number.

Parameters:

Name Type Description Default
n int

the atomic number of the element

required

Returns:

Type Description
Element

Element: an Element object if atomic number was valid, otherwise an exception is raised

Examples:

1
2
3
4
>>> Element.from_atomic_number(2)
He
>>> Element[79].name
'gold'
Source code in chmpy/core/element.py
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
@staticmethod
def from_atomic_number(n: int) -> "Element":
    """Create an element from a given atomic number.

    Args:
        n (int): the atomic number of the element

    Returns:
        Element: an Element object if atomic number was valid, otherwise an exception is raised

    Examples:
        >>> Element.from_atomic_number(2)
        He
        >>> Element[79].name
        'gold'
    """
    return Element(n, *_ELEMENT_DATA[n - 1])

from_label(label) staticmethod

Create an element from a label e.g. 'C1', 'H2_F2___i' etc.

Parameters:

Name Type Description Default
l str

a string representation of an element in the periodic table

required

Returns:

Type Description
Element

Element: an Element object if the conversion was successful, otherwise an exception is raised

Examples:

1
2
3
4
5
6
>>> Element.from_label("C1")
C
>>> Element.from_label("H")
H
>>> Element["LI2_F2____1____i"]
Li

An ambiguous case, will make this Calcium not Carbon

1
2
>>> Element.from_label("Ca2_F2____1____i")
Ca
Source code in chmpy/core/element.py
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
@staticmethod
def from_label(label: str) -> "Element":
    """Create an element from a label e.g. 'C1', 'H2_F2___i' etc.

    Args:
        l (str): a string representation of an element in the periodic table

    Returns:
        Element: an Element object if the conversion was successful, otherwise an exception is raised

    Examples:
        >>> Element.from_label("C1")
        C
        >>> Element.from_label("H")
        H
        >>> Element["LI2_F2____1____i"]
        Li

        An ambiguous case, will make this Calcium not Carbon
        >>> Element.from_label("Ca2_F2____1____i")
        Ca
    """
    m = re.match(_SYMBOL_REGEX, label)
    if m is None:
        raise ValueError("Could not determine symbol from {}".format(label))
    sym = m.group(1).strip().capitalize()
    if sym not in _EL_FROM_SYM:
        raise ValueError("Could not determine symbol from {}".format(label))
    return Element(*_EL_FROM_SYM[sym])

from_string(s) staticmethod

Create an element from a given element symbol.

Parameters:

Name Type Description Default
s str

a string representation of an element in the periodic table

required

Returns:

Type Description
Element

Element: an Element object if the conversion was successful, otherwise an exception is raised

Examples:

1
2
3
4
5
6
>>> Element.from_string("h")
H
>>> Element["rn"].name
'radon'
>>> Element["AC"].cov
2.15
Source code in chmpy/core/element.py
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
@staticmethod
def from_string(s: str) -> "Element":
    """Create an element from a given element symbol.

    Args:
        s (str): a string representation of an element in the periodic table

    Returns:
        Element: an Element object if the conversion was successful, otherwise an exception is raised

    Examples:
        >>> Element.from_string("h")
        H
        >>> Element["rn"].name
        'radon'
        >>> Element["AC"].cov
        2.15
    """
    symbol = s.strip().capitalize()
    if symbol == "D":
        symbol = "H"
    if symbol.isdigit():
        return Element.from_atomic_number(int(symbol))
    if symbol not in _EL_FROM_SYM:
        name = symbol.lower()
        if name not in _EL_FROM_NAME:
            return Element.from_label(s)
        else:
            return Element(*_EL_FROM_NAME[name])
    return Element(*_EL_FROM_SYM[symbol])

chemical_formula(elements, subscript=False)

Calculate the chemical formula for the given list of elements.

Examples:

1
2
3
4
>>> chemical_formula(['O', 'C', 'O'])
'CO2'
>>> chemical_formula(['C', 'H', 'O', 'B'])
'BCHO'

Parameters:

Name Type Description Default
elements List[Element or str]

a list of elements or element symbols. Note that if a list of strings are provided the order of chemical symbols may not match convention.

required
subscript bool, optoinal

toggle to use unicode subscripts for the chemical formula string

False

Returns:

Type Description
str

the chemical formula

Source code in chmpy/core/element.py
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
def chemical_formula(elements, subscript=False):
    """Calculate the chemical formula for the given list of elements.

    Examples:
        >>> chemical_formula(['O', 'C', 'O'])
        'CO2'
        >>> chemical_formula(['C', 'H', 'O', 'B'])
        'BCHO'

    Args:
        elements (List[Element or str]): a list of elements or element symbols.
            Note that if a list of strings are provided the order of chemical
            symbols may not match convention.
        subscript (bool, optoinal): toggle to use unicode subscripts for the chemical formula string

    Returns:
        str: the chemical formula
    """
    count = Counter(sorted(elements))
    if subscript:
        blocks = []
        for el, c in count.items():
            c = "".join(chr(0x2080 + int(i)) for i in str(c)) if c > 1 else ""
            blocks.append(f"{el}{c}")
    else:
        blocks = []
        for el, c in count.items():
            c = c if c > 1 else ""
            blocks.append(f"{el}{c}")
    return "".join(blocks)

cov_radii(atomic_numbers)

Return the covalent radii for the given atomic numbers.

Parameters:

Name Type Description Default
atomic_numbers array_like

the (N,) length integer array of atomic numbers

required

Returns:

Type Description
np.ndarray

(N,) array of floats representing covalent radii

Source code in chmpy/core/element.py
444
445
446
447
448
449
450
451
452
453
454
455
def cov_radii(atomic_numbers):
    """Return the covalent radii for the given atomic numbers.

    Args:
        atomic_numbers (array_like): the (N,) length integer array of atomic numbers

    Returns:
        np.ndarray: (N,) array of floats representing covalent radii
    """
    if np.any(atomic_numbers < 1) or np.any(atomic_numbers > 103):
        raise ValueError("All elements must be atomic numbers between [1,103]")
    return np.array([_ELEMENT_DATA[i - 1][2] for i in atomic_numbers], dtype=np.float32)

element_names(atomic_numbers)

Return the element names for the given atomic numbers.

Parameters:

Name Type Description Default
atomic_numbers array_like

the (N,) length integer array of atomic numbers

required

Returns:

Type Description
List[str]

(N,) list of strings representing element names

Source code in chmpy/core/element.py
472
473
474
475
476
477
478
479
480
481
482
483
def element_names(atomic_numbers):
    """Return the element names for the given atomic numbers.

    Args:
        atomic_numbers (array_like): the (N,) length integer array of atomic numbers

    Returns:
        List[str]: (N,) list of strings representing element names
    """
    if np.any(atomic_numbers < 1) or np.any(atomic_numbers > 103):
        raise ValueError("All elements must be atomic numbers between [1,103]")
    return [_ELEMENT_DATA[i - 1][0] for i in atomic_numbers]

element_symbols(atomic_numbers)

Return the element symbols for the given atomic numbers.

Parameters:

Name Type Description Default
atomic_numbers array_like

the (N,) length integer array of atomic numbers

required

Returns:

Type Description
List[str]

(N,) list of strings representing element symbols

Source code in chmpy/core/element.py
486
487
488
489
490
491
492
493
494
495
496
497
def element_symbols(atomic_numbers):
    """Return the element symbols for the given atomic numbers.

    Args:
        atomic_numbers (array_like): the (N,) length integer array of atomic numbers

    Returns:
        List[str]: (N,) list of strings representing element symbols
    """
    if np.any(atomic_numbers < 1) or np.any(atomic_numbers > 103):
        raise ValueError("All elements must be atomic numbers between [1,103]")
    return [_ELEMENT_DATA[i - 1][1] for i in atomic_numbers]

vdw_radii(atomic_numbers)

Return the van der Waals radii for the given atomic numbers.

Parameters:

Name Type Description Default
atomic_numbers array_like

the (N,) length integer array of atomic numbers

required

Returns:

Type Description
np.ndarray

(N,) array of floats representing van der Waals radii

Source code in chmpy/core/element.py
458
459
460
461
462
463
464
465
466
467
468
469
def vdw_radii(atomic_numbers):
    """Return the van der Waals radii for the given atomic numbers.

    Args:
        atomic_numbers (array_like): the (N,) length integer array of atomic numbers

    Returns:
        np.ndarray: (N,) array of floats representing van der Waals radii
    """
    if np.any(atomic_numbers < 1) or np.any(atomic_numbers > 103):
        raise ValueError("All elements must be atomic numbers between [1,103]")
    return np.array([_ELEMENT_DATA[i - 1][3] for i in atomic_numbers], dtype=np.float32)