Crate sphrs

Source
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 HarmonicsSets 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

§License

Licensed under either of

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§

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

Enums§

ComplexSH
Available types of complex spherical harmonics and solid harmonics
RealSH
Available types of real spherical harmonics and solid harmonics

Traits§

SHCoordinates
Definition of coordinates
SHEval
Harmonics evaluation trait
SphrsFloat
Trait alias for trait bounds on floats

Functions§

irregular_solid_sh
Complex irregular solid harmonics
real_irregular_solid_sh
Real irregular solid harmonics
real_regular_solid_sh
Real regular solid harmonics
real_sh
Real spherical harmonics (recursive implementation)
real_sh_hardcoded
Accelerated spherical harmonics.
regular_solid_sh
Complex regular solid harmonics
sh
Complex spherical harmonics
sh00
SH (l=0,m=0)
sh1n1
SH (l=1,m=-1)
sh1p1
SH (l=1,m=1)
sh2n1
SH (l=2,m=-1)
sh2n2
SH (l=2,m=-2)
sh2p1
SH (l=2,m=1)
sh2p2
SH (l=2,m=2)
sh3n1
SH (l=3,m=-1)
sh3n2
SH (l=3,m=-2)
sh3n3
SH (l=3,m=-3)
sh3p1
SH (l=3,m=1)
sh3p2
SH (l=3,m=2)
sh3p3
SH (l=3,m=3)
sh10
SH (l=1,m=0)
sh20
SH (l=2,m=0)
sh30
SH (l=3,m=0)