State preparation

State Preparation Routines

ghz_block(n_qubits)

Generates the abstract ghz state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int

RETURNS	DESCRIPTION
ChainBlock	A ChainBlock representing the GHZ state.

Examples:

from qadence.states import ghz_block

block = ghz_block(n_qubits=2)
print(block)

ChainBlock(0,1)
├── H(0)
└── ChainBlock(0,1)
    └── CNOT(0, 1)

Source code in qadence/states.py

def ghz_block(n_qubits: int) -> ChainBlock:
    """
    Generates the abstract ghz state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits.

    Returns:
        A ChainBlock representing the GHZ state.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import ghz_block

    block = ghz_block(n_qubits=2)
    print(block)
    ```
    """
    cnots = chain(CNOT(i - 1, i) for i in range(1, n_qubits))
    return chain(H(0), cnots)

ghz_state(n_qubits, batch_size=1)

Creates a GHZ state.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int
batch_size	How many bitstrings to use. TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
Tensor	A torch.Tensor.

Examples:

from qadence.states import ghz_state

print(ghz_state(n_qubits=2, batch_size=2))

tensor([[0.7071+0.j, 0.0000+0.j, 0.0000+0.j, 0.7071+0.j],
        [0.7071+0.j, 0.0000+0.j, 0.0000+0.j, 0.7071+0.j]])

Source code in qadence/states.py

def ghz_state(n_qubits: int, batch_size: int = 1) -> Tensor:
    """
    Creates a GHZ state.

    Arguments:
        n_qubits (int): The number of qubits.
        batch_size (int): How many bitstrings to use.

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import ghz_state

    print(ghz_state(n_qubits=2, batch_size=2))
    ```
    """
    norm = 1 / torch.sqrt(torch.tensor(2))
    return norm * (zero_state(n_qubits, batch_size) + one_state(n_qubits, batch_size))

is_normalized(wf, atol=NORMALIZATION_ATOL)

Checks if a wave function is normalized.

PARAMETER	DESCRIPTION
wf	The wave function as a torch tensor. TYPE: Tensor
atol	The tolerance. TYPE: float) DEFAULT: NORMALIZATION_ATOL

RETURNS	DESCRIPTION
bool	A bool.

Examples:

from qadence.states import uniform_state, is_normalized

print(is_normalized(uniform_state(2)))

True

Source code in qadence/states.py

def is_normalized(wf: Tensor, atol: float = NORMALIZATION_ATOL) -> bool:
    """
    Checks if a wave function is normalized.

    Arguments:
        wf (torch.Tensor): The wave function as a torch tensor.
        atol (float) : The tolerance.

    Returns:
        A bool.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import uniform_state, is_normalized

    print(is_normalized(uniform_state(2)))
    ```
    """
    if wf.dim() == 1:
        wf = wf.unsqueeze(0)
    sum_probs: Tensor = (wf.abs() ** 2).sum(dim=1)
    ones = torch.ones_like(sum_probs)
    return torch.allclose(sum_probs, ones, rtol=0.0, atol=atol)  # type: ignore[no-any-return]

normalize(wf)

Normalizes a wavefunction or batch of wave functions.

PARAMETER	DESCRIPTION
wf	Normalized wavefunctions. TYPE: Tensor

RETURNS	DESCRIPTION
Tensor	A torch.Tensor.

Examples:

from qadence.states import uniform_state, normalize

print(normalize(uniform_state(2, 2)))

tensor([[0.5000+0.j, 0.5000+0.j, 0.5000+0.j, 0.5000+0.j],
        [0.5000+0.j, 0.5000+0.j, 0.5000+0.j, 0.5000+0.j]])

Source code in qadence/states.py

def normalize(wf: Tensor) -> Tensor:
    """
    Normalizes a wavefunction or batch of wave functions.

    Arguments:
        wf (torch.Tensor): Normalized wavefunctions.

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import uniform_state, normalize

    print(normalize(uniform_state(2, 2)))
    ```
    """
    if wf.dim() == 1:
        return wf / torch.sqrt((wf.abs() ** 2).sum())
    else:
        return wf / torch.sqrt((wf.abs() ** 2).sum(1)).unsqueeze(1)

one_block(n_qubits)

Generates the abstract one state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int

RETURNS	DESCRIPTION
KronBlock	A KronBlock representing the one state.

Examples:

from qadence.states import one_block

block = one_block(n_qubits=2)
print(block)

