topqad_sdk.noiseprofiler.libprotocols package

The available protocols are:

LatticeSurgery
MagicStatePreparationHookInjection
MagicStatePreparationRepCode
Memory
Stability

class topqad_sdk.noiseprofiler.libprotocols.LatticeSurgery[source]

Lattice surgery is the method by which entangling operations can be performed on surface code qubits. A lattice surgery is equivalent to measuring a joint Pauli operator of two or more qubits. For example, two logical surface code patches could have their \(XX\) operator measured. If they are in the \(a\|++\rangle + b\|--\rangle\) state then the outcome would be \(+1\), if they are in \(a\|+-\rangle + b\|-+\rangle\) state then the outcome would be \(-1\), and if they are in any other state, then the outcome would be random.

In this protocol, a lattice surgery is implemented between two surface code patches. Two distinct logical qubits are created in the provided bases. They may be initially stabilized for a few rounds. Then a surface code merge is performed. This takes a logical operator of each of the qubits and joins the two surface code patches along these two operators. This is accomplished with the aid of a bus connecting the two qubit patches. This may entangle the two qubits depending on the bases and operators chosen. The merge code is stabilized for at least \(\mathcal{O}(d)\) rounds. Finally, the bus region is measured. This is called splitting the code. If done correctly, the stabilizer measurements of the bus yield the value of the joint observable of the merge. The two qubits may be stabilized for an additonal number of rounds before they too are measured.

Examples

The following example demonstrates how to configure and execute a lattice surgery protocol experiment:

from topqad_sdk.noiseprofiler.libprotocols import LatticeSurgery
from topqad_sdk.noiseprofiler.libnoise import PhysicalDepolarizing

# Initialize the Lattice Surgery protocol
lattice_surgery = LatticeSurgery()

# Configure the noise model
noise_model = PhysicalDepolarizing.from_preset("baseline")
lattice_surgery.add_noise_model(noise_model, label="Baseline")

# Add protocol instance
for d in range(3, 9+1, 2):
    lattice_surgery.add_instance(distance=d,
                                bus_width=d,
                                rounds=(0, d, 0),
                                merge_observable=('X', 'X'),
                                preparation_basis=('Z', 'Z'),
                                measurement_basis=('Z', 'Z'),
                                logical_observable=('Z0', 'Z1', 'BDZ'))

# Execute the simulation
print(lattice_surgery.execute_simulation())

Submitting Noise Profiler job for lattice_surgery protocol...
{'request_id': '12345', 'status': 'done'}

add_instance(distance: int, bus_width: int, rounds: tuple[int, int, int], merge_observable: tuple[str, str] = ('X', 'X'), preparation_basis: tuple[str, str] = ('X', 'Z'), measurement_basis: tuple[str, str] = ('Z', 'X'), logical_observable: tuple[str, ...] = ('X1', 'BSX'), *, noise_model_labels: str | list[str] | None = None, decoder='pymatching')[source]

Add instance of protocol parameters to be simulated.

Parameters:

distance (int) – Distance of codes used for the two logical qubits.
bus_width (int) – Number of row/column of data qubits added in the routing space.
rounds (tuple[int, int, int]) – Number of rounds of the pre-merge, merge, and split phases. merge rounds must be greater than 0. For example, (1, d, 0) is valid.
merge_observable (tuple[str, str], optional) – Joint observable being measured. Only possiblities are (‘X’, ‘X’) and (‘Z’, ‘Z’). Defaults to (‘X’, ‘X’).
preparation_basis (tuple[str, str], optional) – Logical qubits’ initialization basis. Defaults to (‘X’, ‘Z’).
measurement_basis (tuple[str, str], optional) – Logical qubits’ measurement basis. Defaults to (‘Z’, ‘X’).
logical_observable (tuple[str, ...], optional) – The observable used to validate the simulation. It’s a tuple of strings, each of which specifies measurements that must be included in the observable. Possible strings are ‘X0’, ‘X1’, ‘Z0’, ‘Z1’, ‘BSX’, ‘BSZ’, ‘BDX’ and ‘BDZ’. The first four are logical observables of the initial qubits. In the last four ‘B’ stands bus, ‘S’ stands for stabilizer, and ‘D’ stands for data. Defaults to (‘X1’, ‘BSX’).
noise_model_label (str | list[str] | None, optional) – The noise model label(s) for this instance. If None, then all added noise models are used. Default is None.
decoder (str, optional) – The decoder to use. “pymatching” is the only option.

The allowed possibilites of merge_observable, preparation_basis, measurement_basis and logical_observable are stored in the self.valid_observables.

Examples

The default values encode performing and checking teleporting a |+> state from the first to the second qubit, which is initially prepared in |0> using one stabilization round. So

from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing
from topqad_sdk.noiseprofiler.libprotocols import LatticeSurgery

lattice_surgery = LatticeSurgery()
lattice_surgery.add_noise_model(UniformDepolarizing(p=5e-3))
lattice_surgery.add_instance(distance=3,
                            bus_width=3,
                            rounds=(1,3,0),
                            merge_observable=('X', 'X'),
                            preparation_basis=('X', 'Z'),
                            measurement_basis=('Z', 'X'),
                            logical_observable=('X1', 'BSX')
                            )

Here, an XX surgery is performed to move the qubit over. The initial state |+0> after the surgery is either in the |++> or |+-> state. The bus stabilizers should measure +1 or -1 respectively if no errors occur. Hence, to validate this, we compute the product of ‘X1’ and ‘BSX’. It must be +1 if no error occurred.

Another possible lattice surgery is with the combination merge_observable=(‘X’, ‘X’), preparation_basis=(‘X’, ‘X’) and measurement_basis=(‘Z’, ‘X’)). For this key, self.valid_observables stores [‘X1’, ‘BSX’]. This means that logical_observable can be one of (‘X1’,), (‘BSX’, ) or (‘X1’, ‘BSX’).

add_noise_model(noise_model: NoiseModel, *, label: str | float | tuple[str, float] = 'noise_model') → None

Add a noise model that will be used in simulations.

Multiple noise models can be added. Each one should have a unique label (label_str, label_numeric).

Parameters:

noise_model (NoiseModel) – The noise model to add.
label (str | float | tuple[str, float], optional) – The label for the parameters. Defaults to ‘noise_model’.

Raises:

ValueError – If noise_model is not a noise model.
Exception – If label is already used for an existing noise model.

cancel() → dict

Cancel a running Noise Profiler job.

This method allows the user to cancel the currently running job associated with this instance (i.e., the most recent job submitted).

Returns:

request_id (str): The request ID of the request to be cancelled.
status (str): The status of the job after the cancel request, with possible values including “cancel_pending” (the cancel request was successful, and the job is being cancelled) or the current status of the job (e.g., “done”, “failed”, etc.) if the cancel request was declined or the job cannot be cancelled.
message (str): Information about the cancellation request.

Return type:

dict

Raises:

TopQADError – If the cancellation fails due to an internal error.
ValueError – If no request ID is found.

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation
memory.execute_simulation()

# Request cancellation of the running simulation
print(memory.cancel())

Submitting Noise Profiler job for memory protocol...
Cancel request for request_id 12345 has been submitted.
{'request_id': '12345', 'status': 'cancel_pending', 'message': 'Cancellation request submitted.'}

execute_simulation(async_mode=False, overwrite_results=False) → dict

Execute the simulation for the protocol instances specified in the simulation table.

Parameters:

async_mode (bool) – Flag determine whether to run noise profiler asynchronously. Defaults to False.
overwrite_results (bool) – Flag to determine whether to overwrite the noise profiler results. Defaults to False.

The Noise Profiler simulator uses a heuristic to avoid simulations that are unlikely to yield good statistics. It first collects \(10\%\) of the samples. If no errors are observed, then the remaining samples are not collected. In this case, the output statistical parameters will have the value “F” (indicating failure).

This method supports two execution modes: Synchronous and Asynchronous.

