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.

Sign up for GitHub

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

Jump to bottom

docs: Expand the main module and README docs #298

Merged
merged 7 commits into from
Apr 29, 2024
Merged

docs: Expand the main module and README docs #298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d27c2df
Expand the main module and README docs
aborgna-q Feb 29, 2024
040bd85
Merge remote-tracking branch 'origin/main' into docs/more-examples
aborgna-q Apr 19, 2024
9324417
Uncomment mermaid string example
aborgna-q Apr 19, 2024
330d5ac
Remove pypi package line.
aborgna-q Apr 19, 2024
351829f
Small comment on passes
aborgna-q Apr 19, 2024
102ea90
Clarify feature list
aborgna-q Apr 29, 2024
f728db7
Merge branch 'main' into docs/more-examples
aborgna-q Apr 29, 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
50 changes: 47 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,59 @@
# tket2
# tket2: The Hardware Agnostic Quantum Compiler

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel the hardware agnosticism is not new to TKET2 but is inherited from TKET1, and so in that respect we really are "Version 2 of the TKET compiler" (as you remove), or the sequel of, spawn of, etc. (Now Hypertket really is spawn of TKET1 for its multithreaded/distributed capabilities, but there...)

I'd say the big emphasis of TKET2 is on composable rewrites, rather than largely-monolithic "passes". That and the hypertket aspects/characteristics. YMMV though....

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the "version 2" is already implicit from the name, and the previous subtitle didn't explain what this lib is really about.

This is a short one-liner, the actual crate content should be explained below. I'm happy to change the subtitle to something better :)

[![build_status][]](https://github.com/CQCL-DEV/tket2/actions)
![msrv][]
[![codecov][]](https://codecov.io/gh/CQCL/tket2)

Version 2 of the TKET compiler.

[build_status]: https://github.com/CQCL-DEV/hugr/workflows/Continuous%20integration/badge.svg?branch=main
[msrv]: https://img.shields.io/badge/rust-1.75.0%2B-blue.svg
[codecov]: https://img.shields.io/codecov/c/gh/CQCL/tket2?logo=codecov

TKET2 is an open source quantum compiler developed by Quantinuum. Central to
TKET2's design is its hardware agnosticism which allows researchers and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a bit of a shame to repeat these words exactly from the rust crate docs...

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two are read from different places. The crate docs only really appear in docs.rs, whereas the readme is for github/crates.io.

We could make the crate docs more technical at some point, this is just so we have something useful here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I mean, it's a shame not to be able to link between them / copy text (they seem to be aimed at very similar audiences), but I admit I don't see a good way to do that, so ok nvm

quantum software developers to take advantage of its state of the art
compilation for many different quantum architectures.

Circuits are represented using the HUGR IR defined in the
[quantinuum-hugr] crate. TKET2 augments Hugr with
* The [`Circuit`] trait, providing a high-level interface for working with HUGRs representing quantum circuits
* a HUGR extension with quantum operations
* A composable pass system for optimising circuits
* A number of built-in rewrite utilities and passes for common optimisations

This crate is interoperable with [`tket1`] circuits via its
serial encoding.

[quantinuum-hugr]: https://lib.rs/crates/quantinuum-hugr
[`Circuit`]: https://docs.rs/tket2/latest/tket2/trait.Circuit.html
[`tket1`]: https://github.com/CQCL/tket

# Using TKET2

Defining a circuit in TKET2 is currently done by using the low-level [hugr Builder] API, or by loading tket1 circuits from JSON files.

[hugr Builder]: https://docs.rs/quantinuum-hugr/latest/hugr/builder/index.html

```rust
use tket2::{Circuit, Hugr};

// Load a tket1 circuit.
let mut circ: Hugr = tket2::json::load_tk1_json_file("test_files/barenco_tof_5.json").unwrap();

assert_eq!(circ.qubit_count(), 9);
assert_eq!(circ.num_gates(), 170);

// Traverse the circuit and print the gates.
for command in circ.commands() {
println!("{:?}", command.optype());
}

// Render the circuit as a mermaid diagram.
println!("{}", circ.mermaid_string());

// Optimise the circuit.
tket2::passes::apply_greedy_commutation(&mut circ);
```

## Features

- `pyo3`
Expand Down
38 changes: 38 additions & 0 deletions tket2/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,43 @@
//! TKET2's design is its hardware agnosticism which allows researchers and
//! quantum software developers to take advantage of its state of the art
//! compilation for many different quantum architectures.
//!
//! TKET2 circuits are represented using the HUGR IR defined in the
//! [quantinuum-hugr] crate. The [`Circuit`] trait provides a high level
//! interface for working with HUGRs representing quantum circuits, and defines
//! a HUGR extension with quantum operations.
//!
//! This crate includes a number of optimisation passes and rewrite utilities
//! for circuits, as well as interoperability with `tket1` circuits via its
//! serial encoding.
//!
//! Python bindings for TKET2 are available in the `tket2` package on PyPi.
//!
//! # Example
//!
//! ```
//! use tket2::{Circuit, Hugr};
//! use hugr::HugrView;
//!
//! // Load a tket1 circuit.
//! let mut circ: Hugr = tket2::json::load_tk1_json_file("../test_files/barenco_tof_5.json").unwrap();
//!
//! assert_eq!(circ.qubit_count(), 9);
//! assert_eq!(circ.num_gates(), 170);
//!
//! // Traverse the circuit and print the gates.
//! for command in circ.commands() {
//! println!("{:?}", command.optype());
//! }
//!
//! // Render the circuit as a mermaid diagram.
//! println!("{}", circ.mermaid_string());
//!
//! // Optimise the circuit.
//! tket2::passes::apply_greedy_commutation(&mut circ);
//! ```
//!
//! [quantinuum-hugr]: https://lib.rs/crates/quantinuum-hugr

pub mod circuit;
pub mod extension;
Expand All @@ -19,4 +56,5 @@ pub mod portmatching;
mod utils;

pub use circuit::Circuit;
pub use hugr::Hugr;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems sensible

pub use ops::{op_matches, symbolic_constant_op, Pauli, Tk2Op};
Loading