KronBlock(0,1)
├── X(0)
└── X(1)

Source code in qadence/states.py

def one_block(n_qubits: int) -> KronBlock:
    """
    Generates the abstract one state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits.

    Returns:
        A KronBlock representing the one state.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import one_block

    block = one_block(n_qubits=2)
    print(block)
    ```
    """
    return _from_op(X, n_qubits=n_qubits)

one_state(n_qubits, batch_size=1)

Generates the one state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int
batch_size	The batch size. TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
Tensor	A torch.Tensor.

Examples:

from qadence.states import one_state

state = one_state(n_qubits=2)
print(state)

tensor([[0.+0.j, 0.+0.j, 0.+0.j, 1.+0.j]])

Source code in qadence/states.py

def one_state(n_qubits: int, batch_size: int = 1) -> Tensor:
    """
    Generates the one state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits.
        batch_size (int): The batch size.

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import one_state

    state = one_state(n_qubits=2)
    print(state)
    ```
    """
    bitstring = "1" * n_qubits
    return _state_from_bitstring(bitstring, batch_size)

pmf(wf)

Converts a wave function into a torch Distribution.

PARAMETER	DESCRIPTION
wf	The wave function as a torch tensor. TYPE: Tensor

RETURNS	DESCRIPTION
Distribution	A torch.distributions.Distribution.

Examples:

from qadence.states import uniform_state, pmf

print(pmf(uniform_state(2)).probs)

tensor([[0.2500, 0.2500, 0.2500, 0.2500]])

Source code in qadence/states.py

def pmf(wf: Tensor) -> Distribution:
    """
    Converts a wave function into a torch Distribution.

    Arguments:
        wf (torch.Tensor): The wave function as a torch tensor.

    Returns:
        A torch.distributions.Distribution.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import uniform_state, pmf

    print(pmf(uniform_state(2)).probs)
    ```
    """
    return Categorical(torch.abs(torch.pow(wf, 2)))

product_block(bitstring)

Creates an abstract product state from a bitstring.

PARAMETER	DESCRIPTION
bitstring	A bitstring. TYPE: str

RETURNS	DESCRIPTION
KronBlock	A KronBlock representing the product state.

Examples:

from qadence.states import product_block

print(product_block("1100"))

KronBlock(0,1,2,3)
├── X(0)
├── X(1)
├── I(2)
└── I(3)

Source code in qadence/states.py

def product_block(bitstring: str) -> KronBlock:
    """
    Creates an abstract product state from a bitstring.

    Arguments:
        bitstring (str): A bitstring.

    Returns:
        A KronBlock representing the product state.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import product_block

    print(product_block("1100"))
    ```
    """
    return _block_from_bitstring(bitstring)

product_state(bitstring, batch_size=1, endianness=Endianness.BIG, backend=BackendName.PYQTORCH)

Creates a product state from a bitstring.

PARAMETER	DESCRIPTION
bitstring	A bitstring. TYPE: str
batch_size	Batch size. TYPE: int) DEFAULT: 1
backend	The backend to use. Default is "pyqtorch". TYPE: BackendName DEFAULT: PYQTORCH

RETURNS	DESCRIPTION
ArrayLike	A torch.Tensor.

Examples:

from qadence.states import product_state

print(product_state("1100", backend="pyqtorch"))
print(product_state("1100", backend="horqrux"))

tensor([[0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j,
         1.+0.j, 0.+0.j, 0.+0.j, 0.+0.j]])
[0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j
 0.+0.j 0.+0.j 1.+0.j 0.+0.j 0.+0.j 0.+0.j]

Source code in qadence/states.py

@singledispatch
def product_state(
    bitstring: str,
    batch_size: int = 1,
    endianness: Endianness = Endianness.BIG,
    backend: BackendName = BackendName.PYQTORCH,
) -> ArrayLike:
    """
    Creates a product state from a bitstring.

    Arguments:
        bitstring (str): A bitstring.
        batch_size (int) : Batch size.
        backend (BackendName): The backend to use. Default is "pyqtorch".

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import product_state

    print(product_state("1100", backend="pyqtorch"))
    print(product_state("1100", backend="horqrux"))
    ```
    """
    if batch_size:
        logger.debug(
            "The input `batch_size` is going to be deprecated. "
            "For now, default batch_size is set to 1."
        )
    return run(product_block(bitstring), backend=backend, endianness=endianness)

rand_bitstring(N)

Creates a random bistring.

PARAMETER	DESCRIPTION
N	The length of the bitstring. TYPE: int

RETURNS	DESCRIPTION
str	A string.

Examples:

from qadence.states import rand_bitstring

print(rand_bitstring(N=8))

01100001

Source code in qadence/states.py

def rand_bitstring(N: int) -> str:
    """
    Creates a random bistring.

    Arguments:
        N (int): The length of the bitstring.

    Returns:
        A string.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import rand_bitstring

    print(rand_bitstring(N=8))
    ```
    """
    return "".join(str(random.randint(0, 1)) for _ in range(N))

rand_product_block(n_qubits)

Creates a block representing a random abstract product state.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int

RETURNS	DESCRIPTION
KronBlock	A KronBlock representing the product state.

Examples:

from qadence.states import rand_product_block

print(rand_product_block(n_qubits=2))

KronBlock(0,1)
├── I(0)
└── X(1)

Source code in qadence/states.py

def rand_product_block(n_qubits: int) -> KronBlock:
    """
    Creates a block representing a random abstract product state.

    Arguments:
        n_qubits (int): The number of qubits.

    Returns:
        A KronBlock representing the product state.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import rand_product_block

    print(rand_product_block(n_qubits=2))
    ```
    """
    return product_block(rand_bitstring(n_qubits))

rand_product_state(n_qubits, batch_size=1)

Creates a random product state.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int
batch_size	How many bitstrings to use. TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
Tensor	A torch.Tensor.

Examples:

from qadence.states import rand_product_state

print(rand_product_state(n_qubits=2, batch_size=2))

tensor([[0.+0.j, 0.+0.j, 1.+0.j, 0.+0.j],
        [0.+0.j, 0.+0.j, 1.+0.j, 0.+0.j]])

Source code in qadence/states.py

def rand_product_state(n_qubits: int, batch_size: int = 1) -> Tensor:
    """
    Creates a random product state.

    Arguments:
        n_qubits (int): The number of qubits.
        batch_size (int): How many bitstrings to use.

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import rand_product_state

    print(rand_product_state(n_qubits=2, batch_size=2))
    ```
    """
    wf_batch = torch.zeros(batch_size, 2**n_qubits, dtype=DTYPE)
    rand_pos = torch.randint(0, 2**n_qubits, (batch_size,))
    wf_batch[torch.arange(batch_size), rand_pos] = torch.tensor(1.0 + 0j, dtype=DTYPE)
    return wf_batch

random_state(n_qubits, batch_size=1, backend=BackendName.PYQTORCH, type=StateGeneratorType.HAAR_MEASURE_FAST)

Generates a random state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int
backend	The backend to use. TYPE: str DEFAULT: PYQTORCH
batch_size	The batch size. TYPE: int DEFAULT: 1
type	StateGeneratorType. DEFAULT: HAAR_MEASURE_FAST

RETURNS	DESCRIPTION
Tensor	A torch.Tensor.

Examples:

from qadence.states import random_state, StateGeneratorType
from qadence.states import random_state, is_normalized, pmf
from qadence.types import BackendName
from torch.distributions import Distribution

### We have the following options:
print([g.value for g in StateGeneratorType])

n_qubits = 2
# The default is StateGeneratorType.HAAR_MEASURE_FAST
state = random_state(n_qubits=n_qubits)
print(state)

### Lets initialize a state using random rotations, i.e., StateGeneratorType.RANDOM_ROTATIONS.
random = random_state(n_qubits=n_qubits, type=StateGeneratorType.RANDOM_ROTATIONS)
print(random)

['RandomRotations', 'HaarMeasureFast', 'HaarMeasureSlow']
tensor([[-0.2724+0.3132j, -0.5618+0.0106j, -0.2809-0.4559j,  0.3893+0.2713j]])
tensor([[0.6271+0.7789j, 0.0000+0.0000j, 0.0000+0.0000j, 0.0000+0.0000j]])

Source code in qadence/states.py

