Voronoi-based Lattice Distances

Voronoi-based Lattice Distances encodes crystal lattices to Voronoi Domains and runs Voronoi-based metrics to compare them. More details on the used metrics can be found in our paper published in the Crystal Research & Technology Journal: Voronoi-Based Similarity Distances between Arbitrary Crystal Lattices.

The project has been compiled and run only on Windows x64.

Installation

1. Install Visual Studio (e.g. Community) choosing the following single components:

   • .NET SDK
   • .NET 7.0 Runtime
   • MSVC v142 - C++ Build tools
   • MSVC v143 - C++ Build tools
   • C++/CLI for Build Tools v142
   • Windows 10 SDK (10.2.20348.0)
   • CMake C++ Tools for Windows
   • Git for Windows

2. Download the repository

3. The software below must be installed through Windows installers:

   • CGAL-4.14.3-Setup.exe

     Note: Install it in VoronoiLatticeDistances\External\CGAL-4.14.3 folder and choose 64bit binaries.

   • boost_1_69_0-msvc-14.1-64.exe

     Note: Install in VoronoiLatticeDistances\External\boost_1_69_0 folder.

4. Add the following environmental variables as User:

   • VS_DIR: Path to Visual Studio with all folders (e.g. Microsoft Visual Studio\2022\Community)

5. Run the following in a Command Prompt (no PowerShell) to install it:

     "%VS_DIR%\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64
     cd VoronoiLatticeDistances/windows-setup
     dotnet build
     dotnet run
   

6. Restart the command prompt and run the executables: voronoilatticedistances.exe or voronoilatticedistances_off.exe.

Usage

To compute correctly the metrics, it is required that all input CIF files contain the primitive unit cell. Run the executable without parameters for the usage. There are following some examples.

Produce Voronoi-based metrics from CIF files on 5 threads

  .\voronoilatticedistances.exe -inputdir "path\to\cif_folder" -outputdir "path\to\output_dir" -ds -dh -threads 5

Generate OFF files of Voronoi Domains and their volumes

  .\voronoilatticedistances.exe -inputdir "path\to\cif_folder" -outputdir "path\to\output_dir" -off -vol

Generate Voronoi Domains for 3D visualization

File .vtp can be visualized with Paraview software.

  .\voronoilatticedistances.exe -inputdir "path\to\cif_folder" -outputdir "path\to\output_dir" -vtp

Produce Voronoi-based metrics from OFF files

  .\voronoilatticedistances_off.exe -inputdir "path\to\off_folder" -outputdir "path\to\output_dir" -ds -dh 

Required options:

• -inputdir [Input Folder with CIF files]
• -outputdir [Output Folder to write metric results]

Output options (at least 1 required):

• -vol Outputs .csv file with Voronoi Cell volume
• -vtp Outputs .vtp files with Voronoi Cell of a Lattice (Paraview format file)
• -csv Outputs .csv files with Lattice and Voronoi Cell points
• -off Outputs .off files with Voronoi Cell vertices and faces
• -ds Outputs .csv file with Scale Invariant Distance matrix (n x n) between all n crystal lattices
• -dh Outputs .csv file with Extended Hausdorff Distance matrix (n x n) between all n crystal lattices

Optional commands:

• -intervals [integer n (default n=2)] It affects the number of rotation samples to be considered for metric computations (total number of rotations: 4pi^2n^3)
• -threads [integer t (default t=1)] Rotation samples are divided among t threads

Example of Voronoi Domains

There are following the Voronoi domains of 5 real crystal lattices from the T2 dataset used in our experiments: T2-epsilon, T2-delta, T2-beta, T2-gamma and T2-alpha. Plus, the voronoi domains of the standard cubic, body-centred cubic and face-centred cubic lattices.

Dendrogram and Heatmap

The dendrogram and the heatmap of the Voronoi-based metrics can be generated with the following script. The input csv file is generated by the options -dh or -ds of the previous executables.

RScript.exe .\Scripts\make_dendrogram_heatmap.R [csv file]