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

# 4. Quantum counterparts of Python types

This part of Rhyme provides quantum counterparts of Python's built-in `int`, `float`, `str`, and `bool` types. Their **basis values** are ordinary Python values, but each quantum object can hold a superposition of several such values.

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.

## 4.1 `qint`: signed quantum integers

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

qint(*i: int, size: int = 0, name: str = "")
```

A `qint` holds a superposition of **signed integers**.

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

`size` is a **bit-width assertion**, not a conversion or an instruction to truncate integers. For example, `size=8` asserts that only signed integers representable using 8 bits (that is, in the range `-128` to `127`) 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}
qint.get_limits(size: int) -> tuple[int, int]
qint.all(*, size: int = 0, name: str = "") -> qint
```

```python theme={null}
print(qint.get_limits(8))  # (-128, 127)
x = qint.all(size=2)  # Uniform superposition of -2, -1, 0, 1
```

### Fixed-width shortcuts

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

| Function | Equivalent construction |
| - | - |
| `qint8(*i, name="")` | `qint(*i, size=8, name=name)` |
| `qint16(*i, name="")` | `qint(*i, size=16, name=name)` |
| `qint32(*i, name="")` | `qint(*i, size=32, name=name)` |
| `qint64(*i, name="")` | `qint(*i, size=64, name=name)` |

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

x = qint8(-3, 7)
```

### Binary helper functions

`qint` supports `bit_pair()`, `bit_lr()`, and `bit_rot_angle()` using the **two's complement binary representation** of signed integers. Bit index `0` is the least-significant bit. When `size > 0`, the highest bit is the sign 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.

## 4.2 `qfloat`: quantum floating-point numbers

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

qfloat(*f: float, size: int = 0, name: str = "")
```

A `qfloat` holds a superposition of **IEEE 754 floating-point values**.

```python theme={null}
x = qfloat(0.5, 1.25)  # Uniform superposition of 0.5 and 1.25
zero = qfloat()  # Holds 0.0 with amplitude 1
half = qfloat(1.5, size=16)
```

`size` is a **width assertion**. For example, `size=16` asserts that only half-precision floating-point numbers may occur as basis values of this object. If the assertion is violated, the behavior is undefined.

Rhyme supports the following `size` values:

* `size=16`: half-precision floating point.
* `size=32`: single-precision floating point.
* `size=64`: double-precision floating point.
* `size=0`: the precision of Python's `float` type.

The following are **not valid basis values** for qfloat:

* NaN (not a number).
* Negative zero (`-0.0`).

Positive and negative infinity are allowed.

As with `qint`, a `size` assertion does **not** silently round or convert invalid basis values.

### Fixed-precision shortcuts

| Function | Equivalent construction |
| - | - |
| `qfloat16(*f, name="")` | `qfloat(*f, size=16, name=name)` |
| `qfloat32(*f, name="")` | `qfloat(*f, size=32, name=name)` |
| `qfloat64(*f, name="")` | `qfloat(*f, size=64, name=name)` |

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

x = qfloat32(0.25, 0.75)
```

Unlike `qint`, `qfloat` does not declare an `all()` override.

### Binary helper functions

Currently, `qfloat` does not support `bit_pair()`, `bit_lr()`, or `bit_rot_angle()`. Calling these methods raises `RhymeError` in the simulator.

## 4.3 `qstr`: quantum strings

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

qstr(*s: str, size: int = 0, ascii_only: bool = False, name: str = "")
```

A `qstr` holds a superposition of Python **strings**.

```python theme={null}
mood = qstr("happy", "sad")
empty = qstr()  # Holds "" with amplitude 1
short = qstr("cat", "dog", size=3)
ascii_text = qstr("yes", "no", ascii_only=True)
```

* `size` is a **maximum-length assertion**, measured in characters. With `size=10`, each basis value may have up to 10 characters; it need not have exactly 10.
* `size=0` permits unrestricted string length.
* `ascii_only=True` asserts that all characters belong to ASCII; its default is `False`, allowing Unicode.
* **Strings ending in `chr(0)` are not allowed** as basis values.
* Violating an assertion leads to undefined behavior.

