Die grundlegenden Paketänderungen in Qiskit v1.0 verstehen

Qiskit v1.0 verwendet eine andere Paketstruktur als frühere Qiskit-Versionen und wird in Umgebungen, die Pakete nutzen, die noch nicht für Qiskit v1.0 bereit sind, wahrscheinlich zu Problemen führen.

vorsicht

Versuche nicht, eine bestehende virtuelle Python-Umgebung direkt auf Qiskit v1.0 zu aktualisieren.

Wir werden in Zukunft keine ähnlich grundlegenden Paketierungsänderungen mehr vornehmen. Dies ist ein einmaliges Ereignis anlässlich der Veröffentlichung von Qiskit v1.0, damit unsere Paketierungsstrategie künftig so unkompliziert wie möglich ist.

Diese Seite enthält detaillierte Informationen über das Qiskit-Paket vor Version 1.0 und erklärt, warum wir diese grundlegenden Paketierungsänderungen vorgenommen haben.

Wir wissen, dass die Änderung unbequem ist, aber sie stellt die einfache Paketstruktur wieder her, die die meisten Python-Pakete verwenden. Nach Abschluss des Übergangs zu Qiskit v1.0 wird das für Nutzer, Entwickler und Bibliotheksautoren einfacher sein.

Vorwort: Glossar der Python-Paketierungs-Terminologie

Um besser erklären zu können, wie das alte Qiskit-Metapaket aufgebaut war und wie sich das mit der Veröffentlichung von Qiskit v1.0 geändert hat, findest du unten ein Glossar häufig verwendeter Fachbegriffe aus der Python-Paketierung. Die folgenden Begriffe haben spezifische Bedeutungen, die wir in diesem Dokument verwenden.

Hier klicken, um das Glossar dieser Seite zu lesen

• module: Eine einzelne Python-Datei.

• package: Ein Verzeichnis, das eine __init__.py und andere Dateien oder Pakete enthält, die Python lesen kann. Dies ist der eigentliche Code, der auf deinem Computer installiert ist, und was ausgeführt wird, wenn du import something ausführst. Python betrachtet jedes Verzeichnis, das sich im Suchpfad befindet, als etwas, das du importieren kannst (und importiert dabei viele zusätzliche Elemente).

  Das ist nicht dasselbe Objekt, das du mit pip install installierst (was eine distribution ist), aber in der Regel haben das, was du mit pip install installierst, und das, was du mit import einbindest, denselben Namen.

• submodule, subpackage: Das sind ungenaue Begriffe, die aber häufig verwendet werden. Der sub-Teil bedeutet „innerhalb eines Pakets enthalten". Ein Submodul ist ein Modul und ein Subpaket ist ein Paket, aber sie sind Teil eines größeren Pakets.

• namespace package: Ein Paket, in das Submodule oder Subpakete von anderen distributions installiert werden können. Entscheidend ist, dass keine einzelne Distribution, die zu einem Namespace-Paket beiträgt, zwingend alle installierten Dateien besitzt – daher kann es schwierig sein, eines vollständig zu deinstallieren oder zu aktualisieren.

• distribution: Die komprimierten Python-Dateien, Datendateien und Metadaten, die heruntergeladen werden, wenn du pip install something ausführst. Oft enthält eine Distribution genau ein Paket und die Metadaten darüber, wie es installiert werden soll (seine Anforderungen usw.), aber das ist nicht zwingend. Eine Distribution kann null oder mehr Module oder Pakete enthalten.

  Wenn du mit „Paketmanagern" außerhalb des Python-Kontexts vertraut bist, etwa apt von Debian/Ubuntu oder Homebrew auf macOS, dann ist das, was diese ein „Paket" nennen, in Python eine Distribution, und es gibt keine genaue Entsprechung für das, was Python ein Paket nennt.

  Die meisten Quellen, die über Python-Paketierung sprechen, verwenden den Begriff package sowohl für Distributions als auch für Packages, und du musst den Kontext heranziehen, um zu verstehen, was gemeint ist. Im Allgemeinen gilt: Wenn du es mit import einbindest, meint die Quelle „package", und wenn du es mit pip install installierst, meint sie „distribution".

