Memahami perubahan paket Qiskit v1.0 yang merusak kompatibilitas

Qiskit v1.0 menggunakan struktur pengemasan yang berbeda dari versi Qiskit sebelumnya dan kemungkinan besar akan menyebabkan masalah di lingkungan yang menggunakan paket yang belum siap untuk Qiskit v1.0.

perhatian

Jangan mencoba mengupgrade lingkungan virtual Python yang sudah ada ke Qiskit v1.0 secara langsung.

Kami tidak akan membuat perubahan pengemasan yang merusak kompatibilitas serupa di masa depan. Ini adalah kejadian satu kali, saat rilis Qiskit v1.0, khusus agar kisah pengemasan kami semudah mungkin di masa depan.

Halaman ini berisi informasi terperinci tentang paket Qiskit pra-1.0 dan mengapa kami membuat perubahan pengemasan yang merusak kompatibilitas.

Kami tahu bahwa perubahan ini merepotkan, tapi ini mengembalikan Qiskit ke struktur paket sederhana yang digunakan oleh sebagian besar paket Python, yang akan lebih mudah bagi pengguna, pengembang, dan penulis pustaka setelah transisi Qiskit v1.0 selesai.

Pendahuluan: glosarium terminologi pengemasan Python

Untuk menjelaskan lebih baik bagaimana metapaket Qiskit lama disusun dan bagaimana itu telah berubah dengan rilis Qiskit v1.0, di bawah ini adalah glosarium istilah pengemasan Python yang umum digunakan. Kata-kata berikut memiliki arti spesifik yang akan kita gunakan dalam dokumen ini.

Klik di sini untuk membaca glosarium halaman ini

• module: Satu file Python.

• package: Direktori yang berisi __init__.py dan file atau paket lain yang bisa dibaca Python. Ini adalah kode aktual yang terinstal di komputermu, dan yang dieksekusi saat kamu menjalankan import something. Python menganggap setiap direktori yang ada di search path sebagai sesuatu yang bisa diimpor (dan akan mengimpor banyak item tambahan).

  Ini bukan objek yang sama yang kamu pip install (yang merupakan sebuah distribution), tapi biasanya apa yang kamu pip install dan apa yang kamu import memiliki nama yang sama.

• submodule, subpackage: Ini adalah istilah yang tidak presisi, tapi umum digunakan. Bagian sub berarti "terkandung di dalam sebuah package". Submodule adalah modul dan subpackage adalah paket, tapi keduanya merupakan bagian dari paket yang lebih besar.

• namespace package: Sebuah package yang dapat memiliki submodul atau subpackage yang diinstal ke dalamnya oleh distribution lain. Yang krusial, tidak ada satu distribution pun yang berkontribusi ke namespace package yang pasti memiliki semua file yang terinstal, sehingga bisa jadi sulit untuk menguninstall atau mengupgrade salah satunya secara menyeluruh.

• distribution: File Python terkompresi, file data, dan metadata yang diunduh saat kamu menjalankan pip install something. Biasanya, sebuah distribution berisi tepat satu package dan metadata tentang cara menginstalnya (persyaratannya dan sebagainya), tapi ini tidak diwajibkan. Sebuah distribution bisa berisi nol atau lebih modul atau paket.

  Jika kamu familiar dengan "package manager" di luar konteks Python, seperti apt dari Debian/Ubuntu atau Homebrew di macOS, maka apa yang mereka sebut "package", Python menyebutnya distribution, dan tidak ada padanan tepat untuk apa yang Python sebut sebagai package.

  Sebagian besar sumber yang membahas pengemasan Python menggunakan istilah package untuk merujuk pada distribution maupun package, dan kamu harus merujuk pada konteksnya untuk memahami maksudnya. Secara umum, jika kamu import sesuatu, sumber itu berarti "package", dan jika kamu pip install sesuatu, sumber itu berarti "distribution".

• search path: Saat mencoba import something, Python mencari di daftar tempat yang sudah ditentukan sebelumnya untuk modul atau package bernama something. Daftar tempat tersebut adalah search path. Kamu bisa melihat dan memodifikasi search path di sys.path.

• requirement: Sebuah distribution berisi informasi tentang distribution lain yang dibutuhkannya saat diinstal. Distribution lain yang diperlukan adalah sebuah requirement, dan package manager (biasanya pip atau conda) harus memastikan semua requirement diinstal dengan versi yang kompatibel.

Python sangat dinamis, dan banyak kompleksitas bisa muncul; misalnya, dimungkinkan bahwa sebuah module atau package tidak bersesuaian dengan file di disk, atau bahwa mereka adalah ekstensi yang dikompilasi.

Search path tidak hanya pencarian atas direktori, tapi untuk diskusi ini, hanya file di disk yang relevan. Komplikasi lebih lanjut tidak diperlukan untuk memahami masalah yang dijelaskan di bagian ini, jadi kamu bisa menggunakan model yang dijelaskan di atas.

Struktur Qiskit lama

Secara historis, Qiskit terdiri dari banyak distribusi Python: qiskit-terra, inti compiler; qiskit-aer, simulator berkinerja tinggi; provider IBM Quantum® asli; dan beberapa paket yang sekarang sudah usang yang menyediakan fitur algoritmik eksploratoris atau eksekusi eksperimen tertentu. Untuk kemudahan pengguna, kami juga menyediakan distribusi Python bernama qiskit, yang tidak mengandung kode sendiri, tapi menyebabkan semua komponen lain diinstal. Kami menyebut ini metapackage, dengan analogi ke konsep serupa di package manager lain. Kode inti Qiskit berada di qiskit-terra, yang memiliki root dari package Python qiskit. Dengan kata lain, qiskit-terra mengontrol apa yang terjadi saat kamu menjalankan import qiskit. Sampai Qiskit v1.0, package qiskit adalah namespace package dan mengandung namespace package kedua di qiskit.providers.

