Skip to content

Commit

Permalink
[Docs] Update OpenAPI specification for jobs (#64)
Browse files Browse the repository at this point in the history
  • Loading branch information
@katsujukou
katsujukou authored Dec 26, 2024
1 parent 90b5357 commit 28458bb
Show file tree
Hide file tree
Showing 4 changed files with 111 additions and 78 deletions.
38 changes: 38 additions & 0 deletions docs/en/architecture/quantum_jobs_in_detail.md
View file
Original file line number Diff line number Diff line change
@@ -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
145 changes: 69 additions & 76 deletions docs/en/architecture/sequence_diagram.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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": <task ID-1> }
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": <job ID-1> }
User->>Cloud: GET /tasks/<task ID-1>/status
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "submitted" }
User->>Cloud: GET /jobs/<job ID-1>/status
Cloud-->>User: HTTP 200 OK { "job_id": <job ID-1>, "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<br>and sends requests to update their statuses to running.
Note over Provider: Provider starts execution of the jobs and sends <br/> requests to update their statuses to `running`.
Provider->>Cloud: PATCH /jobs/<job ID-1> { "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/<task ID-N> { "status": "running" }
Note over Cloud: The task status is updated to running.
Provider->>Cloud: PATCH /jobs/<job ID-N> { "status": "running" }
Note over Cloud: The job status is updated to `running`.
Cloud-->>Provider: HTTP 200 OK
User->>Cloud: GET /tasks/<task ID-1>/status
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "running" }
Note over Provider: The execution of the task <task ID-1> is successfully completed.
Provider->>Cloud: POST /results { "taskId": <task ID-1>, "status": "succeeded", result: ... }
User->>Cloud: GET /jobs/<job ID-1>/status
Cloud-->>User: HTTP 200 OK { "job_id": <job ID-1>, "status": "running" }
Note over Provider: The execution of the job <job ID-1> is successfully completed.
Provider->>Cloud: PATCH /jobs/<job ID-N>/job_info { "result": ... }
Note over Cloud: The received result of the task is inserted to the DB,<br> 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<br /> in the database, and the job status is updated to `success`.
Cloud-->>Provider: HTTP 200 OK
User->>Cloud: GET /jobs/<job ID-1>/status
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "succeeded" }
User->>Cloud: GET /jobs/<job ID-1>
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "succeeded", "result": ... }
Cloud-->>User: HTTP 200 OK <br>{ "job_id": <job ID-1>, "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)
Expand All @@ -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
Expand All @@ -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": <task ID-1> }
User->>Cloud: POST /jobs { "job_info": "{ \"code\": \"OPENQASM ...\", ... }", ... }
User->>Cloud: GET /tasks/<task ID-1>/status
Cloud-->>User: HTTP 200 OK { "jobId": <job ID-1>, "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": <job ID-1> }
User->>Cloud: GET /jobs/<job ID-1>/status
Cloud-->>User: HTTP 200 OK { "job_id": <job ID-1>, "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<br>and sends requests to update their statuses to running.
Provider->>Cloud: PATCH /tasks/<task ID-N> { "status": "running" }
Note over Cloud: The task status is updated to running.
Note over Provider: Provider starts execution of the jobs and sends <br/> requests to update their statuses to `running`.
Provider->>Cloud: PATCH /jobs/<job ID-1> { "status": "running" }
Note over Cloud: The job status is updated to `running`.
Cloud-->>Provider: HTTP 200 OK
Provider->>Cloud: PATCH /tasks/<task ID-N> { "status": "running" }
Note over Cloud: The task status is updated to running.
Provider->>Cloud: PATCH /jobs/<job ID-N> { "status": "running" }
Note over Cloud: The job status is updated to `running`.
Cloud-->>Provider: HTTP 200 OK
User->>Cloud: GET /tasks/<task ID-1>/status
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "running" }
User->>Cloud: GET /jobs/<job ID-1>/status
Cloud-->>User: HTTP 200 OK { "job_id": <job ID-1>, "status": "running" }
rect rgb(255, 240, 240)
Note over Provider: The execution of the task <task ID-1> is failed.
Provider->>Cloud: POST /results { "taskId": <task ID-1>, "status": "failed", "reason": ... }
Note over Cloud: The received result of the task is inserted to the DB,<br> then the task status is changed to failed (via a DB trigger).
Note over Provider: The execution of the task <job ID-1> 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 <br />field in database, and the job status is set to `failed`.
Cloud-->>Provider: HTTP 200 OK
User->>Cloud: GET /tasks/<task ID-1>/status
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "failed" }
User->>Cloud: GET /results/<task ID-1>
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "failed", "reason": ...}
User->>Cloud: GET /jobs/<job ID-1>
Cloud-->>User: HTTP 200 OK <br />{ "job_id": <job ID-1>, "status": "failed", "job_info": "{ \"reason\": \"The reason of failure\", ... }" }
end
```

Expand Down Expand Up @@ -155,44 +151,41 @@ sequenceDiagram
participant Cloud as Cloud (Backend)
participant Provider as Provider (Device ID is 'SVSim')
User->>Cloud: POST /jobs/<JOB ID-1>/cancel
Note right of User: User sends a cancel requests for the task <task ID-1>.
Note over Cloud: The task status is updated to cancelled
User->>Cloud: POST /jobs/<Job ID-1>/cancel
Note right of User: User sends a cancel requests for the job <job ID-1>.
Note over Cloud: The job status is updated to `cancelled`
Cloud-->>User: HTTP 200 OK
User->>Cloud: GET /tasks/<task ID-1>/status
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "cancelled" }
User->>Cloud: GET /jobs/<job ID-1>/status
Cloud-->>User: HTTP 200 OK { "job_id": <job ID-1>, "status": "cancelled" }
Note over Provider: Provider tries to cancel the executions of the tasks.
Note over Provider: The execution of the task <task ID-1> is successfully cancelled.
Provider->>Cloud: POST /results { "taskId": <task ID-1>, "status": "cancelled", "reason": ... }
Note over Provider: The execution of the job <Job ID-1> is successfully cancelled.
Provider->>Cloud: PATCH /jobs/<JOB ID-1>/job_info { "job_id": <Job ID-1>, "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/<task ID-1>/status
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "cancelled" }
User->>Cloud: GET /results/<task ID-1>
Cloud-->>User: HTTP 200 OK { "taskId": <task ID-1>, "status": "cancelled", "reason": ... }
User->>Cloud: GET /jobs/<Job ID-1>/status
Cloud-->>User: HTTP 200 OK { "job_id": <Job ID-1>, "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)

3 changes: 2 additions & 1 deletion docs/en/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 2 additions & 1 deletion mkdocs.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 28458bb

Please sign in to comment.