mp_api.client.routes.materials.electronic_structure.BandStructureRester

class mp_api.client.routes.materials.electronic_structure.BandStructureRester(api_key: str | None = None, endpoint: str | None = None, include_user_agent: bool = True, use_document_model: bool = True, session: requests.Session | None = None, headers: dict | None = None, mute_progress_bars: bool = False, db_version: str | None = None, local_dataset_cache: str | os.PathLike = PosixPath('/home/runner/mp_datasets'), force_renew: bool = False, query_builder: QueryBuilderWithCache | None = None, s3_client: Any | None = None, timeout: int = 20, **kwargs)

Bases: BaseESPropertyRester

Initialize the REST API helper class.

s3_client: boto3 S3 client object with which to connect to the object stores. timeout: Time in seconds to wait until a request timeout error is thrown

Parameters:

• api_key – A String API key for accessing the MaterialsProject REST interface. Please obtain your API key at https://www.materialsproject.org/dashboard. If this is None, the code will check if there is a “PMG_MAPI_KEY” setting. If so, it will use that environment variable. This makes easier for heavy users to simply add this environment variable to their setups and MPRester can then be called without any arguments.

• endpoint – Url of endpoint to access the MaterialsProject REST interface. Defaults to the standard Materials Project REST address at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface.

• include_user_agent – If True, will include a user agent with the HTTP request including information on pymatgen and system version making the API request. This helps MP support pymatgen users, and is similar to what most web browsers send with each page request. Set to False to disable the user agent.

• session – requests Session object with which to connect to the API, for advanced usage only.

• use_document_model – If False, skip the creating the document model and return data as a dictionary. This can be simpler to work with but bypasses data validation and will not give auto-complete for available fields.

• headers – Custom headers for localhost connections.

• mute_progress_bars – Whether to disable progress bars.

• db_version (str) – EXPERIMENTAL, allows for accessing a different version of the database than what is currently deployed. The Materials Project cannot guarantee that all features will still work.

• local_dataset_cache – Target directory for downloading full datasets. Defaults to ‘mp_datasets’ in the user’s home directory

• force_renew – Option to overwrite existing local dataset

• query_builder – Instance of QueryBuilderWithCache to use in querying delta tables NOTE: Must be a QueryBuilderWithCache, a deltalake.QueryBuilder will be ignored.

• s3_client – boto3 S3 client object with which to connect to the object stores.ct to the object stores.ct to the object stores.

• timeout – Time in seconds to wait until a request timeout error is thrown

• **kwargs – access to legacy kwargs that may be in the process of being deprecated

__init__(api_key: str | None = None, endpoint: str | None = None, include_user_agent: bool = True, use_document_model: bool = True, session: requests.Session | None = None, headers: dict | None = None, mute_progress_bars: bool = False, db_version: str | None = None, local_dataset_cache: str | os.PathLike = PosixPath('/home/runner/mp_datasets'), force_renew: bool = False, query_builder: QueryBuilderWithCache | None = None, s3_client: Any | None = None, timeout: int = 20, **kwargs)

Initialize the REST API helper class.

s3_client: boto3 S3 client object with which to connect to the object stores. timeout: Time in seconds to wait until a request timeout error is thrown

Parameters:

• api_key – A String API key for accessing the MaterialsProject REST interface. Please obtain your API key at https://www.materialsproject.org/dashboard. If this is None, the code will check if there is a “PMG_MAPI_KEY” setting. If so, it will use that environment variable. This makes easier for heavy users to simply add this environment variable to their setups and MPRester can then be called without any arguments.

• endpoint – Url of endpoint to access the MaterialsProject REST interface. Defaults to the standard Materials Project REST address at “https://api.materialsproject.org”, but can be changed to other urls implementing a similar interface.

• include_user_agent – If True, will include a user agent with the HTTP request including information on pymatgen and system version making the API request. This helps MP support pymatgen users, and is similar to what most web browsers send with each page request. Set to False to disable the user agent.

• session – requests Session object with which to connect to the API, for advanced usage only.

• use_document_model – If False, skip the creating the document model and return data as a dictionary. This can be simpler to work with but bypasses data validation and will not give auto-complete for available fields.

• headers – Custom headers for localhost connections.

• mute_progress_bars – Whether to disable progress bars.

