diff --git a/doc/source/intro.rst b/doc/source/intro.rst index 2631016..95230ab 100644 --- a/doc/source/intro.rst +++ b/doc/source/intro.rst @@ -8,15 +8,15 @@ What is pyZacros ---------------- pyZacros (Python Library for Automating Zacros Simulation) is a collection of tools that aims to provide a powerful, flexible, and easily extendable Python interface to -`Zacros `_, a Kinetic Monte Carlo software package for simulating molecular phenomena on catalytic surfaces. pyZacros is designed as an extension of the python library `PLAMS <../plams/index.html>`_. Thereby inherits from PLAMS the robust way of managing the inputs file preparation, job execution, file management, and output file processing. Above that, it also offers the possibility of postprocessing the results and building very advanced data workflows. +`Zacros `_, a Kinetic Monte Carlo software package for simulating molecular phenomena on catalytic surfaces. pyZacros is designed as an extension of the Python library `PLAMS <../plams/index.html>`_. This will, therefore, inherit from PLAMS the robust way of managing input file preparation, job execution, file management, and output file processing. Above that, it also offers the possibility of postprocessing the results and building very advanced data workflows. The normal Zacros workflow has the following steps: -1. First, the subject of the problem (description of the system, and set of the desired simulation parameters) has to be written +1. First, the subject of the problem (description of the system and set of the desired simulation parameters) has to be written to input text files (i.e. ``energetics_input.dat``, ``mechanism_input.dat``, ``lattice_input.dat``, ``simulation_input.dat``). 2. The ``zacros.x`` program is executed and produces output text files (i.e. ``general_output.txt``, ``procstat_output.txt``, ``history_output.txt``, ``specnum_output.txt``, ``lattice_output.txt``). -3. Those output files may contain already the required information or at least contain enough information to get it after +3. Those output files may already contain the required information or at least contain enough information to get it after a postprocessing step. 4. This resultant information may be used to define parameters for further calculations. @@ -25,23 +25,23 @@ pyZacros helps with the automation of all these steps described above directly f What can be done with pyZacros ------------------------------ -As an extension of PLAMS, pyZacros is also designed under the same key design principle ... *flexibility*. -If something (and by something we mean: adjusting an input parameter, executing some program with particular options, extracting a value from output etc.) can be done by hand, it can be done with pyZacros. -The internal structure of the library was designed in a highly modular, especially an object-oriented manner. In particular, there are classes to represent species, clusters, elementary Reactions, among others that are easy to set up and use. +As an extension of PLAMS, pyZacros is also designed under the same key principle: *flexibility*. +If something (and by something, we mean adjusting an input parameter, executing a program with particular options, extracting a value from the output, etc.) can be done by hand, it can be done with pyZacros. +The library's internal structure was designed in a highly modular, especially object-oriented manner. In particular, there are classes to represent species, clusters, and elementary Reactions, among others, that are easy to set up and use. The most important features of pyZacros: -* Preparing, running and examining results of a Zacros jobs from within a single Python script +* Preparing, running, and examining results of Zacros jobs from within a single Python script * Convenient automatic file and folder management * Running jobs in parallel without a need to prepare a special parallel script * Integration with popular job schedulers (OGE, SLURM, TORQUE) * Prevention of multiple runs of the same job * Easy data transfer between separate runs -* An efficient and simple way for restarting calculation in case of a crash or just to extend the simulation. +* An efficient and simple way to restart the calculation in case of a crash or extend the simulation. * Almost full coverage of all input options and output data in Zacros. * Visualization and interactive building of the lattice of the system. * Default plot functions to visualize results like adlayer configurations, process statistics, and species numbers. -* Reconstruction of the pyZacros objects from Zacros calculation which were not managed by pyZacros. +* Reconstruction of the pyZacros objects from Zacros calculation, which were not managed by pyZacros. .. _simple_example: @@ -55,11 +55,11 @@ The ZGB model includes (see the script below): 1. Three gas species: CO, O\ :sub:`2`, and CO\ :sub:`2`. (Lines 5-7) 2. Three surface species: \*, CO\*, O\*. (Lines 10-12) -3. A rectangular lattice with a single site type. (Lines 15-16) +3. A rectangular lattice with a single site type. (Line 15) 4. Two clusters are included in the cluster-expansion Hamiltonian approach for the energetics. The CO* and O* individual - adsorbates (without lateral interactions) with 1.3 eV and 2.3 eV, binding energies, respectively. (Lines 20-21) + adsorbates (without lateral interactions) with 1.3 eV and 2.3 eV binding energies, respectively. (Lines 19-20) 5. Three irreversible events: non-dissociative adsorption of CO, dissociative adsorption of O2, and fast reaction between - an O adatom and a CO adsorbate. (Lines 24-31) + an O adatom and a CO adsorbate. (Lines 23-43) .. literalinclude:: ../../examples/intro/intro0.py :language: python @@ -67,16 +67,16 @@ The ZGB model includes (see the script below): Don't worry if something in the above code is incomprehensible or confusing. Everything you need to know to understand how pyZacros works and how to write your own scripts is explained -in next chapters of this documentation. +in the next chapters of this documentation. -By executing the above script, you are going to see a visual representation of the lattice (see script's line 17) that should +By executing the above script, you are going to see a visual representation of the lattice (see script's line 16) that should be similar to the image below: .. figure:: ../images/ZGB-lattice.png :scale: 80 % :align: center -Then, you should see the plot of the number of molecules of each kind as a function of time during the simulation. We have split this information into two Figures for clarity, one for gas-phase species and the other one for surface species, as follows (see script's line 55-56): +Then, you should see the plot of the number of molecules of each kind as a function of time during the simulation. We have split this information into two Figures for clarity, one for gas-phase species and the other one for surface species, as follows (see script's line 65-66): .. figure:: ../images/ZGB-mol_gas_nums.png :scale: 80 % @@ -86,7 +86,7 @@ Then, you should see the plot of the number of molecules of each kind as a funct :scale: 80 % :align: center -During the execution the following information is written to the standard output: +During the execution, the following information is written to the standard output: .. code-block:: none :linenos: