diff --git a/README.md b/README.md index e885114..85c4605 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,30 @@ -# QART -Quantum Algorithms Represented Topologically (QART) is an open format for representing +# QREF +Quantum Resource Estimation Format (QREF) is an open format for representing quantum algorithms, optimized for usage in quantum resource estimation (QRE). -QART comprises: +QREF comprises: - Definition of data format, formalized as a JSON schema. -- A Python library for validation of quantum programs written in QART format using [Pydantic](https://docs.pydantic.dev/). -- Rudimentary visualization tool `qart-render`. +- A Python library for validation of quantum programs written in QREF format using [Pydantic](https://docs.pydantic.dev/). +- Rudimentary visualization tool `qref-render`. ## Installation -Using QART data format does not require installation - you can easily write quantum +Using QREF data format does not require installation - you can easily write quantum programs in YAML or JSON. -To install QART Python package, clone this repository and install it as usual with `pip`: +To install QREF Python package, clone this repository and install it as usual with `pip`: ```bash -# Clone QART repo (you can use HTTP link as well) -git clone git@github.com:PsiQ/qart.git -cd qart +# Clone QREF repo (you can use HTTP link as well) +git clone git@github.com:PsiQ/qref.git +cd qref pip install . ``` -## QART format +## QREF format -QART format represents quantum programs as a hierarchical directed acyclic graphs (DAGs). +QREF format represents quantum programs as a hierarchical directed acyclic graphs (DAGs). That's a mouthful, so let us unpack what it means: - *hierarchical*: each node can contain subgraphs, i.e. routines can be nested inside @@ -36,7 +36,7 @@ Consider the following hierarchical DAG of a hypothetical quantum program: ![program example](example_routine.svg) -It can be succinctly written in QART format as: +It can be succinctly written in QREF format as: ```yaml @@ -103,18 +103,18 @@ program: ``` -For full description of QART format, check our [docs](https://example.com). +For full description of QREF format, check our [docs](https://example.com). -## Using QART package +## Using QREF package -### Using JSON schema for validating data in QART format +### Using JSON schema for validating data in QREF format -JSON schema for QART format can be obtained by calling `generate_program_schema` function. +JSON schema for QREF format can be obtained by calling `generate_program_schema` function. Such schema can be then used for validating user's input, e.g. using `jsonschema` package: ```python from jsonschema import validate -from qart import generate_program_schema +from qref import generate_program_schema # Hypothetical function loading your data as native Python dictionary. data = load_some_program() @@ -126,12 +126,12 @@ validate(schema, data) ### Validation using Pydantic models -If you are familiar with Pydantic, you might find it easier to work with QART Pydantic +If you are familiar with Pydantic, you might find it easier to work with QREF Pydantic models instead of interacting with JSON schema directly. In the example below, we create -an instance of `SchemaV1` model from validated data stored in QART format: +an instance of `SchemaV1` model from validated data stored in QREF format: ```python -from qart import SchemaV1 +from qref import SchemaV1 data = load_some_program() diff --git a/docs/development.md b/docs/development.md index 78a9880..89b9781 100644 --- a/docs/development.md +++ b/docs/development.md @@ -2,7 +2,7 @@ ## Setting up development environment -QART uses [Poetry](https://python-poetry.org/) for managing dependencies. +QREF uses [Poetry](https://python-poetry.org/) for managing dependencies. Therefore, we recommend you use Poetry to setup your environment. However, if you insist on not using Poetry, the more traditional way of using editable install with `pip` is still avaiable. @@ -31,7 +31,7 @@ pip install -e . !!! Warning - If you are planning to add/modify dependencies of QART, we + If you are planning to add/modify dependencies of QREF, we highly recommend you use Poetry instead of pip editable install. Without Poetry, you will need to edit dependencies manually, which is very error-prone. diff --git a/docs/format.md b/docs/format.md index bf222a7..b0d11f6 100644 --- a/docs/format.md +++ b/docs/format.md @@ -1,10 +1,10 @@ # Data format ## Introduction -QART format is a domain-specific language (DSL) for describing quantum algorithms +QREF format is a domain-specific language (DSL) for describing quantum algorithms built on top of JSON for the purpose of resource estimation. -In QART, the algorithms are described as programs comprising hierarchical, directed +In QREF, the algorithms are described as programs comprising hierarchical, directed acyclic graph (henceforth hierarchical DAGs) of subroutines. Let's break down what this means: @@ -14,7 +14,7 @@ what this means: - *Acyclic* means that traversing the graph along its edges (respecting their direction) will never lead to visiting the same node twice. -Besides specifying the connectivity between routines in the algorithms, the QART format +Besides specifying the connectivity between routines in the algorithms, the QREF format also specifies how to store information relevant to resource estimation, such as known and unknown resources, parameters that might affect them and how the parameters propagate in the algorithm's graph. @@ -23,8 +23,8 @@ Before describing the format in detail, let us first exemplify its usage on a si ## Basic example -In QART, the quantum programs are represented as graphs. If you are not used to -representing computations as graph, don't worry! Before describing QART format, +In QREF, the quantum programs are represented as graphs. If you are not used to +representing computations as graph, don't worry! Before describing QREF format, we'll demostrate how a simple circuit can be represented as a graph. Consider a hypothetical quantum program as depicted in the following circuit. @@ -48,8 +48,8 @@ As we can see, the graph contains both subroutines form the original circuit, and an artificially introduced `merge` operation used to combine outputs from the subprograms into one final outputs. -Now that we have our graph, let's see how it can be represented in QART format. -As already mentioned, QART format is built on top of JSON, so we can write QART +Now that we have our graph, let's see how it can be represented in QREF format. +As already mentioned, QREF format is built on top of JSON, so we can write QREF files in either JSON or YAML. For our examples, those might look as follows: === "YAML" @@ -84,10 +84,10 @@ Let us first take a look at ports, like the first input port of our program: {direction: input, name: in_0, size: 1} ``` -Ports, like most other components in QART, have names, which should be distinct +Ports, like most other components in QREF, have names, which should be distinct among all ports of any given program (or subroutine). Each port also has direction, which can be either `input` or `output`. Finally, each port has size. -In our simple scenario, all sizes are positive integers. However, QART +In our simple scenario, all sizes are positive integers. However, QREF is not limited to them, and size of a port can be either: - A positive integer. diff --git a/docs/index.md b/docs/index.md index 6478741..3863169 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ -# QART +# QREF -Quantum Algorithms Represented Topologically (QART) is an open format for representing +Quantum Resource Estimation Format (QREF) is an open format for representing quantum algorithms, optimized for usage in quantum resource estimation (QRE).
@@ -9,7 +9,7 @@ quantum algorithms, optimized for usage in quantum resource estimation (QRE). --- - QART's data format is built on top of JSON, which makes it easy to + QREF's data format is built on top of JSON, which makes it easy to write and read. [:octicons-arrow-right-24: Learn more](format) @@ -18,14 +18,14 @@ quantum algorithms, optimized for usage in quantum resource estimation (QRE). --- - QART's JSON schema can be used for data validation in any language. + QREF's JSON schema can be used for data validation in any language. - :material-language-python:{ .lg .middle } __Python library__ --- - QART's Python package provides programmatic access - to QART's JSON schema and ready-to-use Pydantic models. + QREF's Python package provides programmatic access + to QREF's JSON schema and ready-to-use Pydantic models. [:octicons-arrow-right-24: See user guide](library/userguide) @@ -34,8 +34,8 @@ quantum algorithms, optimized for usage in quantum resource estimation (QRE). --- - QART is licensed under the MIT license and lives on GitHub. + QREF is licensed under the MIT license and lives on GitHub. - [:octicons-arrow-right-24: See QART on GH](https://github.com/psiq/hqar) + [:octicons-arrow-right-24: See QREF on GH](https://github.com/psiq/hqar)
diff --git a/docs/library/reference/qart.experimental.rendering.md b/docs/library/reference/qart.experimental.rendering.md index ede8019..c7b324d 100644 --- a/docs/library/reference/qart.experimental.rendering.md +++ b/docs/library/reference/qart.experimental.rendering.md @@ -1,3 +1,3 @@ -::: qart.experimental.rendering +::: qref.experimental.rendering handler: python diff --git a/docs/library/reference/qart.md b/docs/library/reference/qart.md index 0f15c61..2eda782 100644 --- a/docs/library/reference/qart.md +++ b/docs/library/reference/qart.md @@ -1,4 +1,4 @@ -::: qart +::: qref handler: python options: members: diff --git a/docs/library/userguide.md b/docs/library/userguide.md index 5fc3a4c..7e9f1ea 100644 --- a/docs/library/userguide.md +++ b/docs/library/userguide.md @@ -2,12 +2,12 @@ ## Installation -To install QART Python package, clone QARt repository and install it as usual with `pip`: +To install QREF Python package, clone QREF repository and install it as usual with `pip`: ```bash -# Clone QART repo (you can use HTTP link as well) -git clone git@github.com:PsiQ/qart.git -cd qart +# Clone QREF repo (you can use HTTP link as well) +git clone git@github.com:PsiQ/qref.git +cd qref pip install . ``` @@ -17,16 +17,16 @@ installation. ## Usage -### Using JSON schema for validating data in QART format +### Using JSON schema for validating data in QREF format -JSON schema for QART format can be obtained by calling -[`generate_program_schema`][qart.generate_program_schema] function. +JSON schema for QREF format can be obtained by calling +[`generate_program_schema`][qref.generate_program_schema] function. Such schema can be then used for validating user's input, e.g. using [`jsonschema`](https://pypi.org/project/jsonschema/) package: ```python from jsonschema import validate -from qart import generate_program_schema +from qref import generate_program_schema # Hypothetical function loading your data as native Python dictionary. data = load_some_program() @@ -39,12 +39,12 @@ validate(schema, data) ### Validation using Pydantic models If you are familiar with [Pydantic](https://docs.pydantic.dev/latest/), you might find -it easier to work with QART Pydantic models instead of interacting with JSON schema directly. -In the example below, we create an instance of [`SchemaV1`][qart.SchemaV1] model from -validated data stored in QART format: +it easier to work with QREF Pydantic models instead of interacting with JSON schema directly. +In the example below, we create an instance of [`SchemaV1`][qref.SchemaV1] model from +validated data stored in QREF format: ```python -from qart import SchemaV1 +from qref import SchemaV1 data = load_some_program() @@ -52,7 +52,7 @@ data = load_some_program() program = SchemaV1.model_validate(data) ``` -### Rendering QART files using `qart-render` (experimental) +### Rendering QREF files using `qref-render` (experimental) !!! Warning @@ -60,19 +60,19 @@ program = SchemaV1.model_validate(data) incorrect results. -QART comes with a CLI tool for rendering hierarchical graphs of quantum +QREF comes with a CLI tool for rendering hierarchical graphs of quantum algorithms. To render an algorithm stored in a file named `my_program.yaml` into a file `my_program_graph.svg` run: ```bash -qart-render my_program.yaml my_program_graph.svg +qref-render my_program.yaml my_program_graph.svg ``` -The `qart-render` tool supports `yaml` and `json` input formats, and all +The `qref-render` tool supports `yaml` and `json` input formats, and all output formats supported by [graphviz](https://graphviz.org/). -If, instead of using CLI, you'd like to invoke QART's rendering capabilities -from Python script, you can look at [qart.experimental.rendering][qart.experimental.rendering] -module which exposes experimental API for performing the same task as `qart-render`. +If, instead of using CLI, you'd like to invoke QREF's rendering capabilities +from Python script, you can look at [qref.experimental.rendering][qref.experimental.rendering] +module which exposes experimental API for performing the same task as `qref-render`. diff --git a/mkdocs.yml b/mkdocs.yml index 5b21403..f84569f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,16 +1,16 @@ # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json -site_name: QART -site_description: Quantum Algorithms Represented Topologically +site_name: QREF +site_description: Quantum Resource Estimation Format site_author: PsiQuantum Corp. copyright: Copyright © 2023-2024 PsiQuantum Corp. -repo_url: https://github.com/psiq/qart +repo_url: https://github.com/psiq/qref nav: - format.md - Python Library: - - library/userguide.md - - API Reference: - - qart: library/reference/qart.md - - qart.experimental.rendering: library/reference/qart.experimental.rendering.md + - library/userguide.md + - API Reference: + - qref: library/reference/qref.md + - qref.experimental.rendering: library/reference/qref.experimental.rendering.md - development.md theme: name: material diff --git a/pyproject.toml b/pyproject.toml index 81c2b97..0bb3377 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [tool.poetry] -name = "qart" +name = "qref" version = "0.1.0" -description = "Quantum Algorithms, Represented Topologically" +description = "Quantum Resource Estimation Format" authors = ["PsiQuantum"] license = "MIT" readme = "README.md" @@ -30,7 +30,7 @@ mkdocs-open-in-new-tab = "^1.0.3" mkdocstrings = {version = "^0.24.2", extras = ["python"]} [tool.poetry.scripts] -qart-render = "qart.experimental.rendering:render_entry_point" +qref-render = "qref.experimental.rendering:render_entry_point" [build-system] diff --git a/src/qart/__init__.py b/src/qart/__init__.py index 327b28b..7de7bbf 100644 --- a/src/qart/__init__.py +++ b/src/qart/__init__.py @@ -1,4 +1,4 @@ -"""Public API of QART.""" +"""Public API of QREF.""" from typing import Any diff --git a/src/qart/experimental/rendering.py b/src/qart/experimental/rendering.py index 9ea371e..132d4f1 100644 --- a/src/qart/experimental/rendering.py +++ b/src/qart/experimental/rendering.py @@ -1,4 +1,4 @@ -"""Experimental visualization capabilities for QART. +"""Experimental visualization capabilities for QREF. Currently, the visualizations are done with graphviz, which does not suport hierarchical structures. Therefore, we have to use a somewhat hacky representation diff --git a/tests/conftest.py b/tests/conftest.py index ea14d27..3443f36 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,11 +1,11 @@ -"""Common fixtures for QART tests.""" +"""Common fixtures for QREF tests.""" from pathlib import Path import pytest import yaml -VALID_PROGRAMS_ROOT_PATH = Path(__file__).parent / "qart/data/valid_programs" +VALID_PROGRAMS_ROOT_PATH = Path(__file__).parent / "qref/data/valid_programs" def _load_valid_examples(): diff --git a/tests/qart/experimental/test_rendering.py b/tests/qart/experimental/test_rendering.py index f576698..44c33c4 100644 --- a/tests/qart/experimental/test_rendering.py +++ b/tests/qart/experimental/test_rendering.py @@ -1,9 +1,9 @@ -"""Sanity checks for QART rendering capabilities.""" +"""Sanity checks for QREF rendering capabilities.""" import json from subprocess import Popen -from qart.experimental.rendering import to_graphviz +from qref.experimental.rendering import to_graphviz def test_example_valid_programs_can_converted_to_graphviz(valid_program): @@ -17,7 +17,7 @@ def test_example_valid_programs_can_be_rendered_from_cli(valid_program, tmp_path with open(input_path, "wt") as f: json.dump(valid_program, f) - process = Popen(["qart-render", input_path, output_path]) + process = Popen(["qref-render", input_path, output_path]) process.wait() assert process.returncode == 0 diff --git a/tests/qart/test_schema_validation.py b/tests/qart/test_schema_validation.py index b3f2883..7738c16 100644 --- a/tests/qart/test_schema_validation.py +++ b/tests/qart/test_schema_validation.py @@ -7,7 +7,7 @@ import yaml # type: ignore[import-untyped] from jsonschema import ValidationError, validate -from qart import SchemaV1, generate_program_schema +from qref import SchemaV1, generate_program_schema def validate_with_v1(data):