msg-byu / symlib

Spacegroup finder. Includes symmetry-related routines for cluster expansion and other codes that rely on symmetries of lattices and crystals.

symlib

Symmetry-related routines for cluster expansion and other codes that rely on symmetries of lattices and crystals. This code was started by GLWH in 1997 with help from Harold Stokes (Mr. Isotropy, see iso.byu.edu). It now includes a number of numerical and combinatorial routines that have been useful in developing UNCLE (the UNiversal CLuster Expansion code). The enum project also relies on this library.

Some key algorithms found in symlib include:

• HermiteNormalForm algorithm that finds the Hermite Normal Form of a 3x3 integer matrix.

• SmithNormalForm algorithm that finds the Smith Normal Form of a 3x3 integer matrix.

• get_spaceGroup which finds the space group of a given crystal.

• get_lattice_pointGroup which finds the point group of a lattice.

• minkowski_reduce_basis which performs minkowski reduction on a lattice to minimize the lengths of each vectors in the basis.

Compiling symlib

symlib ships with a Makefile in the src/ directory. Although it has several rules for different use cases, for a quickstart, just type:

cd src/
make F90=[gfortran|ifort]

This will generate libraries libutils.a libsym.a libcomparestructs.a librational.a libcombinatorics.a. For API references on these libraries (which have to still be generated using fortpy), check out the wiki page.

Running the Unit Tests

symlib is ~10% unit tested. Tests can be run using fortpy. We recommend using a virtualenv to run all the unit tests.

pip install fortpy
cd symlib
runtests.py src/

This will compile a series of drivers to test the symlib codes in a directory at staging/. Any errors or warnings generated will be redirected to stdout.

Troubleshooting

So far, no one has ever had any problems installing and using this code :D.

Code sources

The files src/classes.f90 and src/itertools.f90 were taken from the Polya respository.

symlib's Issues

symmetry.f90 unit test errors

In the symmetry.xml file there are a number of tests with purpose: testingf?_dp8vsdp4?. This is because when fortpy performs the unit test it finds answers to a higher precision, 8, than the 4 that were saved to file for comparison. pysave_real was used to save the output in both cases. Any ideas how to fix this.

Small memory leak in symmetry.f90 get_spaceGroup

lattpg_op does not get deallocated. I created a pull with the fix

find_value_in_array issues.

Each of the subroutines in this interface take 4 arguments, an array, a value or value list, an output location array, and an output integer for the number of times the value array appeared. The current issue is that the output location array has to be allocated outside the subroutines so that we have to "guess at the size before hand" if we fail to do that properly then we get results like this:

4          6         7       805306368         2133590033         2133596230       2133596267       2133596304

where the only the first 3 elements of the output array have meaning. The rest are of course random garbage from the machine. For unit tests I can get around this by pre-assigning the loc vector to have values of zero. The question is do we want to change this so that the only values returned are those that have meaning?

Question from symmetry.f90

In the bring_into_cell subroutine I found this:
'''

! If a component >= 1, translate by subtracting a lattice vector
! If a component < 0, translate by adding a lattice vector
do while(any(v >= 1.0_dp - eps) .or. any(v < 0.0_dp - eps)) 
   c = c +1
   v = merge(v, v - 1.0_dp, v <  1.0_dp - eps) 
   v = merge(v, v + 1.0_dp, v >= 0.0_dp - eps)
   if (c>maxc) stop "ERROR: loop does not end in bring_into_cell. Probably compiler bug."
enddo

'''

From what the comment in the code says it looks like we have the conditions in the merges backwards, or am I seeing this wrong?

Numerical precision issues

As I've been running unit tests there have been some precision issues that have come up in the code. For example in the tests for the cross_product subroutine in vector_matrix_utilities about 25% of the tests differ, from those independently generated, in the last one or two digits of precision that we are using in fortpy (so around the 11th and 12th decimal places). These differences are small and can be accommodated in the unit tests by having a tolerance of 2E-11 for the comparisons. My question though is if this is what we want or expect?

These kinds of errors could just be machine noise but they do propagate, the tolerance for the volume subroutines output, in the same module, has to be set to 2E-10 in order to pass 100% of the time because of it's dependence on the cross_product who's errors get compounded when multiplied by other values.

Non standard function outputs in rational_mathematics.f90 and utilities.f90

In rational_mathematics.f90 the gcd functions don't return their own name, i.e. the have no type, but instead return an integer divisor. In utilities.f90 the ralloc functions have no type since the real output for comparison is the pointer p. In either case fortpy can't compile an executable because it tries to save the function to a variable of the same type.

Some of the unittests are failing

find_site_equivalencies_nSites.x in /Users/hart/codes/staging/symmetry.find_site_equivalencies.g/tests

