ทำความเข้าใจการเปลี่ยนแปลง package ของ Qiskit v1.0 ที่ส่งผลกระทบ

Qiskit v1.0 ใช้โครงสร้าง packaging ที่แตกต่างจาก Qiskit เวอร์ชันก่อนหน้า และอาจทำให้เกิดปัญหาในสภาพแวดล้อมที่ใช้ package ที่ยังไม่พร้อมสำหรับ Qiskit v1.0

ข้อควรระวัง

อย่าพยายาม upgrade Python virtual environment ที่มีอยู่แล้วไปยัง Qiskit v1.0 ในที่เดิม

เราจะไม่ทำการเปลี่ยนแปลง packaging ที่ส่งผลกระทบแบบนี้อีกในอนาคต นี่เป็นเหตุการณ์ที่เกิดขึ้นครั้งเดียว ตอนที่ปล่อย Qiskit v1.0 เพื่อให้เรื่อง packaging ง่ายที่สุดเท่าที่จะเป็นไปได้ในอนาคต

หน้านี้มีข้อมูลรายละเอียดเกี่ยวกับ Qiskit package ก่อน 1.0 และเหตุผลที่เราทำการเปลี่ยนแปลง packaging ที่ส่งผลกระทบ

เรารู้ว่าการเปลี่ยนแปลงนี้ไม่สะดวก แต่มันทำให้ Qiskit กลับมาใช้โครงสร้าง package ที่เรียบง่ายเหมือนที่ Python package ส่วนใหญ่ใช้ ซึ่งจะง่ายกว่าสำหรับผู้ใช้ นักพัฒนา และผู้เขียน library หลังจากการเปลี่ยนผ่าน Qiskit v1.0 เสร็จสิ้น

บทนำ: อภิธานศัพท์ Python packaging

เพื่ออธิบายว่า Qiskit metapackage เก่าถูกจัดโครงสร้างอย่างไร และมันเปลี่ยนแปลงไปอย่างไรพร้อมกับการปล่อย Qiskit v1.0 ด้านล่างคืออภิธานศัพท์ของคำเฉพาะใน Python packaging ที่ใช้กันทั่วไป คำต่อไปนี้มีความหมายเฉพาะที่เราจะใช้ในเอกสารนี้

คลิกเพื่ออ่านอภิธานศัพท์ของหน้านี้

• module: ไฟล์ Python ไฟล์เดียว

• package: ไดเรกทอรีที่มี __init__.py และไฟล์หรือ package อื่นๆ ที่ Python สามารถอ่านได้ นี่คือโค้ดจริงที่ติดตั้งอยู่บนคอมพิวเตอร์ของคุณ และเป็นสิ่งที่รันเมื่อคุณเรียก import something Python ถือว่าไดเรกทอรีใดก็ตามที่อยู่ใน search path เป็นสิ่งที่คุณสามารถ import ได้ (และจะ import รายการเพิ่มเติมอีกมาก)

  นี่ไม่ใช่ object เดียวกับที่คุณ pip install (ซึ่งคือ distribution) แต่โดยทั่วไปสิ่งที่คุณ pip install และสิ่งที่คุณ import จะมีชื่อเดียวกัน

• submodule, subpackage: เหล่านี้เป็นคำที่ไม่แม่นยำ แต่ใช้กันทั่วไป ส่วน sub หมายถึง "อยู่ภายใน package" submodule คือ module และ subpackage คือ package แต่เป็นส่วนหนึ่งของ package ที่ใหญ่กว่า

• namespace package: package ที่สามารถมี submodule หรือ subpackage ติดตั้งเข้าไปได้โดย distribution อื่น สำคัญมากที่ distribution เดียวที่มีส่วนร่วมใน namespace package ไม่จำเป็นต้องเป็นเจ้าของไฟล์ที่ติดตั้งทั้งหมด จึงอาจยุ่งยากในการ uninstall หรือ upgrade อย่างสมบูรณ์

• distribution: ไฟล์ Python ที่บีบอัด ไฟล์ข้อมูล และ metadata ที่ถูกดาวน์โหลดเมื่อคุณรัน pip install something โดยทั่วไป distribution มี package เดียวพอดีและ metadata เกี่ยวกับวิธีการติดตั้ง (requirements และอื่นๆ) แต่ไม่จำเป็นต้องเป็นเช่นนั้น distribution สามารถมี module หรือ package ตั้งแต่ศูนย์ขึ้นไป

  ถ้าคุณคุ้นเคยกับ "package managers" นอกบริบท Python เช่น apt จาก Debian/Ubuntu หรือ Homebrew บน macOS สิ่งที่พวกเขาเรียกว่า "package" Python เรียกว่า distribution และไม่มีความตรงกันทุกประการสำหรับสิ่งที่ Python เรียกว่า package

  แหล่งข้อมูลส่วนใหญ่ที่พูดถึง Python packaging ใช้คำว่า package เพื่อหมายถึงทั้ง distribution และ package และคุณต้องอ้างอิงบริบทเพื่อทำความเข้าใจว่าหมายความว่าอะไร โดยทั่วไป ถ้าคุณ import มัน แหล่งข้อมูลหมายถึง "package" และถ้าคุณ pip install มัน แหล่งข้อมูลหมายถึง "distribution"

