ZacrosSteadyStateResults
************************

The "ZacrosSteadyStateResults" class was designed to take charge of
the job folder after executing the "ZacrosSteadyStateJob". It gathers
the information from the output files and helps to extract data of
interest from them. Every ZacrosSteadyStateJob instance has an
associated "ZacrosSteadyStateResults" instance created automatically
on job creation and stored in its results attribute. This class
extends the PLAMS Results class.

The following lines of code show an example of how to use the
"ZacrosSteadyStateResults" class:

   ss_sett = pz.Settings()
   ss_sett.turnover_frequency.nbatch = 20
   ss_sett.turnover_frequency.confidence = 0.96
   ss_sett.nreplicas = 2

   params = pz.ZacrosSteadyStateJob.Parameters()
   params.add( 'max_time', 'restart.max_time', numpy.arange(20.0, 100.0, 20.0) )
   print(params)

   ss_job = pz.ZacrosSteadyStateJob( settings=ss_sett, reference=job, parameters=params )
   results = ss_job.run()

   if ss_job.ok():
      print(results.history()[0])

      print("%8s"%"iter", "%10s"%"TOF_CO2", "%15s"%"max_time",
            "%15s"%"TOF_CO2_error", "%10s"%"conv?")

      for i,step in enumerate(results.history()):
         print("%8d"%i,
               "%10.5f"%step['turnover_frequency']['CO2'],
               "%15d"%step['max_time'],
               "%15.5f"%step['turnover_frequency_error']['CO2'],
               "%10s"%(all(step['converged'].values())))

Lines 1-11 were already discussed before (see ZacrosSteadyStateJob).
Here, the "ZacrosSteadyStateResults" object "results" is created by
calling the method "run()" of the corresponding "ZacrosSteadyStateJob"
job (line 11).

Afterward, the method "ok()" is invoked to assure that the calculation
finished appropriately (line 13), and only after that, it is good to
go to get information from the output files by using the
"ZacrosSteadyStateResults" methods (lines 14-24). In this example, we
want to print information about the history of the calculation after
each iteration. Line 14 prints the first item of the list returned by
the "history()" method to show its structure. Then after line 16, we
show this information for all iterations summarized in a table.

The execution of the code above after line 13 shows the following
information to the standard output:

   {'turnover_frequency': {'CO': -0.75409, 'O2': -0.39222, 'CO2': 0.75498},
    'turnover_frequency_error': {'CO': 0.11055, 'O2': 0.06458, 'CO2': 0.11099},
    'converged': {'CO': False, 'O2': False, 'CO2': False},
    'max_time': 20.0}

    iter    TOF_CO2        max_time   TOF_CO2_error      conv?
       0    0.75498              20         0.11099      False
       1    0.63210              40         0.03387      False
       2    0.62030              60         0.02156       True

As you can see in the output, each element of the history includes the
maximum amount of time (referred to as "max time") used in that
iteration as well as three numbers related to the turnover frequency
calculation: the value itself (referred to as "turnover frequency"),
its error (referred to as "turnover frequency error"), and a flag
(referred to as "turnover frequency converged") that denotes whether
or not the calculation has converged. Finally, lines 14-18 show the
values of "x_CO" and "TOF_CO2" for all compositions in a summary
table.


API
===

