matsyngate 0.1.0

Material Synthesis Gatekeeper — a Python library for evaluating the experimental synthesizability of inorganic crystals via hard chemical rules.

matsyngate is a strict filtering layer for theoretical and AI-generated crystal structures. A rule earns "hard gate" status only if violating it means the material cannot be made no matter how the temperature and dwell time are tuned. "Difficult but precedented" is deliberately out of scope: this package answers a binary question, not a graded one.

Documentation: https://matsyngate.readthedocs.io/ — installation, a full walkthrough, every threshold with its source, and the API reference.

Installation

uv add matsyngate                 # runtime
uv add 'matsyngate[mp,pandas]'    # + G10 (Materials Project) and DataFrame output

Development:

git clone <this repo> && cd matsyngate
uv sync --extra dev
uv run pytest

Quick start

import matsyngate as msg

result = msg.screen(structures, config=msg.SolidStateConfig(n_max=5))

result.passed              # numpy bool mask, aligned with the input
result.n_passed
result.rejection_counts()  # {"G6": 412, "G5": 88, ...}
result[7].verdicts["G6"].reason
result.to_jsonl("screened.jsonl")

structures may hold pymatgen Structure objects, Composition objects, or formula strings. Rules that need a structure report SKIPPED for the latter two, and SKIPPED never rejects.

Screening repeatedly — inside an RL loop, say — reuse one Screener so the process pool is built once:

with msg.Screener(config=msg.SolidStateConfig.project(), n_jobs=16) as screener:
    for batch in batches:
        mask = screener.screen(batch).passed

The solid-state route

Ten hard rules for conventional ceramic synthesis in an open-air box furnace — see the full documentation for every threshold, its source, and where it deviates from the reference implementation it is built from.

Tier A is offline and needs only composition and structure. G9 activates when you pass e_hull=[...]; G10 when you pass mp_api_key=.... Anything not evaluated is listed in result.skipped_rules, so a Tier A screen can never be mistaken for a full ten-rule one.

Validation

Against A-Lab's 58 attempted targets (Szymanski et al., Nature 624, 86 (2023); 41 reported successes, 17 failures), under SolidStateConfig.alab(): 41/41 experimental successes retained, 3 of 17 failures rejected (all by G6), precision 75% versus A-Lab's own 71%. Full numbers, the element-count sweep, and what this test does and does not measure: Validation against A-Lab.

Known limitations

Reaction kinetics are not modelled at all — 11 of A-Lab's 17 failures were attributed to slow kinetics, and no rule here can catch that failure mode. Five more, plus the rare-earth/heavy-metal exclusion's effect on recall, are detailed in Known limitations.

Provenance

Every threshold is traceable to its source in the docstring of the rule that uses it, and in the corresponding page under The solid-state route. The design and the literature basis are in docs/superpowers/specs/2026-08-07-matsyngate-solidstate-batch-design.md; Extending matsyngate explains how to implement a second route.