requsim.tools package

A module to help working with requsim.

The tools module collects useful ways to set up and interact with requsim simulations, but which are not directly tied to the core functionality (and is therefore not automatically imported with “import requsim”). It also includes useful functions for evaluating the results from the simulation and a collection of useful pre-defined instances of requsim objects that are regularly used, e.g. for error models.

requsim.tools.evaluation module

Functions:

`binary_entropy`(p)	Calculate the binary entropy.
`calculate_keyrate_time`(correlations_z, ...)	Calculate the asymptotic key rate per time from a list of correlations.
`calculate_keyrate_channel_use`(...[, ...])	Calculate the asymptotic key rate per resource from a list of correlations.
`calculate_keyrate_channel_use_from_time`(...)	Calculate the asymptotic key rate per resource with only timing info.
`standard_bipartite_evaluation`(data_frame[, ...])	Calculate fidelities and key rates from times and states.

requsim.tools.evaluation.binary_entropy(p)

Calculate the binary entropy.

Parameters:: p (scalar) – Must be in interval [0, 1]. Usually an error rate.
Returns:: scalar – The binary entropy of p.

requsim.tools.evaluation.calculate_keyrate_time(correlations_z, correlations_x, err_corr_ineff, time_interval, return_std_err=False)

Calculate the asymptotic key rate per time from a list of correlations.

This uses the sample mean of error rates to estimate what the asymptotic key rate would be. It uses the formula for a bound on the asymptotic key rate. See for this particular formulation:

D. Luong, L. Jiang, J. Kim, N. Lütkenhaus; Appl. Phys. B 122, 96 (2016) arXiv:1508.02811 [quant-ph]

Optionally also returns the standard deviation of the key rate calculated by using propagation of error.

Parameters:

correlations_z (list of scalars) – List of correlations. The entries should correspond to the probabilty that measurement outcomes in z-direction coincide for each raw bit.
correlations_x (list of scalars) – List of correlations. The entries should correspond to the probabilty that measurement outcomes in x-direction coincide for each raw bit.
err_corr_ineff (scalar) – The error correction inefficiency, which lowers the obtainable key rate. 1 means perfectly efficient; >1 indicates inefficiencies
time_interval (scalar) – Time interval in which the raw bits were collected.
return_std_err (bool) – Whether to also compute and return the standard error of the mean of the key rate. Default: False

Returns:

scalar or tuple of scalars – If return_std_err is False, returns the key rate. If return_std_err is True, returns at tuple of key rate and standard error of the mean of the key rate.

requsim.tools.evaluation.calculate_keyrate_channel_use(correlations_z, correlations_x, err_corr_ineff, resource_list, return_std_err=False)

Calculate the asymptotic key rate per resource from a list of correlations.

CAREFUL: This formulation only makes sense when the amount of resources (usually number of channel uses or similar) is directly assignable to one particular pair or set of raw bits. This is often not the case e.g. if connections are not established sequentially for each bit, as would be the case for multi-mode memories. This function uses the sample mean of error rates to estimate what the asymptotic key rate would be. It uses the formula for a bound on the asymptotic key rate. See for this particular formulation:

D. Luong, L. Jiang, J. Kim, N. Lütkenhaus; Appl. Phys. B 122, 96 (2016) arXiv:1508.02811 [quant-ph]

Optionally also returns the standard deviation of the key rate calculated by using propagation of error.

Parameters:

correlations_z (list of scalars) – List of correlations. The entries should correspond to the probabilty that measurement outcomes in z-direction coincide for each raw bit.
correlations_x (list of scalars) – List of correlations. The entries should correspond to the probabilty that measurement outcomes in x-direction coincide for each raw bit.
err_corr_ineff (scalar) – The error correction inefficiency, which lowers the obtainable key rate. 1 means perfectly efficient; >1 indicates inefficiencies
resource_list (list of scalar) – A list containing the number of resources each set of raw bits consumed. This might not make sense if the number of consumed resources is not directly assignable to one particular set of raw bits.
return_std_err (bool) – Whether to also compute and return the standard error of the mean of the key rate. Default: False

Returns:

scalar or tuple of scalars – If return_std_err is False, returns the key rate. If return_std is True, returns at tuple of key rate and standard deviation of the key rate.

requsim.tools.evaluation.calculate_keyrate_channel_use_from_time(correlations_z, correlations_x, err_corr_ineff, time_list, trial_time, return_std_err=False)

Calculate the asymptotic key rate per resource with only timing info.

In some setups the number of channel uses is directly tied to time. CARFUL: This measure only makes sense if this is the case for the setup you are analyzing.

This function calculates time intervals and resources from the time_list and then passes them to calculate_keyrate_channel_use.

Parameters:

correlations_z (list of scalars) – List of correlations. The entries should correspond to the probabilty that measurement outcomes in z-direction coincide for each raw bit.
correlations_x (list of scalars) – List of correlations. The entries should correspond to the probabilty that measurement outcomes in x-direction coincide for each raw bit.
err_corr_ineff (scalar) – The error correction inefficiency, which lowers the obtainable key rate. 1 means perfectly efficient; >1 indicates inefficiencies
time_list (list of scalar) – A list containing the point in time that a each set of raw bits was recorded. e.g. data[“time”] from the data attribute of a requsim.tools.TwoLinkProtocol CAREFUL: This assumes that the protocol was started at time 0 and that the communication time is half the trial time.
trial_time (scalar) – The time one trial to establish a pair takes. Usually something like preparation time + 2 * distance / communication speed.
return_std_err (bool) – Whether to also compute and return the standard error of the mean of the key rate. Default: False

