v0.1.4

What's Changed

• Add Krv logo to Sphinx Docs by @sgathrid in #60
• Introducing CosmicGraphs 👾 by @jeremy-wayland in #62

Full Changelog: v0.1.3...v0.1.4

v0.1.3

Thema v0.1.3 Release Notes

October 23, 2025

We are thrilled to announce the release of Thema v0.1.3, coinciding with our paper
“Strategies to accelerate US coal power phase-out using contextual retirement vulnerabilities” — now published in Nature Energy! 🎉

This release marks Thema’s evolution from a research prototype into a production-ready TDA + graph analytics library, empowering researchers and data teams to explore complex systems through topology, geometry, and machine learning. If you use our package, please consider citing our work:

Full Paper:

@article{Gathrid2025,
  author  = {Gathrid, Sidney and Wayland, Jeremy and Wayland, Stuart and Deshmukh, Ranjit and Wu, Grace C.},
  title   = {Strategies to accelerate US coal power phase-out using contextual retirement vulnerabilities},
  journal = {Nature Energy},
  year    = {2025},
  volume  = {10},
  number  = {10},
  pages   = {1274--1288},
  month   = {October},
  doi     = {10.1038/s41560-025-01871-0},
  url     = {https://doi.org/10.1038/s41560-025-01871-0},
  issn    = {2058-7546},
  abstract = {Strategically planning the phase-out of coal power is critical to achieve climate targets, yet current approaches often fail to account for the context-specific barriers and vulnerabilities to retirement. Here we introduce a framework that combines graph theory and topological data analysis to classify the US coal fleet into eight distinct groups based on technical, economic, environmental and socio-political characteristics. We calculate each non-retiring coal plant’s ‘contextual retirement vulnerability’ score, a metric developed to quantify susceptibility to retirement drivers using the graph-based distance to a coal plant with an announced early retirement. Separately, we identify ‘retirement archetypes’ that explain the key factors driving announced retirements within each group, which are used to inform group-specific strategies for accelerating retirements. Our findings reveal the diverse strategies that are required to accelerate the phase-out of remaining coal plants, including regulatory compliance, public health campaigns and economic incentives.}
}

Research Briefing:

@article{Gathrid2025B,
  title   = {Targeted strategies for accelerating US coal plant retirements},
  journal = {Nature Energy},
  year    = {2025},
  month   = {October},
  doi     = {10.1038/s41560-025-01872-z},
  url     = {https://doi.org/10.1038/s41560-025-01872-z},
  issn    = {2058-7546},
  abstract = {US coal power has been on the decline over the past decade, but there is no path forward for a complete phaseout in alignment with climate goals. Targeted early retirement strategies are now made available for major groupings of coal plants using their key group characteristics and similarity to plants with announced retirements.}
}

---

🔬 Research & Real-World Relevance

Thema v0.1.3 implements the full pipeline used in our Nature Energy study to model the US coal fleet and uncover data-driven retirement strategies.
It demonstrates how topological data analysis, graph curvature, and geometric clustering can illuminate hidden structures in energy systems—tools now directly usable across climate science, network analysis, and applied ML workflows.

Thema is developed by Krv Labs, building bridges between academic ML research and enterprise-scale data systems.

---

🌟 Highlights

🧩 Advanced Graph Filtering

• YAML-based filter configuration enables reproducible selection pipelines.
• Built-in filters for topology and structure (component_count_filter, minimum_nodes_filter, etc.)
• Support for custom user-defined filters and programmatic API access

🔍 Observability & Logging

• End-to-end progress tracking and timing metrics.
• Automatic graph statistics, debug reports, and memory-safe parallelism.

⚙️ Production Infrastructure

• Automated PyPI publishing and CI/CD with GitHub Actions
• Complete API docs and user guides at krv-analytics.github.io/Thema
• Modern packaging via uv and pyproject.toml

---

🚀 Technical Improvements

• Default curvature: Switched to Ollivier–Ricci for improved stability.
• Parallel processing: Safer and faster multiprocessing.
• Improved clustering: Configurable thresholds and representative selection.
• Memory optimization: Efficient handling of large graph datasets.
• Clear diagnostics: Better runtime and configuration error messages.

---

📚 Documentation & Examples

• Full API reference and usage tutorials
• Best-practice workflows for TDA-based model analysis
• Real-world example: U.S. coal fleet transition modeling

---

🧠 Designed For

• Complex systems research
• Policy and climate analytics
• Graph learning and TDA benchmarking
• Enterprise ML pipelines needing interpretable, topology-based insights.

---

🧩 Dependencies

curvature-filtrations ≥ 0.1.2
hdbscan ≥ 0.8.40
networkx ≥ 3.4.2
numpy ≥ 2.2.6
scikit-learn ≥ 1.7.1
tqdm ≥ 4.67.1

---

💡 Acknowledgments

Special thanks to our collaborators and supervisors, Dr. Grace Wu and Dr. Ranjit Deshmukh, for their invaluable insight and unwavering support throughout this research journey. Their powerful domain knowledge proved crucial in demonstrating the real-world impact of our algorithms.

---

🔗 Learn More

📘 Docs: krv-analytics.github.io/Thema
💬 Contact: team@krv.ai
🥮 Paper: Nature Energy (2025)
💼 Research Briefing: Nature Energy (2025)