meidnet 2.4.0.dev2__py3-none-any.whl → 2.4.0.dev3__py3-none-any.whl

meidnet/__init__.py

@@ -17,4 +17,4 @@ Typical use (the same steps the ``meidnet`` command runs)::
     generate(cfg)     # design candidates (writes CIFs + generation_report.html)
 """
 
-__version__ = "2.4.0.dev2"
+__version__ = "2.4.0.dev3"

{meidnet-2.4.0.dev2.dist-info → meidnet-2.4.0.dev3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meidnet
-Version: 2.4.0.dev2
+Version: 2.4.0.dev3
 Summary: MEIDNet engine snapshot vendored by MEIDNet Matter: multimodal inverse design for crystalline materials
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -23,10 +23,10 @@ Requires-Dist: openpyxl>=3.1
 (upstream commit 26a0387862 plus the uncommitted work of the staged-evaluation rounds), and `meidnet_eval/` holds the
 evaluation components (the ten blocks and their bands in `stages.py`, the generation, judging, relaxation and
 calibration scripts).  Install with `pip install ./engine` **before** `pip install -e .`; the distribution is named
-`meidnet` (2.4.0.dev2) so the application's `meidnet>=2.2.0,<3` dependency resolves to it and nothing is fetched from PyPI.
+`meidnet` (2.4.0.dev3) so the application's `meidnet>=2.2.0,<3` dependency resolves to it and nothing is fetched from PyPI.
 
-On PyPI, `meidnet` 2.4.0.dev2 is this snapshot, uploaded by MEIDNet-Matter's release workflow so that `pip install meidnet-matter`
+On PyPI, `meidnet` 2.4.0.dev3 is this snapshot, uploaded by MEIDNet-Matter's release workflow so that `pip install meidnet-matter`
 resolves without a clone; the upstream MEIDNet release 2.4.0 (https://github.com/ABnano/MEIDNet) will replace it.
 
-Snapshot taken 2026-10-08.  To refresh it: `python scripts/vendor_engine.py --src <checkout>`.  The upstream release of this
+Snapshot taken 2026-10-09.  To refresh it: `python scripts/vendor_engine.py --src <checkout>`.  The upstream release of this
 work is planned as meidnet 2.4.0; when it exists, this folder is removed and the dependency pinned to that release.

{meidnet-2.4.0.dev2.dist-info → meidnet-2.4.0.dev3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-meidnet/__init__.py,sha256=QJ1fzSjr8ozynxR6WdOVI1p8AxSujXqsRuQA3wn2IyY,797
+meidnet/__init__.py,sha256=Excw9KoMB5C16gZ-V3HlLgNAJY87N4Xdk3uvjU6RrG0,797
 meidnet/__main__.py,sha256=7y_DSGhoKEkFQgmA2BZlaWRUGxRtE7KGr4585i3XG3g,138
 meidnet/benchmark.py,sha256=hHRo8yElEFliQ2INZNWn4ZOb25uSwJBmjwJrnnncfn8,26912
 meidnet/checkpoint.py,sha256=AmUGIz0BZynfZ0ndmIoMYh74gIq3Zn78pD7WhjrtbBY,8429
@@ -38,11 +38,11 @@ meidnet/studio/studio.html,sha256=TFH4RDVV6DPx5bUMeZP_IUQZxmPP-J54aMmPMce1ybQ,18
 meidnet_eval/__init__.py,sha256=e1Gl68TKQTg9_21rVZhMNPZarIZqVkVhYk1JJ10zOps,3589
 meidnet_eval/auto_family.py,sha256=aejS_M6R9Gr-ffTipV9BrQ6iY3LDakBBJVq2S-RySVw,16609
 meidnet_eval/candidate_cells.py,sha256=2ghXaeSsAWBKTJLABdb1D8RirYXXAdC0JmohEyJ5OxI,4598
-meidnet_eval/check_candidates.py,sha256=O4uPhSpHifWuAuFJFvEUd2xXt-F6g0n2P_cVu5xDLso,20459
+meidnet_eval/check_candidates.py,sha256=Ta6gpFd8GWNUinIc_XH4qqNeAPu2WYqvGanQWEtjMjI,21483
 meidnet_eval/component_report.py,sha256=hvRJ6Mt2B3M8r9xCPUQ8_XNzPNLgJC8EzI-6nddoe1s,12385
-meidnet_eval/conditional_generate.py,sha256=SdPopBQzJPksTv2wgsupfve9941aaf989RJOpqR-r1I,20034
+meidnet_eval/conditional_generate.py,sha256=5nS7zjeeqcHgUZ5WWM5SX83hhl6WYIdIX-i2q-SpF4M,20957
 meidnet_eval/d1_demo.py,sha256=0mM22XHZQN1wnkk2QmRVVKH_EcPQe50vRtUrxkjS3J8,9250
-meidnet_eval/d1_mlip_check.py,sha256=zQbMM6pOSvIoltWVX7C9kU_RHNTI_Q2uu06awzmJ8IU,8527
+meidnet_eval/d1_mlip_check.py,sha256=Nm2hd1ZXWdhFKN8xKh02cKZCWNPjkqfae3xqqnBgK3Y,10752
 meidnet_eval/decoder_autopsy.py,sha256=FgwYqR39YJbZARnMCZKBfVE3oHukDey_2HkWqWKkBcQ,5548
 meidnet_eval/discover.py,sha256=12uslj5MFiClifOEysnH93oBFWRd78dHTM19ZY6nyRk,41165
 meidnet_eval/discovery_report.py,sha256=tBHTpXexiv4ZZAK5yAYEhxJhk5lfVZTMFw1qfOn8zXc,6789
@@ -58,7 +58,7 @@ meidnet_eval/generate_to_target.py,sha256=kasRREFK-kxZLnWkyP5gVvNTU3zWRTjWy916ZH
 meidnet_eval/generator_vs_truth.py,sha256=AD8c7VYrdAWDND6LVEYE4H49brZlsUqJKiUJ2MXcu70,4466
 meidnet_eval/hull_mlip.py,sha256=kW9Rg8T124yEXBAn4T1S4yDjotABxSUegiXoiiso2ME,28256
 meidnet_eval/ingest_upload.py,sha256=cPcKNhsL3JJQMFVEzX2eO7FxX57p-e0-LmlHozZvLCQ,9803
-meidnet_eval/instrument_sheet.py,sha256=69B5Cw709qGH7hPJl8tkZs6ChCWifFdqOz1V47_FUkc,14771
+meidnet_eval/instrument_sheet.py,sha256=WcdVC5gt2ca6XI_x5fcx7AOoU4kNlTIcMZoNyDdbjYo,19219
 meidnet_eval/intake.py,sha256=rJq_b7B1PF6i2zmIBAapTrLTjUuUI7YYQ7FygASuqSw,7378
 meidnet_eval/journey.py,sha256=MpaNWWe3-Rypu2zMdIwp8is_4N5YOtrEt2t0Z-nvaQI,3667
 meidnet_eval/judge_consensus.py,sha256=wKmnP9gIvH_uMozQtsu3G11xa0sLC4WHUzkVtMHOIyw,6196
@@ -68,13 +68,13 @@ meidnet_eval/mixed_anion_coverage.py,sha256=YHXuGoVaU6jN8NZi8PulF1LGvy4BJnymHDY7
 meidnet_eval/model_metrics.py,sha256=Hk8WdBqV_vO3kUm6w1cW6E5tdOcSx4inhtXtApuOKYw,4776
 meidnet_eval/mp_perovskite_dataset.py,sha256=3lWp7hhBNDm0p4Yi90xEPQ0zovKTZWfn8lGlatOCCrI,6079
 meidnet_eval/perovskite_geometry.py,sha256=o6yZpXNhKPBk5ISCK_Ub-1EyOTkgiKDAW5VJVrjuwUE,2752
-meidnet_eval/pipeline_checkup.py,sha256=fMVzCnXjg-8byfL7aNeG2iofH863qMSuTh5oZ5cegd8,22348
+meidnet_eval/pipeline_checkup.py,sha256=Ydg2YMgzFDu6N5dNeCeAFAQgoINS0ZS0A4ctnL3OOy4,22521
 meidnet_eval/plot_ablation.py,sha256=vqqyDTgC_BCvKf_7e45x2qQe9mu_Rg6JGieCwS0r12U,4316
 meidnet_eval/prefetch_mp.py,sha256=uzO44j1Q3j-9BwhBoDDY_l3y_19HfgB4Lml4URc6Yu4,1447
 meidnet_eval/preview.py,sha256=FucAbUzi1J_bW9_RbwL8M4THhW3s9q2PqnIWIJk5jAI,9882
 meidnet_eval/relax_cache.py,sha256=HhOUlLWpHRBHIkUGq-St8x8c_zw-NyZ1iRyVnrSsuIg,2525
 meidnet_eval/reliability_map.py,sha256=06XhRdGY5utzxlR_SuhwhUUR7IHYybOWQ2Js2Gseemw,10869
-meidnet_eval/scorecard.py,sha256=RTS-g2Atc6y0AcLUxyJ4n35rJREA6zsxRvTWBVKt04Y,15500
+meidnet_eval/scorecard.py,sha256=jne3Ib1LNn7TSBHUS3a9IqPEbFmolzSwg39giodbg9Q,18619
 meidnet_eval/screen_local.py,sha256=ZJO8nOiNthwV5A9fYZK9zy-zy3lg1FMotwTyFlu-_h0,12665
 meidnet_eval/screen_polymorphs.py,sha256=txc6V5Qf-AmL4RNVEjGDZUOtUVEwr4C9Vn7c0LI5eew,15832
 meidnet_eval/stability_distorted.py,sha256=VnhFEgaX5rUoWPv5DfMteQf08P0Rt5NR2CQ36wO_QrQ,3680
@@ -84,8 +84,8 @@ meidnet_eval/sun_validate.py,sha256=DcJmxk0_KM52HmQvrgkg6G3Eztg89PuuwraJTQqrHVk,
 meidnet_eval/target_calibration.py,sha256=KzuM2fZY8MOhZ5jXN_z6PgtTqqXvlYeMcxbYqsK_QWg,11629
 meidnet_eval/unseen_element_test.py,sha256=PZYPZWJBNHpxAjvW9UZ4ZbIZynNQIsnkIx1tRQ1mIoE,3098
 meidnet_eval/wyckoff_targets.py,sha256=yXiHEPaxfdS9sUXfWicydRZvCezcFLV1SQmKK9HPWb4,5494
-meidnet-2.4.0.dev2.dist-info/METADATA,sha256=eieT-qLmVXmyQg1HiZ120YLfvcsSYKZ_6zAEtG69SwM,1676
-meidnet-2.4.0.dev2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-meidnet-2.4.0.dev2.dist-info/entry_points.txt,sha256=N0rGAumst_v4exbrTZn_K1-zvBIPzkLd6cO8NbP98LY,45
-meidnet-2.4.0.dev2.dist-info/top_level.txt,sha256=zVMmF3NOP2ZV2soL4l2UaYHqPwvHTKoybycSDjawOpw,21
-meidnet-2.4.0.dev2.dist-info/RECORD,,
+meidnet-2.4.0.dev3.dist-info/METADATA,sha256=wln2GnKHzos0n2vlrdobpLIw2sgPvLBoTodJljBEYSg,1676
+meidnet-2.4.0.dev3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+meidnet-2.4.0.dev3.dist-info/entry_points.txt,sha256=N0rGAumst_v4exbrTZn_K1-zvBIPzkLd6cO8NbP98LY,45
+meidnet-2.4.0.dev3.dist-info/top_level.txt,sha256=zVMmF3NOP2ZV2soL4l2UaYHqPwvHTKoybycSDjawOpw,21
+meidnet-2.4.0.dev3.dist-info/RECORD,,

meidnet_eval/check_candidates.py

@@ -6,7 +6,8 @@ table of structures and the band gap each was asked for.  This command gives eve
   1 label     the model's own label, read from each returned cell (re-encoded), never from the search
   2 judge     the independent judge (MEGNet), qualified on the held-out split first; two-model consensus in the window
   3 relax     the consensus cells relaxed by two potentials of different architecture (TensorNet, CHGNet); a relaxed cell
-              whose closest atoms sit nearer than 0.6 of their radii is collapsed, not a crystal, and goes no further
+              whose closest atoms sit nearer than 0.6 of their radii is collapsed, not a crystal, and goes no further;
+              nor does one with an empty layer thicker than 6 A or a packing fraction below 0.12 (a slab or a sparse cell)
   4 re-judge  both readings again on the relaxed cells; the consensus on those is the deliverable
   5 stable    optional: energy above the convex hull, one potential for every phase (hull_mlip.py --reference ...)
   6 novel     AMD distance to the nearest structure of the data; known compositions carry the data's own values
@@ -140,26 +141,34 @@ def check(out, ckpt, intake, gap, window=0.5, test_csv=None, relax="tensornet",
         rel = os.path.join(out, "relaxed"); os.makedirs(os.path.join(rel, "cifs"), exist_ok=True)
         from pymatgen.core import Structure
         try:
-            from meidnet_eval.d1_mlip_check import COLLAPSED, contact_ratio
+            from meidnet_eval.d1_mlip_check import COLLAPSED, bulk_problem, contact_ratio, empty_layer, packing_fraction
         except ImportError:
             sys.path.insert(0, HERE)
-            from d1_mlip_check import COLLAPSED, contact_ratio
-        kept, collapsed = [], []
+            from d1_mlip_check import COLLAPSED, bulk_problem, contact_ratio, empty_layer, packing_fraction
+        kept, collapsed, not_bulk = [], [], []
         for _, r in c0.iterrows():
             src = os.path.join(rdir, "relaxed_tensornet", os.path.basename(r["file"]))
             if os.path.exists(src):
                 # a potential can drive atoms into each other and still report a low energy: such a cell is not judged again
-                ratio = contact_ratio(Structure.from_file(src))
+                s_rel = Structure.from_file(src)
+                ratio = contact_ratio(s_rel)
                 if ratio < COLLAPSED:
                     collapsed.append({"file": os.path.basename(r["file"]), "formula": r.get("formula"), "target": float(r["target"]),
                                       "contact_ratio": round(ratio, 2)})
                     continue
+                # nor is a slab or a sparse cage a bulk crystal: its band gap is not one
+                why = bulk_problem(s_rel)
+                if why:
+                    not_bulk.append({"file": os.path.basename(r["file"]), "formula": r.get("formula"), "target": float(r["target"]),
+                                     "reason": why, "empty_layer": round(empty_layer(s_rel), 2), "packing": round(packing_fraction(s_rel), 3)})
+                    continue
                 shutil.copyfile(src, os.path.join(rel, "cifs", os.path.basename(r["file"])))
                 r = dict(r); r["file"] = "cifs/" + os.path.basename(r["file"]); kept.append(r)
         c1 = pd.DataFrame(kept, columns=list(c0.columns))
         c1.to_csv(os.path.join(rel, "candidates.csv"), index=False)
         report["stages"]["3_relaxed"] = int(len(c1))
         report["collapsed_on_relaxation"] = collapsed
+        report["not_bulk_on_relaxation"] = not_bulk
         if len(c1):
             run(py_model, "target_calibration.py", rel, "--judge", "reencode", "--ckpt", ckpt, "--gap-col", gap, log=log)
             run(py_judge, "target_calibration.py", rel, "--test-csv", test_csv, "--gap-col", gap, "--judge", "megnet",
@@ -239,6 +248,9 @@ def check(out, ckpt, intake, gap, window=0.5, test_csv=None, relax="tensornet",
     if report.get("collapsed_on_relaxation"):
         L += ["", "Collapsed on relaxation, not judged again (closest atoms as a share of their two radii; a sound crystal is near 1): "
               + ", ".join(f"{c['formula']} at {c['target']:g} eV ({c['contact_ratio']:.2f})" for c in report["collapsed_on_relaxation"]) + "."]
+    if report.get("not_bulk_on_relaxation"):
+        L += ["", "Not a bulk crystal after relaxation, not judged again: "
+              + ", ".join(f"{c['formula']} at {c['target']:g} eV ({c['reason']})" for c in report["not_bulk_on_relaxation"]) + "."]
     q = report.get("judge") or {}
     if q:
         L += ["", f"Judge: MEGNet fidelity {q.get('fidelity')}, qualified on {q.get('split')}: MAE {q.get('mae', float('nan')):.2f} eV, "

meidnet_eval/conditional_generate.py

@@ -121,13 +121,25 @@ def structure_label(lm, s):
 
 
 def plausible(s, min_d=0.7, max_vol_per_atom=200.0):
-    """Reject cells that cannot be a material at all, so the judges are not asked to score nonsense."""
+    """Reject cells that cannot be a material at all, so the judges are not asked to score nonsense: atoms on top of each
+    other, an implausible volume, or a slab or sparse cage (d1_mlip_check.bulk_problem), which relaxation does not turn
+    into a bulk crystal.  Atoms closer than 0.6 of their radii are not rejected here: relaxation repairs a third of such
+    cells, so that test is made on the relaxed cell."""
+    try:
+        from meidnet_eval.d1_mlip_check import MAX_EMPTY_LAYER, MIN_PACKING, empty_layer, packing_fraction
+    except ImportError:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        from d1_mlip_check import MAX_EMPTY_LAYER, MIN_PACKING, empty_layer, packing_fraction
     try:
         if s.volume / len(s) > max_vol_per_atom or s.volume / len(s) < 2.0:
             return False, "implausible volume per atom"
         d = s.distance_matrix + np.eye(len(s)) * 99
         if len(s) > 1 and d.min() < min_d:
             return False, f"atoms {d.min():.2f} A apart"
+        if empty_layer(s) > MAX_EMPTY_LAYER:
+            return False, f"empty layer thicker than {MAX_EMPTY_LAYER:g} A (a slab, not a bulk crystal)"
+        if packing_fraction(s) < MIN_PACKING:
+            return False, f"packing fraction below {MIN_PACKING:g} (too little matter for a bulk crystal)"
         return True, ""
     except Exception as e:
         return False, type(e).__name__

meidnet_eval/d1_mlip_check.py

@@ -4,7 +4,8 @@ Two potentials of different architecture (TensorNet and CHGNet, both trained on
 agreeing with itself is not evidence.  Per candidate: whether each relaxed at all, the energy per atom, how far the
 energy fell on relaxation (a sound structure falls by less than 0.1 eV/atom), how far atoms moved, whether the designed
 space group survived, the shortest interatomic distance afterwards, that distance as a share of the two atoms' radii (below
-0.6 the cell collapsed: COLLAPSED, contact_ratio) and whether the optimiser converged before the step limit.  The relaxed cells are kept, because a band gap
+0.6 the cell collapsed: COLLAPSED, contact_ratio), the thickest empty layer and the packing fraction (a slab or a sparse cell
+is not a bulk crystal: bulk_problem) and whether the optimiser converged before the step limit.  The relaxed cells are kept, because a band gap
 judged on a cell that then moves by an angstrom describes no material: the judges must be re-run on the relaxed cell.
 
 Usage: python d1_mlip_check.py RESULTS_DIR [--cifs-dir DIR] [--steps 300] [--shard 0 --nshards 1] [--subset N]
@@ -68,9 +69,8 @@ def spacegroup(s):
 COLLAPSED = 0.6
 
 
-def contact_ratio(s):
-    """The shortest interatomic distance divided by the sum of the two atoms' radii (pymatgen's atomic radii), images of an
-    atom included: about 1 in a sound crystal, below COLLAPSED when atoms were pushed into each other."""
+def _radii(s):
+    """pymatgen's atomic radius of every site (1.5 A when the element has none)."""
     from pymatgen.core import Element
     rad = []
     for site in s:
@@ -83,7 +83,13 @@ def contact_ratio(s):
         except Exception:
             r = None
         rad.append(float(r) if r else 1.5)
-    rad = np.array(rad)
+    return np.array(rad)
+
+
+def contact_ratio(s):
+    """The shortest interatomic distance divided by the sum of the two atoms' radii (pymatgen's atomic radii), images of an
+    atom included: about 1 in a sound crystal, below COLLAPSED when atoms were pushed into each other."""
+    rad = _radii(s)
     ratio = float(min(s.lattice.get_lll_reduced_lattice().abc) / (2 * rad.max()))
     if len(s) > 1:
         d = s.distance_matrix + np.eye(len(s)) * 99
@@ -91,6 +97,44 @@ def contact_ratio(s):
     return ratio
 
 
+# A cell with a thick empty layer is a slab, and one with little matter in it a sparse cage: the band gap of either is not
+# that of a bulk crystal.  Calibrated on all 45,229 known MP-20 crystals (meidnet_journey/gate_calibration): 99% have no
+# empty layer thicker than 4.25 A, 0.84% have one above 6 A (nearly all layered sulfides and selenides whose layers a PBE
+# relaxation pushed apart), and 0.48% have a packing fraction below 0.12 (molecular solids such as PCl5).  Relaxation does not
+# remove either: in the MP-20 study every generated cell beyond these lines was still beyond them after relaxation.
+MAX_EMPTY_LAYER = 6.0
+MIN_PACKING = 0.12
+
+
+def empty_layer(s):
+    """The thickest empty layer between atomic planes, in A: along each lattice direction of the LLL-reduced cell, the widest
+    gap between consecutive fractional coordinates times the spacing of those planes."""
+    s = s.get_reduced_structure()
+    spacing = 1.0 / np.array(s.lattice.reciprocal_lattice_crystallographic.abc)
+    widest = 0.0
+    for i in range(3):
+        f = np.sort(np.mod(s.frac_coords[:, i], 1.0))
+        widest = max(widest, float(np.diff(np.concatenate([f, [f[0] + 1.0]])).max() * spacing[i]))
+    return widest
+
+
+def packing_fraction(s):
+    """The volume of the atoms' spheres (pymatgen's atomic radii) over the volume of the cell."""
+    return float((4.0 / 3.0 * np.pi * _radii(s) ** 3).sum() / s.volume)
+
+
+def bulk_problem(s):
+    """'' for a cell that can be a bulk crystal, else why not: an empty layer thicker than MAX_EMPTY_LAYER or a packing
+    fraction below MIN_PACKING."""
+    layer = empty_layer(s)
+    if layer > MAX_EMPTY_LAYER:
+        return f"empty layer {layer:.1f} A (a slab, not a bulk crystal)"
+    pack = packing_fraction(s)
+    if pack < MIN_PACKING:
+        return f"packing fraction {pack:.2f} (too little matter for a bulk crystal)"
+    return ""
+
+
 def relax_one(s0, name, steps, fmax=0.05):
     """One cell, one potential -> the relaxed structure and its record."""
     res = relaxer(name).relax(s0, fmax=fmax, steps=steps)
