morrowchem / ringsstatisticsmatter.jl

Julia implementation of algorithm for counting primitive rings in an atomistic structure. Useful for materials simulations

Julia Rings

This package provides a tool for finding primitive rings efficiently for large models of amorphous materials.

Designed for large structural models, this can handle 100,000-atoms in under 10 minutes multithreaded on a 16GB M2 Mac laptop.

This package implements an algorithm based on the work described in:

Yuan, X. & Cormack, A. N.
"Efficient Algorithm for Primitive Ring Statistics in Topological Networks.".
Computational Materials Science, vol. 24, pp. 343-360, 2002.

100k-atom model of a-Si with the 9-membered primitive rings highlighted

8k-atom model of a-C with the 5-, 6-, and 7-membered primitive rings highlighted

Features

• Python wrappers for easy plotting and incorporation into more complex analysis frameworks.
• Returns node indices for each ring in your structure
• Flexible multi-element support via ASE NeighborList (ignore or allow homopolar bonds, handle multiple custom cutoff-radii etc.)
• Shared-memory parallelism via Julia's native multithreading. Scales well up to 128 cores (and presumably beyond).

Dependencies

Before using this package, ensure you have the required Julia packages installed. Python dependencies are handled by pip.

To install Julia, use your package manager (brew, apt etc.) or visit the downloads page: https://julialang.org/downloads/

Open the Julia REPL:

julia

Install the packages:

using Pkg
Pkg.add("PyCall")
Pkg.add("JSON")
Pkg.add("Formatting")

Installation

1. Clone the repository:

   git clone --recursive [email protected]:MorrowChem/julia_rings.git
   cd julia_rings

2. Install the package using pip:

   pip install ./

3. Test (optional)

   python -m unittest

Usage

Run the provided Python script to analyze rings with 2 threads:

export JULIA_NUM_THREADS=2 && python run_rings.py structures/aSi_500atom_test.xyz

or for multi-component systems, such as phase-change material Ge-Sb-Te, ignoring homopolar bonds:

python examples/run_rings_GeSbTe.py --homopolar n structures/GST_5k_amorphous.xyz

Disclaimer

If you see non-integer entries in the ring statistics, or the nodes don't seem right, this is most likely from using small unit cells.

We try to automatically create supercells to fix this, but there may be edge cases where this isn't enough. For large enough cells, this shouldn't be an issue.

Extra Arguments

The following extra arguments can be used with the command line tool:

• --maxlvl: Specifies the maximum level of rings that can be found.
• --mxpths: If your structure has numerous neighbors and you're using a large maxlvl, consider increasing this parameter. This adjustment can help mitigate errors like BoundsError: attempt to access 1000×6 Matrix{Int64} at index [1001, 1].

Supported Platforms

This package has been tested on macOS and Linux.

Contributing

Contributions are welcome! Feel free to open issues or pull requests on the GitHub repository:

https://github.com/MorrowChem/julia_rings

License

This project is licensed under the MIT License - see the LICENSE file for details.

ringsstatisticsmatter.jl's Issues

Unreasonable results when dealing with crystal structures

Dear developers,

I used julia_rings to get ring statistics and met some problems as follows. I did tests on Si, SiO2, and Ga2O3 systems and the issues happen when dealing with crystal systems.

• For crystal silicon (diamond structure), the ring statistics are wrong when using conventional unit cell and 2 $\times$ 2 $\times$ 2 supercell, while this problem disappear when using larger supercells.
• For alpha-silica (non-orthogonal cell), the ring statistics are wrong when using small supercells and no rings can be got when using larger supercells. I also tried equivlent orthogonal cell generated by atomsk and get similar results.
• For beta-Ga2O3, the ring statistics become correct when using larger supercells. However, 2-membered ring appears and the statistics seems not reasonable when using equivlent orthogonal cell generated by atomsk. Of course, this problem might result from the orthogonal cell generation, and I am still checking it.

The above-mentioned structures are attached, the structures, ring statistics, and calculation python codes are in respective directories.

Do you have any ideas about the problems and could you help to check?

Thank you~

Lei

issue-0921.zip