mcta 0.0.2

Meta Crystal Toolkit & Analysis (mcta)

• Install (Python ≥ 3.9; core dependencies: numpy, matplotlib, ase):

pip install mcta                          # plotting tools only
pip install "mcta[seeker]"                # + mt.seeker (pymatgen, mp-api, scikit-learn, joblib)
pip install "mcta[skl]"                   # + mt.skl (scikit-learn, joblib)
pip install "mcta[seeker,llm,sqs]"        # + LLM mode (openai) and SQS (sqsgenerator)
pip install "mcta[all]"                   # all : seeker + skl + llm + sqs

mt prints an overview, checks the current directory and suggests the next command.

mt.bandplot — VASP output is the default data source, vaspkit is optional

• -i takes a directory (default: current). VASP output (EIGENVAL / DOSCAR / PROCAR) is preferred, otherwise BAND.dat / PBAND*.dat / PDOS*.dat are used.
• -i alone plots bands, -d alone the DOS, -i -d both side by side; -r -p Mo-d adds projected bands (needs PROCAR, LORBIT = 11); -D -d spin-polarized mirror plot (--no-mirror to keep both positive); -m effective masses from EIGENVAL; two or three directories compare calculations.
• Energies are shifted to the Fermi level (--no-shift keeps raw values); k-path labels come from KPOINTS/KLABELS or are computed automatically; --export-dat DIR dumps vaspkit-style .dat files.

mt.bandplot                               # bands of the current directory
mt.bandplot -i calc_PBE -l g m k g        # given directory, VASP or .dat auto-detected
mt.bandplot -i calc_PBE -d -z             # bands + DOS (DOSCAR or PDOS*.dat)
mt.bandplot -i calc_PBE -r -p Mo-d        # projected bands from PROCAR
mt.bandplot -i calc_PBE -D -d             # spin polarized: up/down panels + mirror DOS
mt.bandplot -i calc_PBE -m 0.15           # effective masses from EIGENVAL
mt.bandplot -i calc_PBE calc_HSE          # compare calculations
mt.bandplot -i BAND.dat -d PDOS*.dat      # vaspkit .dat route

mt.pbandplot — phonon band / DOS plotting

mt.pbandplot -h                                                    # all parameters
mt.pbandplot -i BAND.dat -o BAND.png -l g m k g -d projected_dos.dat -z
mt.pbandplot -B 23 100 -l g m k g -y -2 110                        # broken axis
mt.pbandplot -i BAND1.dat BAND2.dat -B 20 100                      # several files

mt.ph — phonopy workflow helper

• mt.ph -b -d writes band.conf + mesh.conf (names via -B / -D). Without -b/-d it walks the phonopy steps one by one (supercell → force constants → band → DOS), printing and confirming each command; -Y runs without asking, -y only prints. B + Enter goes back one level, Q + Enter quits.
• The unit cell file is auto-detected (POSCAR-unitcell → CONTCAR → POSCAR), or give -c FILE.
• By default the phonopy v4+ commands are used (phonopy-init for setup steps, phonopy_params.yaml for band/DOS); add -O to use the legacy (v3) forms instead.
• -n values (for the force-extraction step, implied by -n alone) may be directories, vasprun.xml suffixes or brace ranges; dir-{001..003} stays compact and bash expands it.

mt.ph                                           # supercell step (default; -s 2 2 1 sets DIM)
mt.ph -b -d --band "0 0 0 0.5 0 0 0.5 0.5 0.5 0 0 0" --labels "G X M G"
mt.ph supercell -s 2 2 1 -c POSCAR-unitcell     # explicit supercell
mt.ph -r                                        # force constants from ./vasprun.xml
mt.ph -n 001-003                                # extract forces -> phonopy-init -f vasprun.xml-{001..003}
mt.ph band                                      # band.conf -> band.yaml -> BAND.dat
mt.ph dos --total                               # mesh.conf -> projected_dos.dat (+ total_dos.dat)
mt.ph -O -y supercell -s 2 2 1                  # preview the legacy v3 command only

mt.seeker — Materials Project retrieval and curation

