Upload dataset/entries_v3.index.json with huggingface_hub

README.md

@@ -0,0 +1,128 @@
+# Dataset Card — Scandium-Dataset v0.3.0
+
+## Dataset Description
+
+- **Name:** Scandium-Dataset
+- **Version:** v0.3.0
+- **Description:** Curated multi-source DFT + experimental dataset for thermodynamic screening and benchmarking of battery-relevant inorganic materials, aggregated from Materials Project, OQMD, and JARVIS-DFT.
+- **Total entries:** 267,230 (Gold: 96,242 | Validated: 140,382 | Raw: 30,108 | Experimental: 498)
+- **Battery subset:** 82,925 entries | **Electrolyte subset:** 41,665 entries (strict Gold)
+- **Storage:** Parquet (`dataset/entries_v3.parquet`) with indexed lookup — 0.18 GB instead of 1.6 GB JSON.
+- **Experimental data:** 599 OBELiX entries integrated (Therrien et al. 2025, NRC-Mila), including 498 new `experimental_gold` tier entries with measured Li-ion conductivity.
+- **Transport proxies:** BVSE migration barrier proxy (bvlain engine, validated against 7 known SSEs, 5/7 pass within literature ranges). See `scripts/compute_bvse_barriers.py`.
+
+## Sources
+
+| Source | Entries | License | Download Date |
+|--------|---------|---------|---------------|
+| Materials Project | 69,279 | CC BY 4.0 | 2026-07-20 |
+| OQMD | 171,780 | Non-commercial + attribution | 2026-07-20 |
+| JARVIS-DFT | 25,673 | CC0 | 2026-07-20 |
+
+## License Warning
+
+⚠️ **This dataset is NOT uniformly licensed.** Each entry carries its own license.
+- `license: "CC-BY-4.0"` → MP entries (commercial safe)
+- `license: "CC0-1.0"` → JARVIS entries (commercial safe)
+- `license: "OQMD-noncommercial"` → OQMD entries (non-commercial only, 64.4%)
+
+Filter by the `license` field for programmatic usage. See [`LICENSE_BREAKDOWN.md`](LICENSE_BREAKDOWN.md).
+
+### Commercial-Safe Edition
+
+A **Commercial-Safe edition** (`commercial_safe_subset_v3.json`) containing only MP + JARVIS entries (~94,952 entries) is available for commercial use. All entries are CC BY 4.0 or CC0 1.0 licensed. Any model trained for commercial deployment should be trained on this edition.
+
+```python
+import json
+# Load commercial-safe edition
+with open("dataset/commercial_safe_subset_v3.json") as f:
+    entries = json.load(f)
+print(f"{len(entries):,} entries — all commercial-safe")
+```
+
+## Fields
+
+### Primary fields
+
+| Field | Type | Description | Coverage |
+|-------|------|-------------|----------|
+| `license` | str | Per-entry license tag | 100% |
+| `source_id` | str | Original source ID | 100% |
+| `formula` | str | Raw formula string | 100% |
+| `structured_formula` | str | Reduced formula | 100% |
+| `elements` | list[str] | Element symbols | 100% |
+| `nsites` | int | Number of atoms in cell | 100% |
+| `space_group` | int | International number | 99.99% |
+| `space_group_symbol` | str | Hermann–Mauguin symbol | 99.99% |
+| `volume` | float | Cell volume (ų) | 100% |
+| `density` | float | Density (g/cm³) | 100% |
+| `formation_energy_per_atom` | float | FE (eV/atom) | 100% |
+| `energy_above_hull` | float | EaH (eV/atom) | 90.4% → **100%** (JARVIS hull added) |
+| `band_gap` | float | Band gap (eV) | 99.94% |
+| `total_magnetization` | float | Total | 100% |
+| `magnetic_ordering` | str | Magnetic ordering | 100% |
+| `is_metal` | bool | Metallic character | 100% |
+| `is_experimental` | bool | From experiment? | 100% |
+| `families` | list[str] | Material families | 100% |
+| `carrier_elements` | list[str] | Mobile ion carriers | 100% |
+| `anions` | list[str] | Anion species | 100% |
+| `structure_json` | str | JSON-encoded pymatgen Structure | 100% |
+| `quality_score` | int | Composite quality (0–88) | 100% |
+| `quality_sub_scores` | dict | Per-category scores | 100% |
+| `quality_flags` | list[str] | Quality flags | 100% |
+| `tier` | str | Gold / Validated / Raw | 100% |
+| `tier_detail` | dict | Gate pass/fail details | 100% |
+| `tier_gates` | dict | Per-gate results | 100% |
+| `strict_gold` | dict | Strict Gold pass/fail | 100% |
+| `duplicate_group` | int | Dedup group ID | 7.9% |
+| `provenance` | dict | Full provenance chain | 100% |
+| `source_weight` | float | Source priority weight | 100% |
+| `references` | list[str] | Source references | 100% |
+
+### SSE proxy fields (added in v0.1.0)
+
+| Field | Type | Description | Coverage |
+|-------|------|-------------|----------|
+| `carrier_fraction` | float | Fraction of mobile ion carriers | 100% |
+| `volume_per_carrier` | float | Volume per mobile carrier (ų) | 100% |
+| `fe_per_carrier` | float | Formation energy per carrier (eV) | 100% |
+| `electronic_insulation` | bool | Band gap > 1.0 eV | 100% |
+| `sse_family` | str | SSE family classification | 100% |
+| `mobile_ion` | str | Primary mobile ion (Li/Na/Mg) | 61.1% |
+| `oxidation_states` | dict | Per-element oxidation states | 100% |
+| `predicted_oxidation_states_valid` | bool | BVA-validated prediction? | 100% |
+
+### ssb_screening block (v0.2.0)
+
+| Field | Type | Description | Coverage |
+|-------|------|-------------|----------|
+| `mobile_ion` | str | Mobile ion species | 61.1% |
+| `mobile_ion_fraction` | float | Fraction of mobile ions | 100% |
+| `sse_family` | str | SSE family tag | 100% |
+| `electronic_insulation` | bool | Band gap > 1.0 eV | 100% |
+| `thermo_stable` | bool | E_hull < 0.025 eV/atom | 100% |
+| `gates_passed` | list[str] | SSE screening gates passed | 100% |
+| `sse_candidate_score` | int | Composite SSE score (0–100) | 100% |
+| `cavd_channel_dimensionality` | str | 0D/1D/2D/3D percolation | ~61% |
+| `stability_window_low_V` | float | Lower stability limit vs Li/Na | ~2.2% |
+| `stability_window_high_V` | float | Upper stability limit vs Li/Na | ~2.2% |
+| `window_width_V` | float | Electrochemical window width | ~2.2% |
+| `passivating_interphase` | bool | Forms passivating interphase? | ~14.9% |
+| `interfacial_reaction_energy_vs_Li_eV_atom` | float | Decomposition energy vs Li | ~14.9% |
+| `bulk_modulus_GPa` | float | Bulk modulus (geometric proxy) | 100% |
+| `shear_modulus_GPa` | float | Shear modulus (geometric proxy) | 100% |
+| `dendrite_suppression_flag` | bool | Shear modulus > 6 GPa | 100% |
+| `elastic_source` | str | "MP_API" / "geometric_proxy" / null | 100% |
+
+## Intended Use
+
+- **Primary:** Training machine learning models for property prediction of solid-state battery materials
+- **Secondary:** Materials discovery, phase stability analysis, and computational screening
+- **Not recommended for:** Quantitative phase diagram construction (use MP/OQMD directly)
+
+## Maintenance
+
+- Version: v0.1.0-rc.1
+- DOI: pending (Zenodo archival in progress)
+- Issue tracking: GitHub Issues
+- Contact: Scandium Labs