app: application functions¶

`qecsim.app`¶

This module contains functions to generate and merge stabilizer code simulation data.

qecsim.app.merge(*data_list)¶

Merge any number of lists of aggregated runs data.

Notes:

The runs data is in the format specified in run() and fun_ftp().
Merged data is grouped by: (code, n_k_d, error_model, decoder, error_probability, time_steps, measurement_error_probability).
The following scalar values are summed: n_run, n_success, n_fail, error_weight_total, wall_time.
The following array values are summed: n_logical_commutations, custom_totals.
The following values are recalculated: logical_failure_rate, physical_error_rate.
The following values are not currently recalculated: error_weight_pvar.

Parameters: data_list (list of dict) – List of aggregated runs data.
Returns: Merged list of aggregated runs data.
Return type: list of dict
Raises: ValueError – if there is a mismatch between array values to be summed.

qecsim.app.run(code, error_model, decoder, error_probability, max_runs=None, max_failures=None, random_seed=None)¶

Execute stabilizer code error-decode-recovery (ideal) simulation many times and return aggregated runs data.

See run_once() for details of a single run.

Notes:

The simulation is run one or more times as determined by max_runs and max_failures:
- If max_runs specified, stop after max_runs runs.
- If max_failures specified, stop after max_failures failures.
- If max_runs and max_failures unspecified, run once.
The returned data is in the following format:

{
    'code': '5-qubit',                      # given code.label
    'n_k_d': (5, 1, 3),                     # given code.n_k_d
    'time_steps': 1,                        # always 1 for ideal simulation
    'error_model': 'Depolarizing',          # given error_model.label
    'decoder': 'Naive',                     # given decoder.label
    'error_probability': 0.0,               # given error_probability
    'measurement_error_probability': 0.0    # always 0.0 for ideal simulation
    'n_run': 0,                             # count of runs
    'n_success': 0,                         # count of successful recovery
    'n_fail': 0,                            # count of failed recovery
    'n_logical_commutations': (0, 0),       # count of logical commutations (tuple)
    'custom_totals': None,                  # sum of custom values (tuple)
    'error_weight_total': 0,                # sum of error_weight over n_run runs
    'error_weight_pvar': 0.0,               # pvariance of error_weight over n_run runs
    'logical_failure_rate': 0.0,            # n_fail / n_run
    'physical_error_rate': 0.0,             # error_weight_total / n_k_d[0] / time_steps / n_run
    'wall_time': 0.0,                       # wall-time for run in fractional seconds
}

Parameters

code (StabilizerCode) – Stabilizer code.
error_model (ErrorModel) – Error model.
decoder (Decoder) – Decoder.
error_probability (float) – Error probability.
max_runs (int) – Maximum number of runs. (default=None or 1 if max_failures unspecified, unrestricted=None)
max_failures (int) – Maximum number of failures. (default=None, unrestricted=None)
random_seed (int) – Error generation random seed. (default=None, unseeded=None)

Returns

Aggregated runs data.

Return type

dict

Raises

ValueError – if error_probability is not in [0, 1].

qecsim.app.run_ftp(code, time_steps, error_model, decoder, error_probability, measurement_error_probability=None, max_runs=None, max_failures=None, random_seed=None)¶

Execute stabilizer code error-decode-recovery (fault-tolerant time-periodic) simulation many times and return aggregated runs data.

See run_once_ftp() for details of a single run.

Notes:

The simulation is run one or more times as determined by max_runs and max_failures:
- If max_runs specified, stop after max_runs runs.
- If max_failures specified, stop after max_failures failures.
- If max_runs and max_failures unspecified, run once.
The returned data is in the following format:

{
    'code': '5-qubit',                      # given code.label
    'n_k_d': (5, 1, 3),                     # given code.n_k_d
    'time_steps': 1,                        # given number of time steps
    'error_model': 'Depolarizing',          # given error_model.label
    'decoder': 'NaiveFTP',                  # given decoder.label
    'error_probability': 0.0,               # given error_probability
    'measurement_error_probability': 0.0    # given measurement_error_probability
    'n_run': 0,                             # count of runs
    'n_success': 0,                         # count of successful recovery
    'n_fail': 0,                            # count of failed recovery
    'n_logical_commutations': (0, 0),       # count of logical commutations (tuple)
    'custom_totals': None,                  # sum of custom values (tuple)
    'error_weight_total': 0,                # sum of error_weight over n_run runs
    'error_weight_pvar': 0.0,               # pvariance of error_weight over n_run runs
    'logical_failure_rate': 0.0,            # n_fail / n_run
    'physical_error_rate': 0.0,             # error_weight_total / n_k_d[0] / time_steps / n_run
    'wall_time': 0.0,                       # wall-time for run in fractional seconds
}

Parameters

code (StabilizerCode) – Stabilizer code.
time_steps (int) – Number of time steps.
error_model (ErrorModel) – Error model.
decoder (DecoderFTP) – Fault-tolerant time-periodic decoder.
error_probability (float) – Error probability.
measurement_error_probability (float) – Measurement error probability. (default=None, None=error_probability or 0.0 if single time step)
max_runs (int) – Maximum number of runs. (default=None or 1 if max_failures unspecified, unrestricted=None)
max_failures (int) – Maximum number of failures. (default=None, unrestricted=None)
random_seed (int) – Error generation random seed. (default=None, unseeded=None)

Returns

Aggregated runs data.

Return type

dict

Raises

