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

materials-cli run

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

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

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):

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

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:

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

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 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.

Citation

If this tool contributes to work you publish, please cite it — see CITATION.cff (GitHub renders a Cite this repository button from it).

License

MIT — see LICENSE.