> ## 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.

# add_phase(): Changing the Phase of an Amplitude

In the previous tutorial, we learned how amplitudes can combine and interfere with each other.

But there is another way we can manipulate amplitudes before they interfere.

**We can change their phase.**

Let's see what this means with a simple example.

Let's create a superposition of four kinds of tea:

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

tea = superpose("hot", "warm", "cold", "iced")
```

As we know, `superpose()` creates an equal superposition of its arguments.

![Rhyme debugger showing equal amplitudes of hot, warm, iced and cold](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/add_phase_superpose.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=f38506bebfd6e48c33ac7e562ffd8806)

Here, each tea value has an equal amplitude:

$$
\frac{1}{2}
$$

because the squares of the four amplitudes add up to `1`. But amplitudes don't have to be positive numbers. They can also be negative, and more generally, they can be *complex numbers*.

This gives us another way to manipulate a superposition: *we can change the **phase** of an amplitude.*

## What is phase?

For now, let's think of an amplitude as something that has both a **size** and a **direction**. The size is called its **magnitude**. The direction is related to its **phase**.

![Figure representing add\_phase](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/add_phase_rotate1.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=eb7877c4726e387cc1e7300e8671d0be)

For example, consider these two amplitudes:

$$
\frac{1}{2}
$$

and

$$
-\frac{1}{2}
$$

They have the same magnitude:

$$
\left|\frac{1}{2}\right| = \left|-\frac{1}{2}\right| = \frac{1}{2}
$$

but they have opposite directions. We say that they have different phases. A convenient way to describe this difference is with an angle.

A rotation by `180` degrees, or `π` radians, takes:

$$
\frac{1}{2}
\quad\longrightarrow\quad
-\frac{1}{2}
$$

![Complex plane showing an amplitude of 1/2 rotated by π radians to -1/2 while keeping the same magnitude](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/add_phase_rotate2.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=c98b0ce6ddd9d729c7b611728adb2f56)

So a phase change can rotate an amplitude without changing its magnitude.

This is important because the probability of observing a value is given by the square of the magnitude of its amplitude, while the phase affects how that amplitude behaves when it is combined with other amplitudes.

*Now let's see how we can change the phase in Rhyme.*

## Changing the phase of our tea

Suppose we want to rotate the amplitude of `iced` tea by `180` degrees or `π` radians, while leaving the others untouched.

We can describe the rotation using an ordinary Python function:

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

def rot_angle(s: str) -> float:
    if s == "iced":
        return pi
    else:
        return 0
```

`rot_angle` is an ordinary Python function. It maps every string to a rotation angle. For `iced`, it returns `π`, which means a 180-degree rotation. For everything else, it returns `0`, so those amplitudes are left unchanged.

Now we can apply this phase change to our quantum string:

```python theme={null}
tea.add_phase(rot_angle)
```

Let's look at the amplitudes again.

![Rhyme debugger showing phase change in iced](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/add_phase.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=89634db3c3f578da52a469e1680659ae)

The amplitudes of `hot`, `warm`, and `cold` are still:

$$
\frac{1}{2}
$$

But the amplitude of `iced` has been rotated by `180` degrees:

$$
\frac{1}{2}
\quad\longrightarrow\quad
-\frac{1}{2}
$$

Notice that its magnitude is still `0.5`.

So `iced` has not become more or less likely to be observed just because we changed its phase.

If we observed the tea right now, `iced` would still have the same probability as before.

The phase change does not change the probability. It changes the phase of the amplitude.

## Why does phase matter?

At this point, you might wonder why we changed the phase of `iced` at all.

Suppose I only like **hot or iced tea**. I don't want to get warm or cold tea.

If I observed the tea right now, all four values would still have a 25% chance of being observed. So instead of observing it, I want to transform the superposition first.

I want the amplitudes of `warm` and `cold` to become zero, while the amplitudes of `hot` and `iced` remain non-zero.

**This is where changing the phase becomes useful.**

By changing the phase of `iced` by `π`, we rotate its amplitude by `180` degrees. Now `iced` has an amplitude with a different phase from `cold`. When we apply `interfere()`, this phase difference causes the amplitudes to cancel in one direction and combine in the other.

Let's see how this works.

Let's pair the teas like this:

```python theme={null}
def pair(tea: str) -> str:
    if tea == "hot": return "warm"
    if tea == "warm": return "hot"
    if tea == "cold": return "iced"
    if tea == "iced": return "cold"
    return tea
```

Here, `pair()` pairs `hot` with `warm`, and `cold` with `iced`.

We also need to tell Rhyme which value comes first in each pair:

```python theme={null}
def lr(tea: str) -> bool:
    return tea == "hot" or tea == "cold"
```

Now we can call:

```python theme={null}
tea.interfere(pair, lr)
```

Let's see what happens to the amplitudes.

For the `hot` and `warm` pair, both amplitudes are:

$$
A=\frac{1}{2},\qquad B=\frac{1}{2}
$$

So the new amplitudes are:

$$
hot\rightarrow\frac{A+B}{\sqrt{2}}
=\frac{\frac{1}{2}+\frac{1}{2}}{\sqrt{2}}
=\frac{1}{\sqrt{2}}
$$

and

$$
warm\rightarrow\frac{A-B}{\sqrt{2}}
=\frac{\frac{1}{2}-\frac{1}{2}}{\sqrt{2}}
=0
$$

So `hot` remains, while `warm` is cancelled.

Now consider the `cold` and `iced` pair.

Their amplitudes are:

$$
C=\frac{1}{2},\qquad D=-\frac{1}{2}
$$

The amplitude of `iced` is negative because we changed its phase earlier.

This time:

$$
cold\rightarrow\frac{C+D}{\sqrt{2}}
=\frac{\frac{1}{2}+(-\frac{1}{2})}{\sqrt{2}}
=0
$$

while:

$$
iced\rightarrow\frac{C-D}{\sqrt{2}}
=\frac{\frac{1}{2}-(-\frac{1}{2})}{\sqrt{2}}
=\frac{1}{\sqrt{2}}
$$

So `cold` is cancelled, while `iced` remains.

The resulting amplitudes are:

$$
hot\rightarrow\frac{1}{\sqrt{2}}
$$

$$
warm\rightarrow0
$$

$$
cold\rightarrow0
$$

$$
iced\rightarrow\frac{1}{\sqrt{2}}
$$

Now only `hot` and `iced` have non-zero amplitudes. This is also shown in the debugger:

![Rhyme debugger showing amplitudes on hot and iced](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/add_phase_interfere.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=be879253ff60f52819cd7f6a1f6b8428)

Here, both `hot` and `iced` remain with equal amplitudes.

Finally, we can observe the tea:

```python theme={null}
print(tea.observe())
```

The result is either `hot` or `iced`, each with a 50% chance.

Now we can see why the phase change mattered.

By rotating the amplitude of `iced` by `π`, we changed its sign. During interference, this caused `cold` to cancel and `iced` to remain.

So `add_phase()` lets us change the amplitudes in a way that can affect the result of a later interference.

The sequence is:

```text theme={null}
                    superpose()
                        ↓
                    add_phase()
                        ↓
                    interfere()
                        ↓
                     observe()
```

`superpose()` creates the values in a superposition.

`add_phase()` changes the phase of their amplitudes.

`interfere()` combines the amplitudes.

`observe()` gives us the final value.

**That's phase in Rhyme!**


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