ValueError – if time_steps is not >= 1.
ValueError – if error_probability is not in [0, 1].
ValueError – if measurement_error_probability is not None or in [0, 1].

qecsim.app.run_once(code, error_model, decoder, error_probability, rng=None)¶

Run a stabilizer code error-decode-recovery (ideal) simulation and return run data.

Assumptions:

Error probability is float in [0, 1].

Notes:

The simulation is as follows:
- generate Pauli error by passing code and error_probability to qecsim.model.ErrorModel.generate().
- evaluate syndrome as error \(\odot\) code.stabilizers\(^T\).
- resolve decoding by passing code and syndrome to qecsim.model.Decoder.decode().
- define recovered as decoding \(\oplus\) error.
- verify recovered \(\odot\) code.stabilizers\(^T = 0\), by construction.
- define logical_commutations as recovered \(\odot\) code.logicals\(^T\).
- define success as logical_commutations\(= 0\).
\(\oplus\) denotes binary addition defined as addition modulo 2, or equivalently exclusive-or.
See qecsim.paulitools.bsp() for definition of \(\odot\).
Optionally, qecsim.model.Decoder.decode() may return DecodeResult as decoding to explicitly specify success, logical_commutations and custom_values, see qecsim.model.DecodeResult for details.
In addition to code and syndrome, the following keyword parameters are passed as context to qecsim.model.Decoder.decode(): error_model, error_probability, error. Furthermore, in order to enable decoders to handle ideal and fault-tolerant decoding consistently, the following keyword parameters and default values are passed as context: step_errors=[error], measurement_error_probability=0.0 and step_measurement_errors=[np.zeros(syndrome.shape)]. Most decoders will ignore these parameters.
The returned data is in the following format:

{
    'error_weight': 2,  # number of qubits acted on non-trivially by error
    'success': False,  # evaluated or overridden by decode result
    'logical_commutations': np.array([1, 0]),  # evaluated or overridden by decode result
    'custom_values': np.array([1])  # None or overridden by decode result
}

Parameters

code (StabilizerCode) – Stabilizer code.
error_model (ErrorModel) – Error model.
decoder (Decoder) – Decoder.
error_probability (float) – Error probability.
rng (numpy.random.Generator) – Random number generator for error generation. (default=None resolves to numpy.random.default_rng())

Returns

error_weight, success flag, logical_commutations, and custom values.

Return type

dict

Raises

ValueError – if error_probability is not in [0, 1].

qecsim.app.run_once_ftp(code, time_steps, error_model, decoder, error_probability, measurement_error_probability=None, rng=None)¶

Run a stabilizer code error-decode-recovery (fault-tolerant time-periodic) simulation and return run data.

Assumptions:

Time steps is integer >= 1.
Probabilities, where defined, are float in [0, 1].

Notes:

The simulation is as follows:
- for each time step \(t\):
  generate Pauli step_errors[t] by passing code and error_probability to qecsim.model.ErrorModel.generate().
  
  evaluate step_syndromes[t] as step_errors[t] \(\odot\) code.stabilizers\(^T\).
  
  generate step_measurement_errors[t] as syndrome bit-flips.
  
  generate syndrome[t] as step_measurement_errors[t-1] \(\oplus\) step_syndromes[t] \(\oplus\) step_measurement_errors[t].
- evaluate error as \(\bigoplus\) step_errors.
- resolve decoding by passing code, time_steps and syndrome to qecsim.model.DecoderFTP.decode_ftp().
- define recovered as decoding \(\oplus\) error.
- verify recovered \(\odot\) code.stabilizers\(^T = 0\), by construction.
- define logical_commutations as recovered \(\odot\) code.logicals\(^T\).
- define success as logical_commutations\(= 0\).
\(\oplus\) denotes binary addition defined as addition modulo 2, or equivalently exclusive-or.
See qecsim.paulitools.bsp() for definition of \(\odot\).
Optionally, qecsim.model.DecoderFTP.decode_ftp() may return DecodeResult as decoding to explicitly specify success, logical_commutations and custom_values, see qecsim.model.DecodeResult for details.
In addition to code, time_steps and syndrome, the following keyword parameters are passed as context to qecsim.model.DecoderFTP.decode_ftp(): error_model, error_probability, error, step_errors, measurement_error_probability and step_measurement_errors. Most decoders will ignore these parameters.
The returned data is in the following format:

{
    'error_weight': 2,  # number of qubits acted on non-trivially by error
    'success': False,  # evaluated or overridden by decode result
    'logical_commutations': np.array([1, 0]),  # evaluated or overridden by decode result
    'custom_values': np.array([1])  # None or overridden by decode result
}

Parameters

code (StabilizerCode) – Stabilizer code.
time_steps (int) – Number of time steps.
error_model (ErrorModel) – Error model.
decoder (DecoderFTP) – Fault-tolerant time-periodic decoder.
error_probability (float) – Error probability.
measurement_error_probability (float) – Measurement error probability. (default=None, None=error_probability or 0.0 if single time step)
rng (numpy.random.Generator) – Random number generator for error generation. (default=None resolves to numpy.random.default_rng())

Returns

error_weight, success flag, logical_commutations, and custom values.

Return type

dict

Raises

ValueError – if time_steps is not >= 1.
ValueError – if error_probability is not in [0, 1].
ValueError – if measurement_error_probability is not None or in [0, 1].

app: application functions¶

qecsim.app¶

`qecsim.app`¶