Databases Module

Provides access to multiple materials databases.

Supported databases:

• Materials Project (MP)

• AFLOW

• JARVIS

• Crystallography Open Database (COD)

Available data:

• Mechanical, electronic, thermodynamic properties

• Structural and crystallographic information

• Chemical composition and symmetry

Main Classes

class PyGamLab.databases.GAM_Explorer(backend='jarvis', timeout=60, api_key=None, dataset='dft_3d', max_results=5, batch_size=10)

Bases: object

Unified interface to explore material properties from multiple databases: Materials Project, COD (Crystallography Open Database), Jarvis (NIST), and AFLOW.

This class allows searching and fetching electronic, mechanical, thermodynamic, and structural properties from a selected backend or from all backends simultaneously.

Parameters:

• backend (str, default='jarvis') – Backend database to use. Options are: ‘material_project’, ‘cod’, ‘jarvis’, ‘aflow’, ‘all’.

• timeout (int, default=60) – Timeout in seconds for database queries (applies to COD).

• api_key (str, optional) – API key required for Materials Project access.

• dataset (str, default='dft_3d') – Dataset to use when querying Jarvis.

• max_results (int, default=5) – Maximum number of materials to return for search queries.

• batch_size (int, default=10) – Batch size for queries (applies to AFLOW).

backend

Normalized backend name.

Type:

str

_explorer

Instance of the selected backend explorer.

Type:

object

search_results

Stores results from the last search query.

Type:

dict or list

Examples

# Example 1: Using Jarvis backend to search and fetch properties >>> gam = GAM_Explorer(backend=’jarvis’) >>> results = gam.search_materials(formula=”MoS2”) >>> electronic_props = gam.fetch_electronic_properties(gam_id=”JARVIS-123”) >>> mechanical_props = gam.fetch_mechanical_properties(gam_id=”JARVIS-123”) >>> thermo_props = gam.fetch_thermodynamic_properties(gam_id=”JARVIS-123”) >>> structure = gam.fetch_structure(gam_id=”JARVIS-123”) >>> all_data = gam.fetch_all_data(gam_id=”JARVIS-123”)

# Example 2: Using Materials Project backend >>> gam_mp = GAM_Explorer(backend=’material_project’, api_key=”MP_API_KEY”) >>> results_mp = gam_mp.search_materials(elements=[“Mo”,”S”]) >>> electronic_mp = gam_mp.fetch_electronic_properties(gam_id=”mp-123”)

# Example 3: Using AFLOW backend >>> gam_aflow = GAM_Explorer(backend=’aflow’) >>> results_aflow = gam_aflow.search_materials(species=”MoS2”) >>> mechanical_aflow = gam_aflow.fetch_mechanical_properties(gam_id=”aflow-456”)

# Example 4: Using COD backend for structure data >>> gam_cod = GAM_Explorer(backend=’cod’) >>> results_cod = gam_cod.search_materials(formula=”MoS2”) >>> structure_cod = gam_cod.fetch_structure(gam_id=”COD-789”)

# Example 5: Using all backends simultaneously >>> gam_all = GAM_Explorer(backend=’all’, api_key=”MP_API_KEY”) >>> results_all = gam_all.search_materials(formula=”MoS2”, elements=[“Mo”,”S”], species=”MoS2”, mp_ids=[“mp-123”]) >>> all_props = gam_all.fetch_all_data(mp_id=”mp-123”, juid=”JARVIS-123”, auid=”aflow-456”, code_id=”COD-789”) >>> all_electronic = gam_all.fetch_electronic_properties(mp_id=”mp-123”, juid=”JARVIS-123”, auid=”aflow-456”) >>> all_mechanical = gam_all.fetch_mechanical_properties(mp_id=”mp-123”, juid=”JARVIS-123”, auid=”aflow-456”) >>> all_thermo = gam_all.fetch_thermodynamic_properties(mp_id=”mp-123”, juid=”JARVIS-123”, auid=”aflow-456”) >>> all_structures = gam_all.fetch_structure(mp_id=”mp-123”, juid=”JARVIS-123”, auid=”aflow-456”, code_id=”COD-789”)

