from_harmonic_modes fails when Lanczos breaks down before full mode count

[joanjcaceres]

Summary

Circuit.from_harmonic_modes raises a length-mismatch ValueError for valid harmonic inputs when the Lanczos reduction terminates before reaching len(frequencies).

Minimal repro

from sccircuits import Circuit
Circuit.from_harmonic_modes(
frequencies=[5.0, 6.0],
phase_zpf=[0.1, 0.0],
dimensions=[10, 10],
Ej=1.0,
)

Observed error

ValueError: linear_frequencies and linear_couplings must each have length len(dimensions) - 1.

Another repro

Circuit.from_harmonic_modes(
frequencies=[5.0, 6.0, 7.0],
phase_zpf=[0.1, 0.2, 0.0],
dimensions=[10, 10, 10],
Ej=1.0,
)

Root cause

harmonic_modes_to_physical returns alpha[1:] and beta directly from lanczos_krylov in sccircuits/circuit.py. When Lanczos hits natural breakdown early, status["m"] is smaller than len(frequencies), so linear_frequencies and linear_couplings are shorter than len(dimensions) - 1. Circuit.init then rejects them.

Relevant code

• sccircuits/circuit.py:37-48
• sccircuits/circuit.py:170-176

Notes

For the 2-mode repro above, harmonic_modes_to_physical returns status={"breakdown": True, "m": 1, ...}, so both returned linear arrays are empty. For frequencies=[5.0, 6.0, 7.0] and phase_zpf=[0.1, 0.2, 0.0], it returns status={"breakdown": True, "m": 2, ...}, so the linear arrays have length 1 instead of 2.

Potential fix directions

• Complete the basis after natural breakdown and include the remaining zero-coupled spectator modes.
• Or raise a clearer error from from_harmonic_modes when the Krylov dimension is smaller than the requested mode count.