Skip to content

Commit

Permalink
docs: update docs for repeated structure
Browse files Browse the repository at this point in the history
  • Loading branch information
mstechly committed Nov 6, 2024
1 parent 1979a2b commit 6c4871e
Show file tree
Hide file tree
Showing 4 changed files with 135 additions and 8 deletions.
84 changes: 84 additions & 0 deletions docs/examples/qpe.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
description: Program representing QPE using geometric sequence
input:
program:
children:
- name: Hadamards
ports:
- direction: through
name: register
size: N
- name: Evolution
ports:
- direction: input
name: result_in
size: bits_of_precision
- direction: output
name: result_out
size: N
- direction: input
name: psi_in
size: None
- direction: output
name: psi_out
size: None
children:
- name: U
ports:
- direction: through
name: result
size: bits_of_precision
- direction: through
name: psi
size: N
resources:
- name: T_gates
type: additive
value: N**2
connections:
- source: result_in
target: U.result
- source: U.result
target: result_out
- source: psi_in
target: U.psi
- source: U.psi
target: psi_out
repetition:
count: bits_of_precision
sequence:
type: geometric
ratio: 1
- name: Inverse_QFT
ports:
- direction: through
name: register
size: N
connections:
- source: result_in
target: Hadamards.register
- source: Hadamards.register
target: Evolution.result_in
- source: Evolution.result_out
target: Inverse_QFT.register
- source: Inverse_QFT.register
target: result_out
- source: psi_in
target: Evolution.psi_in
- source: Evolution.psi_out
target: psi_out
name: QPE
ports:
- direction: input
name: result_in
size: ceil(log2(1/eps))
- direction: output
name: result_out
size: ceil(log2(1/eps))
- direction: input
name: psi_in
size: M
- direction: output
name: psi_out
size: M

version: v1
42 changes: 42 additions & 0 deletions docs/format.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,3 +153,45 @@ beginning looks as follows:
```yaml
--8<-- "basic_program_concise.yaml"
```


### Repetitions

On top of the basic fileds listed above, one can also write a QREF routine which contains repetitions.

This can be added with `repetition` field:

```yaml
repetition:
count: ceil(1/eps)
sequence:
type: constant
multiplier: 1
```
`repetition` consists of two parts:

- `count` – defines how many times the child of the this routine should be repeated.
- `sequence` – defines how the costs for the repetition will be aggregated. Each `sequence` has a field `type` which defines the type of the sequence. Depending on the type there are extra fields, summarized in the table below.


There are 5 different sequences that one can currently use in QREF:


| <div style="width:7em">Sequence type</div> | <div style="width:8em">Additional fields</div> | Description | Example |
|-------|-------|-------|-------|
| `constant`| `multiplier` | In each iteration child is repeated `multiplier` number of times. | Trotterization |
| `arithmetic`| `difference`, `initial_term` | Iteration starts from `initial_term` repetitions of a child and then we increase the of repetitions by `difference` in every iteration. | QFT |
| `geometric` | `ratio` | In each iteration number of repetitions is multiplied by `ratio`, starts for 1 repetition in the first iteartion. | QPE |
| `closed_form` | `sum`, `prod`, `num_terms_symbol` | This can be used for cases, where we know the closed-form expression for the total cost of the routine given the number of repetitions is defined `num_terms_symbol`. `sum` is an expression for additive resources and `prod` is for multiplicative. | Any |
| `custom` | `term_expression`, `iterator_symbol` | This can be used in case where we don't know the formula for closed form, but we do know the formula for each term, which is defined using `term_expression`, and we use `iterator_symbol` to denote the iterator. | Any |


This representation abstracts out certain implementation details. Consider implementation of QPE using geometric sequence below. The child `U` of routine `Evolution` has two ports: `result` and `psi`, the with sizes `bits_of_precision` and `N`. Even though in the executable implementation each next controlled `U^2^i` only acts on one control qubit from the `result` register, there's currently no way of expressing it in QREF.

=== "YAML"

```yaml
--8<-- "qpe.yaml"
```

7 changes: 4 additions & 3 deletions src/qref/schema_v1.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
BaseModel,
BeforeValidator,
ConfigDict,
Field,
StringConstraints,
model_validator,
)
Expand Down Expand Up @@ -230,10 +231,10 @@ class RoutineV1(BaseModel):
"""

name: _Name
children: Annotated[NamedList[RoutineV1], _name_sorter] = NamedList["RoutineV1"]()
children: Annotated[NamedList[RoutineV1], _name_sorter] = Field(default_factory=NamedList)
type: str | None = None
ports: Annotated[NamedList[PortV1], _name_sorter] = NamedList[PortV1]()
resources: Annotated[NamedList[ResourceV1], _name_sorter] = NamedList[ResourceV1]()
ports: Annotated[NamedList[PortV1], _name_sorter] = Field(default_factory=NamedList)
resources: Annotated[NamedList[ResourceV1], _name_sorter] = Field(default_factory=NamedList)
connections: Annotated[list[Annotated[ConnectionV1, _connection_parser]], _source_sorter] = []
input_params: list[_OptionallyMultiNamespacedName] = []
local_variables: dict[str, str] = {}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,22 @@ input:
ports:
- direction: input
name: result_in
size: N
size: bits_of_precision
- direction: output
name: result_out
size: N
- direction: input
name: psi_in
size: M
size: None
- direction: output
name: psi_out
size: M
size: None
children:
- name: U
ports:
- direction: through
name: result
size: N
size: bits_of_precision
- direction: through
name: psi
size: N
Expand All @@ -44,7 +44,7 @@ input:
- source: U.psi
target: psi_out
repetition:
count: N
count: bits_of_precision
sequence:
type: geometric
ratio: 1
Expand Down

0 comments on commit 6c4871e

Please sign in to comment.