fetch_all_data(gam_id=None, mp_id=None, juid=None, auid=None, code_id=None)

Fetch all available properties (electronic, mechanical, thermodynamic, structure) for a material.

Parameters:

• gam_id (str, optional) – Material ID for single backend (Jarvis, AFLOW, or Materials Project).

• mp_id (str, optional) – Materials Project ID (required when backend=’all’).

• juid (str, optional) – Jarvis ID (required when backend=’all’).

• auid (str, optional) – AFLOW ID (required when backend=’all’).

• code_id (str, optional) – COD ID (required when backend=’all’).

Returns:

Dictionary of all properties. If backend=’all’, returns results from all backends; otherwise, returns results from the selected backend.

Return type:

dict

Raises:

ValueError – If required IDs are not provided.

Examples

>>> gam = GAM_Explorer(backend='jarvis')
>>> gam.fetch_all_data(gam_id="JARVIS-123")
{'electronic_prop': {...}, 'mechanical_prop': {...}, 'thermo_prop': {...}, 'structure': {...}}

>>> gam = GAM_Explorer(backend='all', api_key="MP_API_KEY")
>>> gam.fetch_all_data(mp_id="mp-123", juid="JARVIS-123", auid="aflow-456", code_id="COD-789")
{'Material Project': {...}, 'COD': {...}, 'Jarvis': {...}, 'Aflow': {...}}

fetch_electronic_properties(gam_id=None, mp_id=None, juid=None, auid=None)

Fetch electronic properties for a material.

Parameters:

• gam_id (str, optional) – Material ID for single backend (Jarvis, AFLOW, or Materials Project).

• mp_id (str, optional) – Materials Project ID (required when backend=’all’).

• juid (str, optional) – Jarvis ID (required when backend=’all’).

• auid (str, optional) – AFLOW ID (required when backend=’all’).

Returns:

Electronic properties of the material. Returns a dictionary containing results from multiple backends if backend=’all’. Returns None for COD backend.

Return type:

dict or None

Raises:

• ValueError – If required IDs are not provided.

• NotImplementedError – If COD backend is selected.

Examples

>>> gam = GAM_Explorer(backend='jarvis')
>>> gam.fetch_electronic_properties(gam_id="JARVIS-123")
{'band_gap': 1.5, 'eigenvalues': [...], ...}

>>> gam = GAM_Explorer(backend='all', api_key="MP_API_KEY")
>>> gam.fetch_electronic_properties(mp_id="mp-123", juid="JARVIS-123", auid="aflow-456")
{'Material Project': {...}, 'Jarvis': {...}, 'Aflow': {...}, 'COD': None}

fetch_mechanical_properties(gam_id=None, mp_id=None, juid=None, auid=None)

Fetch mechanical properties for a material.

Parameters:

• gam_id (str, optional) – Material ID for single backend (Jarvis, AFLOW, or Materials Project).

• mp_id (str, optional) – Materials Project ID (required when backend=’all’).

• juid (str, optional) – Jarvis ID (required when backend=’all’).

• auid (str, optional) – AFLOW ID (required when backend=’all’).

Returns:

Mechanical properties of the material. Returns a dictionary containing results from multiple backends if backend=’all’. Returns None for COD backend.

Return type:

dict or None

Raises:

• ValueError – If required IDs are not provided.

• NotImplementedError – If COD backend is selected.

Examples

>>> gam = GAM_Explorer(backend='jarvis')
>>> gam.fetch_mechanical_properties(gam_id="JARVIS-123")
{'bulk_modulus_reuss': 120.5, 'bulk_modulus_voigt': 123.0, ...}

