# MatMelt

**{{ tagline }}**

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.

```console
$ 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
```

{doc}`getting-started/installation` covers how to get that command; the whole
path from nothing installed to a screened crystal is
{doc}`getting-started/index`.

## The funnel

```{image} /_static/diagrams/stage-funnel-light.svg
:alt: 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.
:class: only-light
:width: 100%
```

```{image} /_static/diagrams/stage-funnel-dark.svg
:alt: 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.
:class: only-dark
:width: 100%
```

| 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. {doc}`explanation/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 | {doc}`getting-started/index` |
| Be walked through a complete workflow | {doc}`tutorials/index` |
| Solve one specific problem | {doc}`how-to/index` |
| Understand why it works this way | {doc}`explanation/index` |
| Look up a flag, a config key, or a state | {doc}`reference/index` |
| Change the code | {doc}`architecture/index` |

The {doc}`API reference <api/index>` documents every module from its
docstrings, and {doc}`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. {doc}`getting-started/dependencies` states the split in
full, and {doc}`explanation/the-science` describes what each stage actually
computes.

```{toctree}
:hidden:
:maxdepth: 2

getting-started/index
tutorials/index
how-to/index
explanation/index
architecture/index
reference/index
diagrams
api/index
```

```{toctree}
:hidden:
:caption: Project

changelog
license
citation
```
