aws-cqc / aws-cqc/DeviceLayout.jl

Document automatic indexing

Open
#68 0 comments 0 reactions 0 assignees View on GitHub
documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.