htesp.element_extract

Module to extract data from materials project database

Functions

convexhull(data)	Filters the compounds close to the convex hull.
create_folder(parent_folder)	Function to create a 'download' folder :param parent_folder: :type parent_folder: path to current working directory
create_input([input_data])	Reads 'download.csv' file inside 'download' folder and creates 'input.in' and 'mpid-list.in' files for further downloading and calculations.
data_combine(data1, data2)	Combines two pandas DataFrames into a single DataFrame.
data_one_element_compound(elm, ntype, ...[, ...])	Extracts information for compounds containing only one element.
data_two_element_compound(el1, el2, ntype, ...)	Extracts information for compounds containing two elements.
download(elm, num_el, exclude_el, properties)	Extracts various properties for compounds that satisfy certain criteria from the Materials Project database.
download_by_entry(entries, must_include[, ...])	Function to extract and create input files using "mp_api.client.MPRester.get_entries_in_chemsys" Function of the materials project API package (pip install mp_api).
extract(ntype, properties, elm, exclude_el)	Function to extract the data and apply filters, then write 'download.csv' file inside 'download' folder.
filter_ordering(data, ordering)	Keep the rows whose magnetic ordering matches ordering.
legacy_mpid(value)	A Materials Project id in the legacy mp-<integer> spelling.
main()	Main function to orchestrate the data extraction and input file creation process.
metal_filter(data)	Filters metallic compounds from the input DataFrame.
plain_value(value)	An Enum member -> its value; anything else unchanged.
remove(data, element_list)	Removes compounds containing specified elements from the DataFrame.
stable(data)	Filters the compounds for those having negative formation energy.

htesp.element_extract.legacy_mpid(value)

A Materials Project id in the legacy mp-<integer> spelling.

FIX(29): Materials Project is migrating identifiers from MPID (mp-763) to AlphaID (mp-bdj). The two spellings address the same material and the API accepts either, but only the legacy one matches the R<mpid>-<compound>/ directories, scf_dir/scf-<mpid>.in and the tracking files of a campaign started before the migration – and it is what a person recognises.

The 1.x code wrote search['material_id'].string. The rewrite replaced that with search.dict()['material_id'], which drops two things:

• .dict() serialises the id to a plain str already in the alphabetic spelling – 'mp-bdj', with no .string attribute left to recover the legacy form. Attribute access (search.material_id) keeps the MPID/AlphaID object, so callers should prefer it;

• .string, which is the conversion itself.

This helper therefore tries, in order: the object’s own .string; decoding the text through AlphaID, which accepts either spelling and preserves the prefix (mvc- stays mvc-); and finally the text unchanged, so a non-MP identifier (OQMD, AFLOW) passes through untouched.

htesp.element_extract.plain_value(value)

An Enum member -> its value; anything else unchanged.

FIX(28): emmet.core declares Ordering as a plain Enum, so Ordering.NM is not equal to "NM" and str(Ordering.NM) is "Ordering.NM". Both bite the magnetic-ordering filter:

• download() wrote str(prop) into download/data-<elm>.csv, so the ordering column held Ordering.NM and the extract() filter data['ordering'] == 'NM' matched no row at all – a search that returned 465 compounds wrote 0 of them to mpid-list.in;

• download_by_entry() compares the raw field, so mag_logic was False for every entry whenever chemsys.magnetic was false.

Normalising here keeps the CSV and the comparisons in the documented "NM" / "FM" / "AFM" / "FiM" vocabulary of config.json.

htesp.element_extract.filter_ordering(data, ordering)

Keep the rows whose magnetic ordering matches ordering.

FIX(30): this was an unconditional data['ordering'] == ordering, the only filter in extract() with no way to switch it off – metal, FE and thermo_stable are each guarded by an if. That was survivable while Materials Project reported a definite ordering for everything, but it now reports "Unknown" for any material with no magnetism calculation: in a B-binary search, 202 of 465 hits, and 158 of the 222 that survive the metal and formation-energy filters. With ordering: "NM" every one of those is discarded silently, which is how a search returning 465 compounds wrote 2 rows to mpid-list.in.

Accepted values of ordering:

null / None

apply no filter at all – keep every ordering;

a string ("NM")

keep exactly that ordering, the historical behaviour;

a list (["NM", "Unknown"])

keep any row whose ordering is one of them. This is usually what is wanted: “Unknown” mostly means nobody ran the magnetism calculation, not that the material is magnetic.

An empty list is treated as null rather than as “match nothing”, since a filter that rejects everything is never what a configuration means.

htesp.element_extract.create_folder(parent_folder)

Function to create a ‘download’ folder :param parent_folder: :type parent_folder: path to current working directory

htesp.element_extract.download(elm, num_el, exclude_el, properties, input_data=None)

Extracts various properties for compounds that satisfy certain criteria from the Materials Project database.

Parameters:

elmstr or list of str

Element(s) always to include in the compounds. For example, for hydrogen, elm = ‘H’. If multiple elements are desired, provide a list with up to size 2. For example, elm = [‘B’, ‘C’] for boron and carbon.

num_elint

Number of elements in the compound.

exclude_ellist of str

List of elements to exclude from the compound.

propertieslist of str

List of properties to extract.

input_datadict, optional

Parsed config.json. Loaded with htesp.check_json.config() when omitted.

Returns:

datapandas DataFrame

DataFrame containing the extracted data.

Example:

>>> download('H', 2, ['O', 'F'], ['material_id', 'formation_energy_per_atom'])

htesp.element_extract.stable(data)

Filters the compounds for those having negative formation energy.

Parameters:

datapandas DataFrame

