Lattice

The Lattice class defines the lattice structure on which species can bind, diffuse and react. There are several ways to specify the lattice structure. They are defined in a correspondence one-to-one with the conventions used in the Zacros’ input files. See the API section below for a detailed description of these three ways: 1) Default Lattices, 2) Unit-Cell-Defined Periodic Lattices, and 3) Explicitly Defined Custom Lattices.

Following our example (see use case system), we just need a single-site lattice with a coordination number of 3, a lattice constant equal to 1.0, and a modest number of copies of the unit cell 10x3:

1
2
3
4
5
6
7
# Lattice setup
lat = pz.Lattice( lattice_type=pz.Lattice.TRIANGULAR,
                  lattice_constant=1.0, repeat_cell=[10,3] )

print(lat)

lattice.plot()

The previous lines produce the following output:

lattice default_choice
triangular_periodic 1.0 10 3
end_lattice

In addition to the capabilities of building lattices, pyZacros also offers a way to visualize them by calling the function plot(). e.g., see line 7 of the script above. This line produces the following figure:

/scm-uploads/doc.2024/pyzacros/_images/lattice.png

API

class Lattice(**kwargs)

Lattice class that defines the lattice structure on which species can bind, diffuse and react. As in Zacros’ original input files, there are four different ways of specifying a lattice structure. Below we describe these four ways with the corresponding parameters as well with examples of use.

Default Lattices:

  • lattice_type – Define the lattice to use. Possible options are:

    • Lattice.TRIANGULAR: Specifies a lattice with coordination number 3. The unit cell is not the primitive cell. The obtained unit cell is a rectangular cell containing 4 sites.

    • Lattice.RECTANGULAR: Specifies a lattice with coordination number 4. The unit cell contains 1 site. The unit cell is the primitive cell.

    • Lattice.HEXAGONAL: Specifies a lattice with coordination number 6. The unit cell is not the primitive cell. The obtained unit cell is a rectangular cell containing 2 sites.

  • lattice_constant – Defines the lattice constant (in angstrom).

  • repeat_cell – The number of repetitions of the unit cell in the horizontal and vertical.

Example:

lattice = Lattice( lattice_type=Lattice.HEXAGONAL, lattice_constant=1.0, repeat_cell=[4,5] )
/scm-uploads/doc.2024/pyzacros/_images/lattice_default.png

Unit-Cell-Defined Periodic Lattices:

  • cell_vectors – Define the unit vectors. e.g. [[0.123, 0.000],[1.234,1.234]]

  • repeat_cell – The number of repetitions of the unit cell in the directions of unit vectors. e.g. (10,10)

  • site_types – The names of the different site types. e.g. [ "cn2", "br42", "cn2" ]

  • site_coordinates – Pairs of real numbers specifying the “fractional coordinates” of each site in the unit cell. e.g. [ (0.123,0.894), (0.456,0.123) ]

  • neighboring_structure – Defines a neighboring structure block. e.g. [ ((0,0),Lattice.NORTH), ((0,1),Lattice.NORTHEAST) ]

Example:

lattice = Lattice( cell_vectors=[[2.77185866, 0.00000000],[1.38592933, 2.40050002]],
                   repeat_cell=[2, 2],
                   site_types=["b", "h", "b", "b", "f", "t"],
                   site_coordinates=[[0.00001, 0.49999],
                                     [0.33333, 0.33333],
                                     [0.49999, 0.00001],
                                     [0.49999, 0.49999],
                                     [0.66667, 0.66667],
                                     [0.99999, 0.00001]],
                   neighboring_structure=[ [(0,1), Lattice.SELF],
                                           [(1,2), Lattice.SELF],
                                           [(1,3), Lattice.SELF],
                                           [(3,4), Lattice.SELF],
                                           [(4,2), Lattice.NORTH],
                                           [(4,0), Lattice.EAST],
                                           [(5,5), Lattice.NORTH],
                                           [(5,5), Lattice.EAST],
                                           [(5,4), Lattice.SELF],
                                           [(5,1), Lattice.SELF],
                                           [(5,1), Lattice.EAST],
                                           [(5,4), Lattice.SOUTHEAST],
                                           [(5,1), Lattice.SOUTHEAST],
                                           [(4,5), Lattice.NORTH],
                                           [(5,5), Lattice.SOUTHEAST] ] )
