asedb package

Submodules

asedb.abstract module

class asedb.abstract.ArrayType(*args: Any, **kwargs: Any)[source]

Bases: TypeDecorator

Custom type for saving/loading NumPy arrays.

compare_values(x: Any, y: Any) → bool[source]

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)[source]: Convert the array going into the database.

process_result_value(value, dialect)[source]: Convert the result coming from the database.

class asedb.abstract.NamedArray(**kwargs: Any)[source]

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[source]: Construct an instance of the NamedArray model from a NumPy array.

get_array() → ndarray[source]: 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[source]

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)[source]

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)[source]

Bases: Base

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

This class facilitates the storage and retrieval of atomic structures within a relational database, utilizing the SQLAlchemy ORM. It intends to seamlessly serialize and deserialize ASE Atoms objects, including their associated calculator results when available.

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[source]

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() → dict[str, int][source]

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

Returns:: A dictionary with element symbols as keys and their counts as values.
Return type:: dict[str, int]

property has_calc: bool: Indicates whether the atoms object represented by the model has an associated calculator.

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[source]

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.

to_atoms() → Atoms[source]: 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)[source]

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)[source]

Bases: Base

Represents the serialization of an ASE Calculator, encapsulating the results of computational chemistry calculations. This class stores various properties such as energy, free energy, magnetic moment, and the maximum force acting on atoms alongside arbitrary arrays of data like forces or stresses that are results of these calculations.

id

The primary key in the database.

Type:: int

atoms_id

A foreign key linking to the AtomsModel this calculation is associated with.

Type:: int

energy

The total energy from the calculation.

Type:: float, optional

free_energy

The free energy from the calculation, if available.

Type:: float, optional

magmom

The total magnetic moment from the calculation.

Type:: float, optional

fmax

The maximum force acting on any atom in the structure, derived from the forces array.

Type:: float, optional

arrays

A relationship to a collection of CalcArray instances that store arbitrary array results from the calculation.

Type:: list[CalcArray]

The class provides methods to construct a Calculation instance from an ASE Calculator object, manage result arrays, and retrieve calculation results for re-creation of an ASE Calculator object for further analysis.

Example usage:

from ase.calculators.emt import EMT
from ase.build import molecule
from asedb import Calculation, AtomsModel

atoms = molecule('H2O')
atoms.calc = EMT()
energy = atoms.get_potential_energy()

model = AtomsModel.from_atoms(atoms)
# The calc object now contains the calculation results and can be associated with an AtomsModel
assert energy == model.calculation.energy

add_array(name: str, array: ndarray) → None[source]

Adds an array of calculation results to the Calculation object.

This method is used to store additional arrays of results, such as forces or stress tensors, that come from the calculation. If adding forces, the maximum force (fmax) is automatically updated.

Parameters:

name (str) – The name of the array (e.g., “forces”, “stress”).
array (np.ndarray) – The numpy array containing the calculation results.

arrays: Mapped[list[CalcArray]]

atoms_id: Mapped[int]

drop_array(name: str) → None[source]

Removes an array of calculation results from the Calculation object.

This method allows for the removal of specific arrays of results, useful for correcting or updating calculation data.

Parameters:: name (str) – The name of the array to remove (e.g., “forces”, “stress”).
Raises:: ValueError – If the specified array name does not exist within the Calculation object.

energy: Mapped[float]

fmax: Mapped[float]

free_energy: Mapped[float]

classmethod from_calc(calc: Calculator) → Calculation[source]

Constructs a Calculation instance from an ASE Calculator object, extracting relevant calculation results and arrays.

Parameters:: calc (AseCalculator) – The ASE Calculator object from which to extract calculation results.
Returns:: An instance of Calculation populated with results from the ASE Calculator.
Return type:: Calculation

This method automatically extracts properties like energy, free energy, and magnetic moment as floats, and results like forces, stress, and magnetic moments as arrays, storing them for later reconstruction.

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

Retrieves calculation results stored in the Calculation object, formatted for re-creation of an ASE Calculator object.

This method facilitates the reconstruction of an ASE Calculator object from stored calculation results.

Returns:

A dictionary of calculation properties and results,: ready to be passed to an ASE Calculator constructor.

Return type:

Mapping[str, float | np.ndarray]

id: Mapped[int]

magmom: Mapped[float]

class asedb.atoms_model.Element(**kwargs)[source]

Bases: Base

atoms_id: Mapped[int]

count: Mapped[int]

id: Mapped[int]

symbol: Mapped[str]

asedb.initialization module

asedb.initialization.create_schema(engine: Engine)[source]

asedb.initialization.initialize_engine(engine: Engine)[source]

asedb.initialization.make_sqlite_engine(filename: str, initialize: bool = False) → Engine[source]: 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)[source]

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)[source]

Bases: _PropertyBase

ENERGY = 'energy'

FREE_ENERGY = 'free_energy'

MAGMOM = 'magmom'

