MEIDNet Matter

From your materials data to candidate structures.

MEIDNet Matter is a multimodal inverse-design workbench for crystalline materials. A researcher brings crystal structures and properties; Matter reports what the data and the model support (the Design Readiness report), then runs a constrained, property-conditioned search and returns candidate structures with their evidence and provenance. The scientific engine is MEIDNet, imported as a package; the sibling platform MEIDNet Prism is where to learn the method, reproduce the results and benchmark models.

Matter currently searches property-conditioned candidates within supported structural families. Free-geometry crystal generation is planned as additional design backends mature.

Try it

Live: https://babu09-meidnet-matter.hf.space/ — open the Perov-5 demo project, set a band-gap target, exclude lead, read the readiness report, run the search (about a minute on the shared CPU), open a candidate, download its CIF or the whole run bundle.

Mirror for any network: https://abnano.github.io/MEIDNet-Matter/ — the same site on GitHub Pages, for networks that block *.hf.space (public Wi-Fi often does: the Space then shows a grey page). Everything that reads works there (studies, the staged pipeline with its code, the method, checkpoints, every structure file); generation and the demo search point to the Space, and the mirror says whether the Space is reachable from your network. It is rebuilt for every release (.github/workflows/pages.yml: npm run build:mirror, then scripts/build_mirror.py). Prism has its own mirror at https://abnano.github.io/MEIDNet/.

What it does, in this version

The home page opens on a worked result: a real accepted structure with both of its readings, a small requested-versus-delivered plot, an animated six-step walkthrough, and a rolling strip of the structures the generator delivered. From there: Pipeline (the ten blocks with their bands and code), Studies (Perov-5, Materials Project perovskites, an external upload, MP-20, with checkpoints), Generate (live band-gap generation on MP-20 with two independent readings per cell, 3D cards and an evidence map) and Method (mechanism, strengths, limits, and the commands that run the same stages on your own data: whatever route produced your candidates, one check gives them the qualified judge, relaxation by two potentials, both readings again on the relaxed cells, the energy above the hull with one potential for every phase, novelty, and a class: new, rediscovered, or contradicted by your data's own value). The Perov-5 demo project below is the original flow and is kept as it was, with one change: every candidate now shows the structure-based prediction first and the search value beside it, and says which of the two supports the target.

The demo project: cubic ABX₃ perovskites of the Perov-5 dataset, the published MEIDNet model, the direct band gap and the formation enthalpy. By the engine's thresholds the published model is weak on both properties on held-out data, so the demo opens its searches in exploratory mode by design; docs/scientific-scope.md has the numbers and what the evidence shows instead.

Coming next (Phase 1): upload your own property table and CIF files, a data-quality report, training in the browser, readiness on your own held-out data, the same search with your model; then imports from Materials Project and NOMAD, a bring-your-own-model backend, and synthesis context linked from existing resources. docs/data-format.md describes the upload layout, the candidate record and targets.csv.

Matter is one half of the MEIDNet ecosystem: MEIDNet Prism is where the method is learned, benchmarked and developed (the ecosystem); Matter is where a dataset becomes candidates.

Run it yourself

Supported: Linux, macOS, and Windows through WSL (Windows 11 with Smart App Control blocks unsigned wheels one module at a time, so use WSL there). One command installs the engine and the application with the judge from PyPI, with CPU torch (the default Linux build pulls about 2.5 GB of GPU libraries), pinned to the versions this release was tested with; the last line proves the install:

pip install --extra-index-url https://download.pytorch.org/whl/cpu \
  -c https://github.com/ABnano/MEIDNet-Matter/releases/latest/download/constraints.txt "meidnet-matter[judge]"
python -c "import meidnet, matter, matgl; print(meidnet.__version__, matter.__version__)" && meidnet --version

On a slow or flaky network, scripts/install.sh does the same with retries, a fresh virtual environment and the check (bash scripts/install.sh; MATTER_SOURCE=release takes the wheels of the latest release instead of PyPI). The same wheels are attached to every release, for an index mirror or an offline machine:

pip install --extra-index-url https://download.pytorch.org/whl/cpu \
  "meidnet @ https://github.com/ABnano/MEIDNet-Matter/releases/latest/download/meidnet-2.4.0.dev2-py3-none-any.whl" \
  "meidnet-matter[judge] @ https://github.com/ABnano/MEIDNet-Matter/releases/latest/download/meidnet_matter-0.6.1-py3-none-any.whl"

constraints.txt is written by the release workflow from its own install check (Linux, Python 3.12); on another Python drop the -c line. The engine on PyPI, meidnet 2.4.0.dev2, is the snapshot in engine/, published from this repository until the upstream MEIDNet release 2.4.0 replaces it.

From a clone instead (the engine first, so that nothing older is fetched from PyPI):

git clone https://github.com/ABnano/MEIDNet-Matter && cd MEIDNet-Matter
pip install --extra-index-url https://download.pytorch.org/whl/cpu ./engine && pip install -e ".[dev,judge]"
python scripts/fetch_assets.py                 # the checkpoints the studies use, each verified against its checksum
cd frontend && npm ci && npm run build && cd ..
python -m uvicorn matter.app:app --port 8000   # http://127.0.0.1:8000/

The potentials used for relaxation (TensorNet, CHGNet) are fetched from the Hugging Face Hub on first use; the classic transfer is used by default because the Hub's Xet transfer can stall silently on some networks (HF_HUB_DISABLE_XET). The known-good versions of every dependency are the ones in deploy/requirements.txt, which the public Space runs.

Nothing leaves your computer. Details, the Docker image and the Space deploy: docs/deployment.md. What happens to your data on the shared Space: docs/privacy.md.

How it works

Data → readiness → shared latent space → search → candidates. MEIDNet learns one latent space shared by crystal structures and their properties and searches it for compositions that hit property targets while obeying the chemistry rules of a material family; Matter adds the readiness report before the search, the evidence next to every candidate, the run manifest, and the interface. The backend (matter/, FastAPI) calls the meidnet package through one backend interface so that other design engines can be added; the frontend (frontend/, React + TypeScript) is built into matter/static and served by the backend.

Development

python -m pytest -q                                          # backend; -m "not slow" skips the model and the tiny search
cd frontend && npm run typecheck && npm test && npm run lint  # frontend
node scripts/smoke_browser.mjs http://127.0.0.1:8000 build/smoke   # the browser walk-through against a running server

Citation

If you use MEIDNet Matter, please cite the MEIDNet paper and the software (CITATION.cff):

A. Babu, R. Almeida Gouvêa, P. Vandergheynst, G.-M. Rignanese, MEIDNet: Multimodal generative AI framework for inverse materials design, npj Computational Materials 12, 287 (2026). doi:10.1038/s41524-026-02153-3

Data: Perov-5 (Castelli et al. 2012) in the CDVAE split (Xie et al. 2022). Licence: MIT. Author: Anand Babu.