pygsti.io.writers

Functions for writing GST objects to text files.

Module Contents

Functions

write_empty_dataset(filename, circuits, header_string='## Columns = 1 frequency, count total', num_zero_cols=None, append_weights_column=False)

Write an empty dataset file to be used as a template.

_outcome_to_str(x)

write_dataset(filename, dataset, circuits=None, outcome_label_order=None, fixed_column_mode='auto', with_times='auto')

Write a text-formatted dataset file.

write_multidataset(filename, multidataset, circuits=None, outcome_label_order=None)

Write a text-formatted multi-dataset file.

write_circuit_list(filename, circuits, header=None)

Write a text-formatted circuit list file.

write_model(model, filename, title=None)

Write a text-formatted model file.

write_empty_protocol_data(dirname, edesign, sparse='auto', clobber_ok=False)

Write to disk an empty ProtocolData object.

fill_in_empty_dataset_with_fake_data(dataset_filename, model, num_samples, sample_error='multinomial', seed=None, rand_state=None, alias_dict=None, collision_action='aggregate', record_zero_counts=True, comm=None, mem_limit=None, times=None, fixed_column_mode='auto')

Fills in the text-format data set file dataset_fileame with simulated data counts using model.

write_circuit_strings(filename, obj)

TODO: docstring - write various Circuit-containing standard objects with circuits

pygsti.io.writers.write_empty_dataset(filename, circuits, header_string='## Columns = 1 frequency, count total', num_zero_cols=None, append_weights_column=False)

Write an empty dataset file to be used as a template.

