Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Add contents to the docs #21

Merged
merged 28 commits into from
Dec 9, 2024
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
570c8a0
add some examples of possible IR compilations
kaosmicadei Oct 11, 2024
031ee29
fix examples
kaosmicadei Oct 11, 2024
a84e07a
fix example
kaosmicadei Oct 11, 2024
6158bbe
fix last example
kaosmicadei Oct 11, 2024
5197c31
fix last example
kaosmicadei Oct 11, 2024
7302c7b
add IR structure and purpose documentation
kaosmicadei Oct 14, 2024
0bfc4c7
Fix wrong repo mentioned in README License
pimvenderbosch Nov 29, 2024
714348b
Add titles to API pages
pimvenderbosch Nov 29, 2024
3f99b9a
Update docstrings in irbuilder.py
pimvenderbosch Nov 29, 2024
ccb3d74
Fix minor spelling mistake
pimvenderbosch Nov 29, 2024
d5c59f3
Remove warning from IR Builder page
pimvenderbosch Nov 29, 2024
6364676
Update docstrings in types.py
pimvenderbosch Nov 29, 2024
a8666ba
Update docstrings in factory.py
pimvenderbosch Nov 29, 2024
1d631d9
Fix spelling mistake in returns header
pimvenderbosch Nov 29, 2024
bdf2766
Fix syntax issue in Support docstring
pimvenderbosch Nov 29, 2024
ce428ca
Update docstrings in factory_tools.py
pimvenderbosch Nov 29, 2024
5f38164
Update docstrings in irast.py
pimvenderbosch Dec 2, 2024
b405d91
Merge branch 'km/docs' into pv/docs-contents
pimvenderbosch Dec 2, 2024
2a51d5b
Fix reference to qadence 2 instead of 1
pimvenderbosch Dec 3, 2024
34d2cb5
Fix typo
pimvenderbosch Dec 3, 2024
ba8f579
Split up in multiple files
pimvenderbosch Dec 3, 2024
6c95fbc
Merge remote-tracking branch 'refs/remotes/origin/pv/docs-contents' i…
pimvenderbosch Dec 3, 2024
6b4e88f
Add subpages to content in mkdocs config
pimvenderbosch Dec 3, 2024
bcd8e84
Make figure number bold
pimvenderbosch Dec 6, 2024
d3322ab
Add API reference index page contents
pimvenderbosch Dec 6, 2024
1dfc561
Improve challenges based on @doosmk input
pimvenderbosch Dec 6, 2024
923604d
Fix typos in challenges
pimvenderbosch Dec 6, 2024
dcae4fa
Move tutorial files around
pimvenderbosch Dec 9, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,4 +56,4 @@ Before making a contribution, please review our [code of conduct](docs/getting_s

## License

Qadence Expressions is a free and open source software package, released under the Apache License, Version 2.0.
Qadence 2 IR is a free and open source software package, released under the Apache License, Version 2.0.
3 changes: 1 addition & 2 deletions docs/api/factory.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
!!! warning
This page is under construction.
# Factory

::: qadence2_ir.factory
4 changes: 1 addition & 3 deletions docs/api/factory_tools.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
!!! warning
This page is under construction.

# Factory Tools

::: qadence2_ir.factory_tools
3 changes: 1 addition & 2 deletions docs/api/irast.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
!!! warning
This page is under construction.
# IRAST

::: qadence2_ir.irast
3 changes: 1 addition & 2 deletions docs/api/irbuilder.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
!!! warning
This page is under construction.
# IR Builder

::: qadence2_ir.irbuilder
3 changes: 1 addition & 2 deletions docs/api/types.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
!!! warning
This page is under construction.
# Types

::: qadence2_ir.types
17 changes: 12 additions & 5 deletions qadence2_ir/factory.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
"""This module defines a factory method that creates a compiler function based on an `IRBuilder`.

The compiler function, that can be generated using the factory, should be used to to compile a
certain type of input, based on the front-end that is being used, to IR code. This is the first
step of compilation, which is followed by a compilation from IR to the targeted backend.
"""

from __future__ import annotations

from typing import Callable
Expand All @@ -9,17 +16,17 @@


def ir_compiler_factory(builder: IRBuilder[InputType]) -> Callable[[InputType], Model]:
"""Use an IRBuilder[InputType] to create an IR compiler function that converts an input of type
`InputType` and returns a Model.
"""Constructs an IR compiler function for a specific input type by using an `IRBuilder`.

The IR compiler must be named 'compile_to_model' by convention to ensure accessibility to other
engines in the framework.
The factory function uses an `IRBuilder[InputType]` to create an IR compiler function that
converts an input of type `InputType` and returns a Model. The IR compiler must be named
'compile_to_model' by convention to ensure accessibility to other engines in the framework.

Args:
builder: A concrete implementation of the generic class `IRBuilder` for a particular
`InputType`.

Return:
Returns:
A function that compiles an `InputType` object to the Qadence-IR (`Model`).
"""

Expand Down
56 changes: 30 additions & 26 deletions qadence2_ir/factory_tools.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
"""Tools to process an `AST` as used by the compiler factory in `qadence2-ir.factory`.

This module defines a collection of functions that manipulate an `AST`. Using these AST manipulation
tools the factory function in `qadence2-ir.factory` can build the instruction list from a given AST.
"""

from __future__ import annotations

from functools import reduce
Expand All @@ -8,23 +14,23 @@


def filter_ast(predicate: Callable[[AST], bool], ast: AST) -> Iterable[AST]:
"""Filter the elements of the AST according to the `predicate` function.
"""Filters the elements of the AST according to the `predicate` function.

Args:
predicate: A function to check if a specific property is present in the `ast`.
ast: A parsed tree containing the sequence of instructions to be added to the `Model`.
predicate: A function that checks if a specific property is present in the `ast`.
ast: A parsed AST containing the sequence of instructions to be added to the `Model`.

Return:
Returns:
An iterable and flattened version of the AST that contains the selected elements.

Example:
```
>>> ast = AST.binar_op("/", AST.numeric(2), AST.callable("fn", AST.numeric(3)))

```python
>>> ast = AST.div(AST.numeric(2), AST.callable("fn", AST.numeric(3)))
>>> list(filter_ast(lambda x: x.is_numeric, ast))
[AST.numeric(2), AST.numeric(3)]
````
```
"""
# TODO edit example: binar_op is not available in AST

if predicate(ast):
yield ast
Expand All @@ -37,18 +43,18 @@ def filter_ast(predicate: Callable[[AST], bool], ast: AST) -> Iterable[AST]:


def flatten_ast(ast: AST) -> Iterable[AST]:
"""Returns an interable and flattened version of the AST.
"""Returns an iterable and flattened version of the AST.

Args:
ast: A parsed tree containing the sequence of instructions to be added to the `Model`.

Return:
Returns:
An iterable and flattened version of the AST. The arguments of operations/functions will
appear before the operation/function.

Example:
```
>>> ast = AST.binar_op("/", AST.numeric(2), AST.callable("fn", AST.numeric(3)))
```python
>>> ast = AST.div(AST.numeric(2), AST.callable("fn", AST.numeric(3)))
>>> list(flatten_ast(ast))
[
AST.numeric(2),
Expand All @@ -74,7 +80,7 @@ def extract_inputs_variables(ast: AST) -> dict[str, Alloc]:
Args:
ast: A parsed tree containing the sequence of instructions to be added to the `Model`.

Return:
Returns:
A dictionary with the variables names as keys and their respective allocation instructions
as values.
"""
Expand All @@ -83,11 +89,11 @@ def extract_inputs_variables(ast: AST) -> dict[str, Alloc]:


def to_alloc(inputs: dict[str, Alloc], ast: AST) -> dict[str, Alloc]:
"""If the `ast` is an input variable, add it to the inputs to be allocated
if not present yet.
"""If the `ast` is an input variable, add it to the inputs to be allocated if not present yet.

Args:
inputs: A dictionary containing pairs of variables and their allocation instructions.
inputs: A dictionary containing pairs of variables and their allocation instructions, which
are already allocated.
ast: A parsed tree containing the sequence of instructions to be added to the `Model`.

Return
Expand All @@ -107,13 +113,12 @@ def to_alloc(inputs: dict[str, Alloc], ast: AST) -> dict[str, Alloc]:


def build_instructions(ast: AST) -> list[QuInstruct | Assign]:
"""Converts a sequence of instructions in the AST form into a list of Model
instructions.
"""Converts an AST into a list of `Model` instructions.

Args:
ast: A parsed tree containing the sequence of instructions to be added to the `Model`.

Return:
Returns:
A list of quantum operations and temporary static single-assigned variables. Temporary
variables store the outcomes of classical operations and are used as arguments for
parametric quantum operations.
Expand All @@ -131,12 +136,11 @@ def to_instruct(
memoise: dict[AST, Load],
single_assign_index: int,
) -> tuple[list[QuInstruct | Assign], dict[AST, Load], int]:
"""Add the `ast` to the `instructions_list` if `ast` is a classical function
or a quantum instruction.
"""Adds the `ast` to the `instructions_list` if it is a `Call` or `QuInstruct`.

When the `ast` is a classical function, it uses the `single_assign_index` to
assign the call to a temporary variable using memoisation to avoid duplicated
assignments.
When the `ast` is a classical function, it uses the `single_assign_index` to assign the call to
a temporary variable using memoisation to avoid duplicated assignments. If the `ast` is a
quantum instruction, the instruction will be added to the instruction list.

Args:
ast: A parsed tree containing the sequence of instructions to be added to the `Model`.
Expand All @@ -147,8 +151,8 @@ def to_instruct(
single_assign_index: The index to be used by the next temporary variable assignement.
Tempmorary variables are labled from "%0" to "%n".

Return:
A tuple consists of an updated list of instructions and assignments, a dictionary of pairs
Returns:
A tuple consisting of an updated list of instructions and assignments, a dictionary of pairs
of AST objects and temporary variables, and the updated index for the next assignment.
"""

Expand Down
Loading