> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhymeq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 2. First steps: From zero to universality

## 2.1 Superposition

In the code snippet below, we can think of the ordinary Python variable `i` as referring to a segment of memory (e.g. 3 consecutive bits) that holds the value `5`:

```python theme={null}
i = 5
```

Rhyme introduces **quantum types** that obey quantum semantics. Here, we define the quantum integer `j` holding the values `5` and `6` in **superposition**:

```python theme={null}
from rhyme import qint

j = qint(5, 6)
```

We can think of `j` as referring to a segment of memory (e.g. 3 consecutive bits) that somehow holds **both** values `5` and `6` at the same time. More precisely, `j` holds a value that is a "combination" of `5` and `6`. When executed on a quantum computer, the code above physically creates superposition! On your laptop, it simulates superposition.

If you don't 100% grasp superposition, then join the club: nobody on the planet does. Nevertheless, superposition is an experimental fact. The best we can do is to **try to get used to it** and see if we can harness it to solve interesting problems.

## 2.2 Amplitudes

According to quantum mechanics, `5` and `6` each "participate" in the superposition with some **amplitude**. We can see in the debugger that the `qint()` constructor created a uniform superposition of its arguments `5` and `6`, each participating with an amplitude of $\frac{1}{\sqrt{2}}$:

![](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/language-reference/5_6_amplitudes.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=535f2e1023f2f5196e8329245c9db5cd)

`_amplitudes` is a private attribute because, in the physical world, the amplitudes in a superposition cannot be directly seen. However, for educational and debugging purposes, Rhyme allows you to "cheat" and view them in the simulator.

An important rule is that, at any point in time, the absolute squares of the amplitudes are guaranteed to add up to 1. The reason for this will become clear [later](#2-5-observation).

## 2.3 Phase change

In Rhyme, quantum programming is the art of manipulating the amplitudes. According to quantum mechanics, the amplitudes don't have to be positive numbers. They may be negative, or even complex numbers!

Let's use the `add_phase()` method to negate the amplitude of `5`:

```python theme={null}
from math import pi

j.add_phase(
    lambda x: pi if x == 5 else 0
)
```

The `lambda` function specifies that the amplitude of `5` is rotated by 180 degrees (`pi` radians) in the complex plane, which means negation, while all other amplitudes are rotated by 0 degrees (no change).

Indeed, the debugger now shows that the amplitude of `5` is $-\frac{1}{\sqrt{2}}$:

![](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/language-reference/5_6_negated.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=6e72db04bd4a3b4dee3e1a3e299e8c9f)

## 2.4 Interference

`add_phase()` does not change the absolute values of the amplitudes. To manipulate the absolute values, we can use the `interfere()` method:

```python theme={null}
j.interfere(
    lambda x: 7 if x == 6 else 6 if x == 7 else x,
    lambda x: x == 6
)
```

`interfere()` mixes the amplitudes pairwise. The first `lambda` argument forms pairs by mapping values to each other. In this case, `6` and `7` are paired. If a value is mapped to itself, its amplitude won't change. The second `lambda` argument determines the "left" element in a pair by returning `True` for the "left" values. Here, we have `(6, 7)`, not `(7, 6)`, because `6` is the "left" value.

Let `a` denote the amplitude of `6` (the "left" amplitude) and `b` the amplitude of `7` (the "right" amplitude). The rule is that `a` changes to $\frac{a+b}{\sqrt{2}}$ and `b` to $\frac{a-b}{\sqrt{2}}$.

But wait a moment... `7` doesn't even participate in the superposition. How can it have an amplitude? Well, although we say it "doesn't participate," formally it is still there with amplitude zero! Thus, the formulas for `interfere()` can be applied with `a = 1/sqrt(2)` and `b = 0`.

The debugger now shows that the amplitudes of `6` and `7` are both one half, as per the formulas above:

![](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/language-reference/6_7_interfere.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=5334d98ef6a0b49ef72e7d9fb35dd2c5)

## 2.5 Observation

Are you curious what a superposition looks like? Let's observe it!

```python theme={null}
outcome: int = j.observe()
print(outcome)
```

However, it's not what you'd expect... According to quantum mechanics, observation **collapses** the superposition to exactly one of its participating values, with a probability equal to the absolute square of its amplitude. Thus, there is a 50% chance of obtaining `5`, and a 25% chance each for `6` or `7`.

The value of `j` collapsed to `7`, which was also returned in `outcome`:

![](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/language-reference/7_observed.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=ac8b8eddc159385a0018ceb5e6441f43)

In general, collapse is the price we pay every time we want to extract information from a superposition.

## 2.6 Universality

Using the `add_phase()`, `interfere()`, and `observe()` methods of a quantum integer, you can compute anything that can be computed on a quantum computer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.