---
description: What each stage needs installed, why MatMelt does not install it for you, and how doctor reports what is missing.
---

# The tool and the science stack

MatMelt separates what it *is* from what it *runs*. The tool is the orchestration
— a CLI, a config schema, a state database, and the logic that submits jobs and
interprets their results. The science is a set of packages that you install and
that MatMelt calls.

This page is deliberately early, because the split is the single thing most
likely to surprise you.

## What the base install contains

Four small pure-Python dependencies: Typer, Rich, pydantic and PyYAML. Installing
MatMelt does not install PyTorch, and never will.

That means a fresh install can already scaffold a config, inspect a workspace,
report on state, export results and diagnose an environment. What it cannot do
is compute anything, until you give each stage an interpreter that has what it
needs.

## What each stage needs

| Stage | Needs | Install as |
|---|---|---|
| `compose` | SMACT | `pip install smact` |
| `structure` | PyXtal | `pip install pyxtal` |
| `screen` | MACE (and ASE, which comes with it) | `pip install mace-torch` |
| `calculate` *(optional)* | AiiDA + the `aiida-mydftbp` plugin + ASE | `pip install aiida-core aiida-mydftbp ase` |
| `extract` | nothing — standard library only | — |

Note the two cases where the import name and the package name differ: you
install `mace-torch` but import `mace`, and you install `aiida-core` but import
`aiida`. MatMelt always prints the name you must *install*, never the one it
imports, so a copied command works.

`extract` needing nothing is not an oversight — it is a contract. The extract
runner is standard-library only so that turning screened structures into records
can never be blocked by a broken scientific environment.

## Why it works this way

**The packages are large and opinionated.** `mace-torch` pulls in PyTorch, which
is gigabytes and extremely particular about CUDA versions. A tool that installed
it as a dependency would make itself uninstallable on machines where those
choices conflict with what the user already has.

**Researchers already have environments.** A conda environment with ASE, PyXtal
and a working PyTorch is a normal thing to already own. MatMelt is designed to
*use* that environment rather than duplicate it.

**Different stages can use different interpreters.** Each stage's `python`
option is independent, so `compose` can run in one environment and `screen` in
another — or on another machine entirely, which is the same mechanism (tutorial T3 covers it).

The honest cost: your first run involves real setup. There is no single command
that makes a fresh machine ready to screen structures, and this site will not
pretend otherwise.

## Pointing a stage at an interpreter

Every stage takes a `python` option, and it is simply the interpreter that runs
that stage's work:

```yaml
stages:
  compose:
    backend: laptop
    options:
      python: /home/you/miniconda3/envs/science/bin/python
  structure:
    backend: laptop
    options:
      python: /home/you/miniconda3/envs/science/bin/python
```

If everything you need is on your `PATH`, plain `python3` — the scaffolded
default — is fine.

## Letting `doctor` tell you what is missing

You never have to guess. `doctor` probes each stage's own interpreter and, when
something is missing, prints the exact command that fixes it:

```console
$ matmelt doctor
```

```text
                                Stage readiness
┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Stage     ┃ Needs       ┃ Interpreter    ┃ Where ┃ Status  ┃ Detail          ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ compose   │ smact       │ python3        │ local │ ok      │ smact           │
│           │             │                │       │         │ importable      │
│ structure │ pyxtal      │ ./nosci/bin/p… │ local │ MISSING │ ModuleNotFound… │
│           │             │                │       │         │ No module named │
│           │             │                │       │         │ 'pyxtal'        │
│ screen    │ mace        │ python3        │ local │ ok      │ mace importable │
│ extract   │ stdlib only │ python3        │ local │ ok      │ standard        │
│           │             │                │       │         │ library only -- │
│           │             │                │       │         │ always ready    │
└───────────┴─────────────┴────────────────┴───────┴─────────┴─────────────────┘
To fix the missing requirements, run:
  ./nosci/bin/python -m pip install pyxtal
```

The fix is printed as a command against **that stage's own interpreter**, so it
can be copied and run as-is.

The **Interpreter** and **Where** columns matter: the probe runs in the
interpreter that stage will actually use, on the machine it will actually use.
A stage wired to a remote backend is probed *over SSH on that remote*, and the
suggested fix is prefixed accordingly — because the science must exist where the
job runs, not where you typed the command.

`run` performs the same check before it starts, and refuses rather than failing
halfway through a funnel.

## The MACE model

`screen` needs model weights as well as the `mace` package. You have two
options, and MatMelt will not download anything without asking:

**Point at a model you already have** with the `model_path` option — the usual
choice on a cluster where the weights are already on disk.

**Let it fetch a MACE-MP foundation model.** With no `model_path` configured,
`doctor` discloses the size and cache location up front, and `run` asks for
consent before downloading:

```text
Screen model: ok -- no model_path configured: the MACE-MP foundation model
(size=medium) will be downloaded on first use into the mace cache
(~/.cache/mace) -- a one-time download on the order of hundreds of MB. It will
NOT be downloaded without your consent.
```

The `model_size` option selects which one: `small` keeps the download to a few
tens of megabytes and is a good choice for a first run, while `medium` (the
default) is the better model for real work.

Next: {doc}`first-run` — a scaffolded config and a real screened structure.

Every option named here — `model_path`, `model_size`, each stage's `python` —
is listed with its default in the
{doc}`configuration reference <../reference/config>`, and
{doc}`../how-to/doctor` covers reading the readiness report in full.