• search path: Wenn Python versucht, import something auszuführen, durchsucht es eine vordefinierte Liste von Orten nach einem Modul oder Paket namens something. Diese Liste von Orten ist der search path. Du kannst den Suchpfad in sys.path einsehen und verändern.

• requirement: Eine Distribution enthält Informationen über andere Distributions, von denen sie bei der Installation abhängt. Jede andere Distribution, die notwendig ist, ist eine requirement, und der Paketmanager (normalerweise pip oder conda) sollte sicherstellen, dass alle Anforderungen mit kompatiblen Versionen installiert sind.

Python ist hochgradig dynamisch, und es können viele Komplexitäten entstehen; zum Beispiel ist es möglich, dass ein module oder package nicht mit Dateien auf der Festplatte übereinstimmt oder dass es sich um kompilierte Erweiterungen handelt.

Der search path ist nicht nur eine Suche über Verzeichnisse, aber für diese Diskussion sind nur Dateien auf der Festplatte relevant. Weitere Komplikationen sind nicht nötig, um die in diesem Abschnitt beschriebenen Probleme zu verstehen, daher kannst du das oben beschriebene Modell verwenden.

Die alte Qiskit-Struktur

Historisch gesehen bestand Qiskit aus vielen Python-Distributions: qiskit-terra, dem Compiler-Kern; qiskit-aer, dem Hochleistungssimulator; dem ursprünglichen IBM Quantum®-Provider; sowie mehreren inzwischen veralteten Paketen, die bestimmte explorative algorithmische oder experimentdurchführende Funktionen bereitstellten. Zur Vereinfachung für die Nutzer haben wir auch eine Python-Distribution namens qiskit bereitgestellt, die keinen eigenen Code enthielt, aber dazu führte, dass alle anderen Komponenten installiert wurden. Wir nannten das das Metapaket, in Analogie zu ähnlichen Konzepten in anderen Paketmanagern. Der Code des Qiskit-Kerns befand sich in qiskit-terra, das das Root des Python-Pakets qiskit besaß. Mit anderen Worten: qiskit-terra steuerte, was passierte, wenn du import qiskit ausführtest. Bis Qiskit v1.0 war das qiskit-Paket ein Namespace-Paket und enthielt ein zweites Namespace-Paket unter qiskit.providers.

Diese Organisation verursachte uns und unseren Nutzern eine Reihe von Problemen.

Zum Beispiel benötigten nachgelagerte Bibliotheken, die von Qiskit abhingen, oft tatsächlich nur den Compiler-Kern und nicht den Rest des großen Ökosystems, das mit pip install qiskit kam. Sie würden daher korrekt ihre Anforderung als qiskit-terra angeben. Wenn Nutzer jedoch versuchten, Qiskit durch Ausführen von pip uninstall qiskit zu deinstallieren, stieß pip auf Probleme:

• pip entfernt keine Distributions, die nun nicht mehr verwendet werden. pip uninstall qiskit tat also fast nichts; es war kein Code in der Distribution vorhanden, also wurde kein Code entfernt.
• Selbst wenn Code entfernt worden wäre, würden viele nachgelagerte Distributions installiert bleiben, da sie von qiskit-terra abhingen.
• Selbst wenn qiskit-terra deinstalliert worden wäre, könnte noch ein importierbares qiskit-Verzeichnis ohne nutzbaren Code übrig bleiben, da es ein Namespace-Paket war.

