{"id":9494,"library":"ase-db-backends","title":"ASE-DB Backends","description":"ASE-DB Backends (version 0.11.0) provides alternative database backends for ASE, focusing on more performant storage of large datasets than the default SQLite. It offers MongoDB, HDF5, and ZODB/JSON backends, allowing users to choose storage solutions optimized for their specific needs, such as distributed access or very large datasets. The library maintains an active development pace with releases tied to features and bug fixes, typically requiring recent ASE versions.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/ComputationalMaterialsScience/ase-db-backends","tags":["ase","database","materials science","computational chemistry","hdf5","mongodb","zodb"],"install":[{"cmd":"pip install ase-db-backends","lang":"bash","label":"Install core library"},{"cmd":"pip install ase-db-backends[hdf5]","lang":"bash","label":"Install with HDF5 support"},{"cmd":"pip install ase-db-backends[mongo]","lang":"bash","label":"Install with MongoDB support"}],"dependencies":[{"reason":"Core functionality relies on ASE Atoms objects and utilities.","package":"ase","optional":false},{"reason":"Required for the HDF5 backend.","package":"h5py","optional":true},{"reason":"Required for the MongoDB backend.","package":"pymongo","optional":true},{"reason":"Required for the ZODB/JSON backend.","package":"ZODB","optional":true}],"imports":[{"note":"HDF5Database is part of `ase-db-backends`, not `ase.db`.","wrong":"from ase.db import HDF5Database","symbol":"HDF5Database","correct":"from ase_db_backends.hdf5 import HDF5Database"},{"note":"MongoDatabase is part of `ase-db-backends`, not `ase.db`.","wrong":"from ase.db import MongoDatabase","symbol":"MongoDatabase","correct":"from ase_db_backends.mongo import MongoDatabase"},{"symbol":"JSONDatabase","correct":"from ase_db_backends.json_db import JSONDatabase"}],"quickstart":{"code":"import os\nfrom ase.atoms import Atoms\nfrom ase.build import molecule\nfrom ase_db_backends.hdf5 import HDF5Database\n\n# Clean up previous run for repeatability\nif os.path.exists('test_ase_backend.hdf5'):\n    os.remove('test_ase_backend.hdf5')\n\n# 1. Create an Atoms object\nh2o = molecule('H2O')\nh2o.info['user_note'] = 'A test molecule'\n\n# 2. Instantiate the HDF5 backend\n# Replace 'test_ase_backend.hdf5' with your desired filename\ndb = HDF5Database('test_ase_backend.hdf5')\n\n# 3. Write the Atoms object to the database\n# You can also add key-value pairs for searching\nrow_id = db.write(h2o,\n                  key_value_pairs={'formula': 'H2O', 'source': 'ase_example'},\n                  data={'energy_dft': -10.0}) # Arbitrary data can be stored\n\nprint(f\"Stored H2O molecule with row_id: {row_id}\")\n\n# 4. Read back from the database (example for iterating)\n# Note: Iterating returns (id, atoms, kvp, data)\nprint(\"\\nRetrieving stored data:\")\nfor r_id, atoms_read, kvp_read, data_read in db.select():\n    print(f\"  Read row_id: {r_id}\")\n    print(f\"  Formula: {atoms_read.get_chemical_formula()}\")\n    print(f\"  Label from KVP: {kvp_read.get('formula')}\")\n    print(f\"  Energy from data: {data_read.get('energy_dft')}\")\n\n# Clean up\nif os.path.exists('test_ase_backend.hdf5'):\n    os.remove('test_ase_backend.hdf5')","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your ASE installation is `ase>=3.23` by running `pip install --upgrade ase`.","message":"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.","severity":"breaking","affected_versions":"<0.11.0 (implicitly, by `ase` dependency)"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install ASE: `pip install ase`","cause":"The core ASE library is not installed.","error":"ModuleNotFoundError: No module named 'ase'"},{"fix":"Install `ase-db-backends` with the HDF5 extra: `pip install ase-db-backends[hdf5]`","cause":"Attempting to use `HDF5Database` without installing `h5py`, which is an optional dependency.","error":"ModuleNotFoundError: No module named 'h5py'"},{"fix":"Instantiate the backend class directly: `from ase_db_backends.hdf5 import HDF5Database; db = HDF5Database('my_db.hdf5')`","cause":"Incorrectly trying to pass `ase-db-backends` specific arguments to the standard `ase.db.connect` function.","error":"TypeError: ase.db.connect() got an unexpected keyword argument 'filename'"}]}