Exécution de votre code local en tant que tâche hybride

Amazon Braket Hybrid Jobs fournit une orchestration entièrement gérée d'algorithmes hybrides quantiques-classiques, combinant les EC2 ressources informatiques d'Amazon avec l'accès à l'unité de traitement quantique Amazon Braket (). QPU Les tâches quantiques créées dans le cadre d'une tâche hybride sont mises en file d'attente en priorité par rapport aux tâches quantiques individuelles afin que vos algorithmes ne soient pas interrompus par les fluctuations de la file d'attente des tâches quantiques. Chacune QPU gère une file d'attente de tâches hybrides distincte, ce qui garantit qu'une seule tâche hybride peut être exécutée à la fois.

Création d'une tâche hybride à partir du code Python local

Vous pouvez exécuter votre code Python local sous forme d'Amazon Braket Hybrid Job. Vous pouvez le faire en annotant votre code à l'aide d'un @hybrid_job décorateur, comme illustré dans l'exemple de code suivant. Pour les environnements personnalisés, vous pouvez choisir d'utiliser un conteneur personnalisé depuis Amazon Elastic Container Registry (ECR).

Note

Seul Python 3.10 est pris en charge par défaut.

Vous pouvez utiliser le @hybrid_job décorateur pour annoter une fonction. Braket transforme le code contenu dans le décorateur en un script d'algorithme de travail hybride Braket. La tâche hybride invoque ensuite la fonction dans le décorateur sur une instance AmazonEC2. Vous pouvez suivre la progression de la tâche avec job.state() ou avec la console Braket. L'exemple de code suivant montre comment exécuter une séquence de cinq états sur le State Vector Simulator (SV1) device.

from braket.aws import AwsDevice
from braket.circuits import Circuit, FreeParameter, Observable
from braket.devices import Devices
from braket.jobs.hybrid_job import hybrid_job
from braket.jobs.metrics import log_metric

device_arn = Devices.Amazon.SV1


@hybrid_job(device=device_arn)  # choose priority device
def run_hybrid_job(num_tasks=1):
    device = AwsDevice(device_arn)  # declare AwsDevice within the hybrid job

    # create a parametric circuit
    circ = Circuit()
    circ.rx(0, FreeParameter("theta"))
    circ.cnot(0, 1)
    circ.expectation(observable=Observable.X(), target=0)

    theta = 0.0  # initial parameter

    for i in range(num_tasks):
        task = device.run(circ, shots=100, inputs={"theta": theta})  # input parameters
        exp_val = task.result().values[0]

        theta += exp_val  # modify the parameter (possibly gradient descent)

        log_metric(metric_name="exp_val", value=exp_val, iteration_number=i)

    return {"final_theta": theta, "final_exp_val": exp_val}

Vous créez la tâche hybride en invoquant la fonction comme vous le feriez pour les fonctions Python normales. Cependant, la fonction de décorateur renvoie le descripteur de tâche hybride plutôt que le résultat de la fonction. Pour récupérer les résultats une fois l'opération terminée, utilisezjob.result().

job = run_hybrid_job(num_tasks=1)
result = job.result() 

L'argument device dans le @hybrid_job décorateur indique le périphérique auquel la tâche hybride a un accès prioritaire, dans ce cas, SV1 simulateur. Pour obtenir la QPU priorité, vous devez vous assurer que le périphérique ARN utilisé dans la fonction correspond à celui spécifié dans le décorateur. Pour plus de commodité, vous pouvez utiliser la fonction d'assistance get_job_device_arn() pour capturer le périphérique ARN déclaré dans@hybrid_job.

Note

Chaque tâche hybride a un temps de démarrage d'au moins une minute car elle crée un environnement conteneurisé sur Amazon. EC2 Ainsi, pour des charges de travail très courtes, telles qu'un circuit unique ou un lot de circuits, il peut suffire d'utiliser des tâches quantiques.

Hyperparamètres

La run_hybrid_job() fonction utilise l'argument num_tasks pour contrôler le nombre de tâches quantiques créées. La tâche hybride le capture automatiquement sous forme d'hyperparamètre.

Note

Les hyperparamètres sont affichés dans la console Braket sous forme de chaînes limitées à 2 500 caractères.

Métriques et journalisation

Dans la run_hybrid_job() fonction, les métriques issues d'algorithmes itératifs sont enregistrées aveclog_metrics. Les métriques sont automatiquement tracées sur la page de la console Braket, sous l'onglet Job hybride. Vous pouvez utiliser des métriques pour suivre les coûts quantiques des tâches en temps quasi réel pendant l'exécution d'une tâche hybride avec le système de suivi des coûts Braket. L'exemple ci-dessus utilise le nom de métrique « probabilité » qui enregistre la première probabilité du type de résultat.

Récupération des résultats

Une fois la tâche hybride terminée, vous pouvez job.result() récupérer les résultats des tâches hybrides. Tous les objets du relevé de retour sont automatiquement capturés par Braket. Notez que les objets renvoyés par la fonction doivent être un tuple, chaque élément étant sérialisable. Par exemple, le code suivant montre un exemple de fonctionnement et un exemple d'échec.