DataFrame containing information about compounds, including formation energy per atom.

Returns:

datapandas DataFrame

DataFrame containing compounds with negative formation energy per atom.

htesp.element_extract.convexhull(data)

Filters the compounds close to the convex hull.

Parameters:

datapandas DataFrame

DataFrame containing information about compounds, including energy above hull.

Returns:

datapandas DataFrame

DataFrame containing compounds close to the convex hull.

htesp.element_extract.metal_filter(data)

Filters metallic compounds from the input DataFrame.

Parameters:

datapandas DataFrame

DataFrame containing information about compounds, including band_gap.

Returns:

datapandas DataFrame

DataFrame containing metallic compounds (band gap <= 0.00001).

htesp.element_extract.data_combine(data1, data2)

Combines two pandas DataFrames into a single DataFrame.

Parameters:

data1pandas DataFrame

The first DataFrame to be combined.

data2pandas DataFrame

The second DataFrame to be combined.

Returns:

datapandas DataFrame

Combined DataFrame containing data from both data1 and data2.

htesp.element_extract.remove(data, element_list)

Removes compounds containing specified elements from the DataFrame.

Parameters:

datapandas DataFrame

The DataFrame containing compounds to be filtered.

element_liststr, optional

File with elements to exclude. Default is ‘remove.list’. The file should contain elements separated by commas. For example, to remove oxygen and nitrogen, write ‘O,N’ in ‘remove.list’.

Returns:

datapandas DataFrame

Processed DataFrame with compounds containing specified elements removed.

htesp.element_extract.data_one_element_compound(elm, ntype, exclude_el, properties, input_data=None)

Extracts information for compounds containing only one element.

Parameters:

elmstr

Element to search for in compounds. For example, ‘B’ for boron.

ntypeint or tuple

Number of unique elements. Can be a single integer or a tuple (e.g., (1, 2) for 2 different types).

exclude_ellist

List of elements to exclude. For example, [‘O’, ‘N’].

propertieslist

List of properties to extract.

Returns:

datapandas DataFrame

DataFrame containing information for compounds with only one element.

htesp.element_extract.data_two_element_compound(el1, el2, ntype, exclude_el, properties, input_data=None)

Extracts information for compounds containing two elements.

Parameters:

el1str

First element to search for in compounds (e.g., ‘B’ for boron).

el2str

Second element to search for in compounds (e.g., ‘C’ for carbon).

ntypeint or tuple

Number of unique elements in compounds. Can be a single integer or a tuple (e.g., (1, 2) for 2 different types).

exclude_ellist

List of elements to exclude. For example, [‘O’, ‘N’].

propertieslist

List of properties to extract.

Returns:

datapandas DataFrame

DataFrame containing information for compounds with two elements.

htesp.element_extract.create_input(input_data=None)

Reads ‘download.csv’ file inside ‘download’ folder and creates ‘input.in’ and ‘mpid-list.in’ files for further downloading and calculations.

htesp.element_extract.extract(ntype, properties, elm, exclude_el, nelm=1, metal=False, neg_fe=False, thermo_stable=False, ordering='NM', nsites=10, spacegroup=None, out='download/download.csv', input_data=None)

Function to extract the data and apply filters, then write ‘download.csv’ file inside ‘download’ folder.

Parameters:

ntypetuple

Number of unique elements in the compound. For example: (1, 3) for 3 different unique elements in compounds.

propertieslist

List of properties to extract.

elmlist

List of elements used in search.

exclude_ellist

List of elements to exclude.

nelmint, optional

Length of list elm. Default is 1.

metalbool, optional

True to download zero bandgap compounds. Default is False.

neg_febool, optional

True to download compounds with negative formation energy. Default is False.

thermo_stablebool, optional

True to download compounds at the convex hull. Default is False.

orderingstr, list or None, optional

Magnetic ordering to keep. Default is ‘NM’. None applies no filter; a list keeps any of its values, e.g. ["NM", "Unknown"] (Materials Project reports "Unknown" whenever no magnetism calculation was run). See filter_ordering().

nsitesint, optional

Maximum number of sites in the compound. Default is 10.

spacegroupint or str, optional

Spacegroup number or name. Default is None.

outstr, optional

Output file to write. Default is ‘download/download.csv’.

Returns:

datapandas DataFrame

Extracted data after applying filters.

htesp.element_extract.download_by_entry(entries, must_include, size_constraint=20, ntype_constraint=5, FE=False, thermo_stable=True, metal=False, magnetic=False, spacegroup=None, properties=None, input_data=None)

Function to extract and create input files using “mp_api.client.MPRester.get_entries_in_chemsys” Function of the materials project API package (pip install mp_api). This mode is turned on when using ‘mode’:’chemsys’ in ‘download.py’ file.

Parameters:

entrieslist

List of elements ==> elements and compounds (combination of elements) to search.

size_constraintint, optional

Size of the compounds (total number of ions). Upper bound not included. Default is 20.

ntype_constraintint, optional

Number of different types of ions. Upper bound not included. Default is 5.

must_includelist

Elements that must be included in the compounds.

FEbool, optional

True if the formation energy is negative. Default is False.

metalbool, optional

True if the compound is a metal. Default is False.

magneticbool, optional

True if the compound has a non-zero magnetic moment. Default is False.

spacegroupint or str, optional

Spacegroup number or name. Default is None.

propertieslist, optional

List of properties to extract.

Returns:

None

htesp.element_extract.main()

Main function to orchestrate the data extraction and input file creation process.

If ‘mpid-list.in’ file does not exist, the function reads settings from ‘config.json’ to create mpid-list.in file.

Parameters:

None

Returns:

None