Sync Mode: The method waits for the job to complete and retrieves the results immediately. Use this mode when you want to block execution until the job finishes.
Async Mode: The method submits the job and returns immediately with the request_id and status. Use this mode when you want to submit the job and retrieve the results later.

Interactive Cancellation (sync mode):

In a terminal: While waiting for the job to complete, you can press Ctrl+C to interrupt polling.

When interrupted, you will be prompted to choose one of the following options:

Stop tracking the job (exit, job continues on server).

Send a cancellation request to the server and exit.

Resume waiting for the job to complete.

In a Jupyter notebook: Interrupting the cell (by pressing the stop button ■ in the notebook interface) while the job is running in synchronous mode will cancel the job on the server.

Returns:

Returns dict of request_id and status if async_mode set to True.

Return type:

dict

Raises:

RuntimeError – If the Noise Profiler fails to execute.
KeyboardInterrupt – If the job is interrupted by the user.
ValueError – If existing results are present and overwrite_result is False.
TopQADTimeoutError – If polling for the Noise Profiler job times out.

Examples

Synchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Execute the Noise Profiler simulation
print(memory.execute_simulation())

Submitting Noise Profiler job for memory protocol...
{'request_id': ..., 'status': 'done'}

Asynchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

response = memory.execute_simulation(async_mode=True) # Async mode
request_id = response["request_id"] # Store the job ID for later use

memory.load(request_id=request_id)  # Load the job later
memory.update_results()  # Check the job status or update the simulation table when complete

Submitting Noise Profiler job for memory protocol...
Existing request ID ... found. Requesting reports from server...
Noise Profile has finished for reqest ... Sim table has been updated.

fit_data(ind: str, dep: str, noise_model_label: str = 'noise_model', SNR_threshold: float = 5, Abs_threshold: float = inf) → tuple[Variable, ...][source]

Fit data for some combination of variables.

Parameters:

ind (str) – The independent variable name.
dep (str) – The dependent variable name.
noise_model_label (str) – The noise model for which to fit data. Defaults to “noise_model”.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded. Defaults to np.inf.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.

Returns:

The fit parameters as uncertainities Variable types. Use p.nominal_value and p.std_dev to access the stored values.

Return type:

tuple[Variable, …]

ind=”distance” and dep=”reaction_time” will return the reaction time for a SOTA decoder model.

fit_options: dict[tuple[str, str], FitSpecification] = {('distance', 'ler'): FitSpecification(fit_ansatz='p_0 * 3 * d**2 * p_1**(-(d+1)/2)', param_bounds=([0, 0], [inf, inf]), y_scale='log', fit_ansatz_latex='{p_0} \\times 3d^2 \\times {p_1}^{{-\\frac{{d+1}}{{2}}}}', ind_math_symbol='d'), ('distance', 'reaction_time'): FitSpecification(fit_ansatz='p_0 * d**p_1', param_bounds=([0, 0], [inf, inf]), y_scale='linear', fit_ansatz_latex='{p_0} d^{p_1}', ind_math_symbol='d'), (('rounds', 1), 'ler'): FitSpecification(fit_ansatz='p_0 * d**2 * p_1**(-(r+1)/2)', param_bounds=([0, 0], [inf, inf]), y_scale='log', fit_ansatz_latex='{p_0} d^2 \\times {p_1}^{{-\\frac{{r+1}}{{2}}}}', ind_math_symbol='r')}: A dictionary mapping (ind, dep) parameters to a fit specification. These fit options will then be used by the fitting and plotting routines.

includes_postselection: bool = False: Whether the protocol has post-selection in it.

load(request_id)

Retrieves and loads request information from server using given request_id.

This method fetches the status and results of a previously submitted Noise Profiler job. If the job is complete, the results are also loaded into the current instance. Any existing cached data (e.g., results, status, request ID) in the instance will be overwritten.

Use this method when you have a request_id from a previously submitted job and want to retrieve its current status or results.

Parameters:: request_id (str) – The ID of the Noise Profiler request.
Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

request_id = "12345"  # Replace with your actual request ID
print(memory.load(request_id))

{'request_id': '12345', 'status': 'done'}

noise_models: dict[str | float | tuple[str, float], NoiseModel]

plot(ind: str, dep: str, fit: bool = False, SNR_threshold: float = 5, Abs_threshold: float = inf, extrapolate: bool = False, extrapolate_to_dep: float = 1e-08, save_fig: bool = False, save_fig_dir: str = 'data/output', save_fig_filename: str | None = None, ax: Axes | None = None)

Plot the collected simulation data.

Each noise model data is plotted as a separate line on the plot.

Parameters:

ind (str) – The independent variable to use on the horizontal axis.
dep (str) – The dependent variable to use on the vertical axis. Can only be “ler” or “dr”.
fit (bool, optional) – Whether to fit the data. Defaults to False.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded for fits. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded for fits. Defaults to np.inf.
extrapolate (bool, optional) – Whether to extrapolate the dep var to. Defaults to False.
extrapolate_to_dep (float, optional) – The value to extrapolate the dep var to. Defaults to 1e-8.
save_fig (bool, optional) – Whether to safe the figure. Defaults to False.
save_fig_dir (str, optional) – Directory in which figure is saved. Directory is created if needed. Defaults to ‘data/output’.
save_fig_filename (str, optional) – Filename of saved figure. Defaults to f’plot_{self.protocol_name}_{ind}_{dep}.png’.
ax (Axes, optional) – A matplotlib Axes. If passed, then the plot is added to this axis. Defaults to None.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.
ValueError – If ax is not None or does not have type Axes.
ValueError – If extrapolation fails.
Exception – Fitting failed to yield reasonable values.

protocol_category: str = 'lattice_surgery': The main protocol category.

protocol_name: str = 'lattice_surgery': The unique name of the protocol.

protocol_parameters: alias of ModelLatticeSurgery

protocol_subcategory: str = 'emulated': The subcategory if there are various kinds of protocols.

set_simulation_parameters(max_n_samples: int = 100000000, signal_to_noise: float = 10, num_workers: int = 8, save_data: bool = False, save_data_dir: str = 'data/output', save_data_filename: str | None = None)

Set simulation parameters.

Parameters:

max_n_samples (int, optional) – The maximum samples that will be collected. Defaults to 10**8.
signal_to_noise (float, optional) – Signal to noise ratio used to determine how many samples will be collected. Defaults to 10.
num_workers (int, optional) – The number of worker processes that sinter should use. Defaults to 8.
save_data (bool, optional) – Whether to save simulation data to file.
save_data_dir (str, optional) – Directory where data file is saved, which is created if needed. Defaults to ‘data/output’.
save_data_filename (str, optional) – The name of the pickle file containing list[stim.TaskStats]. Defaults to f”simulation_table_{self.protocol_name}.pkl”.

simulation_table: SimTable

update_results() → dict

Retrieve the latest status for the request and update the simulation table if the job is complete.

Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to update the results of a previously submitted Noise Profiler job. This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation in async mode
memory.execute_simulation(async_mode=True)

# Later, when you want to check the status or update the table results if available
print(memory.update_results())

Submitting Noise Profiler job for memory protocol...
{'request_id': '12345', 'status': 'done'}