@@ -103,6 +147,7 @@ def relax_one(s0, name, steps, fmax=0.05):
            # matgl records the start, every step and the end: a run stopped by the step limit holds steps + 2 frames
            f"{name}_converged": bool(len(traj.energies) < steps + 1),
            f"{name}_contact_ratio": round(contact_ratio(s1), 3),
+           f"{name}_empty_layer": round(empty_layer(s1), 2), f"{name}_packing": round(packing_fraction(s1), 3),
            f"{name}_ok": True}
     return s1, rec
 

meidnet_eval/instrument_sheet.py

@@ -3,11 +3,13 @@
 Stated the way a measuring device is specified: response curve, bias, precision, accuracy with a confidence interval,
 linearity, resolution between adjacent requests, serviceable range, yield per stage, plus the stability proxy and the
 novelty of the delivered cells.  Everything is read from the result folders a run leaves behind.  A relaxed cell that
-collapsed (closest atoms nearer than 0.6 of their radii) describes no material: it is counted in the funnel and listed,
-and its gap is left out of every number.
+collapsed (closest atoms nearer than 0.6 of their radii) describes no material, and one with an empty layer thicker than
+6 A or a packing fraction below 0.12 is a slab or a sparse cage, not a bulk crystal: each is counted in the funnel and
+listed, and its gap is left out of every number.  The judge's error before relaxation is also given on the same cells
+as after it, so the two can be compared.
 
 Usage: python instrument_sheet.py --pool DIR --relaxed DIR --consensus DIR --out DIR [--window 0.5] [--min-gap 0.1]
