Database

class atomman.library.Database(local: bool | None = None, remote: bool | None = None, localpath: str | None = None, local_name: str | None = None, local_database: Database | None = None, local_style: str | None = None, local_host: str | None = None, local_terms: dict | None = None, remote_name: str | None = None, remote_database: Database | None = None, remote_style: str | None = None, remote_host: str | None = None, remote_terms: dict | None = None, kim_models: str | list | None = None, kim_api_directory: Path | None = None, kim_models_file: Path | None = None)

Bases: Database

Child of potentials.Database extended for interacting with structure and defect reference records.

download_all(status: str | list | None = None, downloadfiles: bool = True, overwrite: bool = False, verbose: bool = False)

Downloads potential and structure-related records from the remote location to the local location.

Parameters:

• status (str, list or None, optional) – Only potential_LAMMPS records with the given status(es) will be downloaded. Allowed values are ‘active’ , ‘superseded’, and ‘retracted’. If None (default) is given, then all potentials will be downloaded.

• downloadfiles (bool, optional) – If True, the parameter files associated with the potential_LAMMPS record will also be downloaded.

• overwrite (bool, optional) – Flag indicating if any existing local records with names matching remote records are updated (True) or left unchanged (False). Default value is False.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

download_crystal_prototypes(name: str | list | None = None, id: str | list | None = None, key: str | list | None = None, commonname: str | list | None = None, prototype: str | list | None = None, pearson: str | list | None = None, strukturbericht: str | list | None = None, sg_number: int | list | None = None, sg_hm: str | list | None = None, sg_schoenflies: str | list | None = None, crystalfamily: str | list | None = None, natypes: int | list | None = None, overwrite: bool = False, return_records: bool = False, verbose: bool = False) → ndarray | None

Downloads crystal prototypes from the remote to the local.

Parameters:

• name (str or list, optional) – The record name(s) to parse by. For crystal prototype records, the names should correspond to the id.

• id (str or list, optional) – Prototype ID(s) to search for. These are unique identifiers for each prototype based on comm.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• name – Common name(s) to limit the search by.

• prototype (str or list, optional) – Prototype identifying composition(s) to limit the search by.

• pearson (str or list, optional) – The Pearson symbol(s) to limit the search by.

• strukturbericht (str or list, optional) – The strukturbericht identifier(s) to limit the search by.

• sg_number (int or list, optional) – The space group number(s) to limit the search by.

• sg_hm (str or list, optional) – The space group Hermann-Maguin identifier(s) to limit the search by.

• sg_schoenflies (str or list, optional) – The space group Schoenflies identifier(s) to limit the search by.

• crystalfamily (str or list, optional) – The crystal system families to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• overwrite (bool, optional) – Flag indicating if any existing local records with names matching remote records are updated (True) or left unchanged (False). Default value is False.

• return_records (bool, optional) – If True, the retrieved record objects are also returned. Default value is False.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

The matching records - returned if return_records=True

Return type:

numpy.ndarray

download_reference_crystals(name: str | list | None = None, key: str | list | None = None, id: str | list | None = None, sourcename: str | list | None = None, sourcelink: str | list | None = None, crystalfamily: str | list | None = None, composition: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, overwrite: bool = False, return_records: bool = False, verbose: bool = False) → ndarray | None

Download reference records from the remote and save to localpath.

Parameters:

• name (str or list, optional) – The record name(s) to parse by. For reference crystal records, the names should correspond to the id.

• id (str or list, optional) – The record id(s) to parse by. For reference crystal records, the id are letters identifying the source database “mp-”, “mvc-”, or “oqmd-“, followed by the source database’s identification number.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• sourcename (str or list, optional) – The full name of source DFT databases to limit the search by. “Materials Project” or “Open Quantum Materials Database”.

• sourcelink (str or list, optional) – The web link of the source DFT databases to limit the search by.

• crystalfamily (str or list, optional) – The crystal system families to limit the search by.

