Overview

materials-cli is a config-driven CLI for running a multi-stage materials discovery funnel. Run jobs on your local machines, GPUs, or remote SSH servers using SLURM. It maintains state in SQLite and plain files, allowing you to pause and resume funnel runs seamlessly at any stage.

Funnel Stages

compose➔structure➔screen➔calculate (DFT/DFTB+)➔extract

Stage	Output	Underlying Science
compose	Charge-balanced compositions	SMACT
structure	Candidate crystal structures	PyXtal (Symmetry families)
screen	ML relaxation & convergence verdict	MACE machine learning potentials
calculate	DFTB+ energies with self-healing retries	AiiDA plugin on your machines
extract	OPTIMADE-compliant record.json	—

Installation

Install the base package via pip:

pip install materials-cli

Or get a self-contained installation (launcher placed on path):

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

For a full computational stack (includes SMACT, PyXtal, and MACE-Torch):

pip install materials-cli[compute]

Funnel Configuration

Funnel steps and execution backends are defined in materials-cli.yaml:

run:
  work_dir: ./materials-work
  elements: [Na, Cl, O]          # Elements to explore

backends:                        # Execution backends
  laptop:
    kind: local
    options: { max_parallel: 2 }
  gpu_box:
    kind: ssh_exec
    options: { host: user@gpu-box.lan, max_parallel: 4 }

stages:                          # Map stages to backends
  compose:   { backend: laptop }
  structure: { backend: laptop }
  screen:    { backend: gpu_box }
  extract:   { backend: laptop }

Command Reference

Command	Description
materials-cli init	Scaffolds a starter materials-cli.yaml config
materials-cli doctor	Diagnoses config, backend reachability, and dependency readiness
materials-cli run	Starts processing elements down the funnel. Interruptible and resumable
materials-cli status	Prints structural metrics, failures, and jobs in flight
materials-cli monitor	Launches a live dashboard displaying stage pipelines and stats
materials-cli retry	Requeues failed computations back into the funnel
materials-cli results	Exports and lists all completed materials to JSON database format