Welcome to mxene’s documentation!¶

Tools of MXene¶

mxene.core.mxenes.MXene are inherited from Structure from pymatgen, beside the basic functions of Structure, it customizes some specialized functions for MXenes structure.

Name	Application
`mxene.core.mxenes.MXene`	MXene structure object.
`mxene.core.mxenes.MXene.get_similar_layer_atoms()`	Get all same layer atoms by z0 site.
`mxene.core.mxenes.MXene.get_next_layer_sites_xy()`	Obtain the atomic position of the next layer.
`mxene.core.mxenes.MXene.from_standard()`	Generate ideal single atom doping MXenes.
`mxene.core.mxenes.MXene.get_structure_message()`	Obtaining bond and face information
`mxene.core.mxenes.MXene.add_absorb()`	Add adsorbent atoms.
`mxene.core.mxenes.MXene.add_face_random()`	Add atoms at randomly.
`mxene.core.mxenes.MXene.non_equivalent_site()`	Obtain 16 equivalent positions.

Note

The background of MXene refers to Sample Data and Background

The background and data of Structure refer to Background of MXene

Guide¶

Background of MXene¶

MXene¶

MXenes is the general name of two-dimensional transition metal carbides, nitrides or carbonitrides. It is a new type of graphene like two-dimensional structural material jointly discovered by Professor Yury Gogotsi of Drexel University and Professor Michel W. Barsoum in 2011. The general chemical formula can be expressed as \(M_{n+1}X_{n}T_{x}\), where M refers to transition metals (such as Ti, Zr, Hf, V, Nb, Ta, Cr, Sc, etc.), X refers to C or N, n generally 1-3, and T refers to surface groups (such as \(O^{2-}\), \(OH^-\), \(F^-\), etc.). It is mainly obtained by extracting weakly bound A-site elements (such as Al atoms) from the MAX phase through the mixed solution of HF acid or hydrochloric acid and fluoride. Due to the diversity of the composition and structure of the MAX phase, MXene materials derived from it have also become the largest family of two-dimensional materials, with more than 100 theoretically predicted and more than 40 currently synthesized.

Application¶

MXene’s unique two-dimensional layered structure, high density, metalloid conductivity, adjustable surface terminal groups, excellent mechanical properties and pseudo capacitor energy storage mechanism make it a very promising electrochemical energy storage material. It has unique application advantages in many advanced energy storage devices, such as supercapacitors, lithium/sodium/potassium ion batteries, lithium sulfur batteries, water-based zinc ion batteries, etc. Therefore, MXene has become a frontier hotspot in the field of energy materials.

Sample Data and Background¶

Sample data¶

Download data from the following link: Structure List .

Usage:

>>> import pandas as pd
>>> from pymatgen.core import Structure
>>> structures = pd.read_pickle("structures.pkl_pd")
>>> structure = structures[0]

>>> from mxene.core.mxenes import MXene
>>> structure = MXene.from_structure(structure)

Background¶

The Structure from pymatgen is one class to represent the crystal structure data, which contain all message of atoms and their sites. More details link: pymatgen Structure .

The class MXene from mxene is one sub-class Structure . Therefore, besides the same functions and properties of Structure, the MXene has more powerful and specialized function for 2D MXenes materials.

Generation¶

Generate MXene Structural Data¶

The crystal structure data generated by mxene includes three methods:

Usage:

Starting from layered structure, customize structural elements, number of layers, supercell size, etc.

>>> from mxene.core.mxenes import MXene
>>> from pymatgen.io.vasp import Poscar
>>> structures = MXene.from_standard(terminal_site='fcc', terminal="O", base="Ti")

Read and generate from the existing poscar file.
```
>>> structures = MXene.from_file('POSCAR')
```

Read the existing POSCAR and convert it to Structure through pymatgen, and convert it to MXene sequentially.

>>> pos = Poscar.from_file('POSCAR')
>>> st = pos.structure
>>> structures = MXene.from_structure(st)

Note

The 2 and 3 methods are inherited from structure.

VASP input¶

This package can be used to generate VASP inputs easily. The files are “POSCAR”,”INCAR”,”KPOINTS”,”POTCAR”,”pbs.run” .etc.

Examples:

# POSCAR

>>> from mxene.core.mxenes import MXene
>>> from mxene.prepare.vaspinput import MXVaspInput
>>> from pymatgen.io.vasp.inputs import Poscar
>>> structure = MXene.from_standard(terminal_site='fcc', terminal="O", base="Ti")
>>> poscar = Poscar(structure)

# POTCAR

>>> sym_potcar_map = check_potcar(potpath=r"POT-database")
>>> potcar = get_potcar(poscar, sym_potcar_map=sym_potcar_map)

# KPOINTS

>>> from pymatgen.io.vasp import Kpoints
>>> kpoints = Kpoints(kpts=((3, 3, 1),))

# INCAR

>>> from mxene.prepare.conf_files import opt_incar
>>> from pymatgen.io.vasp import Incar
>>> incar = Incar.from_string(opt_incar)

# run file (depend on your machine.)

>>> from pymatgen.io.vasp import Incar
>>> run_f = """#PBS -S /bin/bash
... #PBS -N vasp
... #PBS -l nodes=1:ppn=12
... #PBS -l walltime=120:00:00
... #PBS -q master
... source /opt/intel/oneapi/mkl/latest/env/vars.sh intel64
... source /opt/intel/oneapi/compiler/latest/env/vars.sh intel64
... source /opt/intel/oneapi/mpi/2021.4.0/env/vars.sh intel64
... export PATH=/opt/software/vasp.5.4.4/bin:$PATH
... cd ${PBS_O_WORKDIR}
... mpirun -np 40 vasp_std"""
>>> incar = Incar.from_string(opt_incar)

# ALL

>>> mxinput = MXVaspInput(incar, kpoints, poscar, potcar, optional_files=None, **kwargs)
>>> mxinput.write_input(output_dir=".",make_dir_if_not_present=True)

Dop and Add¶

Dop or add can effectively change the electronic structure of MXenes based materials, which is an effective strategy to control the properties of materials themselves. mxene provides this way to create crystal structures:

Method 1:

>>> from pymatgen.io.vasp import Poscar
>>> structures = MXene.from_standard(terminal_site='fcc', terminal="O", base="Ti", doping="Mo", add_atoms='Fe', add_atoms_site=(0.24, 0.82, 0.64), coords_are_cartesian=False)

Method 2:

In addition to the above method, you can also read the existing POSCAR and convert it into Structure through pymatgen, and then successively dop or add to form a new POSCAR:

>>> from pymatgen.io.vasp import Poscar
>>> pos = Poscar.from_file('POSCAR')
>>> st = pos.structure
>>> st.replace(44, "Mo")

>>> st.append("Fe", [0.24, 0.82, 0.64])
>>> st.insert(45, "Fe", [0.24, 0.82, 0.64])

Absorb¶

In the fields of catalysis and battery materials, various adsorbents are often designed, and various adsorption models need to be built. mxene provides this tool:

There are three common adsorption sites: top, bridge and hollow. You can use the tools in mxene to define the location and type of adsorption atoms.

>>> from mxene.core.mxenes import MXene
>>> from pymatgen.io.vasp import Poscar
>>> pos = MXene.from_file('POSCAR')
>>> pos.add_absorb(site_type= "top", absorb= "H")

mxene also provides a tool for batch generation of randomly adsorbed atomic crystal structures on material surfaces, which may be conveniently used in the calculation of isoenergetic surface.

>>> from mxene.core.mxenes import MXene
>>> from pymatgen.io.vasp import Poscar
>>> pos = MXene.from_file('POSCAR')
>>> structures = pos.add_face_random(number=10, random_xy=True, add_atom="H", up_down="up", offset_z=1.0)
>>> print(structures[0])
>>> structures[0].show()

At the same time, mxene also supports layered adsorption.

_images/layer_absorb.png — which is often used in the calculation of battery materials.¶

>>> from mxene.core.mxenes import MXene >>> from pymatgen.io.vasp import Poscar >>> pos = MXene.from_file('POSCAR') >>> pos.add_atom_layer(site_type="fcc",site_atom="Ag",up_down="up_and_down")

which is often used in the calculation of battery materials.

>>> from mxene.core.mxenes import MXene >>> from pymatgen.io.vasp import Poscar >>> pos = MXene.from_file('POSCAR') >>> pos.add_atom_layer(site_type="fcc",site_atom="Ag",up_down="up_and_down")

which is often used in the calculation of battery materials.

>>> from mxene.core.mxenes import MXene
>>> from pymatgen.io.vasp import Poscar
>>> pos = MXene.from_file('POSCAR')
>>> pos.add_next_layer_atoms(site_type="fcc",site_atom="Ag",up_down="up_and_down")

Examples¶

Batch generation of VASP calculation files¶

