📋 Table of Contents

• Overview
• Quick Start
• Features
• Usage
• Examples
• Interactive Diagrams
• Scientific Background
• Contributing
• Citation
• License

🌟 Overview

TanabeSugano is a comprehensive Python package for calculating and visualizing Tanabe-Sugano and Energy-Correlation diagrams for d²-d⁸ transition metal ions. Based on the pioneering work of Yukito Tanabe and Satoru Sugano, this tool provides both computational accuracy and interactive visualization capabilities.

Why TanabeSugano?

• 🎯 Accurate Calculations - Based on rigorous quantum mechanical principles
• 📊 Beautiful Visualizations - Generate publication-quality diagrams
• 🔄 Interactive Exploration - Explore diagrams with Plotly integration
• 🚀 Easy to Use - Simple CLI and Python API
• 📱 Cloud-Ready - Run in Google Colab or locally

🚀 Quick Start

Installation

Choose your preferred installation method:

# 📦 Install from PyPI (recommended)
pip install TanabeSugano

# 🔧 Install with interactive plotting support
pip install TanabeSugano[plotly]

# 🤖 Install with MCP server support (Claude Desktop, Cursor, VS Code, …)
pip install TanabeSugano[mcp]

# 🌐 Install from GitHub (latest development version)
pip install git+https://github.com/Anselmoo/TanabeSugano.git

Note: TanabeSugano now uses the uv_build backend and requires Python ≥ 3.12.

Basic Usage

Generate a Tanabe-Sugano diagram in seconds:

# Generate diagram for d6 configuration
tanabesugano -d 6

# Customize parameters
tanabesugano -d 6 -Dq 8000 -B 860 1.0 -C 3850 1.0

🎮 Try it now:

✨ Features

📖 Usage

Command Line Interface

tanabesugano --help

usage: __main__.py [-h] [-d D] [-Dq DQ] [-cut CUT] [-B B B] [-C C C] [-n N]
               [-ndisp] [-ntxt] [-slater]

optional arguments:
  -h, --help     show this help message and exit
  -d D           Number of unpaired electrons (default d5)
  -Dq DQ         10Dq crystal field splitting (default 10Dq = 8065 cm-)
  -cut CUT       10Dq crystal field splitting (default 10Dq = 8065 cm-)
  -B B B         Racah Parameter B and the corresponding reduction (default B = 860 cm- * 1.)
  -C C C         Racah Parameter C and the corresponding reduction (default C = 4.477*860 cm- * 1.)
  -n N           Number of roots (default nroots = 500)
  -ndisp         Plot TS-diagram (default = on)
  -ntxt          Save TS-diagram and dd energies (default = on)
  -slater        Using Slater-Condon F2,F4 parameter instead Racah-Parameter B,C (default = off)
  -v, --version  Print version number and exit
  -html          Save TS-diagram and dd energies (default = on)

Python API

from tanabesugano import TanabeSugano

# Create a d6 configuration
ts = TanabeSugano(d=6, Dq=8065, B=860, C=3850)

# Generate and display diagram
ts.plot()

# Export to HTML for interactive use
ts.export_html('d6_diagram.html')

🎨 Examples

Static Matplotlib Plot

High-quality diagram for d⁶ configuration with B = 860 cm⁻¹ and C = 3850 cm⁻¹:

Interactive Plotly Visualization

Interactive diagram for d⁶ with Slater-Condon parameters F² = 1065 cm⁻¹ and F⁴ = 5120 cm⁻¹:

🌐 Interactive Diagrams

✨ NEW: Explore all Tanabe-Sugano diagrams online!

All diagrams (d² through d⁸) are now available on our interactive GitHub Pages site with full Plotly integration:

🤖 MCP Server (Claude Desktop, Cursor, …)

TanabeSugano ships an optional Model Context Protocol server so AI assistants can compute diagrams, evaluate term symbols, and render plots as first-class tools.

Install

pip install "TanabeSugano[mcp]"
# or with uv:
uv add "TanabeSugano[mcp]"

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tanabesugano": {
      "command": "uvx",
      "args": ["--from", "tanabesugano[mcp]", "tanabesugano-mcp"]
    }
  }
}

One-click via .mcpb bundle

Every release attaches a tanabesugano-<version>.mcpb artifact (built by the Build .mcpb bundle job in cicd.yml) that Claude Desktop can install in one step — drag the file onto the Claude Desktop window. The bundle pins the exact published version and launches the tanabesugano-mcp entry point with the [mcp] extra; both are asserted by scripts/validate_mcpb.py before the release is created.

Exposed tools

Compute & analysis tools

Note. ts_compute and ts_diagram (raw nested-dict eigenvalue payloads) were removed because the output was unusable without further rendering — Claude's "next steps" devolved into "save to CSV / render PNG" suggestions the client cannot execute. Use ts_compute_app / ts_diagram_app for in-chat tables and charts, or ts_terms_table_data for machine-readable rows.

Interactive app tools (Prefab / Chart.js UI — capable clients only)

Prompts & resources

Prompts: tanabesugano_why (discovery context) and tanabesugano_explain_complex (guided spectrum interpretation from measured absorption peaks).

Resources at tanabesugano://version, tanabesugano://configs, tanabesugano://config/{d} provide static metadata.

📚 Scientific Background

This implementation is based on the seminal work of Yukito Tanabe and Satoru Sugano:

📄 Original Publications

🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

• 📖 Read our Contributing Guide
• 🐛 Report issues on GitHub Issues
• 💡 Suggest features or improvements
• 🔧 Submit pull requests

📝 Citation

If you use TanabeSugano in your research, please cite:

@software{tanabesugano,
  author       = {Anselm Hahn},
  title        = {TanabeSugano: Python-based Eigensolver for Tanabe-Sugano Diagrams},
  year         = {2024},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.206847682},
  url          = {https://github.com/Anselmoo/TanabeSugano}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.