>>> gam = GAM_Explorer(backend='all', api_key="MP_API_KEY")
>>> gam.fetch_mechanical_properties(mp_id="mp-123", juid="JARVIS-123", auid="aflow-456")
{'Material Project': {...}, 'Jarvis': {...}, 'Aflow': {...}, 'COD': None}

fetch_structure(gam_id=None, mp_id=None, juid=None, auid=None, code_id=None)

Fetch structural properties for a material.

Parameters:

• gam_id (str, optional) – Material ID for single backend (Jarvis, AFLOW, or Materials Project).

• mp_id (str, optional) – Materials Project ID (required when backend=’all’).

• juid (str, optional) – Jarvis ID (required when backend=’all’).

• auid (str, optional) – AFLOW ID (required when backend=’all’).

• code_id (str, optional) – COD ID (required when backend=’all’).

Returns:

Structural properties of the material. Returns a dictionary containing results from multiple backends if backend=’all’.

Return type:

dict or None

Raises:

ValueError – If required IDs are not provided.

Examples

>>> gam = GAM_Explorer(backend='jarvis')
>>> gam.fetch_structure(gam_id="JARVIS-123")
{'spacegroup_relax': 194, 'Bravais_lattice_relax': 'hexagonal', ...}

>>> gam = GAM_Explorer(backend='all', api_key="MP_API_KEY")
>>> gam.fetch_structure(mp_id="mp-123", juid="JARVIS-123", auid="aflow-456", code_id="COD-789")
{'Material Project': {...}, 'COD': {...}, 'Jarvis': {...}, 'Aflow': {...}}

fetch_thermodynamic_properties(gam_id=None, mp_id=None, juid=None, auid=None)

Fetch thermodynamic properties for a material.

Parameters:

• gam_id (str, optional) – Material ID for single backend (Jarvis, AFLOW, or Materials Project).

• mp_id (str, optional) – Materials Project ID (required when backend=’all’).

• juid (str, optional) – Jarvis ID (required when backend=’all’).

• auid (str, optional) – AFLOW ID (required when backend=’all’).

Returns:

Thermodynamic properties of the material. Returns a dictionary containing results from multiple backends if backend=’all’. Returns None for COD backend.

Return type:

dict or None

Raises:

• ValueError – If required IDs are not provided.

• NotImplementedError – If COD backend is selected.

Examples

>>> gam = GAM_Explorer(backend='jarvis')
>>> gam.fetch_thermodynamic_properties(gam_id="JARVIS-123")
{'enthalpy_formation_cell': -5.4, 'entropy_cell': 12.3, ...}

>>> gam = GAM_Explorer(backend='all', api_key="MP_API_KEY")
>>> gam.fetch_thermodynamic_properties(mp_id="mp-123", juid="JARVIS-123", auid="aflow-456")
{'Material Project': {...}, 'Jarvis': {...}, 'Aflow': {...}, 'COD': None}

search_materials(formula=None, elements=None, mp_ids=None, species=None, description=True)

Search for materials using the selected backend.

Parameters:

• formula (str, optional) – Chemical formula to search for.

• elements (list, optional) – Elements to search for (only for Materials Project).

• mp_ids (list, optional) – Materials Project IDs (only for Materials Project backend).

• species (str or list, optional) – Species for AFLOW backend.

• description (bool, default=True) – If True, returns detailed descriptions. Otherwise, only IDs.

Returns:

Search results. Dict is returned if backend=’all’.

Return type:

list or dict

Raises:

ValueError – If backend-specific arguments are used incorrectly.

Database-Specific Explorers

class PyGamLab.databases.Aflow_Explorer

Bases: object

A unified interface to search and fetch various material properties from the AFLOW database.

This class allows searching by species or chemical formula, and fetching electronic, mechanical, thermodynamic, and structural properties of materials using AFLOW keys.

all_entries

Stores the results of the latest search query.

Type:

list

results

Stores the latest fetched data for a material.

Type:

dict

Examples