valid_observables: dict = {(('X', 'X'), ('X', 'X'), ('X', 'X')): ['X0', 'X1', 'BSX'], (('X', 'X'), ('X', 'X'), ('X', 'Z')): ['X0', 'BSX'], (('X', 'X'), ('X', 'X'), ('Z', 'X')): ['X1', 'BSX'], (('X', 'X'), ('X', 'X'), ('Z', 'Z')): ['BSX'], (('X', 'X'), ('X', 'Z'), ('X', 'X')): ['X0', ('X1', 'BSX')], (('X', 'X'), ('X', 'Z'), ('X', 'Z')): ['X0'], (('X', 'X'), ('X', 'Z'), ('Z', 'X')): [('X1', 'BSX')], (('X', 'X'), ('X', 'Z'), ('Z', 'Z')): [], (('X', 'X'), ('Z', 'X'), ('X', 'X')): ['X1', ('X0', 'BSX')], (('X', 'X'), ('Z', 'X'), ('X', 'Z')): [('X0', 'BSX')], (('X', 'X'), ('Z', 'X'), ('Z', 'X')): ['X1'], (('X', 'X'), ('Z', 'X'), ('Z', 'Z')): [], (('X', 'X'), ('Z', 'Z'), ('X', 'X')): [('X0', 'X1', 'BSX')], (('X', 'X'), ('Z', 'Z'), ('X', 'Z')): [], (('X', 'X'), ('Z', 'Z'), ('Z', 'X')): [], (('X', 'X'), ('Z', 'Z'), ('Z', 'Z')): [('Z0', 'Z1', 'BDZ')], (('Z', 'Z'), ('X', 'X'), ('X', 'X')): [('X0', 'X1', 'BDX')], (('Z', 'Z'), ('X', 'X'), ('X', 'Z')): [], (('Z', 'Z'), ('X', 'X'), ('Z', 'X')): [], (('Z', 'Z'), ('X', 'X'), ('Z', 'Z')): [('Z0', 'Z1', 'BSZ')], (('Z', 'Z'), ('X', 'Z'), ('X', 'X')): [], (('Z', 'Z'), ('X', 'Z'), ('X', 'Z')): ['Z1'], (('Z', 'Z'), ('X', 'Z'), ('Z', 'X')): [('Z0', 'BSZ')], (('Z', 'Z'), ('X', 'Z'), ('Z', 'Z')): ['Z1', ('Z0', 'BSZ')], (('Z', 'Z'), ('Z', 'X'), ('X', 'X')): [], (('Z', 'Z'), ('Z', 'X'), ('X', 'Z')): [('Z1', 'BSZ')], (('Z', 'Z'), ('Z', 'X'), ('Z', 'X')): ['Z0'], (('Z', 'Z'), ('Z', 'X'), ('Z', 'Z')): ['Z0', ('Z1', 'BSZ')], (('Z', 'Z'), ('Z', 'Z'), ('X', 'X')): ['BSZ'], (('Z', 'Z'), ('Z', 'Z'), ('X', 'Z')): ['Z1', 'BSZ'], (('Z', 'Z'), ('Z', 'Z'), ('Z', 'X')): ['Z0', 'BSZ'], (('Z', 'Z'), ('Z', 'Z'), ('Z', 'Z')): ['Z0', 'Z1', 'BSZ']}

class topqad_sdk.noiseprofiler.libprotocols.MagicStatePreparationHookInjection[source]

This protocol prepares a logical magic state. It has two stages [1]. In the first stage, two things happen simultaneously. First, a distance 2 surface code patch is created. However, in this process an intentional hook error is introduced that rotates the logical state of the code into the \(T\) state. Second, a surface code of distance \(d_1\) is created. Consequently, a \(T\) logical state is created in a distance \(d_1\) surface code. If any detectors trigger in this stage, the protocol is restarted. Otherwise, the second stage proceeds, in which the magic state is grown to a final distance \(d_2\).

In this implementation, an analogous protocol is constructed suitable for simulation on a Clifford simulator. Instead of creating a logical \(T\) state, a logical \(X\) state is created.

Examples

The following example demonstrates how to configure and execute a magic state preparation hook injection protocol experiment:

from topqad_sdk.noiseprofiler.libprotocols import MagicStatePreparationHookInjection
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

# Initialize the Magic State Preparation Hook Injection protocol
magic = MagicStatePreparationHookInjection()

# Configure the noise model
noise_model_uniform1 = UniformDepolarizing(p=8e-3)
magic.add_noise_model(noise_model_uniform1, label="p=8e-3")
noise_model_uniform2 = UniformDepolarizing(p=4e-3)
magic.add_noise_model(noise_model_uniform2, label="p=4e-3")

# Add protocol instance
for d_2 in range(5, 15+1, 2):
    magic.add_instance(d_1=3, d_2=d_2, r_2=d_2)
magic.set_simulation_parameters(max_n_samples=1e7, signal_to_noise=40)

# Execute the simulation
print(magic.execute_simulation())

Submitting Noise Profiler job for magic_state_preparation_hook_injection protocol...
{'request_id': ..., 'status': 'done'}

References

[1] C. Gidney, Cleaner Magic States with Hook Injection, arXiv:2302.12292.

add_instance(d_1: int, d_2: int, r_2: int, inject_state: str = 'X', *, noise_model_labels: str | list[str] | None = None, decoder: str = 'pymatching')[source]

Add instance of protocol parameters to be simulated.

Parameters:

d_1 (int) – The distance of the injection patch created in stage I. Must be odd.
d_2 (int) – The distance of the target patch created during state II. Must be odd and larger than d_1.
r_2 (int) – The number of rounds during stage II.
inject_state (str, optional) – Clifford simulation can be run with either the ‘X’ or ‘Y’ basis states. Defaults to ‘X’. Currently, ‘Y’ is not implemented.
noise_model_label (str | list[str] | None, optional) – The noise model label(s) for this instance. If None, then all added noise models are used. Default is None.
decoder (str, optional) – The decoder to use. “pymatching” is the only option.

add_noise_model(noise_model: NoiseModel, *, label: str | float | tuple[str, float] = 'noise_model') → None

Add a noise model that will be used in simulations.

Multiple noise models can be added. Each one should have a unique label (label_str, label_numeric).

Parameters:

noise_model (NoiseModel) – The noise model to add.
label (str | float | tuple[str, float], optional) – The label for the parameters. Defaults to ‘noise_model’.

Raises:

ValueError – If noise_model is not a noise model.
Exception – If label is already used for an existing noise model.

cancel() → dict

Cancel a running Noise Profiler job.

This method allows the user to cancel the currently running job associated with this instance (i.e., the most recent job submitted).

Returns:

request_id (str): The request ID of the request to be cancelled.
status (str): The status of the job after the cancel request, with possible values including “cancel_pending” (the cancel request was successful, and the job is being cancelled) or the current status of the job (e.g., “done”, “failed”, etc.) if the cancel request was declined or the job cannot be cancelled.
message (str): Information about the cancellation request.

Return type:

dict

Raises:

TopQADError – If the cancellation fails due to an internal error.
ValueError – If no request ID is found.

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation
memory.execute_simulation()

# Request cancellation of the running simulation
print(memory.cancel())

Submitting Noise Profiler job for memory protocol...
Cancel request for request_id 12345 has been submitted.
{'request_id': '12345', 'status': 'cancel_pending', 'message': 'Cancellation request submitted.'}

execute_simulation(async_mode=False, overwrite_results=False) → dict

Execute the simulation for the protocol instances specified in the simulation table.

Parameters:

async_mode (bool) – Flag determine whether to run noise profiler asynchronously. Defaults to False.
overwrite_results (bool) – Flag to determine whether to overwrite the noise profiler results. Defaults to False.

The Noise Profiler simulator uses a heuristic to avoid simulations that are unlikely to yield good statistics. It first collects \(10\%\) of the samples. If no errors are observed, then the remaining samples are not collected. In this case, the output statistical parameters will have the value “F” (indicating failure).

This method supports two execution modes: Synchronous and Asynchronous.

Sync Mode: The method waits for the job to complete and retrieves the results immediately. Use this mode when you want to block execution until the job finishes.
Async Mode: The method submits the job and returns immediately with the request_id and status. Use this mode when you want to submit the job and retrieve the results later.

Interactive Cancellation (sync mode):

In a terminal: While waiting for the job to complete, you can press Ctrl+C to interrupt polling.

When interrupted, you will be prompted to choose one of the following options:

Stop tracking the job (exit, job continues on server).

Send a cancellation request to the server and exit.

Resume waiting for the job to complete.

