## 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);
```

## Advanced features

Feel free to directly use the low level functions linked at the bottom of this page.

## Acknowledgements

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

## References

- Robin Green, “Spherical Harmonic Lighting: The Gritty Details”
- Spherical harmonics (Wikipedia)
- Solid harmonics (Wikipedia)

## License

Licensed under either of

- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

### 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.

## Structs

- Representation of coordinates.
- A set of spherical/solid harmonics up to a given degree

## Enums

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

## Traits

- Definition of coordinates
- Harmonics evaluation trait
- Trait alias for trait bounds on floats

## Functions

- Complex irregular solid harmonics
- Real irregular solid harmonics
- Real regular solid harmonics
- Real spherical harmonics (recursive implementation)
- Accelerated spherical harmonics.
- Complex regular solid harmonics
- Complex spherical harmonics
- SH (l=0,m=0)
- SH (l=1,m=-1)
- SH (l=1,m=1)
- SH (l=2,m=-1)
- SH (l=2,m=-2)
- SH (l=2,m=1)
- SH (l=2,m=2)
- SH (l=3,m=-1)
- SH (l=3,m=-2)
- SH (l=3,m=-3)
- SH (l=3,m=1)
- SH (l=3,m=2)
- SH (l=3,m=3)
- SH (l=1,m=0)
- SH (l=2,m=0)
- SH (l=3,m=0)