qubosolver.bitstring

qubosolver.Bitstring module-attribute

Bitstring: TypeAlias = jaxtyping.Int8[torch.Tensor, 'n']

1-D int8 tensor of shape (n,) representing a single bitstring of 0s and 1s.

qubosolver.bitstring

Bitstring utilities for QUBO solvers.

A Bitstring is a 1-D torch.int8 tensor whose elements are 0 or 1. This module provides factory functions and converters for creating and manipulating bitstrings on the globally configured torch device.

Typical usage:

bs = bitstring.from_string("1010")
s  = bitstring.to_string(bs)        # "1010"
z  = bitstring.zeros(4)             # tensor([0, 0, 0, 0], dtype=torch.int8)
f  = bitstring.round([1.0, 0.0, 0.9999999])         # from a MIP solver's output

Functions:

• as_tensor –

  Convenience wrapper for torch.as_tensor that converts data to a bitstring tensor.

• device –

  Returns the globally configured torch device.

• dtype –

  Returns the dtype used for bitstrings (torch.int8).

• from_string –

  Creates a bitstring tensor from a string of '0' and '1' characters.

• rand –

  Creates a bitstring of length n with independent uniformly random bits.

• round –

  Rounds near-integral float values to a bitstring tensor.

• tensor –

  Creates a bitstring tensor from the given data.

• to_string –

  Converts a bitstring tensor to its string representation.

• zeros –

  Creates a zero-filled bitstring of length n.

• zeros_field –

  Creates a dataclass field defaulting to a zero-filled bitstring.

as_tensor

as_tensor(data: Any) ->             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring

Convenience wrapper for torch.as_tensor that converts data to a bitstring tensor.

Avoids a copy when possible. If data is already a tensor with the right dtype and on the right device, it is returned as-is, sharing the same underlying memory. A numpy array is also shared rather than copied if it already has int8 dtype and the global device is cpu (numpy arrays only live on CPU, so any other dtype or device forces a copy). Lists, tuples, and other array-like inputs are always copied.

Parameters:

• data (Any (external)) –

  Input data (tensor, numpy array, list, tuple, etc.).

Returns:

• Bitstring –

  A 1-D int8 tensor on the global device.

Source code in qubosolver/types/bitstring.py

def as_tensor(data: Any) -> Bitstring:  # noqa: ANN401 (array-like input forwarded to torch.as_tensor)
    """Convenience wrapper for `torch.as_tensor` that converts data to a bitstring tensor.

    Avoids a copy when possible. If *data* is already a tensor with the right dtype and on
    the right device, it is returned as-is, sharing the same underlying memory. A numpy
    array is also shared rather than copied if it already has ``int8`` dtype and the global
    device is ``cpu`` (numpy arrays only live on CPU, so any other dtype or device forces a
    copy). Lists, tuples, and other array-like inputs are always copied.

    Args:
        data: Input data (tensor, numpy array, list, tuple, etc.).

    Returns:
        A 1-D ``int8`` tensor on the global device.
    """
    return torch.as_tensor(data, dtype=dtype(), device=device())

device

device() -> torch.device

Returns the globally configured torch device.

Source code in qubosolver/types/bitstring.py

def device() -> torch.device:
    """Returns the globally configured torch device."""
    return bitstrings.device()

dtype

dtype() -> torch.dtype

Returns the dtype used for bitstrings (torch.int8).

Source code in qubosolver/types/bitstring.py

def dtype() -> torch.dtype:
    """Returns the dtype used for bitstrings (``torch.int8``)."""
    return bitstrings.dtype()

from_string

from_string(s: str, *, device: torch.device | None = None) ->             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring

Creates a bitstring tensor from a string of '0' and '1' characters.

Parameters:

• s (str (external)) –

  A string consisting of '0' and '1' characters.

• device (torch (external).device (external) | None, default: None ) –

  Torch device for the tensor.

Returns:

• Bitstring –

  A 1-D int8 tensor.

Source code in qubosolver/types/bitstring.py

def from_string(s: str, *, device: torch.device | None = None) -> Bitstring:
    """Creates a bitstring tensor from a string of '0' and '1' characters.

    Args:
        s: A string consisting of '0' and '1' characters.
        device: Torch device for the tensor.

    Returns:
        A 1-D ``int8`` tensor.
    """
    device = device or _device()
    return bitstrings.from_strings([s], device=device)[0]

rand

rand(n: int, *, device: torch.device | None = None, rng: torch.Generator | None = None) ->             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring

Creates a bitstring of length n with independent uniformly random bits.

Parameters:

• n (int (external)) –

  Length of the bitstring.

• device (torch (external).device (external) | None, default: None ) –

  Torch device for the tensor.

• rng (torch (external).Generator (external) | None, default: None ) –

  PyTorch random number generator controlling the sampling.

Returns:

• Bitstring –

  A 1-D int8 tensor of 0s and 1s.

Source code in qubosolver/types/bitstring.py

def rand(
    n: int, *, device: torch.device | None = None, rng: torch.Generator | None = None
) -> Bitstring:
    """Creates a bitstring of length *n* with independent uniformly random bits.

    Args:
        n: Length of the bitstring.
        device: Torch device for the tensor.
        rng: PyTorch random number generator controlling the sampling.

    Returns:
        A 1-D ``int8`` tensor of 0s and 1s.
    """
    device = device or _device()
    rng = rng or torch_rng()
    return torch.randint(0, 2, (n,), generator=rng, device=device, dtype=dtype())

round

round(data: Any, *, atol: float = 1e-06, device: torch.device | None = None) ->             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring

Rounds near-integral float values to a bitstring tensor.

