Metadata-Version: 2.4
Name: meidnet
Version: 2.2.0
Summary: MEIDNet: multimodal structure-property latent space and constrained inverse design of crystalline materials
Author: Anand Babu
License-Expression: MIT
Project-URL: Homepage, https://babu09-meidnet.hf.space/
Project-URL: Documentation, https://babu09-meidnet.hf.space/docs/
Project-URL: Source, https://github.com/ABnano/MEIDNet
Project-URL: Issues, https://github.com/ABnano/MEIDNet/issues
Project-URL: Paper, https://doi.org/10.1038/s41524-026-02153-3
Project-URL: Models, https://huggingface.co/Babu09/MEIDNet
Keywords: materials,inverse design,generative model,perovskite,contrastive learning
Classifier: Development Status :: 4 - Beta
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: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.1
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pymatgen>=2024.1.1
Requires-Dist: scikit-learn>=1.3
Requires-Dist: matplotlib>=3.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.5
Requires-Dist: openpyxl>=3.1
Provides-Extra: parquet
Requires-Dist: pyarrow>=14; extra == "parquet"
Provides-Extra: stability
Requires-Dist: ase>=3.22; extra == "stability"
Requires-Dist: mace-torch>=0.3.6; extra == "stability"
Provides-Extra: app
Requires-Dist: gradio>=4.0; extra == "app"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/ABnano/MEIDNet/main/docs/assets/meidnet_prism_logo.png" alt="MEIDNet Prism — Multimodal materials representation and inverse design" width="640"/>
</p>

<p align="center"><em>Inverse design of crystalline materials from target properties, with your own data and rules.</em><br/>
<b>MEIDNet Prism</b>: learn, build and benchmark multimodal AI for materials discovery, with MEIDNet as the reference implementation.<br/>
<a href="https://babu09-meidnet.hf.space/">home</a> · <a href="https://babu09-meidnet.hf.space/docs/learn/index.html">learn</a> · <a href="https://babu09-meidnet.hf.space/docs/learn/architectures.html">architectures</a> · <a href="https://babu09-meidnet.hf.space/studio/">build (Studio)</a> · <a href="https://babu09-meidnet.hf.space/docs/explore/datasets.html">datasets</a> · <a href="https://babu09-meidnet.hf.space/docs/benchmarks/index.html">benchmarks</a> · <a href="https://babu09-meidnet.hf.space/docs/community/contribute.html">community</a></p>

<p align="center">
  <a href="https://doi.org/10.1038/s41524-026-02153-3"><img alt="Paper" src="https://img.shields.io/badge/npj%20Comput.%20Mater.-2026-1c5cab"></a>
  <a href="https://babu09-meidnet.hf.space/"><img alt="MEIDNet Prism" src="https://img.shields.io/badge/MEIDNet%20Prism-live-4f46e5"></a>
  <a href="https://huggingface.co/Babu09/MEIDNet"><img alt="Model on Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97%20model-Babu09%2FMEIDNet-ffcc4d"></a>
  <a href="https://github.com/ABnano/MEIDNet/actions"><img alt="CI" src="https://github.com/ABnano/MEIDNet/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/ABnano/MEIDNet/blob/main/LICENSE"><img alt="MIT" src="https://img.shields.io/badge/licence-MIT-0a7d0a"></a>
</p>

<p align="center">
  <a href="https://babu09-meidnet.hf.space/docs/"><b>Documentation</b></a> ·
  <a href="https://babu09-meidnet.hf.space/studio/"><b>Try it in your browser</b></a> ·
  <a href="https://www.nature.com/articles/s41524-026-02153-3">Paper</a> ·
  <a href="https://github.com/ABnano/MEIDNet/releases/tag/v1.0.0-paper">v1.0 code as published</a>
</p>

