Installation

MatMelt needs Python 3.10 or newer. It installs into its own environment and requires no root access.

Version 0.2.0 is not on PyPI yet

MatMelt was renamed from materials-cli at 0.2.0, and the matmelt distribution has not been published yet. Until it is, pip install matmelt will not resolve — install from the repository as shown below.

The last published release under the old name is materials-cli 0.1.1, which pre-dates the rename. pip install --upgrade materials-cli cannot cross over to the new name: PyPI treats them as unrelated projects, so a fresh install is required either way.

The installer script

The installer builds a dedicated virtual environment, installs MatMelt into it, and links a matmelt launcher into ~/.local/bin. It never uses sudo, never touches your system Python, and re-running it is the upgrade-and-repair path.

$ git clone https://github.com/Quantum-ARISE-Acad/qa-materials-cli.git
$ cd qa-materials-cli
$ ./install.sh

After release, the one-liner form works from anywhere:

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

The script understands four environment overrides:

MATMELT_SPEC

What pip installs. Defaults to matmelt from PyPI; a git+https://… URL or a path to a local checkout works identically, which is how pre-release installs are done. Whatever you pass is recorded and becomes what matmelt update re-installs from later.

MATMELT_HOME

Install root. Default ~/.local/share/matmelt.

MATMELT_BIN

Where the launcher is linked. Default ~/.local/bin.

MATMELT_PYTHON

The interpreter used to build the environment. Default python3.

So a pre-release install from a checkout is:

$ MATMELT_SPEC="$PWD" ./install.sh

If ~/.local/bin is not on your PATH, the script says so and prints the line to add to your shell profile.

With pip

If you would rather manage the environment yourself:

$ python3 -m venv ~/matmelt-venv
$ ~/matmelt-venv/bin/pip install git+https://github.com/Quantum-ARISE-Acad/qa-materials-cli.git

and after release, simply:

$ ~/matmelt-venv/bin/pip install matmelt

The [compute] extra

There is an optional extra that installs the scientific stack alongside the tool:

$ ~/matmelt-venv/bin/pip install "matmelt[compute]"

It is a convenience alias, not a requirement — it installs SMACT, PyXtal and mace-torch (which brings ASE and PyTorch with it) into that same environment. Read The tool and the science stack before using it: putting several gigabytes of PyTorch into the tool’s own environment is often not what you want, and pointing each stage at an environment you already have is usually better.

Verify

$ matmelt --version
matmelt 0.2.0

$ matmelt --help

The help text lists every command: init, doctor, run, status, retry, results, monitor, cif and update — all of them, with their flags, in the command reference. When a new version lands, see Update MatMelt.

Note

If you installed with pip into your own environment rather than using the installer script, replace matmelt with ~/matmelt-venv/bin/matmelt in every example on this site, or activate the environment first.

Next: The tool and the science stack — what the scientific stages need, and how MatMelt tells you what is missing.