📋 Table of Contents

• Overview
• Upgrading to 2.0.0
• 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

🔄 Upgrading to 2.0.0

2.0.0 is a breaking release. Three changes bite existing users; the full list is in CHANGELOG.md.

Python ≥ 3.12 is required.

🚀 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: tanabesugano [-h] [-d D] [-Dq DQ] [-cut CUT] [-B B B] [-C C C] [-n N] [-ndisp]
                    [-ntxt] [-slater] [-v] [-html] [-html-offline]

A python-based Eigensolver for Tanabe-Sugano- & Energy-Correlation-Diagrams based on
studies by *Yukito Tanabe and Satoru Sugano* for d3-d8 transition metal ions: For
further help, please use tanabe '--help'

options:
  -h, --help     show this help message and exit
  -d D           Number of d electrons, 2-8 (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 the interactive Plotly diagrams as HTML (default = off)
  -html-offline  With -html, write a shared plotly.min.js beside the diagrams so they
                 render without a network connection (default = CDN)

Python API

Changed in 2.0.0. solver() returns a LevelSet, not a dict. LevelSet is not a Mapping — states[key], .items() and len() raise TypeError. Call .as_dict() for the previous shape, or iterate .levels.

from tanabesugano.levels import LevelSet

# Solve the d8 manifold at one ligand-field strength.
manifold = LevelSet.solve(8, dq=850.0, b=1030.0, c=4850.0)

print(manifold.ground.label)          # 3_A_2
print(manifold.level_count)           # 11 levels ...
print(manifold.total_degeneracy)      # ... accounting for C(10,8) = 45 microstates

# Levels are typed objects, not bare arrays, and carry free-ion parentage:
# 3T_1g(F) / 3T_1g(P), the notation the literature uses, rather than a
# positional (a)/(b).
for level in manifold.spin_allowed():
    print(f"{level.parent_unicode:10} {level.energy_cm1:9.1f} cm-1")
# 3T_2g        8500.0 cm-1     <- nu1 = 10Dq exactly, for d3 and d8
# 3T_1g(F)    14283.0 cm-1
# 3T_1g(P)    26667.0 cm-1

# Name a transition the way a caption would.
excited = manifold.for_term("3_T_1")[1]
print(manifold.transition_unicode(excited))   # 3A_2g -> 3T_1g(P)

Sweeping a range of ligand-field strengths, and exporting a figure:

from pathlib import Path

from tanabesugano.batch import Batch
from tanabesugano.mcp.plotting import render_diagram

# Sweep Dq while holding the Racah parameters fixed.
# Each parameter is [start, stop, steps]; hold B and C fixed with one step.
batch = Batch(Dq=[500.0, 1500.0, 20], B=[1030.0, 1030.0, 1], C=[4850.0, 4850.0, 1], d_count=8)
batch.calculation()

# Publication figure: "png" (default), "pdf" or "svg".
Path("d8.pdf").write_bytes(
    render_diagram(d_count=8, dq_max=1500.0, B=1030.0, C=4850.0, fmt="pdf"),
)

🎨 Examples

Static Matplotlib Plot

High-quality diagrams for d⁶ configuration with B = 1080.0 cm⁻¹ and C = 4773.0 cm⁻¹:

Tanabe-Sugano Diagram

Energy-Correlation Diagram

Interactive Plotly Visualization

Interactive diagram for d⁶ with B = 1080 cm⁻¹ and C = 4773 cm⁻¹ — the same parameters as the static figures above, so the two can be read against each other:

🌐 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:

Every diagram is also committed as a static figure, so a paper or a slide deck does not need the browser:

All four are regenerated by uv run poe regen-diagrams and guarded against drift in CI. Both renderers read one palette and one notation ladder, so a state is the same colour and carries the same symbol wherever you meet it:

• colour = spin multiplicity (Okabe-Ito, colour-blind safe)
• paler shade = higher level within the same term
• solid vs dashed = spin-allowed vs spin-forbidden from the ground level

🤖 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       = {Hahn, Anselm W.},
  title        = {TanabeSugano: Python-based Eigensolver for Tanabe-Sugano Diagrams},
  year         = {2026},
  publisher    = {Zenodo},
  version      = {2.0.0-alpha.1},
  doi          = {10.5281/zenodo.3402463},
  url          = {https://github.com/Anselmoo/TanabeSugano}
}

Which DOI? 10.5281/zenodo.3402463 is the concept DOI — it always resolves to the newest deposited release, which is what you want in a reference list. To cite the exact version you ran, use that release's own version DOI from the Zenodo record instead.

📄 License

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