Using Zeo++

The main Zeo++ utility works in a text terminal and can be called by executing the "network" binary. The to-be-analyzed materials' structures have to be provided in one of compatible file formats. For a detail documentation of the program's functions as well as the graphical user interface (ZeoVis) please check the readme files coming with the source, or simply contact Maciej Haranczyk.

In the following sections, the basic Zeo++ functionality is presented. It can serve as a crash-course. Each section discusses a general syntax requires to call a specific functionality, e.g. calculation of pore diameters or accessible volume, followed by a specific example of EDI zeolite. The CSSR files for EDI zeolites can be downloaded here and immediately tested.

Before you start

In typical calculations, Zeo++ needs to know radii and masses of atoms involved. Masses and radii for all elements have been encoded. For radii, the set provided by the Cambridge Crystalography Data Center (CCDC) has been implemented and it is used by default. In some cases, however, the to-be-analyzed system has atoms, which names do not correspond to known elements, e.g. "Atm1" or "N12", or simple the default values needs to be overriden. In these cases, the user can define radii and masses by providing additional files. Otherwise, the code has to be executed with additional "-nomass" and/or "-nor" parameters.
The format of the mass and radii files is simple. In each line, in two columns, atom name and the corresponding, respectively, mass or radius is specified. The corresponding, respectively, "mass.mass" and "rad.rad" files are specified during the execution of the code: ./network -r rad.rad -mass mass.mass ...

Warning: The Voronoi decomposition underlying majority of algorithms implemented in Zeo++ can be performed by either using radii of atom or not. By default, radii are used and the Voronoi decomposition is approximated through the radical approximation. The latter can lead to errors in predicted pore dimaters and pore accessiblity if the system contains atoms of unequal radii. In these cases, we strongly advise to run the code with additonal "-ha" parameter, which should decrease maximum expected errors to below 0.1 Ang. Alternatively, point particle approximation can be used (all atomic radii set to zero) when "-nor" parameter is used.


Examples discussed in this document: Pore diameters | Dimensionality of channels | Surface area | Accessible volume | Pore size distribution | Stochastic ray tracing | Distance grids | Accessing the structure and Voronoi network data |

If you wish to use other Zeo++ functionality, i.e. diversity selection, will you please contact Maciej Haranczyk.

Please note that the examples discussed below are run using the default CCDC radii. In case of all silicious zeolite EDI, radii of O and Si atoms are 1.52 and 2.1 Ang, respectively. Therefore, the high accuracy "-ha" flag is used.

Pore diameters

To calculate diameters of the largest included sphere, free sphere and included sphere along free sphere path please use the following syntax:

./network -ha -res output_file.res input_structure.cssr

As the result output_file.res is written. It contains three numbers, diameters of, respectively, the largest included sphere, the largest free sphere and the largest included sphere along free sphere path. In fact, filename output_file.res is optional. If it is not provided, the results are written to input_structure.res


./network -ha -res EDI.cssr

gives the following results in the EDI.res file:

     EDI.res    4.89082 3.03868  4.81969

The first column containing the filename may seem redundant. However, it turns very useful when hundreds of .res files are catenated into large data files (For example, cat *.res > final_results_table.txt). The output filename can be changed. For example, the results will be written to EDI_output.res file, if the following parameters are used:

./network -ha -res EDI_output.res EDI.cssr

There is also an alternative option to print extended output, "-resex", which provides the largest free and included sphere diameters for each of crystalographic directions (see original Zeo++ publication for details).

Channel identification and dimensionality

For a given spherical probe of a radius probe_radius, Zeo++ can analyze the void space accessible to this probe. Each identified channel system is characterized by dimensionality as well as Di, Df and Dif. Syntax:

./network -chan probe_radius input_structure.cssr

An example analysis for a probe of radius of 1.5A roughly corresponding to CO2:

./network -ha -chan 1.5 EDI.cssr

gives the following results saved in the EDI.chan file:

EDI.chan   1 channels identified of dimensionality 1
Channel  0  4.89082  3.03868  4.89082

The default output filename (here EDI.chan) can be changed to another filename, EDI_output.chan, by using:

./network -ha -chan 1.5 EDI_output.chan EDI.cssr

Surface area

Zeo++ can calculate surface area accessible to a spherical probe of a radius probe_radius. The calculation is performed in two steps. First, the accessibility of pores in determined. Then, a Monte Carlo sampling procedure is employed to integrate surface area. The radii used in both steps do not have to be the same number though there are certain limitations discussed below. Syntax:

./network -sa chan_radius probe_radius num_samples input_structure.cssr

chan_radius is the radius of a probe used to determine accessibility of the void space. probe_radius is the radius of a probe used in Monte Carlo sampling of surface (probe_radious has to be equal or smaller than chan_radius, equal is advised unless you are a "pro" user). Variable num_samples sets number of MC samples per atom. The, which is the name of a file to which results are to be written is optional. If not provided, by default, the output will be written to

An example analysis of calculation of surface area accessible to a probe of radius of 1.2A (again, it is advised to keep chan_radius=probe_radius):

./network -ha -sa 1.2 1.2 2000 EDI.cssr

gives the file containing:

@ Unitcell_volume: 307.484   Density: 1.62239   
ASA_A^2: 60.7713 ASA_m^2/cm^3: 1976.4 ASA_m^2/g: 1218.21
NASA_A^2: 0 NASA_m^2/cm^3: 0 NASA_m^2/g: 0