• db_version (str) – EXPERIMENTAL, allows for accessing a different version of the database than what is currently deployed. The Materials Project cannot guarantee that all features will still work.

• local_dataset_cache – Target directory for downloading full datasets. Defaults to ‘mp_datasets’ in the user’s home directory

• force_renew – Option to overwrite existing local dataset

• query_builder – Instance of QueryBuilderWithCache to use in querying delta tables NOTE: Must be a QueryBuilderWithCache, a deltalake.QueryBuilder will be ignored.

• s3_client – boto3 S3 client object with which to connect to the object stores.ct to the object stores.ct to the object stores.

• timeout – Time in seconds to wait until a request timeout error is thrown

• **kwargs – access to legacy kwargs that may be in the process of being deprecated

Methods

__init__([api_key, endpoint, ...])	Initialize the REST API helper class.
count([criteria])	Return a count of total documents.
get_bandstructure_from_material_id(material_id)	Get the band structure pymatgen object associated with a Materials Project ID.
get_bandstructure_from_task_id(task_id[, ...])	Get the band structure pymatgen object associated with a given task ID.
get_data_by_id(document_id[, fields])
search([band_gap, efermi, is_gap_direct, ...])	Query band structure summary data in electronic structure docs using a variety of search criteria.
search_bandstructure_summary(*args, **kwargs)	Deprecated.

Attributes

available_fields
delta_backed
es_rester
primary_key
query_builder
s3_client
session
suffix

search_bandstructure_summary(*args, **kwargs)

Deprecated.

search(band_gap: tuple[float, float] | None = None, efermi: tuple[float, float] | None = None, is_gap_direct: bool | None = None, is_metal: bool | None = None, magnetic_ordering: Ordering | str | None = None, path_type: BSPathType | str = BSPathType.setyawan_curtarolo, num_chunks: int | None = None, chunk_size: int = 1000, all_fields: bool = True, fields: list[str] | None = None)

Query band structure summary data in electronic structure docs using a variety of search criteria.

Parameters:

• band_gap (Tuple[float,float]) – Minimum and maximum band gap in eV to consider.

• efermi (Tuple[float,float]) – Minimum and maximum fermi energy in eV to consider.

• is_gap_direct (bool) – Whether the material has a direct band gap.

• is_metal (bool) – Whether the material is considered a metal.

• magnetic_ordering (Ordering or str) – Magnetic ordering of the material.

• path_type (BSPathType or str) – k-path selection convention for the band structure.

• num_chunks (int) – Maximum number of chunks of data to yield. None will yield all possible.

• chunk_size (int) – Number of data entries per chunk.

• all_fields (bool) – Whether to return all fields in the document. Defaults to True.

• fields (List[str]) – List of fields in ElectronicStructureDoc to return data for. Default is material_id and last_updated if all_fields is False.

Returns:

([ElectronicStructureDoc]) List of electronic structure documents

get_bandstructure_from_task_id(task_id: str, run_type: str | RunType | None = None, path_type: str | BSPathType | None = None, load_projections: bool = False) → BandStructure

Get the band structure pymatgen object associated with a given task ID.

Parameters:

• task_id (str) – Task ID for the band structure calculation

• run_type (str, RunType, or None) – Optional run type, will speed up query due to delta table partitioning.

• path_type (str, BSPathType, or None) – Optional path type to speed up query

• load_projections (bool) – Optionally load atom- and spin-projected bandstructure, if available.

Returns:

BandStructure or BandStructureSymmLine object

Return type:

bandstructure (BandStructure)

get_bandstructure_from_material_id(material_id: str, path_type: str | BSPathType = BSPathType.setyawan_curtarolo, line_mode=True, load_projections: bool = False)

Get the band structure pymatgen object associated with a Materials Project ID.

Parameters:

• material_id (str) – Materials Project ID for a material

• path_type (BSPathType or its value as a str) – k-point path selection convention

• line_mode (bool) – Whether to return data for a line-mode calculation

• load_projections (bool) – Optionally load atom- and spin-projected bandstructure, if available.

Returns:

BandStructure or BandStructureSymmLine object

Return type:

bandstructure (Union[BandStructure, BandStructureSymmLine])

count(criteria: dict | None = None) → int

Return a count of total documents.

Parameters:

criteria (dict | None) – As in .search(). Defaults to None

Returns:

Count of total results

Return type:

int

document_model

alias of ElectronicStructureDoc