<p align="center">
  <a href="https://babu09-meidnet.hf.space/"><img src="https://raw.githubusercontent.com/ABnano/MEIDNet/main/docs/assets/meidnet_tour_poster.png" alt="MEIDNet: from concept to demonstration" width="720"/></a><br/>
  <sub><a href="https://babu09-meidnet.hf.space/"><b>▶ MEIDNet: from concept to demonstration</b></a>, the live 3D tour on the home page (<a href="https://github.com/ABnano/MEIDNet/releases/download/v2.1.0/meidnet_tour.webm">video version</a>)</sub>
</p>

---

MEIDNet learns one latent space shared by **crystal structures** and their **properties**
(contrastive alignment of an equivariant graph encoder and a property encoder), then
searches that space for new materials that hit property targets while obeying the
chemical and structural rules of a **material family**.

MEIDNet 2.0 turns the published perovskite code into a framework:

| You want to… | You do… |
|---|---|
| try it | `meidnet demo` or the [browser demo](https://babu09-meidnet.hf.space/studio/) |
| use **your** structures + properties | put them in a table, run `meidnet init / check / train / generate` |
| change targets, elements, rules | edit `meidnet.yaml` — or move sliders in **MEIDNet Studio** and export it |
| a different material family | copy a family `.yaml` (prototype + site groups + rules) |
| your own rule | a 5-line Python function registered as a constraint |
| understand every decision | each step writes a plain-language HTML report (data check, training, generation) |

The published cubic-ABX₃ perovskite model (band gap + formation enthalpy, Perov-5) is
**example application #1**; it runs unchanged and bit-identically (tests prove it).

## Install

```bash
pip install meidnet            # core (PyTorch CPU wheels work; CUDA optional)
pip install "meidnet[stability]"   # + MACE stability screening
```

From source: `git clone https://github.com/ABnano/MEIDNet && cd MEIDNet && pip install -e ".[dev]"`.

## Try it (2 minutes, CPU is fine)

```bash
meidnet demo                      # halide perovskites, band gap 2.0 eV → CIFs + report
meidnet studio                    # interactive workbench with the published model
```

## Use your own data (the main path)

Your data is a table with one row per material plus the structures as CIF text (a `cif`
column) or files (`structures/<id>.cif`):

```
material_id   cif                         band_gap   dielectric
mat_001       data_mat_001 ...            1.42       18.3
mat_002       data_mat_001 ...            2.16       11.7
```

```bash
meidnet init --table materials.csv --properties band_gap dielectric --family perovskite_abx3 --variant oxide
meidnet check meidnet.yaml      # → check_report.html: what is usable, what was skipped and why
meidnet train meidnet.yaml      # → model.pt + training_report.html: how accurate, did modalities align
meidnet generate meidnet.yaml   # → CIFs + generation_report.html: every candidate and why it passed
```

Everything you can change is in `meidnet.yaml`, with a one-line explanation per setting
([reference](https://babu09-meidnet.hf.space/docs/reference/config.html)). No Python needed.

## MEIDNet Studio — see the effect of every change

```bash
meidnet studio meidnet.yaml
```

A local web page shows the workflow as a strip of colour-coded blocks **Data → Model →
Family → Rules → Targets → Search → Candidates**. Move a rule's limit or a target and watch
the change flow through every later block, with a short explanation: how many compositions
still pass, which are predicted closest, which of your earlier candidates would now be
rejected. Beginner mode shows the input, logic and output of each block, and *Behind the
scenes* shows the YAML and Python that do the same thing.

- **Your data in the browser:** upload a table (CSV / Excel / JSON) with CIF structures, map
  the columns, check it and train a model — every block then uses your properties.
- **Edit as text:** the configuration as YAML; errors name the exact setting.
- **Explore in 3D:** the design space, your data or the candidates as a property map linked
  to a crystal viewer ([chemiscope](https://chemiscope.org)).
- "Run search" runs the paper's latent optimisation live; every candidate comes with its
  checklist and a rotatable cell. Export `meidnet.yaml` to repeat the run from the command line.

No installation needed to try it: the [hosted Studio](https://huggingface.co/spaces/Babu09/MEIDNet)
runs on Hugging Face ([direct link](https://babu09-meidnet.hf.space/studio/)).

## What is in the box

```
meidnet/
  config.py       the meidnet.yaml schema (pydantic) — single source of truth for CLI, docs, Studio
  data.py         tables + CIFs → prototype-aligned feature vectors, with a skip report
  model.py        SE(3)-equivariant crystal autoencoder + property autoencoder, shared latent
  train.py        the five-term objective of the paper, validation metrics in physical units
  family.py       material families from YAML: prototype, site groups, charges, lattice rule, variants
  constraints.py  hard rules (charge balance, tolerance factor, …) — each returns value, window, sentence
  terms.py        soft search terms and logit transforms used during the latent optimisation
  generate.py     the inverse-design loop (latent search → decode → rules → rank → save), with a funnel log
  designspace.py  every composition a family can make, with rule descriptors and model predictions
  report.py       plain-language HTML reports; svg.py: dependency-free charts
  studio/         the interactive workbench (stdlib HTTP server + one HTML page)
  families/       perovskite_abx3.yaml, double_perovskite_a2bbx6.yaml
tests/            incl. byte-level regression against the published v1 code (tests/legacy_v1/)
examples/         Perov-5 reproduction, custom-rule plugin, the paper's generated CIFs
docs/             the website (MkDocs)   notebooks/  Colab tutorials   app/  Hugging Face demo
```

## Scope

* Generation works for **prototype families**: a fixed arrangement of sites whose
  occupants and cell size are chosen (ABX₃, A₂BB′X₆, and anything you describe the same
  way, up to `max_sites` atoms). It does **not** invent new atomic arrangements.
* Properties: any number of scalar columns. Spectra/images as modalities are on the
  [roadmap](https://babu09-meidnet.hf.space/docs/understand/limits.html), not in this release.
* Predicted properties are **model estimates**. Confirm candidates with DFT or experiment;
  `meidnet screen` (MACE) is a first filter.

## Reproducing the paper

```bash
meidnet download-data                       # Perov-5 (CDVAE split) → data/perov5/
meidnet init --template perov5 -o examples/perov5/meidnet.yaml
meidnet train examples/perov5/meidnet.yaml  # ~1 h on a laptop GPU for 200 epochs
meidnet generate examples/perov5/meidnet.yaml --model checkpoints/dual_autoencoder_clip_earlyfusion_propertyaware_2k.pth
```

`pytest -m slow` re-runs the frozen v1 generation code (`tests/legacy_v1/`) and checks that
MEIDNet 2 produces the same CIFs, predictions and file names.

## Citation

```bibtex
@article{meidnet2026,
  title   = {MEIDNet: Multimodal generative AI framework for inverse materials design},
  author  = {Anand Babu and Rog{\'e}rio Almeida Gouv{\^e}a and Pierre Vandergheynst and Gian-Marco Rignanese},
  journal = {npj Computational Materials},
  year    = {2026},
  doi     = {10.1038/s41524-026-02153-3}
}
```

MIT licence. Perov-5 data: Xie et al., CDVAE (ICLR 2022); Castelli et al. (2012).

## Further reading

- A. Babu, R. Almeida Gouvêa, G.-M. Rignanese, *Toward automated discovery with generative models multimodal
  learning and closed loop workflows in inverse materials design*, Cell Reports Physical Science **7**, 103561
  (2026). [doi:10.1016/j.xcrp.2026.103561](https://doi.org/10.1016/j.xcrp.2026.103561)
- A. Babu, N. M. A. Krishnan, *Multimodal and cross-modal learning techniques*, APL Machine Learning **4**, 030901
  (2026). [doi:10.1063/5.0346744](https://doi.org/10.1063/5.0346744)
