A significant result from a KMC simulation is how the different sites in the lattice are populated as a function of time. During a Zacros simulation, Zacros takes snapshots of the lattice state and writes them in the file history_output.txt. Parallelly pyZacros stores each snapshot as a LatticeState object (see ZacrosResults) for further analysis and/or use on the python side. Another important application of LatticeState objects is that they can be used as initial states, either as objects from a previous simulation or built from scratch.

For our example (see use case system), we will use the LatticeState class to build a lattice state from scratch, and use it as the initial state.


pyZacros (and Zacros) will start with an empty lattice if not stated otherwise.

We are going to make the initial state as a randomly populated lattice by CO* and O* with a given coverage:

 # LatticeState setup (initial state)
 ist = pz.LatticeState(lat, surface_species=spl.surface_species())
 ist.fill_sites_random(site_name='StTp1', species='CO*', coverage=0.1)
 ist.fill_sites_random(site_name='StTp1', species='O*', coverage=0.1)



Similarly to the other classes, the function print() (see line 6) allows taking a look at the Zacros code that will be internally generated, which for this example is the following:

  # species * CO* O*
  # species_numbers
  #   - CO*  12
  #   - O*  11
  seed_on_sites CO* 1
  seed_on_sites CO* 4
  seed_on_sites O* 6
  seed_on_sites O* 10
  seed_on_sites O* 20
  seed_on_sites CO* 30
  seed_on_sites CO* 43
  seed_on_sites O* 48
  seed_on_sites O* 52
  seed_on_sites CO* 55
  seed_on_sites O* 58
  seed_on_sites CO* 62
  seed_on_sites CO* 69
  seed_on_sites CO* 70
  seed_on_sites O* 72
  seed_on_sites CO* 73
  seed_on_sites CO* 78
  seed_on_sites CO* 93
  seed_on_sites O* 99
  seed_on_sites O* 106
  seed_on_sites O* 109
  seed_on_sites O* 110
  seed_on_sites CO* 115

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.

Finally, to visualize the lattice you can make use of the function plot() (see line 8). The result is as follows:



To visualize the previous figure, be sure you have matplotlib installed.


class LatticeState(lattice, surface_species, initial=True, add_info=None)

LatticeState class represents the lattice state at a specific time during a Zacros simulation. Fundamentally contains information about which species populate the particular sites in the lattice. LatticeStates objects can be used for visualization/analysis purposes or as initial states for a new ZacrosJob.

  • lattice – Reference lattice
  • surface_species – List of allowed surface species, e.g., [ Species("H*"), Species("O*") ]
  • initial – If True, it indicates that the state represents an initial state. This is used to create the Zacros input files. If the state is an initial state the corresponding block in the Zacros input files is initial_state ... end_initial_state, otherwise state ... end_state is used.
  • add_info – A dictionary containing additional information. For example, self.add_info['time'] will be used as part of the title in the figure generated by the function plot().

Returns True if the state is empty


Returns the number of filled sites on the lattice

fill_site(site_number, species, update_species_numbers=True)

Fills the site_number site with the species species

  • site_number – Integer number indicating the site id to be filled.
  • species – Species to be used to fill the site, e.g., Species("O2*"), or "O2*".
  • update_species_numbers – Forces to update the statistics about the number of species adsorbed in the lattice. For better performance, it would be wise to set it to False if a massive number of species are going to be added (one by one) using this function.
fill_sites_random(site_name, species, coverage, neighboring=None)

Fills the named sites site_name randomly with the species species by keeping a coverage given by coverage. Coverage is defined relative to the available empty sites. Neighboring can be specified if the sites are not neighboring linearly, but are branched or cyclical.

  • site_name – Name of the sites to be filled, e.g., ["fcc","hcp"]
  • species – Species to be used to fill the site, e.g., Species("O2*"), or "O2*".
  • coverage – A number between 0.0 and 1.0 represents the expected coverage. The function will try to generate coverage as close as possible to this number.
  • neighboring – Neighboring relations associated to the sites site_name, e.g., [[0,2],[1,2]].
fill_all_sites(site_name, species)

Fills all available named sites site_name with the species species.

  • site_name – Name of the sites to be filled, e.g., ["fcc","hcp"]
  • species – Species to be used to fill the site, e.g., Species("O2*"), or "O2*".

Returns a dictionary with the coverage fractions, e.g., { "CO*":0.32, "O*":0.45 }

plot(pause=-1, show=True, ax=None, close=False, show_sites_ids=False, file_name=None)

Uses matplotlib to visualize the lattice state

  • 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.
  • show_sites_ids – Shows the binding sites id on the figure.
  • file_name – Saves the figure to the file file_name. The format is inferred from the extension, and by default, .png is used.