Beim Installieren oder Aktualisieren von Distributions mit einem pip install-Befehl berücksichtigt pip auch keine früheren Anforderungsauflösungen. Da es zwei Pakete gab, führte das Aktualisieren eines Pakets, das ein Upgrade von qiskit-terra erforderte, zu einer ungültigen Umgebung; pip aktualisierte qiskit-terra, ließ aber qiskit unverändert. Es gab bei diesem und allen nachfolgenden pip install-Befehlen eine Warnung aus, aber da nichts kaputt erschien, ignorierten Nutzer die Warnung in der Regel, und pip gab keinen Fehlerstatus zurück und verbat keine Operationen.

Im Laufe der Zeit haben wir Elemente aus dem qiskit-Metapaket entfernt, bis ab Qiskit v0.44 nur noch qiskit-terra übrig blieb. Von diesen Komponenten existiert qiskit-aer noch und wird aktiv gepflegt, wird aber jetzt als separate Distribution installiert.

Ebenso haben wir andere Bibliotheken immer stärker davon abgeraten, die Namespace-Hooks zu verwenden. Wir haben die letzte Qiskit-Nutzung der Hooks in nicht veralteten Paketen mit der Veröffentlichung von Qiskit Aer v0.11 und seinem neuen qiskit_aer-Python-Paket entfernt, obwohl wir bis Qiskit v1.0 auch den Namespace-Pfad qiskit.providers.aer zum Funktionieren gezwungen haben. Ab Qiskit v1.0 haben wir die Möglichkeit entfernt, dass Pakete einen beliebigen qiskit-Namespace erweitern. Daher funktioniert pip uninstall für die korrekte Distribution in einer gültigen Umgebung nun wie erwartet.

Die neue Qiskit-Struktur

Ab Version 1.0 besteht Qiskit aus einer einzigen Distribution namens qiskit, die ein einziges Paket installiert, das ebenfalls qiskit heißt und den gesamten Code in seinem Verzeichnis besitzt. Das ist die normale Struktur von Python-Code und die einfachste und fehlerunanfälligste Struktur.

Die qiskit-terra-Distribution auf PyPI wird nie auf Version 1.0 oder höher aktualisiert; sie wird vollständig durch qiskit ersetzt. Der Name qiskit-terra ist nicht mehr an der Installation beteiligt. Das qiskit-terra-Paket wird jedoch nicht von PyPI entfernt, und wir werden seine neueste Version in einem funktionsfähigen Zustand belassen, damit alter wissenschaftlicher Code und Legacy-Pakete ihn weiterhin einfacher nutzen können.

Leider ist es aufgrund des Metapaket-Erbes und der Mängel von pip als Paketmanager nicht möglich, einen vollständig reibungslosen Upgrade-Pfad für Nutzer zu Qiskit v1.0 bereitzustellen, insbesondere solange einige Pakete von früheren Versionen von Qiskit abhängen und andere nur Qiskit v1.0+ erfordern. Diese Probleme werden nachlassen, sobald mehr des Ökosystems zu Qiskit v1.0 migriert.

Wo sind die Anwendungsmodule hin?

Du wirst vielleicht bemerken, dass der Befehl pip install qiskit keine Pakete wie qiskit-aer oder qiskit-nature mehr enthält. Mit der Abschaffung der Metapaket-Struktur wurden viele dieser Pakete in Distributions aufgeteilt, die separat installiert werden müssen.

Vor der Veröffentlichung des Qiskit SDK v1.0 bestand Qiskit aus vielen verschiedenen Python-Distributions, wie qiskit-terra, dem Compiler-Kern; qiskit-aer, dem Hochleistungssimulator; dem ursprünglichen IBM Quantum®-Provider; sowie mehreren inzwischen veralteten Paketen, die bestimmte explorative algorithmische oder experimentdurchführende Funktionen bereitstellten.

Wenn du die Pakete installieren möchtest, die zuvor im Qiskit-Metapaket enthalten waren, besuche das Qiskit-Ökosystem, um eine Reihe von Paketen zu finden, die deinen Anforderungen entsprechen. Du kannst auch den v1.0-Migrationsleitfaden lesen, um mehr Informationen darüber zu erhalten, wie du die neue Distribution installierst.