Skip to main content
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

A qint holds a superposition of signed integers.
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:

Fixed-width shortcuts

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

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, including the handling of control bits where applicable.

4.2 qfloat: quantum floating-point numbers

A qfloat holds a superposition of IEEE 754 floating-point values.
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

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

A qstr holds a superposition of Python strings.
  • 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:
Currently, qstr.all() supports only ASCII strings (ascii_only=True) and requires size > 0.

qascii: ASCII-only strings

qascii is a convenience function, equivalent to qstr(*s, size=size, ascii_only=True, name=name).
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:
All three helpers behave as described in Section 3.4, 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

A qbool holds a superposition of False and True.
Because there are only two possible basis values, qbool provides convenient short forms for several operations:
For phase changes, either pass a function or give two angles, one for each basis value:
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:

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

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