In a Jupyter notebook: Interrupting the cell (by pressing the stop button ■ in the notebook interface) while the job is running in synchronous mode will cancel the job on the server.

Returns:

Returns dict of request_id and status if async_mode set to True.

Return type:

dict

Raises:

RuntimeError – If the Noise Profiler fails to execute.
KeyboardInterrupt – If the job is interrupted by the user.
ValueError – If existing results are present and overwrite_result is False.
TopQADTimeoutError – If polling for the Noise Profiler job times out.

Examples

Synchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Execute the Noise Profiler simulation
print(memory.execute_simulation())

Submitting Noise Profiler job for memory protocol...
{'request_id': ..., 'status': 'done'}

Asynchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

response = memory.execute_simulation(async_mode=True) # Async mode
request_id = response["request_id"] # Store the job ID for later use

memory.load(request_id=request_id)  # Load the job later
memory.update_results()  # Check the job status or update the simulation table when complete

Submitting Noise Profiler job for memory protocol...
Existing request ID ... found. Requesting reports from server...
Noise Profile has finished for reqest ... Sim table has been updated.

fit_data(ind: str, dep: str, noise_model_label: str = 'noise_model', SNR_threshold: float = 5, Abs_threshold: float = inf) → tuple[Variable, ...]

Fit data for some combination of variables.

The fit function used must be present in self.fit_options[ind, dep].

Parameters:

ind (str) – The independent variable name.
dep (str) – The dependent variable name.
noise_model_label (str) – The noise model for which to fit data. Defaults to “noise_model”.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded. Defaults to np.inf.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.

Returns:

The fit parameters as uncertainities Variable types. Use p.nominal_value and p.std_dev to access the stored values.

Return type:

tuple[Variable, …]

fit_options: dict[tuple[str, str], FitSpecification] = {('d_1', 'dr'): FitSpecification(fit_ansatz='p_0 + 0*d_1', param_bounds=([0], [inf]), y_scale='linear', fit_ansatz_latex='{p_0}', ind_math_symbol='d_1'), ('d_2', 'ler'): FitSpecification(fit_ansatz='p_0*d_2 + p_1', param_bounds=([-inf, -inf], [inf, inf]), y_scale='linear', fit_ansatz_latex='{p_0} d_2 + {p_1}', ind_math_symbol='d_2')}: A dictionary mapping (ind, dep) parameters to a fit specification. These fit options will then be used by the fitting and plotting routines.

includes_postselection: bool = True: Whether the protocol has post-selection in it.

load(request_id)

Retrieves and loads request information from server using given request_id.

This method fetches the status and results of a previously submitted Noise Profiler job. If the job is complete, the results are also loaded into the current instance. Any existing cached data (e.g., results, status, request ID) in the instance will be overwritten.

Use this method when you have a request_id from a previously submitted job and want to retrieve its current status or results.

Parameters:: request_id (str) – The ID of the Noise Profiler request.
Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

request_id = "12345"  # Replace with your actual request ID
print(memory.load(request_id))

{'request_id': '12345', 'status': 'done'}

noise_models: dict[str | float | tuple[str, float], NoiseModel]

plot(ind: str, dep: str, fit: bool = False, SNR_threshold: float = 5, Abs_threshold: float = inf, extrapolate: bool = False, extrapolate_to_dep: float = 1e-08, save_fig: bool = False, save_fig_dir: str = 'data/output', save_fig_filename: str | None = None, ax: Axes | None = None)

Plot the collected simulation data.

Each noise model data is plotted as a separate line on the plot.

Parameters:

ind (str) – The independent variable to use on the horizontal axis.
dep (str) – The dependent variable to use on the vertical axis. Can only be “ler” or “dr”.
fit (bool, optional) – Whether to fit the data. Defaults to False.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded for fits. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded for fits. Defaults to np.inf.
extrapolate (bool, optional) – Whether to extrapolate the dep var to. Defaults to False.
extrapolate_to_dep (float, optional) – The value to extrapolate the dep var to. Defaults to 1e-8.
save_fig (bool, optional) – Whether to safe the figure. Defaults to False.
save_fig_dir (str, optional) – Directory in which figure is saved. Directory is created if needed. Defaults to ‘data/output’.
save_fig_filename (str, optional) – Filename of saved figure. Defaults to f’plot_{self.protocol_name}_{ind}_{dep}.png’.
ax (Axes, optional) – A matplotlib Axes. If passed, then the plot is added to this axis. Defaults to None.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.
ValueError – If ax is not None or does not have type Axes.
ValueError – If extrapolation fails.
Exception – Fitting failed to yield reasonable values.

protocol_category: str = 'magic_state_preparation_unit': The main protocol category.

protocol_name: str = 'magic_state_preparation_hook_injection': The unique name of the protocol.

protocol_parameters: alias of ModelMagicStatePreparationHookInjection

protocol_subcategory: str = 'two-stage': The subcategory if there are various kinds of protocols.

set_simulation_parameters(max_n_samples: int = 100000000, signal_to_noise: float = 10, num_workers: int = 8, save_data: bool = False, save_data_dir: str = 'data/output', save_data_filename: str | None = None)

Set simulation parameters.

Parameters:

max_n_samples (int, optional) – The maximum samples that will be collected. Defaults to 10**8.
signal_to_noise (float, optional) – Signal to noise ratio used to determine how many samples will be collected. Defaults to 10.
num_workers (int, optional) – The number of worker processes that sinter should use. Defaults to 8.
save_data (bool, optional) – Whether to save simulation data to file.
save_data_dir (str, optional) – Directory where data file is saved, which is created if needed. Defaults to ‘data/output’.
save_data_filename (str, optional) – The name of the pickle file containing list[stim.TaskStats]. Defaults to f”simulation_table_{self.protocol_name}.pkl”.

simulation_table: SimTable

update_results() → dict

Retrieve the latest status for the request and update the simulation table if the job is complete.

Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to update the results of a previously submitted Noise Profiler job. This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation in async mode
memory.execute_simulation(async_mode=True)

# Later, when you want to check the status or update the table results if available
print(memory.update_results())

Submitting Noise Profiler job for memory protocol...
{'request_id': '12345', 'status': 'done'}

class topqad_sdk.noiseprofiler.libprotocols.MagicStatePreparationRepCode[source]

This protocol prepares a logical magic state. It is inspired by Ref. [1]. Unlike in Ref. [1], this implementation is on the CSS rotated surface code with odd distances. This protocol has two stages. First a two-qubit repetition code is created and its state is rotated with the aid of a two-qubit rotation gate to create a logical magic state. Next, the repetition code is deformed/expanded into a surface code patch. If, during this expansion, any of the detectors trigger, the protocol is restarted. In the second stage, the logical state is grown to some final desired distance.

In this implementation, an analogous protocol is constructed suitable for simulation on a Clifford simulator. Instead of creating a logical \(T\) state, a logical \(X\) or \(Y\) state is created.

Examples

The following example demonstrates how to configure and execute a magic state preparation rep code protocol experiment:

from topqad_sdk.noiseprofiler.libprotocols import MagicStatePreparationRepCode
from topqad_sdk.noiseprofiler.libnoise import PhysicalDepolarizing

# Initialize the Magic State Preparation Rep Code protocol
magic = MagicStatePreparationRepCode()

# Configure the noise model
noise_model_target = PhysicalDepolarizing.from_preset("target")
magic.add_noise_model(noise_model_target, label="Target")

# Add protocol instance
for d in range(5, 15+1, 2):
    magic.add_instance(distances=[3,d],
                    rounds=[2, d],
                    inject_state='X')

magic.set_simulation_parameters(max_n_samples=1e7, signal_to_noise=40)

# Execute the simulation
print(magic.execute_simulation())

Submitting Noise Profiler job for magic_state_preparation_rep_code protocol...
{'request_id': ..., 'status': 'done'}

References

