Elementary Reaction / Mechanism
*******************************

"ElementaryReaction" class allows to define reversible and/or
irreversible elementary steps for adsorption of molecules on surface
sites, desorption from there, diffusion from one site to a neighboring
site, or reactions between adsorbed particles and gas species.
"ElementaryReaction" class has a one-to-one relation with the sections
"steps" and "reversible_step" in Zacros' input files.

For our example (see use case system), we need to create three
irreversible events:

1. Non-dissociative adsorption of CO: "CO(g) + * 🠒 CO*"

2. Dissociative adsorption of O_2: "O2(g) + * + * 🠒 O* + O*"

3. Fast reaction between an O adatom and a CO adsorbate to produce
   CO_2: "O* + CO* 🠒 * + * + CO2(g)"

This can be achieved by using the lines 1-10 of following code:

   # Elementary Reactions
   CO_ads = pz.ElementaryReaction( initial=[s0, CO_g], final=[CO_s],
                                   reversible=False, pre_expon=10.0,
                                   label="CO_adsorption" )

   O2_ads = pz.ElementaryReaction( initial=[s0, s0, O2_g], final=[O_s, O_s],
                                   neighboring=[(0,1)],
                                   reversible=False, pre_expon=2.5,
                                   label="O2_adsorption" )

   CO_oxi = pz.ElementaryReaction( initial=[CO_s, O_s], final=[s0, s0, CO2_g],
                                   neighboring=[(0,1)],
                                   reversible=False, pre_expon=1.0e+20,
                                   label="CO_oxidation")

   mech = pz.Mechanism([O2_ads, CO_ads, CO_oxi])

   print(mech)

Here, we have also introduced the class "Mechanism", which is formally
a list of "ElementaryReaction" objects (see line 16). But, it allows
looking at the Zacros code that will be generated by using the
"print()" function (see line 18). The execution of the previous lines
show the following on the standard output:

   mechanism

     step O2_adsorption
       gas_reacs_prods O2 -1
       sites 2
       neighboring 1-2
       initial
         1 * 1
         2 * 1
       final
         1 O* 1
         2 O* 1
       site_types 1 1
       pre_expon  2.50000e+00
       activ_eng  0.00000e+00
     end_step

     step CO_adsorption
       gas_reacs_prods CO -1
       sites 1
       initial
         1 * 1
       final
         1 CO* 1
       site_types 1
       pre_expon  1.00000e+01
       activ_eng  0.00000e+00
     end_step

     step CO_oxidation
       gas_reacs_prods CO2 1
       sites 2
       neighboring 1-2
       initial
         1 CO* 1
         2 O* 1
       final
         1 * 1
         2 * 1
       site_types 1 1
       pre_expon  1.00000e+20
       activ_eng  0.00000e+00
     end_step

   end_mechanism

Please consult Zacros' user guide
("$AMSHOME/scripting/scm/pyzacros/doc/ZacrosManual.pdf") for more
details about the specific meaning of the keywords used in the
previous lines.


API
===

class ElementaryReaction(initial, final, site_types=None, initial_entity_number=None, final_entity_number=None, neighboring=None, reversible=True, pre_expon=0.0, pe_ratio=0.0, activation_energy=0.0, prox_factor=None, label=None)

   Creates a new ElementaryReaction object

   * "initial" -- List of species bound to the sites in the initial
     state, e.g. "[ Species("H*",1), Species("H*",1) ]". Gas species
     have to be added at the end of the list.

   * "final" -- Same as "initial" but for the final state.

   * "site_types" -- Specifies the name of the sites in the graph
     pattern, e.g. "['fcc','hcp']". Notice that the order is essential
     and it should agree with the "initial" and "final" options.

   * "initial_entity_number" -- List of the molecular entities ids
     bound to each site. For example, if a bidentate species is bound
     to sites 1 and 2 ( "species=[ Species("H**",2), Species("H**",2)
     ]" ), both of these sites will have the same entity numbers, i.e.
     "entity_number=[0,0]". By default, the list of entity numbers is
     created by assuming that species with the same symbol belong to
     the same entity.

   * "final_entity_number" -- Same as "initial_entity_number" but for
     the final state.

   * "neighboring" -- Specifies the neighboring between sites, if more
     than one sites appear in the graph pattern, e.g. [ (0,1) ]

   * "reversible" -- Sets the reaction as a reversible step.

   * "pre_expon" -- Specifies the pre-exponential in the Arrhenius
     formula giving the rate constant of that elementary step. Units:
     1/s or Hz.

   * "pe_ratio" -- Sets the ratio of forward over reverse pre-
     exponential terms if the reaction is reversible.

   * "activation_energy" -- Sets the activation energy at the zero
     coverage limit. Units eV.

   * "prox_factor" -- The proximity factor used in the BEP
     relationship to calculate the forward (and also reverse, if
     applicable) activation energy.

   * "label" -- If None, a unique label is generated based on the
     label of its initial and final states.

   label()

      Returns the label of the cluster

   site_types_set()

      Returns the set of the sites types

   replace_site_types(site_types_old, site_types_new)

      Replaces the site types names

      * "site_types_old" -- List of strings containing the old
        site_types to be replaced

      * "site_types_new" -- List of strings containing the new
        site_types which would replace old site_types_old.

class Mechanism(data=[], fileName=None, gas_species=None, surface_species=None)

   Creates a new Mechanism object. If no argument is given, the
   constructor creates a new empty mechanism.

   * "data" -- List of elementary reactions to initialize the
     mechanism.

   * "fileName" -- Path to the zacros file name to load the mechanism,
     typically "mechanism_input.dat"

   * "gas_species" -- Gas species. It is required if the option
     "fileName" was used.

   * "surface_species" -- Surface species. It is required if the
     option "fileName" was used.

   __fromZacrosFile(fileName, gas_species, surface_species)

      Creates a Mechanism from a Zacros input file mechanism_input.dat

   append(item)

      Append item to the end of the sequence

   extend(other)

      Extend sequence by appending elements from the iterable

   insert(i, item)

      Insert value before index

   surface_species()

      Returns the surface species list.

   gas_species()

      Returns the gas species list.

   species()

      Returns the adsorbed species.

   site_types_set()

      Returns the set of the sites types

   replace_site_types(site_types_old, site_types_new)

      Replaces the site types names

      * "site_types_old" -- List of strings containing the old
        site_types to be replaced

      * "site_types_new" -- List of strings containing the new
        site_types which would replace old site_types_old.

   find(label)

      Returns the list of reactions where the substring "label" is
      found in the reactions' label

   find_one(label)

      Returns the first reaction where the substring "label" is found
      in the reaction's label
