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.

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

Install

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

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

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.

MIT licensed — see LICENSE.