>>> explorer = Aflow_Explorer()
>>> results = explorer.search_materials(formula="MoS2")
>>> explorer.fetch_electronic_properties("aflow-123")
{'formula': 'MoS2', 'bandgap': 1.23, ...}
>>> all_data = explorer.fetch_all_data("aflow-123")
>>> all_data['electronic_prop']['bandgap']
1.23

fetch_all_data(auid)

Fetch all available data (electronic, mechanical, thermodynamic, structure) for a material.

Parameters:

auid (str) – AFLOW unique ID of the material.

Returns:

Dictionary with keys: ‘electronic_prop’, ‘mechanical_prop’, ‘thermo_prop’, ‘structure’.

Return type:

dict

Example

>>> all_data = explorer.fetch_all_data("aflow-123")
>>> all_data['electronic_prop']['bandgap']
1.23

fetch_electronic_properties(auid)

Fetch electronic properties for a given AFLOW AUID.

Parameters:

auid (str) – AFLOW unique ID of the material.

Returns:

Dictionary containing electronic properties such as bandgap, spin polarization, etc.

Return type:

dict

Example

>>> explorer.fetch_electronic_properties("aflow-123")
{'formula': 'MoS2', 'bandgap': 1.23, ...}

fetch_mechanical_properties(auid)

Fetch mechanical properties for a given AFLOW AUID.

Parameters:

auid (str) – AFLOW unique ID of the material.

Returns:

Dictionary containing bulk modulus, shear modulus, elastic tensors, etc.

Return type:

dict

fetch_structure(auid)

Fetch structural properties for a given AFLOW AUID.

Parameters:

auid (str) – AFLOW unique ID of the material.

Returns:

Dictionary containing lattice, space group, atomic positions, density, and valence info.

Return type:

dict

fetch_thermodynamic_properties(auid)

Fetch thermodynamic properties for a given AFLOW AUID.

Parameters:

auid (str) – AFLOW unique ID of the material.

Returns:

Dictionary containing Debye temperature, heat capacity, enthalpy, and related properties.

Return type:

dict

search_materials(species=None, formula=None, max_results=5, batch_size=10, description=True)

Search for materials in AFLOW by species or chemical formula.

Parameters:

• species (str or list[str], optional) – Element(s) to search for.

• formula (str, optional) – Chemical formula to search for.

• max_results (int, default 5) – Maximum number of results to return.

• batch_size (int, default 10) – Number of entries retrieved per batch from AFLOW.

• description (bool, default True) – If True, returns detailed information for each entry. If False, returns only AFLOW unique IDs (AUIDs).

Returns:

List of results containing AUID and optionally detailed description.

Return type:

list of dict

Example

>>> explorer = Aflow_Explorer()
>>> explorer.search_materials(formula="MoS2", max_results=3)
[{'auid': 'aflow-123', 'prototype': 'MoS2', 'spacegroup_relax': 187, ...}]

class PyGamLab.databases.COD_Explorer(timeout=60)

Bases: object

Python wrapper for the Crystallography Open Database (COD).

Provides methods to search materials by chemical formula, retrieve COD IDs, and fetch crystallographic information files (CIFs).

timeout

Request timeout in seconds for HTTP queries.

Type:

int

url

Base URL of the COD website.

Type:

str

api_url

Endpoint URL for COD search queries.

Type:

str

formula

Last processed chemical formula in COD format.

Type:

str

all_elements

List of all recognized chemical elements (1- and 2-letter symbols).

Type:

list[str]

Examples

>>> explorer = COD_Explorer(timeout=30)
>>> ids = explorer.search_materials("TiO2")
>>> ids
[900856, 900857, 901234]
>>> structure = explorer.fetch_structure(ids[0])
>>> print(structure['cif'][:200])  # Print first 200 chars of CIF

