:py:mod:`pygsti.io.stdinput`
============================

.. py:module:: pygsti.io.stdinput

.. autoapi-nested-parse::

   Text-parsing classes and functions to read input files.






Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   pygsti.io.stdinput.StdInputParser



Functions
~~~~~~~~~

.. autoapisummary::

   pygsti.io.stdinput.parse_model



.. py:class:: StdInputParser


   Bases: :py:obj:`object`

   Encapsulates a text parser for reading GST input files.

   Create a new standard-input parser object 

   .. py:attribute:: use_global_parse_cache
      :value: 'True'

      

   .. py:method:: parse_circuit(s, lookup=None, create_subcircuits=True)

      Parse a circuit from a string.

      Parameters
      ----------
      s : string
          The string to parse.

      lookup : dict, optional
          A dictionary with keys == reflbls and values == tuples of operation labels
          which can be used for substitutions using the S<reflbl> syntax.

      create_subcircuits : bool, optional
          Whether to create sub-circuit-labels when parsing
          string representations or to just expand these into non-subcircuit
          labels.

      Returns
      -------
      Circuit


   .. py:method:: parse_circuit_raw(s, lookup=None, create_subcircuits=True)

      Parse a circuit's constituent pieces from a string.

      This doesn't actually create a circuit object, which may be desirable
      in some scenarios.

      Parameters
      ----------
      s : string
          The string to parse.

      lookup : dict, optional
          A dictionary with keys == reflbls and values == tuples of operation labels
          which can be used for substitutions using the S<reflbl> syntax.

      create_subcircuits : bool, optional
          Whether to create sub-circuit-labels when parsing
          string representations or to just expand these into non-subcircuit
          labels.

      Returns
      -------
      label_tuple: tuple
          Tuple of operation labels representing the circuit's layers.
      line_labels: tuple or None
          A tuple or `None` giving the parsed line labels (follwing the '@' symbol) of the circuit.
      occurrence_id: int or None
          The "occurence id" - an integer following a second '@' symbol that identifies a particular
          copy of this circuit.
      compilable_indices : tuple
          A tuple of layer indices (into `label_tuple`) marking the layers that can be "compiled",
          and are *not* followed by a barrier so they can be compiled with following layers.  This
          is non-empty only when there are explicit markers within the circuit string indicating
          the presence or absence of barriers.


   .. py:method:: parse_dataline(s, lookup=None, expected_counts=-1, create_subcircuits=True, line_labels=None)

      Parse a data line (dataline in grammar)

      Parameters
      ----------
      s : string
          The string to parse.

      lookup : dict, optional
          A dictionary with keys == reflbls and values == tuples of operation labels
          which can be used for substitutions using the S<reflbl> syntax.

      expected_counts : int, optional
          The expected number of counts to accompany the circuit on this
          data line.  If < 0, no check is performed; otherwise raises ValueError
          if the number of counts does not equal expected_counts.

      create_subcircuits : bool, optional
          Whether to create sub-circuit-labels when parsing string representations
          or to just expand these into non-subcircuit labels.

      Returns
      -------
      circuit : Circuit
          The circuit.
      counts : list
          List of counts following the circuit.


   .. py:method:: parse_dictline(s)

      Parse a circuit dictionary line (dictline in grammar)

      Parameters
      ----------
      s : string
          The string to parse.

      Returns
      -------
      circuitLabel : string
          The user-defined label to represent this circuit.
      circuitTuple : tuple
          The circuit as a tuple of operation labels.
      circuitStr : string
          The circuit as represented as a string in the dictline.
      circuitLineLabels : tuple
          The line labels of the cirucit.
      occurrence : object
          Circuit's occurrence id, or `None` if there is none.
      compilable_indices : tuple or None
          A tuple of layer indices (into `label_tuple`) marking the layers that can be "compiled",
          and are *not* followed by a barrier so they can be compiled with following layers.  This
          is non-`None` only when there are explicit markers within the circuit string indicating
          the presence or absence of barriers.


   .. py:method:: parse_stringfile(filename, line_labels='auto', num_lines=None, create_subcircuits=True)

      Parse a circuit list file.

      Parameters
      ----------
      filename : string
          The file to parse.

      line_labels : iterable, optional
          The (string valued) line labels used to initialize :class:`Circuit`
          objects when line label information is absent from the one-line text
          representation contained in `filename`.  If `'auto'`, then line labels
          are taken to be the list of all state-space labels present in the
          circuit's layers.  If there are no such labels then the special value
          `'*'` is used as a single line label.

      num_lines : int, optional
          Specify this instead of `line_labels` to set the latter to the
          integers between 0 and `num_lines-1`.

      create_subcircuits : bool, optional
          Whether to create sub-circuit-labels when parsing
          string representations or to just expand these into non-subcircuit
          labels.

      Returns
      -------
      list of Circuits
          The circuits read from the file.


   .. py:method:: parse_dictfile(filename)

      Parse a circuit dictionary file.

      Parameters
      ----------
      filename : string
          The file to parse.

      Returns
      -------
      dict
          Dictionary with keys == circuit labels and values == Circuits.


   .. py:method:: parse_datafile(filename, show_progress=True, collision_action='aggregate', record_zero_counts=True, ignore_zero_count_lines=True, with_times='auto')

      Parse a data set file into a DataSet object.

      Parameters
      ----------
      filename : string
          The file to parse.

      show_progress : bool, optional
          Whether or not progress should be displayed

      collision_action : {"aggregate", "keepseparate"}
          Specifies how duplicate circuits should be handled.  "aggregate"
          adds duplicate-circuit counts, whereas "keepseparate" tags duplicate
          circuits by setting their `.occurrence` IDs to sequential positive integers.

      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.

      ignore_zero_count_lines : bool, optional
          Whether circuits for which there are no counts should be ignored
          (i.e. omitted from the DataSet) or not.

      with_times : bool or "auto", optional
          Whether to the time-stamped data format should be read in.  If
          "auto", then this format is allowed but not required.  Typically
          you only need to set this to False when reading in a template file.

      Returns
      -------
      DataSet
          A static DataSet object.


   .. py:method:: parse_multidatafile(filename, show_progress=True, collision_action='aggregate', record_zero_counts=True, ignore_zero_count_lines=True)

      Parse a multiple data set file into a MultiDataSet object.

      Parameters
      ----------
      filename : string
          The file to parse.

      show_progress : bool, optional
          Whether or not progress should be displayed

      collision_action : {"aggregate", "keepseparate"}
          Specifies how duplicate circuits should be handled.  "aggregate"
          adds duplicate-circuit counts, whereas "keepseparate" tags duplicate
          circuits by setting their `.occurrence` IDs to sequential positive integers.

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

      ignore_zero_count_lines : bool, optional
          Whether circuits for which there are no counts should be ignored
          (i.e. omitted from the MultiDataSet) or not.

      Returns
      -------
      MultiDataSet
          A MultiDataSet object.


   .. py:method:: parse_tddatafile(filename, show_progress=True, record_zero_counts=True, create_subcircuits=True)

      Parse a timstamped data set file into a DataSet object.

      Parameters
      ----------
      filename : string
          The file to parse.

      show_progress : bool, optional
          Whether or not progress should be displayed

      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.

      create_subcircuits : bool, optional
          Whether to create sub-circuit-labels when parsing
          string representations or to just expand these into non-subcircuit
          labels.

      Returns
      -------
      DataSet
          A static DataSet object.



.. py:function:: parse_model(filename)

   Parse a model file into a Model object.

   Parameters
   ----------
   filename : string
       The file to parse.

   Returns
   -------
   Model