Welcome to elementable’s documentation!
Elementable is another elements package defined in Python. It is written to be usable with a number of different unit systems and classes. At its most minimal, it has no dependencies outside the main Python library. However, Elementable can be combined with units packages such as OpenFF-Units, and fun subclasses such as Pydantic.
Elementable was written because many, many, many other elements packages and distributions already exist. Most downstream packages are looking for different things out of an elements package; some value being lightweight, some value complete data, some require specific data, some require a units system, some might need elements to be serializable, etc. Elementable aims to provide a single solution by enabling packages to ship their own required datasets, base classes, units, and so on, using Elementable’s general API.
I mostly envision Elementable being used in a separate elements.py
module in a library. For example, the below class creates a Pydantic BaseModel
subclass with OpenForceField units.
In [1]: import elementable as elm
In [2]: from pydantic import BaseModel
In [3]: from openff.units import unit
In [4]: class Element(BaseModel):
...: class Config:
...: arbitrary_types_allowed = True
...: json_encoders = {unit.Quantity: str}
...:
In [5]: elements = elm.Elementable(
...: units=dict(
...: mass=unit.amu,
...: covalent_radius=unit.angstrom,
...: ),
...: element_cls=Element
...: )
...:
In [6]: print(elements.H)
name='hydrogen' symbol='H' atomic_number=1 mass=<Quantity(1.00782503, 'unified_atomic_mass_unit')> period=1 group=1 covalent_radius=<Quantity(0.31, 'angstrom')>
In [7]: print(elements.H.mass)
1.00782503223 u
In [8]: print(elements.H.json())
{"name": "hydrogen", "symbol": "H", "atomic_number": 1, "mass": "1.00782503223 u", "period": 1, "group": 1, "covalent_radius": "0.31 \u00c5"}
In [9]: print(elements(mass=1.6735328346123168e-09 * unit.fg))
name='hydrogen' symbol='H' atomic_number=1 mass=<Quantity(1.00782503, 'unified_atomic_mass_unit')> period=1 group=1 covalent_radius=<Quantity(0.31, 'angstrom')>
Installation
Elementable can be installed via pip or conda.
pip install elementable
# or
conda install -c conda-forge elementable
Alternatively, you can download the repository and build from source.
git clone https://github.com/lilyminium/elementable.git
cd elementable
python setup.py install