Metadata-Version: 2.4
Name: materials-cli
Version: 0.1.1
Summary: Config-driven CLI that runs a multi-stage materials-discovery funnel on your own machines.
Project-URL: Homepage, https://github.com/Quantum-ARISE-Acad/qa-materials-cli
Project-URL: Repository, https://github.com/Quantum-ARISE-Acad/qa-materials-cli
Project-URL: Documentation, https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/guide.md
Project-URL: Changelog, https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Quantum-ARISE-Acad/qa-materials-cli/issues
Author: Quantum ARISE, AMUZUGA Komi Djidoula Wisdom Sitou, LABBAH Elie
Author-email: AMUZUGA Komi Djidoula Wisdom Sitou <sitouamu510@gmail.com>
Maintainer: AMUZUGA Komi Djidoula Wisdom Sitou, LABBAH Elie
Maintainer-email: AMUZUGA Komi Djidoula Wisdom Sitou <sitouamu510@gmail.com>
License: MIT
License-File: LICENSE
Keywords: cli,high-throughput,materials-science,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">

# materials-cli

**A config-driven funnel for high-throughput materials discovery — on your own machines.**

[![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)
[![Code style](https://img.shields.io/badge/lint-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
[![Typed](https://img.shields.io/badge/mypy-strict-2A6DB0)](https://mypy-lang.org/)

</div>

---

You write one YAML file saying **what** to explore and **where** each stage runs.
You run one command.

```bash
materials-cli run
```

```mermaid
flowchart LR
    A(compose) --> B(structure) --> C(screen) --> D(["calculate<br/><i>optional</i>"]) --> E(extract)

    classDef s fill:#1E3A5F,stroke:#38BDF8,stroke-width:1px,color:#E0F2FE
    classDef o fill:#3B2F63,stroke:#A78BFA,stroke-width:1px,color:#EDE9FE,stroke-dasharray:4 3
    class A,B,C,E s
    class D o
```

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

Every stage runs on your local CPU/GPU or on a machine you own over SSH (optionally through
SLURM). State lives in SQLite, results in plain files — no server, no database to install,
nothing on anyone else's infrastructure. Interrupt a run at any point; running it again
picks up exactly where it stopped.

## Install

```bash
pip install materials-cli
```

Or get a self-contained install (its own venv under `~/.local/share/materials-cli`, a
launcher on your `PATH`, upgradeable later with `materials-cli update`):

```bash
curl -fsSL https://raw.githubusercontent.com/Quantum-ARISE-Acad/qa-materials-cli/main/install.sh | bash
```

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

## Quickstart

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

Every command reads `materials-cli.yaml` from the current directory (or `--config PATH`)
and accepts `--json` for machine-readable output.
Exit codes: **0** success · **1** problems found · **2** config error.

## Configure

The scaffold from `init` is a working config; this is its shape:

```yaml
run:
  work_dir: ./materials-work
  elements: [Na, Cl, O]          # what to explore
  # combination_sizes: [2, 3]    # binaries, ternaries, ... (omit = all sizes)

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 }
```

Any string may be an environment reference (`env:NAME`) — secrets never live in the file.
Adding an optional `calculate:` stage runs each screened-in structure through DFTB+ using
**your** AiiDA installation; leave it out and the funnel is unchanged.

## Commands

| Command | What it does |
|---|---|
| `init` | Scaffold a starter config and check your environment |
| `doctor` | Diagnose config, machine reachability, and per-stage readiness — naming the exact fix |
| `run` | Seed and drain the funnel; `--only STAGE` and `--materials` narrow it |
| `status` | Per-state counts, failures with reasons, jobs in flight |
| `monitor` | Live read-only dashboard: progress donut, stage pipeline, per-material CPU/GPU |
| `retry` | Put failed materials back in the queue (previews before it acts) |
| `results` | List finished materials; `--export PATH` writes the records array |
| `cif` | Export DFTB+ relaxed structures as CIF files |
| `update` | Upgrade an installed copy in place |

`materials-cli <command> --help` documents every flag.

## The science stack is yours

`materials-cli` automates your calculations; it does **not** bundle SMACT, PyXtal,
MACE/torch, ASE, AiiDA, or any ML model. You install those in your own environment — the
tool checks what a run needs and tells you precisely what is missing, and where, *before*
any calculation starts. For screening, if you have no MACE model configured it can fetch
the foundation model for you — always with your consent, never silently.

Want the whole stack in one go? `pip install materials-cli[compute]` is a convenience
alias for `smact` + `pyxtal` + `mace-torch`. An alias, never a requirement.

## Documentation

**[`guide.md`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/guide.md)** is the full user guide — every command, every flag, the complete
config reference, remote execution, material states, and worked recipes.
Contributing and release process: **[`CONTRIBUTING.md`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/CONTRIBUTING.md)**.

## Citation

If this tool contributes to work you publish, please cite it — see
[`CITATION.cff`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/CITATION.cff) (GitHub renders a *Cite this repository* button from it).

## License

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