Index

start `module-attribute` ¶

start = ListOfLocations()

A Program starting point, alias of empty [ListOfLocations][bloqade.ir.location.list.ListOfLocations].

Next possible steps to build your program are:
Specify which level coupling to address with:
- start.rydberg: for Rydberg Level coupling
- start.hyperfine: for Hyperfine Level coupling
- LOCKOUT: You cannot add atoms to your geometry after specifying level coupling.
continue/start building your geometry with:
- start.add_position(): to add atom(s) to current register. It will accept:
  - A single coordinate, represented as a tuple (e.g. (5,6)) with a value that can either be:
    - integers: (5,6)
    - floats: (5.1, 2.5)
    - strings (for later variable assignment): ("x", "y")
    - Scalar objects: (2*cast("x"), 5+cast("y"))
  - A list of coordinates, represented as a list of types mentioned previously.
  - A numpy array with shape (n, 2) where n is the total number of atoms

AlignedWaveform ¶

Bases: Waveform

<padded waveform> ::= <waveform> | <waveform> <alignment> <value>

<alignment> ::= 'left aligned' | 'right aligned'
<value> ::= 'left value' | 'right value' | <scalar expr>

AnalogCircuit ¶

AnalogCircuit is a dummy type that bundle register and sequence together.

register `property` ¶

register

Get the register of the program.

Returns:

Type	Description
	register (Union["AtomArrangement", "ParallelRegister"])

Note

If the program is built with [parallelize()][bloqade.builder.emit.Emit.parallelize], The the register will be a ParallelRegister. Otherwise it will be a AtomArrangement.

show ¶

show(**assignments)

Interactive visualization of the program

Parameters:

Name	Type	Description	Default
`**assignments`		assigning the instance value (literal) to the existing variables in the program	`{}`

Source code in src/bloqade/ir/analog_circuit.py

def show(self, **assignments):
    """Interactive visualization of the program

    Args:
        **assignments: assigning the instance value (literal) to the
            existing variables in the program

    """
    display_ir(self, assignments)

AtomArrangement ¶

Bases: ProgramStart, TransformTrait

n_atoms `property` ¶

n_atoms

number of atoms (filled sites) in the register.

n_dims `property` ¶

n_dims

number of dimensions in the register.

n_sites `property` ¶

n_sites

number of sites in the register.

n_vacant `property` ¶

n_vacant

number of vacant sites in the register.

enumerate ¶

enumerate()

enumerate all locations in the register.

Source code in src/bloqade/ir/location/base.py

def enumerate(self) -> Generator[LocationInfo, None, None]:
    """enumerate all locations in the register."""
    raise NotImplementedError

figure ¶

figure(fig_kwargs=None, **assignments)

obtain a figure object from the atom arrangement.

Source code in src/bloqade/ir/location/base.py

def figure(self, fig_kwargs=None, **assignments):
    """obtain a figure object from the atom arrangement."""
    return get_atom_arrangement_figure(self, fig_kwargs, **assignments)

BoundedBravais ¶

BoundedBravais(*shape, lattice_spacing=1.0)

Bases: AtomArrangement

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(self, *shape: int, lattice_spacing: ScalarType = 1.0):
    self.shape = shape
    self.lattice_spacing = cast(lattice_spacing)
    self.__n_atoms = None
    self.__n_dims = None
    super().__init__()

__match_args__ `class-attribute` `instance-attribute` ¶

__match_args__ = ('shape', 'lattice_spacing')

Base classe for Bravais lattices AtomArrangement.

n_dims `property` ¶

n_dims

dimension of the lattice

Returns:

Name	Type	Description
`int`		dimension of the lattice

coordinates ¶

coordinates(index)

calculate the coordinates of a cell in the lattice given the cell index.

Source code in src/bloqade/ir/location/bravais.py