• search path: เมื่อพยายาม import something Python ค้นหาในรายการสถานที่ที่กำหนดล่วงหน้าสำหรับ module หรือ package ที่ชื่อ something รายการสถานที่นั้นคือ search path คุณสามารถดูและแก้ไข search path ได้ใน sys.path

• requirement: distribution มีข้อมูลเกี่ยวกับ distribution อื่นที่ต้องพึ่งพาเมื่อติดตั้ง distribution อื่นใดก็ตามที่จำเป็นคือ requirement และ package manager (โดยปกติคือ pip หรือ conda) ควรตรวจสอบว่า requirement ทั้งหมดถูกติดตั้งด้วยเวอร์ชันที่เข้ากันได้

Python มีความยืดหยุ่นสูง และอาจเกิดความซับซ้อนต่างๆ ขึ้นได้ เช่น เป็นไปได้ที่ module หรือ package ไม่ตรงกับไฟล์บนดิสก์ หรืออาจเป็น compiled extensions

search path ไม่ได้เป็นแค่การค้นหาผ่านไดเรกทอรี แต่สำหรับการอภิปรายนี้ เฉพาะไฟล์บนดิสก์เท่านั้นที่เกี่ยวข้อง ความซับซ้อนเพิ่มเติมไม่จำเป็นต้องเข้าใจปัญหาที่อธิบายในส่วนนี้ ดังนั้นคุณสามารถใช้โมเดลที่อธิบายข้างต้นได้

โครงสร้าง Qiskit เก่า

ในอดีต Qiskit ประกอบด้วย Python distribution หลายตัว: qiskit-terra แกนหลักของ compiler; qiskit-aer simulator ประสิทธิภาพสูง; IBM Quantum® provider ดั้งเดิม; และ package ที่ล้าสมัยหลายตัวที่ให้ฟีเจอร์ algorithm หรือการรันการทดลองเชิงสำรวจ เพื่อความสะดวกของผู้ใช้ เรายังจัดเตรียม Python distribution ที่ชื่อ qiskit ซึ่งไม่มีโค้ดของตัวเอง แต่ทำให้ component อื่นๆ ทั้งหมดถูกติดตั้ง เราเรียกสิ่งนี้ว่า metapackage โดยอุปมาจากแนวคิดที่คล้ายคลึงกันใน package manager อื่นๆ โค้ดของแกนหลัก Qiskit อยู่ใน qiskit-terra ซึ่งเป็นเจ้าของ root ของ Python package qiskit กล่าวอีกนัยหนึ่ง qiskit-terra ควบคุมสิ่งที่เกิดขึ้นเมื่อคุณรัน import qiskit จนถึง Qiskit v1.0, package qiskit เป็น namespace package และมี namespace package ที่สองที่ qiskit.providers

การจัดระเบียบนี้ทำให้เราและผู้ใช้พบปัญหาหลายอย่าง

ตัวอย่างเช่น library ปลายทางที่พึ่งพา Qiskit มักต้องการแค่แกนหลักของ compiler และไม่ต้องการ ecosystem ขนาดใหญ่ที่มาพร้อม pip install qiskit ดังนั้นพวกเขาจะระบุ requirement ได้อย่างถูกต้องว่าเป็น qiskit-terra อย่างไรก็ตาม เมื่อผู้คนพยายาม uninstall Qiskit โดยรัน pip uninstall qiskit, pip พบปัญหา:

• pip ไม่ลบ distribution ที่ไม่ได้ใช้แล้ว ดังนั้น pip uninstall qiskit แทบไม่ทำอะไร ไม่มีโค้ดใน distribution จึงไม่มีโค้ดถูกลบ
• แม้ว่าจะลบโค้ดได้ distribution ปลายทางหลายตัวจะยังคงติดตั้งอยู่เพราะพวกเขาพึ่งพา qiskit-terra
• แม้ว่า qiskit-terra จะถูก uninstall อาจยังคงเหลือไดเรกทอรี qiskit ที่ import ได้โดยไม่มีโค้ดที่ใช้งานได้ เพราะมันเป็น namespace package

