# Crate sphrs

Expand description

A general purpose spherical/solid harmonics library in Rust.

This crate offers real and complex spherical harmonics and solid harmonics.

Documentation:

## Usage

Add this to your `Cargo.toml`:

``````[dependencies]
sphrs = "0.2.2"
``````

## Tutorial

There are two enums `RealSH` and `ComplexSH`, each with the following variants:

• `Spherical`
• `RegularSolid`
• `IrregularSolid`

These variants are used to define which kind of spherical/solid harmonic is to be computed. Each enum implements the `SHEval` trait, which provides an `SHEval::eval` method. This method is used to compute the spherical/solid harmonic for `Coordinates`. Coordinates define a position in space and can be constructed from Cartesian and spherical coordinates via `Coordinates::cartesian` and `Coordinates::spherical`, respectively.

In order to compute real valued spherical harmonics, one needs to call the `eval` method on the `Spherical` variant of the `RealSH` enum. The `eval` method is part of the `SHEval` trait and as such this trait must be in scope.

``````use sphrs::{Coordinates, RealSH, SHEval};

// l = 2
let degree = 2;
// m = 1
let order = 1;

// Define the position where the SH will be evaluated at
// in Cartesian coordinates
let p = Coordinates::cartesian(1.0, 0.2, 1.4);

// Compute the real-valued SH value at `p` for l = 2, m = 1
let computed_sh = RealSH::Spherical.eval(degree, order, &p);

println!("SH ({}, {}): {:?}", degree, order, computed_sh);``````

This library can also compute `HarmonicsSet`s which contains all spherical/solid harmonics up to a given order.

The following example shows how to compute complex spherical harmonics up to third order at the spherical coordinates (r, theta, phi) = (1.0, 0.8, 0.4):

``````use sphrs::{ComplexSH, Coordinates, HarmonicsSet};

// l = 3
let degree = 3;

// Create the harmonics set (in this case for complex SH)
let sh = HarmonicsSet::new(degree, ComplexSH::Spherical);

// Position in spherical coordinates where the set is evaluated at
let p = Coordinates::spherical(1.0, 0.8, 0.4);

// Evaluate. Returns a `Vec<f64>`
let set = sh.eval(&p);

println!("SH up to degree {}: {:?}", degree, set);``````

The individual SH in the set can also be multiplied element-wise with a vector of coefficients with the function `HarmonicsSet::eval_with_coefficients`:

``````let sh = HarmonicsSet::new(degree, ComplexSH::Spherical);
// Must be the same length as the set.
let coeff = vec![2.0; sh.num_sh()];
let set = sh.eval_with_coefficients(&p, coeff.as_slice());
println!("SH up to degree {}: {:?}", degree, set);``````

## Acknowledgements

This crate is heavily inspired by Google’s spherical-harmonics library and follows the design documented here.

## References

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

## Enums

• Available types of complex spherical harmonics and solid harmonics
• Available types of real spherical harmonics and solid harmonics