class ZacrosSteadyStateResults(job: Job)

   A Class for handling ZacrosSteadyStateJob Results.

   history(pos=None)

      Returns a list of properties related with the history of the
      calculation. Each element of the history includes the maximum
      amount of time (referred to as "max_steps", "max_time", or
      "wall_time") used in that iteration as well as three numbers
      related to the turnover frequency calculation: the value itself
      (referred to as "turnover frequency"), its error (referred to as
      "turnover frequency error"), and a flag (referred to as
      "turnover frequency converged") that denotes whether or not the
      calculation has converged.

      Example of an item of the returned history list:

         {'turnover_frequency': {'CO': -0.75409, 'O2': -0.39222, 'CO2': 0.75498},
          'turnover_frequency_error': {'CO': 0.11055, 'O2': 0.06458, 'CO2': 0.11099},
          'converged': {'CO': False, 'O2': False, 'CO2': False},
          'max_time': 20.0}

   niterations()

      Returns the current number of iterations executed

   nreplicas()

      Returns the number of replicas used

   children_results(iteration=None, replica=None)

      Returns a list of the children's results or the results for a
      specific iteration or replica if requested.

   get_zacros_version()

      Returns the zacros's version from the 'general_output.txt' file.

   get_reaction_network()

      Returns the reactions from the 'general_output.txt' file
      associated to the last children.

   provided_quantities()

      Returns the provided quantities headers from the
      "specnum_output.txt" file in a list associated to the last
      children.

   number_of_lattice_sites()

      Returns the number of lattice sites from the
      'general_output.txt' file associated to the last children.

   gas_species_names()

      Returns the gas species names from the 'general_output.txt' file
      associated to the last children.

   surface_species_names()

      Returns the surface species names from the 'general_output.txt'
      file associated to the last children.

   site_type_names()

      Returns the site types from the 'general_output.txt' file
      associated to the last children.

   number_of_snapshots()

      Returns the number of configurations from the
      'history_output.txt' file associated to the last children.

   number_of_process_statistics()

      Returns the number of process statistics from the
      'procstat_output.txt' file associated to the last children.

   elementary_steps_names()

      Returns the names of elementary steps from the
      'procstat_output.txt' file associated to the last children.

   lattice_states(last=None)

      Returns the configurations from the 'history_output.txt' file
      associated to the last children.

   last_lattice_state()

      Returns the last configuration from the 'history_output.txt'
      file associated to the last children.

   average_coverage(last=5)

      Returns a dictionary with the average coverage fractions using
      the last "last" lattice states, e.g., "{ "CO*":0.32, "O*":0.45
      }". It makes an average on the number of replicas if they were
      requested.

   plot_lattice_states(data, pause=-1, show=True, ax=None, close=False, time_perframe=0.5, file_name=None, frames=None, markers=None, marker_size=1.0, colors=None, lattice_markers=None, lattice_color='0.8')

      Uses Matplotlib to create an animation of the lattice states
      associated to the last children.

      * "data" -- List of LatticeState objects to plot

      * "pause" -- After showing the figure, it will wait
        "pause"-seconds before refreshing.

      * "show" -- Enables showing the figure on the screen.

      * "ax" -- The axes of the plot. It contains most of the figure
        elements: Axis, Tick, Line2D, Text, Polygon, etc., and sets
        the coordinate system. See matplotlib.axes.

      * "close" -- Closes the figure window after pause time.

      * "time_perframe" -- Sets the time interval between frames in
        seconds.

      * "file_name" -- Saves the figures to the file "file_name-<id>"
        (the corresponding id on the list replaces the "<id>"). The
        format is inferred from the extension, and by default, ".png"
        is used.

      * "frames" -- Optional list where each frame artists list is
        appended. Useful for "matplotlib.animation.ArtistAnimation".

      * "markers" -- List of marker styles used for site types.

      * "marker_size" -- Scale factor for marker area.

      * "colors" -- List of colors used for species.

      * "lattice_markers" -- List of marker styles used for lattice
        site types. If "None", "markers" is used.

      * "lattice_color" -- Single color used to draw lattice sites,
        lattice unit-cell lines, and lattice connections.

   plot_molecule_numbers(species_name, pause=-1, show=True, ax=None, close=False, file_name=None, normalize_per_site=False, derivative=False)

      uses Matplotlib to create an animation of the Molecule Numbers
      associated to the last children.

      * "species_name" -- List of species names to show, e.g.,
        "["CO*", "CO2"]"

      * "pause" -- After showing the figure, it will wait
        "pause"-seconds before refreshing. This can be used for crude
        animation.

      * "show" -- Enables showing the figure on the screen.

      * "ax" -- The axes of the plot. It contains most of the figure
        elements: Axis, Tick, Line2D, Text, Polygon, etc., and sets
        the coordinate system. See matplotlib.axes.

      * "close" -- Closes the figure window after pause time.

      * "file_name" -- Saves the figure to the file "file_name". The
        format is inferred from the extension, and by default, ".png"
        is used.

      * "normalize_per_site" -- Divides the molecule numbers by the
        total number of sites in the lattice.

      * "derivative" -- Plots the first derivative.

   get_process_statistics()

      Returns the statistics from the 'procstat_output.txt' file in a
      form of a list of dictionaries associated to the last children.

   plot_process_statistics(data, key, log_scale=False, pause=-1, show=True, ax=None, close=False, file_name=None)

      Uses Matplotlib to create an animation of the process statistics
      associated to the last children.

      * "data" -- List of process statistics to plot. See function
        "get_process_statistics()".

      * "key" -- Key to plot, e.g., "'average_waiting_time'",
        "'average_waiting_time'". See function
        "get_process_statistics()".

      * "log_scale" -- Use log scale for the x axis.

      * "pause" -- After showing the figure, it will wait
        "pause"-seconds before refreshing.

      * "show" -- Enables showing the figure on the screen.

      * "ax" -- The axes of the plot. It contains most of the figure
        elements: Axis, Tick, Line2D, Text, Polygon, etc., and sets
        the coordinate system. See matplotlib.axes.

      * "close" -- Closes the figure window after pause time.

      * "file_name" -- Saves the figures to the file "file_name-<id>"
        (the corresponding id on the list replaces the "<id>"). The
        format is inferred from the extension, and by default, ".png"
        is used.
