BloqBuilder.map_soqs behavior when soq is not in map

[mpharrigan]

Background

BloqBuilder.map_soqs is a somewhat advanced method generally used when you're building a program (composite bloq) from an existing bloq (potentially with modification). It's needed because each BloqInstance in a compute graph has a locally-unique integer index i, and if you're adding bloq instances from one compute graph to the new one, you need to update all these references.

From the docstring of CompositeBloq.iter_bloqsoqs, this is an example of how you'd make a copy of a bloq.

            >>> from qualtran.bloqs.for_testing.with_decomposition import TestParallelCombo
            >>> cbloq = TestParallelCombo().decompose_bloq()
            >>> bb, _ = BloqBuilder.from_signature(cbloq.signature)
            >>> soq_map: List[Tuple[SoquetT, SoquetT]] = []
            >>> for binst, in_soqs, old_out_soqs in cbloq.iter_bloqsoqs():
            ...    in_soqs = bb.map_soqs(in_soqs, soq_map)
            ...    new_out_soqs = bb.add_t(binst.bloq, **in_soqs)
            ...    soq_map.extend(zip(old_out_soqs, new_out_soqs))
            >>> bb.finalize(**bb.map_soqs(cbloq.final_soqs(), soq_map))
            CompositeBloq(...)

Current Behavior

See how we initialize soq_map with an empty list in the above? map_soqs will leave any in_soqs not found in soq_map unchanged. This happens to work because the initial soquets connect to the special DanglingT sentinels and don't have these unique bloq instance indices.

Upgrade our usages

We should add a helper method and change internal usages of map_soqs to not rely on this quirky behavior. E.g., the initialization of soq_map can be replaced with

            >>> soq_map = bb.initial_soq_map(cbloq.signature.lefts())

Deprecate/Remove weird functionality

We should deprecate relying on the existing fallback; and it may make sense to remove it completely.