Skip to content

Index

RB_C6 module-attribute 

RB_C6 = 2 * pi * 862690

The C6 constant for the Rydberg Interaction of two Rubidium atoms in units of: rad μm^6/μs

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][bloqade.builder.coupling.Rydberg] Level coupling
    • start.hyperfine: for [Hyperfine][bloqade.builder.coupling.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][bloqade.ir.scalar.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

Literal

Bases: Real

value instance-attribute 

value: Decimal

Scalar Literal, which stores a decimaal value instance.

Parameters:

Name Type Description Default
value Decimal

decimal value instance

 required

Variable

Bases: Real

Variable, which stores a variable name.

Parameters:

Name Type Description Default
name str

variable instance.

 required

cast 

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

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 .venv/lib/python3.12/site-packages/bloqade/analog/ir/scalar.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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

constant 

constant(
    duration: ScalarType, value: ScalarType
) -> Constant

Create a Constant waveform.

Parameters:

Name Type Description Default
duration ScalarType

Duration of the Constant waveform.

 required
value ScalarType

Value of the Constant waveform.s

 required

Returns:

Name Type Description
Constant Constant

A Constant waveform.
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/factory.py 
59
60
61
62
63
64
65
66
67
68
69
70
@beartype
def constant(duration: ScalarType, value: ScalarType) -> Constant:
    """Create a Constant waveform.

    Args:
        duration (ScalarType): Duration of the Constant waveform.
        value (ScalarType): Value of the Constant waveform.s

    Returns:
        Constant: A Constant waveform.
    """
    return Constant(value, duration)

dumps 

dumps(
    o: Any, use_decimal: bool = True, **json_kwargs
) -> str

Serialize object to string

Parameters:

Name Type Description Default
o Any

the object to serialize

 required
use_decimal bool

use decimal.Decimal for numbers. Defaults to True.

 True
**json_kwargs

other arguments passed to json.dumps

 {}

Returns:

Name Type Description
str str

the serialized object as a string
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/serialize.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
@beartype
def dumps(
    o: Any,
    use_decimal: bool = True,
    **json_kwargs,
) -> str:
    """Serialize object to string

    Args:
        o (Any): the object to serialize
        use_decimal (bool, optional): use decimal.Decimal for numbers. Defaults to True.
        **json_kwargs: other arguments passed to json.dumps

    Returns:
        str: the serialized object as a string
    """
    if not isinstance(o, Serializer.types):
        raise TypeError(
            f"Object of type {type(o)} is not JSON serializable. "
            f"Only {Serializer.types} are supported."
        )
    return json.dumps(o, cls=Serializer, use_decimal=use_decimal, **json_kwargs)

get_capabilities 

get_capabilities(
    use_experimental: bool = False,
) -> QuEraCapabilities

Get the device capabilities for Aquila

Parameters:

Name Type Description Default
use_experimental bool

Get experimental capabilities instead of standard ones. By default value is False.

 False

Returns:

Name Type Description
QuEraCapabilities QuEraCapabilities

capabilities object for Aquila device.
Note

Units of time, distance, and energy are microseconds (us), micrometers (um), and rad / us, respectively.

For a comprehensive list of capabilities, see the Hardware Reference page

Source code in .venv/lib/python3.12/site-packages/bloqade/analog/factory.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def get_capabilities(use_experimental: bool = False) -> "QuEraCapabilities":
    """Get the device capabilities for Aquila

    Args:
        use_experimental (bool): Get experimental capabilities instead of
            standard ones. By default value is False.

    Returns:
        QuEraCapabilities: capabilities object for Aquila device.


    Note:
        Units of time, distance, and energy are microseconds (us),
        micrometers (um), and rad / us, respectively.

        For a comprehensive list of capabilities,
        see the [Hardware Reference](../../reference/hardware-capabilities.md)
        page
    """

    from bloqade.analog.submission.capabilities import get_capabilities

    # manually convert to units
    return get_capabilities(use_experimental=use_experimental).scale_units(
        Decimal("1e6"), Decimal("1e-6")
    )

linear 

linear(
    duration: ScalarType,
    start: ScalarType,
    stop: ScalarType,
) -> Linear

Create a Linear waveform.

Parameters:

Name Type Description Default
duration ScalarType

Duration of linear waveform

 required
start ScalarType

Starting value of linear waveform

 required
stop ScalarType

Ending value of linear waveform

 required

Returns:

Name Type Description
Linear Linear

Linear waveform
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/factory.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
@beartype
def linear(duration: ScalarType, start: ScalarType, stop: ScalarType) -> Linear:
    """Create a Linear waveform.

    Args:
        duration (ScalarType): Duration of linear waveform
        start (ScalarType): Starting value of linear waveform
        stop (ScalarType): Ending value of linear waveform

    Returns:
        Linear: Linear waveform
    """
    return Linear(start, stop, duration)

load 

load(
    fp: Union[TextIO, str],
    use_decimal: bool = True,
    **json_kwargs
)

Load object from file

Parameters:

Name Type Description Default
fp Union[TextIO, str]

the file path or file object

 required
use_decimal bool

use decimal.Decimal for numbers. Defaults to True.

 True
**json_kwargs

other arguments passed to json.load

 {}

Returns:

Name Type Description
Any

the deserialized object
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/serialize.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@beartype
def load(fp: Union[TextIO, str], use_decimal: bool = True, **json_kwargs):
    """Load object from file

    Args:
        fp (Union[TextIO, str]): the file path or file object
        use_decimal (bool, optional): use decimal.Decimal for numbers. Defaults to True.
        **json_kwargs: other arguments passed to json.load

    Returns:
        Any: the deserialized object
    """
    load_bloqade()
    if isinstance(fp, str):
        with open(fp, "r") as f:
            return json.load(
                f,
                object_hook=Serializer.object_hook,
                use_decimal=use_decimal,
                **json_kwargs,
            )
    else:
        return json.load(
            fp,
            object_hook=Serializer.object_hook,
            use_decimal=use_decimal,
            **json_kwargs,
        )

loads 

loads(s: str, use_decimal: bool = True, **json_kwargs)

Load object from string

Parameters:

Name Type Description Default
s str

the string to load

 required
use_decimal bool

use decimal.Decimal for numbers. Defaults to True.

 True
**json_kwargs

other arguments passed to json.loads

 {}

Returns:

Name Type Description
Any

the deserialized object
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/serialize.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@beartype
def loads(s: str, use_decimal: bool = True, **json_kwargs):
    """Load object from string

    Args:
        s (str): the string to load
        use_decimal (bool, optional): use decimal.Decimal for numbers. Defaults to True.
        **json_kwargs: other arguments passed to json.loads

    Returns:
        Any: the deserialized object
    """
    load_bloqade()
    return json.loads(
        s, object_hook=Serializer.object_hook, use_decimal=use_decimal, **json_kwargs
    )

piecewise_constant 

piecewise_constant(
    durations: List[ScalarType], values: List[ScalarType]
) -> Waveform

Create a piecewise linear waveform.

Create a piecewise constant waveform from a list of durations and values. The value duration[i] corresponds to the length of time for the i'th segment with a value of values[i].

Parameters:

Name Type Description Default
durations List[ScalarType]

The duration of each segment

 required
values List[ScalarType]

The values for each segment

 required

Raises:

Type Description
ValueError

If the length of values is not the same as the length of

Returns:

Name Type Description
Waveform Waveform

The piecewise linear waveform.
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/factory.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@beartype
def piecewise_constant(
    durations: List[ScalarType], values: List[ScalarType]
) -> Waveform:
    """Create a piecewise linear waveform.

    Create a piecewise constant waveform from a list of durations and values. The
    value `duration[i]` corresponds to the length of time for the i'th segment
    with a value of `values[i]`.

    Args:
        durations (List[ScalarType]): The duration of each segment
        values (List[ScalarType]): The values for each segment

    Raises:
        ValueError: If the length of `values` is not the same as the length of
        `durations`.

    Returns:
        Waveform: The piecewise linear waveform.
    """
    if len(durations) != len(values):
        raise ValueError(
            "The length of values must be the same as the length of durations"
        )

    if len(durations) == 0:
        raise ValueError("The durations and values lists must not be empty.")

    pwc_wf = Constant(values[0], durations[0])
    for duration, value in zip(durations[1:], values[1:]):
        pwc_wf = pwc_wf.append(Constant(value, duration))

    return pwc_wf

piecewise_linear 

piecewise_linear(
    durations: List[ScalarType], values: List[ScalarType]
) -> Waveform

Create a piecewise linear waveform.

Create a piecewise linear waveform from a list of durations and values. The value duration[i] is of the linear segment between values[i] and values[i+1].

Parameters:

Name Type Description Default
durations List[ScalarType]

The duration of each segment

 required
values List[ScalarType]

The values for each segment

 required

Raises:

Type Description
ValueError

If the length of values is not one greater than the length of

Returns:

Name Type Description
Waveform Waveform

The piecewise linear waveform.
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/factory.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
@beartype
def piecewise_linear(durations: List[ScalarType], values: List[ScalarType]) -> Waveform:
    """Create a piecewise linear waveform.

    Create a piecewise linear waveform from a list of durations and values. The
    value `duration[i]` is of the linear segment between `values[i]` and `values[i+1]`.

    Args:
        durations (List[ScalarType]): The duration of each segment
        values (List[ScalarType]): The values for each segment

    Raises:
        ValueError: If the length of `values` is not one greater than the length of
        `durations`.

    Returns:
        Waveform: The piecewise linear waveform.
    """

    if len(durations) + 1 != len(values):
        raise ValueError(
            "The length of values must be one greater than the length of durations"
        )

    if len(durations) == 0:
        raise ValueError("The durations and values lists must not be empty.")

    pwl_wf = Linear(values[0], values[1], durations[0])
    for duration, start, stop in zip(durations[1:], values[1:-1], values[2:]):
        pwl_wf = pwl_wf.append(Linear(start, stop, duration))

    return pwl_wf

rydberg_h 

rydberg_h(
    atoms_positions: Any,
    detuning: Optional[Waveform] = None,
    amplitude: Optional[Waveform] = None,
    phase: Optional[Waveform] = None,
    static_params: Dict[str, Any] = {},
    batch_params: Union[
        List[Dict[str, Any]], Dict[str, Any]
    ] = [],
    args: List[str | Variable] = [],
) -> Routine

Create a rydberg program with uniform detuning, amplitude, and phase.

Parameters:

Name Type Description Default
atoms_positions Any

Description of geometry of atoms in system.

 required
detuning Optional[Waveform]

Waveform for detuning. Defaults to None.

 None
amplitude Optional[Waveform]

Waveform describing the amplitude of the rabi term. Defaults to None.

 None
phase Optional[Waveform]

Waveform describing the phase of rabi term. Defaults to None.

 None
static_params Dict[str, Any]

Define static parameters of your program. Defaults to {}.

 {}
batch_params Union[List[Dict[str, Any]], Dict[str, Any]]

Parmaters for a batch of tasks. Defaults to [].

 []
args List[str]

List of arguments to leave till runtime. Defaults to [].

 []

Returns:

Name Type Description
Routine Routine

An object that can be used to dispatch a rydberg program to multiple backends.
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/factory.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
@beartype
def rydberg_h(
    atoms_positions: Any,
    detuning: Optional[Waveform] = None,
    amplitude: Optional[Waveform] = None,
    phase: Optional[Waveform] = None,
    static_params: Dict[str, Any] = {},
    batch_params: Union[List[Dict[str, Any]], Dict[str, Any]] = [],
    args: List[str | Variable] = [],
) -> Routine:
    """Create a rydberg program with uniform detuning, amplitude, and phase.

    Args:
        atoms_positions (Any): Description of geometry of atoms in system.
        detuning (Optional[Waveform], optional): Waveform for detuning.
            Defaults to None.
        amplitude (Optional[Waveform], optional): Waveform describing the amplitude of
            the rabi term. Defaults to None.
        phase (Optional[Waveform], optional): Waveform describing the phase of rabi
            term. Defaults to None.
        static_params (Dict[str, Any], optional): Define static parameters of your
            program. Defaults to {}.
        batch_params (Union[List[Dict[str, Any]], Dict[str, Any]], optional):
            Parmaters for a batch of tasks. Defaults to [].
        args (List[str], optional): List of arguments to leave till runtime.
            Defaults to [].

    Returns:
        Routine: An object that can be used to dispatch a rydberg program to
            multiple backends.
    """
    from bloqade.analog import start
    from bloqade.analog.atom_arrangement import AtomArrangement

    if isinstance(atoms_positions, AtomArrangement):
        prog = atoms_positions
    else:
        prog = start.add_position(atoms_positions)

    if detuning is not None:
        prog = prog.rydberg.detuning.uniform.apply(detuning)

    if amplitude is not None:
        prog = prog.rydberg.rabi.amplitude.uniform.apply(amplitude)

    if phase is not None:
        prog = prog.rydberg.rabi.phase.uniform.apply(phase)

    if not isinstance(prog, Assignable):
        raise ValueError(
            "At least one of detuning, amplitude, or phase must be provided."
        )

    prog = prog.assign(**static_params)

    if isinstance(batch_params, dict):
        prog = prog.batch_assign(**batch_params)
    else:
        prog = prog.batch_assign(batch_params)

    prog = prog.args(args)

    return prog.parse()

save 

save(
    o: Any,
    fp: Union[TextIO, str],
    use_decimal=True,
    **json_kwargs
) -> None

Serialize object to file

Parameters:

Name Type Description Default
o Any

the object to serialize

 required
fp Union[TextIO, str]

the file path or file object

 required
use_decimal bool

use decimal.Decimal for numbers. Defaults to True.

 True
**json_kwargs

other arguments passed to json.dump

 {}

Returns:

Type Description
None

None
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/serialize.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
@beartype
def save(
    o: Any,
    fp: Union[TextIO, str],
    use_decimal=True,
    **json_kwargs,
) -> None:
    """Serialize object to file

    Args:
        o (Any): the object to serialize
        fp (Union[TextIO, str]): the file path or file object
        use_decimal (bool, optional): use decimal.Decimal for numbers. Defaults to True.
        **json_kwargs: other arguments passed to json.dump

    Returns:
        None
    """
    if not isinstance(o, Serializer.types):
        raise TypeError(
            f"Object of type {type(o)} is not JSON serializable. "
            f"Only {Serializer.types} are supported."
        )
    if isinstance(fp, str):
        with open(fp, "w") as f:
            json.dump(o, f, cls=Serializer, use_decimal=use_decimal, **json_kwargs)
    else:
        json.dump(o, fp, cls=Serializer, use_decimal=use_decimal, **json_kwargs)

tree_depth 

tree_depth(depth: int = None)

Setting globally maximum depth for tree printing

If depth=None, return current depth. If depth is provided, setting current depth to depth

Parameters:

Name Type Description Default
depth int

the user specified depth. Defaults to None.

 None

Returns:

Name Type Description
int

current updated depth
Source code in .venv/lib/python3.12/site-packages/bloqade/analog/__init__.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def tree_depth(depth: int = None):
    """Setting globally maximum depth for tree printing

    If `depth=None`, return current depth.
    If `depth` is provided, setting current depth to `depth`

    Args:
        depth (int, optional): the user specified depth. Defaults to None.

    Returns:
        int: current updated depth
    """
    if depth is not None:
        _ir.tree_print.MAX_TREE_DEPTH = depth
    return _ir.tree_print.MAX_TREE_DEPTH

var 

var(py: str) -> Variable

cast string (or list/tuple of strings) to [Variable][bloqade.ir.scalar.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 .venv/lib/python3.12/site-packages/bloqade/analog/ir/scalar.py 
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
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