• composition (str or list, optional) – The reduced compositions of the structures to limit the search by. Element symbols are sorted alphabetically.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natoms (int or list, optional) – The number of unique atoms in the crystal’s unit cell to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• overwrite (bool, optional) – Flag indicating if any existing local records with names matching remote records are updated (True) or left unchanged (False). Default value is False.

• return_records (bool, optional) – If True, the retrieved record objects are also returned. Default value is False.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

The matching records - returned if return_records=True

Return type:

numpy.ndarray

download_relaxed_crystals(name: str | list | None = None, key: str | list | None = None, method: str | list | None = None, standing: str | list | None = None, family: str | list | None = None, parent_key: str | list | None = None, potential_LAMMPS_id: str | list | None = None, potential_LAMMPS_key: str | list | None = None, potential_id: str | list | None = None, potential_key: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, overwrite: bool = False, return_records: bool = False, verbose: bool = False) → ndarray | None

Download citation records from the remote and save to localpath.

Parameters:

• name (str or list) – The record name(s) to parse by. For relaxed crystal records, the names should correspond to the key.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• method (str or list or None, optional) – The relaxation method used. Allowed values are dynamic, static and box.

• standing (str or list or None, optional) – “good” records are the unique crystals found with the most rigorous relaxation, and with known prototypes over DFT structures. “bad” are records filtered out, usually for being duplicates.

• family (str or atomman.library.CrystalPrototype or list, optional) – The crystal family associated with the relaxed crystal - either crystal prototype name or MP/OQMD database entry name.

• parent_key (str or list, optional) – The UUID4 key(s) assigned to the calculation that the record is based on.

• potential_LAMMPS_id (str or list, optional) – The id for a LAMMPS implemented potential to limit the search by.

• potential_LAMMPS_key (str or list, optional) – The UUID4 for a LAMMPS implemented potential to limit the search by.

• potential_id (str or list, optional) – The id for a potential to limit the search by.

• potential_key (str or list, optional) – The UUID4 for a potential to limit the search by.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natypes (int or list, optional) – The number of unique element model symbols in the crystal to limit the search by.

• natoms (int or list, optional) – The number of unique atoms in the crystal’s unit cell to limit the search by.

• overwrite (bool, optional) – Flag indicating if any existing local records with names matching remote records are updated (True) or left unchanged (False). Default value is False.

• return_records (bool, optional) – If True, the retrieved record objects are also returned. Default value is False.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

The matching records - returned if return_records=True

Return type:

numpy.ndarray

fetch_mp_crystal(id: str, api_key: str | None = None) → Record

Retrieves a single reference crystal from Materials Project based on id.

Parameters:

• id (str) – The structure id of the crystal to retrieve.

• api_key (str, optional) – The user’s Materials Project API key. If not given, will use “MAPI_KEY” environment variable.

Returns:

The retrieved reference crystal.

Return type:

Record

fetch_mp_crystals(id: str, api_key: str | None = None) → list

Retrieves reference crystals from Materials Project based on id(s).

Parameters:

• id (str or list) – The structure id(s) of the crystals to retrieve.

• api_key (str, optional) – The user’s Materials Project API key or path to a file containing the key. If not given, will use the “MAPI_KEY” environment variable.

Returns:

All matching reference crystals retrieved.

Return type:

list

fetch_oqmd_crystal(id: str) → Record

Retrieves a single reference crystal from OQMD based on id.

Parameters:

id (str) – The OQMD entry number with “oqmd-” prefix.

Returns:

The retrieved reference crystal.

Return type:

Record

fetch_reference_crystal(id: str, api_key: str | None = None, local: bool | None = None, remote: bool | None = None, refresh_cache: bool = False, verbose: bool = False) → Record

Retrieves a single reference crystal. First, the database is checked for matches with the DOI, then with the record name. If no matches are found in the database, then the corresponding crystal structure is downloaded from the source database.

Parameters:

• id (str) – The reference crystal’s unique id. Combines a database tag “mp-” or “oqmd-” and the DFT database’s entry id.

