Database

Database#

All data managed by DuckAtoms is inserted to or retrieved from a DuckDB database, which is contained in a single file. As DuckDB is an in-process database, only one process can access it for read/write operations at a time. In principle multiple processes can read from the database concurrently if they are all read-only, but this is not utilized in the DuckAtoms package. Inside such a database the data is structured into two tables.

Structures table#

The structures table always contains columns for:

  • id: Unique structure identifier

  • cell: Flattened cell vectors (3,3) -> (9,)

  • pbc: Periodic boundary conditions and each structure aka ase.Atoms object is saved in one row of the structures table. The id is automatically assigned and not changed, even if atoms are removed. You can add additional properties aka columns to the structures table.

Atoms table#

The second table is made up with a row for each atom contained in each structure you inserted. It always contains columns for:

  • id: Unique atom identifier

  • structure_id: Reference to the structures table

  • ase_atoms_id: Atom index from the original ASE Atoms object

  • number: Atomic number

  • x, y, z: Atomic coordinates Again the id is automatically assigned and not changed after creation and you can add additional properties, such as coordination numbers, local atomic environment descriptors etc. Those are then stored in additional columns of the atoms table.

In the next section, we will explain how you can set up a database and add custom columns to the structures and atoms tables.

Contents