-       [--sun FILE] [--sun-per-candidate FILE] [--known-formulas FILE]
+       [--sun FILE] [--sun-per-candidate FILE] [--known-formulas FILE] [--reference-intake DIR]
 """
 import argparse, glob, json, os
 
@@ -30,11 +32,15 @@ def load(a):
         rel["contact_ratio"] = rel["file"].map(lambda f: _contact(a, f))
         collapsed = rel[rel["contact_ratio"] < _collapsed_line()]
         rel = rel.drop(collapsed.index)
+        # nor is a slab or a sparse cage a bulk crystal: left out the same way
+        rel["bulk_problem"] = rel["file"].map(lambda f: _bulk_problem(a, f))
+        not_bulk = rel[rel["bulk_problem"] != ""]
+        rel = rel.drop(not_bulk.index)
     else:                                   # no relaxed folder: the sheet describes the generated (unrelaxed) cells and says so
         rel = cons.copy()
         rel["label_structure"] = rel.get("label_gap", rel.get("label_structure_gap"))
         rel["judge"] = rel["file"].map(lambda f: pcal["per_candidate"].get(f, {}).get("independent_gap"))
-        collapsed = rel.iloc[0:0]
+        collapsed = not_bulk = rel.iloc[0:0]
     mlip = [r for f in glob.glob(f"{a.consensus}/mlip_shard*.json") for r in json.load(open(f))] if a.consensus else []
     drop = {os.path.basename(r["file"]): r.get("tensornet_drop_per_atom") for r in mlip}
     kept = {os.path.basename(r["file"]): r.get("tensornet_spacegroup_relaxed") == r.get("spacegroup_designed") for r in mlip}
@@ -45,7 +51,7 @@ def load(a):
         if os.path.exists(cand):
             sun = json.load(open(cand))
             break
-    return pool, pcal, cons, rel, sun, collapsed
+    return pool, pcal, cons, rel, sun, collapsed, not_bulk
 
 
 def _collapsed_line():
@@ -56,21 +62,37 @@ def _collapsed_line():
     return COLLAPSED
 
 
-def _contact(a, f):
-    """Contact ratio of the relaxed cell behind a candidates-table row (the relaxed folder's copy, else the relaxer's own)."""
-    try:
-        from meidnet_eval.d1_mlip_check import contact_ratio
-    except ImportError:
-        from d1_mlip_check import contact_ratio
+def _relaxed_cell(a, f):
+    """The relaxed cell behind a candidates-table row (the relaxed folder's copy, else the relaxer's own), or None."""
     from pymatgen.core import Structure
     for p in ([os.path.join(a.relaxed, f)] if a.relaxed else []) + \
              ([os.path.join(a.consensus, "relaxed_tensornet", os.path.basename(f))] if a.consensus else []):
         if os.path.exists(p):
             try:
-                return contact_ratio(Structure.from_file(p))
+                return Structure.from_file(p)
             except Exception:
-                return np.nan
-    return np.nan
+                return None
+    return None
+
+
+def _contact(a, f):
+    """Contact ratio of the relaxed cell behind a candidates-table row."""
+    try:
+        from meidnet_eval.d1_mlip_check import contact_ratio
+    except ImportError:
+        from d1_mlip_check import contact_ratio
+    s = _relaxed_cell(a, f)
+    return contact_ratio(s) if s is not None else np.nan
+
+
+def _bulk_problem(a, f):
+    """'' when the relaxed cell behind a row can be a bulk crystal, else why not (empty layer, packing)."""
+    try:
+        from meidnet_eval.d1_mlip_check import bulk_problem
+    except ImportError:
+        from d1_mlip_check import bulk_problem
+    s = _relaxed_cell(a, f)
+    return bulk_problem(s) if s is not None else ""
 
 
 def per_target(pool, cons, ok, final):
@@ -97,20 +119,51 @@ def per_target(pool, cons, ok, final):
     return rows
 
 
-def classify(known: bool, amd: float | None) -> str:
-    """What relaxation revealed: a known structure found again, a new polymorph of a known formula, or a new composition."""
-    if known and amd is not None and amd < 0.3:
-        return "rediscovered known structure"
-    if known and amd is not None and amd < 0.35:
-        return "rediscovered (borderline)"
-    if known:
-        return "new polymorph of known formula"
-    return "new composition, new structure"
+def classify(known: bool, match_id: str | None, compared: bool = True) -> str:
+    """What relaxation revealed: a known structure found again (its structure matches an entry of the same formula), a new
+    polymorph of a known formula, or a new composition.  Without a structure comparison a known formula is only that."""
+    if not known:
+        return "new composition, new structure"
+    if not compared:
+        return "known formula (structure not compared)"
+    return "rediscovered known structure" if match_id else "new polymorph of known formula"
+
+
+def same_formula_match(structure, intake: str, cache: dict) -> str | None:
+    """The id of the first entry of the intake (train/val/test CSVs with a cif column) with the same reduced formula whose
+    structure matches (pymatgen StructureMatcher, default tolerances, volumes scaled), else None.  Every entry of that
+    formula is compared, not a sample, and no entry of another composition can match."""
+    from pymatgen.analysis.structure_matcher import StructureMatcher
+    from pymatgen.core import Composition, Structure
+    if "by_formula" not in cache:
+        rows = {}
+        for split in ("train", "val", "test"):
+            p = os.path.join(intake, f"{split}.csv")
+            if not os.path.exists(p):
+                continue
+            t = pd.read_csv(p)
+            ids = t["material_id"].astype(str) if "material_id" in t.columns else pd.Series([f"{split}-{i}" for i in range(len(t))])
+            for mid, cif, fml in zip(ids, t["cif"], t["formula"] if "formula" in t.columns else [None] * len(t)):
+                try:
+                    key = Composition(fml).reduced_formula if isinstance(fml, str) else Structure.from_str(cif, fmt="cif").composition.reduced_formula
+                except Exception:
+                    continue
+                rows.setdefault(key, []).append((mid, cif))
+        cache["by_formula"] = rows
+    matcher = StructureMatcher()
+    for mid, cif in cache["by_formula"].get(structure.composition.reduced_formula, []):
+        try:
+            if matcher.fit(structure, Structure.from_str(cif, fmt="cif")):
+                return mid
+        except Exception:
+            continue
+    return None
 
 
 def accepted_table(final, a) -> pd.DataFrame:
     """One row per accepted material with the evidence a reader needs: both gaps on the relaxed cell, the AMD distance,