@hybrid_job(device=Devices.Amazon.SV1)
def passing():
    np_array = np.random.rand(5)
    return np_array  # serializable
    
@hybrid_job(device=Devices.Amazon.SV1)
def failing():
    return MyObject() # not serializable

Nom du job

Par défaut, le nom de cette tâche hybride est déduit du nom de la fonction. Vous pouvez également spécifier un nom personnalisé d'une longueur maximale de 50 caractères. Par exemple, dans le code suivant, le nom de la tâche est « my-job-name ».

@hybrid_job(device=Devices.Amazon.SV1, job_name="my-job-name")
def function():
    pass

Mode local

Les tâches locales sont créées en ajoutant l'argument local=True au décorateur. Cela exécute la tâche hybride dans un environnement conteneurisé sur votre environnement informatique local, tel que votre ordinateur portable. Les emplois locaux ne sont pas prioritaires dans les files d'attente pour les tâches quantiques. Dans les cas avancés, tels que les tâches multi-nœuds ou localesMPI, peuvent avoir accès aux variables d'environnement Braket requises. Le code suivant crée une tâche hybride locale avec le périphérique comme SV1 simulateur.

@hybrid_job(device=Devices.Amazon.SV1, local=True)
def run_hybrid_job(num_tasks = 1):
    return ...

Toutes les autres options d'emploi hybrides sont prises en charge. Pour une liste des options, consultez le module braket.jobs.quantum_job_creation.

Installation de packages Python et de code source supplémentaires

Vous pouvez personnaliser votre environnement d'exécution pour utiliser vos packages Python préférés. Vous pouvez utiliser un requirements.txt fichier, une liste de noms de packages ou apporter votre propre conteneur (BYOC). Pour personnaliser un environnement d'exécution à l'aide d'un requirements.txt fichier, reportez-vous à l'exemple de code suivant.

@hybrid_job(device=Devices.Amazon.SV1, dependencies="requirements.txt")
def run_hybrid_job(num_tasks = 1):
    return ...

Par exemple, le requirements.txt fichier peut inclure d'autres packages à installer.

qiskit 
pennylane >= 0.31
mitiq == 0.29

Vous pouvez également fournir les noms des packages sous forme de liste Python comme suit.

@hybrid_job(device=Devices.Amazon.SV1, dependencies=["qiskit", "pennylane>=0.31", "mitiq==0.29"])
def run_hybrid_job(num_tasks = 1):
    return ...

Le code source supplémentaire peut être spécifié sous la forme d'une liste de modules ou d'un seul module, comme dans l'exemple de code suivant.

@hybrid_job(device=Devices.Amazon.SV1, include_modules=["my_module1", "my_module2"])
def run_hybrid_job(num_tasks = 1):
    return ...

Enregistrer et charger des données dans une instance de tâche hybride

Spécification des données d'entraînement en entrée

Lorsque vous créez une tâche hybride, vous pouvez fournir des ensembles de données de formation en entrée en spécifiant un bucket Amazon Simple Storage Service (Amazon S3). Vous pouvez également spécifier un chemin local, puis Braket télécharge automatiquement les données vers Amazon S3 à l'adresse. s3://<default_bucket_name>/jobs/<job_name>/<timestamp>/data/<channel_name> Si vous spécifiez un chemin local, le nom du canal est par défaut « input ». Le code suivant montre un fichier numpy à partir du chemin data/file.npy local.

@hybrid_job(device=Devices.Amazon.SV1, input_data="data/file.npy")
def run_hybrid_job(num_tasks = 1):
    data = np.load("data/file.npy")
    return ...

Pour S3, vous devez utiliser la fonction get_input_data_dir() d'assistance.

s3_path = "s3://amazon-braket-us-west-1-961591465522/job-data/file.npy"

@hybrid_job(device=None, input_data=s3_path)
def job_s3_input():
    np.load(get_input_data_dir() + "/file.npy")
    
@hybrid_job(device=None, input_data={"channel": s3_path})
def job_s3_input_channel():
    np.load(get_input_data_dir("channel") + "/file.npy")

Vous pouvez spécifier plusieurs sources de données d'entrée en fournissant un dictionnaire des valeurs de canal et des chemins S3 URIs ou locaux.

input_data = {
    "input": "data/file.npy",
    "input_2": "s3://my-bucket/data.json"
} 


@hybrid_job(device=None, input_data=input_data)
def multiple_input_job():
    np.load(get_input_data_dir("input") + "/file.npy")
    np.load(get_input_data_dir("input_2") + "/data.json")

Note

Lorsque les données d'entrée sont volumineuses (> 1 Go), le temps d'attente est long avant que la tâche ne soit créée. Cela est dû aux données d'entrée locales lorsqu'elles sont téléchargées pour la première fois dans un compartiment S3, puis le chemin S3 est ajouté à la demande de travail. Enfin, la demande d'emploi est soumise au service Braket.

Sauvegarde des résultats dans S3