all_elements = ['H', 'He', 'Li', 'Be', 'B', 'C', 'N', 'O', 'F', 'Ne', 'Na', 'Mg', 'Al', 'Si', 'P', 'S', 'Cl', 'Ar', 'K', 'Ca', 'Sc', 'Ti', 'V', 'Cr', 'Mn', 'Fe', 'Co', 'Ni', 'Cu', 'Zn', 'Ga', 'Ge', 'As', 'Se', 'Br', 'Kr', 'Rb', 'Sr', 'Y', 'Zr', 'Nb', 'Mo', 'Tc', 'Ru', 'Rh', 'Pd', 'Ag', 'Cd', 'In', 'Sn', 'Sb', 'Te', 'I', 'Xe', 'Cs', 'Ba', 'La', 'Ce', 'Pr', 'Nd', 'Pm', 'Sm', 'Eu', 'Gd', 'Tb', 'Dy', 'Ho', 'Er', 'Tm', 'Yb', 'Lu', 'Hf', 'Ta', 'W', 'Re', 'Os', 'Ir', 'Pt', 'Au', 'Hg', 'Tl', 'Pb', 'Bi', 'Po', 'At', 'Rn', 'Fr', 'Ra', 'Ac', 'Th', 'Pa', 'U', 'Np', 'Pu', 'Am', 'Cm', 'Bk', 'Cf', 'Es', 'Fm', 'Md', 'No', 'Lr', 'Rf', 'Db', 'Sg', 'Bh', 'Hs', 'Mt', 'Ds', 'Rg', 'Cn', 'Nh', 'Fl', 'Mc', 'Lv', 'Ts', 'Og']

fetch_all_data(cod_id)

Fetch all available data for a given COD ID.

Parameters:

cod_id (int) – COD ID of the structure to fetch.

Returns:

Dictionary containing: - ‘formula’: COD-formatted chemical formula - ‘cod_id’: COD ID of the structure - ‘cif’: Raw CIF content as a string

Return type:

dict

Notes

Currently identical to fetch_structure but designed for future expansion to include more metadata fields from COD.

Example

>>> explorer = COD_Explorer()
>>> data = explorer.fetch_all_data(856789)
>>> print(data.keys())
dict_keys(['formula', 'cod_id', 'cif'])

fetch_structure(cod_id)

Fetch structure data for a given COD ID.

Parameters:

cod_id (int) – COD ID of the structure to fetch.

Returns:

Dictionary containing: - ‘formula’: COD-formatted chemical formula - ‘cod_id’: COD ID of the structure - ‘cif’: Raw CIF content as a string

Return type:

dict

Example

>>> explorer = COD_Explorer()
>>> ids = explorer.search_materials("TiO2")
>>> structure = explorer.fetch_structure(ids[0])
>>> print(structure['formula'])
'Ti O2'

search_materials(formula)

Search COD for materials matching a chemical formula.

Parameters:

formula (str) – Chemical formula (e.g., ‘TiO2’, ‘C6H6’).

Returns:

List of COD IDs corresponding to structures matching the formula.

Return type:

List[int]

Example

>>> explorer = COD_Explorer()
>>> ids = explorer.search_materials("C6H6")
>>> print(ids)
[123456, 123457]

class PyGamLab.databases.Jarvis_Explorer

Bases: object

Python interface for exploring the JARVIS-DFT dataset.

This class allows searching materials by chemical formula, and retrieving electronic, mechanical, thermodynamic, and structural properties for entries.

all_entries

List of entries matching the last search.

Type:

list[dict]

results

Dictionary storing electronic, mechanical, thermodynamic, structural, and metadata for the last fetched material.

Type:

dict

Examples

>>> explorer = Jarvis_Explorer()
>>> entries = explorer.search_materials("MoS2", dataset="dft_3d", max_results=3)
>>> entries
[{'JID': 'JVASP-123', 'formula': 'MoS2', 'spg': 'P63/mmc', ...}, ...]
>>> explorer.fetch_electronic_properties("JVASP-123")
{'JID': 'JVASP-123', 'Formula': 'MoS2', 'optb88vdw_bandgap': 1.23, ...}
>>> all_data = explorer.fetch_all_data("JVASP-123")
>>> all_data['electronic_prop']['optb88vdw_bandgap']
1.23

