Structure Search | Atomic Tessellator

Atomic Tessellator provides access to structure databases using ASE database query syntax.

For more information on ASE database query syntax, see the ASE Database Documentation.

1. ASE Database Search

Search structures using ASE (Atomic Simulation Environment) database query syntax.

structure_search.py

from atomict.structure.search import search_structures

# Basic usage pattern:
result = search_structures(query, limit=10)

# Query examples:
queries = [
    "formula=Cu2O",                  # Exact formula
    "Cu,O",                          # Elements present  
    "spacegroup=225",                # Space group
    "natoms>10,natoms<50",           # Atom count range
    "energy<-3.0",                   # Energy threshold
    "magmom_per_atom>0.1",           # Magnetic moments
    "formula=Cu2O,spacegroup=225"    # Combined criteria
]

# Use any query:
result = search_structures("formula=Cu2O", limit=5)

# ...

1.1 Query Syntax Reference

All queries are passed as strings to the search_structures() function:

Query Type	Syntax	Example	Description
Formula	`formula=FORMULA`	`"formula=Cu2O"`	Exact chemical formula
Elements	`ELEMENT1,ELEMENT2`	`"Cu,O"`	Structures containing these elements
Space Group	`spacegroup=NUMBER`	`"spacegroup=225"`	Crystal space group number
Atom Count	`natoms>MIN,natoms<MAX`	`"natoms>10,natoms<50"`	Number of atoms range
Energy	`energy<VALUE`	`"energy<-3.0"`	Energy per atom threshold
Magnetic	`magmom_per_atom>VALUE`	`"magmom_per_atom>0.1"`	Magnetic moment per atom
Combined	`criteria1,criteria2`	`"formula=Cu2O,spacegroup=225"`	Multiple criteria (comma-separated)

1.2 Response Format

The result object contains an array of matches, each containing the ASE Atoms object data:

structure_search_result.json

{
    "status": "OK",
    # List of found structures
    "results": [
        {
            # Structure data (ASE format)
            "1": {
                # 3×3 unit cell lattice vectors
                "cell": {
                    "array": {
                        # Serialized numpy array
                        "__ndarray__": [[3, 3], "float64", [...]],
                        "__ase_objtype__": "cell"
                    }
                },
                # Atomic numbers (29=Cu, 8=O)
                "numbers": {"__ndarray__": [[3], "int64", [29, 29, 8]]},
                # 3D atomic coordinates
                "positions": {"__ndarray__": [[3, 3], "float64", [...]]},
                # Periodic boundary conditions
                "pbc": {"__ndarray__": [[3], "bool", [True, True, True]]},
                # Database ID for referencing in other API calls
                "unique_id": "47b61ecde291020fb031f45961806e12"
            },
            "ids": [1],
            "nextid": 2,
            # Chemical formula
            "chemical_formula": "Cu2O"
        }
    ]
}

2. Saving Results as CIF Files

To use run subsequent simulations with the result, you can convert it into a .cif file through ASE.

structure_search.py

# ...

import numpy as np
from ase.io import write
from ase import Atoms


def save_structure_as_cif(struct, filename):
    # extract atoms and positions
    numbers = np.array(struct['numbers']['__ndarray__'][2])
    positions_data = struct['positions']['__ndarray__'][2]
    n_atoms = len(numbers)
    positions = np.array(positions_data).reshape(n_atoms, 3)
    
    # build the cell
    cell_info = struct['cell']['array']['__ndarray__']
    cell_data = cell_info[2]
    cell = np.array(cell_data).reshape(3, 3)

    # extract periodic boundary conditions
    pbc = struct['pbc']['__ndarray__'][2]
    
    # create and save
    atoms = Atoms(numbers=numbers, positions=positions, cell=cell, pbc=pbc)
    write(filename, atoms, format='cif')


for i, structure in enumerate(result['results']):
    filename = f"structure_{i}_{structure['chemical_formula']}.cif"
    save_structure_as_cif(structure['1'], filename)

3. Chaining with Structure Operations

You can chain structure search results with subsequent structure operations like supercells and structure optimization. This workflow allows you to discover structures and immediately prepare them for calculations.