• api_key (str, optional) – The user’s Materials Project API key or path to a file containing the key. Only needed for fetching structures from Materials Project and if the key is not set to the “MAPI_KEY” environment variable.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

The matching reference crystal record.

Return type:

yabadaba.record.Record

get_crystal_prototype(name: str | list | None = None, id: str | list | None = None, key: str | list | None = None, commonname: str | list | None = None, prototype: str | list | None = None, pearson: str | list | None = None, strukturbericht: str | list | None = None, sg_number: int | list | None = None, sg_hm: str | list | None = None, sg_schoenflies: str | list | None = None, crystalfamily: str | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, prompt: bool = True, refresh_cache: bool = False, verbose: bool = False) → Record

Gets exactly one matching crystal prototype from the database.

Parameters:

• name (str or list, optional) – The record name(s) to parse by. For crystal prototype records, the names should correspond to the id.

• id (str or list, optional) – Prototype ID(s) to search for. These are unique identifiers for each prototype based on comm.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• name – Common name(s) to limit the search by.

• prototype (str or list, optional) – Prototype identifying composition(s) to limit the search by.

• pearson (str or list, optional) – The Pearson symbol(s) to limit the search by.

• strukturbericht (str or list, optional) – The strukturbericht identifier(s) to limit the search by.

• sg_number (int or list, optional) – The space group number(s) to limit the search by.

• sg_hm (str or list, optional) – The space group Hermann-Maguin identifier(s) to limit the search by.

• sg_schoenflies (str or list, optional) – The space group Schoenflies identifier(s) to limit the search by.

• crystalfamily (str or list, optional) – The crystal system family to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• prompt (bool) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

The matching record object

Return type:

yabadaba.record.Record

get_crystal_prototypes(name: str | list | None = None, id: str | list | None = None, key: str | list | None = None, commonname: str | list | None = None, prototype: str | list | None = None, pearson: str | list | None = None, strukturbericht: str | list | None = None, sg_number: int | list | None = None, sg_hm: str | list | None = None, sg_schoenflies: str | list | None = None, crystalfamily: str | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, refresh_cache: bool = False, return_df: bool = False, verbose: bool = False) → ndarray | Tuple[ndarray, DataFrame]

Gets all matching crystal prototypes from the database.

Parameters:

• name (str or list) – The record name(s) to parse by. For crystal prototype records, the names should correspond to the id.

• id (str or list, optional) – Prototype ID(s) to search for. These are unique identifiers for each prototype based on comm.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• commonname (str or list, optional) – Common name(s) to limit the search by.

• prototype (str or list, optional) – Prototype identifying composition(s) to limit the search by.

• pearson (str or list, optional) – The Pearson symbol(s) to limit the search by.

• strukturbericht (str or list, optional) – The strukturbericht identifier(s) to limit the search by.

• sg_number (int or list, optional) – The space group number(s) to limit the search by.

• sg_hm (str or list, optional) – The space group Hermann-Maguin identifier(s) to limit the search by.

• sg_schoenflies (str or list, optional) – The space group Schoenflies identifier(s) to limit the search by.

• crystalfamily (str, optional) – The crystal system family to limit the search by.

• natypes (int, optional) – The number(s) of unique atom types to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• return_df (bool, optional) – If True, then the corresponding pandas.Dataframe of metadata will also be returned.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

• numpy.ndarray – The matching record objects

• pandas.DataFrame – A table of the associated record metadata, returned if return_df = True.

get_reference_crystal(name: str | list | None = None, key: str | list | None = None, id: str | list | None = None, sourcename: str | list | None = None, sourcelink: str | list | None = None, crystalfamily: str | list | None = None, composition: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, prompt: bool = True, refresh_cache: bool = False, verbose: bool = False) → Record

Gets exactly one matching reference crystal from the database.

Parameters:

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• name (str or list, optional) – The record name(s) to parse by. For reference crystal records, the names should correspond to the id.