fetch_all_data(jid)

Fetch all available data (electronic, mechanical, thermodynamic, structural, metadata) for a given JARVIS ID.

Parameters:

jid (str) – JARVIS ID of the material.

Returns:

Dictionary with keys: - electronic_prop - mechanical_prop - thermo_prop - structure - meta_data

Return type:

dict

Example

>>> all_data = explorer.fetch_all_data("JVASP-123")
>>> all_data['electronic_prop']['optb88vdw_bandgap']
1.23

fetch_electronic_properties(jid)

Retrieve electronic properties for a given JARVIS ID.

Parameters:

jid (str) – JARVIS ID of the material.

Returns:

Electronic properties including bandgaps, effective masses, dielectric constants, magnetization, and superconducting Tc. Returns None if jid not found or search not performed.

Return type:

dict or None

Example

>>> explorer.fetch_electronic_properties("JVASP-123")
{'JID': 'JVASP-123', 'Formula': 'MoS2', 'optb88vdw_bandgap': 1.23, ...}

fetch_mechanical_properties(jid)

Retrieve mechanical/elastic properties for a given JARVIS ID.

Parameters:

jid (str) – JARVIS ID of the material.

Returns:

Mechanical properties including elastic tensor, bulk modulus, shear modulus, Poisson ratio, and piezoelectric constants. Returns None if jid not found or search not performed.

Return type:

dict or None

Example

>>> explorer.fetch_mechanical_properties("JVASP-123")
{'JID': 'JVASP-123', 'Formula': 'MoS2', 'elastic_tensor': [...], ...}

fetch_structure(jid)

Retrieve structural properties for a given JARVIS ID.

Parameters:

jid (str) – JARVIS ID of the material.

Returns:

Structural properties including space group, atoms, dimensionality, density, crystal type, and links to raw data files. Returns None if jid not found or search not performed.

Return type:

dict or None

Example

>>> explorer.fetch_structure("JVASP-123")
{'JID': 'JVASP-123', 'Formula': 'MoS2', 'spg_number': 194, ...}

fetch_thermodynamic_properties(jid)

Retrieve thermodynamic properties for a given JARVIS ID.

Parameters:

jid (str) – JARVIS ID of the material.

Returns:

Thermodynamic properties including Seebeck coefficients, power factors, conductivity, heat capacities, Debye temperature, formation energy, and exfoliation energy. Returns None if jid not found or search not performed.

Return type:

dict or None

Example

>>> explorer.fetch_thermodynamic_properties("JVASP-123")
{'JID': 'JVASP-123', 'Formula': 'MoS2', 'n-Seebeck': 200, ...}

search_materials(formula=None, dataset='dft_3d', max_results=5, description=True)

Search the JARVIS dataset for materials matching a chemical formula.

Parameters:

• formula (str, optional) – Chemical formula to search for (e.g., “MoS2”). If None, returns all entries.

• dataset (str, default "dft_3d") – Name of the dataset to query.

• max_results (int, default 5) – Maximum number of entries to return.

• description (bool, default True) – If True, returns detailed description dictionaries for each entry. If False, returns only JIDs.

Returns:

If description=True, returns a list of dicts containing basic material info:

• JID

• formula

• space group

• bandgap

• formation energy

• density

• dimensionality

If description=False, returns a list of JIDs. Returns None if no matches are found.

Return type:

list[dict] or list[str] or None

Example

>>> explorer = Jarvis_Explorer()
>>> results = explorer.search_materials("MoS2", dataset="dft_3d", max_results=3)
>>> results[0]['formula']
'MoS2'

class PyGamLab.databases.MaterialsProject_Explorer(api_key=None)

Bases: object

A unified interface to search and fetch various material properties from the Materials Project.

