Molecular Feature Array Euclidean Distance Filter

A Fortran package for Hash-grid-based filtering out molecules with similar configurations in XYZ format.

Features

• XYZ trajectory file parsing
• Energy range pre-filtering
• Vector-based molecular structure representation
• Mitigation of oversampling [ref.1]
• Permutation invariance of indistinguishable atoms enforced through invariant polynomials [ref.2]
• Asymptotic complexity reduction via hash-grid-based spatial partitioning [ref.3]
• Dataset filtering and preprocessing utilities

Directory Structure

├── src/          # Fortran source files
│   ├── main.f90             # Main program
│   ├── xyz.f90              # Module
│   ├── pre.f90
│   ├── fi.f90               # Invariant polynomials
│   ├── feat.f90
│   └── filter_hash.f90      # Module
├── obj/          # Object File
├── bin/          # Example datasets
│   ├── aparameter           # parameters
│   └── euDist_filter        # Executable file
├── makefile
└── README.md

Requirements

Tested on Linux

• Intel Fortran Compiler (ifort) with full OpenMP support
• GNU Make

Compilation

make

The executable will be generated in bin/

Method

The workflow is

1. Reading geometries
2. Energy Preprocessing and Structure Loading
3. Feature Vector Generation
4. Hash-Grid Filtering

Input

1. The input trajectory should contain

• Number of Atoms in the molecule or system
• Single Point Energy (Hartree)
• Atom Symbols
• Cartesian Coordinates (Å)

Example

6
-993.123456
O   0.000  0.000  0.000
H   ...
H   ...
...

Users can modify the code to adapt to any molecular properties, such as

• Dipole Moment Components (Debye)

2. Invariants and xyz module

• The elements of a molecular feature vector are functions of the internuclear distances.
• About invariant: a function which remains unchanged when a specified transformation is applied.
• Users can implement invariants themselves in the src/fi.f90.
• The author suggests using invariant polynomials with a number (nfeat) similar to or a little more than the combination of n taken 2, where n is the number of atoms.
• Users should modify the variable named nfeat in xyz module.

e.g. H₂O

The internuclear distances are set as follows.

r(1) = r(H1-O)
r(2) = r(H2-O)
r(3) = r(H1-H2)

The Group of water is C_2v. The molecule remains unchanged after exchanging two hydrogen atoms.

p(1) = r(1) + r(2)
p(2) = r(3)
p(3) = r(1) * r(2)

The combination of 3 taken 2 is 3. So you can use the three polynomials as feature vector elements. You can also choose to use invariants with more and higher orders.

3. parameters

The input used in the program is provided in bin/aparameter.

Users can modify the following parameters:

input trajectory filename
output filename
Euclidean distance threshold
energy unit system conversion             1: au2ev, 2: au2cm, 0: au, 11:ev2au, 22:cm2au
energy preprocessing                      1: yes, 0: no
lower energy
upper energy
feature vector conversing function type   1: Exponential function, 2: Fractional functions, 3: linear functions(normally, c=1)
constant in the function

Usage

User can run the program directly,

cd bin/
./euDist_filter

or use script (recommended).

cd bin/
./run.sh

References

[1] Rongjun Chen. Fitting Potential Energy Surfaces with Fundamental Invariant Neural Network. PhD diss., Dalian Institute of Chemical Physics, Chinese Academy of Sciences. Advisor: Zhang Donghui.

[2] Bina Fu, Dong H Zhang, Accurate fundamental invariant-neural network representation of ab initio potential energy surfaces, National Science Review, Volume 10, Issue 12, December 2023, nwad321, https://doi.org/10.1093/nsr/nwad321

[3] Thomas Müller, Alex Evans, Christoph Schied, Alexander Keller. Instant neural graphics primitives with a multiresolution hash encoding. ACM Transactions on Graphics, 2022, 41(4), Article 102. https://doi.org/10.1145/3528223.3530127

Citation

If you use this code in your research, please cite this GitHub repository as https://github.com/OiChihang/EuDist_HashFilter

The author appreciates your citations.

Acknowledgments

The author gratefully acknowledges the use of the following artificial intelligence tools during the course of this work:

• ChatGPT by OpenAI (https://chat.openai.com)
• Claude by Anthropic (https://claude.ai)
• DeepSeek (https://www.deepseek.com)