Pour enregistrer les résultats non inclus dans l'instruction de retour de la fonction décorée, vous devez ajouter le répertoire approprié à toutes les opérations d'écriture de fichiers. L'exemple suivant montre la sauvegarde d'un tableau numpy et d'une figure matplotlib.

@hybrid_job(device=Devices.Amazon.SV1)
def run_hybrid_job(num_tasks = 1):
    result = np.random.rand(5)
    
    # save a numpy array
    np.save("result.npy", result)
    
    # save a matplotlib figure
    plt.plot(result)
    plt.savefig("fig.png")
    return ...

Tous les résultats sont compressés dans un fichier nommémodel.tar.gz. Vous pouvez télécharger les résultats à l'aide de la fonction job.result() Python ou en accédant au dossier des résultats depuis la page des tâches hybrides dans la console de gestion Braket.

Sauvegarde et reprise depuis les points de contrôle

Pour les tâches hybrides de longue durée, il est recommandé de sauvegarder régulièrement l'état intermédiaire de l'algorithme. Vous pouvez utiliser la fonction d'save_job_checkpoint()assistance intégrée ou enregistrer des fichiers dans le AMZN_BRAKET_JOB_RESULTS_DIR chemin. Ce dernier est disponible avec la fonction d'assistance. get_job_results_dir()

Voici un exemple pratique minimal pour enregistrer et charger des points de contrôle avec un décorateur de tâches hybride :

from braket.jobs import save_job_checkpoint, load_job_checkpoint, hybrid_job

@hybrid_job(device=None, wait_until_complete=True)
def function():
    save_job_checkpoint({"a": 1})

job = function()
job_name = job.name
job_arn = job.arn

@hybrid_job(device=None, wait_until_complete=True, copy_checkpoints_from_job=job_arn)
def continued_function():
    load_job_checkpoint(job_name)

continued_job = continued_function()

Dans le premier job hybride, save_job_checkpoint() il est appelé avec un dictionnaire contenant les données que nous voulons enregistrer. Par défaut, chaque valeur doit être sérialisable sous forme de texte. Pour le pointage d'objets Python plus complexes, tels que des tableaux numpy, vous pouvez définir. data_format = PersistedJobDataFormat.PICKLED_V4 Ce code crée et remplace un fichier de point de contrôle portant le nom par défaut <jobname>.json dans vos artefacts de tâches hybrides dans un sous-dossier appelé « points de contrôle ».

Pour créer un nouveau travail hybride afin de continuer depuis le point de contrôle, nous devons indiquer copy_checkpoints_from_job=job_arn où se job_arn trouve le travail hybride ARN du travail précédent. Ensuite, nous load_job_checkpoint(job_name) chargeons depuis le point de contrôle.

Bonnes pratiques pour les décorateurs hybrides

Adoptez l'asynchronicité

Les tâches hybrides créées avec l'annotation du décorateur sont asynchrones : elles s'exécutent une fois que les ressources classiques et quantiques sont disponibles. Vous suivez la progression de l'algorithme à l'aide du Braket Management Console ou Amazon CloudWatch. Lorsque vous soumettez votre algorithme à exécuter, Braket l'exécute dans un environnement conteneurisé évolutif et les résultats sont récupérés lorsque l'algorithme est terminé.

Exécuter des algorithmes variationnels itératifs

Les tâches hybrides vous fournissent les outils nécessaires pour exécuter des algorithmes classiques quantiques itératifs. Pour les problèmes purement quantiques, utilisez des tâches quantiques ou un lot de tâches quantiques. L'accès prioritaire à certains QPUs est particulièrement avantageux pour les algorithmes variationnels de longue durée nécessitant plusieurs appels itératifs QPUs avec un traitement classique entre les deux.

Déboguer en mode local

Avant d'exécuter une tâche hybride sur unQPU, il est recommandé de l'exécuter d'abord sur le simulateur SV1 pour vérifier qu'elle s'exécute comme prévu. Pour les tests à petite échelle, vous pouvez les exécuter en mode local pour une itération et un débogage rapides.

Améliorez la reproductibilité avec Bring your own container () BYOC

Créez une expérience reproductible en encapsulant votre logiciel et ses dépendances dans un environnement conteneurisé. En regroupant l'ensemble de votre code, de vos dépendances et de vos paramètres dans un conteneur, vous évitez les conflits potentiels et les problèmes de version.

Simulateurs distribués multi-instances

Pour exécuter un grand nombre de circuits, pensez à utiliser le MPI support intégré pour exécuter des simulateurs locaux sur plusieurs instances dans le cadre d'une seule tâche hybride. Pour plus d'informations, consultez la section Simulateurs intégrés.

Utiliser des circuits paramétriques

Les circuits paramétriques que vous soumettez à partir d'une tâche hybride sont automatiquement compilés sur certains à QPUs l'aide d'une compilation paramétrique afin d'améliorer les temps d'exécution de vos algorithmes.

Point de contrôle périodique

Pour les tâches hybrides de longue durée, il est recommandé de sauvegarder régulièrement l'état intermédiaire de l'algorithme.

Pour plus d'exemples, de cas d'utilisation et de bonnes pratiques, consultez les exemples d'Amazon GitHub Braket.