Organisasi ini menyebabkan cukup banyak masalah bagi kami dan pengguna kami.

Misalnya, pustaka downstream yang bergantung pada Qiskit seringkali hanya benar-benar membutuhkan inti compiler, dan tidak memerlukan sisa ekosistem besar yang datang dengan pip install qiskit. Mereka karena itu dengan benar menentukan requirement mereka sebagai qiskit-terra. Namun, saat orang mencoba menguninstall Qiskit dengan menjalankan pip uninstall qiskit, pip mengalami masalah:

• pip tidak menghapus distribusi yang sekarang tidak digunakan. Jadi pip uninstall qiskit hampir tidak melakukan apa-apa; tidak ada kode dalam distribusi, sehingga tidak ada kode yang dihapus.
• Bahkan jika menghapus kode, banyak distribusi downstream akan tetap terinstal karena bergantung pada qiskit-terra.
• Bahkan jika qiskit-terra diuninstall, mungkin masih meninggalkan direktori qiskit yang bisa diimpor tanpa kode yang bisa digunakan, karena itu adalah namespace package.

Saat menginstal atau mengupgrade distribusi dengan perintah pip install, pip juga tidak memperhitungkan resolusi requirement sebelumnya. Karena ada dua paket, mengupgrade paket yang mengharuskan qiskit-terra untuk diupgrade menyebabkan lingkungan yang tidak valid; pip mengupgrade qiskit-terra tapi membiarkan qiskit tidak berubah. Ia mengeluarkan peringatan pada perintah pip install ini dan semua perintah selanjutnya, tapi karena tidak ada yang tampak rusak, pengguna biasanya mengabaikan peringatan tersebut, dan pip tidak menampilkan status error atau melarang operasi.

Seiring waktu, kami menghapus elemen dari metapackage qiskit hingga, mulai Qiskit v0.44, hanya qiskit-terra yang tersisa. Dari komponen-komponen ini, qiskit-aer masih ada dan diperbarui secara aktif, tapi sekarang diinstal sebagai distribusi terpisah.

Demikian pula, kami semakin kuat melarang pustaka lain menggunakan namespace hooks. Kami menghapus penggunaan hooks Qiskit terakhir di paket yang tidak usang dengan rilis Qiskit Aer v0.11 dan package Python qiskit_aer yang baru, meskipun sampai Qiskit v1.0 kami juga memaksakan jalur namespace qiskit.providers.aer agar tetap berfungsi. Mulai Qiskit v1.0, kami telah menghapus kemampuan bagi paket untuk memperluas namespace qiskit mana pun. Dengan demikian, pip uninstall pada distribusi yang benar di lingkungan yang valid sekarang berfungsi seperti yang diharapkan.

Struktur Qiskit baru

Mulai versi 1.0, Qiskit terdiri dari satu distribusi, bernama qiskit, yang menginstal satu paket tunggal, juga bernama qiskit, yang memiliki semua kode yang terkandung dalam direktorinya. Ini adalah struktur normal kode Python, dan merupakan struktur paling sederhana dan paling sedikit rentan terhadap error.

Distribusi qiskit-terra di PyPI tidak akan pernah diperbarui ke versi 1.0 atau lebih tinggi; itu sepenuhnya digantikan oleh qiskit. Nama qiskit-terra tidak lagi terlibat dalam instalasi. Namun, paket qiskit-terra tidak dihapus dari PyPI, dan kami akan membiarkan versi terbarunya dalam keadaan berfungsi, sehingga kode ilmiah lama dan paket legacy dapat lebih mudah terus menggunakannya.

Sayangnya, karena warisan metapackage dan kekurangan di pip sebagai package manager, tidak mungkin bagi kami untuk membuat jalur upgrade yang sepenuhnya mulus bagi pengguna ke Qiskit v1.0, terutama saat beberapa paket bergantung pada versi Qiskit yang lebih lama, dan beberapa hanya memerlukan Qiskit v1.0+. Masalah-masalah ini akan berkurang seiring semakin banyak ekosistem yang bermigrasi ke Qiskit v1.0.

Ke mana modul aplikasi pergi?

Kamu mungkin memperhatikan bahwa perintah pip install qiskit tidak lagi menyertakan paket seperti qiskit-aer atau qiskit-nature. Dengan penghapusan struktur metapackage, banyak paket ini dibagi menjadi distribusi yang perlu diinstal secara terpisah.

Sebelum rilis Qiskit SDK v1.0, Qiskit terdiri dari banyak distribusi Python yang berbeda, seperti qiskit-terra, inti compiler; qiskit-aer, simulator berkinerja tinggi; provider IBM Quantum® asli; dan beberapa paket yang sekarang sudah usang yang menyediakan fitur algoritmik eksploratoris atau eksekusi eksperimen tertentu.

Jika kamu ingin menginstal paket yang sebelumnya termasuk dalam metapackage Qiskit, kunjungi ekosistem Qiskit untuk menemukan berbagai paket yang sesuai dengan kebutuhanmu. Kamu juga bisa membaca panduan migrasi v1.0 untuk informasi lebih lanjut tentang cara menginstal distribusi baru.