docs: Document Guppy libraries#1552
docs: Document Guppy libraries#1552maximilianruesch wants to merge 23 commits intomr/feat/compile-libraryfrom
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## mr/feat/compile-library #1552 +/- ##
===========================================================
- Coverage 93.55% 93.42% -0.13%
===========================================================
Files 130 128 -2
Lines 12364 12064 -300
===========================================================
- Hits 11567 11271 -296
+ Misses 797 793 -4 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Bencher Report
| concerns additional ways to define (members of) a library, and automatically collect functions to be included in it. | ||
|
|
||
| A potential addition would be a `@guppy(export=...)` argument, that registers the function to be included in *the* | ||
| library in some global Guppy store (like the `DEF_STORE`). A function could then be included simply by adding that |
There was a problem hiding this comment.
a "global library" is a bit confusing - this still would require some notion of a specific library the function is exported in. The string method below addresses this, but passing in library objects rather than strings seems preferable
There was a problem hiding this comment.
This seems very similar to how GuppyModules were handled.
| main.emulator(n_qubits=..., libraries=discover_hugr_packages()).with_shots(100).run() | ||
| ``` | ||
|
|
||
| Optionally, omission of `libraries` may lead to internal calls to automatic discovery, and other means of configuring |
There was a problem hiding this comment.
what about instead just refer to library by name, which is then looked up in the discovered set, seems more familiar to the search path/-L mylib compiler CLI pattern
There was a problem hiding this comment.
I think all three should be allowed (pass hugr, pass name (which is looked up), and passing nothing which means all known hugrs get thrown in).
|
|
||
|
|
||
| # Choice 2, different syntax, same effect | ||
| @guppy(instances=[{T: int}, {T: float}, ...]) # may be unpacked, as QOL for manual specification |
There was a problem hiding this comment.
alternative, specify at point of library specification, and use existing type parameter syntax:
library = guppy.library(my_generic_func[int], my_generic_func[float])There was a problem hiding this comment.
Potentially a lot more verbose, but would allow for different instances in different libraries, which is a win. Perhaps we can do / allow both?
| # from package_a, package_b, and package_c | ||
| ``` | ||
|
|
||
| There are no guarantees about the order of modules being linked together, or whether that is pairwise or all at once. |
There was a problem hiding this comment.
If we reject duplicate definitions then the order generally only affects what error is reported, rather than whether there is an error or what the resulting Hugr looks like in case of success, so fine :)
docs/library-docs/overview.md
Outdated
|
|
||
| # In the future, keywords may be added to allow e.g. privatization of all | ||
| # functions from package_b (i.e. swallowing), so for example: | ||
| package_a.link(package_b, privatize=True) |
There was a problem hiding this comment.
Or possibly something funky like package_a.link(Privatize(package_b), ReplaceFuncsWithExisting(package_c)) where Privatize/... have a type of LinkingDirective (i.e. are not funcs producing a Hugr/Package)
There was a problem hiding this comment.
I will leave that to be figured out by future implementors
4 participants
Checkout, build with
just build-docsand then opendocs/build/library-docs/index.htmlin your favourite HTML renderer.Closes #1548