>>> from mxene.core.mxenes import MXene
>>> from pymatgen.io.vasp import Poscar, Kpoints, Incar
>>> from mxene.prepare.conf_files import opt_incar
>>> from mxene.prepare import pre_potcar
>>> from mxene.prepare.vaspinput import MXVaspInput
>>>
>>> kpoints = Kpoints(kpts=((3, 3, 1),))
>>> incar = Incar.from_string(opt_incar)
>>> pos = MXene.from_file('POSCAR')
>>>
>>> for i in ["Mo", "Sc", "Ag"]:
>>>     pos.replace(44, i)
>>>     poscar = Poscar(pos)
>>>     sym_potcar_map = pre_potcar.check_potcar(potpath=r"POT-database")
>>>     potcar = pre_potcar.get_potcar(poscar, sym_potcar_map=sym_potcar_map)
>>>     mxinput = MXVaspInput(incar, kpoints, poscar, potcar, optional_files=None)
>>>     mxinput.write_input(output_dir='mxene_data' + '\\' + i, make_dir_if_not_present=True)

Contact¶

The package is during test development. Thanks for any bug or advise.

1787364072@qq.com Mei Yang

986798607@qq.com Changxin Wang

mxene¶

mxene package¶

Subpackages¶

mxene.apply package¶

Submodules¶

mxene.apply.infect module¶

mxene.cli package¶

mxene.core package¶

Submodules¶

mxene.core.functions module¶

mxene.core.functions2 module¶

mxene.core.mxenes module¶

mxene.extract package¶

Submodules¶

mxene.extract.structure_extractor module¶

mxene.monitor package¶

Submodules¶

mxene.monitor.jobmanagement module¶

mxene.organize package¶

Submodules¶

mxene.organize.disk module¶

mxene.organize.disk.make_disk(disk, terminal, base, carbide_nitride, n_base, doping, site_name, absorb=None, equ_name=None, add_atoms=None, base_num_cls=None, super_cell=None, terminal_site=None, ts_name='all', old_type=True) → Path¶: Organize the name to one path.

mxene.organize.grid module¶

mxene.organize.mx_org module¶

** This script is used to reorganize the MXenes folder **

This code can be used as a script alone, need to install python3, if you need to obtain the recommended path, need to install pymatgen,ase,mxene and other packages.
This code does not change the file content, but only adjusts the directory (pay attention to the data backup first, ensure that everything is correct, and then delete the original folder).
If the code fails to pass after analysis, add the un_mark.txt file to the path to output the necessary information.
If both the optimization structure folder and the static computing folder exist, only the static computing (not added, under development) is saved by default.
After sorting out the data, the data cannot appear in the same folder, that is, the calculation file and the sub-folder, (except for auxiliary files).
All un-calculated or un_mark data is not recommended to be uploaded to the database.
This script can be distributed freely and can be used freely. The version in the mxene package is the source version. If you need to change the source version of any bug or important content, please Contact me.

The final unified folder format.

** (1) does not adsorb **

MXenes -> Basal number classification -> Base name -> Load content -> Dopant -> pure/pure_static

Examples

MXenes -> M2C -> Ti2NO2 -> no_add -> no_doping -> pure/pure_static

MXenes -> M2N -> Ti2NO2 -> no_add -> Mo -> pure/pure_static

Examples (New):

MXenes -> M2C -> Ti2NO2 -> no_add -> no_doping -> no_absorb -> fcc(O-site) -> pure/pure_static

** (2) adsorption **

MXenes -> Basal number classification -> Base name -> Load content -> Dopant -> Adsorb -> site -> label

Examples

MXenes -> M2N -> Ti2NO2 -> no_add -> no_dopin -> H/add_H -> top -> opt

MXenes -> M3N2 -> TiNCrNTi-O2 -> Hf -> C -> Li -> S0 -> opt

** (3)NEB **

MXenes -> Basal number classification -> Base name -> Load content -> Dopant -> Adsorb -> Equivalent site -> Path name

Examples

MXenes -> M2N -> Ti2NO2 -> no_add -> no_doping -> H -> S0-S1 -> 00/01/01/03/04/ini/fin/…

‘->’ represents the ‘next level’. ‘/’ means ‘or’.

mxene.organize.mx_org.check_convergence(pt: Union[str, Path, PathLike, Path], msg=None)¶

Check final energy. Check the structure for convergence.

Parameters:

pt – (str, path.Path, os.PathLike,pathlib.Path), path
msg – (list of str), message.

Returns:

(tuple), bool and msg list

Return type:

res

mxene.organize.mx_org.check_mx_data(pt, ck_pt=True, ck_conver=True, ck_st=True, get_rcmd_pt=True, check_vasp=True, out_file='un_mark.txt')¶

Check MXene data in total.

Parameters:

