Scandium-Labs/Scandium-Dataset

1# Getting Started2 3## Installation4 5The Scandium Dataset is distributed as JSON files. No installation required6for basic use. For benchmark evaluation, clone the repository:7 8```bash9git clone https://github.com/Scandium-Labs/Scandium-Dataset10cd Scandium-Dataset11```12 13Python 3.9+ is recommended.14 15## Loading the Dataset16 17```python18import json19 20# Load the full dataset21with open("dataset/entries_final_v3.json") as f:22    entries = json.load(f)23 24print(f"Loaded {len(entries):,} entries")25```26 27## Basic Operations28 29### Filter by tier30 31```python32gold = [e for e in entries if e.get("tier") == "gold"]33strict_gold = [e for e in entries34               if e.get("strict_gold", {}).get("is_strict_gold")]35validated = [e for e in entries if e.get("tier") == "validated"]36```37 38### Filter by family39 40```python41battery_families = {"layered_oxide", "sulfide_sse", "halide_sse",42                    "polyanion", "nasicon", "garnet", "borohydride"}43 44battery = [e for e in entries45           if set(e.get("families", [])) & battery_families]46```47 48### Filter by source49 50```python51mp = [e for e in entries if e.get("source") == "mp"]52oqmd = [e for e in entries if e.get("source") == "oqmd"]53jarvis = [e for e in entries if e.get("source") == "jarvis"]54```55 56### Access properties57 58```python59for e in entries[:5]:60    print(f"{e['formula']:20s}  "61          f"FE={e.get('formation_energy_per_atom', 'N/A'):>8.4f}  "62          f"EaH={e.get('energy_above_hull', 'N/A'):>8.4f}  "63          f"BG={e.get('band_gap', 'N/A'):>8.4f}")64```65 66### Check provenance67 68```python69e = entries[0]70prov = e.get("provenance", {})71print(f"Source: {prov.get('source')} ({prov.get('source_id')})")72print(f"Checksum: {prov.get('checksum')}")73print(f"Repairs: {prov.get('repairs_applied')}")74print(f"Tier: {prov.get('tier_assignment', {}).get('tier')}")75```76 77## Using Editions78 79```python80# Battery subset81with open("dataset/battery_candidate_subset_v1.json") as f:82    battery = json.load(f)83 84# Electrolyte subset (strict Gold only)85with open("dataset/solid_electrolyte_candidate_subset_v1.json") as f:86    electrolyte = json.load(f)87```88 89## Using the Benchmark Splits90 91```python92import json93 94with open("dataset/splits/random_80_10_10.json") as f:95    split = json.load(f)96 97train_entries = [entries[i] for i in split["train"]]98val_entries = [entries[i] for i in split["val"]]99test_entries = [entries[i] for i in split["test"]]100```101 102See [examples/](../examples/) for complete scripts.103