-    whether the formula exists in the training data (and at which recorded gaps), the class, and a charge-balance flag."""
+    whether the formula exists in the training data (and at which recorded gaps), the class (with the matching entry when the
+    structure was compared), and a charge-balance flag."""
     amd, by_file = {}, False
     if a.sun_per_candidate and os.path.exists(a.sun_per_candidate):
         t = pd.read_csv(a.sun_per_candidate)
@@ -123,11 +176,16 @@ def accepted_table(final, a) -> pd.DataFrame:
         import gzip
         opener = gzip.open if a.known_formulas.endswith(".gz") else open
         known = json.load(opener(a.known_formulas, "rt"))
-    rows = []
+    rows, cache = [], {}
+    compare = bool(getattr(a, "reference_intake", None))
     for _, r in final.sort_values(["target", "formula"]).iterrows():
         d = amd.get(os.path.basename(str(r["file"]))) if by_file else amd.get(r["formula"])
         d = None if d is None or d != d else float(d)
         is_known = r["formula"] in known if known else None
+        match = None
+        if is_known and compare:
+            s = _relaxed_cell(a, r["file"])
+            match = same_formula_match(s, a.reference_intake, cache) if s is not None else None
         try:
             from pymatgen.core import Composition
             balanced = bool(Composition(r["formula"]).oxi_state_guesses(max_sites=-1))