This class allows searching by elements, chemical formula, or specific MP-IDs, and fetching electronic, mechanical, thermodynamic, and structural properties.

api_key

API key for accessing Materials Project (if required).

Type:

str, optional

mpr

MPRester instance for querying the API.

Type:

MPRester

results

Stores the latest fetched data for a material.

Type:

dict

Examples

>>> explorer = MaterialsProject_Explorer(api_key="YOUR_API_KEY")
>>> results = explorer.search_materials(formula="MoS2")
>>> explorer.fetch_electronic_properties("mp-123")
{'mp-id': 'mp-123', 'band_gap': 1.23, ...}
>>> all_data = explorer.fetch_all_data("mp-123")
>>> all_data['electronic_prop']['band_gap']
1.23
>>> explorer.close()

close()

Close the underlying MPRester session.

Example

>>> explorer.close()

fetch_all_data(mp_id)

Fetch all available data (electronic, mechanical, thermodynamic, structure) for a material.

Parameters:

mp_id (str) – Materials Project ID.

Returns:

Dictionary with keys: ‘electronic_prop’, ‘mechanical_prop’, ‘thermo_prop’, ‘structure’, ‘meta_data’.

Return type:

dict

Example

>>> all_data = explorer.fetch_all_data("mp-123")
>>> all_data['electronic_prop']['band_gap']
1.23

fetch_electronic_properties(mp_id)

Fetch electronic properties for a given Materials Project ID.

Parameters:

mp_id (str) – Materials Project ID (e.g., “mp-123”).

Returns:

Electronic properties including band structure, density of states, bandgap, etc.

Return type:

dict

Example

>>> explorer.fetch_electronic_properties("mp-123")
{'mp-id': 'mp-123', 'band_gap': 1.23, 'DOS': {...}, ...}

fetch_mechanical_properties(mp_id)

Fetch mechanical properties for a given Materials Project ID.

Parameters:

mp_id (str) – Materials Project ID.

Returns:

Mechanical properties including elastic tensors, bulk/shear modulus, Poisson ratio.

Return type:

dict or None

Example

>>> explorer.fetch_mechanical_properties("mp-123")
{'mp-id': 'mp-123', 'elastic_tensor': [...], ...}

fetch_structure(mp_id)

Fetch structural properties for a given Materials Project ID.

Parameters:

mp_id (str) – Materials Project ID.

Returns:

Structure data in pymatgen format.

Return type:

list of dict or None

Example

>>> explorer.fetch_structure("mp-123")
[{'structure_pymatgen': Structure(...)}]

fetch_thermodynamic_properties(mp_id)

Fetch thermodynamic properties for a given Materials Project ID.

Parameters:

mp_id (str) – Materials Project ID.

Returns:

Thermodynamic properties including formation energy, heat capacities, etc.

Return type:

dict or None

Example

>>> explorer.fetch_thermodynamic_properties("mp-123")
{'mp-id': 'mp-123', 'formation_energy_per_atom': -2.34, ...}

search_materials(elements=None, formula=None, mp_ids=None, max_results=5, description=True)

Search for materials by elements, chemical formula, or MP-IDs.

Parameters:

• elements (list[str], optional) – List of chemical elements to search for (e.g., [“Mo”, “S”]).

• formula (str, optional) – Chemical formula to search for (e.g., “MoS2”).

• mp_ids (list[str], optional) – List of Materials Project IDs to search directly.

• max_results (int, default 5) – Maximum number of results to return.

• description (bool, default True) – If True, returns a list of dictionaries with basic material info. If False, returns only a list of material IDs.

Returns:

List of material IDs or detailed descriptions for each result.

Return type:

list[str] or list[dict]

Example

>>> explorer = MaterialsProject_Explorer()
>>> explorer.search_materials(formula="MoS2")
[{'mp-id': 'mp-123', 'system': 'Mo-S', 'band_gap (eV)': 1.23, ...}]