/scm-uploads/doc.2024/pyzacros/_images/lattice_unit_cell.png

Explicitly Defined Custom Lattices:

  • site_types – The names of the different site types. e.g. [ "cn2", "br42" ]

  • site_coordinates – Pairs of real numbers specifying the “fractional coordinates” of each site in the unit cell. e.g. [ (0.123,0.894), (0.456,0.123) ]

  • nearest_neighbors – Defines the neighboring structure. e.g. [ (2,6), (2,4,7,8) ]

  • cell_vectors – Define the unit vectors. Optional

Example:

lattice = Lattice( site_types=["cn2", "br42", "cn4", "br42", "cn2", "br42",
                                  "br44", "br44", "br42", "cn4", "br44", "cn4",
                                  "br42", "br42", "cn2"],
                   site_coordinates=[[0.0000e+0, 0.0000e+0],
                                     [1.4425e+0, 0.0000e+0],
                                     [2.8850e+0, 0.0000e+0],
                                     [4.3275e+0, 0.0000e+0],
                                     [5.7700e+0, 0.0000e+0],
                                     [7.2125e-1, 1.2492e+0],
                                     [2.1637e+0, 1.2492e+0],
                                     [3.6062e+0, 1.2492e+0],
                                     [5.0487e+0, 1.2492e+0],
                                     [1.4425e+0, 2.4985e+0],
                                     [2.8850e+0, 2.4985e+0],
                                     [4.3275e+0, 2.4985e+0],
                                     [2.1637e+0, 3.7477e+0],
                                     [3.6062e+0, 3.7477e+0],
                                     [2.8850e+0, 4.9970e+0]],
                   nearest_neighbors=[[ 1,  5],
                                      [ 0,  2],
                                      [ 1,  3,  6, 7],
                                      [ 2,  4],
                                      [ 3,  8],
                                      [ 0,  9],
                                      [ 2,  9],
                                      [ 2, 11],
                                      [ 4, 11],
                                      [ 5,  6, 10, 12],
                                      [ 9, 11],
                                      [ 7,  8, 10, 13],
                                      [ 9, 14],
                                      [11, 14],
                                      [12, 13]] )
/scm-uploads/doc.2024/pyzacros/_images/lattice_custom.png

From a Zacros input file:

  • fileName – Path to the zacros file name, typically lattice_input.dat

Example:

lattice = Lattice( fileName='mypath/lattice_input.dat' )
__fromZacrosFile(fileName)

Creates a Lattice from a Zacros input file lattice_input.dat

add_site_type(site_type, coordinates, precision=0.01)

Adds a new site only if this is not already included in the lattice. It returns the id of the site

  • site_type – Site type name, e.g. ‘StTp1’

  • coordinates – 2D vector representing the site position, e.g. [0.0, 0.5]

  • precision – Precision used to determine (based on the coordinates) if the site is already

    or not contained on the list of sites. Default: 0.01

add_nearest_neighbor(id_site, id_neighbor)

Adds a new nearest-neighbor item to the lattice, e.g. (1,3)

  • id_site – Site id, e.g. 1

  • id_neighbor – id of the new site neighbor, e.g. 3

extend(other, precision=0.1, cell_vectors_precision=0.01)

Extends the sites and corresponding neighboring information by appending the equivalent items from another lattice.

  • other – Lattice to append

  • precision – Precision used to determine (based on the coordinates) if the site is already or not contained on the list of sites. Default: 0.1

  • cell_vectors_precision – Precision used to determine cell_vectors are the same or not. Default: 0.01

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

Uses Matplotlib to visualize the lattice. Be sure that Matplotlib is installed in your system; otherwise, the function does nothing.

  • 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.

  • color – Uses the same color for both binding sites and connections; e.g. ‘k’. See matplotlib.colors.

  • 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.

number_of_sites()

Returns the total number of sites

site_types_set()

Returns the set of the sites types

set_repeat_cell(repeat_cell)

Set the parameter repeat_cell and update all internal information

  • repeat_cell – The number of repetitions of the unit cell in the directions of unit vectors. e.g. (10,10)

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.