:py:mod:`pygsti.io.writers` =========================== .. py:module:: pygsti.io.writers .. autoapi-nested-parse:: Functions for writing GST objects to text files. Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: pygsti.io.writers.write_empty_dataset pygsti.io.writers.write_dataset pygsti.io.writers.write_multidataset pygsti.io.writers.write_circuit_list pygsti.io.writers.write_model pygsti.io.writers.write_empty_protocol_data pygsti.io.writers.fill_in_empty_dataset_with_fake_data pygsti.io.writers.convert_circuits_to_strings pygsti.io.writers.write_circuit_strings .. py:function:: 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 .. py:function:: 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 :). 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: 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 .. py:function:: write_empty_protocol_data(dirname, edesign, sparse='auto', clobber_ok=False) Write to disk an empty :class:`ProtocolData` object. Write to a directory an experimental design (`edesign`) and the dataset template files needed to load in a :class:`ProtocolData` object, e.g. using the :func:`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 .. py:function:: 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 :class:`~pygsti.objects.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 :func:`write_dataset`. Returns ------- DataSet The generated data set (also written in place of the template file). .. py:function:: convert_circuits_to_strings(obj) Converts a list or dictionary potentially containing Circuit objects to a JSON-able one with circuit strings. Parameters ---------- obj : list or tuple or dict The object to convert. Returns ------- object A JSON-able object containing circuit string representations in place of Circuit objects. .. py:function:: write_circuit_strings(filename, obj) TODO: docstring - write various Circuit-containing standard objects with circuits replaced by their string reps