materials-cli 0.1.1

Config-driven CLI that runs a multi-stage materials-discovery funnel on your own machines.

materials-cli

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

---

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

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

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: [e-mail], 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 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.