BloqBuilder#

qualtran.BloqBuilder

A builder class for constructing a CompositeBloq.

qualtran.BloqBuilder(
    add_registers_allowed: bool = True
)

Users may instantiate this class directly or use its methods by overriding Bloq.build_composite_bloq.

When overriding build_composite_bloq, the Bloq class will ensure that the bloq under construction has the correct registers: namely, those of the decomposed bloq and parent bloq are the same. This affords some additional error checking. Initial soquets are passed as **kwargs (by register name) to the build_composite_bloq method.

When using this class directly, you must call add_register to set up the composite bloq’s registers. When adding a LEFT or THRU register, the method will return soquets to be used when adding more bloqs. Adding a THRU or RIGHT register can enable more checks during finalize().

Args

add_registers_allowed

Whether we allow the addition of registers during bloq building. This affords some additional error checking if set to False but you must specify all registers ahead-of-time.

Methods#

add_register_from_dtype

View source

add_register_from_dtype(
    reg: Union[str, qualtran.Register],
    dtype: Optional[qualtran.QCDType] = None
) -> Union[None, qualtran.Soquet]

Add a new typed register to the composite bloq being built.

If this bloq builder was constructed with add_registers_allowed=False, this operation is not allowed.

Args

reg

Either the register or a register name. If this is a register, then bitsize must also be provided and a default THRU register will be added.

dtype

If reg is a register name, this is the quantum data type for the added register. Otherwise, this must not be provided.

Returns

add_register

View source

add_register(
    reg: Union[str, qualtran.Register],
    bitsize: Optional['SymbolicInt'] = None
) -> Union[None, qualtran.Soquet]

Add a new register to the composite bloq being built.

If this bloq builder was constructed with add_registers_allowed=False, this operation is not allowed.

Args

reg

Either the register or a register name. If this is a register name, then bitsize must also be provided and a default THRU register will be added.

bitsize

If reg is a register name, this is the bitsize for the added register. Otherwise, this must not be provided.

Returns

from_signature

View source

@classmethod
from_signature(
    signature: qualtran.Signature,
    add_registers_allowed: bool = False
) -> Tuple['BloqBuilder', Dict[str, SoquetT]]

Construct a BloqBuilder with a pre-specified signature.

This is safer if e.g. you’re decomposing an existing Bloq and need the signatures to match. This constructor is used by Bloq.decompose_bloq().

map_soqs

View source

@staticmethod
map_soqs(
    soqs: Dict[str, SoquetT], soq_map: Iterable[Tuple[SoquetT, SoquetT]]
) -> Dict[str, SoquetT]

Map soqs according to soq_map.

See CompositeBloq.iter_bloqsoqs for example code.

Args

soqs

A soquet dictionary mapping register names to Soquets or arrays of Soquets. The values of this dictionary will be mapped.

soq_map

An iterable of (old_soq, new_soq) tuples that inform how to perform the mapping. Note that this is a list of tuples (not a dictionary) because old_soq may be an unhashable numpy array of Soquet.

Returns

add_t

View source

add_t(
    bloq: qualtran.Bloq,
    **in_soqs
) -> Tuple[SoquetT, ...]

Add a new bloq instance to the compute graph and always return a tuple of soquets.

This method will always return a tuple of soquets. See BloqBuilder.add_d(..) for a method that returns a dictionary of soquets. See BloqBuilder.add(..) for a return type that depends on the arity of the bloq.

Args

bloq

The bloq representing the operation to add.

**in_soqs

Keyword arguments mapping the new bloq’s register names to input Soquets or an array thereof. This is likely the output soquets from a prior operation.

Returns

add_d

View source

add_d(
    bloq: qualtran.Bloq,
    **in_soqs
) -> Dict[str, SoquetT]

Add a new bloq instance to the compute graph and return new soquets as a dictionary.

This method returns a dictionary of soquets. See BloqBuilder.add_t(..) for a method that returns an ordered tuple of soquets. See BloqBuilder.add(..) for a return type that depends on the arity of the bloq.

Args

bloq

The bloq representing the operation to add.

**in_soqs

Keyword arguments mapping the new bloq’s register names to input Soquets or an array thereof. This is likely the output soquets from a prior operation.

Returns

add_and_partition

View source

add_and_partition(
    bloq: qualtran.Bloq,
    partitions: Sequence[Tuple[Register, Sequence[Union[str, 'Unused']]]],
    left_only: bool = False,
    **in_soqs
)

Add a new bloq instance to the compute graph by partitioning input and output soquets to fit the signature of the bloq.

Args

bloq

The bloq representing the operation to add.

partitions

A sequence of pairs specifying each register that is exposed in the external signature of the AutoPartition and the corresponding register names from bloq that concatenate to form the externally exposed register. See AutoPartition.

left_only

If False, the output soquets will also follow partition. Otherwise, the output soquets will follow bloq.signature.rights(). This flag must be set to True if bloq does not have the same LEFT and RIGHT registers, as is required for the bloq to be fully wrapped on the left and right.

**in_soqs

Keyword arguments mapping the new bloq’s register names to input Soquets. This is likely the output soquets from a prior operation.

Returns

add

View source

add(
    bloq: qualtran.Bloq,
    **in_soqs
)

Add a new bloq instance to the compute graph.

This is the primary method for building a composite bloq. Each call to add adds a new bloq instance to the compute graph, wires up the soquets from prior operations into the new bloq, and returns new soquets to be used for subsequent bloqs.

This method will raise a BloqError if the addition is invalid. Soquets must be used exactly once and soquets must match the Register specifications of the bloq.

See also add_t or add_d for versions of this function that return output soquets in a structured way that may be more appropriate for programmatic adding of bloqs.

Args

bloq

The bloq representing the operation to add.

**in_soqs

Keyword arguments mapping the new bloq’s register names to input Soquets or an array thereof. This is likely the output soquets from a prior operation.

Returns

add_from

View source

add_from(
    bloq: qualtran.Bloq,
    **in_soqs
) -> Tuple[SoquetT, ...]

Add all the sub-bloqs from bloq to the composite bloq under construction.

Args

bloq

Where to add from. If this is a composite bloq, use its contents directly. Otherwise, we call decompose_bloq() first.

in_soqs

Input soquets for bloq; used to connect its left-dangling soquets.

Returns

finalize

View source

finalize(
    **final_soqs
) -> qualtran.CompositeBloq

Finish building a CompositeBloq and return the immutable CompositeBloq.

This method is similar to calling add() but instead of adding a new Bloq, it configures the final “dangling” soquets that serve as the outputs for the composite bloq as a whole.

If self.add_registers_allowed is set to True, additional register names passed to this function will be added as RIGHT registers. Otherwise, this method validates the provided final_soqs against our list of RIGHT (and THRU) registers.

Args

**final_soqs

Keyword arguments mapping the composite bloq’s register names to finalSoquets, e.g. the output soquets from a prior, final operation.

allocate

View source

allocate(
    n: qualtran.symbolics.SymbolicInt = 1,
    dtype: Optional[qualtran.QDType] = None,
    dirty: bool = False
) -> qualtran.Soquet

free

View source

free(
    soq: qualtran.Soquet,
    dirty: bool = False
) -> None

split

View source

split(
    soq: qualtran.Soquet
) -> NDArray[Soquet]

Add a Split bloq to split up a register.

join

View source

join(
    soqs: qualtran.Soquet,
    dtype: Optional[qualtran.QDType] = None
) -> qualtran.Soquet
On this page

This Page