asedb package

Submodules

asedb.abstract module

class asedb.abstract.ArrayType(*args: Any, **kwargs: Any)

Bases: TypeDecorator

Custom type for saving/loading NumPy arrays.

compare_values(x: Any, y: Any) → bool

Given two values, compare them for equality.

By default this calls upon TypeEngine.compare_values() of the underlying “impl”, which in turn usually uses the Python equals operator ==.

This function is used by the ORM to compare an original-loaded value with an intercepted “changed” value, to determine if a net change has occurred.

impl

alias of LargeBinary

process_bind_param(value, dialect)

Convert the array going into the database.

process_result_value(value, dialect)

Convert the result coming from the database.

class asedb.abstract.NamedArray(**kwargs: Any)

Bases: Base

Base table object for storing a NumPy array along with a name and some metadata.

property array_meta: None | dict[str, Any]

array_meta_json: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>

array_obj: Mapped[ndarray] = <sqlalchemy.orm.properties.MappedColumn object>

classmethod from_np_array(name: str, array: ndarray) → T_Arr

Construct an instance of the NamedArray model from a NumPy array.

get_array() → ndarray

Access the NumPy array object from the model.

id: Mapped[int] = <sqlalchemy.orm.properties.MappedColumn object>

last_update_time: Mapped[float] = <sqlalchemy.orm.properties.MappedColumn object>

name: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>

set_array(array: ndarray | Cell) → None

Update the blob representing a NumPy array. The array will be serialized to a binary blob using the NumPy save function.

Note: Arbitrary Python objects are not allowed, as Pickle serialization is disabled by default for security purposes. Change the asedb.abstract.ALLOW_PICKLE variable to True to allow pickle serialization.

asedb.atoms_model module

class asedb.atoms_model.AtomsArray(**kwargs)

Bases: NamedArray

array_meta_json: Mapped[str]

array_obj: Mapped[ndarray]

atoms_id: Mapped[int]

id: Mapped[int]

last_update_time: Mapped[float]

name: Mapped[str]

class asedb.atoms_model.AtomsModel(**kwargs)

Bases: Base

The primary class representing the SQLAlchemy model for an ASE Atoms object.

The main usage will be something like

atoms = ase.Atoms(...)
model = AtomsModel.from_atoms(atoms)
session.add(model)
session.commit()

# Load the model from the database
loaded = session.query(AtomsModel).first().to_atoms()

The AtomsModel will also serialize a calculator object into a Calculation if a calculator exists.

arrays: Mapped[list[AtomsArray]]

calculation: Mapped[Calculation]

creation_time: Mapped[float]

elements: Mapped[list[Element]]

classmethod from_atoms(atoms: Atoms, import_calculation: bool = True, project: None | str = None) → AtomsModel

Helper method to instantiate an AtomsModel instance from an ASE Atoms object.

Parameters:

• atoms (ase.Atoms) – The ASE Atoms instance.

• import_calculation (bool, optional) – Whether the calculator should be imported, if it exists. Defaults to True.

• project (None | str, optional) – An optional project name. Defaults to None.

Returns:

The newly instantiated AtomsModel.

Return type:

AtomsModel

get_element_counts() → int

Get the number of times a particular element occurs in the model.

property has_calc: bool

id: Mapped[int]

last_updated: Mapped[float]

natoms: Mapped[int]

property pbc: ndarray

The full period boundary conditions.

pbc_int: Mapped[int]

project: Mapped[str]

set_atoms(atoms: Atoms, import_calculation: bool = True) → None

Read the current Atoms configurations, including the calculator, and save the state in the current AtomsModel instance.

If import_calculation is True, then the calculator object will also be serialized into a Calculation object, otherwise the calculator will be ignored.

set_calculation(atoms: Atoms) → None

Update the calculation cache for an Atoms object.

to_atoms() → Atoms

Export the SQL Alchemy object as an ASE Atoms object. If a corresponding Calculation object exists, a SinglePointCalculator will be attached to the constructed Atoms object.

class asedb.atoms_model.CalcArray(**kwargs)

Bases: NamedArray

array_meta_json: Mapped[str]

array_obj: Mapped[ndarray]

calc_id: Mapped[int]

id: Mapped[int]

last_update_time: Mapped[float]

name: Mapped[str]

class asedb.atoms_model.Calculation(**kwargs)

Bases: Base

The serialization of an ASE Calculator.

add_array(name: str, array: ndarray) → None

arrays: Mapped[list[CalcArray]]

atoms_id: Mapped[int]

drop_array(name: str) → None

energy: Mapped[float]

fmax: Mapped[float]

free_energy: Mapped[float]

classmethod from_calc(calc: Calculator) → Calculation

Construct a Calculation object from an ASE Calculator. Extracts the following properties: As floats:

• energy

• free_energy

• magmom

As arrays:

• forces

• stress

• stresses

• charges

• magmoms

get_calc_kwargs() → Mapping[str, float | ndarray]

id: Mapped[int]

magmom: Mapped[float]

class asedb.atoms_model.Element(**kwargs)

Bases: Base

atoms_id: Mapped[int]

