feat: Add Ising analysis and atomic visualization features (#58 #59)

[idriss-hamadi]

• Please check if the PR fulfills these requirements

• The commit message follows our guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

• What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
  issue 58 & 59

• What is the current behavior? (You can also link to an open issue here)

• What is the new behavior (if this is a feature change)?

tested to pass ruff tests, same code of the two PRs merged in one PR that was tested locally to pass the ruff tests

• Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)

• Other information:

closes #58
closes #59

Summary

This PR combines two complementary features for quantum system analysis and visualization:

1. Ising Hamiltonian Analysis ([IN REVIEW] Check if an analog AnalogGate implements an Ising-like Hamiltonian #59) - Analyzes AnalogGate for Ising-like properties
2. Atomic Energy Level Visualization ([IN REVIEW] Create a energy level visualization based on an instance of the Atomic objects #58) - Generates Grotrian-like diagrams for Ion instances

Why Combined PR?

These two features are being submitted together because:

• Shared Infrastructure: Both features modify the same core files (src/oqd_core/__init__.py, src/oqd_core/compiler/analog/passes/__init__.py)
• Avoid Merge Conflicts: Separating them would create unnecessary merge conflicts and complicate the review process

each feature was submitted in it's PR, this one is combining them, no code change execept for combining and passing ruff tests

Features Added

1. Ising Hamiltonian Analysis (#59)

• Analyzes AnalogGate instances to determine if they implement Ising-like Hamiltonians
• Validates three key constraints:
  • Only qubit registers (no bosonic operators)
  • Weight-2 Pauli strings (max two non-identity Paulis per term)
  • Time-independent coefficients
• Extracts coupling matrices for all Pauli interaction types (XX, YY, ZZ, XY, XZ, YZ)
• Provides structured error reporting for invalid Hamiltonians
• Includes comprehensive unit tests (13 test cases covering valid/invalid scenarios)

2. Atomic Energy Level Visualization (#58)

• Generates Grotrian-like energy level diagrams for Ion instances
• Groups energy levels by orbital quantum number (s, p, d, f columns)
• Displays transitions as arrows between levels
• Highly customizable (colors, fonts, arrow styles, labels, etc.)
• Handles edge cases (empty ions, no transitions, etc.)
• Adds matplotlib as a project dependency

Testing Status

• ✅ All pytest tests pass (13/13 Ising analysis tests)
• ✅ Visualization functionality verified via manual testing script
• ✅ All ruff linting issues resolved (import formatting, unused imports, variable naming)
• ✅ No breaking changes to existing functionality

Files Changed

Core Infrastructure:

• src/oqd_core/__init__.py - Added visualizations module import
• src/oqd_core/compiler/analog/passes/__init__.py - Added Ising analysis export
• pyproject.toml - Added matplotlib dependency

Ising Analysis Feature:

• src/oqd_core/compiler/analog/passes/ising_analysis.py - Main analysis logic
• src/oqd_core/compiler/analog/passes/ising_types.py - Data structures
• tests/test_analog/test_ising_analysis.py - Comprehensive test suite

Visualization Feature:

• src/oqd_core/visualizations/__init__.py - Package initialization
• src/oqd_core/visualizations/atomic.py - Plotting implementation

Usage Examples

Ising Analysis

from oqd_core.compiler.analog.passes import analyze_ising_gate
from oqd_core.interface.analog import AnalogGate, OperatorKron, PauliX

gate = AnalogGate(hamiltonian=OperatorKron(op1=PauliX(), op2=PauliX()))
result = analyze_ising_gate(gate)
print(f"Is Ising-like: {result.is_ising_like}")
print(f"XX coupling: {result.coupling_matrices.XX}")

Visualization

from oqd_core.visualizations import generate_energy_level_plot
from oqd_core.interface.atomic import Ion, Level, Transition

Create Ion with levels and transitions

ion = Ion(levels=[...], transitions=[...])
fig = generate_energy_level_plot(ion, figure={'figsize': (10, 8)})
fig.show()

some figs of the tests included