feat: add source mapping for calibration expansion

quil-py/quil/program/__init__.pyi

@@ -1,3 +1,70 @@
+"""
+The `quil.program` module contains classes for constructing and representing a Quil program.
+
+# Examples
+
+## Source Mapping for Calibration Expansion
+
+```py
+    import inspect
+
+    program_text = inspect.cleandoc(
+        \"\"\"
+        DEFCAL X 0:
+            Y 0
+
+        DEFCAL Y 0:
+            Z 0
+
+        X 0 # This instruction is index 0
+        Y 0 # This instruction is index 1
+        \"\"\"
+    )
+
+    # First, we parse the program and expand its calibrations
+    program = Program.parse(program_text)
+    expansion = program.expand_calibrations_with_source_map()
+    source_map = expansion.source_map()
+
+    # This is what we expect the expanded program to be. X and Y have been replaced by Z
+    expected_program_text = inspect.cleandoc(
+        \"\"\"
+        DEFCAL X 0:
+            Y 0
+
+        DEFCAL Y 0:
+            Z 0
+
+        Z 0 # This instruction is index 0
+        Z 0 # This instruction is index 1
+        \"\"\"
+    )
+
+    # In order to discover _which_ calibration led to each Z in the resulting program, we
+    # can interrogate the expansion source mapping:
+
+    # The X at index 0 should have been replaced with a Z at index 0:
+
+    # ...first, we list the calibration expansion targets for that first instruction...
+    targets = source_map.list_targets_for_source_index(0)
+
+    # ...then we extract the expanded instruction.
+    # If the instruction had _not_ been expanded (i.e. there was no matching calibration), then `as_expanded()` would return `None`.
+    expanded = targets[0].as_expanded()
+
+    # ...This line shows how that `X 0` was expanded into instruction index 0 (only) within the expanded program.
+    # The end of the range is exclusive.
+    assert expanded.range() == range(0, 1)
+
+    # We can also map instructions in reverse: given an instruction index in the expanded program, we can find the source index.
+    # This is useful for understanding the provenance of instructions in the expanded program.
+    sources = source_map.list_sources_for_target_index(1)
+
+    # ... in this case, the instruction was expanded from the source program at index 1.
+    assert sources == [1]
+```
+"""
+
 from typing import Callable, Dict, FrozenSet, List, Optional, Sequence, Set, Union, final
 
 import numpy as np