@@ -136,13 +194,20 @@ def accepted_table(final, a) -> pd.DataFrame:
         rows.append(dict(requested=float(r["target"]), formula=r["formula"], label_structure=round(float(r["label_structure"]), 3),
                          judge=round(float(r["judge"]), 3), amd_nearest=None if d is None else round(d, 3),
                          known_formula=is_known, recorded_gaps=",".join(f"{g:.2f}" for g in known.get(r["formula"], [])) if known else "",
-                         cls=classify(bool(is_known), d) if is_known is not None else "",
+                         cls=classify(bool(is_known), match, compare) if is_known is not None else "", reference_id=match or "",
                          charge_balanced=balanced, drop_eV_atom=r.get("drop"), spacegroup_kept=r.get("sg_kept"),
                          natoms=int(r["natoms"]) if "natoms" in r else None, file=r.get("file"),
                          flag="judges disagree" if abs(float(r["label_structure"]) - float(r["judge"])) > 0.5 else ""))
     return pd.DataFrame(rows).rename(columns={"cls": "class"})
 
 
+def _mae_before(pool, ok):
+    """The judge's error on the generated (unrelaxed) versions of the cells that make up the relaxed set."""
+    names = set(ok["file"].map(os.path.basename))
+    same = pool[pool["file"].map(os.path.basename).isin(names)].dropna(subset=["judge_generated"])
+    return float(np.abs(same["judge_generated"] - same["target"]).mean()) if len(same) else None
+
+
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--pool", required=True, help="the generation folder (candidates.csv, calibration.json, candidates_consensus.csv)")
@@ -156,9 +221,11 @@ def main():
     ap.add_argument("--sun", default=None, help="metrics_sun JSON for the novelty line (default: the relaxed folder's sun_relaxed_strict.json or sun.json)")
     ap.add_argument("--sun-per-candidate", default=None, help="metrics_sun per-candidate CSV (adds the AMD distance per material)")
     ap.add_argument("--known-formulas", default=None, help="JSON {reduced formula: [gaps]} of the training data (adds known/new and the recorded gaps)")
+    ap.add_argument("--reference-intake", default=None, help="the intake folder (train/val/test CSVs with a cif column): a known formula is called "
+                                                              "rediscovered only when its relaxed cell matches an entry of that formula (StructureMatcher)")
     a = ap.parse_args()
     os.makedirs(a.out, exist_ok=True)
-    pool, pcal, cons, rel, sun, collapsed = load(a)
+    pool, pcal, cons, rel, sun, collapsed, not_bulk = load(a)
 
     ok = rel.dropna(subset=["label_structure", "judge"]).copy()
     in_window = (abs(ok["label_structure"] - ok["target"]) <= a.window) & (abs(ok["judge"] - ok["target"]) <= a.window)
@@ -184,12 +251,15 @@ def main():
     sheet = dict(
         window_eV=a.window, metal_floor_eV=a.min_gap,
         funnel=dict(generated=int(len(pool)), both_judges=int(len(cons)), collapsed_on_relaxation=int(len(collapsed)),
-                    relaxed=int(len(ok)), final=int(len(final))),
+                    not_bulk_on_relaxation=int(len(not_bulk)), relaxed=int(len(ok)), final=int(len(final))),
         collapsed_on_relaxation=[dict(formula=r["formula"], target=float(r["target"]), contact_ratio=round(float(r["contact_ratio"]), 2))
                                  for _, r in collapsed.iterrows()],
+        not_bulk_on_relaxation=[dict(formula=r["formula"], target=float(r["target"]), reason=r["bulk_problem"]) for _, r in not_bulk.iterrows()],
         judge=pcal.get("judge_qualification"),
         per_target=rows,
         accuracy=dict(mae_generated_cells=float(np.abs(pool["judge_generated"] - pool["target"]).mean()),
+                      # the same cells before relaxation, so that before and after compare like with like
+                      mae_same_cells_before_relaxation=_mae_before(pool, ok), same_cells=int(len(ok)),
                       mae_relaxed_cells=float(np.abs(y - x).mean()),
                       mae_relaxed_ci95=[float(np.percentile(boots, 2.5)), float(np.percentile(boots, 97.5))],
                       within_window=int((np.abs(y - x) <= a.window).sum()), of=int(len(x))),
@@ -220,7 +290,10 @@ def main():
     acc, lin = sheet["accuracy"], sheet["linearity"]
     cells = sheet.get("cells", "relaxed")
     print(f"\ncells: {cells}")