[1] Singh et al., High-Fidelity Magic-State Preparation with a Biased-Noise Architecture, Phys. Rev. A 105, 052410 (2022)

add_instance(distances: list[int | tuple[int, int]], rounds: list[int], inject_state: str = 'X', noise_model_labels: str | list[str] | None = None, decoder='pymatching')[source]

Add instance of protocol parameters to be simulated.

Parameters:

distances (list[int | tuple[int, int]]) – The distances for each of the two stages. Must be odd. If any distance is a tuple, it is treated as (d_x, d_z) for that stage.
rounds (list[int]) – The number of rounds for each of the two stages.
inject_state (str, optional) – Clifford simulation can be run with either the ‘X’ or ‘Y’ basis states. Defaults to ‘X’.
noise_model_label (str | list[str] | None, optional) – The noise model label(s) for this instance. If None, then all added noise models are used. Default is None.
decoder (str, optional) – The decoder to use. “pymatching” is the only option.

add_noise_model(noise_model: NoiseModel, *, label: str | float | tuple[str, float] = 'noise_model') → None

Add a noise model that will be used in simulations.

Multiple noise models can be added. Each one should have a unique label (label_str, label_numeric).

Parameters:

noise_model (NoiseModel) – The noise model to add.
label (str | float | tuple[str, float], optional) – The label for the parameters. Defaults to ‘noise_model’.

Raises:

ValueError – If noise_model is not a noise model.
Exception – If label is already used for an existing noise model.

cancel() → dict

Cancel a running Noise Profiler job.

This method allows the user to cancel the currently running job associated with this instance (i.e., the most recent job submitted).

Returns:

request_id (str): The request ID of the request to be cancelled.
status (str): The status of the job after the cancel request, with possible values including “cancel_pending” (the cancel request was successful, and the job is being cancelled) or the current status of the job (e.g., “done”, “failed”, etc.) if the cancel request was declined or the job cannot be cancelled.
message (str): Information about the cancellation request.

Return type:

dict

Raises:

TopQADError – If the cancellation fails due to an internal error.
ValueError – If no request ID is found.

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation
memory.execute_simulation()

# Request cancellation of the running simulation
print(memory.cancel())

Submitting Noise Profiler job for memory protocol...
Cancel request for request_id 12345 has been submitted.
{'request_id': '12345', 'status': 'cancel_pending', 'message': 'Cancellation request submitted.'}

execute_simulation(async_mode=False, overwrite_results=False) → dict

Execute the simulation for the protocol instances specified in the simulation table.

Parameters:

async_mode (bool) – Flag determine whether to run noise profiler asynchronously. Defaults to False.
overwrite_results (bool) – Flag to determine whether to overwrite the noise profiler results. Defaults to False.

The Noise Profiler simulator uses a heuristic to avoid simulations that are unlikely to yield good statistics. It first collects \(10\%\) of the samples. If no errors are observed, then the remaining samples are not collected. In this case, the output statistical parameters will have the value “F” (indicating failure).

This method supports two execution modes: Synchronous and Asynchronous.

Sync Mode: The method waits for the job to complete and retrieves the results immediately. Use this mode when you want to block execution until the job finishes.
Async Mode: The method submits the job and returns immediately with the request_id and status. Use this mode when you want to submit the job and retrieve the results later.

Interactive Cancellation (sync mode):

In a terminal: While waiting for the job to complete, you can press Ctrl+C to interrupt polling.

When interrupted, you will be prompted to choose one of the following options:

Stop tracking the job (exit, job continues on server).

Send a cancellation request to the server and exit.

Resume waiting for the job to complete.

In a Jupyter notebook: Interrupting the cell (by pressing the stop button ■ in the notebook interface) while the job is running in synchronous mode will cancel the job on the server.

Returns:

Returns dict of request_id and status if async_mode set to True.

Return type:

dict

Raises:

RuntimeError – If the Noise Profiler fails to execute.
KeyboardInterrupt – If the job is interrupted by the user.
ValueError – If existing results are present and overwrite_result is False.
TopQADTimeoutError – If polling for the Noise Profiler job times out.

Examples

Synchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Execute the Noise Profiler simulation
print(memory.execute_simulation())

Submitting Noise Profiler job for memory protocol...
{'request_id': ..., 'status': 'done'}

Asynchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

response = memory.execute_simulation(async_mode=True) # Async mode
request_id = response["request_id"] # Store the job ID for later use

memory.load(request_id=request_id)  # Load the job later
memory.update_results()  # Check the job status or update the simulation table when complete

Submitting Noise Profiler job for memory protocol...
Existing request ID ... found. Requesting reports from server...
Noise Profile has finished for reqest ... Sim table has been updated.

fit_data(ind: str, dep: str, noise_model_label: str = 'noise_model', SNR_threshold: float = 5, Abs_threshold: float = inf) → tuple[Variable, ...]

Fit data for some combination of variables.

The fit function used must be present in self.fit_options[ind, dep].

Parameters:

ind (str) – The independent variable name.
dep (str) – The dependent variable name.
noise_model_label (str) – The noise model for which to fit data. Defaults to “noise_model”.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded. Defaults to np.inf.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.

Returns:

The fit parameters as uncertainities Variable types. Use p.nominal_value and p.std_dev to access the stored values.

Return type:

tuple[Variable, …]

fit_options: dict[tuple[str, str], FitSpecification] = {(('distances', 0), 'dr'): FitSpecification(fit_ansatz='p_0 + 0*d_1', param_bounds=([0], [inf]), y_scale='linear', fit_ansatz_latex='{p_0} + {p_1}*d', ind_math_symbol='d_1'), (('distances', 1), 'ler'): FitSpecification(fit_ansatz='p_0 + p_1*d_2', param_bounds=([-inf, -inf], [inf, inf]), y_scale='linear', fit_ansatz_latex='{p_0} + {p_1}*d_2', ind_math_symbol='d_2')}: A dictionary mapping (ind, dep) parameters to a fit specification. These fit options will then be used by the fitting and plotting routines.

includes_postselection: bool = True: Whether the protocol has post-selection in it.

load(request_id)

Retrieves and loads request information from server using given request_id.

This method fetches the status and results of a previously submitted Noise Profiler job. If the job is complete, the results are also loaded into the current instance. Any existing cached data (e.g., results, status, request ID) in the instance will be overwritten.

Use this method when you have a request_id from a previously submitted job and want to retrieve its current status or results.

Parameters:: request_id (str) – The ID of the Noise Profiler request.
Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

request_id = "12345"  # Replace with your actual request ID
print(memory.load(request_id))

{'request_id': '12345', 'status': 'done'}

noise_models: dict[str | float | tuple[str, float], NoiseModel]

plot(ind: str, dep: str, fit: bool = False, SNR_threshold: float = 5, Abs_threshold: float = inf, extrapolate: bool = False, extrapolate_to_dep: float = 1e-08, save_fig: bool = False, save_fig_dir: str = 'data/output', save_fig_filename: str | None = None, ax: Axes | None = None)

Plot the collected simulation data.

Each noise model data is plotted as a separate line on the plot.

Parameters:

ind (str) – The independent variable to use on the horizontal axis.
dep (str) – The dependent variable to use on the vertical axis. Can only be “ler” or “dr”.
fit (bool, optional) – Whether to fit the data. Defaults to False.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded for fits. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded for fits. Defaults to np.inf.
extrapolate (bool, optional) – Whether to extrapolate the dep var to. Defaults to False.
extrapolate_to_dep (float, optional) – The value to extrapolate the dep var to. Defaults to 1e-8.
save_fig (bool, optional) – Whether to safe the figure. Defaults to False.
save_fig_dir (str, optional) – Directory in which figure is saved. Directory is created if needed. Defaults to ‘data/output’.
save_fig_filename (str, optional) – Filename of saved figure. Defaults to f’plot_{self.protocol_name}_{ind}_{dep}.png’.
ax (Axes, optional) – A matplotlib Axes. If passed, then the plot is added to this axis. Defaults to None.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.
ValueError – If ax is not None or does not have type Axes.
ValueError – If extrapolation fails.
Exception – Fitting failed to yield reasonable values.