asedb.time_utils module

asedb.time_utils.datetime_from_timestamp(timestamp: float) → DateTime[source]: Convert a float POSIX time to a datetime object in UTC.

asedb.time_utils.get_posix_timestamp() → float[source]: The current POSIX time as a float.

asedb.trajectory_model module

class asedb.trajectory_model.Trajectory(**kwargs)[source]

Bases: Base

add_atoms(atoms: Atoms) → AtomsModel[source]: 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][source]

asedb.utils module

asedb.utils.float_or_none(value: Any) → float | None[source]

asedb.version module

asedb.version.get_version() → Version[source]: Get the packaging Version object for the package.

Module contents

class asedb.AtomsModel(**kwargs)[source]

Bases: Base

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

This class facilitates the storage and retrieval of atomic structures within a relational database, utilizing the SQLAlchemy ORM. It intends to seamlessly serialize and deserialize ASE Atoms objects, including their associated calculator results when available.

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[source]

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() → dict[str, int][source]

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

Returns:: A dictionary with element symbols as keys and their counts as values.
Return type:: dict[str, int]

property has_calc: bool: Indicates whether the atoms object represented by the model has an associated calculator.

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[source]

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.

to_atoms() → Atoms[source]: 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)[source]

Bases: Base

Represents the serialization of an ASE Calculator, encapsulating the results of computational chemistry calculations. This class stores various properties such as energy, free energy, magnetic moment, and the maximum force acting on atoms alongside arbitrary arrays of data like forces or stresses that are results of these calculations.

id

The primary key in the database.

Type:: int

atoms_id

A foreign key linking to the AtomsModel this calculation is associated with.

Type:: int

energy

The total energy from the calculation.

Type:: float, optional

free_energy

The free energy from the calculation, if available.

Type:: float, optional

magmom

The total magnetic moment from the calculation.

Type:: float, optional

fmax

The maximum force acting on any atom in the structure, derived from the forces array.

Type:: float, optional

arrays

A relationship to a collection of CalcArray instances that store arbitrary array results from the calculation.

Type:: list[CalcArray]

The class provides methods to construct a Calculation instance from an ASE Calculator object, manage result arrays, and retrieve calculation results for re-creation of an ASE Calculator object for further analysis.

Example usage:

from ase.calculators.emt import EMT
from ase.build import molecule
from asedb import Calculation, AtomsModel

atoms = molecule('H2O')
atoms.calc = EMT()
energy = atoms.get_potential_energy()

model = AtomsModel.from_atoms(atoms)
# The calc object now contains the calculation results and can be associated with an AtomsModel
assert energy == model.calculation.energy

add_array(name: str, array: ndarray) → None[source]

Adds an array of calculation results to the Calculation object.

This method is used to store additional arrays of results, such as forces or stress tensors, that come from the calculation. If adding forces, the maximum force (fmax) is automatically updated.

Parameters:

name (str) – The name of the array (e.g., “forces”, “stress”).
array (np.ndarray) – The numpy array containing the calculation results.

arrays: Mapped[list[CalcArray]]

atoms_id: Mapped[int]

drop_array(name: str) → None[source]

Removes an array of calculation results from the Calculation object.

This method allows for the removal of specific arrays of results, useful for correcting or updating calculation data.

Parameters:: name (str) – The name of the array to remove (e.g., “forces”, “stress”).
Raises:: ValueError – If the specified array name does not exist within the Calculation object.

energy: Mapped[float]

fmax: Mapped[float]

free_energy: Mapped[float]

classmethod from_calc(calc: Calculator) → Calculation[source]

Constructs a Calculation instance from an ASE Calculator object, extracting relevant calculation results and arrays.

Parameters:: calc (AseCalculator) – The ASE Calculator object from which to extract calculation results.
Returns:: An instance of Calculation populated with results from the ASE Calculator.
Return type:: Calculation

This method automatically extracts properties like energy, free energy, and magnetic moment as floats, and results like forces, stress, and magnetic moments as arrays, storing them for later reconstruction.

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

Retrieves calculation results stored in the Calculation object, formatted for re-creation of an ASE Calculator object.

This method facilitates the reconstruction of an ASE Calculator object from stored calculation results.

Returns:

A dictionary of calculation properties and results,: ready to be passed to an ASE Calculator constructor.

Return type:

Mapping[str, float | np.ndarray]

id: Mapped[int]

magmom: Mapped[float]

class asedb.Element(**kwargs)[source]

Bases: Base

atoms_id: Mapped[int]

count: Mapped[int]

id: Mapped[int]

symbol: Mapped[str]

class asedb.Trajectory(**kwargs)[source]

Bases: Base

add_atoms(atoms: Atoms) → AtomsModel[source]: 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][source]

asedb.initialize_engine(engine: Engine)[source]

asedb.make_sqlite_engine(filename: str, initialize: bool = False) → Engine[source]: Helper function to create a sqlite Engine, that disables the usage of the default schema.