Metadata-Version: 2.4
Name: mcta
Version: 0.0.1
Summary: Meta Crystal Toolkit Analysis (mcta): band structure, DOS or phonon band structure plot from VASP, vaspkit or phonopy results (mt.bandplot / mt.pbandplot / mt.ph); crystal structure retrieval from the Materials Project (mt.seeker); bash script runner (mt.sh).
Author: Kan
License-Expression: MIT
Project-URL: Homepage, https://github.com/lkccrr/mc
Keywords: DFT,VASP,DOS,band,plot,Phonon,materials-project,pymatgen,crystal-structure,SQS
Platform: Unix
Platform: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: ase>=3.22.0
Provides-Extra: seeker
Requires-Dist: pymatgen>=2024.1.1; extra == "seeker"
Requires-Dist: mp-api>=0.40; extra == "seeker"
Requires-Dist: scikit-learn>=1.3; extra == "seeker"
Requires-Dist: joblib>=1.3; extra == "seeker"
Provides-Extra: llm
Requires-Dist: openai>=1.30; extra == "llm"
Provides-Extra: sqs
Requires-Dist: sqsgenerator>=0.5; extra == "sqs"
Dynamic: license-file

[![mcta](https://img.shields.io/pypi/v/mcta?style=flat-square)](https://pypi.org/project/mcta/)
[![mcta](https://img.shields.io/pypi/pyversions/mcta?style=flat-square)](https://pypi.org/project/mcta/)
[![mcta](https://img.shields.io/pypi/l/mcta?style=flat-square)](https://pypi.org/project/mcta/)
[![mcta](https://img.shields.io/pypi/dm/mcta?style=flat-square)](https://pypi.org/project/mcta/)
[![mcta](https://img.shields.io/pypi/wheel/mcta?style=flat-square)](https://pypi.org/project/mcta/)
[![mcta](https://img.shields.io/github/last-commit/lkccrr/mcta?style=flat-square)](https://github.com/lkccrr/mcta)
[![mcta](https://img.shields.io/github/release-date/lkccrr/mcta?style=flat-square)](https://github.com/lkccrr/mcta)

### mcta — Meta Crystal Toolkit & Analysis

<b style="color:green;"><i>mcta</b></i> (**Meta Crystal Toolkit & Analysis**) tools package

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

* Install (Python &ge; 3.9; core dependencies: `numpy`, `matplotlib`, `ase`):
```bash
pip install mcta              # plotting tools only
pip install "mcta[seeker]"    # + mt.seeker (pymatgen, mp-api, scikit-learn, joblib)
pip install "mcta[seeker,llm,sqs]"   # + LLM mode (openai) and SQS (sqsgenerator)
```
***
<b style="color:blue;"><i>mt.bandplot</b></i> — 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.
```bash
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
```

| File | Used for |
|---|---|
| `vasprun.xml` | eigenvalues, k-points, occupations, Fermi level, structure (parsed by ASE, preferred) |
| `EIGENVAL` | eigenvalues, k-points (needed for bands / masses without `vasprun.xml`) |
| `PROCAR` / `DOSCAR` | projected bands / DOS (`LORBIT = 11`) |
| `OUTCAR` | `E-fermi` fallback, `ISPIN`, element names |
| `KPOINTS` / `KLABELS` | high-symmetry labels |
| `POSCAR` / `CONTCAR` | lattice and formula legend |
***
<b style="color:blue;"><i>mt.pbandplot</i></b> — phonon band / DOS plotting
```bash
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
```
***
<b style="color:blue;"><i>mt.ph</b></i> — phonopy workflow helper
* `mt.ph -b -d` writes <b style="color:darkred;"><i>band.conf</i></b> + <b style="color:darkred;"><i>mesh.conf</i></b> (names via `-B` / `-D`). Without `-b`/`-d` it walks the phonopy steps one by one (supercell &rarr; force constants &rarr; band &rarr; 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` &rarr; `CONTCAR` &rarr; `POSCAR`), or give `-c FILE`.
* By default the <b style="color:blue;">phonopy v4+</b> 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.
```bash
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
```

| Option | Meaning | Default |
|---|---|---|
| `-c FILE` | unit cell file | auto-detected |
| `-s N [N ...]` | supercell `DIM`, 1-3 integers (`2x2x1`, `(2,2,1)` also accepted) | `1 1 1` |
| `-r [FILE]` | forces source; alone runs `fc`; with `-n` the forces file name inside each directory | `vasprun.xml` |
| `-n NAME [NAME ...]` | directories / `vasprun.xml` suffixes / ranges for the `f` step | &mdash; |
| `-b` / `-d` | write `band.conf` / `mesh.conf` only | &mdash; |
| `-B` / `-D` | names written by `-b` / `-d` | `band.conf` / `mesh.conf` |
| `--band` / `--labels` / `--points` / `--mp` | `BAND` path, labels, points, mesh used with `-b` / `-d` | built-in, `20 20 20` |
| `-O` / `-Y` / `-y` | legacy v3 commands / run without asking / print only | &mdash; |
***
<b style="color:blue;"><i>mt.seeker</b></i> — Materials Project retrieval, curation and SQS

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; a custom unit cell can be expanded into special quasirandom structures (SQS). No calculations are executed locally.

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

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

Typical usage:

```bash
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
mt.seeker -M                                         # ML analysis: random forest on manifests,
                                                     #   predicts ehull / band gap -> <home>/ml/

# SQS from a custom cell (needs mcta[sqs]; no network, no key)
mt.seeker -S cell.vasp -a "Cu:0.5,Au:0.5" -x 4,4,4 -n cuau-sqs
mt.seeker -S LaAlO3.cif --sqs-host La -a "La:0.5,Sr:0.5" -x 2,2,2   # A-site only
```

Each bundle lands in `exports/<name>/` (`structures/<id>/`, `manifest.csv` with 14 columns, `README.md`, `results/`) plus `exports/<name>.tar.gz`; SQS bundles additionally contain `sqs.json` and `sqs_summary.csv`. 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 `MCSEEKER_*` environment variables are documented there and in the code (`mcta/seeker/config.py`).
***
<b style="color:blue;"><i>mt.sh</b></i> — 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) &rarr; directories listed in `$MTSH_SCRIPTS` (colon/semicolon-separated) &rarr; 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. `python -m mcta.sh` works as well.
* 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).
