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

# Entanglement: Linking Quantum Values

In the previous tutorials, we learned how quantum values can exist in superposition, how their amplitudes can interfere, and how we can change their phase.

But quantum values can also become connected to each other.

This is called **entanglement**.

Let's take a closer look at it through Rhyme.

First, we define the variable `myDrink`, which is a character in superposition.

```python theme={null}
from rhyme import qchar, flip, join

myDrink = qchar('m', 't')
```

Here, `m` means mineral water and `t` means tap water. Both values are in an equal superposition and have equal amplitudes.

Then, we define the variable `yourDrink` to have the value `m`.

```python theme={null}
yourDrink = qchar('m')
```

Although `yourDrink` contains only one possible value, it is still represented by an amplitude. The amplitude is `1` for `m` and `0` for any other character.

The amplitudes of values of `myDrink` and `yourDrink` are:

![Amplitudes of values of myDrink and yourDrink](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_amplitudes.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=1755ae584fe7be1247f69b64c4f3b1eb)

These amplitudes are also shown in the Rhyme debugger.

## Seeing a Joint Value

According to quantum theory, the variables `myDrink` and `yourDrink` also have a **joint value**. A joint value represents the possible combinations of the classical values in `myDrink` and `yourDrink`, together with their amplitudes.

In the classical world, this is an obvious thing, and usually we don't spell it out. For example, if we have two marbles, a blue one and a green one, then we can consider the two marbles together, and their joint color value is `(blue, green)`. There is nothing special about it, as each marble has exactly one color.

In the quantum world, the same idea applies. The joint value of our drinks contains all the possible combinations of the classical values in `myDrink` and `yourDrink`, as we can see below:

![All possible joint values](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_joint_states.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=552fdcdf7de7580d9d3256d0e3238a58)

We use `join()` to tell the Rhyme simulator to consider these two values together, so that we can see their joint value in the debugger.

```python theme={null}
join(myDrink, yourDrink)
```

`join()` itself does not change the values or their amplitudes. In fact, it's merely a simulation facility, intended mostly for education purposes. Omitting `join()` does not change the outcome of a Rhyme program. In nature, the joint value always exists, whether we have classical marbles or quantum drinks.

The debugger now displays the amplitudes of `myDrink` and `yourDrink` as part of their joint value:

![Debugger showing joint amplitudes of myDrink](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_joint_myDrink.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=755017ff9b4f735e4c73113c0a36ccb4)

![Debugger showing joint amplitudes of yourDrink](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_joint_yourDrink.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=44b09faf0f976719a31e330c79667276)

Now let's look at how the amplitudes of these joint values are calculated.

The amplitude for each joint value is calculated by multiplying the corresponding amplitudes of its constituent values together.

For example, the amplitude of the combination `('m', 'm')` is:

$$
\frac{1}{\sqrt{2}}\times1 = \frac{1}{\sqrt{2}}.
$$

Similarly, the amplitude of `('t', 'm')` is also:

$$
\frac{1}{\sqrt{2}}\times1 = \frac{1}{\sqrt{2}}.
$$

For all possible joint values, the amplitudes are calculated as:

![All joint amplitudes](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_joint_amplitudes.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=4c69ea30c611f3350ff10a984293da51)

As we can see, there are only two combinations with a non-zero amplitude. Therefore, these are the possible joint values.

## Flipping One Drink

And now let's do something really interesting.

We're going to flip `yourDrink`, but only when `myDrink` is `t`.

We use a classical function to describe this operation:

```python theme={null}
def conditional_flip(my: str, your: str) -> tuple[str, str]:
    if my == 't':
        return my, ('t' if your == 'm' else 'm')
    return my, your
```

This function looks at the two classical values on each branch. If `myDrink` is `t`, it flips `yourDrink`, and if `myDrink` is `m`, it leaves `yourDrink` unchanged.

We now apply this operation to the joint value:

```python theme={null}
flip(conditional_flip, myDrink, yourDrink)
```

The important thing to notice is that `flip()` swaps amplitudes between paired joint values. For this operation, the relevant values form reversible pairs.

In our example, `('t', 'm')` and `('t', 't')` form such a pair. Before the flip, the branch `('t', 'm')` has amplitude $\frac{1}{\sqrt{2}}$, while `('t', 't')` has amplitude `0`. We can imagine that `('t', 't')` has been there all along, but only with amplitude `0`. The `flip()` exchanges these amplitudes.

So, `('t', 'm')` now has amplitude `0`, while `('t', 't')` has amplitude $\frac{1}{\sqrt{2}}$. The `('m', 'm')` branch remains unchanged.

Our function does not map every possible character combination back and forth. For example, both `('t', 't')` and `('t', 'k')` map to `('t', 'm')`. This does not cause a problem here because `('t', 'k')` is not a relevant joint value: it has amplitude `0`. What matters is that the relevant pair `('t', 'm')` and `('t', 't')` maps back and forth consistently.

Let's look at the joint amplitudes in the debugger.

![Debugger showing joint amplitudes after the flip](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_flip_myDrink.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=4a2b062d2d197df18d710e8516c16fb9)

![Debugger showing joint amplitudes after the flip](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_flip_yourDrink.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=736dd394d931cc0459269d673704fea1)

## What Is Entanglement?

Notice that the values of `myDrink` and `yourDrink` are now correlated.

The values are no longer independent. The value of one is connected to the value of the other.

This is called **entanglement**.

The important point is that the relationship between the two values is contained in the **joint amplitudes**.

We can no longer describe `myDrink` and `yourDrink` as independent quantum values.

Instead, we describe the possible combinations of the two values together.

## Observing the Entangled Values

Let's now observe `myDrink`.

There is a 50% chance that `myDrink` is observed as `m`, because the total probability of the branches containing `m` as the first character is one-half.

For similar reasons, there is a 50% chance of the outcome `t`.

As a reminder, the probability is just the absolute square of the amplitude.

And now, let's see the outcome.

```python theme={null}
myDrink.observe()

print(myDrink)
print(yourDrink)
```

The debugger now shows the result.

![Debugger showing myDrink and yourDrink after observation](https://mintcdn.com/rhyme-q/JlURJlNdnA85HOaP/images/basic-tutorials/entanglement_observe.png?fit=max\&auto=format\&n=JlURJlNdnA85HOaP\&q=85\&s=9e637d0f80b54b290f94a56bc27ee4fa)

Here, `myDrink` collapses to `m`.

Since only the branch containing `m` remains, the value of `yourDrink` is also `m`.

Both values now have definite classical values, and the simulator no longer treats them as a quantum superposition.

## A Simple Coordination Task

This gives us a simple example of coordination.

Imagine I am on Earth, and you are on the moon.

When we observe our entangled variables, we get random results, but the results always follow the same relationship.

So, if I get `m`, you get `m` as well.

If I get `t`, you get `t` as well.

It doesn't matter who observes first. Once one value is observed, the other value is determined by the relationship between them.

*That's the basic idea of entanglement.*

**And that's how you implemented Entanglement in Rhyme!**


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