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:

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:

$ matmelt doctor

                                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:

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: Your 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 configuration reference, and Check that a machine can do the work covers reading the readiness report in full.