refactor: Add a hugr-core crate

.github/CODEOWNERS

@@ -8,6 +8,4 @@
 
 # The release PRs that trigger publication to crates.io or PyPI always modify the changelog.
 # We require those PRs to be approved by someone with release permissions.
-hugr/CHANGELOG.md @aborgna-q @cqc-alec @ss2165
-hugr-passes/CHANGELOG.md @aborgna-q @cqc-alec @ss2165
-hugr-py/CHANGELOG.md @aborgna-q @cqc-alec @ss2165
+**/CHANGELOG.md @aborgna-q @cqc-alec @ss2165

.github/change-filters.yml

@@ -3,7 +3,7 @@
 
 rust:
   - "hugr/**"
-  - "hugr-passes/**"
+  - "hugr-*/**"
   - "Cargo.toml"
   - "specification/schema/**"
 

Cargo.toml

@@ -3,8 +3,9 @@ lto = "thin"
 
 [workspace]
 resolver = "2"
-members = ["hugr", "hugr-passes"]
-default-members = ["hugr", "hugr-passes"]
+members = ["hugr", "hugr-core", "hugr-passes"]
+default-members = ["hugr", "hugr-core", "hugr-passes"]
+default-run = "hugr"
 
 [workspace.package]
 rust-version = "1.75"

hugr-core/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

hugr-core/Cargo.toml

@@ -0,0 +1,66 @@
+[package]
+name = "hugr-core"
+version = "0.0.0"
+edition = { workspace = true }
+rust-version = { workspace = true }
+
+license = { workspace = true }
+readme = "README.md"
+documentation = "https://docs.rs/hugr/"
+homepage = { workspace = true }
+repository = { workspace = true }
+description = "Quantinuum's Hierarchical Unified Graph Representation"
+keywords = ["Quantum", "Quantinuum"]
+categories = ["compilers"]
+
+[lints]
+workspace = true
+
+[features]
+extension_inference = []
+cli = ["dep:clap", "dep:clap-stdin"]
+
+[dependencies]
+portgraph = { workspace = true, features = ["serde", "petgraph"] }
+thiserror = { workspace = true }
+regex = { workspace = true }
+cgmath = { workspace = true, features = ["serde"] }
+num-rational = { workspace = true, features = ["serde"] }
+downcast-rs = { workspace = true }
+# Rc used here for Extension, but unfortunately we must turn the feature on globally
+serde = { workspace = true, features = ["derive", "rc"] }
+serde_yaml = { workspace = true }
+typetag = { workspace = true }
+smol_str = { workspace = true, features = ["serde"] }
+derive_more = { workspace = true }
+itertools = { workspace = true }
+html-escape = { workspace = true }
+bitvec = { workspace = true, features = ["serde"] }
+enum_dispatch = { workspace = true }
+lazy_static = { workspace = true }
+petgraph = { workspace = true }
+context-iterators = { workspace = true }
+serde_json = { workspace = true }
+delegate = { workspace = true }
+paste = { workspace = true }
+strum = { workspace = true }
+strum_macros = { workspace = true }
+clap = { workspace = true, features = ["derive"], optional = true }
+clap-stdin = { workspace = true, optional = true }
+
+[dev-dependencies]
+rstest = { workspace = true }
+webbrowser = { workspace = true }
+urlencoding = { workspace = true }
+cool_asserts = { workspace = true }
+insta = { workspace = true, features = ["yaml"] }
+jsonschema = { workspace = true }
+proptest = { workspace = true }
+proptest-derive = { workspace = true }
+regex-syntax = { workspace = true }
+assert_cmd = { workspace = true }
+predicates = { workspace = true }
+assert_fs = { workspace = true }
+
+# Required for documentation examples
+hugr = { path = "../hugr" }

hugr-core/README.md