where accessible surface area (ASA) and non-accessible surface area (NASA, corresponding to surface area inside inaccessible pockets) is provided in different units (respectively, surface area per unit cell, surface area in square meters per volume (in cubic cm) and mass (in grams) of a material). The output is formated as a single line starting with "@". This is to facilitate work with many output files, which can be converted into a single summary file by one simple command. For example: grep "@" *.sa > final_summary_file.txt

The newer versions of Zeo++ has additional information about the surface area. Contributions to ASA and NASA are printed for each channel and pocket, respectively.

Number_of_channels: 1 Channel_surface_area_A^2: 60.7713
Number_of_pockets: 0 Pocket_surface_area_A^2:

Accessible volume

The syntax of a command to calculate accessible volume is similar syntax of surface area calculation (with the same recommendation to keep chan_radius and probe_radius equal):

./network -vol chan_radius probe_radius num_samples outputfile.vol input_structure.cssr

However, in this case the num_samples variable sets a number of Monte Carlo samples per unit cell. The outfile.vol parameter, which is the name of a file to which results are to be written, is optional.

An example calculation of accessible volume accessible to a probe of radius of 1.2A:

./network -ha -vol 1.2 1.2 50000 EDI.cssr

gives the EDI.vol file containing:

@ EDI.vol Unitcell_volume: 307.484   Density: 1.62239   
AV_A^3: 22.6493 AV_Volume_fraction: 0.07366 AV_cm^3/g: 0.0454022
NAV_A^3: 0 NAV_Volume_fraction: 0 NAV_cm^3/g: 0

where accessible volume (AV) and non-accessible volume (NAV, corresponding to volume of non-accessible pockets) is provided in three different units: respectively, volume per unit cell, void fraction and volume per mass of a material. Again, similarly to the output of surface area calculation the format is single line starting with "@" character.

The newer versions of Zeo++ has additional information about the accessible volume. Contributions to AV and NAV are printed for each channel and pocket, respectively.

Number_of_channels: 1 Channel_volume_A^3: 22.6493
Number_of_pockets: 0 Pocket_volume_A^3:

Pore size distribution

The syntax of a command to calculate pore size distribution histogram is similar syntax of accessible volume (with the same recommendation to keep chan_radius and probe_radius equal):

./network -psd chan_radius probe_radius num_samples outputfile.psd input_structure.cssr

where num_samples variable sets a number of Monte Carlo samples per unit cell. The outfile.psd parameter, which is the name of a file to which results are to be written, is optional.

An example calculation of pore size distribution to a probe of radius of 1.2A:

./network -ha -psd 1.2 1.2 50000 EDI.cssr

gives the EDI.psd_histo file containing histograms. Typically, the "deriviative distribution" (change of accessible volume with respect to probe size) is analyzed and it can be found in the fouth column of the histogram file. By default, histogram has 1000 bins of size of 0.1 Ang (to change these setting, the source code needs to be alterd).

Stochastic ray tracing

Stochastic ray tracing histograms provie another approach to create histograms representing the void space. The algorithm shoots random rays through accesible volume of cell until hits atoms, and it records their lenghts to provide the corresponding histogram. The synthax and restrictions on the used probe radii are the same as in the case of accessible volume calculation:

./network -ray_atom chan_radius probe_radius num_samples outputfile.ray input_structure.cssr

Distance grids

Distance grids in which each grid point is assigned the distance to the surface of its nearest atom (alternatively, to the center of the nearest atom if "-nor" flag is specified) are often used for visualization. Zeo++ can save grids in both Gaussian Cube format and BOV format. The first one can be easily displayed in VMD while the second one is suitable for VisIT. The synthax is respectively:

./network -gridG input_structure.cssr
./network -gridBOV input_structure.cssr

"-grid" will save the grid file in .cube format using Ang as units; to generate the cube file in Bohr units, use "-gridGBohr" instead. "-gridBOV" will save two files: one .bov header file and other binary data file. By default, the grid resolution is set to 0.2 Ang. It can be changed by altering the source code (

Accessing structure data and the Voronoi network

Zeo++ can be also used to convert an input file with structure, i.e. CSSR file, to other file formats. Two formats with Cartesian coordinates of atoms are available: standard .xyz format used in the most of molecular visualization codes and our .v1 format. The latter is similar to .xyz but also contains unit cell vectors. To generate .xyz and .v1 files for our example EDI.cssr file, please use:

./network -xyz EDI.cssr
./network -v1 EDI.cssr

The Voronoi network obtained for a given structure can be saved in our .nt2 file format. It contains information on all nodes and edges in the network. Each nodes is characterized by a position in Cartesian coordinates, a distance to the nearest atom, node connectivity. Each edge is characterized by a pair of nodes its connected to, its restricting distances and lenght. To save .nt2 files for the example EDI.cssr file use:

./network -r -nt2 EDI.cssr

Please note that "-r" parameter requests radial Voronoi decomposition, i.e. atomic radii are used. The distances to atoms in the resulting .nt2 files will then be the distances to the atomic surface. Specifying "-nor" will request standard Voronoi decomposition with point particles in place of atoms. Then, the distances will be defined as distances to the center of atoms.