Metadata-Version: 2.4
Name: matmelt
Version: 0.2.0
Summary: Melt elements into crystals — automated structure generation, screening, and calculation, from your laptop to remote compute.
License: MIT
License-File: LICENSE
Keywords: cli,high-throughput,materials-science,matmelt,screening,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: compute
Requires-Dist: mace-torch; extra == 'compute'
Requires-Dist: pyxtal; extra == 'compute'
Requires-Dist: smact; extra == 'compute'
Provides-Extra: dev
Requires-Dist: mypy<2.4,>=1.10; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# MatMelt

**Melt elements into crystals — automated structure generation, screening, and calculation, from your laptop to remote compute.**

[![CI](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-22C55E)](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/LICENSE)

</div>

---

You write one YAML file saying **what** to explore and **where** each stage runs, then run
one command. State is durable — interrupt a run at any point and running it again picks up
where it stopped. No server, no database to install, nothing on anyone else's machines.

```text
compose  →  structure  →  screen    →  [calculate]      →  extract
SMACT       PyXtal        MACE/ASE     DFTB+, optional     record.json
```

| Stage | What it produces | Science it uses |
|---|---|---|
| `compose` | charge-balanced compositions from your element set | SMACT |
| `structure` | candidate crystals — 3D / 2D / 1D symmetry families | PyXtal |
| `screen` | ML relaxation and a convergence/sanity verdict | MACE |
| `calculate` *(optional)* | DFTB+ energies with self-healing retries | your own AiiDA |
| `extract` | one OPTIMADE-shaped `record.json` per material | — |

## Install

```bash
pip install matmelt
```

> Not on PyPI until the `v0.2.0` tag. Until then:
> `pip install git+https://github.com/Quantum-ARISE-Acad/qa-materials-cli.git`

The base install is deliberately light — it never pulls in torch or a science stack.

## Use it

```bash
matmelt init                       # scaffold matmelt.yaml + check the environment
$EDITOR matmelt.yaml               # your elements, your machines
matmelt doctor                     # deps present? machines reachable? fixes named
matmelt run                        # seed and drain the funnel  (Ctrl-C is safe)
matmelt results --export db.json   # your records, one JSON array
```

`matmelt --help` lists the rest (`status`, `monitor`, `retry`, `cif`, `update`), and
`matmelt <command> --help` documents every flag. Exit codes: **0** success ·
**1** problems found · **2** config error.

## The config

```yaml
run:
  name: my-first-run
  work_dir: ./materials-work
  elements: [Na, Cl, O]          # what to explore

backends:                        # the WHERE — machines that run jobs
  laptop:
    kind: local
    options: { max_parallel: 2 }
  gpu_box:
    kind: ssh_exec
    options: { host: you@gpu-box.lan, max_parallel: 4 }

stages:                          # the WHAT — each stage picks a backend
  compose:   { backend: laptop }
  structure: { backend: laptop }
  screen:    { backend: gpu_box }
  extract:   { backend: laptop }
```

Moving a heavy stage to a bigger machine is that one line, never code. Any value may be an
environment reference (`env:NAME`), so secrets never live in the file.

## The science stack is yours

MatMelt does not bundle SMACT, PyXtal, MACE/torch, ASE, AiiDA or any ML model, and never
installs them behind your back. `doctor` and every run report what is missing and on which
machine, naming the exact fix, before any calculation starts.
`pip install matmelt[compute]` is a convenience alias for `smact` + `pyxtal` +
`mace-torch` — an alias, never a requirement.

<!-- ## More

[`guide.md`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/guide.md) — every command, every flag, the full config reference ·
[`docs/`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/tree/main/docs) — the documentation site, 61 pages ·
[`CHANGELOG.md`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/CHANGELOG.md) — including how to move over from `materials-cli` ·
[`CONTRIBUTING.md`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/CONTRIBUTING.md) ·
[`CITATION.cff`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/CITATION.cff) — how to cite it -->

MIT licensed — see [`LICENSE`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/LICENSE).
