meidnet-matter 0.6.1__tar.gz

meidnet_matter-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anand Babu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meidnet_matter-0.6.1/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: meidnet-matter
+Version: 0.6.1
+Summary: MEIDNet Matter: multimodal inverse design for materials discovery, from your materials data to candidate structures
+Author: Anand Babu
+License-Expression: MIT
+Project-URL: Homepage, https://babu09-meidnet-matter.hf.space/
+Project-URL: Source, https://github.com/ABnano/MEIDNet-Matter
+Project-URL: Issues, https://github.com/ABnano/MEIDNet-Matter/issues
+Project-URL: Engine, https://github.com/ABnano/MEIDNet
+Project-URL: Models, https://huggingface.co/Babu09/MEIDNet
+Project-URL: Paper, https://doi.org/10.1038/s41524-026-02153-3
+Keywords: materials,inverse design,multimodal learning,crystal structures,perovskite,generative model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: meidnet<3,>=2.4.0.dev0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: pydantic>=2.5
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pandas>=2.2
+Requires-Dist: scipy>=1.11
+Requires-Dist: spglib>=2.5
+Requires-Dist: ase>=3.23
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Provides-Extra: judge
+Requires-Dist: matgl==4.0.3; extra == "judge"
+Requires-Dist: torch-geometric>=2.6; extra == "judge"
+Provides-Extra: deploy
+Requires-Dist: huggingface_hub>=0.25; extra == "deploy"
+Dynamic: license-file
+
+<p align="center"><img src="https://raw.githubusercontent.com/ABnano/MEIDNet-Matter/main/docs/assets/screenshot.png" alt="MEIDNet Matter: the readiness report and the candidates of a search" width="820"></p>
+
+# 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](https://github.com/ABnano/MEIDNet), imported as a package; the sibling platform [MEIDNet Prism](https://babu09-meidnet.hf.space/) is where to learn the method, reproduce the results and benchmark models.
+
+[![ci](https://github.com/ABnano/MEIDNet-Matter/actions/workflows/ci.yml/badge.svg)](https://github.com/ABnano/MEIDNet-Matter/actions/workflows/ci.yml)
+[![Space](https://img.shields.io/badge/%F0%9F%A4%97%20Space-MEIDNet--Matter-4f46e5)](https://huggingface.co/spaces/Babu09/MEIDNet-Matter)
+[![PyPI](https://img.shields.io/pypi/v/meidnet-matter?label=PyPI&color=4f46e5)](https://pypi.org/project/meidnet-matter/)
+[![engine](https://img.shields.io/badge/engine-meidnet%202.4.0.dev2-9333ea)](https://pypi.org/project/meidnet/)
+[![licence](https://img.shields.io/badge/licence-MIT-0a7d0a)](https://github.com/ABnano/MEIDNet-Matter/blob/main/LICENSE)
+[![paper](https://img.shields.io/badge/npj%20Comput.%20Mater.-2026-1c5cab)](https://doi.org/10.1038/s41524-026-02153-3)
+
+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.
+
+
+| Step | What you get |
+|---|---|
+| **Goal** | Target value, range or bound per property; family and variant; excluded elements and presets; the chemistry rules with their limits; the search budget. |
+| **Readiness** | Six indicators before any search: prediction error of each targeted property on the evaluation split (a published-model diagnostic when the checkpoint saw that split in training), cross-modal retrieval in both directions, what the decoder recovers, where the target sits in the training distribution and how much data lies around it, how many structures share the target window, and whether the family's elements occur in the data. One verdict; a "not recommended" target can still be searched in exploratory mode. |
+| **Candidates** | A search with the engine; every candidate carries the structure-based prediction and the search value of each property, each with its domain status, and what the evidence supports, the rules with values and windows, the encoder's own prediction of the composition and whether it agrees with the search's, the nearest training materials with their DFT values, the training data around the prediction, whether the dataset already holds it, the stability stage, and a "why" sentence that repeats these facts. Table, cards and map; filters; comparison side by side. |
+| **One target, many structures** | When the search has finished, candidates are grouped into clusters of similar encoder latents (cosine ≥ 0.9). The cards view shows the clusters; the "Prioritise" control orders candidates by target accuracy, diversity (one per cluster first), stability, novelty, search score, encoder agreement or order found. |
+| **Validation ladder** | Six stages: Generated · Chemistry checked · MLIP screened · DFT relaxed · DFT property confirmed · Experimentally tested. Every candidate records the highest stage it reached and the result of each stage; this version records stages 0 and 1, the later ones are your own steps and keep their place in the record. |
+| **Export** | CIF per candidate, the candidate table, the candidate record (versioned: `meidnet-matter/candidate-record/1`, JSON Schema at `/api/schema/candidate-record`), and the run bundle: goal, engine configuration, metrics, readiness, candidates, CIFs, `targets.csv`, the record schema, a manifest with file hashes. |
+| **Score on Prism** | The bundle's `cifs/` and `targets.csv` are the input of `meidnet score` (MEIDNet 2.3.1 or later): validity, uniqueness, novelty, diversity, distribution and the conditional metrics, named as in LeMat-GenBench. The export page gives the commands; [the metrics are defined on Prism](https://babu09-meidnet.hf.space/docs/benchmarks/compatibility.html). |
+
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/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](https://github.com/ABnano/MEIDNet-Matter/blob/main/docs/data-format.md) describes the upload layout, the candidate record and `targets.csv`.
+
+Matter is one half of the MEIDNet ecosystem: [MEIDNet Prism](https://babu09-meidnet.hf.space/) is where the method is learned, benchmarked and developed ([the ecosystem](https://babu09-meidnet.hf.space/docs/ecosystem.html)); 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:
+
+```bash
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/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:
+
+```bash
+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):
+
+```bash
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/deploy/requirements.txt), which the
+public Space runs.
+
+Nothing leaves your computer. Details, the Docker image and the Space deploy: [docs/deployment.md](https://github.com/ABnano/MEIDNet-Matter/blob/main/docs/deployment.md). What happens to your data on the shared Space: [docs/privacy.md](https://github.com/ABnano/MEIDNet-Matter/blob/main/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
+
+```bash
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/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.

meidnet_matter-0.6.1/README.md

@@ -0,0 +1,119 @@
+<p align="center"><img src="https://raw.githubusercontent.com/ABnano/MEIDNet-Matter/main/docs/assets/screenshot.png" alt="MEIDNet Matter: the readiness report and the candidates of a search" width="820"></p>
+
+# 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](https://github.com/ABnano/MEIDNet), imported as a package; the sibling platform [MEIDNet Prism](https://babu09-meidnet.hf.space/) is where to learn the method, reproduce the results and benchmark models.
+
+[![ci](https://github.com/ABnano/MEIDNet-Matter/actions/workflows/ci.yml/badge.svg)](https://github.com/ABnano/MEIDNet-Matter/actions/workflows/ci.yml)
+[![Space](https://img.shields.io/badge/%F0%9F%A4%97%20Space-MEIDNet--Matter-4f46e5)](https://huggingface.co/spaces/Babu09/MEIDNet-Matter)
+[![PyPI](https://img.shields.io/pypi/v/meidnet-matter?label=PyPI&color=4f46e5)](https://pypi.org/project/meidnet-matter/)
+[![engine](https://img.shields.io/badge/engine-meidnet%202.4.0.dev2-9333ea)](https://pypi.org/project/meidnet/)
+[![licence](https://img.shields.io/badge/licence-MIT-0a7d0a)](https://github.com/ABnano/MEIDNet-Matter/blob/main/LICENSE)
+[![paper](https://img.shields.io/badge/npj%20Comput.%20Mater.-2026-1c5cab)](https://doi.org/10.1038/s41524-026-02153-3)
+
+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.
+
+
+| Step | What you get |
+|---|---|
+| **Goal** | Target value, range or bound per property; family and variant; excluded elements and presets; the chemistry rules with their limits; the search budget. |
+| **Readiness** | Six indicators before any search: prediction error of each targeted property on the evaluation split (a published-model diagnostic when the checkpoint saw that split in training), cross-modal retrieval in both directions, what the decoder recovers, where the target sits in the training distribution and how much data lies around it, how many structures share the target window, and whether the family's elements occur in the data. One verdict; a "not recommended" target can still be searched in exploratory mode. |
+| **Candidates** | A search with the engine; every candidate carries the structure-based prediction and the search value of each property, each with its domain status, and what the evidence supports, the rules with values and windows, the encoder's own prediction of the composition and whether it agrees with the search's, the nearest training materials with their DFT values, the training data around the prediction, whether the dataset already holds it, the stability stage, and a "why" sentence that repeats these facts. Table, cards and map; filters; comparison side by side. |
+| **One target, many structures** | When the search has finished, candidates are grouped into clusters of similar encoder latents (cosine ≥ 0.9). The cards view shows the clusters; the "Prioritise" control orders candidates by target accuracy, diversity (one per cluster first), stability, novelty, search score, encoder agreement or order found. |
+| **Validation ladder** | Six stages: Generated · Chemistry checked · MLIP screened · DFT relaxed · DFT property confirmed · Experimentally tested. Every candidate records the highest stage it reached and the result of each stage; this version records stages 0 and 1, the later ones are your own steps and keep their place in the record. |
+| **Export** | CIF per candidate, the candidate table, the candidate record (versioned: `meidnet-matter/candidate-record/1`, JSON Schema at `/api/schema/candidate-record`), and the run bundle: goal, engine configuration, metrics, readiness, candidates, CIFs, `targets.csv`, the record schema, a manifest with file hashes. |
+| **Score on Prism** | The bundle's `cifs/` and `targets.csv` are the input of `meidnet score` (MEIDNet 2.3.1 or later): validity, uniqueness, novelty, diversity, distribution and the conditional metrics, named as in LeMat-GenBench. The export page gives the commands; [the metrics are defined on Prism](https://babu09-meidnet.hf.space/docs/benchmarks/compatibility.html). |
+
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/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](https://github.com/ABnano/MEIDNet-Matter/blob/main/docs/data-format.md) describes the upload layout, the candidate record and `targets.csv`.
+
+Matter is one half of the MEIDNet ecosystem: [MEIDNet Prism](https://babu09-meidnet.hf.space/) is where the method is learned, benchmarked and developed ([the ecosystem](https://babu09-meidnet.hf.space/docs/ecosystem.html)); 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:
+
+```bash
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/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:
+
+```bash
+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):
+
+```bash
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/deploy/requirements.txt), which the
+public Space runs.
+
+Nothing leaves your computer. Details, the Docker image and the Space deploy: [docs/deployment.md](https://github.com/ABnano/MEIDNet-Matter/blob/main/docs/deployment.md). What happens to your data on the shared Space: [docs/privacy.md](https://github.com/ABnano/MEIDNet-Matter/blob/main/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
+
+```bash
+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](https://github.com/ABnano/MEIDNet-Matter/blob/main/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.

meidnet_matter-0.6.1/matter/__init__.py

@@ -0,0 +1,10 @@
+"""
+MEIDNet Matter: from your materials data to candidate structures.
+
+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 the ``meidnet`` package; Matter imports it and never
+copies it.
+"""
+
+__version__ = "0.6.1"

meidnet_matter-0.6.1/matter/api/deps.py

@@ -0,0 +1,34 @@
+"""Request-scoped helpers for the routes."""
+from __future__ import annotations
+
+import re
+
+from fastapi import Header, Request
+
+from matter.api.errors import ApiError
+
+SESSION_RE = re.compile(r"^[A-Za-z0-9_-]{4,64}$")
+RESERVED_SESSIONS = ("local", "localtab")
+
+
+def get_services(request: Request):
+    services = getattr(request.app.state, "services", None)
+    if services is None:
+        raise ApiError("server_error", "the application has not finished starting", status=503)
+    return services
+
+
+def session_id(request: Request, x_matter_session: str | None = Header(default=None), mutating: bool = False) -> str:
+    """The visitor's session id: the X-Matter-Session header. Locally it may be absent ("local"); on a shared host a
+    mutating request needs one, and the shared defaults are refused."""
+    settings = request.app.state.settings
+    sid = (x_matter_session or "").strip()
+    if not sid:
+        if settings.public and mutating:
+            raise ApiError("validation_error", "the X-Matter-Session header is needed on this shared server", status=400)
+        return "local"
+    if not SESSION_RE.match(sid):
+        raise ApiError("validation_error", "X-Matter-Session must be 4–64 letters, digits, '-' or '_'", status=400)
+    if settings.public and sid in RESERVED_SESSIONS:
+        raise ApiError("validation_error", f"'{sid}' is a reserved session id", status=400)
+    return sid

meidnet_matter-0.6.1/matter/api/errors.py

@@ -0,0 +1,99 @@
+"""One error shape for every non-2xx answer:
+
+    {"error": {"code": "...", "message": "plain sentence", "fields": [{"loc": "objectives.0.property", "msg": "..."}],
+               "retry_after_s": 30}}
+
+Engine errors (ValueError, SystemExit, KeyError raised by meidnet) are the user's problem to fix and come back as 400
+with the engine's own sentence. Anything unexpected is a 500; on a public host its text is hidden.
+"""
+from __future__ import annotations
+
+import traceback
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from matter.jsonsafe import MatterJSONResponse
+from matter.settings import Settings
+
+
+class ApiError(Exception):
+    """An error with a code and a status, raised by services and turned into the envelope here."""
+
+    def __init__(self, code: str, message: str, status: int = 400, fields: list | None = None, retry_after_s: int | None = None):
+        super().__init__(message)
+        self.code, self.message, self.status, self.fields, self.retry_after_s = code, message, status, fields or [], retry_after_s
+
+
+class NotAvailableInPhase(ApiError):
+    def __init__(self, phase: int, what: str):
+        super().__init__("not_available_in_phase", f"{what} arrives in Phase {phase} of MEIDNet Matter", status=501)
+
+
+def envelope(code: str, message: str, status: int, fields=None, retry_after_s=None) -> MatterJSONResponse:
+    body = {"error": {"code": code, "message": message}}
+    if fields:
+        body["error"]["fields"] = fields
+    if retry_after_s is not None:
+        body["error"]["retry_after_s"] = retry_after_s
+    headers = {"Retry-After": str(retry_after_s)} if retry_after_s else None
+    return MatterJSONResponse(body, status_code=status, headers=headers)
+
+
+def _loc(loc) -> str:
+    return ".".join(str(x) for x in loc if x not in ("body",))
+
+
+class EngineExitMiddleware:
+    """meidnet reports user errors with SystemExit, a BaseException that Starlette's handlers cannot register for;
+    this turns it into the 400 envelope before it reaches the server."""
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+        try:
+            await self.app(scope, receive, send)
+        except SystemExit as exc:
+            response = envelope("engine_error", str(exc.code if exc.code is not None else exc), 400)
+            await response(scope, receive, send)
+
+
+def install_error_handlers(app: FastAPI, settings: Settings) -> None:
+    app.add_middleware(EngineExitMiddleware)
+
+    @app.exception_handler(ApiError)
+    async def _api_error(request: Request, exc: ApiError):
+        return envelope(exc.code, exc.message, exc.status, exc.fields, exc.retry_after_s)
+
+    @app.exception_handler(RequestValidationError)
+    async def _request_validation(request: Request, exc: RequestValidationError):
+        fields = [{"loc": _loc(e.get("loc", ())), "msg": e.get("msg", "")} for e in exc.errors()]
+        return envelope("validation_error", "the request does not match the API schema", 422, fields)
+
+    @app.exception_handler(ValidationError)
+    async def _pydantic_validation(request: Request, exc: ValidationError):
+        fields = [{"loc": _loc(e.get("loc", ())), "msg": e.get("msg", "")} for e in exc.errors()]
+        return envelope("validation_error", "a setting has an invalid value", 422, fields)
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _http(request: Request, exc: StarletteHTTPException):
+        code = {404: "not_found", 405: "method_not_allowed"}.get(exc.status_code, "http_error")
+        return envelope(code, str(exc.detail), exc.status_code)
+
+    @app.exception_handler(ValueError)
+    async def _value_error(request: Request, exc: ValueError):
+        return envelope("engine_error", str(exc), 400)
+
+    @app.exception_handler(KeyError)
+    async def _key_error(request: Request, exc: KeyError):
+        return envelope("engine_error", str(exc.args[0]) if exc.args else "unknown key", 400)
+
+    @app.exception_handler(Exception)
+    async def _unexpected(request: Request, exc: Exception):
+        message = "server error" if settings.public else "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+        return envelope("server_error", message, 500)

meidnet_matter-0.6.1/matter/api/router.py

@@ -0,0 +1,33 @@
+"""All API routes, mounted under /api by matter.app."""
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+
+from matter.api import routes_generate, routes_pipeline, routes_read, routes_readiness, routes_runs, routes_schema, routes_studies
+from matter.api.errors import NotAvailableInPhase
+from matter.version import build_info
+
+api_router = APIRouter()
+api_router.include_router(routes_read.router)
+api_router.include_router(routes_readiness.router)
+api_router.include_router(routes_runs.router)
+api_router.include_router(routes_schema.router)
+api_router.include_router(routes_pipeline.router)
+api_router.include_router(routes_studies.router)
+api_router.include_router(routes_generate.router)
+
+
+@api_router.get("/version", summary="What is running: versions, git commit, mode")
+def version(request: Request) -> dict:
+    settings = request.app.state.settings
+    return build_info(settings.build_info, settings.public)
+
+
+@api_router.post("/datasets/upload", summary="Phase 1: upload your own dataset", status_code=501)
+def upload_dataset():
+    raise NotAvailableInPhase(1, "Uploading your own dataset")
+
+
+@api_router.post("/models/train", summary="Phase 1: train a model on your dataset", status_code=501)
+def train_model():
+    raise NotAvailableInPhase(1, "Training a model")

meidnet_matter-0.6.1/matter/api/routes_generate.py

@@ -0,0 +1,88 @@
+"""Generation jobs: a band-gap request in, structures with two judgements out."""
+from __future__ import annotations
+
+import io
+import os
+import zipfile
+
+from fastapi import APIRouter, Depends, Header, Request
+from fastapi.responses import FileResponse, StreamingResponse
+
+from matter.api.deps import get_services, session_id
+from matter.api.errors import ApiError
+from matter.schemas.generation import GENERATION_SCHEMA_ID, GenerateRequest, result_schema
+from matter.services import generation as GEN
+
+router = APIRouter(tags=["generate"])
+
+
+@router.post("/generate", status_code=201, summary="Start a generation job for one or more band-gap targets")
+def create(body: GenerateRequest, request: Request, x_matter_session: str | None = Header(default=None), services=Depends(get_services)) -> dict:
+    sid = session_id(request, x_matter_session, mutating=True)
+    settings = services.settings
+    if settings.public:
+        services.generations.cleanup()
+    req, notes = GEN.validate_request(body, settings.public, services.catalog)
+    if not services.catalog.available(req["model_id"]):
+        raise ApiError("model_unavailable", f"{req['model_id']} is not present on this server", status=503)
+    est = int(8 + 1.5 * sum(req["per_target"] for _ in req["targets"]) * (1 + len(req["targets"])))
+    job = services.generations.create(sid, req, notes, services.catalog.info(req["model_id"]), services.judge.describe(), est)
+    try:
+        services.jobs.start(job["job_id"], sid, GEN.execute_generation, job, services, max_seconds=GEN.GEN_PUBLIC_LIMITS["seconds"])
+    except ApiError:
+        services.generations.remove(job["job_id"])
+        raise
+    return GEN.summary(job)
+
+
+@router.get("/generate", summary="This session's generation jobs")
+def list_jobs(request: Request, x_matter_session: str | None = Header(default=None), services=Depends(get_services)) -> list[dict]:
+    sid = session_id(request, x_matter_session)
+    return services.generations.list(sid if services.settings.public else None)
+
+
+@router.get("/generate/{job_id}", summary="A job's status (default) or its whole record (view=full)")
+def get_job(job_id: str, view: str = "status", services=Depends(get_services)) -> dict:
+    job = services.generations.get(job_id)
+    if view == "full":
+        return {k: v for k, v in job.items() if not k.startswith("_")}
+    return GEN.status_view(job)
+
+
+@router.post("/generate/{job_id}/stop", summary="Ask a running job to stop after the current draw")
+def stop(job_id: str, services=Depends(get_services)) -> dict:
+    job = services.generations.get(job_id)
+    stopping = services.jobs.stop(job_id)
+    return {"ok": True, "stopping": stopping, "status": job["status"]}
+
+
+@router.get("/generate/{job_id}/candidates/{candidate_id}/cif", summary="One generated cell")
+def cif(job_id: str, candidate_id: str, services=Depends(get_services)):
+    job = services.generations.get(job_id)
+    for c in job.get("candidates", []):
+        if c["candidate_id"] == candidate_id:
+            path = os.path.join(services.generations.path(job_id), c["file"])
+            if os.path.isfile(path):
+                return FileResponse(path, media_type="chemical/x-cif", filename=f"{c['formula']}_{candidate_id}.cif")
+    raise ApiError("not_found", f"no candidate {candidate_id} in {job_id}", status=404)
+
+
+@router.get("/generate/{job_id}/export/cifs.zip", summary="Every generated cell, the table, the record and the relax command")
+def export_zip(job_id: str, services=Depends(get_services)):
+    job = services.generations.get(job_id)
+    if job["status"] in ("queued", "running"):
+        raise ApiError("busy", "the job is still running; download when it has finished", status=409, retry_after_s=15)
+    folder = services.generations.path(job_id)
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        for root, _dirs, files in os.walk(folder):
+            for name in files:
+                p = os.path.join(root, name)
+                z.write(p, os.path.relpath(p, folder))
+    buf.seek(0)
+    return StreamingResponse(buf, media_type="application/zip", headers={"Content-Disposition": f'attachment; filename="{job_id}.zip"'})
+
+
+@router.get("/schema/generation-result", summary="The JSON Schema of a generation record")
+def schema() -> dict:
+    return {"schema_id": GENERATION_SCHEMA_ID, **result_schema()}

meidnet_matter-0.6.1/matter/api/routes_pipeline.py

@@ -0,0 +1,42 @@
+"""The staged pipeline: the ten blocks, their metrics and bands, and the source of every component (read-only)."""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import PlainTextResponse
+
+from matter.api.deps import get_services
+from matter.api.errors import ApiError
+from matter.services.pipeline_blocks import blocks_payload, component_list, component_source
+
+router = APIRouter(prefix="/pipeline", tags=["pipeline"])
+
+
+def _research_file(services) -> str | None:
+    studies = getattr(services, "studies", None)
+    return studies.pipeline_blocks_file() if studies is not None else None
+
+
+@router.get("/blocks", summary="The ten blocks with their metrics, bands, components and per-dataset verdicts")
+def blocks(services=Depends(get_services)) -> dict:
+    return blocks_payload(_research_file(services))
+
+
+@router.get("/blocks/{block_id}", summary="One block")
+def block(block_id: str, services=Depends(get_services)) -> dict:
+    bid = (block_id or "").upper()
+    for b in blocks_payload(_research_file(services))["blocks"]:
+        if b["id"] == bid:
+            return b
+    raise ApiError("not_found", f"no block {block_id!r}", status=404)
+
+
+@router.get("/components", summary="Every component with its size, checksum and where it can run")
+def components() -> list[dict]:
+    return component_list()
+
+
+@router.get("/components/{name}", summary="The source of one component, as plain text", response_class=PlainTextResponse)
+def component(name: str):
+    text, meta = component_source(name)
+    return PlainTextResponse(text, headers={"X-Matter-Sha256": meta["sha256"], "Cache-Control": "no-cache",
+                                            "Content-Disposition": f'inline; filename="{name}"'})