protocol_category: str = 'magic_state_preparation_unit': The main protocol category.

protocol_name: str = 'magic_state_preparation_rep_code': The unique name of the protocol.

protocol_parameters: alias of ModelMagicStatePreparationRepCode

protocol_subcategory: str = 'two-stage': The subcategory if there are various kinds of protocols.

set_simulation_parameters(max_n_samples: int = 100000000, signal_to_noise: float = 10, num_workers: int = 8, save_data: bool = False, save_data_dir: str = 'data/output', save_data_filename: str | None = None)

Set simulation parameters.

Parameters:

max_n_samples (int, optional) – The maximum samples that will be collected. Defaults to 10**8.
signal_to_noise (float, optional) – Signal to noise ratio used to determine how many samples will be collected. Defaults to 10.
num_workers (int, optional) – The number of worker processes that sinter should use. Defaults to 8.
save_data (bool, optional) – Whether to save simulation data to file.
save_data_dir (str, optional) – Directory where data file is saved, which is created if needed. Defaults to ‘data/output’.
save_data_filename (str, optional) – The name of the pickle file containing list[stim.TaskStats]. Defaults to f”simulation_table_{self.protocol_name}.pkl”.

simulation_table: SimTable

update_results() → dict

Retrieve the latest status for the request and update the simulation table if the job is complete.

Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to update the results of a previously submitted Noise Profiler job. This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation in async mode
memory.execute_simulation(async_mode=True)

# Later, when you want to check the status or update the table results if available
print(memory.update_results())

Submitting Noise Profiler job for memory protocol...
{'request_id': '12345', 'status': 'done'}

class topqad_sdk.noiseprofiler.libprotocols.Memory[source]

This protocol is used to protect idle qubits from noise. For simulation, a logical basis state of the rotated surface code of distance \(d\) is simultaneously created and stabilized for \(r\) rounds. A logical zero state \(|0\rangle_L\) is created by first indiviually preparing all the physical data qubits in the zero state \(|0\rangle\) and then the \(r\) stabilization rounds are conducted. A plus state \(|+\rangle_L\) is created similarly, except that the physical data qubits are individually prepared in the plus state \(|+\rangle\).

To verify that the state was correctly preserved in memory, after r rounds, all data qubits are measured. Then, the value of the logical observable is extracted. For example, to verify that the \(|0\rangle_L\) was preserved, the logical \(Z\) operator is determined by multiplying the value of all data qubits along the top row of the surface code grid. If the value is \(+1\), then no logical \(X\) error occured to flip the value of the state.

Examples: The following example demonstrates how to configure and execute a memory protocol experiment:

from topqad_sdk.noiseprofiler.libprotocols import Memory
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

# Initialize the Memory protocol
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")

# Add protocol instances
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')

# Set simulation parameters
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Execute the simulation
print(memory.execute_simulation())

Submitting Noise Profiler job for memory protocol...
{'request_id': ..., 'status': 'done'}

add_instance(distance: int, rounds: int, basis: str = 'Z', *, noise_model_labels: str | list[str] | None = None, decoder: str = 'pymatching')[source]

Add instance of protocol parameters to be simulated.

Parameters:

distance (int) – Distance of code. Must be odd.
rounds (int) – Number of rounds.
basis (str, optional) – The memory basis. Defaults to ‘Z’.
noise_model_label (str | list[str] | None, optional) – The noise model label(s) for this instance. If None, then all added noise models are used. Default is None.
decoder (str, optional) – The decoder to use. “pymatching” is the only option.

add_noise_model(noise_model: NoiseModel, *, label: str | float | tuple[str, float] = 'noise_model') → None

Add a noise model that will be used in simulations.

Multiple noise models can be added. Each one should have a unique label (label_str, label_numeric).

Parameters:

noise_model (NoiseModel) – The noise model to add.
label (str | float | tuple[str, float], optional) – The label for the parameters. Defaults to ‘noise_model’.

Raises:

ValueError – If noise_model is not a noise model.
Exception – If label is already used for an existing noise model.

cancel() → dict

Cancel a running Noise Profiler job.

This method allows the user to cancel the currently running job associated with this instance (i.e., the most recent job submitted).

Returns:

request_id (str): The request ID of the request to be cancelled.
status (str): The status of the job after the cancel request, with possible values including “cancel_pending” (the cancel request was successful, and the job is being cancelled) or the current status of the job (e.g., “done”, “failed”, etc.) if the cancel request was declined or the job cannot be cancelled.
message (str): Information about the cancellation request.

Return type:

dict

Raises:

TopQADError – If the cancellation fails due to an internal error.
ValueError – If no request ID is found.

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation
memory.execute_simulation()

# Request cancellation of the running simulation
print(memory.cancel())

Submitting Noise Profiler job for memory protocol...
Cancel request for request_id 12345 has been submitted.
{'request_id': '12345', 'status': 'cancel_pending', 'message': 'Cancellation request submitted.'}

execute_simulation(async_mode=False, overwrite_results=False) → dict

Execute the simulation for the protocol instances specified in the simulation table.

Parameters:

async_mode (bool) – Flag determine whether to run noise profiler asynchronously. Defaults to False.
overwrite_results (bool) – Flag to determine whether to overwrite the noise profiler results. Defaults to False.

The Noise Profiler simulator uses a heuristic to avoid simulations that are unlikely to yield good statistics. It first collects \(10\%\) of the samples. If no errors are observed, then the remaining samples are not collected. In this case, the output statistical parameters will have the value “F” (indicating failure).

This method supports two execution modes: Synchronous and Asynchronous.

Sync Mode: The method waits for the job to complete and retrieves the results immediately. Use this mode when you want to block execution until the job finishes.
Async Mode: The method submits the job and returns immediately with the request_id and status. Use this mode when you want to submit the job and retrieve the results later.

Interactive Cancellation (sync mode):

In a terminal: While waiting for the job to complete, you can press Ctrl+C to interrupt polling.

When interrupted, you will be prompted to choose one of the following options:

Stop tracking the job (exit, job continues on server).

Send a cancellation request to the server and exit.

Resume waiting for the job to complete.

In a Jupyter notebook: Interrupting the cell (by pressing the stop button ■ in the notebook interface) while the job is running in synchronous mode will cancel the job on the server.

Returns:

Returns dict of request_id and status if async_mode set to True.

Return type:

dict

Raises:

RuntimeError – If the Noise Profiler fails to execute.
KeyboardInterrupt – If the job is interrupted by the user.
ValueError – If existing results are present and overwrite_result is False.
TopQADTimeoutError – If polling for the Noise Profiler job times out.

Examples

Synchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Execute the Noise Profiler simulation
print(memory.execute_simulation())

Submitting Noise Profiler job for memory protocol...
{'request_id': ..., 'status': 'done'}

Asynchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

response = memory.execute_simulation(async_mode=True) # Async mode
request_id = response["request_id"] # Store the job ID for later use

memory.load(request_id=request_id)  # Load the job later
memory.update_results()  # Check the job status or update the simulation table when complete

Submitting Noise Profiler job for memory protocol...
Existing request ID ... found. Requesting reports from server...
Noise Profile has finished for reqest ... Sim table has been updated.

fit_data(ind: str, dep: str, noise_model_label: str = 'noise_model', SNR_threshold: float = 5, Abs_threshold: float = inf) → tuple[Variable, ...][source]

Fit data for some combination of variables.

Parameters:

ind (str) – The independent variable name.
dep (str) – The dependent variable name.
noise_model_label (str) – The noise model for which to fit data. Defaults to “noise_model”.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded. Defaults to np.inf.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.

Returns:

The fit parameters as uncertainities Variable types. Use p.nominal_value and p.std_dev to access the stored values.

Return type:

tuple[Variable, …]

ind=”distance” and dep=”reaction_time” will return the reaction time for a SOTA decoder model.

fit_options: dict[tuple[str, str], FitSpecification] = {('distance', 'ler'): FitSpecification(fit_ansatz='p_0 * d**2 * p_1**(-(d+1)/2)', param_bounds=([0, 0], [inf, inf]), y_scale='log', fit_ansatz_latex='{p_0} d^2 \\times {p_1}^{{-\\frac{{d+1}}{{2}}}}', ind_math_symbol='d'), ('distance', 'reaction_time'): FitSpecification(fit_ansatz='p_0 * d**p_1', param_bounds=([0, 0], [inf, inf]), y_scale='linear', fit_ansatz_latex='{p_0} d^{p_1}', ind_math_symbol='d')}: A dictionary mapping (ind, dep) parameters to a fit specification. These fit options will then be used by the fitting and plotting routines.

includes_postselection: bool = False: Whether the protocol has post-selection in it.

load(request_id)

Retrieves and loads request information from server using given request_id.

This method fetches the status and results of a previously submitted Noise Profiler job. If the job is complete, the results are also loaded into the current instance. Any existing cached data (e.g., results, status, request ID) in the instance will be overwritten.

Use this method when you have a request_id from a previously submitted job and want to retrieve its current status or results.

Parameters:: request_id (str) – The ID of the Noise Profiler request.
Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

request_id = "12345"  # Replace with your actual request ID
print(memory.load(request_id))

{'request_id': '12345', 'status': 'done'}

noise_models: dict[str | float | tuple[str, float], NoiseModel]

plot(ind: str, dep: str, fit: bool = False, SNR_threshold: float = 5, Abs_threshold: float = inf, extrapolate: bool = False, extrapolate_to_dep: float = 1e-08, save_fig: bool = False, save_fig_dir: str = 'data/output', save_fig_filename: str | None = None, ax: Axes | None = None)

Plot the collected simulation data.

Each noise model data is plotted as a separate line on the plot.

Parameters:

ind (str) – The independent variable to use on the horizontal axis.
dep (str) – The dependent variable to use on the vertical axis. Can only be “ler” or “dr”.
fit (bool, optional) – Whether to fit the data. Defaults to False.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded for fits. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded for fits. Defaults to np.inf.
extrapolate (bool, optional) – Whether to extrapolate the dep var to. Defaults to False.
extrapolate_to_dep (float, optional) – The value to extrapolate the dep var to. Defaults to 1e-8.
save_fig (bool, optional) – Whether to safe the figure. Defaults to False.
save_fig_dir (str, optional) – Directory in which figure is saved. Directory is created if needed. Defaults to ‘data/output’.
save_fig_filename (str, optional) – Filename of saved figure. Defaults to f’plot_{self.protocol_name}_{ind}_{dep}.png’.
ax (Axes, optional) – A matplotlib Axes. If passed, then the plot is added to this axis. Defaults to None.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.
ValueError – If ax is not None or does not have type Axes.
ValueError – If extrapolation fails.
Exception – Fitting failed to yield reasonable values.

protocol_category: str = 'memory': The main protocol category.

protocol_name: str = 'memory': The unique name of the protocol.

protocol_parameters: alias of ModelMemory

protocol_subcategory: str = 'emulated': The subcategory if there are various kinds of protocols.

set_simulation_parameters(max_n_samples: int = 100000000, signal_to_noise: float = 10, num_workers: int = 8, save_data: bool = False, save_data_dir: str = 'data/output', save_data_filename: str | None = None)

Set simulation parameters.

Parameters:

max_n_samples (int, optional) – The maximum samples that will be collected. Defaults to 10**8.
signal_to_noise (float, optional) – Signal to noise ratio used to determine how many samples will be collected. Defaults to 10.
num_workers (int, optional) – The number of worker processes that sinter should use. Defaults to 8.
save_data (bool, optional) – Whether to save simulation data to file.
save_data_dir (str, optional) – Directory where data file is saved, which is created if needed. Defaults to ‘data/output’.
save_data_filename (str, optional) – The name of the pickle file containing list[stim.TaskStats]. Defaults to f”simulation_table_{self.protocol_name}.pkl”.

simulation_table: SimTable

update_results() → dict

Retrieve the latest status for the request and update the simulation table if the job is complete.

Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to update the results of a previously submitted Noise Profiler job. This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation in async mode
memory.execute_simulation(async_mode=True)

# Later, when you want to check the status or update the table results if available
print(memory.update_results())

Submitting Noise Profiler job for memory protocol...
{'request_id': '12345', 'status': 'done'}

class topqad_sdk.noiseprofiler.libprotocols.Stability[source]

The stability protocol [1] is used to estimate how well a fault-tolerant system can move logical observables through space or, equivalently, determine the product of a large region of stabilizers. Logical observables are, for example, moved through space in lattice surgery operations.

Examples

The following example demonstrates how to configure and execute a stability protocol experiment:

from topqad_sdk.noiseprofiler.libprotocols import Stability
from topqad_sdk.noiseprofiler.libnoise import PhysicalDepolarizing

# Initialize the Stability protocol
stability = Stability()

# Configure the noise model
noise_model = PhysicalDepolarizing.from_preset("baseline")
stability.add_noise_model(noise_model, label="Baseline")

# Add protocol instance
for r in range(4,12+1, 2):
    stability.add_instance(rounds=r, diameter=8)

# Execute the simulation
print(stability.execute_simulation())

Submitting Noise Profiler job for stability protocol...
{'request_id': ..., 'status': 'done'}

References

[1] Gidney et al, Stability Experiments: The Overlooked Dual of Memory Experiments, Quantum 6, 786 (2022)

add_instance(rounds: int, diameter: int | tuple[int, int], *, noise_model_labels: str | list[str] | None = None, decoder='pymatching')[source]

Add instance of protocol parameters to be simulated.

Parameters:

rounds (int) – Number of rounds (temporal distance).
diameter (int | tuple[int, int]) – Spatial distance of code. Must be even. Can separately specify (d_x, d_z).
noise_model_label (str | list[str] | None, optional) – The noise model label(s) for this instance. If None, then all added noise models are used. Default is None.
decoder (str, optional) – The decoder to use. “pymatching” is the only option.

add_noise_model(noise_model: NoiseModel, *, label: str | float | tuple[str, float] = 'noise_model') → None

Add a noise model that will be used in simulations.

Multiple noise models can be added. Each one should have a unique label (label_str, label_numeric).

Parameters:

noise_model (NoiseModel) – The noise model to add.
label (str | float | tuple[str, float], optional) – The label for the parameters. Defaults to ‘noise_model’.

Raises:

ValueError – If noise_model is not a noise model.
Exception – If label is already used for an existing noise model.

cancel() → dict

Cancel a running Noise Profiler job.

This method allows the user to cancel the currently running job associated with this instance (i.e., the most recent job submitted).

Returns:

request_id (str): The request ID of the request to be cancelled.
status (str): The status of the job after the cancel request, with possible values including “cancel_pending” (the cancel request was successful, and the job is being cancelled) or the current status of the job (e.g., “done”, “failed”, etc.) if the cancel request was declined or the job cannot be cancelled.
message (str): Information about the cancellation request.

Return type:

dict

Raises:

TopQADError – If the cancellation fails due to an internal error.
ValueError – If no request ID is found.

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation
memory.execute_simulation()

# Request cancellation of the running simulation
print(memory.cancel())

Submitting Noise Profiler job for memory protocol...
Cancel request for request_id 12345 has been submitted.
{'request_id': '12345', 'status': 'cancel_pending', 'message': 'Cancellation request submitted.'}

execute_simulation(async_mode=False, overwrite_results=False) → dict

Execute the simulation for the protocol instances specified in the simulation table.

Parameters:

async_mode (bool) – Flag determine whether to run noise profiler asynchronously. Defaults to False.
overwrite_results (bool) – Flag to determine whether to overwrite the noise profiler results. Defaults to False.

