diff --git a/docs/en/architecture/quantum_jobs_in_detail.md b/docs/en/architecture/quantum_jobs_in_detail.md new file mode 100644 index 0000000..f0c1920 --- /dev/null +++ b/docs/en/architecture/quantum_jobs_in_detail.md @@ -0,0 +1,38 @@ +# Quantum Jobs in Detail + +## The Definition of Quantum Job + +The quantum job in OQTOPUS is a structure consisting of several fields, some of which also include subfields. +In this section, we describe how quantum jobs are structured. + +### Job Info + +`JobInfo` is a structure that holds data related to the execution of individual quantum jobs and is composed of the following fields + +- **`desc`** + The quantum job descriptor, detailed below. +- **`transpiled_code`** + The transpiled quantum program which is actually executed on a device. +- **`result`** + The computation result. For failed jobs, this field is empty. +- **`reason`** + The description of failure. For successful jobs, this field is empty. + +The job info descriptor is also a structure with fields varying depending on the job type. All job types have a `job_type` field in common, and its value determines the type of quantum job. + +Currently, the following types of jobs are supported. The structure of the job info descriptor for each job type is as follows: + +- **Sampling Job** + - `job_type`: `sampling` + - `code`: The quantum program of the job, written in OpenQASM3. + +- **Estimation Job** + - `job_type`: `estimation`. + - `code`: The quantum program of the job, written in OpenQASM3. + - `operators`: + +### Transpiler Info + +### Mitigation Info + +### Simulator Info diff --git a/docs/en/architecture/sequence_diagram.md b/docs/en/architecture/sequence_diagram.md index 176437a..775d7da 100644 --- a/docs/en/architecture/sequence_diagram.md +++ b/docs/en/architecture/sequence_diagram.md @@ -1,14 +1,9 @@ -# Sequences of Task Operations +# Sequences of Job Operations This page shows behavioral sequences of task operations. -Each sequence shows a series of steps from sending a request of task execution or cancellation to the completion of the operations. - -> [!NOTE] -> The `/tasks`, `/tasks/{taskId}/cancel`, and `/results` endpoints in the following sequence diagrams are actually implemented as separate endpoints specific to sampling and estimation tasks. -> For example, `/tasks` is actually implemented as `/tasks/sampling` and `/tasks/estimation`. -> The path part `/sampling` or `/estimation` is omitted in the sequence diagrams because the behavioral sequences of the both endpoints are the same. +Each sequence shows a series of steps from sending a request of job execution or cancellation to the completion of the operations. -## Sequence of Task Execution (Success Case) +## Sequence of Job Execution (Success Case) The following shows a sequence of successful job execution. It shows the steps of job submission by User, job execution by Provider, and retrieval of the execution result by User. @@ -20,50 +15,53 @@ sequenceDiagram participant Cloud as Cloud (Backend) participant Provider as Provider (Device ID is 'SC') - User->>Cloud: POST /tasks { "code": "OPENQASM ...", ... } - Note right of User: User submits a task - Note over Cloud: A new task is created. - Cloud-->>User: HTTP 200 OK { "taskId": } + User->>Cloud: POST /jobs { "job_info": "{ \"code\": \"OPENQASM ...\", ... }", ... } + Note right of User: User submits a job + Note over Cloud: A new job is created. + Cloud-->>User: HTTP 200 OK { "job_id": } - User->>Cloud: GET /tasks//status - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "submitted" } + User->>Cloud: GET /jobs//status + Cloud-->>User: HTTP 200 OK { "job_id": , "status": "submitted" } - Note over Provider: Provider starts getting the tasks. + Note over Provider: Provider starts getting jobs. Provider->>Cloud: GET /jobs - Note over Cloud: The task status is updated to ready. + Note over Cloud: The job status is updated to `ready`. Cloud-->>Provider: HTTP 200 OK - Note over Provider: Provider starts execution of the tasks
and sends requests to update their statuses to running. + Note over Provider: Provider starts execution of the jobs and sends
requests to update their statuses to `running`. Provider->>Cloud: PATCH /jobs/ { "status": "running" } - Note over Cloud: The task status is updated to running. + Note over Cloud: The job status is updated to `running`. Cloud-->>Provider: HTTP 200 OK - Provider->>Cloud: PATCH /tasks/ { "status": "running" } - Note over Cloud: The task status is updated to running. + Provider->>Cloud: PATCH /jobs/ { "status": "running" } + Note over Cloud: The job status is updated to `running`. Cloud-->>Provider: HTTP 200 OK - User->>Cloud: GET /tasks//status - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "running" } - Note over Provider: The execution of the task is successfully completed. - Provider->>Cloud: POST /results { "taskId": , "status": "succeeded", result: ... } + User->>Cloud: GET /jobs//status + Cloud-->>User: HTTP 200 OK { "job_id": , "status": "running" } + + Note over Provider: The execution of the job is successfully completed. + Provider->>Cloud: PATCH /jobs//job_info { "result": ... } - Note over Cloud: The received result of the task is inserted to the DB,
then the task status is changed to succeeded (via a DB trigger). + Note over Cloud: The result of the job is stored in the `job_info` JSON field
in the database, and the job status is updated to `success`. Cloud-->>Provider: HTTP 200 OK - User->>Cloud: GET /jobs//status - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "succeeded" } - User->>Cloud: GET /jobs/ - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "succeeded", "result": ... } + Cloud-->>User: HTTP 200 OK
{ "job_id": , "status": "succeeded", "job_info": "{ \"result\": ... }", ... } ``` -Provider periodically repeats the process of executing the tasks and sending the results. +Provider periodically repeats the process of executing the jobs and writting the results. The above diagram shows one iteration of the repeated process. +Each sequence shows a series of steps from sending a request of task execution or cancellation to the completion of the operations. + +> [!NOTE] +> The `job_info` field in the job is a JSON serialized string. + ### Data in the DB at Each Time Point -The followings show sample data in the DB at each point in the sequence diagram, -where there is one task submission to each of the two endpoints, `/tasks/sampling` and `/tasks/estimation`. +The followings show sample data in the database at each point in the sequence diagram, +where there is one job submission to each of the two endpoints, `/tasks/sampling` and `/tasks/estimation`. The numbers below correspond to the circled numbers in the sequence diagram. - (2) @@ -79,10 +77,10 @@ The numbers below correspond to the circled numbers in the sequence diagram. - tasks table: [success-case-tasks-14.csv](../../sample/architecture/success-case-tasks-14.csv) - results table: [success-case-results-14.csv](../../sample/architecture/success-case-results-14.csv) -## Sequence of Task Execution (Failure Case) +## Sequence of Job Execution (Failure Case) -The following shows a sequence in which a task execution fails. -Each step from the beginning until the task status is changed to running is the same as in the success case. +The following shows a sequence in which a job execution fails. +Each step from the beginning until the job status is changed to `running` is the same as in the success case. The colored part shows steps specific to the failure case. ```mermaid @@ -92,42 +90,40 @@ sequenceDiagram participant Cloud as Cloud (Backend) participant Provider as Provider (Device ID is 'SVSim') - User->>Cloud: POST /tasks { "code": "OPENQASM ...", ... } - Note right of User: User submits a task - Note over Cloud: A new task is created. - Cloud-->>User: HTTP 200 OK { "taskId": } + User->>Cloud: POST /jobs { "job_info": "{ \"code\": \"OPENQASM ...\", ... }", ... } - User->>Cloud: GET /tasks//status - Cloud-->>User: HTTP 200 OK { "jobId": , "status": "submitted" } + Note right of User: User submits a job + Note over Cloud: A new job is created. + Cloud-->>User: HTTP 200 OK { "job_id": } + + User->>Cloud: GET /jobs//status + Cloud-->>User: HTTP 200 OK { "job_id": , "status": "submitted" } - Note over Provider: Provider starts getting the tasks. + Note over Provider: Provider starts getting jobs. Provider->>Cloud: GET /jobs - Note over Cloud: The task status is updated to ready. + Note over Cloud: Suppose that the job status is set to `ready`. Cloud-->>Provider: HTTP 200 OK - Note over Provider: Provider starts execution of the tasks
and sends requests to update their statuses to running. - Provider->>Cloud: PATCH /tasks/ { "status": "running" } - Note over Cloud: The task status is updated to running. + Note over Provider: Provider starts execution of the jobs and sends
requests to update their statuses to `running`. + Provider->>Cloud: PATCH /jobs/ { "status": "running" } + Note over Cloud: The job status is updated to `running`. Cloud-->>Provider: HTTP 200 OK - Provider->>Cloud: PATCH /tasks/ { "status": "running" } - Note over Cloud: The task status is updated to running. + Provider->>Cloud: PATCH /jobs/ { "status": "running" } + Note over Cloud: The job status is updated to `running`. Cloud-->>Provider: HTTP 200 OK - User->>Cloud: GET /tasks//status - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "running" } + User->>Cloud: GET /jobs//status + Cloud-->>User: HTTP 200 OK { "job_id": , "status": "running" } rect rgb(255, 240, 240) - Note over Provider: The execution of the task is failed. - Provider->>Cloud: POST /results { "taskId": , "status": "failed", "reason": ... } - Note over Cloud: The received result of the task is inserted to the DB,
then the task status is changed to failed (via a DB trigger). + Note over Provider: The execution of the task is failed. + Provider->>Cloud: PATCH /jobs/{job ID-1}/job_info { "reason": "The reason of failure", ... } + Note over Cloud: The error description is stored in the `job_info` JSON
field in database, and the job status is set to `failed`. Cloud-->>Provider: HTTP 200 OK - User->>Cloud: GET /tasks//status - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "failed" } - - User->>Cloud: GET /results/ - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "failed", "reason": ...} + User->>Cloud: GET /jobs/ + Cloud-->>User: HTTP 200 OK
{ "job_id": , "status": "failed", "job_info": "{ \"reason\": \"The reason of failure\", ... }" } end ``` @@ -155,44 +151,41 @@ sequenceDiagram participant Cloud as Cloud (Backend) participant Provider as Provider (Device ID is 'SVSim') - User->>Cloud: POST /jobs//cancel - Note right of User: User sends a cancel requests for the task . - Note over Cloud: The task status is updated to cancelled + User->>Cloud: POST /jobs//cancel + Note right of User: User sends a cancel requests for the job . + Note over Cloud: The job status is updated to `cancelled` Cloud-->>User: HTTP 200 OK - User->>Cloud: GET /tasks//status - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "cancelled" } + User->>Cloud: GET /jobs//status + Cloud-->>User: HTTP 200 OK { "job_id": , "status": "cancelled" } Note over Provider: Provider tries to cancel the executions of the tasks. - Note over Provider: The execution of the task is successfully cancelled. - Provider->>Cloud: POST /results { "taskId": , "status": "cancelled", "reason": ... } + Note over Provider: The execution of the job is successfully cancelled. + Provider->>Cloud: PATCH /jobs//job_info { "job_id": , "reason": ... } - Note over Cloud: The received result of the task is inserted to the DB. + Note over Cloud: The received result is stored in the `job_info` JSON field of the job. Cloud-->>Provider: HTTP 200 OK - User->>Cloud: GET /tasks//status - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "cancelled" } - - User->>Cloud: GET /results/ - Cloud-->>User: HTTP 200 OK { "taskId": , "status": "cancelled", "reason": ... } + User->>Cloud: GET /jobs//status + Cloud-->>User: HTTP 200 OK { "job_id": , "status": "cancelled", "job_info": "{ \"reason\": ... }", ... } ``` -Provider periodically repeats the process of cancelling task executions and sending the cancellation results. +Provider periodically repeats the process of cancelling job executions and sending the cancellation results. The above diagram shows one iteration of the repeated process. ### Data in the DB at Each Time Point The followings show sample data in the DB at each point in the sequence diagram, -where there is one cancellation request to the endpoint `/tasks/sampling/{taskId}/cancel`. +where there is one cancellation request to the endpoint `/jobs/{job ID}/cancel`. The numbers below correspond to the circled numbers in the sequence diagram. - (1) - - tasks table: [cancel-case-tasks-01.csv](../../sample/architecture/cancel-case-tasks-01.csv) + - tasks table: [cancel-case-jobs-01.csv](../../sample/architecture/cancel-case-tasks-01.csv) - results table: no data - (2) - - tasks table: [cancel-case-tasks-02.csv](../../sample/architecture/cancel-case-tasks-02.csv) + - tasks table: [cancel-case-jobs-02.csv](../../sample/architecture/cancel-case-tasks-02.csv) - results table: no data - (6) - - tasks table: [cancel-case-tasks-08.csv](../../sample/architecture/cancel-case-tasks-08.csv) + - tasks table: [cancel-case-jobs-08.csv](../../sample/architecture/cancel-case-tasks-08.csv) - results table: [cancel-case-results-08.csv](../../sample/architecture/cancel-case-results-08.csv) diff --git a/docs/en/index.md b/docs/en/index.md index 617a910..2b59129 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -34,7 +34,8 @@ By using it in conjunction with various OSS provided by [@oqtopus-team](https:// - [AWS System Architecture Diagram](./architecture/aws_system_architecture_diagram.md) - [Sequence Diagram](./architecture/sequence_diagram.md) -- [Task State Transition Diagram](./architecture/task_state_transition_diagram.md) +- [Quantum Jobs in Detail](./architecture/quantum_jobs_in_detail.md) +- [Job State Transition Diagram](./architecture/task_state_transition_diagram.md) ### Developer Guidelines diff --git a/mkdocs.yaml b/mkdocs.yaml index ad71aef..2bdb360 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -4,7 +4,8 @@ nav: - Home: index.md - Architecture: - AWS System Architecture Diagram: architecture/aws_system_architecture_diagram.md - - Task State Transition Diagram: architecture/task_state_transition_diagram.md + - Job State Transition Diagram: architecture/task_state_transition_diagram.md + - Quantum Jobs in Detail: architecture/quantum_jobs_in_detail.md - Sequence Diagram: architecture/sequence_diagram.md - Developer Guidelines: - Development Flow: developer_guidelines/index.md