aim2dat.strct.structure_importer

Module that implements an interface to online databases and random crystal generation.

Module Contents

Classes

StructureImporter

Imports structures from online databases.
class aim2dat.strct.structure_importer.StructureImporter(structures: aim2dat.strct.StructureCollection = None, neglect_elemental_structures: bool = False)[source]

Bases: aim2dat.strct.mixin.ConstraintsMixin

Imports structures from online databases.

Overview

Properties

attribute_constraints

Attribute constraints.

chem_formula_constraints

Constraints on the chemical formula.

concentration_constraints

Elemental concentration constraints.

neglect_elemental_structures

Whether to neglect elemental phases.

structures

Return the internal StructureCollection object.
Methods

add_chem_formula_constraint(chem_formula, reduced_formula)

Add a chemical formula as a constraint.

append_from_mp_by_id(entry_id, api_key, property_data, structure_type)

Append structure via the database-id.

generate_random_crystals(formulas, excl_space_groups, tol_tuples, molecular, dimensions, bin_size, max_atoms, max_structures, max_structures_per_cs, max_structures_per_sg, volume_factor)

Generate random crystals using the PyXtaL library.

import_from_mofxdb(name, mofid, mofkey, vf_range, lcd_range, pld_range, sa_m2g_range, sa_m2cm3_range, adsorbates, database, store_uptake, query_limit)

Import structures from the MOFX database using the fetch function.

import_from_mp(formulas, api_key, compatible_only, conv_unit_cell, property_data, structure_type, use_openapi)

Import structures from the crystal database Materials Project using the pymatgen interface.

import_from_optimade(formulas, database_id, api_version, optimade_url, timeout)

Import crystal structures using the optimade-API.

import_from_oqmd(formulas, query_limit)

Import from the open quantum materials database.

remove_constraints()

Remove all constraints.

return_optimade_database_ids(api_version, optimade_url, timeout)

Return a list of all ids of online databases that provide a base-url.

set_attribute_constraint(attribute, min_value, max_value)

Set a constraint on attributes.

set_concentration_constraint(element, min_conc, max_conc)

Set a constraint on the concentration of an element in the structure.
property attribute_constraints

Attribute constraints.

property chem_formula_constraints

Constraints on the chemical formula.

property concentration_constraints

Elemental concentration constraints.

property neglect_elemental_structures

Whether to neglect elemental phases.

property structures : aim2dat.strct.StructureCollection

Return the internal StructureCollection object.

add_chem_formula_constraint(chem_formula, reduced_formula=True)

Add a chemical formula as a constraint.

The formula can be given as a string, dictionary or list of strings or dictionaries.

Parameters:

  • chem_formula (list, dict or str) – Chemical formula given as list, dict or str.

  • reduced_formula (bool (optional)) – If set to True the reduced formulas are compared. The default value is True.

append_from_mp_by_id(entry_id: str, api_key: str, property_data: list = None, structure_type: str = 'initial') → aim2dat.strct.Structure[source]

Append structure via the database-id.

Parameters:

  • entry_id (str) – Database id of the entry.

  • api_key (str) – API key for the database, can be obtained here: https://www.materialsproject.org/dashboard

  • property_data (list (optional)) – Extra data that is queried for each entry. The properties need to be passed as a list of strings (e.g. ['el_band_structure', 'el_dos'] to obtain the electronic band structure and the electronic density of states).

  • structure_type (str (optional)) – Materials project includes the initial and final (relaxed) stucture in the database. The intial or final structure can be queried by setting this attribute to initial or final, respectively.

generate_random_crystals(formulas: str | list[str], excl_space_groups: list = [], tol_tuples: list = None, molecular: bool = False, dimensions: int = 3, bin_size: float = 0.1, max_atoms: int = 30, max_structures: int = 10, max_structures_per_cs: int = 10, max_structures_per_sg: int = 5, volume_factor: float = 1.0) → aim2dat.strct.StructureCollection[source]

Generate random crystals using the PyXtaL library.

Parameters:

  • formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.

  • excl_space_groups (list (optional)) – Exclude one or more space groups.

  • tol_tuples (None or list) – Tolerance tuples used to create the tolerance matrix. The default value is None.

  • molecular (bool (optional)) – Whether to generate molecular crystals. The default value is False.

  • dimensions (int) – Dimension of the crystal, possible values range from zero to three. The default value is 3.

  • bin_size (float (optional)) – Size of bins that contain a certain number of structures. The default value is 0.1.

  • max_atoms (int (optional)) – Maximum number of atoms per structure. The default value is 30.

  • max_structures (int (optional)) – Maximum number of structures that are generated. The default value is 10.

  • max_structures_per_cs (int (optional)) – Maximum number of structures that are generated per crystal system. The default value is 10.

  • max_structures_per_sg (int (optional)) – Maximum number of structures that are generated per space group. The default value is 5.

  • volume_factor (float (optional)) – Volume factor used to generate the crystal. The default value is 1.0.