• id (str or list, optional) – The record id(s) to parse by. For reference crystal records, the id are letters identifying the source database “mp-”, “mvc-”, or “oqmd-“, followed by the source database’s identification number.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• sourcename (str or list, optional) – The full name of source DFT databases to limit the search by. “Materials Project” or “Open Quantum Materials Database”.

• sourcelink (str or list, optional) – The web link of the source DFT databases to limit the search by.

• crystalfamily (str or list, optional) – The crystal system families to limit the search by.

• composition (str or list, optional) – The reduced compositions of the structures to limit the search by. Element symbols are sorted alphabetically.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natoms (int or list, optional) – The number of unique atoms in the crystal’s unit cell to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• prompt (bool) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

The matching record object

Return type:

yabadaba.record.Record

get_reference_crystals(name: str | list | None = None, key: str | list | None = None, id: str | list | None = None, sourcename: str | list | None = None, sourcelink: str | list | None = None, crystalfamily: str | list | None = None, composition: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, refresh_cache: bool = False, return_df: bool = False, verbose: bool = False) → ndarray | Tuple[ndarray, DataFrame]

Gets all matching reference crystals from the database.

Parameters:

• name (str or list, optional) – The record name(s) to parse by. For reference crystal records, the names should correspond to the id.

• id (str or list, optional) – The record id(s) to parse by. For reference crystal records, the id are letters identifying the source database “mp-”, “mvc-”, or “oqmd-“, followed by the source database’s identification number.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• sourcename (str or list, optional) – The full name of source DFT databases to limit the search by. “Materials Project” or “Open Quantum Materials Database”.

• sourcelink (str or list, optional) – The web link of the source DFT databases to limit the search by.

• crystalfamily (str or list, optional) – The crystal system families to limit the search by.

• composition (str or list, optional) – The reduced compositions of the structures to limit the search by. Element symbols are sorted alphabetically.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natoms (int or list, optional) – The number of unique atoms in the crystal’s unit cell to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• return_df (bool, optional) – If True, then the corresponding pandas.Dataframe of metadata will also be returned.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

• numpy.ndarray – The matching record objects

• pandas.DataFrame – A table of the associated record metadata, returned if return_df = True.

get_relaxed_crystal(name: str | list | None = None, key: str | list | None = None, method: str | list | None = None, standing: str | list | None = None, family: str | list | None = None, parent_key: str | list | None = None, potential_LAMMPS_id: str | list | None = None, potential_LAMMPS_key: str | list | None = None, potential_id: str | list | None = None, potential_key: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, prompt: bool = True, refresh_cache: bool = False, verbose: bool = False) → Record

Gets exactly one matching relaxed crystal from the database.

Parameters:

• name (str or list) – The record name(s) to parse by. For relaxed crystal records, the names should correspond to the key.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• method (str or list or None, optional) – The relaxation method used. Allowed values are dynamic, static and box.

• standing (str or list or None, optional) – “good” records are the unique crystals found with the most rigorous relaxation, and with known prototypes over DFT structures. “bad” are records filtered out, usually for being duplicates.

• family (str or atomman.library.CrystalPrototype or list, optional) – The crystal family associated with the relaxed crystal - either crystal prototype name or MP/OQMD database entry name.

• parent_key (str or list, optional) – The UUID4 key(s) assigned to the calculation that the record is based on.

• potential_LAMMPS_id (str or list, optional) – The id for a LAMMPS implemented potential to limit the search by.

• potential_LAMMPS_key (str or list, optional) – The UUID4 for a LAMMPS implemented potential to limit the search by.

• potential_id (str or list, optional) – The id for a potential to limit the search by.

• potential_key (str or list, optional) – The UUID4 for a potential to limit the search by.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natypes (int or list, optional) – The number of unique element model symbols in the crystal to limit the search by.

• natypes – The number(s) of unique atom types to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• prompt (bool) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

The matching record object

Return type:

yabadaba.record.Record