Retrieves crystal structures from the Materials Project, writes CIF / POSCAR / JSON and packs them into bundles ready for scp to a server (with optional INCAR / KPOINTS / slurm templates). Local structures can be filtered, deduplicated and re-exported. No calculations are executed locally. Special quasirandom structures (SQS) from a custom unit cell is handled by the separate mt.sqs tool.

Set the API key once (free account at https://next-gen.materialsproject.org):

mkdir -p ~/.config/mcta
echo 'MP_API_KEY=your-key' >> ~/.config/mcta/config
chmod 600 ~/.config/mcta/config
# or: export MP_API_KEY=... (lookup order: env -> $MT_SEEKER_CONFIG -> the file above -> ./mcseeker.conf)

Typical usage:

mt.seeker --offline                                  # offline self-check, no key needed
mt.seeker -c Ti-C -k 3 -n ti-c                       # search by chemsys, export top 3
mt.seeker -f MoS2 -k 5 -F cif,poscar                 # search by formula
mt.seeker -I mp-149 mp-2658                          # or give mp_ids directly
mt.seeker -c Cr-I -k 2 --job-template                # + INCAR/KPOINTS/slurm templates
mt.seeker -t "find 2D candidates in Cr-I" -p deepseek  # natural language (needs mcta[llm])
mt.seeker -L                                         # list previous bundles

# local curation (dedup, filter, diversity, top-up)
mt.seeker -d                                         # dataset summary
mt.seeker -w "ehull<=0.05 and is_2d and has('Mn')"   # rule filter (-y previews only)
mt.seeker -r -D 8 -o my-pick                         # dedup + pick 8 most dissimilar
mt.seeker -T 5 -c Mn-P-S                             # download 5 more structures

Each bundle lands in exports/<name>/ (structures/<id>/, manifest.csv with 14 columns, README.md, results/) plus exports/<name>.tar.gz. Upload with scp exports/<name>.tar.gz user@server:~/calc/.

Short options are case-sensitive: -t task vs -T top-up, -r dedup vs -R refresh. mt.seeker -h prints the full option list; LLM engines (-p openai/deepseek/qwen/glm/kimi/siliconflow/gemini/openrouter/ollama/vllm, any OpenAI-compatible endpoint) and all MT_SEEKER_* environment variables are documented there and in the code (mcta/seeker/config.py).

mt.sqs — special quasirandom structures from a custom unit cell

mt.sqs reads a POSCAR / CONTCAR / CIF / JSON, expands it to a supercell, and randomises a single sublattice into a quasirandom solid solution with a specified target composition (objective: weighted sum of pair-correlation deviations, smaller = closer to perfect randomness). The engine is sqsgenerator (C++ + Python), no network access required.

mt.sqs -c cell.vasp -a "Cu:0.5,Au:0.5" -x 4,4,4 -n cuau-sqs
mt.sqs -c LaAlO3.cif --host La -a "La:0.5,Sr:0.5" -x 2,2,2     # A-site only
mt.sqs -c cell.vasp -a Cu,Au --iterations 1000 --number 5 -y   # dry-run: no disk write

SQS bundles additionally contain sqs.json and sqs_summary.csv. mt.sqs -h lists every flag and default. The algorithm lives in mcta.seeker.sqs; the rest of mt.seeker no longer pulls in sqsgenerator.

mt.sh — run bash helper scripts by short name

• mt.sh NAME [args...] executes script NAME with bash and forwards the arguments unchanged, e.g. mt.sh xy POSCAR runs xy.sh POSCAR. The exit code of the script is returned.
• Script lookup order: the current directory (./NAME.sh, local overrides first) → directories listed in $MTSH_SCRIPTS (colon/semicolon-separated) → the scripts bundled with the package (mcta/sh/scripts/).
• Bare mt.sh (or mt.sh -l) lists every script found with its source path and a one-line description taken from the first comment line.
• Bundled scripts (VASP workflow helpers, best run on Linux/WSL; Windows needs Git Bash on PATH and the scripts use sed/awk/bc):

Citation

Structure data comes from the Materials Project: A. Jain et al., APL Materials 1, 011002 (2013).