Spherical Harmonics in Rust

[janbridley]

Description

Simple and efficient evaluation of spherical harmonics in rust. While a crate for this does exist, it appears to be abandonware and panics for l > 10.

Motivation and context

Evaluation of the Steinhardt order parameters requires spherical harmonics, and the Glotzerlab's current codebase (fsph)for spherical harmonics is not structured to efficiently calculate things like this. With some compile-time generics and some of the new findings from the sphericart paper in JCP, I have an approach better-suited to our standard workflow. It provides all positive m values for a compile-time value of L, and can efficiently evaluate both individual and multiple points. A doc example shows a simple Steinhardt calculation, although the real implementation of that should go in hoomd-order or similar.

Example implementation of q6

/// Implement the Steinhardt order parameter q6.
fn q6(bonds: &[Cartesian<3>]) -> f64 {
    let mut accum = [Complex64::ZERO; 7];
    let y6 = SphericalHarmonic::<6>::new();

    for &bond in bonds {
        let projected_onto_sphere = bond / bond.norm();
        let qlmi = y6.eval(projected_onto_sphere.coordinates);
        for m in 0..7 { accum[m] += qlmi[m]; }
    }

    // We multiply the `m>0` components by two to account for `-m` contributions.
    let sum_sq = accum[0].norm_sqr()
        + 2.0 * accum[1..].iter().map(Complex64::norm_sqr).sum::<f64>();
    let n = bonds.len() as f64;

    (4.0 * PI / 13.0 * sum_sq).sqrt() / n
}

How has this been tested?

Tests against SPHRS for l<=10 compare the actual values, and I have an integration-ish test that tests the completeness relation to measure accumulated numerical error. Offline/mixed-language tests have shown my results are similar accuracy to fsph and sphericcart, but better performance when only a few l values are required.

Checklist:

• I have reviewed the Contributor Guidelines.
• I agree with the terms of the hoomd-rs Contributor Agreement.
• My name is on the list of contributors (doc/src/credits.md) in the pull request source branch.
• I have summarized these changes in release-notes.md following the established format.

[mthran]

Very nice! Other than a couple clarifying questions, this API is consistent with how I would hope to use spherical harmonics.

[janbridley]

The last major question (and the failing lint) is a readme -- Josh, I see this crate as useful outside hoomd-rs but the maintenance burden of it being fully standalone seems undesirable. Is it worth having the README (and therefore crates.io page) be more or less independent and just release the code with hoomd-rs, or should we just make this a core part of the HOOMD code? Per some offline discussions with Michelle, the actual order parameters using this code will go in a crate like hoomd-order

[joaander]

Thanks! This is clean and simple. We discussed offline regarding what crate makes the most sense to hold this code.

You could make use of katex math in the documentation to make it more clear and explicit what this code calculates.