count: Mapped[int]

id: Mapped[int]

symbol: Mapped[str]

asedb.initialization module

asedb.initialization.create_schema(engine: Engine)

asedb.initialization.initialize_engine(engine: Engine)

asedb.initialization.make_sqlite_engine(filename: str, initialize: bool = False) → Engine

Helper function to create a sqlite Engine, that disables the usage of the default schema.

asedb.properties module

class asedb.properties.ArrayProperties(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: _PropertyBase

CHARGES = 'charges'

FORCES = 'forces'

MAGMOMS = 'magmoms'

STRESS = 'stress'

STRESSES = 'stresses'

class asedb.properties.ValueProperties(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: _PropertyBase

ENERGY = 'energy'

FREE_ENERGY = 'free_energy'

MAGMOM = 'magmom'

asedb.time_utils module

asedb.time_utils.datetime_from_timestamp(timestamp: float) → DateTime

Convert a float POSIX time to a datetime object in UTC.

asedb.time_utils.get_posix_timestamp() → float

The current POSIX time as a float.

asedb.trajectory_model module

class asedb.trajectory_model.Trajectory(**kwargs)

Bases: Base

add_atoms(atoms: Atoms) → AtomsModel

Add an Atoms object to the Trajectory. Returns the newly created AtomsModel instance, which belongs to the trajectory.

atoms_list: Mapped[list[AtomsModel]]

id: Mapped[int]

project: Mapped[str]

to_atoms_list() → list[Atoms]

asedb.utils module

asedb.utils.float_or_none(value: Any) → float | None

asedb.version module

asedb.version.get_version() → Version

Get the packaging Version object for the package.

Module contents

class asedb.AtomsModel(**kwargs)

Bases: Base

The primary class representing the SQLAlchemy model for an ASE Atoms object.

The main usage will be something like

atoms = ase.Atoms(...)
model = AtomsModel.from_atoms(atoms)
session.add(model)
session.commit()

# Load the model from the database
loaded = session.query(AtomsModel).first().to_atoms()

The AtomsModel will also serialize a calculator object into a Calculation if a calculator exists.

arrays: Mapped[list[AtomsArray]]

calculation: Mapped[Calculation]

creation_time: Mapped[float]

elements: Mapped[list[Element]]

classmethod from_atoms(atoms: Atoms, import_calculation: bool = True, project: None | str = None) → AtomsModel

Helper method to instantiate an AtomsModel instance from an ASE Atoms object.

Parameters:

• atoms (ase.Atoms) – The ASE Atoms instance.

• import_calculation (bool, optional) – Whether the calculator should be imported, if it exists. Defaults to True.

• project (None | str, optional) – An optional project name. Defaults to None.

Returns:

The newly instantiated AtomsModel.

Return type:

AtomsModel

get_element_counts() → int

Get the number of times a particular element occurs in the model.

property has_calc: bool

id: Mapped[int]

last_updated: Mapped[float]

natoms: Mapped[int]

property pbc: ndarray

The full period boundary conditions.

pbc_int: Mapped[int]

project: Mapped[str]

set_atoms(atoms: Atoms, import_calculation: bool = True) → None

Read the current Atoms configurations, including the calculator, and save the state in the current AtomsModel instance.

If import_calculation is True, then the calculator object will also be serialized into a Calculation object, otherwise the calculator will be ignored.

set_calculation(atoms: Atoms) → None

Update the calculation cache for an Atoms object.

to_atoms() → Atoms

Export the SQL Alchemy object as an ASE Atoms object. If a corresponding Calculation object exists, a SinglePointCalculator will be attached to the constructed Atoms object.

class asedb.Calculation(**kwargs)

Bases: Base

The serialization of an ASE Calculator.

add_array(name: str, array: ndarray) → None

arrays: Mapped[list[CalcArray]]

atoms_id: Mapped[int]

drop_array(name: str) → None

energy: Mapped[float]

fmax: Mapped[float]

free_energy: Mapped[float]

classmethod from_calc(calc: Calculator) → Calculation

Construct a Calculation object from an ASE Calculator. Extracts the following properties: As floats:

• energy

• free_energy

• magmom

As arrays:

• forces

• stress

• stresses

• charges

• magmoms

get_calc_kwargs() → Mapping[str, float | ndarray]

id: Mapped[int]

magmom: Mapped[float]

class asedb.Element(**kwargs)

Bases: Base

atoms_id: Mapped[int]

count: Mapped[int]

id: Mapped[int]

symbol: Mapped[str]

class asedb.Trajectory(**kwargs)

Bases: Base

add_atoms(atoms: Atoms) → AtomsModel

Add an Atoms object to the Trajectory. Returns the newly created AtomsModel instance, which belongs to the trajectory.

atoms_list: Mapped[list[AtomsModel]]

id: Mapped[int]

project: Mapped[str]

to_atoms_list() → list[Atoms]

asedb.initialize_engine(engine: Engine)

asedb.make_sqlite_engine(filename: str, initialize: bool = False) → Engine

Helper function to create a sqlite Engine, that disables the usage of the default schema.