@beartype
def coordinates(self, index: List[int]) -> NDArray:
    """calculate the coordinates of a cell in the lattice
    given the cell index.
    """
    # damn! this is like stone age broadcasting
    vectors = np.array(self.cell_vectors())
    index = np.array(index)
    pos = np.sum(vectors.T * index, axis=1)
    return pos + np.array(self.cell_atoms())

scale ¶

scale(factor)

Scale the current location with a factor.

(x,y) -> factor*(x,y)

Parameters:

Name	Type	Description	Default
`factor`	`str \| Real \| Decimal \| Scalar`	scale factor	required

Returns:

Name	Type	Description
`BoundedBravais`	`BoundedBravais`	The lattice with the scaled locations

Source code in src/bloqade/ir/location/bravais.py

@beartype
def scale(self, factor: ScalarType) -> "BoundedBravais":
    """Scale the current location with a factor.

    (x,y) -> factor*(x,y)

    Args:
        factor (str | Real | Decimal | Scalar): scale factor

    Returns:
        BoundedBravais: The lattice with the scaled locations
    """
    factor = cast(factor)
    obj = self.__new__(type(self))
    for f in fields(self):
        if f.name == "lattice_spacing":
            obj.lattice_spacing = factor * self.lattice_spacing
        else:
            setattr(obj, f.name, getattr(self, f.name))
    return obj

Chain ¶

Chain(L, lattice_spacing=1.0, vertical_chain=False)

Bases: BoundedBravais

Chain lattice.

1D lattice
primitive (cell) vector(s)
- a1 = (1,0).
unit cell (1 atom(s))
- loc (0,0)

Parameters:

Name	Type	Description	Default
`L`	`int`	number of sites in the chain	required
`lattice_spacing`	`(Scalar, Real)`	lattice spacing. Defaults to 1.0.	`1.0`

Possible Next: continue with . to see possible next step in auto-prompt supported setting (IPython, IDE ...)

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(
    self, L: int, lattice_spacing: ScalarType = 1.0, vertical_chain: bool = False
):
    self.vertical = vertical_chain
    super().__init__(L, lattice_spacing=lattice_spacing)

Constant ¶

Constant(value, duration)

Bases: Instruction

<constant> ::= 'constant' <scalar expr>

f(t=0:duration) = value

Parameters:

Name	Type	Description	Default
`value`	`Scalar`	the constant value	required
`duration`	`Scalar`	the time span of the constant waveform.	required

Source code in src/bloqade/ir/control/waveform.py

@beartype
def __init__(self, value: ScalarType, duration: ScalarType):
    object.__setattr__(self, "value", cast(value))
    object.__setattr__(self, "duration", cast(duration))

Field ¶

Bases: FieldExpr

Field node in the IR. Which contains collection(s) of Waveform

<field> ::= ('field' <spatial modulation>  <padded waveform>)*

canonicalize ¶

canonicalize()

Canonicalize the Field by merging ScaledLocation nodes with the same waveform.

Source code in src/bloqade/ir/control/field.py

def canonicalize(self) -> "Field":
    """
    Canonicalize the Field by merging `ScaledLocation` nodes with the same waveform.
    """
    reversed_dirves = {}

    for sm, wf in self.drives.items():
        reversed_dirves[wf] = reversed_dirves.get(wf, []) + [sm]

    drives = {}

    for wf, sms in reversed_dirves.items():
        new_sm = [sm for sm in sms if not isinstance(sm, ScaledLocations)]
        scaled_locations_sm = [sm for sm in sms if isinstance(sm, ScaledLocations)]

        new_mask = {}

        for ele in scaled_locations_sm:
            for loc, scl in ele.value.items():
                new_mask[loc] = new_mask.get(loc, 0) + cast(scl)

        if new_mask:
            new_sm += [ScaledLocations(new_mask)]

        for sm in new_sm:
            drives[sm] = wf

    return Field(drives)

show ¶

show(**assignments)

Interactive visualization of the Field

Parameters:

Name	Type	Description	Default
`**assignments`		assigning the instance value (literal) to the existing variables in the Field	`{}`

