Alter 2-point correlation output

[jgostick]

As discussed in #626, our 2-point correlation function does not give the same output as Torquato, meaning that our data can't be used in some of the analytical functions that have been derived (e.g. surface area calculation, etc). We should update the function to optionally scale the output accordingly (I think scaling is all that needs to be done). We should probably add a test that ensures this function gives exact/known values for standard materials (lattice spheres?).

• [ ] Add optional argument to function
• [ ] Update example notebook (this has been deleted for now)
• [ ] Add unit test(s)

[OhmFF]

Dear Professor Gostick

There are 2 other two-point correlation functions, according to Torquato, namely, 1) Lineal path function (Lp) and 2) Two-point cluster function (Cp). In my case, the two-point cluster function is very interesting because it directly implies the degree of connectivity (or clustering) of the pore phase.

Is there any way to implement the two-point cluster function in Porespy?

[jgostick]

The two-point cluster function is challenging because you have to deal with the additional complication of only looking at certain clusters. The scipy.ndimage.label function is an easy way to separate clusters, but then I'm not sure how to implement the function in an efficient way. We currently use a FFT for the two-point correlation, which makes it difficult to extend to this more complicated analysis. We used to have a 'brute force' method which was terribly slow so it was removed in v2...maybe that should be revistied.

If you're willing to give it a try, here is where I would start:

1. Create a fuction that accepts the binary image im, as well as batch_size and batch_num (will explain below)
2. Firstly, apply scipy.nimage.label to im
3. Choose a bunch of random points in the image using (np.random.rand(batch_size, im.ndim)*im.shape).astype(int)
4. Use scipy.spatial.distance_matrix to get a map of how far each point is to all the others
5. Mask the distance map to set all points on the wrong cluster to np.nan (so if row 1 corresponds to cluster 10, then set all points NOT on cluster 10 to np.nan)
6. Compute the statistics for the number of points on each row that are not nans, to see the distribution of distances.
7. Repeat for batch_num times to accumulate enough stats.
8. Doing it in batches will enable the use of dask since batches can be distributed between cores, but this can be added later. The important thing is that the code has the ability to accumulate stats from different batches.

We would we be very grateful if you were able to contribute something like this to PoreSpy. We can help you through the pull request process when the time comes.

[jgostick]

This was addressed in PR #703