quantum-exercises 0.8.0__py3-none-any.whl

quantum_exercises/__init__.py

@@ -0,0 +1,44 @@
+"""qx: a command line course in quantum computing with Qiskit."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from functools import lru_cache
+
+__version__ = "0.8.0"
+
+
+@lru_cache(maxsize=1)
+def invocation() -> str:
+    """How to spell the command in guidance the tool prints.
+
+    `qx` once it is installed globally, `uv run qx` otherwise. The quickstart
+    installs it, so every written file says plainly `qx`; this exists for the
+    reader who skipped that step, so the guidance still matches what they can
+    type. Printing one form unconditionally would contradict one of them.
+
+    Lives here rather than in ui so that registry and runner can use it too,
+    since ui imports both of them.
+    """
+    # A qx inside this interpreter's own environment is the one `uv run` or an
+    # activated venv puts on PATH for the moment. It is not there in the reader's
+    # next shell, so answering "qx" on the strength of it would be exactly the
+    # mistake this helper exists to prevent.
+    #
+    # So look past it: search every PATH entry and keep the first qx that is not
+    # inside this environment. Finding one means a global install really is there
+    # and `qx` is what the reader should type, whether or not a venv happens to be
+    # active right now. Compared without resolving symlinks on purpose, because
+    # `uv tool install` leaves a link in ~/.local/bin pointing back into the
+    # tool's own environment, and that link is a real, permanent entry on PATH.
+    prefix = os.path.normcase(os.path.abspath(sys.prefix)) + os.sep
+    for directory in os.get_exec_path():
+        candidate = shutil.which("qx", path=directory)
+        if candidate and not os.path.normcase(os.path.abspath(candidate)).startswith(prefix):
+            return "qx"
+    return "uv run qx"
+
+
+__all__ = ["__version__", "invocation"]

quantum_exercises/_course/exercises/01_environment/README.md

@@ -0,0 +1,34 @@
+# 01 - Your environment works
+
+Before any quantum mechanics, one boring question has to be settled: does code you
+write in this repository actually run, against the Qiskit that is actually installed?
+
+Plenty of quantum tutorials fail at this step and never say so. You get an error
+about `execute` or `Aer`, you assume you misunderstood the physics, and you stop.
+You did not misunderstand anything. You were reading instructions for a version of
+the library that no longer exists.
+
+So the first exercise checks the ground you are standing on.
+
+## Your task
+
+Open `exercise.py` and do two things:
+
+1. Import the `qiskit` package.
+2. Set `qiskit_version` to the version string Qiskit reports about itself.
+
+The runner compares your answer against the version genuinely installed in this
+project's virtual environment. Copying a number from a blog post will not pass.
+
+## Run it
+
+```bash
+qx run 1
+```
+
+## What you should take away
+
+A Python package usually exposes its own version as `package.__version__`. That
+attribute is the single most useful thing to print when something behaves
+differently from a tutorial, because almost every "this doesn't work" in the
+Qiskit world is a version mismatch.

quantum_exercises/_course/exercises/01_environment/check.py

@@ -0,0 +1,63 @@
+"""Verification for exercise 01."""
+
+from importlib.metadata import version
+from pathlib import Path
+
+import qiskit
+
+from quantum_exercises.checks import CheckFailed, require, text_artifact
+
+
+def check(mod):
+    reported = require(mod, "qiskit_version", str)
+    actual = qiskit.__version__
+
+    _require_asking_the_package(mod)
+
+    if reported != actual:
+        raise CheckFailed(
+            f"You reported Qiskit {reported!r}, but this environment has {actual!r}.",
+            detail=(
+                "Read the value from the package rather than typing it in, so the answer "
+                "stays true after the next `uv sync`."
+            ),
+        )
+
+    return text_artifact(
+        f"Qiskit SDK      {actual}\n"
+        f"qiskit-aer      {_safe_version('qiskit-aer')}\n"
+        f"IBM Runtime     {_safe_version('qiskit-ibm-runtime')}",
+        caption="Your quantum stack",
+    )
+
+
+def _require_asking_the_package(mod) -> None:
+    """Typing the right number in also matches, and stops being right next sync.
+
+    The exercise is about asking the package, so read the file and insist on it.
+    """
+    source_file = getattr(mod, "__file__", None)
+    if not source_file:
+        return
+    try:
+        source = Path(source_file).read_text(encoding="utf-8")
+    except OSError:
+        return
+
+    if "__version__" in source or "importlib" in source:
+        return
+
+    raise CheckFailed(
+        "The version is written in by hand rather than read from the package.",
+        detail=(
+            "A literal is right until the next `uv sync` and then quietly wrong, which is the "
+            "exact failure this exercise is about. Ask qiskit what version it is."
+        ),
+    )
+
+
+def _safe_version(package: str) -> str:
+    try:
+        return version(package)
+    except Exception:  # noqa: BLE001 - a missing optional package is not a failure here
+        return "not installed"

quantum_exercises/_course/exercises/01_environment/exercise.py

@@ -0,0 +1,11 @@
+"""Exercise 01 - your environment works.
+
+Fill in the TODOs, then run:  qx run 1
+"""
+
+# TODO: import the qiskit package.
+
+# TODO: replace None with the version string that qiskit reports about itself.
+#       A package normally exposes this as a module-level attribute whose name
+#       starts and ends with two underscores.
+qiskit_version = None

quantum_exercises/_course/exercises/01_environment/hints.md

@@ -0,0 +1,30 @@
+## Hint 1
+
+Two lines are enough. The first is an `import`. The second assigns to
+`qiskit_version`.
+
+Do not type the version number by hand, even if you know it. Ask the package.
+
+## Hint 2
+
+Almost every Python package stores its own version in an attribute named with two
+leading and two trailing underscores. You have seen the pattern before in
+`__init__` and `__main__`.
+
+Try this in a terminal to see it:
+
+```bash
+uv run python -c "import qiskit; print(dir(qiskit))"
+```
+
+Look through the names that start with `__`.
+
+## Hint 3
+
+The attribute is `__version__`:
+
+```python
+import qiskit
+
+qiskit_version = qiskit.__version__
+```

quantum_exercises/_course/exercises/01_environment/meta.toml

@@ -0,0 +1,4 @@
+title = "Your environment works"
+act = "Act I - Reaching a first result"
+summary = "Prove the toolchain is real: import Qiskit and read the version it reports about itself."
+hardware = false

quantum_exercises/_course/exercises/01_environment/solution.py

@@ -0,0 +1,5 @@
+"""Exercise 01 - reference solution."""
+
+import qiskit
+
+qiskit_version = qiskit.__version__

quantum_exercises/_course/exercises/01_environment/template.py

@@ -0,0 +1,11 @@
+"""Exercise 01 - your environment works.
+
+Fill in the TODOs, then run:  qx run 1
+"""
+
+# TODO: import the qiskit package.
+
+# TODO: replace None with the version string that qiskit reports about itself.
+#       A package normally exposes this as a module-level attribute whose name
+#       starts and ends with two underscores.
+qiskit_version = None

quantum_exercises/_course/exercises/02_dictionaries/README.md

@@ -0,0 +1,41 @@
+# 02 - Counts is just a dictionary
+
+Every measurement result you will see in this course arrives in the same shape:
+
+```python
+{"00": 508, "11": 516}
+```
+
+Keys are the outcomes, as strings of bits. Values are how many of your shots
+produced that outcome. That is the whole data structure. No quantum magic.
+
+This exercise exists because the single most common stumbling block in the first
+week is not superposition, it is reaching for `counts[0]` and getting a
+`KeyError`. `"00"` is a string key, not a position. A dict is not a list.
+
+## Your task
+
+Implement three functions in `exercise.py`. You will use all three repeatedly for
+the rest of the course.
+
+| Function | Returns |
+|---|---|
+| `total_shots(counts)` | how many shots produced this result |
+| `most_common(counts)` | the outcome that occurred most often |
+| `outcome_probabilities(counts)` | `{outcome: estimated probability}` |
+
+The runner calls your functions with several different dictionaries, so hardcoding
+one answer will not pass.
+
+## Run it
+
+```bash
+qx run 2
+```
+
+## What you should take away
+
+`outcome_probabilities` is doing real physics, even though it is three lines of
+Python. Dividing a count by the number of shots is how you estimate a probability
+from a finite sample, and it is exactly why your numbers never come out at a clean
+0.5. You are sampling, not reading a value off the state.

quantum_exercises/_course/exercises/02_dictionaries/check.py

@@ -0,0 +1,91 @@
+"""Verification for exercise 02."""
+
+import math
+
+from quantum_exercises.checks import CheckFailed, require, text_artifact
+
+# Several inputs, so a hardcoded answer to one of them fails on the others.
+# No ties in any case, so most_common has a single correct answer.
+CASES = [
+    {"00": 500, "11": 524},
+    {"0": 750, "1": 250},
+    {"000": 10, "001": 30, "111": 60},
+    {"1010": 4096},
+]
+
+
+def check(mod):
+    total_shots = _callable(mod, "total_shots")
+    most_common = _callable(mod, "most_common")
+    outcome_probabilities = _callable(mod, "outcome_probabilities")
+
+    if total_shots({}) != 0:
+        raise CheckFailed(
+            "total_shots({}) should be 0.",
+            detail="Summing an empty collection gives 0. Python's sum() already does this.",
+        )
+
+    for counts in CASES:
+        expected_total = sum(counts.values())
+        actual_total = total_shots(counts)
+        if actual_total != expected_total:
+            raise CheckFailed(
+                f"total_shots({counts}) returned {actual_total!r}, expected {expected_total}.",
+                detail="Add up the values, not the keys. counts.values() gives you the numbers.",
+            )
+
+        expected_common = max(counts, key=lambda outcome: counts[outcome])
+        actual_common = most_common(counts)
+        if actual_common != expected_common:
+            raise CheckFailed(
+                f"most_common({counts}) returned {actual_common!r}, expected {expected_common!r}.",
+                detail=(
+                    "Return the outcome itself, the key, not how many times it happened. "
+                    f"Here {expected_common!r} occurred {counts[expected_common]} times."
+                ),
+            )
+
+        expected_probs = {k: v / expected_total for k, v in counts.items()}
+        actual_probs = outcome_probabilities(counts)
+        _compare_probs(counts, actual_probs, expected_probs)
+
+    lines = []
+    for counts in CASES[:2]:
+        probs = outcome_probabilities(counts)
+        rendered = ", ".join(f"{k}: {v:.3f}" for k, v in sorted(probs.items()))
+        lines.append(
+            f"{counts}\n  -> {total_shots(counts)} shots, most common {most_common(counts)!r}"
+        )
+        lines.append(f"  -> probabilities {{{rendered}}}")
+
+    return text_artifact("\n".join(lines), caption="Your functions on real data")
+
+
+def _callable(mod, name):
+    value = require(mod, name)
+    if not callable(value):
+        raise CheckFailed(f"`{name}` should be a function, but it is a {type(value).__name__}.")
+    return value
+
+
+def _compare_probs(counts, actual, expected):
+    if not isinstance(actual, dict):
+        raise CheckFailed(
+            f"outcome_probabilities({counts}) returned a {type(actual).__name__}, expected a dict.",
+        )
+    if set(actual) != set(expected):
+        raise CheckFailed(
+            f"outcome_probabilities({counts}) returned keys {sorted(actual)}, "
+            f"expected {sorted(expected)}.",
+            detail="Keep the same outcomes as the input; only the values change.",
+        )
+    for outcome, want in expected.items():
+        got = actual[outcome]
+        if not isinstance(got, (int, float)) or not math.isclose(float(got), want, abs_tol=1e-9):
+            raise CheckFailed(
+                f"outcome_probabilities({counts})[{outcome!r}] is {got!r}, expected {want}.",
+                detail=(
+                    "Divide each count by the total number of shots. If you got a whole number, "
+                    "check that you are dividing with / and not //."
+                ),
+            )

quantum_exercises/_course/exercises/02_dictionaries/exercise.py

@@ -0,0 +1,40 @@
+"""Exercise 02 - counts is just a dictionary.
+
+Fill in the TODOs, then run:  qx run 2
+"""
+
+
+def total_shots(counts: dict[str, int]) -> int:
+    """Return how many shots produced this result.
+
+    That is the sum of all the values. An empty dict must return 0.
+
+    >>> total_shots({"00": 500, "11": 524})
+    1024
+    """
+    # TODO: replace this with the sum of the dictionary's values.
+    return 0
+
+
+def most_common(counts: dict[str, int]) -> str:
+    """Return the outcome that occurred most often.
+
+    `counts` always has at least one entry, and there is never a tie.
+
+    >>> most_common({"00": 500, "11": 524})
+    '11'
+    """
+    # TODO: return the key whose value is the largest.
+    return ""
+
+
+def outcome_probabilities(counts: dict[str, int]) -> dict[str, float]:
+    """Return each outcome's share of the shots.
+
+    `counts` always has at least one entry and at least one shot.
+
+    >>> outcome_probabilities({"0": 750, "1": 250})
+    {'0': 0.75, '1': 0.25}
+    """
+    # TODO: build a new dict mapping each outcome to count / total.
+    return {}

quantum_exercises/_course/exercises/02_dictionaries/hints.md

@@ -0,0 +1,40 @@
+## Hint 1
+
+Three built-ins do almost all the work here: `sum`, `max`, and a dict
+comprehension.
+
+For `total_shots`, remember that a dict has three views: `.keys()`, `.values()`
+and `.items()`. You want the one holding the numbers.
+
+## Hint 2
+
+`max(counts)` alone gives the largest **key** in alphabetical order, which is not
+what you want. `max` takes a `key=` argument telling it what to rank by:
+
+```python
+max(counts, key=lambda outcome: counts[outcome])
+```
+
+Read that as: go through the outcomes, and rank each one by the number it maps to.
+
+For the probabilities, a dict comprehension has the shape
+`{k: f(v) for k, v in counts.items()}`.
+
+## Hint 3
+
+```python
+def total_shots(counts):
+    return sum(counts.values())
+
+
+def most_common(counts):
+    return max(counts, key=lambda outcome: counts[outcome])
+
+
+def outcome_probabilities(counts):
+    shots = total_shots(counts)
+    return {outcome: count / shots for outcome, count in counts.items()}
+```
+
+Note `/` and not `//`. Integer division floors, so every probability short of a
+whole 1 comes back as 0.

quantum_exercises/_course/exercises/02_dictionaries/meta.toml

@@ -0,0 +1,4 @@
+title = "Counts is just a dictionary"
+act = "Act I - Reaching a first result"
+summary = "Quantum results arrive as a plain Python dict. Write the three functions you will keep reusing."
+hardware = false

quantum_exercises/_course/exercises/02_dictionaries/solution.py

@@ -0,0 +1,15 @@
+"""Exercise 02 - reference solution."""
+
+
+def total_shots(counts: dict[str, int]) -> int:
+    return sum(counts.values())
+
+
+def most_common(counts: dict[str, int]) -> str:
+    # max() over the keys, ranked by the value each key maps to.
+    return max(counts, key=lambda outcome: counts[outcome])
+
+
+def outcome_probabilities(counts: dict[str, int]) -> dict[str, float]:
+    shots = total_shots(counts)
+    return {outcome: count / shots for outcome, count in counts.items()}

quantum_exercises/_course/exercises/02_dictionaries/template.py

@@ -0,0 +1,40 @@
+"""Exercise 02 - counts is just a dictionary.
+
+Fill in the TODOs, then run:  qx run 2
+"""
+
+
+def total_shots(counts: dict[str, int]) -> int:
+    """Return how many shots produced this result.
+
+    That is the sum of all the values. An empty dict must return 0.
+
+    >>> total_shots({"00": 500, "11": 524})
+    1024
+    """
+    # TODO: replace this with the sum of the dictionary's values.
+    return 0
+
+
+def most_common(counts: dict[str, int]) -> str:
+    """Return the outcome that occurred most often.
+
+    `counts` always has at least one entry, and there is never a tie.
+
+    >>> most_common({"00": 500, "11": 524})
+    '11'
+    """
+    # TODO: return the key whose value is the largest.
+    return ""
+
+
+def outcome_probabilities(counts: dict[str, int]) -> dict[str, float]:
+    """Return each outcome's share of the shots.
+
+    `counts` always has at least one entry and at least one shot.
+
+    >>> outcome_probabilities({"0": 750, "1": 250})
+    {'0': 0.75, '1': 0.25}
+    """
+    # TODO: build a new dict mapping each outcome to count / total.
+    return {}

quantum_exercises/_course/exercises/03_first_circuit/README.md

@@ -0,0 +1,39 @@
+# 03 - Your first circuit
+
+A quantum circuit in Qiskit is an object you build up line by line. You create it
+with a number of wires, then you call methods on it to add gates.
+
+```python
+qc = QuantumCircuit(2)  # two qubits, no classical bits
+qc.h(0)  # Hadamard on qubit 0
+qc.cx(0, 1)  # controlled-NOT, control 0, target 1
+```
+
+The Hadamard gate is where every course starts, because it is the cheapest way to
+create superposition. Applied to a qubit sitting in state 0, it produces a state
+that is equally likely to be measured as 0 or as 1.
+
+## Your task
+
+In `exercise.py`, build a circuit with exactly **one qubit and no classical bits**,
+and apply a Hadamard gate to qubit 0. Leave the result in `qc`.
+
+Do not add a measurement. This exercise looks at the circuit as a matrix, and a
+measurement is not a matrix. Exercise 04 adds the measurement.
+
+## Run it
+
+```bash
+qx run 3
+```
+
+## What you should take away
+
+The runner does not compare your code to the solution as text. It builds the
+matrix your circuit represents and compares it to the matrix a Hadamard gate
+represents, using `Operator.equiv`.
+
+`equiv` deliberately ignores global phase. If your circuit produces a matrix that
+differs from Hadamard's by an overall factor like -1 or `i`, it still passes,
+because no measurement can ever distinguish those two circuits. That is physics,
+not leniency. You will meet this again in exercise 07.

quantum_exercises/_course/exercises/03_first_circuit/check.py

@@ -0,0 +1,49 @@
+"""Verification for exercise 03."""
+
+from qiskit.circuit.library import HGate
+from qiskit.quantum_info import Operator
+
+from quantum_exercises.checks import (
+    CheckFailed,
+    assert_operator_equiv,
+    matrix_artifact,
+    require_circuit,
+    text_artifact,
+)
+
+
+def check(mod):
+    qc = require_circuit(mod, "qc")
+
+    if qc.num_qubits != 1:
+        raise CheckFailed(
+            f"Your circuit has {qc.num_qubits} qubits, but this exercise asks for exactly 1.",
+            detail="QuantumCircuit(1) creates a single-qubit circuit.",
+        )
+
+    if qc.num_clbits != 0:
+        raise CheckFailed(
+            f"Your circuit has {qc.num_clbits} classical bits, but this exercise asks for none.",
+            detail=(
+                "A classical register is only needed to store measurement results, and this "
+                "exercise has no measurement. QuantumCircuit(1) with a single argument gives "
+                "you zero classical bits."
+            ),
+        )
+
+    if len(qc.data) == 0:
+        raise CheckFailed(
+            "Your circuit is empty: no gate was added.",
+            detail="Creating the circuit is only half the task. Now apply the Hadamard gate.",
+        )
+
+    operator = assert_operator_equiv(
+        qc,
+        Operator(HGate()),
+        message="Your circuit does not implement a Hadamard gate.",
+    )
+
+    return [
+        text_artifact(str(qc.draw(output="text")), caption="Your circuit"),
+        matrix_artifact(operator, caption="The matrix it represents"),
+    ]

quantum_exercises/_course/exercises/03_first_circuit/exercise.py

@@ -0,0 +1,13 @@
+"""Exercise 03 - your first circuit.
+
+Fill in the TODOs, then run:  qx run 3
+"""
+
+from qiskit import QuantumCircuit
+
+# TODO: create a circuit with exactly one qubit and no classical bits.
+#       QuantumCircuit takes the number of qubits as its first argument.
+qc = None
+
+# TODO: apply a Hadamard gate to qubit 0.
+#       Gate methods are named after the gate and take the qubit index.

quantum_exercises/_course/exercises/03_first_circuit/hints.md

@@ -0,0 +1,28 @@
+## Hint 1
+
+Two lines, replacing the two TODOs.
+
+`QuantumCircuit(1)` and `QuantumCircuit(1, 1)` are both valid Python, but they
+build different things. The second argument is the number of classical bits, and
+this exercise wants none of those.
+
+## Hint 2
+
+Gate methods on a circuit are short and lowercase, named after the gate itself:
+
+- `qc.h(0)` - Hadamard
+- `qc.x(0)` - NOT
+- `qc.z(0)` - phase flip
+- `qc.cx(0, 1)` - controlled-NOT
+
+They mutate the circuit in place, so you call `qc.h(0)` on its own line. Writing
+`qc = qc.h(0)` would throw away your circuit.
+
+## Hint 3
+
+```python
+from qiskit import QuantumCircuit
+
+qc = QuantumCircuit(1)
+qc.h(0)
+```

quantum_exercises/_course/exercises/03_first_circuit/meta.toml

@@ -0,0 +1,4 @@
+title = "Your first circuit"
+act = "Act I - Reaching a first result"
+summary = "Build a one-qubit circuit with a Hadamard gate and see the matrix it represents."
+hardware = false

quantum_exercises/_course/exercises/03_first_circuit/solution.py

@@ -0,0 +1,6 @@
+"""Exercise 03 - reference solution."""
+
+from qiskit import QuantumCircuit
+
+qc = QuantumCircuit(1)
+qc.h(0)

quantum_exercises/_course/exercises/03_first_circuit/template.py

@@ -0,0 +1,13 @@
+"""Exercise 03 - your first circuit.
+
+Fill in the TODOs, then run:  qx run 3
+"""
+
+from qiskit import QuantumCircuit
+
+# TODO: create a circuit with exactly one qubit and no classical bits.
+#       QuantumCircuit takes the number of qubits as its first argument.
+qc = None
+
+# TODO: apply a Hadamard gate to qubit 0.
+#       Gate methods are named after the gate and take the qubit index.