ASE-DB Backends

Common errors

• ModuleNotFoundError: No module named 'ase'

  cause The core ASE library is not installed.
  fix Install ASE: `pip install ase`

• ModuleNotFoundError: No module named 'h5py'

  cause Attempting to use `HDF5Database` without installing `h5py`, which is an optional dependency.
  fix Install `ase-db-backends` with the HDF5 extra: `pip install ase-db-backends[hdf5]`

• TypeError: ase.db.connect() got an unexpected keyword argument 'filename'

  cause Incorrectly trying to pass `ase-db-backends` specific arguments to the standard `ase.db.connect` function.
  fix Instantiate the backend class directly: `from ase_db_backends.hdf5 import HDF5Database; db = HDF5Database('my_db.hdf5')`

Warnings

• breaking The `ase-db-backends` library requires `ase` version 3.23 or newer. Using older `ase` versions can lead to `AttributeError` or `TypeError` due to API incompatibilities.
  Fix: Ensure your ASE installation is `ase>=3.23` by running `pip install --upgrade ase`.
• gotcha Unlike `ase.db.connect`, you must explicitly instantiate the backend class (e.g., `HDF5Database`) and use its methods. The `ase.db.connect` function does not directly support backend-specific configuration arguments like `filename` or `mongo_url` from this library.
  Fix: Do not use `ase.db.connect(filename='my_db.hdf5')`. Instead, use `from ase_db_backends.hdf5 import HDF5Database; db = HDF5Database('my_db.hdf5')`.
• gotcha Each backend (HDF5, MongoDB, JSON) requires specific extra dependencies. If you install `ase-db-backends` without extras, you might encounter `ModuleNotFoundError` when trying to use a backend.
  Fix: Install the library with the necessary extras, e.g., `pip install ase-db-backends[hdf5]` for HDF5 support, or `pip install ase-db-backends[all]` for all backends.

Install

• pip install ase-db-backends Install core library
• pip install ase-db-backends[hdf5] Install with HDF5 support
• pip install ase-db-backends[mongo] Install with MongoDB support

Imports

• HDF5Database
  wrong:

  from ase.db import HDF5Database

  correct:

  from ase_db_backends.hdf5 import HDF5Database

  HDF5Database is part of `ase-db-backends`, not `ase.db`.
• MongoDatabase
  wrong:

  from ase.db import MongoDatabase

  correct:

  from ase_db_backends.mongo import MongoDatabase

  MongoDatabase is part of `ase-db-backends`, not `ase.db`.
• JSONDatabase

  from ase_db_backends.json_db import JSONDatabase

Quickstart

This quickstart demonstrates how to initialize an HDF5 database backend, store an `ase.Atoms` object with key-value pairs and additional data, and then retrieve it. This pattern is similar for other backends like MongoDB or JSON/ZODB.

import os
from ase.atoms import Atoms
from ase.build import molecule
from ase_db_backends.hdf5 import HDF5Database

# Clean up previous run for repeatability
if os.path.exists('test_ase_backend.hdf5'):
    os.remove('test_ase_backend.hdf5')

# 1. Create an Atoms object
h2o = molecule('H2O')
h2o.info['user_note'] = 'A test molecule'

# 2. Instantiate the HDF5 backend
# Replace 'test_ase_backend.hdf5' with your desired filename
db = HDF5Database('test_ase_backend.hdf5')

# 3. Write the Atoms object to the database
# You can also add key-value pairs for searching
row_id = db.write(h2o,
                  key_value_pairs={'formula': 'H2O', 'source': 'ase_example'},
                  data={'energy_dft': -10.0}) # Arbitrary data can be stored

print(f"Stored H2O molecule with row_id: {row_id}")

# 4. Read back from the database (example for iterating)
# Note: Iterating returns (id, atoms, kvp, data)
print("\nRetrieving stored data:")
for r_id, atoms_read, kvp_read, data_read in db.select():
    print(f"  Read row_id: {r_id}")
    print(f"  Formula: {atoms_read.get_chemical_formula()}")
    print(f"  Label from KVP: {kvp_read.get('formula')}")
    print(f"  Energy from data: {data_read.get('energy_dft')}")

# Clean up
if os.path.exists('test_ase_backend.hdf5'):
    os.remove('test_ase_backend.hdf5')