-    print(f"accuracy: MAE generated {acc['mae_generated_cells']:.2f} -> {'relaxed' if cells == 'relaxed' else 'kept (unrelaxed)'} {acc['mae_relaxed_cells']:.2f} eV "
+    before = acc["mae_same_cells_before_relaxation"]
+    print(f"accuracy: MAE on all generated cells {acc['mae_generated_cells']:.2f} eV; on the same {acc['same_cells']} cells "
+          + (f"{before:.2f} before relaxation -> " if before is not None else "")
+          + f"{'relaxed' if cells == 'relaxed' else 'kept (unrelaxed)'} {acc['mae_relaxed_cells']:.2f} eV "
           f"(95% CI {acc['mae_relaxed_ci95'][0]:.2f}-{acc['mae_relaxed_ci95'][1]:.2f}); within {a.window} eV: {acc['within_window']} of {acc['of']}")
     if len(x) >= 3 and lin["slope"] == lin["slope"]:
         print(f"linearity: delivered = {lin['intercept']:.2f} + {lin['slope']:.2f} x requested (R2 {lin['r2']:.2f}, Spearman {lin['spearman']:.2f}); ideal 0 + 1.00 x")

meidnet_eval/pipeline_checkup.py

@@ -173,6 +173,7 @@ def main():
     ap.add_argument("--family", default=None, help="family for the design-space checks of stage 0 (default: the Perov-5 demo "
                     "family); 'none' skips them, e.g. when discover.py checks the design space in its own stage")
     ap.add_argument("--variant", default="oxide")
+    ap.add_argument("--out-dir", default=None, help="where <tag>.json and <tag>.md go (default: results/checkups beside this file)")
     a = ap.parse_args()
     torch.set_num_threads(int(os.environ.get("OMP_NUM_THREADS", "4")))
     t0 = time.time()
@@ -288,7 +289,7 @@ def main():
                 def decode(self, Z, *x, **k):
                     pops.append(Z.clone()); return super().decode(Z, *x, **k)
             d = D(lm, fam_t, cfg.generation, device=torch.device("cpu"), log=lambda *x: None, reference_latents=ref)
-            res = d.run(os.path.join(HERE, "results", "checkups", f"{a.tag}_search", f"T{tgt:g}"), ranges=property_ranges(lm))
+            res = d.run(os.path.join(a.out_dir or os.path.join(HERE, "results", "checkups"), f"{a.tag}_search", f"T{tgt:g}"), ranges=property_ranges(lm))
             Zall.append(torch.cat(pops).numpy())
             for c in res.saved:
                 cand = build_candidate(fam_t, c.elements)
@@ -328,7 +329,7 @@ def main():
         else:
             add("6 end-to-end", "returned structures follow the target (DFT)", "FAIL", "no candidate returned for any target", value=None)
 
-    out_dir = os.path.join(HERE, "results", "checkups"); os.makedirs(out_dir, exist_ok=True)
+    out_dir = a.out_dir or os.path.join(HERE, "results", "checkups"); os.makedirs(out_dir, exist_ok=True)
     json.dump(dict(tag=a.tag, ckpt=a.ckpt, switches=dict(label_source=a.label_source, latent_space=a.latent_space,
                    manifold_weight=a.manifold_weight), thresholds=THRESHOLDS, checks=checks, data=data,
                    seconds=time.time() - t0), open(f"{out_dir}/{a.tag}.json", "w"), indent=1, default=float)

meidnet_eval/scorecard.py

@@ -31,10 +31,16 @@ FID = os.environ.get("MEIDNET_FIDELITY_DIR", "")   # the CGCNN judge checkout, w
 PY = sys.executable
 
 
-def run(cmd, env, log):
+def run(cmd, env, log, cwd):
+    """One component, from a work folder inside --out (never the package's own folder) by its absolute path; its exit
+    status is returned and recorded in the log."""
+    if cmd[1].endswith(".py") and not os.path.isabs(cmd[1]):
+        cmd = [cmd[0], os.path.join(HERE, cmd[1]), *cmd[2:]]
+    os.makedirs(cwd, exist_ok=True)
     with open(log, "a") as f:
         f.write(f"\n$ {' '.join(cmd)}\n"); f.flush()
-        r = subprocess.run(cmd, cwd=HERE, env=env, stdout=f, stderr=subprocess.STDOUT)
+        r = subprocess.run(cmd, cwd=cwd, env=env, stdout=f, stderr=subprocess.STDOUT)
+        f.write(f"[exit {r.returncode}]\n")
     return r.returncode
 
 
@@ -44,14 +50,26 @@ def collect(out, name, intake, ckpt, gap, cost, targets, env, skip):
     mj = os.path.join(out, f"metrics_{name}.json")
     dj = os.path.join(out, f"decoder_{name}.json")
     log = os.path.join(out, "diagnostics.log")
+    work = os.path.join(out, "_work")
+    failed = []
     if not skip:
-        run([PY, "pipeline_checkup.py", f"sc_{name}", ckpt, "--label-source", "structure", "--latent-space", "sphere",
-             "--skip-search", "--family", "none"], env, log)
-        src = os.path.join(HERE, "results", "checkups", f"sc_{name}.json")
-        if os.path.exists(src):
+        # results of an earlier run (another model, perhaps) must never stand in for this one: clear them first
+        src = os.path.join(work, "checkups", f"sc_{name}.json")
+        for stale in (cj, mj, dj, src):
+            if os.path.exists(stale):
+                os.remove(stale)
+        rc = run([PY, "pipeline_checkup.py", f"sc_{name}", ckpt, "--label-source", "structure", "--latent-space", "sphere",
+                  "--skip-search", "--family", "none", "--out-dir", os.path.join(work, "checkups")], env, log, work)
+        if rc == 0 and os.path.exists(src):
             json.dump(json.load(open(src)), open(cj, "w"), indent=1)
-        run([PY, "model_metrics.py", f"sc_{name}", ckpt, mj, intake], env, log)
-        run([PY, "decoder_autopsy.py", ckpt, "--data", intake, "--json", dj], env, log)
+        else:
+            failed.append(f"pipeline_checkup.py (exit {rc})")
+        rc = run([PY, "model_metrics.py", f"sc_{name}", ckpt, mj, intake], env, log, work)
+        if rc != 0 or not os.path.exists(mj):
+            failed.append(f"model_metrics.py (exit {rc})")
+        rc = run([PY, "decoder_autopsy.py", ckpt, "--data", intake, "--json", dj], env, log, work)
+        if rc != 0 or not os.path.exists(dj):
+            failed.append(f"decoder_autopsy.py (exit {rc})")
 
     v, raw = {}, {}
     if os.path.exists(mj):
@@ -87,6 +105,7 @@ def collect(out, name, intake, ckpt, gap, cost, targets, env, skip):
                 v["head_length_sensitivity"] = val
     if os.path.exists(dj):
         raw["decoder"] = json.load(open(dj))
+    raw["failed"] = failed
     return {k: x for k, x in v.items() if x is not None}, raw
 
 
@@ -101,8 +120,19 @@ def main():
     ap.add_argument("--judge-n", type=int, default=80)
     ap.add_argument("--out", required=True); ap.add_argument("--skip-run", action="store_true")
     a = ap.parse_args()
+    # absolute paths: the components run from a work folder, and a relative path must mean what the user meant
+    a.intake, a.out = os.path.abspath(a.intake), os.path.abspath(a.out)
     os.makedirs(a.out, exist_ok=True)
-    models = dict(m.split("=", 1) for m in a.models)
+    models = {k: os.path.abspath(v) for k, v in (m.split("=", 1) for m in a.models)}
+    if not a.cost:                                 # the second property, when the intake has an obvious one
+        try:
+            cols = [c for c in pd.read_csv(os.path.join(a.intake, "train.csv"), nrows=1).columns if c != a.gap]
+            cands = [c for c in cols if any(w in c.lower() for w in ("formation", "heat", "e_form", "dhf"))]
+            if len(cands) == 1:
+                a.cost = cands[0]
+                print(f"--cost not given: using the intake's {a.cost}", flush=True)
+        except Exception:
+            pass
     if "main" not in models:                       # the first model named is the one every block is computed for
         first = next(iter(models))
         print(f"no model is named 'main': treating '{first}' as the main model (control= and seed1= are the comparisons)", flush=True)
@@ -118,6 +148,8 @@ def main():
             print(f"  {name}: checkpoint missing ({ckpt}) — skipped", flush=True); continue
         print(f"running diagnostics for {name} ...", flush=True)
         measured[name], raws[name] = collect(a.out, name, a.intake, ckpt, a.gap, a.cost, a.targets, env, a.skip_run)
+    if "main" not in measured:
+        raise SystemExit(f"the main model's checkpoint was not found: {models['main']}")
 
     # block S9 needs the reliability map, which is a separate script
     rel = os.path.join(a.out, "reliability_map.csv")
@@ -126,7 +158,10 @@ def main():
                "--out", a.out]
         if a.targets:
             cmd += ["--targets"] + [str(t) for t in a.targets]