get_relaxed_crystals(name: str | list | None = None, key: str | list | None = None, method: str | list | None = None, standing: str | list | None = None, family: str | list | None = None, parent_key: str | list | None = None, potential_LAMMPS_id: str | list | None = None, potential_LAMMPS_key: str | list | None = None, potential_id: str | list | None = None, potential_key: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, refresh_cache: bool = False, return_df: bool = False, verbose: bool = False) → ndarray | Tuple[ndarray, DataFrame]

Gets all matching relaxed crystals from the database.

Parameters:

• name (str or list) – The record name(s) to parse by. For relaxed crystal records, the names should correspond to the key.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• method (str or list or None, optional) – The relaxation method used. Allowed values are dynamic, static and box.

• standing (str or list or None, optional) – “good” records are the unique crystals found with the most rigorous relaxation, and with known prototypes over DFT structures. “bad” are records filtered out, usually for being duplicates.

• family (str or atomman.library.CrystalPrototype or list, optional) – The crystal family associated with the relaxed crystal - either crystal prototype name or MP/OQMD database entry name.

• parent_key (str or list, optional) – The UUID4 key(s) assigned to the calculation that the record is based on.

• potential_LAMMPS_id (str or list, optional) – The id for a LAMMPS implemented potential to limit the search by.

• potential_LAMMPS_key (str or list, optional) – The UUID4 for a LAMMPS implemented potential to limit the search by.

• potential_id (str or list, optional) – The id for a potential to limit the search by.

• potential_key (str or list, optional) – The UUID4 for a potential to limit the search by.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• natoms (int or list, optional) – The number of unique atoms in the crystal’s unit cell to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• return_df (bool, optional) – If True, then the corresponding pandas.Dataframe of metadata will also be returned.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns:

• numpy.ndarray – The matching record objects

• pandas.DataFrame – A table of the associated record metadata, returned if return_df = True.

retrieve_crystal_prototype(name: str | list | None = None, dest: Path | None = None, id: str | list | None = None, key: str | list | None = None, commonname: str | list | None = None, prototype: str | list | None = None, pearson: str | list | None = None, strukturbericht: str | list | None = None, sg_number: int | list | None = None, sg_hm: str | list | None = None, sg_schoenflies: str | list | None = None, crystalfamily: str | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, prompt: bool = True, format: str = 'json', indent: int = 4, refresh_cache: bool = False, verbose: bool = False)

Gets a single matching crystal prototype from the database and saves it to a file based on the record’s name.

Parameters:

• name (str or list, optional) – The name(s) of records to limit the search by.

• dest (path, optional) – The parent directory where the record will be saved to. If not given, will use the current working directory.

• id (str or list, optional) – Prototype ID(s) to search for. These are unique identifiers for each prototype based on comm.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• name – Common name(s) to limit the search by.

• prototype (str or list, optional) – Prototype identifying composition(s) to limit the search by.

• pearson (str or list, optional) – The Pearson symbol(s) to limit the search by.

• strukturbericht (str or list, optional) – The strukturbericht identifier(s) to limit the search by.

• sg_number (int or list, optional) – The space group number(s) to limit the search by.

• sg_hm (str or list, optional) – The space group Hermann-Maguin identifier(s) to limit the search by.

• sg_schoenflies (str or list, optional) – The space group Schoenflies identifier(s) to limit the search by.

• crystalfamily (str or list, optional) – The crystal system family to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• prompt (bool, optional) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

• format (str, optional) – The file format to save the record in: ‘json’ or ‘xml’. Default is ‘json’.

• indent (int, optional) – The number of space indentation spacings to use in the saved record for the different tiered levels. Default is 4. Giving None will create a compact record.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Raises:

• ValueError – If local or remote is set to True when the corresponding database interaction has not been set.

• ValueError – If multiple or no matching records are discovered.

retrieve_reference_crystal(name: str | list | None = None, dest: Path | None = None, key: str | list | None = None, id: str | list | None = None, sourcename: str | list | None = None, sourcelink: str | list | None = None, crystalfamily: str | list | None = None, composition: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, prompt: bool = True, format: str = 'json', indent: int = 4, refresh_cache: bool = False, verbose: bool = False)