Parameters
  • filename (string) – The filename to write.

  • circuits (list of Circuits) – List of circuits to write, each to be followed by num_zero_cols zeros.

  • header_string (string, optional) – Header string for the file; should start with a pound (#) or double-pound (##) so it is treated as a commend or directive, respectively.

  • num_zero_cols (int, optional) – The number of zero columns to place after each circuit. If None, then header_string must begin with “## Columns = ” and number of zero columns will be inferred.

  • append_weights_column (bool, optional) – Add an additional ‘weights’ column.

Returns

None

pygsti.io.writers._outcome_to_str(x)
pygsti.io.writers.write_dataset(filename, dataset, circuits=None, outcome_label_order=None, fixed_column_mode='auto', with_times='auto')

Write a text-formatted dataset file.

Parameters
  • filename (string) – The filename to write.

  • dataset (DataSet) – The data set from which counts are obtained.

  • circuits (list of Circuits, optional) – The list of circuits to include in the written dataset. If None, all circuits are output.

  • outcome_label_order (list, optional) – A list of the outcome labels in dataset which specifies the column order in the output file.

  • fixed_column_mode (bool or 'auto', optional) – When True, a file is written with column headers indicating which outcome each column of counts corresponds to. If a row doesn’t have any counts for an outcome, ‘–’ is used in its place. When False, each row’s counts are written in an expanded form that includes the outcome labels (each “count” has the format <outcomeLabel>:<count>).

  • with_times (bool or "auto", optional) – Whether to include (save) time-stamp information in output. This can only be True when fixed_column_mode=False. “auto” will set this to True if fixed_column_mode=False and dataset has data at non-trivial (non-zero) times.

Returns

None

pygsti.io.writers.write_multidataset(filename, multidataset, circuits=None, outcome_label_order=None)

Write a text-formatted multi-dataset file.

Parameters
  • filename (string) – The filename to write.

  • multidataset (MultiDataSet) – The multi data set from which counts are obtained.

  • circuits (list of Circuits) – The list of circuits to include in the written dataset. If None, all circuits are output.

  • outcome_label_order (list, optional) – A list of the SPAM labels in multidataset which specifies the column order in the output file.

Returns

None

pygsti.io.writers.write_circuit_list(filename, circuits, header=None)

Write a text-formatted circuit list file.

Parameters
  • filename (string) – The filename to write.

  • circuits (list of Circuits) – The list of circuits to include in the written dataset.

  • header (string, optional) – Header line (first line of file). Prepended with a pound sign (#), so no need to include one.

Returns

None

pygsti.io.writers.write_model(model, filename, title=None)

Write a text-formatted model file.

Parameters
  • model (Model) – The model to write to file.

  • filename (string) – The filename to write.

  • title (string, optional) – Header line (first line of file). Prepended with a pound sign (#), so no need to include one.

Returns

None

pygsti.io.writers.write_empty_protocol_data(dirname, edesign, sparse='auto', clobber_ok=False)

Write to disk an empty ProtocolData object.

Write to a directory an experimental design (edesign) and the dataset template files needed to load in a ProtocolData object, e.g. using the :function:`read_data_from_dir` function, after the template files are filled in.

Parameters
  • dirname (str) – The root directory to write into. This directory will have ‘edesign’ and ‘data’ subdirectories created beneath it.

  • edesign (ExperimentDesign) – The experiment design defining the circuits that need to be performed.

  • sparse (bool or "auto", optional) – If True, then the template data set(s) are written in a sparse-data format, i.e. in a format where not all the outcomes need to be given. If False, then a dense data format is used, where counts for all possible bit strings are given. “auto” causes the sparse format to be used when the number of qubits is > 2.

  • clobber_ok (bool, optional) – If True, then a template dataset file will be written even if a file of the same name already exists (this may overwrite existing data with an empty template file, so be careful!).

Returns

None

pygsti.io.writers.fill_in_empty_dataset_with_fake_data(dataset_filename, model, num_samples, sample_error='multinomial', seed=None, rand_state=None, alias_dict=None, collision_action='aggregate', record_zero_counts=True, comm=None, mem_limit=None, times=None, fixed_column_mode='auto')

Fills in the text-format data set file dataset_fileame with simulated data counts using model.

Parameters
  • dataset_filename (str) – the path to the text-formatted data set file.

  • model (Model) – the model to use to simulate the data.

  • num_samples (int or list of ints or None) – The simulated number of samples for each circuit. This only has effect when sample_error == "binomial" or "multinomial". If an integer, all circuits have this number of total samples. If a list, integer elements specify the number of samples for the corresponding circuit. If None, then model_or_dataset must be a DataSet, and total counts are taken from it (on a per-circuit basis).

  • sample_error (string, optional) –

    What type of sample error is included in the counts. Can be:

    • ”none” - no sample error: counts are floating point numbers such that the exact probabilty can be found by the ratio of count / total.

    • ”clip” - no sample error, but clip probabilities to [0,1] so, e.g., counts are always positive.

    • ”round” - same as “clip”, except counts are rounded to the nearest integer.

    • ”binomial” - the number of counts is taken from a binomial distribution. Distribution has parameters p = (clipped) probability of the circuit and n = number of samples. This can only be used when there are exactly two SPAM labels in model_or_dataset.

    • ”multinomial” - counts are taken from a multinomial distribution. Distribution has parameters p_k = (clipped) probability of the gate string using the k-th SPAM label and n = number of samples.

  • seed (int, optional) – If not None, a seed for numpy’s random number generator, which is used to sample from the binomial or multinomial distribution.

  • rand_state (numpy.random.RandomState) – A RandomState object to generate samples from. Can be useful to set instead of seed if you want reproducible distribution samples across multiple random function calls but you don’t want to bother with manually incrementing seeds between those calls.

  • alias_dict (dict, optional) – A dictionary mapping single operation labels into tuples of one or more other operation labels which translate the given circuits before values are computed using model_or_dataset. The resulting Dataset, however, contains the un-translated circuits as keys.

  • collision_action ({"aggregate", "keepseparate"}) – Determines how duplicate circuits are handled by the resulting DataSet. Please see the constructor documentation for DataSet.

  • record_zero_counts (bool, optional) – Whether zero-counts are actually recorded (stored) in the returned DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors and ensuring that the same dataset is generated on each processor.

  • mem_limit (int, optional) – A rough memory limit in bytes which is used to determine job allocation when there are multiple processors.

  • times (iterable, optional) – When not None, a list of time-stamps at which data should be sampled. num_samples samples will be simulated at each time value, meaning that each circuit in circuits will be evaluated with the given time value as its start time.

  • fixed_column_mode (bool or 'auto', optional) – How the underlying data set file is written - see :function:`write_dataset`.

Returns

DataSet – The generated data set (also written in place of the template file).

pygsti.io.writers.write_circuit_strings(filename, obj)

TODO: docstring - write various Circuit-containing standard objects with circuits replaced by their string reps