-        run(cmd, env, os.path.join(a.out, "diagnostics.log"))
+        if os.path.exists(rel):
+            os.remove(rel)
+        if run(cmd, env, os.path.join(a.out, "diagnostics.log"), os.path.join(a.out, "_work")) != 0 or not os.path.exists(rel):
+            raws.setdefault("main", {}).setdefault("failed", []).append("reliability_map.py")
     if os.path.exists(rel):
         R = pd.read_csv(rel)
         measured.setdefault("main", {})["servable_targets"] = int((R.verdict == "servable").sum())
@@ -195,11 +230,18 @@ def main():
             text += " In this configuration the structure losses are already on, so the limit is the data (block S0's density), not the losses."
         return text
     report = {}
+    failures = {name: (raws.get(name) or {}).get("failed", []) for name in measured}
     for name, vals in measured.items():
         blocks = {}
+        model_failed = [f for f in failures.get(name, []) if not f.startswith("reliability_map")]
         for sid in ("S1", "S2", "S3", "S4", "S8", "S9"):
             st = BY_ID[sid]
             sub = {m.id: vals[m.id] for m in st.metrics if m.id in vals}
+            if sid in ("S1", "S2", "S3", "S4") and model_failed:
+                # a block whose diagnostics failed is not graded: neither from partial values nor from an earlier run
+                blocks[sid] = dict(name=st.name, question=st.question, verdict="NOT COMPUTED", metrics=[],
+                                   reason="failed: " + ", ".join(model_failed) + " (see diagnostics.log)")
+                continue
             if not sub:
                 continue
             verdict, grades = st.verdict(sub, context=vals)
@@ -230,7 +272,7 @@ def main():
             if k in measured["main"] and k in measured["seed1"]}
 
     json.dump(dict(intake=a.intake, gap=a.gap, cost=a.cost, models=models, measured=measured, report=report,
-                   comparisons=comparisons, judge=judge), open(os.path.join(a.out, "scorecard.json"), "w"),
+                   comparisons=comparisons, judge=judge, failures=failures), open(os.path.join(a.out, "scorecard.json"), "w"),
               indent=1, default=float)
 
     # ── render ──
@@ -249,6 +291,9 @@ def main():
     for sid, b in main.items():
         L += [f"## {sid} — {b['name']}: **{b['verdict']}**", "",
               "| metric | value | band | grade |", "|---|---|---|---|"]
+        if b["verdict"] == "NOT COMPUTED":
+            L += [f"Not computed: {b['reason']}.", ""]
+            continue
         for r in b["metrics"]:
             L.append(f"| {r['metric']} ({r['unit']}) | {r['value']:.4g} | {r['band']} | **{r['grade']}** |")
         L.append("")
@@ -275,6 +320,10 @@ def main():
     open(os.path.join(a.out, "scorecard.md"), "w").write("\n".join(L))
     print("\n".join(L))
     print(f"\nwrote {a.out}/scorecard.md and scorecard.json")
+    failed = {k: v for k, v in failures.items() if v}
+    if failed:
+        print("\nNOT COMPUTED: " + "; ".join(f"{k}: {', '.join(v)}" for k, v in failed.items()) + f" (log: {a.out}/diagnostics.log)", flush=True)
+        sys.exit(1)
 
 
 if __name__ == "__main__":