The Noise Profiler simulator uses a heuristic to avoid simulations that are unlikely to yield good statistics. It first collects \(10\%\) of the samples. If no errors are observed, then the remaining samples are not collected. In this case, the output statistical parameters will have the value “F” (indicating failure).

This method supports two execution modes: Synchronous and Asynchronous.

Sync Mode: The method waits for the job to complete and retrieves the results immediately. Use this mode when you want to block execution until the job finishes.
Async Mode: The method submits the job and returns immediately with the request_id and status. Use this mode when you want to submit the job and retrieve the results later.

Interactive Cancellation (sync mode):

In a terminal: While waiting for the job to complete, you can press Ctrl+C to interrupt polling.

When interrupted, you will be prompted to choose one of the following options:

Stop tracking the job (exit, job continues on server).

Send a cancellation request to the server and exit.

Resume waiting for the job to complete.

In a Jupyter notebook: Interrupting the cell (by pressing the stop button ■ in the notebook interface) while the job is running in synchronous mode will cancel the job on the server.

Returns:

Returns dict of request_id and status if async_mode set to True.

Return type:

dict

Raises:

RuntimeError – If the Noise Profiler fails to execute.
KeyboardInterrupt – If the job is interrupted by the user.
ValueError – If existing results are present and overwrite_result is False.
TopQADTimeoutError – If polling for the Noise Profiler job times out.

Examples

Synchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Execute the Noise Profiler simulation
print(memory.execute_simulation())

Submitting Noise Profiler job for memory protocol...
{'request_id': ..., 'status': 'done'}

Asynchronous Mode

from topqad_sdk.noiseprofiler.libprotocols import Memory
from topqad_sdk.noiseprofiler.libnoise import UniformDepolarizing

memory = Memory()

uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

response = memory.execute_simulation(async_mode=True) # Async mode
request_id = response["request_id"] # Store the job ID for later use

memory.load(request_id=request_id)  # Load the job later
memory.update_results()  # Check the job status or update the simulation table when complete

Submitting Noise Profiler job for memory protocol...
Existing request ID ... found. Requesting reports from server...
Noise Profile has finished for reqest ... Sim table has been updated.

fit_data(ind: str, dep: str, noise_model_label: str = 'noise_model', SNR_threshold: float = 5, Abs_threshold: float = inf) → tuple[Variable, ...]

Fit data for some combination of variables.

The fit function used must be present in self.fit_options[ind, dep].

Parameters:

ind (str) – The independent variable name.
dep (str) – The dependent variable name.
noise_model_label (str) – The noise model for which to fit data. Defaults to “noise_model”.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded. Defaults to np.inf.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.

Returns:

The fit parameters as uncertainities Variable types. Use p.nominal_value and p.std_dev to access the stored values.

Return type:

tuple[Variable, …]

fit_options: dict[tuple[str, str], FitSpecification] = {}: A dictionary mapping (ind, dep) parameters to a fit specification. These fit options will then be used by the fitting and plotting routines.

includes_postselection: bool = False: Whether the protocol has post-selection in it.

load(request_id)

Retrieves and loads request information from server using given request_id.

This method fetches the status and results of a previously submitted Noise Profiler job. If the job is complete, the results are also loaded into the current instance. Any existing cached data (e.g., results, status, request ID) in the instance will be overwritten.

Use this method when you have a request_id from a previously submitted job and want to retrieve its current status or results.

Parameters:: request_id (str) – The ID of the Noise Profiler request.
Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to cancel a running Noise Profiler job.

This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

request_id = "12345"  # Replace with your actual request ID
print(memory.load(request_id))

{'request_id': '12345', 'status': 'done'}

noise_models: dict[str | float | tuple[str, float], NoiseModel]

plot(ind: str, dep: str, fit: bool = False, SNR_threshold: float = 5, Abs_threshold: float = inf, extrapolate: bool = False, extrapolate_to_dep: float = 1e-08, save_fig: bool = False, save_fig_dir: str = 'data/output', save_fig_filename: str | None = None, ax: Axes | None = None)

Plot the collected simulation data.

Each noise model data is plotted as a separate line on the plot.

Parameters:

ind (str) – The independent variable to use on the horizontal axis.
dep (str) – The dependent variable to use on the vertical axis. Can only be “ler” or “dr”.
fit (bool, optional) – Whether to fit the data. Defaults to False.
SNR_threshold (float) – Points with signal-to-noise below this threshold are discarded for fits. Defaults to 5.
Abs_threshold (float) – Points whose value is higher than this absolute threshold are discarded for fits. Defaults to np.inf.
extrapolate (bool, optional) – Whether to extrapolate the dep var to. Defaults to False.
extrapolate_to_dep (float, optional) – The value to extrapolate the dep var to. Defaults to 1e-8.
save_fig (bool, optional) – Whether to safe the figure. Defaults to False.
save_fig_dir (str, optional) – Directory in which figure is saved. Directory is created if needed. Defaults to ‘data/output’.
save_fig_filename (str, optional) – Filename of saved figure. Defaults to f’plot_{self.protocol_name}_{ind}_{dep}.png’.
ax (Axes, optional) – A matplotlib Axes. If passed, then the plot is added to this axis. Defaults to None.

Raises:

ValueError – If (ind, dep) is not a key in self.fit_options.
ValueError – If ax is not None or does not have type Axes.
ValueError – If extrapolation fails.
Exception – Fitting failed to yield reasonable values.

protocol_category: str = 'stability': The main protocol category.

protocol_name: str = 'stability': The unique name of the protocol.

protocol_parameters: alias of ModelStability

protocol_subcategory: str = 'emulated': The subcategory if there are various kinds of protocols.

set_simulation_parameters(max_n_samples: int = 100000000, signal_to_noise: float = 10, num_workers: int = 8, save_data: bool = False, save_data_dir: str = 'data/output', save_data_filename: str | None = None)

Set simulation parameters.

Parameters:

max_n_samples (int, optional) – The maximum samples that will be collected. Defaults to 10**8.
signal_to_noise (float, optional) – Signal to noise ratio used to determine how many samples will be collected. Defaults to 10.
num_workers (int, optional) – The number of worker processes that sinter should use. Defaults to 8.
save_data (bool, optional) – Whether to save simulation data to file.
save_data_dir (str, optional) – Directory where data file is saved, which is created if needed. Defaults to ‘data/output’.
save_data_filename (str, optional) – The name of the pickle file containing list[stim.TaskStats]. Defaults to f”simulation_table_{self.protocol_name}.pkl”.

simulation_table: SimTable

update_results() → dict

Retrieve the latest status for the request and update the simulation table if the job is complete.

Returns:: Status and request ID of the request.
Return type:: dict

Examples

The following example demonstrates how to update the results of a previously submitted Noise Profiler job. This example uses the Memory protocol as a placeholder. If you are using a different protocol (e.g., LatticeSurgery, Stability), replace Memory with the protocol you are using.

from topqad_sdk.noiseprofiler.libprotocols import Memory  # Replace `Memory` with your protocol, e.g., `LatticeSurgery`
memory = Memory()

# Configure the noise model
uniform_noise_model = UniformDepolarizing(p=3e-3)
memory.add_noise_model(noise_model=uniform_noise_model, label="uniform")
for d in range(3, 11+1, 2):
    memory.add_instance(distance=d,
                        rounds=d,
                        basis='Z')
memory.set_simulation_parameters(max_n_samples=5e5, signal_to_noise=25)

# Submit the Noise Profiler simulation in async mode
memory.execute_simulation(async_mode=True)

# Later, when you want to check the status or update the table results if available
print(memory.update_results())

Submitting Noise Profiler job for memory protocol...
{'request_id': '12345', 'status': 'done'}

topqad_sdk.noiseprofiler.libprotocols package

topqad_sdk.noiseprofiler.libprotocols models