A `qstr` starts at the empty string `""` when no initial value is given.

You can also request a uniform superposition over the valid string domain:

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

Currently, `qstr.all()` supports only ASCII strings (`ascii_only=True`) and requires `size > 0`.

### `qascii`: ASCII-only strings

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

qascii(*s: str, size: int = 0, name: str = "") -> qstr
```

`qascii` is a convenience function, equivalent to `qstr(*s, size=size, ascii_only=True, name=name)`.

```python theme={null}
word = qascii("yes", "no", size=3)
```

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

### Binary helper functions

`qstr` supports `bit_pair()`, `bit_lr()`, and `bit_rot_angle()` only when `ascii_only=True`. Each character is represented using **7 bits**, with bit indices increasing from the first character to the last. Thus, bits `0`–`6` belong to the first character, bits `7`–`13` to the second, and so on.

Missing characters are treated as `chr(0)` (all zero bits). Flipping a bit can therefore extend or shorten a string. Trailing `chr(0)` characters are removed from the result, ensuring that the string remains in its canonical representation.

For example:

```python theme={null}
word = qstr("A", ascii_only=True)
pair = word.bit_pair(13)  # Returns a function to flip the highest bit of the second character

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

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.

Using these helpers with a `qstr` where `ascii_only=False` results in undefined behavior.

## 4.4 `qbool`: quantum booleans

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

qbool(*b: bool, name: str = "")
```

A `qbool` holds a superposition of `False` and `True`.

```python theme={null}
flag = qbool(False, True)
zero = qbool()  # Holds False with amplitude 1
both = qbool.all()  # Uniform superposition of False and True
```

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

```python theme={null}
flag.interfere()  # Uses the default False/True pair
flag.rotate(angle)  # Rotates the pair's amplitudes
flag.flip()  # Exchanges False and True amplitudes
```

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

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

flag.add_phase(lambda b: pi if b else 0.0)
# Or, equivalently:
flag.add_phase(0.0, pi)  # Angle for False, then angle for True
```

`qbool` 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 |
| - | - |
| `qbool.pairFT(b)` | Pair `False` with `True`. |
| `qbool.lrF(b)` | Return `True` exactly when `b` is `False`. |
| `qbool.lrT(b)` | Return `True` exactly when `b` is `True`. |

### Binary helper functions

`qbool` supports `bit_pair()`, `bit_lr()`, and `bit_rot_angle()` for its single bit, with index `0`. The helpers pair `False` with `True`, identify `False` as the "left" value, and select `angle_0` or `angle_1` according to the boolean value.

These helpers do not accept control-bit arguments.

## 4.5 `superpose`: a convenient constructor

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

superpose(t, *rest, size=0, ascii_only=False, name="")
```

`superpose()` is a convenience function for creating a quantum superposition from ordinary Python values, without explicitly naming a quantum type. The type of the first argument determines which quantum type is created:

* `int` → `qint`
* `float` → `qfloat`
* `str` → `qstr`
* `bool` → `qbool`

For example:

```python theme={null}
choice = superpose("red", "blue", name="color")  # Creates a qstr
number = superpose(5, 6, size=8)  # Creates a qint

result = choice.observe()  # Either "red" or "blue"
```

At least one basis value must be supplied, and all supplied values must be valid for the selected quantum type. Other Python types are not supported.

The `size` parameter applies to `qint`, `qfloat`, and `qstr`, while `ascii_only` applies only to `qstr`. The `name` parameter is supported by all four types. These parameters have the same meaning as in the corresponding constructors.

## 4.6 Common behavior

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

`x.observe()` returns a Python `int` for `qint`, a `float` for `qfloat`, a `str` for `qstr`, and a `bool` for `qbool`. It also collapses the quantum value.


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