aws-cqc / aws-cqc/DeviceLayout.jl
Document automatic indexing
- Dominant language
- Julia
- Stars
- 67
- Forks
- 14
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 21
Description
This isn't yet documented. `index_layer!` has no docstring and isn't exported, and the `SolidModelTarget` docstring says "- `indexed_layers`: A list of layer `Symbol`s to be turned into separate `PhysicalGroup`s with `"_\$i"` appended for each index `i`. These layers will be automatically indexed if not already present in a `Schematic`'s `index_dict`." It would be best for the docs to tie it to examples/applications (it's already used in the single transmon example), also explaining how to use it with `index_dict`. We should explain in more detail somewhere (not necessarily the example) specifically how `index_layer!` and automatic indexing works. Some of this detail and/or `index_layer!` itself may be "internals" and subject to breaking changes, although we should still document them to make that explicit and help with development/debugging. For temporary reference, here's my brief explanation as of v1.3:
For each layer in a `SolidModelTarget`'s `indexed_layers`, we look through the schematic's components (in the order they were added) for entities in those layers, set the index of those entities' metadata to zero, and make a copy of each entity outside the component with an incremented index starting at 1. This lets us associate that port index with its component in the schematic's `index_dict` entry for that layer. (It's a copy outside the component so that there's no risk that its coordinate system gets referenced elsewhere.) So for everything that's automatically indexed, we end up with a copy with index 0. Index 0 gets assigned to the physical group without any suffix (`"port"` rather than `"port_0"`).
Elements of the top-level coordinate system `schematic.coordinate_system` in indexed layers just have their index incremented.
Any entities in indexed layers outside components or the top-level coordinate system are ignored, so if you manually add ports inside references in the top-level coordinate system, those will have whatever index they started with (default 1). They will still have any suffix appropriate for that index.
`Path`s should not have metadata whose layer is in `indexed_layers`. If you're using a path to position an indexed entity, use an entity in an `attach!`-ed reference.
Contributor guide
Research direction
Start with the SolidModelTarget docstring, the single transmon example, and the index_layer! entry point; inspect how indexed_layers and index_dict are described and used. Document automatic indexing, index_layer!, relevant edge cases, and the internals or breaking-change status, with completion shown by clear guidance tied to the example.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- julia
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100