Compilation error during unit testing

rm_3d_operations_sgrots.f90:23:31:

   call rm_3d_operations(aVecs, sgrots, sgshifts, eps)
                               1
Error: Actual argument for 'sgrots' must be ALLOCATABLE at (1)
gfortran: error: rm_3d_operations_sgrots.o: No such file or directory
Error.

WARNING: compile generated some errors or warnings:
rm_3d_operations_sgrots.f90:23:31:

   call rm_3d_operations(aVecs, sgrots, sgshifts, eps)
                               1
Error: Actual argument for 'sgrots' must be ALLOCATABLE at (1)
gfortran: error: rm_3d_operations_sgrots.o: No such file or directory

ERROR: Could not compile executable rm_3d_operations_sgrots.x

numerical_utilities module conflicts during build with another module with same name

I am trying to get FHI-aims build with autoGR. Unfortunately, there is also a module in FHI-aims named numerical_utilities, so during the linking the compilers complain about "multiple definition".

The best solution in my view would be to rename the module to symlib_numerical_utilities and occurrences.
Would that be an option?

Possible error in minkowski_reduce_basis

When given a basis, constructed using:

       c_basis(:,1) = (/0.5_dp,1.0_dp,0.0_dp/)
       c_basis(:,2) = (/0.5_dp,-1.0_dp,0.0_dp/)
       c_basis(:,3) = (/0.0_dp,0.0_dp,3.0_dp/)

The minkowski_reduce_basis vectors return:

 C_mink
   1.0000000000000000        0.0000000000000000        0.0000000000000000     
   0.0000000000000000        0.0000000000000000        3.0000000000000000     
   0.0000000000000000        0.0000000000000000        3.0000000000000000     

This reduced basis is linearly dependent, but the original basis is not. I've produced this error now with eps values of 1E-3 to 1E-10, and by transposing the input basis. The returned reduced basis is always linearly dependent. The input vectors above are a basis choice for a base centered orthorhombic cell. Oddly my python code returns 3 vectors that are linearly independent and make intuitive sense:

[[ 1. ,  0. ,  0. ],
       [-0.5,  1. ,  0. ],
       [ 0. ,  0. ,  3. ]]

but I'm not convinced it's the correct answer.

Incorrect behavior for equal function when comparing rank 1+ arrays

Right now if we compare two arrays we get the following, in the following example they are a and b:

 a   4.5600927478517406E-009  -2.9999999934510697        3.9999999999953424     
 b           0          -3           4
 atol   1.0000000000000000E-010
 rtol   1.0000000000000000E-003
 rtol * max(abs(a),abs(b))  = (4.5600927478517410E-012   3.0000000000000001E-003   4.0000000000000001E-003)
 atol + rtol * max(abs(a),abs(b)) =   (1.0456009274785174E-010   3.0000001000000001E-003   4.0000000999999997E-003)
 abs(a-b) = (4.5600927478517406E-009   6.5489302869536914E-009   4.6576076329074567E-012)
 abs(a-b) < atol + rtol * max(abs(a),abs(b)) =  F T T

and because there is an F in the results the algorithm returns False, however, from our own observations we can clearly see that the result should be True. The problem seems to be that we are using max an arrays which results in another array that is then compared to. The solution is to use maxval on each array then wrap the results in max like so:

atol + rtol * max(maxval(abs(a)), maxval(abs(b))) =  4.0000000999999997E-003
abs(a-b) < atol + rtol * max(maxval(abs(a)), maxval(abs(b))) = T T T

Fortpy comparison error?

ERROR: [autovar] could not parse value '-61.2238249-101.4675892' of type 'float'.
Error produced from cross_product tests in vector_matrix_utilities.f90

Error in symmetry.f90

There seems to be an error in symmetry.f90's subroutine rm_3d_operations. This subroutine is supposed to remove the 3D operations from the point group for surface calculations. At the moment however, it leaves the 3D operations in. Looking back on the code it appears the difference came in when this operation was moved into it's own subroutine. At that point the following line:

       if (equal(sgrots(2:3,1,i),0._dp,eps) .and. equal(sgrots(1,2:3,i),0._dp,eps) .and.&
            & equal(sgrots(1,1,i),1._dp,eps)) then ! this operation is "2D"         

was changed to:

       if (equal(sgrots(2:3,1,i),0._dp,eps) .and. equal(sgrots(1,2:3,i),0._dp,eps) .and.&
            & equal(abs(sgrots(1,1,i)),1._dp,eps)) then ! this operation is "2D"         

If I reverse this change then the code removes the point group again as expected. The question is why was the change made and are we safe if we change it back?