เมื่อติดตั้งหรือ upgrade distribution ด้วยคำสั่ง pip install, pip ก็ไม่คำนึงถึง requirement resolutions ก่อนหน้า เพราะมี package สองตัว การ upgrade package ที่ต้องการ qiskit-terra ให้ถูก upgrade ทำให้สภาพแวดล้อมไม่ถูกต้อง; pip upgrade qiskit-terra แต่ปล่อย qiskit ไว้โดยไม่เปลี่ยน มันแสดงคำเตือนในคำสั่ง pip install นี้และครั้งต่อๆ ไป แต่เพราะดูเหมือนไม่มีอะไรเสียหาย ผู้ใช้มักเพิกเฉยต่อคำเตือน และ pip ไม่ได้ raise สถานะ error หรือห้ามการดำเนินการ

เมื่อเวลาผ่านไป เราลบ element ออกจาก qiskit metapackage จนกระทั่ง เริ่มจาก Qiskit v0.44 เหลือแค่ qiskit-terra ใน component เหล่านี้ qiskit-aer ยังคงมีอยู่และมีการอัปเดตอยู่ แต่ตอนนี้ถูกติดตั้งเป็น distribution แยก

ในทำนองเดียวกัน เราได้ไม่สนับสนุนให้ library อื่นใช้ namespace hooks มากขึ้นเรื่อยๆ เราลบการใช้ hooks ของ Qiskit ล่าสุดใน package ที่ไม่ล้าสมัยด้วยการปล่อย Qiskit Aer v0.11 และ Python package ใหม่ qiskit_aer แม้ว่าจนถึง Qiskit v1.0 เราก็บังคับให้ namespace path qiskit.providers.aer ยังทำงานได้ เริ่มจาก Qiskit v1.0 เราได้ลบความสามารถสำหรับ package ในการขยาย namespace qiskit ใดๆ ดังนั้น pip uninstall บน distribution ที่ถูกต้องในสภาพแวดล้อมที่ถูกต้องตอนนี้ทำงานได้ตามที่คาดหวัง

โครงสร้าง Qiskit ใหม่

เริ่มจากเวอร์ชัน 1.0 Qiskit ประกอบด้วย distribution เดียวที่ชื่อ qiskit ซึ่งติดตั้ง package เดียว ก็คือ qiskit ด้วยเช่นกัน ซึ่งเป็นเจ้าของโค้ดทั้งหมดที่อยู่ในไดเรกทอรีของมัน นี่คือโครงสร้างปกติของโค้ด Python และเป็นโครงสร้างที่เรียบง่ายที่สุดและมีแนวโน้มเกิดข้อผิดพลาดน้อยที่สุด

qiskit-terra distribution บน PyPI จะไม่มีการอัปเดตเป็นเวอร์ชัน 1.0 หรือสูงกว่า มันถูกแทนที่ทั้งหมดโดย qiskit ชื่อ qiskit-terra ไม่ได้เกี่ยวข้องกับการติดตั้งอีกต่อไป อย่างไรก็ตาม qiskit-terra package ไม่ได้ถูกลบออกจาก PyPI และเราจะปล่อยให้เวอร์ชันล่าสุดอยู่ในสถานะทำงานได้ เพื่อให้โค้ดวิทยาศาสตร์เก่าและ package legacy สามารถใช้งานต่อได้ง่ายขึ้น

น่าเสียดายที่เนื่องจาก legacy ของ metapackage และข้อบกพร่องใน pip ในฐานะ package manager มันไม่เป็นไปได้สำหรับเราที่จะทำ upgrade path ที่ราบรื่นสมบูรณ์ให้ผู้ใช้ไปยัง Qiskit v1.0 โดยเฉพาะอย่างยิ่งในขณะที่ package บางตัวพึ่งพา Qiskit เวอร์ชันก่อนหน้า และบางตัวต้องการเฉพาะ Qiskit v1.0+ ปัญหาเหล่านี้จะลดลงเมื่อ ecosystem มากขึ้น migrate ไปยัง Qiskit v1.0

Application module ไปอยู่ที่ไหน?

คุณอาจสังเกตว่าคำสั่ง pip install qiskit จะไม่รวม package เช่น qiskit-aer หรือ qiskit-nature อีกต่อไป ด้วยการลบโครงสร้าง metapackage package เหล่านี้หลายตัวถูกแบ่งออกเป็น distribution ที่ต้องติดตั้งแยกกัน

ก่อนการปล่อย Qiskit SDK v1.0 Qiskit ประกอบด้วย Python distribution ที่แตกต่างกันหลายตัว เช่น qiskit-terra แกนหลักของ compiler; qiskit-aer simulator ประสิทธิภาพสูง; IBM Quantum® provider ดั้งเดิม; และ package ที่ล้าสมัยหลายตัวที่ให้ฟีเจอร์ algorithm หรือการรันการทดลองเชิงสำรวจ

ถ้าคุณต้องการติดตั้ง package ที่เคยรวมอยู่ใน Qiskit metapackage ก่อนหน้า ให้เยี่ยมชม Qiskit ecosystem เพื่อหา package ที่เหมาะสมกับความต้องการของคุณ คุณยังสามารถอ่าน v1.0 migration guide สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีการติดตั้ง distribution ใหม่