Bug Report: Import Error with Python 3.14 and scipy 1.17.0 #78
Description
(Dear He Xu: I created this after diagnosing and solving my specific problem with Claude. Hopefully it can help other users.)
Environment:
- OS: macOS (Apple Silicon)
- Python: 3.14
- TB2J: 0.9.12.18
- sisl: 0.16.2
- scipy: 1.17.0
- Installation method: pip in virtual environment
Description:
TB2J fails to import with Python 3.14 and scipy 1.17.0 due to a breaking change in scipy. The sisl dependency (v0.16.2) attempts to import sph_harm from scipy.special, which has been removed or relocated in scipy 1.17.0.
Error Message:
ImportError: cannot import name 'sph_harm' from 'scipy.special'
Fuller traceback:
(TB2J) work> siesta2J.py --fdf_fname siesta.fdf --kmesh 7 7 1 --elements Cr_3d I
Traceback (most recent call last):
File "/Somedir/TB2J/lib/python3.14/site-packages/HamiltonIO/siesta/mysiesta_nc.py", line 2, in <module>
from sisl.io.siesta._help import _mat_spin_convert as _mat_siesta2sisl # noqa: F401
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...
File "/Somedir/TB2J/lib/python3.14/site-packages/sisl/utils/mathematics.py", line 27, in <module>
from scipy.special import sph_harm
ImportError: cannot import name 'sph_harm' from 'scipy.special' (/Somedir/TB2J/lib/python3.14/site-packages/scipy/special/__init__.py)
Root Cause:
- Python 3.14 is too new; most scientific packages lack pre-built wheels for it
- When pip installs scipy, it gets version 1.17.0 (the only version with Python 3.14 support)
- scipy 1.17.0 has breaking changes that sisl 0.16.2 hasn't adapted to yet
Workaround:
Use Python 3.12 or 3.13 with scipy ≤ 1.16.x:
(Using conda for environment control)
conda create -n TB2J python=3.12
conda activate TB2J
pip install "scipy>=1.11,<1.17"
pip install TB2J[siesta]Suggested Solutions:
- Documentation: Add a note in the installation docs warning against Python 3.14 and recommending Python 3.12/3.13
- Dependencies: Consider adding an upper bound for scipy in
setup.py/pyproject.tomluntil sisl is updated:
scipy>=1.9,<1.17
- Testing: Add Python 3.14 to CI/CD to catch these issues early
Additional Context:
This issue will likely resolve itself once sisl releases a version compatible with scipy 1.17.0, but in the meantime, users hitting this with fresh Python 3.14 installations may be confused.
Thank you for maintaining this excellent package!