pt – pt: (str, path.Path, os.PathLike,pathlib.Path), path.
ck_pt – (bool), check path.
ck_conver – (bool),check convergence.
ck_st – (bool), check structure.
get_rcmd_pt – (bool), check recommend path.
out_file – (str), out file name.
check_vasp – (bool), vasprun.xml.

mxene.organize.mx_org.check_pt(pt: Union[str, Path, PathLike, Path], msg=None)¶

Check the path is in standard.

Parameters:

msg – (list), message.
pt – (str, path.Path, os.PathLike,pathlib.Path), path of leaf node.

Returns:

(tuple), bool and msg list.

Return type:

res

mxene.organize.mx_org.check_structure_contcar(pt: Union[str, Path, PathLike, Path], msg=None)¶

Check that the POSCAR, CONTCAR constructs correspond.

Parameters:

pt – (str, path.Path, os.PathLike,pathlib.Path), path
msg – (list of str), message.

Returns:

(tuple), bool and msg list

Return type:

res

mxene.organize.mx_org.check_vasprun(pt: Union[str, Path, PathLike, Path], msg=None)¶

Check final energy with vasprun.xml.

Parameters:

pt – (str, path.Path, os.PathLike,pathlib.Path), path
msg – (list of str), message.

Returns:

(tuple), bool and msg list

Return type:

res

mxene.organize.mx_org.comparison(pt)¶: print if path is not standard.

mxene.organize.mx_org.copy_disk(old_pt: Union[str, Path], new_pt: Union[str, Path], file=True, disk=False, cover=False, remove=False)¶

Copy files,disks of old path to new path. Copy the subfiles in the old path and the sub-folders in the new path.

Parameters:

old_pt – (str, path.Path, os.PathLike,pathlib.Path), old path
new_pt – (str, path.Path, os.PathLike,pathlib.Path), new path
file – (bool), copy file.
disk – (bool), copy sub-disk.
cover – (bool), cover the exist data.
remove – (bool), remove the old path.

mxene.organize.mx_org.get_recommend_path(pt: Union[str, Path, PathLike, Path], **kwargs)¶

Get recommend path.

Based on the structure, get the recommended path (not necessarily correct, need to check).

The mxene package is required:

pip install mxene

Parameters:

pt – (str, path.Path, os.PathLike,pathlib.Path), path
msg – (list of str), message.

Returns:

(tuple), bool and msg list

Return type:

res

mxene.organize.mx_org.path_regroup(pt: Union[str, Path, PathLike, Path], base_name: Union[tuple, int, None, str] = 1, add: Union[tuple, int, None, str] = 2, doping: Union[tuple, int, None, str] = 3, absorb: Union[tuple, int, None, str] = 4, site: Union[tuple, int, None, str] = 5, label: Union[tuple, int, None, str] = 6, base_num_class: Union[tuple, int, None, str] = None, prefix=None, **kwargs) → Path¶

Re-group the disk.

重新组织文件夹,使用序号标记文件层，使得最终为:

MXenes -> 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 MXenes -> 基底层数分类 -> 基底名称 -> 负载物 -> 搀杂物 -> 吸附物/pure_* -> 等效位点/路径 -> 标签例如： MXenes -> base_num_class -> base_name -> add -> doping -> absorb -> site -> label MXenes -> base_num_class -> base_name -> add -> doping -> pure

1.若输入序号n,则代表使用旧文件夹的第n层作为名称. 2.若输入None,则代表跳过,将使用（掺杂no_doping，负载no_add，吸附no_absorb）. 3.若输入字符串,则该层直接使用该名称.

Examples:

>>> path_regroup(pt=r"E:/x/MXenes/M2C/M2XO2-TM/Hf/C/Au/2",
...             base_name=1, add=2,doping=3,absorb=4,site=5,label="00")

>>> path_regroup(pt=r"E:/x/MXenes/M2XO2-TM/Hf/C/Au/2",base_num_class="M2C",
...             base_name=0, add=1,doping=2,absorb=3,site=4,label="00")

Parameters:

pt – (str, path.Path, os.PathLike,pathlib.Path), path of leaf node.
base_name – (tuple,int,None,str), layer of base structure name.
add – (tuple,int,None,str), layer of add atom.
doping – (tuple,int,None,str), layer of doping atom.
absorb – (tuple,int,None,str), layer of absorb atom.
site – (tuple,int,None,str), layer of site name.
label – (tuple,int,None,str), layer of label name.
base_num_class – (tuple,int,None,str), label of MXenes system.
prefix – (str,None), Move to other path.
**kwargs – keywords are formed “func_*”, such as “fun_base_name”, and the value are one function.