@@ -0,0 +1,42 @@
+![](/hugr/assets/hugr_logo.svg)
+
+hugr-core
+===============
+
+[![build_status][]](https://github.com/CQCL/hugr/actions)
+[![crates][]](https://crates.io/crates/hugr-core)
+[![msrv][]](https://github.com/CQCL/hugr)
+[![codecov][]](https://codecov.io/gh/CQCL/hugr)
+
+Internal core definitions for the `hugr` package.
+Refer to the [main crate](http://crates.io/crates/hugr) for more information.
+
+Please read the [API documentation here][].
+
+## Experimental Features
+
+- `extension_inference`:
+  Experimental feature which allows automatic inference of extension usages and
+  requirements in a HUGR and validation that extensions are correctly specified.
+  Not enabled by default.
+
+## Recent Changes
+
+See [CHANGELOG][] for a list of changes. The minimum supported rust
+version will only change on major releases.
+
+## Development
+
+See [DEVELOPMENT.md](https://github.com/CQCL/hugr/blob/main/DEVELOPMENT.md) for instructions on setting up the development environment.
+
+## License
+
+This project is licensed under Apache License, Version 2.0 ([LICENSE][] or http://www.apache.org/licenses/LICENSE-2.0).
+
+  [API documentation here]: https://docs.rs/hugr-core/
+  [build_status]: https://github.com/CQCL/hugr/actions/workflows/ci-rs.yml/badge.svg?branch=main
+  [msrv]: https://img.shields.io/badge/rust-1.75.0%2B-blue.svg
+  [crates]: https://img.shields.io/crates/v/hugr-core
+  [codecov]: https://img.shields.io/codecov/c/gh/CQCL/hugr?logo=codecov
+  [LICENSE]: https://github.com/CQCL/hugr/blob/main/LICENCE
+  [CHANGELOG]: https://github.com/CQCL/hugr/blob/main/hugr-core/CHANGELOG.md

hugr/src/builder.rs → hugr-core/src/builder.rs

@@ -26,11 +26,11 @@
 //! `CircuitBuilder`.
 //!
 //! ```rust
-//! # use hugr::Hugr;
-//! # use hugr::builder::{BuildError, BuildHandle, Container, DFGBuilder, Dataflow, DataflowHugr, ModuleBuilder, DataflowSubContainer, HugrBuilder};
-//! use hugr::extension::prelude::BOOL_T;
-//! use hugr::std_extensions::logic::{NotOp, LOGIC_REG};
-//! use hugr::types::FunctionType;
+//! # use hugr_core::Hugr;
+//! # use hugr_core::builder::{BuildError, BuildHandle, Container, DFGBuilder, Dataflow, DataflowHugr, ModuleBuilder, DataflowSubContainer, HugrBuilder};
+//! use hugr_core::extension::prelude::BOOL_T;
+//! use hugr_core::std_extensions::logic::{NotOp, LOGIC_REG};
+//! use hugr_core::types::FunctionType;
 //!
 //! # fn doctest() -> Result<(), BuildError> {
 //! let hugr = {

hugr/src/extension/declarative.rs → hugr-core/src/extension/declarative.rs

@@ -9,15 +9,15 @@
 //! ### Example
 //!
 //! ```yaml
-#![doc = include_str!("../../examples/extension/declarative.yaml")]
+#![doc = include_str!("../../../hugr/examples/extension/declarative.yaml")]
 //! ```
 //!
 //! The definition can be loaded into a registry using the [`load_extensions`] or [`load_extensions_file`] functions.
 //! ```rust
-//! # const DECLARATIVE_YAML: &str = include_str!("../../examples/extension/declarative.yaml");
-//! # use hugr::extension::declarative::load_extensions;
+//! # const DECLARATIVE_YAML: &str = include_str!("../../../hugr/examples/extension/declarative.yaml");
+//! # use hugr_core::extension::declarative::load_extensions;
 //! // Required extensions must already be present in the registry.
-//! let mut reg = hugr::std_extensions::logic::LOGIC_REG.clone();
+//! let mut reg = hugr_core::std_extensions::logic::LOGIC_REG.clone();
 //! load_extensions(DECLARATIVE_YAML, &mut reg).unwrap();
 //! ```
 //!
@@ -327,7 +327,7 @@ extensions:
 "#;
 
     /// The yaml used in the module documentation.
-    const EXAMPLE_YAML_FILE: &str = "examples/extension/declarative.yaml";
+    const EXAMPLE_YAML_FILE: &str = "../hugr/examples/extension/declarative.yaml";
 
     #[rstest]
     #[case(EMPTY_YAML, 1, 0, 0, &PRELUDE_REGISTRY)]

hugr/src/hugr/views/snapshots/hugr__hugr__views__tests__dot_cfg.snap → hugr-core/src/hugr/views/snapshots/hugr_core__hugr__views__tests__dot_cfg.snap

@@ -1,5 +1,5 @@
 ---
-source: hugr/src/hugr/views/tests.rs
+source: hugr-core/src/hugr/views/tests.rs
 expression: h.dot_string()
 ---
 digraph {

hugr/src/hugr/views/snapshots/hugr__hugr__views__tests__dot_dfg.snap → hugr-core/src/hugr/views/snapshots/hugr_core__hugr__views__tests__dot_dfg.snap

@@ -1,5 +1,5 @@
 ---
-source: hugr/views/tests.rs
+source: hugr-core/views/tests.rs
 expression: h.dot_string()
 ---
 digraph {

hugr/src/hugr/views/snapshots/hugr__hugr__views__tests__dot_empty_dfg.snap → hugr-core/src/hugr/views/snapshots/hugr_core__hugr__views__tests__dot_empty_dfg.snap

@@ -1,5 +1,5 @@
 ---
-source: hugr/src/hugr/views/tests.rs
+source: hugr-core/src/hugr/views/tests.rs
 expression: h.dot_string()
 ---
 digraph {

hugr/src/hugr/views/snapshots/hugr__hugr__views__tests__mmd_cfg.snap → hugr-core/src/hugr/views/snapshots/hugr_core__hugr__views__tests__mmd_cfg.snap

@@ -1,5 +1,5 @@
 ---
-source: hugr/src/hugr/views/tests.rs
+source: hugr-core/src/hugr/views/tests.rs
 expression: h.mermaid_string()
 ---
 graph LR

hugr/src/hugr/views/snapshots/hugr__hugr__views__tests__mmd_dfg.snap → hugr-core/src/hugr/views/snapshots/hugr_core__hugr__views__tests__mmd_dfg.snap

@@ -1,5 +1,5 @@
 ---
-source: src/hugr/views/tests.rs
+source: hugr-core/src/hugr/views/tests.rs
 expression: h.mermaid_string()
 ---
 graph LR

hugr/src/hugr/views/snapshots/hugr__hugr__views__tests__mmd_empty_dfg.snap → hugr-core/src/hugr/views/snapshots/hugr_core__hugr__views__tests__mmd_empty_dfg.snap

@@ -1,5 +1,5 @@
 ---
-source: hugr/src/hugr/views/tests.rs
+source: hugr-core/src/hugr/views/tests.rs
 expression: h.mermaid_string()
 ---
 graph LR

hugr-core/src/lib.rs

@@ -0,0 +1,163 @@
+//! Extensible, graph-based program representation with first-class support for linear types.
+//!
+//! The name HUGR stands for "Hierarchical Unified Graph Representation". It is designed primarily
+//! as an intermediate representation and interchange format for quantum and hybrid
+//! classical–quantum programs.
+//!
+//! Both data-flow and control-flow graphs can be represented in the HUGR. Nodes in the graph may
+//! represent basic operations, or may themselves have "child" graphs, which inherit their inputs
+//! and outputs. Special "non-local" edges allow data to pass directly from a node to another node
+//! that is not a direct descendent (subject to causality constraints).
+//!
+//! The specification can be found
+//! [here](https://github.com/CQCL/hugr/blob/main/specification/hugr.md).
+//!
+//! This crate provides a Rust implementation of HUGR and the standard extensions defined in the
+//! specification.
+//!
+//! It includes methods for:
+//!
+//! - building HUGRs from basic operations;
+//! - defining new extensions;
+//! - serializing and deserializing HUGRs;
+//! - performing local rewrites.
+//!
+//! # Example
+//!
+//! To build a HUGR for a simple quantum circuit and then serialize it to a buffer, we can define
+//! a simple quantum extension and then use the [[builder::DFGBuilder]] as follows:
+//! ```
+//! use hugr_core::builder::{BuildError, DFGBuilder, Dataflow, DataflowHugr};
+//! use hugr_core::extension::prelude::{BOOL_T, QB_T};
+//! use hugr_core::hugr::Hugr;
+//! use hugr_core::type_row;
+//! use hugr_core::types::FunctionType;
+//!
+//! // The type of qubits, `QB_T` is in the prelude but, by default, no gateset
+//! // is defined. This module provides Hadamard and CX gates.
+//! mod mini_quantum_extension {
+//!     use hugr_core::{
+//!         extension::{
+//!             prelude::{BOOL_T, QB_T},
+//!             ExtensionId, ExtensionRegistry, PRELUDE,
+//!         },
+//!         ops::{CustomOp, OpName},
+//!         type_row,
+//!         types::{FunctionType, PolyFuncType},
+//!         Extension,
+//!     };
+//!
+//!     use lazy_static::lazy_static;
+//!
+//!     fn one_qb_func() -> PolyFuncType {
+//!         FunctionType::new_endo(type_row![QB_T]).into()
+//!     }
+//!
+//!     fn two_qb_func() -> PolyFuncType {
+//!         FunctionType::new_endo(type_row![QB_T, QB_T]).into()
+//!     }
+//!     /// The extension identifier.
+//!     pub const EXTENSION_ID: ExtensionId = ExtensionId::new_unchecked("mini.quantum");
+//!     fn extension() -> Extension {
+//!         let mut extension = Extension::new(EXTENSION_ID);
+//!
+//!         extension
+//!             .add_op(OpName::new_inline("H"), "Hadamard".into(), one_qb_func())
+//!             .unwrap();
+//!
+//!         extension
+//!             .add_op(OpName::new_inline("CX"), "CX".into(), two_qb_func())
+//!             .unwrap();
+//!
+//!         extension
+//!             .add_op(
+//!                 OpName::new_inline("Measure"),
+//!                 "Measure a qubit, returning the qubit and the measurement result.".into(),
+//!                 FunctionType::new(type_row![QB_T], type_row![QB_T, BOOL_T]),
+//!             )
+//!             .unwrap();
+//!
+//!         extension
+//!     }
+//!
+//!     lazy_static! {
+//!         /// Quantum extension definition.
+//!         pub static ref EXTENSION: Extension = extension();
+//!         static ref REG: ExtensionRegistry =
+//!             ExtensionRegistry::try_new([EXTENSION.to_owned(), PRELUDE.to_owned()]).unwrap();
+//!
+//!     }
+//!     fn get_gate(gate_name: impl Into<OpName>) -> CustomOp {
+//!         EXTENSION
+//!             .instantiate_extension_op(&gate_name.into(), [], &REG)
+//!             .unwrap()
+//!             .into()
+//!     }
+//!     pub fn h_gate() -> CustomOp {
+//!         get_gate("H")
+//!     }
+//!
+//!     pub fn cx_gate() -> CustomOp {
+//!         get_gate("CX")
+//!     }
+//!
+//!     pub fn measure() -> CustomOp {
+//!         get_gate("Measure")
+//!     }
+//! }
+//!
+//! use mini_quantum_extension::{cx_gate, h_gate, measure};
+//!
+//! //      ┌───┐
+//! // q_0: ┤ H ├──■─────
+//! //      ├───┤┌─┴─┐┌─┐
+//! // q_1: ┤ H ├┤ X ├┤M├
+//! //      └───┘└───┘└╥┘
+//! // c:              ╚═
+//! fn make_dfg_hugr() -> Result<Hugr, BuildError> {
+//!     let mut dfg_builder = DFGBuilder::new(FunctionType::new(
+//!         type_row![QB_T, QB_T],
+//!         type_row![QB_T, QB_T, BOOL_T],
+//!     ))?;
+//!     let [wire0, wire1] = dfg_builder.input_wires_arr();
+//!     let h0 = dfg_builder.add_dataflow_op(h_gate(), vec![wire0])?;
+//!     let h1 = dfg_builder.add_dataflow_op(h_gate(), vec![wire1])?;
+//!     let cx = dfg_builder.add_dataflow_op(cx_gate(), h0.outputs().chain(h1.outputs()))?;
+//!     let measure = dfg_builder.add_dataflow_op(measure(), cx.outputs().last())?;
+//!     dfg_builder.finish_prelude_hugr_with_outputs(cx.outputs().take(1).chain(measure.outputs()))
+//! }
+//!
+//! let h: Hugr = make_dfg_hugr().unwrap();
+//! let serialized = serde_json::to_string(&h).unwrap();
+//! println!("{}", serialized);
+//! ```
+
+// Unstable check, may cause false positives.
+// https://github.com/rust-lang/rust-clippy/issues/5112
+#![warn(clippy::debug_assert_with_mut_call)]
+// proptest-derive generates many of these warnings.
+// https://github.com/rust-lang/rust/issues/120363
+// https://github.com/proptest-rs/proptest/issues/447
+#![cfg_attr(test, allow(non_local_definitions))]
+
+pub mod builder;
+pub mod core;
+pub mod extension;
+pub mod hugr;
+pub mod macros;
+pub mod ops;
+pub mod std_extensions;
+pub mod types;
+pub mod utils;
+
+pub use crate::core::{
+    CircuitUnit, Direction, IncomingPort, Node, NodeIndex, OutgoingPort, Port, PortIndex, Wire,
+};
+pub use crate::extension::Extension;
+pub use crate::hugr::{Hugr, HugrView, SimpleReplacement};
+
+#[cfg(feature = "cli")]
+pub mod cli;
+
+#[cfg(test)]
+pub mod proptest;