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: simple_op.rs trait usage is confusing, explain it #1659

Open
ss2165 opened this issue Nov 15, 2024 · 0 comments
Open

docs: simple_op.rs trait usage is confusing, explain it #1659

ss2165 opened this issue Nov 15, 2024 · 0 comments

Comments

@ss2165
Copy link
Member

ss2165 commented Nov 15, 2024

We should do a better job of explaining how to define extensions. This might be something to come back to after the hugr-model changes to extensions is more mature. #1433

A brief explanation of how to use the current system:

The most direct way to construct an extension is to use the Extension interface to directly add types and ops: https://docs.rs/hugr/latest/hugr/struct.Extension.html

This is how the example at the top of the docs defines a mini_quantum_extension:
https://docs.rs/hugr/latest/hugr/index.html. For simple extensions this is a nice approach.

The traits in simple_op (https://docs.rs/hugr/latest/hugr/extension/simple_op/index.html) are helpers to help you define structures that you can use to both load ops in to the extension, and to add instances of those ops to HUGRs you are building. (For types, using Extension.add_type directly is still best).

The more generic your extension is (the more type parameters your types and operations have), the more complicated it becomes to define an extension.

In the simplest case where there are no type parameters, you can define a set of ops by defining a simple enum, deriving some strum_macros on that enum, and defining MakeOpDef on that enum. The logic operations in the standard example are a good example of this: https://github.com/CQCL/hugr/blob/main/hugr-core/src/std_extensions/logic.rs#L63.
That example also implements the MakeRegisteredOp trait which lets you use the op to build HUGRs, because the struct now points to the extension it belongs to and a registry holding that extension (for validating the operation).

The remaining traits are for operations with type parameters. A good example is the standard array extension, the operations are generic over the array type and size:https://github.com/CQCL/hugr/blob/main/hugr-core/src/extension/prelude/array.rs In this case typically you define one struct for the generic operation definition, and one struct to hold concrete instances with instantiated type arguments (ArrayOpDef and ArrayOp in this case). The concrete instances have to implement the MakeExtensionOp trait, and the two structures point to each other via the HasDef and HasConcrete traits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant