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

# 5. Other quantum types

In addition to the quantum counterparts of Python types described in [Section 4](https://docs.rhymeq.com/language-reference/04-quantum-python-types.md), Rhyme provides quantum types for **unsigned integers, individual bits, and characters**. Their basis values are ordinary Python integers or single-character strings, but each quantum object can hold a superposition of several such values.

As in [Section 4](https://docs.rhymeq.com/language-reference/04-quantum-python-types.md), the constructor arguments specify the values to include in the initial uniform superposition. If no values are given, the object starts at its type's canonical zero value.

## 5.1 `quint`: unsigned quantum integers

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

quint(*u: int, size: int = 0, name: str = "")
```

A `quint` holds a superposition of **non-negative integers**.

```python theme={null}
x = quint(5, 6)  # Uniform superposition of 5 and 6
zero = quint()  # Holds 0 with amplitude 1
bounded = quint(5, size=3)
```

`size` is a **bit-width assertion**, not a conversion or an instruction to truncate integers. For example, `size=3` asserts that only unsigned integers representable using 3 bits (that is, in the range `0` to `7`) may occur as basis values of this object. If the assertion is violated, the behavior is undefined. `size=0` means unrestricted bit width.

Useful class methods:

```python theme={null}
quint.get_limits(size: int) -> tuple[int, int]
quint.all(*, size: int = 0, name: str = "") -> quint
```

```python theme={null}
print(quint.get_limits(8))  # (0, 255)
x = quint.all(size=2)  # Uniform superposition of 0, 1, 2, 3
```

A positive `size` is required when calling `all()`.

### Fixed-width shortcuts

These functions are shortcuts for `quint(..., size=n)`; they return `quint` objects, rather than distinct classes:

| Function | Equivalent construction |
| - | - |
| `quint8(*u, name="")` | `quint(*u, size=8, name=name)` |
| `quint16(*u, name="")` | `quint(*u, size=16, name=name)` |
| `quint32(*u, name="")` | `quint(*u, size=32, name=name)` |
| `quint64(*u, name="")` | `quint(*u, size=64, name=name)` |

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

house_no = quint16(100, 200)
```

### Binary helper functions

`quint` supports `bit_pair()`, `bit_lr()`, and `bit_rot_angle()` using the **standard binary representation** of unsigned integers. Bit index `0` is the least-significant bit.

All three helpers behave as described in [Section 3.4](https://docs.rhymeq.com/language-reference/03-core-of-rhyme.md#3-4-binary-helper-functions), including the handling of control bits where applicable.

## 5.2 `qbit`: a single quantum bit

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

qbit(*b: int, name: str = "")
```

A `qbit` holds a superposition of the integers **`0` and `1`**. It is a specialized `quint` with a fixed bit width of one.

Unlike `qbool`, which uses the Python values `False` and `True`, `qbit` uses integer basis values.

```python theme={null}
zero = qbit()  # Holds 0 with amplitude 1
one = qbit(1)
both = qbit.all()  # Uniform superposition of 0 and 1
```

Because there are only two possible basis values, `qbit` provides convenient **short forms** for several operations:

```python theme={null}
zero.interfere()  # Uses the default 0/1 pair
zero.rotate(angle)  # Rotates the pair's amplitudes
zero.flip()  # Exchanges the amplitudes of 0 and 1
```

For phase changes, either pass a function or give **two angles**, one for each basis value:

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

bit.add_phase(lambda b: pi if b == 1 else 0.0)
# Or, equivalently:
bit.add_phase(0.0, pi)  # Angle for 0, then angle for 1
```

`qbit` also supports `combine(u11, u12, u21, u22)` without an explicit pair or left/right function.

The following static helpers are provided if you want to supply the pair explicitly:

| Helper | Meaning |
| - | - |
| `qbit.pair01(b)` | Pair `0` with `1`. |
| `qbit.lr0(b)` | Return `True` exactly when `b` is `0`. |
| `qbit.lr1(b)` | Return `True` exactly when `b` is `1`. |

For example, `bit.interfere(qbit.pair01, qbit.lr0)` is equivalent to `bit.interfere()`.

### Binary helper functions

As a subclass of `quint`, `qbit` inherits `bit_pair()`, `bit_lr()`, and `bit_rot_angle()`. Only bit index `0` is valid.

The helpers pair `0` with `1`, identify `0` as the "left" value, and select `angle_0` or `angle_1` according to the bit value.

Since there is only one bit, no control bits can be specified.

## 5.3 `qchar`: quantum characters

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

qchar(*c: str, ascii_only: bool = False, name: str = "")
```

A `qchar` holds a superposition of **individual characters**, each represented by a Python string of length one.

```python theme={null}
letter = qchar("A", "B")  # Uniform superposition of "A" and "B"
zero = qchar()  # Holds chr(0) with amplitude 1
ascii_letter = qchar("A", "Z", ascii_only=True)
```

By default, Unicode characters are allowed. The assertion `ascii_only=True` restricts valid basis values to ASCII characters. If the assertion is violated, the behavior is undefined.

Unlike `qstr`, `qchar` allows `chr(0)` as a basis value. This is its canonical zero value, whereas the canonical zero value of `qstr` is the empty string `""`.

You can also request a uniform superposition over all valid characters:

```python theme={null}
qchar.all(*, ascii_only: bool = False, name: str = "") -> qchar
```

Currently, `qchar.all()` supports only ASCII characters (`ascii_only=True`). It creates a uniform superposition over all 128 ASCII characters, including `chr(0)`.

### `qchar7`: ASCII quantum characters

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

qchar7(*c: str, name: str = "") -> qchar
```

`qchar7` is a convenience function, equivalent to `qchar(*c, ascii_only=True, name=name)`. The name `qchar7` refers to the seven-bit ASCII character set.

```python theme={null}
letter = qchar7("A", "B")
```

It returns a `qchar`, not a distinct quantum class.

### Binary helper functions

`qchar` supports `bit_pair()`, `bit_lr()`, and `bit_rot_angle()` only when `ascii_only=True`. Each character is represented using **7 bits**, indexed from `0` (least significant) to `6` (most significant).

The helpers operate on the ASCII code of the character and behave as described in [Section 3.4](https://docs.rhymeq.com/language-reference/03-core-of-rhyme.md#3-4-binary-helper-functions), including the handling of control bits where applicable.

For example:

```python theme={null}
letter = qchar7("A")
pair = letter.bit_pair(0)  # Returns a function to flip the lowest bit

pair("A")  # Returns "@"
pair("@")  # Returns "A"
```

Using these helpers with a non-ASCII `qchar` results in undefined behavior.

## 5.4 Which type should you use?

| Basis values | Quantum type | Example |
| - | - | - |
| Signed integers | `qint` | `qint(-1, 2)` |
| Non-negative integers | `quint` | `quint(1, 2)` |
| One bit, `0` or `1` | `qbit` | `qbit(0, 1)` |
| Floating-point numbers | `qfloat` | `qfloat(0.5, 1.5)` |
| Boolean values | `qbool` | `qbool(False, True)` |
| Individual characters | `qchar` | `qchar("A", "B")` |
| Strings | `qstr` | `qstr("yes", "no")` |

Choose the type according to the **meaning of its basis values**, not merely their binary representation. For example, use `qbit` for the integers `0` and `1`, and `qbool` for the logical values `False` and `True`.

## 5.5 Common behavior

All three classes inherit the `qobject` methods: `observe()`, `measure()`, `add_phase()`, `interfere()`, `flip()`, `rotate()`, `combine()`, `discard()`, and the binary helpers.

`x.observe()` returns a Python `int` for `quint` and `qbit`, and a `str` for `qchar`. It also collapses the quantum value.


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