Values are compared in float64 regardless of the globally configured float dtype, so atol keeps its meaning even when the global dtype is narrower (e.g. float32, which would round 0.9999999998 to exactly 1.0 before the check could see it).

Parameters:

• data (Any (external)) –

  Input data (tensor, numpy array, list, etc.) of floats, each within atol of 0 or 1.

• atol (float (external), default: 1e-06 ) –

  Maximum absolute distance from 0 or 1 tolerated before raising.

• device (torch (external).device (external) | None, default: None ) –

  Torch device for the tensor.

Returns:

• Bitstring –

  A 1-D int8 tensor of 0s and 1s.

Raises:

• ValueError (external) –

  If any value is further than atol from both 0 and 1.

Source code in qubosolver/types/bitstring.py

def round(
    data: Any,  # noqa: ANN401 (array-like input forwarded to torch.as_tensor)
    *,
    atol: float = 1e-6,
    device: torch.device | None = None,
) -> Bitstring:
    """Rounds near-integral float values to a bitstring tensor.

    Values are compared in ``float64`` regardless of the globally configured
    float dtype, so *atol* keeps its meaning even when the global dtype is
    narrower (e.g. ``float32``, which would round ``0.9999999998`` to exactly
    ``1.0`` before the check could see it).

    Args:
        data: Input data (tensor, numpy array, list, etc.) of floats, each
            within *atol* of 0 or 1.
        atol: Maximum absolute distance from 0 or 1 tolerated before raising.
        device: Torch device for the tensor.

    Returns:
        A 1-D ``int8`` tensor of 0s and 1s.

    Raises:
        ValueError: If any value is further than *atol* from both 0 and 1.
    """
    device = device or _device()
    values = torch.as_tensor(data, dtype=torch.float64)
    return bitstrings.round(values.unsqueeze(0), atol=atol, device=device)[0]

tensor

tensor(data: Any, *, device: torch.device | None = None, **kwargs: Any) ->             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring

Creates a bitstring tensor from the given data.

Parameters:

• data (Any (external)) –

  Input data (list, tuple, or array-like of 0s and 1s).

• device (torch (external).device (external) | None, default: None ) –

  Torch device for the tensor.

• **kwargs (Any (external), default: {} ) –

  Extra keyword arguments forwarded to torch.tensor.

Returns:

• Bitstring –

  A 1-D int8 tensor.

Source code in qubosolver/types/bitstring.py

def tensor(
    data: Any,  # noqa: ANN401 (array-like input forwarded to torch.tensor)
    *,
    device: torch.device | None = None,
    **kwargs: Any,  # noqa: ANN401 (forwarded to torch.tensor)
) -> Bitstring:
    """Creates a bitstring tensor from the given data.

    Args:
        data: Input data (list, tuple, or array-like of 0s and 1s).
        device: Torch device for the tensor.
        **kwargs: Extra keyword arguments forwarded to `torch.tensor`.

    Returns:
        A 1-D ``int8`` tensor.
    """
    device = device or _device()
    return torch.tensor(data, dtype=dtype(), device=device, **kwargs)

to_string

to_string(bitstring:             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring) -> str

Converts a bitstring tensor to its string representation.

Parameters:

• bitstring (Bitstring) –

  A 1-D int8 tensor of 0s and 1s.

Returns:

• str (external) –

  A string of '0' and '1' characters.

Source code in qubosolver/types/bitstring.py

def to_string(bitstring: Bitstring) -> str:
    """Converts a bitstring tensor to its string representation.

    Args:
        bitstring: A 1-D ``int8`` tensor of 0s and 1s.

    Returns:
        A string of '0' and '1' characters.
    """
    return bitstrings.to_strings(bitstring.flatten().unsqueeze(0))[0]

zeros

zeros(n: int, *, device: torch.device | None = None) ->             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring

Creates a zero-filled bitstring of length n.

Parameters:

• n (int (external)) –

  Length of the bitstring.

• device (torch (external).device (external) | None, default: None ) –

  Torch device for the tensor.

Returns:

• Bitstring –

  A 1-D int8 tensor of zeros.

Source code in qubosolver/types/bitstring.py

def zeros(n: int, *, device: torch.device | None = None) -> Bitstring:
    """Creates a zero-filled bitstring of length *n*.

    Args:
        n: Length of the bitstring.
        device: Torch device for the tensor.

    Returns:
        A 1-D ``int8`` tensor of zeros.
    """
    device = device or _device()
    return torch.zeros(n, dtype=dtype(), device=device)

zeros_field

zeros_field(n: int, *, device: torch.device | None = None) ->             qubosolver.Bitstring



      module-attribute
   (qubosolver.types.linalg.Bitstring)" href="#qubosolver.Bitstring">Bitstring

Creates a dataclass field defaulting to a zero-filled bitstring.

Parameters:

• n (int (external)) –

  Length of the bitstring.

• device (torch (external).device (external) | None, default: None ) –

  Torch device for the tensor.

Returns:

• Bitstring –

  A dataclass field (typed as Bitstring for the enclosing class) whose

• Bitstring –

  default_factory builds a fresh zero tensor per instance.

Source code in qubosolver/types/bitstring.py

@no_runtime_typecheck
def zeros_field(n: int, *, device: torch.device | None = None) -> Bitstring:
    """Creates a dataclass field defaulting to a zero-filled bitstring.

    Args:
        n: Length of the bitstring.
        device: Torch device for the tensor.

    Returns:
        A dataclass field (typed as `Bitstring` for the enclosing class) whose
        `default_factory` builds a fresh zero tensor per instance.
    """
    return field(default_factory=lambda: zeros(n, device=device))