Source code in src/bloqade/ir/control/field.py

def show(self, **assignments):
    """
    Interactive visualization of the Field

    Args:
        **assignments: assigning the instance value (literal) to the
            existing variables in the Field

    """
    display_ir(self, assignments)

Honeycomb ¶

Honeycomb(L, lattice_spacing=1.0)

Bases: BoundedBravais

Honeycomb lattice.

2D lattice
primitive (cell) vector(s)
- a1 = (1, 0)
- a2 = (½, sqrt(3)/2)
unit cell (2 atom(s))
- loc1 (0, 0)
- loc2 (½, 1/(2*sqrt(3))

Parameters:

Name	Type	Description	Default
`L`	`int`	number of sites in linear direction. n_atoms = L * L * 2.	required
`lattice_spacing`	`(Scalar, Real)`	lattice spacing. Defaults to 1.0.	`1.0`

Possible Next: continue with . to see possible next step in auto-prompt supported setting (IPython, IDE ...)

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(self, L: int, lattice_spacing: ScalarType = 1.0):
    super().__init__(L, L, lattice_spacing=lattice_spacing)

Kagome ¶

Kagome(L, lattice_spacing=1.0)

Bases: BoundedBravais

Kagome lattice.

2D lattice
primitive (cell) vector(s)
- a1 = (1, 0)
- a2 = (½, sqrt(3)/2)
unit cell (3 atom(s))
- loc1 (0, 0)
- loc2 (0.5, 0)
- loc3 (0.25 ,0.25sqrt(3))

Parameters:

Name	Type	Description	Default
`L`	`int`	number of sites in linear direction. n_atoms = L * L.	required
`lattice_spacing`	`(Scalar, Real)`	lattice spacing. Defaults to 1.0.	`1.0`

Possible Next: continue with . to see possible next step in auto-prompt supported setting (IPython, IDE ...)

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(self, L: int, lattice_spacing: ScalarType = 1.0):
    super().__init__(L, L, lattice_spacing=lattice_spacing)

Lieb ¶

Lieb(L, lattice_spacing=1.0)

Bases: BoundedBravais

Lieb lattice.

2D lattice
primitive (cell) vector(s)
- a1 = (1, 0)
- a2 = (0, 1)
unit cell (3 atom(s))
- loc1 (0, 0)
- loc2 (0.5, 0)
- loc3 (0 ,0.5)

Parameters:

Name	Type	Description	Default
`L`	`int`	number of sites in linear direction. n_atoms = L * L.	required
`lattice_spacing`	`(Scalar, Real)`	lattice spacing. Defaults to 1.0.	`1.0`

Possible Next: continue with . to see possible next step in auto-prompt supported setting (IPython, IDE ...)

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(self, L: int, lattice_spacing: ScalarType = 1.0):
    super().__init__(L, L, lattice_spacing=lattice_spacing)

Linear ¶

Linear(start, stop, duration)

Bases: Instruction

<linear> ::= 'linear' <scalar expr> <scalar expr>

f(t=0:duration) = start + (stop-start)/duration * t

Parameters:

Name	Type	Description	Default
`start`	`Scalar`	start value	required
`stop`	`Scalar`	stop value	required
`duration`	`Scalar`	the time span of the linear waveform.	required

Source code in src/bloqade/ir/control/waveform.py

@beartype
def __init__(self, start: ScalarType, stop: ScalarType, duration: ScalarType):
    object.__setattr__(self, "start", cast(start))
    object.__setattr__(self, "stop", cast(stop))
    object.__setattr__(self, "duration", cast(duration))

Literal ¶

Bases: Real

value `instance-attribute` ¶

value

Scalar Literal, which stores a decimaal value instance.

Parameters:

Name	Type	Description	Default
`value`	`Decimal`	decimal value instance	required

ParallelRegister ¶

ParallelRegister(register, cluster_spacing)

Bases: ProgramStart

Parallel Register

Source code in src/bloqade/ir/location/base.py

@beartype
def __init__(self, register: AtomArrangement, cluster_spacing: ScalarType):
    self._register = register
    self._cluster_spacing = cast(cluster_spacing)

    if register.n_atoms > 0:
        # calculate bounding box
        # of this register
        location_iter = register.enumerate()
        (x, y) = next(location_iter).position
        x_min = x
        x_max = x
        y_min = y
        y_max = y

        for location_info in location_iter:
            (x, y) = location_info.position
            x_min = x.min(x_min)
            x_max = x.max(x_max)
            y_min = y.min(y_min)
            y_max = y.max(y_max)

        shift_x = (x_max - x_min) + cluster_spacing
        shift_y = (y_max - y_min) + cluster_spacing

        register_locations = [
            list(location_info.position) for location_info in register.enumerate()
        ]
        register_filling = [
            location_info.filling.value for location_info in register.enumerate()
        ]
        shift_vectors = [[shift_x, cast(0)], [cast(0), shift_y]]
    else:
        raise ValueError("No locations to parallelize.")

    self.register_locations = register_locations
    self.register_filling = register_filling
    self.shift_vectors = shift_vectors
    super().__init__(self)

Poly ¶

Poly(coeffs, duration)

Bases: Instruction

<poly> ::= <scalar>+

f(t=0:duration) = c[0] + c[1]t + c[2]t^2 + ... + c[n-1]t^n-1 + c[n]t^n

Parameters:

Name	Type	Description	Default
`coeffs`	`List[Scalar]`	the coefficients c[] of the polynomial.	required
`duration`	`Scalar`	the time span of the waveform.	required

Source code in src/bloqade/ir/control/waveform.py

@beartype
def __init__(self, coeffs: List[ScalarType], duration: ScalarType):
    object.__setattr__(self, "coeffs", tuple(map(cast, coeffs)))
    object.__setattr__(self, "duration", cast(duration))

Pulse ¶

Pulse(field_pairs)

Bases: PulseExpr

<pulse> ::= (<field name> <field>)+

Source code in src/bloqade/ir/control/pulse.py

def __init__(self, field_pairs):
    fields = dict()
    for k, v in field_pairs.items():
        if isinstance(v, Field):
            fields[k] = v
        elif isinstance(v, dict):
            fields[k] = Field(v)
        else:
            raise TypeError(f"Expected Field or dict, got {type(v)}")
    self.fields = fields

show ¶

show(**assignments)

Interactive visualization of the Pulse

Parameters:

Name	Type	Description	Default
`**assignments`		assigning the instance value (literal) to the existing variables in the Pulse	`{}`

Source code in src/bloqade/ir/control/pulse.py

def show(self, **assignments):
    """
    Interactive visualization of the Pulse

    Args:
        **assignments: assigning the instance value (literal) to the
            existing variables in the Pulse

    """
    display_ir(self, assignments)

PythonFn ¶

Bases: Instruction

<python-fn> ::= 'python-fn' <python function def> <scalar expr>

Record ¶

Bases: Waveform

<record> ::= 'record' <waveform> <var>

Rectangular ¶

Rectangular(
    width,
    height,
    lattice_spacing_x=1.0,
    lattice_spacing_y=None,
)

Bases: BoundedBravais

Rectangular lattice.

2D lattice
primitive (cell) vector(s)
- a1 = (1,0)
- a2 = (0,1)
unit cell (1 atom(s))
- loc (0,0)

Parameters:

Name	Type	Description	Default
`width`	`int`	number of sites in x direction.	required
`height`	`int`	number of sites in y direction.	required
`lattice_spacing_x`	`(Scalar, Real)`	lattice spacing. Defaults to 1.0.	`1.0`
`lattice_spacing_y`	`(Scalar, Real)`	lattice spacing in y direction. optional.	`None`

Possible Next: continue with . to see possible next step in auto-prompt supported setting (IPython, IDE ...)

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(
    self,
    width: int,
    height: int,
    lattice_spacing_x: ScalarType = 1.0,
    lattice_spacing_y: Optional[ScalarType] = None,
):
    super().__init__(width, height, lattice_spacing=lattice_spacing_x)

    if lattice_spacing_y is None:
        self.ratio = cast(1.0) / cast(lattice_spacing_x)
    else:
        self.ratio = cast(lattice_spacing_y) / cast(lattice_spacing_x)

    super().__init__(width, height, lattice_spacing=lattice_spacing_x)

Sample ¶

Bases: Waveform

<sample> ::= 'sample' <waveform> <interpolation> <scalar>

Scalar ¶

Base class for all scalar expressions.

<scalar> ::= <literal>
| <variable>
| <default>
| <negative>
| <add>
| <mul>
| <min>
| <max>
| <slice>
| <inverval>

<mul> ::= <scalar> '*' <scalar>
<add> ::= <scalar> '+' <scalar>
<min> ::= 'min' <scalar>+
<max> ::= 'max' <scalar>+
<slice> ::= <scalar expr> '[' <interval> ']'
<interval> ::= <scalar expr> '..' <scalar expr>
<real> ::= <literal> | <var>

Sequence ¶

Sequence(seq_pairs=None)

Bases: SequenceExpr

Sequence of a program, which includes pulses informations.

Source code in src/bloqade/ir/control/sequence.py

def __init__(self, seq_pairs: Optional[Dict] = None):
    if seq_pairs is None:
        self.pulses = {}
        return

    pulses = {}
    for level_coupling, pulse in seq_pairs.items():
        if not isinstance(level_coupling, LevelCoupling):
            raise TypeError(f"Unexpected type {type(level_coupling)}")

        if isinstance(pulse, PulseExpr):
            pulses[level_coupling] = pulse
        elif isinstance(pulse, dict):
            pulses[level_coupling] = Pulse(pulse)
        else:
            raise TypeError(f"Unexpected type {type(pulse)}")
    self.pulses = pulses

show ¶

show(**assignments)

Interactive visualization of the Sequence

Parameters:

Name	Type	Description	Default
`**assignments`		assigning the instance value (literal) to the existing variables in the Sequence	`{}`

Source code in src/bloqade/ir/control/sequence.py

def show(self, **assignments):
    """
    Interactive visualization of the Sequence

    Args:
        **assignments: assigning the instance value (literal) to the
            existing variables in the Sequence

    """
    display_ir(self, assignments)

Square ¶

Square(L, lattice_spacing=1.0)

Bases: BoundedBravais

Square lattice.

2D lattice
primitive (cell) vector(s)
- a1 = (1,0)
- a2 = (0,1)
unit cell (1 atom(s))
- loc (0,0)

Parameters:

Name	Type	Description	Default
`L`	`int`	number of sites in linear direction. n_atoms = L * L.	required
`lattice_spacing`	`(Scalar, Real)`	lattice spacing. Defaults to 1.0.	`1.0`

Possible Next: continue with . to see possible next step in auto-prompt supported setting (IPython, IDE ...)

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(self, L: int, lattice_spacing: ScalarType = 1.0):
    super().__init__(L, L, lattice_spacing=lattice_spacing)

Triangular ¶

Triangular(L, lattice_spacing=1.0)

Bases: BoundedBravais

Triangular lattice.

2D lattice
primitive (cell) vector(s)
- a1 = (1, 0)
- a2 = (½, sqrt(3)/2)
unit cell (1 atom(s))
- loc (0, 0)

Parameters:

Name	Type	Description	Default
`L`	`int`	number of sites in linear direction. n_atoms = L * L.	required
`lattice_spacing`	`(Scalar, Real)`	lattice spacing. Defaults to 1.0.	`1.0`

Possible Next: continue with . to see possible next step in auto-prompt supported setting (IPython, IDE ...)

Source code in src/bloqade/ir/location/bravais.py

@beartype
def __init__(self, L: int, lattice_spacing: ScalarType = 1.0):
    super().__init__(L, L, lattice_spacing=lattice_spacing)

Variable ¶

Bases: Real

Variable, which stores a variable name.

Parameters:

Name	Type	Description	Default
`name`	`str`	variable instance.	required

Waveform ¶

Waveform node in the IR.

<waveform> ::= <instruction>
    | <smooth>
    | <slice>
    | <append>
    | <negative>
    | <scale>
    | <add>
    | <record>
    | <sample>

figure ¶

figure(**assignments)

get figure of the plotting the waveform.

Returns:

Name	Type	Description
`figure`		a bokeh figure

Source code in src/bloqade/ir/control/waveform.py

def figure(self, **assignments):
    """get figure of the plotting the waveform.

    Returns:
        figure: a bokeh figure
    """
    return get_ir_figure(self, **assignments)

cast ¶

cast(py)

cast Real number (or list/tuple of Real numbers) to Scalar Literal.
cast str (or list/tuple of Real numbers) to Scalar Variable.

Parameters:

Name	Type	Description	Default
`py`	`Union[str, Real, Tuple[Real], List[Real]]`	python object to cast	required

Returns:

Type	Description
`Scalar`	Scalar

Source code in src/bloqade/ir/scalar.py

def cast(py) -> "Scalar":
    """
    1. cast Real number (or list/tuple of Real numbers)
    to [`Scalar Literal`][bloqade.ir.scalar.Literal].

    2. cast str (or list/tuple of Real numbers)
    to [`Scalar Variable`][bloqade.ir.scalar.Variable].

    Args:
        py (Union[str,Real,Tuple[Real],List[Real]]): python object to cast

    Returns:
        Scalar
    """
    ret = trycast(py)
    if ret is None:
        raise TypeError(f"Cannot cast {type(py)} to Scalar Literal")

    return ret

var ¶

var(py)

cast string (or list/tuple of strings) to Variable.

Parameters:

Name	Type	Description	Default
`py`	`Union[str, List[str]]`	a string or list/tuple of strings	required

Returns:

Type	Description
`Variable`	Union[Variable]

Source code in src/bloqade/ir/scalar.py

def var(py: str) -> "Variable":
    """cast string (or list/tuple of strings)
    to [`Variable`][bloqade.ir.scalar.Variable].

    Args:
        py (Union[str, List[str]]): a string or list/tuple of strings

    Returns:
       Union[Variable]
    """
    ret = tryvar(py)
    if ret is None:
        raise TypeError(f"Cannot cast {type(py)} to Variable")

    return ret

Index

start module-attribute ¶

AlignedWaveform ¶

AnalogCircuit ¶

register property ¶

show ¶

AtomArrangement ¶

n_atoms property ¶

n_dims property ¶

n_sites property ¶

n_vacant property ¶

enumerate ¶

figure ¶

BoundedBravais ¶

__match_args__ class-attribute instance-attribute ¶

n_dims property ¶

coordinates ¶

scale ¶

Chain ¶

Constant ¶

Field ¶

canonicalize ¶

show ¶

Honeycomb ¶

Kagome ¶

Lieb ¶

Linear ¶

Literal ¶

value instance-attribute ¶

ParallelRegister ¶

Poly ¶

Pulse ¶

show ¶

PythonFn ¶

Record ¶

Rectangular ¶

Sample ¶

Scalar ¶

Sequence ¶

show ¶

Square ¶

Triangular ¶

Variable ¶

Waveform ¶

figure ¶

cast ¶

var ¶

start `module-attribute` ¶

register `property` ¶

n_atoms `property` ¶

n_dims `property` ¶

n_sites `property` ¶

n_vacant `property` ¶

__match_args__ `class-attribute` `instance-attribute` ¶

n_dims `property` ¶

value `instance-attribute` ¶