Gets a single matching relaxed crystal from the database and saves it to a file based on the record’s name.

Parameters:

• name (str or list, optional) – The name(s) of records to limit the search by.

• dest (path, optional) – The parent directory where the record will be saved to. If not given, will use the current working directory.

• id (str or list, optional) – The record id(s) to parse by. For reference crystal records, the id are letters identifying the source database “mp-”, “mvc-”, or “oqmd-“, followed by the source database’s identification number.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• sourcename (str or list, optional) – The full name of source DFT databases to limit the search by. “Materials Project” or “Open Quantum Materials Database”.

• sourcelink (str or list, optional) – The web link of the source DFT databases to limit the search by.

• crystalfamily (str or list, optional) – The crystal system families to limit the search by.

• composition (str or list, optional) – The reduced compositions of the structures to limit the search by. Element symbols are sorted alphabetically.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natoms (int or list, optional) – The number of unique atoms in the crystal’s unit cell to limit the search by.

• natypes (int or list, optional) – The number(s) of unique atom types to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• prompt (bool, optional) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

• format (str, optional) – The file format to save the record in: ‘json’ or ‘xml’. Default is ‘json’.

• indent (int, optional) – The number of space indentation spacings to use in the saved record for the different tiered levels. Default is 4. Giving None will create a compact record.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Raises:

• ValueError – If local or remote is set to True when the corresponding database interaction has not been set.

• ValueError – If multiple or no matching records are discovered.

retrieve_relaxed_crystal(name: str | list | None = None, dest: Path | None = None, key: str | list | None = None, method: str | list | None = None, standing: str | list | None = None, family: str | list | None = None, parent_key: str | list | None = None, potential_LAMMPS_id: str | list | None = None, potential_LAMMPS_key: str | list | None = None, potential_id: str | list | None = None, potential_key: str | list | None = None, symbols: str | list | None = None, natoms: int | list | None = None, natypes: int | list | None = None, local: bool | None = None, remote: bool | None = None, prompt: bool = True, format: str = 'json', indent: int = 4, refresh_cache: bool = False, verbose: bool = False)

Gets a single matching relaxed crystal from the database and saves it to a file based on the record’s name.

Parameters:

• name (str or list, optional) – The name(s) of records to limit the search by.

• dest (path, optional) – The parent directory where the record will be saved to. If not given, will use the current working directory.

• key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

• method (str or list or None, optional) – The relaxation method used. Allowed values are dynamic, static and box.

• standing (str or list or None, optional) – “good” records are the unique crystals found with the most rigorous relaxation, and with known prototypes over DFT structures. “bad” are records filtered out, usually for being duplicates.

• family (str or atomman.library.CrystalPrototype or list, optional) – The crystal family associated with the relaxed crystal - either crystal prototype name or MP/OQMD database entry name.

• parent_key (str or list, optional) – The UUID4 key(s) assigned to the calculation that the record is based on.

• potential_LAMMPS_id (str or list, optional) – The id for a LAMMPS implemented potential to limit the search by.

• potential_LAMMPS_key (str or list, optional) – The UUID4 for a LAMMPS implemented potential to limit the search by.

• potential_id (str or list, optional) – The id for a potential to limit the search by.

• potential_key (str or list, optional) – The UUID4 for a potential to limit the search by.

• symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

• natypes (int or list, optional) – The number of unique element model symbols in the crystal to limit the search by.

• natypes – The number(s) of unique atom types to limit the search by.

• local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

• remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

• prompt (bool, optional) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

• format (str, optional) – The file format to save the record in: ‘json’ or ‘xml’. Default is ‘json’.

• indent (int, optional) – The number of space indentation spacings to use in the saved record for the different tiered levels. Default is 4. Giving None will create a compact record.

• refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

• verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Raises:

• ValueError – If local or remote is set to True when the corresponding database interaction has not been set.

• ValueError – If multiple or no matching records are discovered.