def random_state(
    n_qubits: int,
    batch_size: int = 1,
    backend: str = BackendName.PYQTORCH,
    type: StateGeneratorType = StateGeneratorType.HAAR_MEASURE_FAST,
) -> Tensor:
    """
    Generates a random state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits.
        backend (str): The backend to use.
        batch_size (int): The batch size.
        type : StateGeneratorType.

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import random_state, StateGeneratorType
    from qadence.states import random_state, is_normalized, pmf
    from qadence.types import BackendName
    from torch.distributions import Distribution

    ### We have the following options:
    print([g.value for g in StateGeneratorType])

    n_qubits = 2
    # The default is StateGeneratorType.HAAR_MEASURE_FAST
    state = random_state(n_qubits=n_qubits)
    print(state)

    ### Lets initialize a state using random rotations, i.e., StateGeneratorType.RANDOM_ROTATIONS.
    random = random_state(n_qubits=n_qubits, type=StateGeneratorType.RANDOM_ROTATIONS)
    print(random)
    ```
    """

    if type == StateGeneratorType.HAAR_MEASURE_FAST:
        state = concat(tuple(_rand_haar_fast(n_qubits) for _ in range(batch_size)), dim=0)
    elif type == StateGeneratorType.HAAR_MEASURE_SLOW:
        state = concat(tuple(_rand_haar_slow(n_qubits) for _ in range(batch_size)), dim=0)
    elif type == StateGeneratorType.RANDOM_ROTATIONS:
        state = run(_abstract_random_state(n_qubits, batch_size))  # type: ignore
    assert all(list(map(is_normalized, state)))
    return state

uniform_block(n_qubits)

Generates the abstract uniform state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int

RETURNS	DESCRIPTION
KronBlock	A KronBlock representing the uniform state.

Examples:

from qadence.states import uniform_block

block = uniform_block(n_qubits=2)
print(block)

KronBlock(0,1)
├── H(0)
└── H(1)

Source code in qadence/states.py

def uniform_block(n_qubits: int) -> KronBlock:
    """
    Generates the abstract uniform state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits.

    Returns:
        A KronBlock representing the uniform state.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import uniform_block

    block = uniform_block(n_qubits=2)
    print(block)
    ```
    """
    return _from_op(H, n_qubits=n_qubits)

uniform_state(n_qubits, batch_size=1)

Generates the uniform state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int
batch_size	The batch size. TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
Tensor	A torch.Tensor.

Examples:

from qadence.states import uniform_state

state = uniform_state(n_qubits=2)
print(state)

tensor([[0.5000+0.j, 0.5000+0.j, 0.5000+0.j, 0.5000+0.j]])

Source code in qadence/states.py

def uniform_state(n_qubits: int, batch_size: int = 1) -> Tensor:
    """
    Generates the uniform state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits.
        batch_size (int): The batch size.

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import uniform_state

    state = uniform_state(n_qubits=2)
    print(state)
    ```
    """
    norm = 1 / torch.sqrt(torch.tensor(2**n_qubits))
    return norm * torch.ones(batch_size, 2**n_qubits, dtype=DTYPE)

zero_block(n_qubits)

Generates the abstract zero state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits. TYPE: int

RETURNS	DESCRIPTION
KronBlock	A KronBlock representing the zero state.

Examples:

from qadence.states import zero_block

block = zero_block(n_qubits=2)
print(block)

KronBlock(0,1)
├── I(0)
└── I(1)

Source code in qadence/states.py

def zero_block(n_qubits: int) -> KronBlock:
    """
    Generates the abstract zero state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits.

    Returns:
        A KronBlock representing the zero state.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import zero_block

    block = zero_block(n_qubits=2)
    print(block)
    ```
    """
    return _from_op(I, n_qubits=n_qubits)

zero_state(n_qubits, batch_size=1)

Generates the zero state for a specified number of qubits.

PARAMETER	DESCRIPTION
n_qubits	The number of qubits for which the zero state is to be generated. TYPE: int
batch_size	The batch size for the zero state. TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
Tensor	A torch.Tensor.

Examples:

from qadence.states import zero_state

state = zero_state(n_qubits=2)
print(state)

tensor([[1.+0.j, 0.+0.j, 0.+0.j, 0.+0.j]])

Source code in qadence/states.py

def zero_state(n_qubits: int, batch_size: int = 1) -> Tensor:
    """
    Generates the zero state for a specified number of qubits.

    Arguments:
        n_qubits (int): The number of qubits for which the zero state is to be generated.
        batch_size (int): The batch size for the zero state.

    Returns:
        A torch.Tensor.

    Examples:
    ```python exec="on" source="material-block" result="json"
    from qadence.states import zero_state

    state = zero_state(n_qubits=2)
    print(state)
    ```
    """
    bitstring = "0" * n_qubits
    return _state_from_bitstring(bitstring, batch_size)