MatMelt#

Melt elements into crystals — automated structure generation, screening, and calculation, from your laptop to remote compute.

MatMelt runs a multi-stage materials-discovery funnel on machines you already have. You write one YAML file saying what to explore and where each stage runs; MatMelt enumerates compositions, builds candidate crystals, relaxes and screens them, optionally refines the survivors with DFTB+, and writes one OPTIMADE-shaped record per material. Every run is durable: interrupt it at any point and the same command picks up where it stopped, without recomputing or resubmitting anything.

$ matmelt init      # scaffold matmelt.yaml, then edit your elements
$ matmelt doctor    # what is installed, what is missing, and on which machine
$ matmelt run       # drive the funnel; Ctrl-C is safe, re-run to continue

Installation covers how to get that command; the whole path from nothing installed to a screened crystal is Getting started.

The funnel#

The five-stage funnel: compose and structure fan one seed out into several compositions and then several candidate crystals; screen narrows them, sending rejects to a terminal FAILED state; the optional calculate stage and then extract carry survivors to DONE. A stop_after setting rests materials at a stage rather than retiring them. The five-stage funnel: compose and structure fan one seed out into several compositions and then several candidate crystals; screen narrows them, sending rejects to a terminal FAILED state; the optional calculate stage and then extract carry survivors to DONE. A stop_after setting rests materials at a stage rather than retiring them.

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

—

Each stage is assigned a backend in the config — your own machine, or a remote one over SSH, with or without SLURM. A stage never names a host and a backend never judges the science; moving a heavy stage to a bigger machine is a config change and no Python at all. What vs. where explains why that separation is the load-bearing one.

Where to start#

If you want to

Go to

Install it and get a first result

Getting started

Be walked through a complete workflow

Tutorials

Solve one specific problem

How-to guides

Understand why it works this way

Explanation

Look up a flag, a config key, or a state

Reference

Change the code

Architecture

The API reference documents every module from its docstrings, and Architecture diagrams collects the five architecture diagrams on one page.

The science stack is yours#

MatMelt does not bundle SMACT, PyXtal, MACE, torch, ASE, AiiDA, or any ML model, and it never installs them behind your back. You install what your configured stages need, in an environment you control — which may be a different environment on a different machine for each stage. The tool’s job is the automation around that: every stage declares its requirements, doctor and the run preflight report exactly what is missing and where, and no calculation starts before you know. The tool and the science stack states the split in full, and What the stages actually compute describes what each stage actually computes.