import_from_mofxdb(name: str = None, mofid: str = None, mofkey: str = None, vf_range: tuple = (None, None), lcd_range: tuple = (None, None), pld_range: tuple = (None, None), sa_m2g_range: tuple = (None, None), sa_m2cm3_range: tuple = (None, None), adsorbates: str | list[str] = None, database: str = None, store_uptake: bool = False, query_limit: int = 1000) → aim2dat.strct.StructureCollection[source]

Import structures from the MOFX database using the fetch function. If no parameters are set, the whole dabatabse will be imported.

Parameters:

  • name (str (optional)) – Name of the MOF in the corresponding DB.

  • mofid (str (optional)) – The unique ID for the MOF.

  • mofkey (str (optional)) – A specific key, often used for subcategorization or indexing.

  • vf_range (tuple (optional)) – Minimum and maximum values for the void fraction (VF).

  • lcd_range (tuple (optional)) – Minimum and maximum values for the largest cavity diameter (LCD).

  • pld_range (tuple (optional)) – Minimum and maximum values for the pore limiting diameter (PLD).

  • sa_m2g_range (tuple (optional)) – Minimum and maximum values for the surface area (SA) per gram (m^3/g^3).

  • sa_m2cm3_range (tuple (optional)) – Minimum and maximum values for the surface area (SA) in square meters (m^2/cm^3).

  • adsorbates (str or list of str (optional)) – The adsorbates included for heat and isotherm analysis. E.g. 'Hydrogen'. If not defined, all adsorbates studied are considered.

  • database (str (optional)) – The database from which MOF information is retrieved. E.g. 'CoREMOF 2019'.

  • store_uptake (bool (optional)) – If True, uptake data is stored in extras.

  • query_limit (int (optional)) – The maximum number of results to retrieve for the query.

import_from_mp(formulas: str | list[str], api_key: str, compatible_only: bool = True, conv_unit_cell: bool = False, property_data: list = [], structure_type: str = 'initial', use_openapi: bool = False) → aim2dat.strct.StructureCollection[source]

Import structures from the crystal database Materials Project using the pymatgen interface.

Parameters:

  • formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.

  • api_key (str) – API key for the database, can be obtained here: https://www.materialsproject.org/dashboard

  • compatible_only (bool (optional)) – Whether to only query compatible data. The default value is True.

  • conv_unit_cell (bool (optional)) – Query the conventional unit cell instead of the primitive unit cell. The default value is False.

  • property_data (list (optional)) – Extra data that is queried for each entry. The properties need to be passed as a list of strings (e.g. ['el_bandstructure', 'el_dos'] to obtain the electronic band structure and the electronic density of states). The default value is [].

  • structure_type (str (optional)) – Materials project includes the initial and final (relaxed) structure in the database. The initial or final structure can be queried by setting this attribute to initial or final, respectively. The default setting is initial.

  • use_openapi (bool (optional)) – Whether to use the openapi interface of Materials Project. If set to False the legacy interface is used. The default value is False.

import_from_optimade(formulas: str | list[str], database_id: str, api_version: int = 1, optimade_url: str = 'https://providers.optimade.org/providers.json', timeout: float = 60.0) → aim2dat.strct.StructureCollection[source]

Import crystal structures using the optimade-API.

The provider information is queried using the page: https://providers.optimade.org/providers.json.

Parameters:

  • formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.

  • database_id (str) – Database used to query the data.

  • api_version (int (optional)) – Version of the optimade API. The default value is 1.

  • optimade_url (str (optional)) – Page used to obtain the provider information. The default value is 'https://providers.optimade.org/providers.json'.

  • timeout (float (optional)) – Specifies the time to wait for response from the server. The default value is 60.0.

import_from_oqmd(formulas: str | list[str], query_limit=1000) → aim2dat.strct.StructureCollection[source]

Import from the open quantum materials database.

Parameters:

  • formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.

  • query_limit (int (optional)) – Maximum number of crystals that are queried.

remove_constraints()

Remove all constraints.

return_optimade_database_ids(api_version: int = 1, optimade_url: str = 'https://providers.optimade.org/providers.json', timeout: float = 60.0) → list[source]

Return a list of all ids of online databases that provide a base-url.

Parameters:

  • api_version (int (optional)) – Version of the optimade API. The default value is 1.

  • optimade_url (str (optional)) – Page used to obtain the provider information. The default value is 'https://providers.optimade.org/providers.json'.

  • timeout (float (optional)) – Specifies the time to wait for response from the server. The default value is 60.0.

Returns:

list – List of provider-ids.

set_attribute_constraint(attribute, min_value=None, max_value=None)

Set a constraint on attributes.

Parameters:

  • attribute (str) – Attribute to be constraint.

  • min_value (float) – Minimum value of the attribute. In case of no limit the variable can be set to 0.0.

  • max_value (float) – Maximum value of the attribute. In case of no limit the variable can be set to 1.0.

set_concentration_constraint(element, min_conc=0.0, max_conc=1.0)

Set a constraint on the concentration of an element in the structure.

The minimum and maximum values have to be set between 0.0 and 1.0.

Parameters:

  • element (str) – Element to be constraint.

  • min_conc (float) – Minimum concentration. In case of no limit the variable can be set to 0.0.

  • max_conc (float) – Maximum concentration. In case of no limit the variable can be set to 1.0.