Add transport bipolar-risk screening

Author: quanshengwu

README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://img.shields.io/github/actions/workflow/status/chatmaterials/transport-analysis/ci.yml?branch=main&label=CI)](https://github.com/chatmaterials/transport-analysis/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/chatmaterials/transport-analysis?display_name=tag)](https://github.com/chatmaterials/transport-analysis/releases)
 
-Standalone skill for transport-relevant DFT result analysis, including thermoelectric-style screening descriptors and batch candidate ranking.
+Standalone skill for transport-relevant DFT result analysis, including thermoelectric-style screening descriptors, bipolar-risk checks, and batch candidate ranking.
 
 ## Install
 
@@ -16,9 +16,10 @@ npx skills add chatmaterials/transport-analysis -g -y
 python3 -m py_compile scripts/*.py
 npx skills add . --list
 python3 scripts/analyze_carrier_type.py fixtures/band/bands.dat --occupied-bands 2 --fermi 0.35 --json
+python3 scripts/analyze_bipolar_risk.py fixtures/band/bands.dat --occupied-bands 2 --fermi 0.35 --temperature-k 300 --json
 python3 scripts/analyze_effective_mass.py fixtures/effective_mass/effective_mass.dat --json
-python3 scripts/analyze_transport_trend.py --band-path fixtures/band/bands.dat --dos-path fixtures/dos/dos.dat --occupied-bands 2 --fermi 0.35 --json
-python3 scripts/compare_transport_candidates.py fixtures fixtures/candidates/heavy fixtures/candidates/metallic --occupied-bands 2 --fermi 0.35 --target-gap-min 0.5 --target-gap-max 1.0 --prefer-carrier electron-like --json
-python3 scripts/export_transport_report.py --band-path fixtures/band/bands.dat --dos-path fixtures/dos/dos.dat --mass-path fixtures/effective_mass/effective_mass.dat --occupied-bands 2 --fermi 0.35
+python3 scripts/analyze_transport_trend.py --band-path fixtures/band/bands.dat --dos-path fixtures/dos/dos.dat --occupied-bands 2 --fermi 0.35 --temperature-k 300 --json
+python3 scripts/compare_transport_candidates.py fixtures fixtures/candidates/heavy fixtures/candidates/narrow-gap fixtures/candidates/metallic --occupied-bands 2 --fermi 0.35 --target-gap-min 0.5 --target-gap-max 1.0 --prefer-carrier electron-like --temperature-k 300 --json
+python3 scripts/export_transport_report.py --band-path fixtures/band/bands.dat --dos-path fixtures/dos/dos.dat --mass-path fixtures/effective_mass/effective_mass.dat --occupied-bands 2 --fermi 0.35 --temperature-k 300
 python3 scripts/run_regression.py
 ```

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "transport-analysis"
-description: "Use when the task is to analyze transport-relevant quantities from DFT-derived results, including carrier-type tendency, effective-mass estimates, simple DOS-informed transport trends, thermoelectric-style screening descriptors, multi-candidate ranking, and compact markdown reports from finished calculations."
+description: "Use when the task is to analyze transport-relevant quantities from DFT-derived results, including carrier-type tendency, effective-mass estimates, simple DOS-informed transport trends, thermoelectric-style screening descriptors, bipolar-risk checks, multi-candidate ranking, and compact markdown reports from finished calculations."
 ---
 
 # Transport Analysis
@@ -13,6 +13,7 @@ Use this skill for transport-oriented post-processing rather than generic workfl
 - estimate an effective mass from a simple band-edge dispersion
 - summarize a transport trend from band-edge and DOS information
 - derive compact thermoelectric-style screening descriptors such as activation energy and transport quality score
+- estimate bipolar-conduction risk from the band gap and temperature
 - rank multiple candidate datasets with a compact screening heuristic
 - write a compact transport-analysis report from existing data
 
@@ -24,6 +25,8 @@ Use this skill for transport-oriented post-processing rather than generic workfl
   Estimate an effective mass from a simple band-edge dispersion.
 - `scripts/analyze_transport_trend.py`
   Summarize a simple transport trend from band-edge and DOS information and derive compact quality descriptors.
+- `scripts/analyze_bipolar_risk.py`
+  Estimate a compact bipolar-conduction risk from the band gap and temperature.
 - `scripts/compare_transport_candidates.py`
   Rank multiple candidate datasets with a compact gap-plus-mass screening heuristic.
 - `scripts/export_transport_report.py`

fixtures/candidates/narrow-gap/bands.dat

@@ -0,0 +1,2 @@
+0.00 -5.00 0.05 0.20 2.30
+0.50 -4.95 0.10 0.25 2.25

fixtures/candidates/narrow-gap/dos.dat

@@ -0,0 +1,5 @@
+-1.0 0.5
+-0.5 0.7
+0.0 0.0
+0.5 0.4
+1.0 0.8

fixtures/candidates/narrow-gap/effective_mass.dat

@@ -0,0 +1,5 @@
+-0.20 0.006
+-0.10 0.0015
+0.00 0.0000
+0.10 0.0015
+0.20 0.006

references/transport.md

@@ -5,3 +5,4 @@
 - DOS-informed transport trend summaries are qualitative, not a replacement for full transport coefficient calculations.
 - Screening scores are useful for ranking, but they are not a substitute for full transport coefficients.
 - Activation-energy and quality-score style descriptors are useful for screening, but they remain compact proxies rather than predictive transport models.
+- Bipolar-risk estimates are useful for narrow-gap screening, but they remain simplified intrinsic-excitation proxies rather than full finite-temperature transport solutions.

scripts/analyze_bipolar_risk.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from pathlib import Path
+
+from analyze_carrier_type import analyze as analyze_carrier
+
+
+KB_EV_K = 8.617333262145e-5
+
+
+def classify_risk(score: float) -> str:
+    if score < 1e-4:
+        return "low-bipolar-risk"
+    if score < 1e-2:
+        return "moderate-bipolar-risk"
+    return "high-bipolar-risk"
+
+
+def analyze(path: Path, occupied_bands: int, fermi: float, temperature_k: float) -> dict[str, object]:
+    carrier = analyze_carrier(path, occupied_bands, fermi)
+    gap = float(carrier["band_gap_eV"])
+    if temperature_k <= 0:
+        raise SystemExit("Temperature must be positive")
+    score = math.exp(-gap / (2.0 * KB_EV_K * temperature_k))
+    return {
+        "path": str(path),
+        "temperature_K": temperature_k,
+        "band_gap_eV": gap,
+        "bipolar_risk_score": score,
+        "bipolar_risk_class": classify_risk(score),
+        "observations": [
+            "Bipolar risk was estimated from a simple intrinsic excitation factor based on the band gap and temperature."
+        ],
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Estimate a compact bipolar-conduction risk from the band gap and temperature.")
+    parser.add_argument("path")
+    parser.add_argument("--occupied-bands", type=int, default=2)
+    parser.add_argument("--fermi", type=float, required=True)
+    parser.add_argument("--temperature-k", type=float, default=300.0)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    payload = analyze(
+        Path(args.path).expanduser().resolve(),
+        args.occupied_bands,
+        args.fermi,
+        args.temperature_k,
+    )
+    if args.json:
+        print(json.dumps(payload, indent=2))
+        return
+    print(json.dumps(payload, indent=2))
+
+
+if __name__ == "__main__":
+    main()

scripts/analyze_transport_trend.py

@@ -6,6 +6,7 @@
 import json
 from pathlib import Path
 
+from analyze_bipolar_risk import analyze as analyze_bipolar
 from analyze_carrier_type import analyze as analyze_carrier
 from analyze_effective_mass import analyze as analyze_mass
 
@@ -23,8 +24,9 @@ def analyze_dos(path: Path) -> dict[str, float]:
     return {"dos_at_fermi": nearest[1]}
 
 
-def analyze(band_path: Path, dos_path: Path, occupied_bands: int, fermi: float, mass_path: Path | None) -> dict[str, object]:
+def analyze(band_path: Path, dos_path: Path, occupied_bands: int, fermi: float, mass_path: Path | None, temperature_k: float = 300.0) -> dict[str, object]:
     carrier = analyze_carrier(band_path, occupied_bands, fermi)
+    bipolar = analyze_bipolar(band_path, occupied_bands, fermi, temperature_k)
     dos = analyze_dos(dos_path)
     mass = analyze_mass(mass_path) if mass_path else None
     if dos["dos_at_fermi"] < 1e-6:
@@ -58,12 +60,15 @@ def analyze(band_path: Path, dos_path: Path, occupied_bands: int, fermi: float,
         "band_gap_eV": carrier["band_gap_eV"],
         "activation_energy_eV": carrier["activation_energy_eV"],
         "dos_at_fermi": dos["dos_at_fermi"],
+        "temperature_K": temperature_k,
         "regime": regime,
         "effective_mass_me": mass["effective_mass_me"] if mass else None,
         "mobility_hint": mobility_hint,
         "thermoelectric_quality_score": quality_score,
         "screening_class": screening_class,
         "dopability_hint": dopability_hint,
+        "bipolar_risk_score": bipolar["bipolar_risk_score"],
+        "bipolar_risk_class": bipolar["bipolar_risk_class"],
         "observations": ["Transport tendency summarized from band-edge position, DOS at the Fermi level, and optional effective mass."],
     }
 
@@ -75,6 +80,7 @@ def main() -> None:
     parser.add_argument("--mass-path")
     parser.add_argument("--occupied-bands", type=int, default=2)
     parser.add_argument("--fermi", type=float, required=True)
+    parser.add_argument("--temperature-k", type=float, default=300.0)
     parser.add_argument("--json", action="store_true")
     args = parser.parse_args()
     payload = analyze(
@@ -83,6 +89,7 @@ def main() -> None:
         args.occupied_bands,
         args.fermi,
         Path(args.mass_path).expanduser().resolve() if args.mass_path else None,
+        args.temperature_k,
     )
     if args.json:
         print(json.dumps(payload, indent=2))

scripts/compare_transport_candidates.py

@@ -6,6 +6,7 @@
 import json
 from pathlib import Path
 
+from analyze_bipolar_risk import analyze as analyze_bipolar
 from analyze_carrier_type import analyze as analyze_carrier
 from analyze_effective_mass import analyze as analyze_mass
 from analyze_transport_trend import analyze as analyze_trend
@@ -34,13 +35,15 @@ def analyze_case(
     target_gap_min: float,
     target_gap_max: float,
     prefer_carrier: str | None,
+    temperature_k: float,
 ) -> dict[str, object]:
     band_path = locate_required(root, ["bands.dat", "band/bands.dat"])
     dos_path = locate_required(root, ["dos.dat", "dos/dos.dat"])
     mass_path = locate_optional(root, ["effective_mass.dat", "effective_mass/effective_mass.dat"])
     carrier = analyze_carrier(band_path, occupied_bands, fermi)
-    trend = analyze_trend(band_path, dos_path, occupied_bands, fermi, mass_path)
+    trend = analyze_trend(band_path, dos_path, occupied_bands, fermi, mass_path, temperature_k)
     mass = analyze_mass(mass_path) if mass_path is not None else None
+    bipolar = analyze_bipolar(band_path, occupied_bands, fermi, temperature_k)
 
     gap = float(carrier["band_gap_eV"])
     if gap < target_gap_min:
@@ -54,7 +57,8 @@ def analyze_case(
     mass_value = abs(float(mass["effective_mass_me"])) if mass and mass["effective_mass_me"] is not None else None
     mass_penalty = 0.25 * mass_value if mass_value is not None else 0.5
     quality_penalty = max(0.0, 0.3 - float(trend["thermoelectric_quality_score"]))
-    score = gap_penalty + regime_penalty + carrier_penalty + mass_penalty + quality_penalty
+    bipolar_penalty = 10.0 * float(bipolar["bipolar_risk_score"])
+    score = gap_penalty + regime_penalty + carrier_penalty + mass_penalty + quality_penalty + bipolar_penalty
 
     return {
         "case": root.name,
@@ -67,11 +71,14 @@ def analyze_case(
         "activation_energy_eV": trend["activation_energy_eV"],
         "thermoelectric_quality_score": trend["thermoelectric_quality_score"],
         "screening_class": trend["screening_class"],
+        "bipolar_risk_score": bipolar["bipolar_risk_score"],
+        "bipolar_risk_class": bipolar["bipolar_risk_class"],
         "gap_penalty_eV": gap_penalty,
         "regime_penalty": regime_penalty,
         "carrier_penalty": carrier_penalty,
         "mass_penalty": mass_penalty,
         "quality_penalty": quality_penalty,
+        "bipolar_penalty": bipolar_penalty,
         "screening_score": score,
     }
 
@@ -83,16 +90,18 @@ def analyze_cases(
     target_gap_min: float,
     target_gap_max: float,
     prefer_carrier: str | None,
+    temperature_k: float,
 ) -> dict[str, object]:
     cases = [
-        analyze_case(root, occupied_bands, fermi, target_gap_min, target_gap_max, prefer_carrier)
+        analyze_case(root, occupied_bands, fermi, target_gap_min, target_gap_max, prefer_carrier, temperature_k)
         for root in roots
     ]
     ranked = sorted(cases, key=lambda item: item["screening_score"])
     return {
         "target_gap_window_eV": [target_gap_min, target_gap_max],
         "preferred_carrier": prefer_carrier,
-        "ranking_basis": "screening_score = gap_penalty + regime_penalty + carrier_penalty + mass_penalty + quality_penalty",
+        "temperature_K": temperature_k,
+        "ranking_basis": "screening_score = gap_penalty + regime_penalty + carrier_penalty + mass_penalty + quality_penalty + bipolar_penalty",
         "cases": ranked,
         "best_case": ranked[0]["case"] if ranked else None,
         "observations": [
@@ -109,6 +118,7 @@ def main() -> None:
     parser.add_argument("--target-gap-min", type=float, default=0.5)
     parser.add_argument("--target-gap-max", type=float, default=1.5)
     parser.add_argument("--prefer-carrier", choices=["electron-like", "hole-like"])
+    parser.add_argument("--temperature-k", type=float, default=300.0)
     parser.add_argument("--json", action="store_true")
     args = parser.parse_args()
     payload = analyze_cases(
@@ -118,6 +128,7 @@ def main() -> None:
         args.target_gap_min,
         args.target_gap_max,
         args.prefer_carrier,
+        args.temperature_k,
     )
     if args.json:
         print(json.dumps(payload, indent=2))

scripts/export_transport_report.py

@@ -13,6 +13,8 @@
 def screening_note(carrier: dict[str, object], mass: dict[str, object] | None, trend: dict[str, object]) -> str:
     if trend["regime"] == "metallic-like":
         return "The sampled DOS indicates a metallic-like regime, so this case is better treated as a metal or degenerate system than as a simple semiconductor."
+    if trend["bipolar_risk_class"] == "high-bipolar-risk":
+        return "The band gap is small enough that bipolar conduction may become a serious screening concern at the chosen temperature."
     if trend["screening_class"] == "promising-semiconductor-like":
         return f"This case looks promising in compact screening: `{carrier['carrier_tendency']}` tendency, `{trend['dopability_hint']}`, and a reasonable transport quality score."
     mass_value = mass["effective_mass_me"] if mass and mass["effective_mass_me"] is not None else None
@@ -38,6 +40,8 @@ def render_markdown(carrier: dict[str, object], mass: dict[str, object] | None,
         f"- Screening class: `{trend['screening_class']}`",
         f"- Transport quality score: `{trend['thermoelectric_quality_score']:.4f}`",
         f"- Dopability hint: `{trend['dopability_hint']}`",
+        f"- Bipolar risk class: `{trend['bipolar_risk_class']}`",
+        f"- Bipolar risk score: `{trend['bipolar_risk_score']:.4e}`",
     ]
     if mass is not None:
         lines.extend(
@@ -60,13 +64,21 @@ def main() -> None:
     parser.add_argument("--mass-path")
     parser.add_argument("--occupied-bands", type=int, default=2)
     parser.add_argument("--fermi", type=float, required=True)
+    parser.add_argument("--temperature-k", type=float, default=300.0)
     parser.add_argument("--output")
     args = parser.parse_args()
     band_path = Path(args.band_path).expanduser().resolve()
     dos_path = Path(args.dos_path).expanduser().resolve()
     carrier = analyze_carrier(band_path, args.occupied_bands, args.fermi)
     mass = analyze_mass(Path(args.mass_path).expanduser().resolve()) if args.mass_path else None
-    trend = analyze_trend(band_path, dos_path, args.occupied_bands, args.fermi, Path(args.mass_path).expanduser().resolve() if args.mass_path else None)
+    trend = analyze_trend(
+        band_path,
+        dos_path,
+        args.occupied_bands,
+        args.fermi,
+        Path(args.mass_path).expanduser().resolve() if args.mass_path else None,
+        args.temperature_k,
+    )
     output = Path(args.output).expanduser().resolve() if args.output else Path.cwd() / "TRANSPORT_REPORT.md"
     output.write_text(render_markdown(carrier, mass, trend))
     print(output)