Returns:

(path.Path), new path

Return type:

new_pt

mxene.prepare package¶

Submodules¶

mxene.prepare.conf_files module¶

This file is used to generated vasp input file (INCAR, run script) Custom modifications are recommended.

mxene.prepare.conf_files.cmd_sys(cmds)¶

mxene.prepare.conf_files.write_batch()¶

mxene.prepare.pre_kpoints module¶

mxene.prepare.pre_potcar module¶

############## Usage 1 ###################

sym_potcar_map = check_potcar(potpath=r”POT-database”) potcar = get_potcar(poscar, sym_potcar_map=sym_potcar_map)

############## Usage 2 (Avoid repeated calls) ###################

sym_potcar_map = check_potcar(potpath=r”POT-database”)

@functools.lru_cache(200) def get_potcar_lru(sym):

return Potcar(sym, sym_potcar_map=sym_potcar_map)

potcar = get_potcar_lru(tuple(poscar.site_symbols))

mxene.prepare.pre_potcar.check_potcar(potpath)¶: Check and get the potcar file. The potcar file name should start from element such as ‘Ag-POSCAR’,’Ag’,’Ag_sl’.

mxene.prepare.pre_potcar.get_potcar(poscar: Union[Poscar, Structure], sym_potcar_map: dict)¶: Read from sym_potcar_map according poscar message.

mxene.prepare.vaspinput module¶

class mxene.prepare.vaspinput.MXVaspInput(incar, kpoints, poscar, potcar, optional_files=None, **kwargs)¶

Bases: VaspInput

Class to contain a set of vasp input objects corresponding to a run.

Parameters:

incar – Incar object.
kpoints – Kpoints object.
poscar – Poscar object.
potcar – Potcar object.
optional_files – Other input files supplied as a dict of { filename: object}. The object should follow standard pymatgen conventions in implementing as_dict() and from_dict method.

static from_directory(input_dir, optional_files=None, structure_file='CONTCAR')¶

Read in a set of VASP input from a directory. Note that only the standard INCAR, POSCAR, POTCAR and KPOINTS files are read unless optional_filenames is specified.

Parameters:

input_dir (str) – Directory to read VASP input from.
optional_files (dict) – Optional files to read in as well as a dict of {filename: Object type}. Object type must have a static method from_file.

write_input(output_dir='auto', make_dir_if_not_present=True)¶

Write VASP inputs to a directory.

Parameters:

output_dir (str) – Directory to write to. Defaults to current directory (“.”).
make_dir_if_not_present (bool) – Create the directory if not present. Defaults to True.

mxene.utility package¶

Submodules¶

mxene.utility.typing module¶

This software mxene is one toolkit for MXene material generation, calculation and analysis.

mxene mainly includes some tools for batch generation of MXene structures and crystal structure feature extraction, aiming to achieve data mining in universities. In addition, mxene can also be used to check the rationality of vasp calculation process and results.

Using this software, you could:

Generate initial various kinds MXene structure and relevant VASP input.
Monitor VASP calculation processing.
Organize MXene data.
Extract structure features from crystal structure.

Install:

pip install mxene

Install configuration:

Before first using, we recommend using the following methods to generate the configuration file.

>>> from mxene.conf_files import write_batch
>>> write_batch()

Welcome to mxene’s documentation!¶

Tools of MXene¶

Guide¶

Background of MXene¶

MXene¶

Application¶

Sample Data and Background¶

Sample data¶

Background¶

Generation¶

Generate MXene Structural Data¶

VASP input¶

Dop and Add¶

Absorb¶

Examples¶

Batch generation of VASP calculation files¶

Contact¶

mxene¶

mxene package¶

Subpackages¶

mxene.apply package¶

Submodules¶

mxene.apply.infect module¶

mxene.cli package¶

mxene.core package¶

Submodules¶

mxene.core.functions module¶

mxene.core.functions2 module¶

mxene.core.mxenes module¶

mxene.extract package¶

Submodules¶

mxene.extract.structure_extractor module¶

mxene.monitor package¶

Submodules¶

mxene.monitor.jobmanagement module¶

mxene.organize package¶

Submodules¶

mxene.organize.disk module¶

mxene.organize.grid module¶

mxene.organize.mx_org module¶

mxene.prepare package¶

Submodules¶

mxene.prepare.conf_files module¶

mxene.prepare.pre_kpoints module¶

mxene.prepare.pre_potcar module¶

mxene.prepare.vaspinput module¶

mxene.utility package¶

Submodules¶

mxene.utility.typing module¶

Indices and tables¶