Returns:

scalar or tuple of scalars – If return_std is False, returns the key rate. If return_std is True, returns at tuple of key rate and standard deviation of the key rate.

requsim.tools.evaluation.standard_bipartite_evaluation(data_frame, err_corr_ineff=1)

Calculate fidelities and key rates from times and states.

Parameters:

data_frame (pd.DataFrame) – A pandas DataFrame with columns “time” and “state”, representing when each connection was made and the two-qubit state associated with that connection.
err_corr_ineff (scalar) – The error correction inefficiency, which lowers the obtainable key rate. 1 means perfectly efficient; >1 indicates inefficiencies. Default: 1

Returns:

list of scalars –

contains: raw rate,: average fidelity, standard error of the mean of fidelity, average asymptotic key rate per time, standard error of the mean of key rate per time

requsim.tools.noise_channels module

Functions:

`_x_noise_function`(rho, epsilon)	A single-qubit bit-flip channel.
`_y_noise_function`(rho, epsilon)	A single-qubit bit-and-phase-flip channel.
`_z_noise_function`(rho, epsilon)	A single-qubit phase-flip channel.
`_w_noise_function`(rho, alpha)	A single-qubit depolarizing (white) noise channel.

requsim.tools.noise_channels._x_noise_function(rho, epsilon)

A single-qubit bit-flip channel.

Parameters:

rho (np.ndarray) – A single-qubit density matrix (2x2).
epsilon (scalar) – Error probability 0 <= epsilon <= 1.

Returns:

np.ndarray – The density matrix with the map applied.

requsim.tools.noise_channels._y_noise_function(rho, epsilon)

A single-qubit bit-and-phase-flip channel.

Parameters:

rho (np.ndarray) – A single-qubit density matrix (2x2).
epsilon (scalar) – Error probability 0 <= epsilon <= 1.

Returns:

np.ndarray – The density matrix with the map applied.

requsim.tools.noise_channels._z_noise_function(rho, epsilon)

A single-qubit phase-flip channel.

Parameters:

rho (np.ndarray) – A single-qubit density matrix (2x2).
epsilon (scalar) – Error probability 0 <= epsilon <= 1.

Returns:

np.ndarray – The density matrix with the map applied.

requsim.tools.noise_channels._w_noise_function(rho, alpha)

A single-qubit depolarizing (white) noise channel.

Parameters:

rho (np.ndarray) – A single-qubit density matrix (2x2).
alpha (scalar) – Error parameter alpha 0 <= alpha <= 1. State is fully depolarized with probability (1-alpha)

Returns:

np.ndarray – The density matrix with the map applied.

requsim.tools.noise_channels.x_noise_channel(rho, *args, **kwargs) = NoiseChannel(n_qubits=1, channel_function=<function _x_noise_function>): Single-qubit Pauli-X noise channel. Takes error probability epsilon as additional argument.

requsim.tools.noise_channels.y_noise_channel(rho, *args, **kwargs) = NoiseChannel(n_qubits=1, channel_function=<function _y_noise_function>): Single-qubit Pauli-Y noise channel. Takes error probability epsilon as additional argument.

requsim.tools.noise_channels.z_noise_channel(rho, *args, **kwargs) = NoiseChannel(n_qubits=1, channel_function=<function _z_noise_function>): Single-qubit Pauli-Z noise channel. Takes error probability epsilon as additional argument.

requsim.tools.noise_channels.w_noise_channel(rho, *args, **kwargs) = NoiseChannel(n_qubits=1, channel_function=<function _w_noise_function>): Single-qubit white noise (=fully depolarizing) channel. Takes error parameter alpha as additional argument.

requsim.tools.protocol module

Classes:

`Protocol`([world])	Abstract base class for protocols.
`TwoLinkProtocol`([world, communication_speed])	A class that collects various useful methods for two-link scenarios.

class requsim.tools.protocol.Protocol(world=None)

Bases: ABC

Abstract base class for protocols.

Parameters:: world (World or None) – The use of this argument is deprecated (because a protocol should be defined and intializable without specifying a scenario it is used in) and only remains here for backward compatibility. Setting the world attribute as part of the setup method is the recommended way to do this now. Default: None
Variables:: world

Methods:

`setup`(world, args, *kwargs)	Setup function to be called after the world has been initialized.
`check`([message])	The main method of the protocol.

abstractmethod setup(world, *args, **kwargs)

Setup function to be called after the world has been initialized.

Should analyze the world to see if the protocol is applicable to the situation and possibly label stations/sources so they are easy to access in the check method of the protocol.

abstractmethod check(message=None)

The main method of the protocol.

Should analyze the current status of the world and event_queue to make decisions about next steps.

Parameters:: message (None or dict) – Optional additional information for the Protocol to consider. Default is None.

class requsim.tools.protocol.TwoLinkProtocol(world=None, communication_speed=None)

Bases: Protocol

A class that collects various useful methods for two-link scenarios.

But it is still abstract and misses the central check method.

Attributes:

data

Methods:

setup([world, communication_speed])

Identifies the stations and sources in the world.

property data

setup(world=None, communication_speed=None)

Identifies the stations and sources in the world.

Should be run after the relevant WorldObjects have been added to the world.

Parameters:

world (World) – The World object representing the scenario for which this Protocol will be used.
communication_speed (scalar) – The communication speed usd for calculating delays when sending qubits or classical messages between stations.

Returns:

None