Class SphericalCoordinates

java.lang.Object
org.apache.commons.math3.geometry.euclidean.threed.SphericalCoordinates
All Implemented Interfaces:
Serializable

public class SphericalCoordinates extends Object implements Serializable
This class provides conversions related to spherical coordinates.

The conventions used here are the mathematical ones, i.e. spherical coordinates are related to Cartesian coordinates as follows:

  • x = r cos(θ) sin(Φ)
  • y = r sin(θ) sin(Φ)
  • z = r cos(Φ)
  • r = √(x2+y2+z2)
  • θ = atan2(y, x)
  • Φ = acos(z/r)

r is the radius, θ is the azimuthal angle in the x-y plane and Φ is the polar (co-latitude) angle. These conventions are different from the conventions used in physics (and in particular in spherical harmonics) where the meanings of θ and Φ are reversed.

This class provides conversion of coordinates and also of gradient and Hessian between spherical and Cartesian coordinates.

Since:
3.2
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static class 
    Internal class used only for serialization.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private double[][]
    Jacobian of (r, θ invalid input: '&Phi').
    private final double
    Polar angle (co-latitude) Φ.
    private double[][]
    Hessian of polar (co-latitude) angle Φ.
    private final double
    Radius.
    private double[][]
    Hessian of radius.
    private static final long
    Serializable UID.
    private final double
    Azimuthal angle in the x-y plane θ.
    private double[][]
    Hessian of azimuthal angle in the x-y plane θ.
    private final Vector3D
    Cartesian coordinates.
  • Constructor Summary

    Constructors
    Constructor
    Description
    SphericalCoordinates(double r, double theta, double phi)
    Build a spherical coordinates transformer from spherical coordinates.
    Build a spherical coordinates transformer from Cartesian coordinates.
  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    Lazy evaluation of Hessians.
    private void
    Lazy evaluation of (r, θ, φ) Jacobian.
    Get the Cartesian coordinates.
    double
    Get the polar (co-latitude) angle.
    double
    Get the radius.
    double
    Get the azimuthal angle in x-y plane.
    double[]
    toCartesianGradient(double[] sGradient)
    Convert a gradient with respect to spherical coordinates into a gradient with respect to Cartesian coordinates.
    double[][]
    toCartesianHessian(double[][] sHessian, double[] sGradient)
    Convert a Hessian with respect to spherical coordinates into a Hessian with respect to Cartesian coordinates.
    private Object
    Replace the instance with a data transfer object for serialization.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serializable UID.
      See Also:
    • v

      private final Vector3D v
      Cartesian coordinates.
    • r

      private final double r
      Radius.
    • theta

      private final double theta
      Azimuthal angle in the x-y plane θ.
    • phi

      private final double phi
      Polar angle (co-latitude) Φ.
    • jacobian

      private double[][] jacobian
      Jacobian of (r, θ invalid input: '&Phi').
    • rHessian

      private double[][] rHessian
      Hessian of radius.
    • thetaHessian

      private double[][] thetaHessian
      Hessian of azimuthal angle in the x-y plane θ.
    • phiHessian

      private double[][] phiHessian
      Hessian of polar (co-latitude) angle Φ.
  • Constructor Details

    • SphericalCoordinates

      public SphericalCoordinates(Vector3D v)
      Build a spherical coordinates transformer from Cartesian coordinates.
      Parameters:
      v - Cartesian coordinates
    • SphericalCoordinates

      public SphericalCoordinates(double r, double theta, double phi)
      Build a spherical coordinates transformer from spherical coordinates.
      Parameters:
      r - radius
      theta - azimuthal angle in x-y plane
      phi - polar (co-latitude) angle
  • Method Details

    • getCartesian

      public Vector3D getCartesian()
      Get the Cartesian coordinates.
      Returns:
      Cartesian coordinates
    • getR

      public double getR()
      Get the radius.
      Returns:
      radius r
      See Also:
    • getTheta

      public double getTheta()
      Get the azimuthal angle in x-y plane.
      Returns:
      azimuthal angle in x-y plane θ
      See Also:
    • getPhi

      public double getPhi()
      Get the polar (co-latitude) angle.
      Returns:
      polar (co-latitude) angle Φ
      See Also:
    • toCartesianGradient

      public double[] toCartesianGradient(double[] sGradient)
      Convert a gradient with respect to spherical coordinates into a gradient with respect to Cartesian coordinates.
      Parameters:
      sGradient - gradient with respect to spherical coordinates {df/dr, df/dθ, df/dΦ}
      Returns:
      gradient with respect to Cartesian coordinates {df/dx, df/dy, df/dz}
    • toCartesianHessian

      public double[][] toCartesianHessian(double[][] sHessian, double[] sGradient)
      Convert a Hessian with respect to spherical coordinates into a Hessian with respect to Cartesian coordinates.

      As Hessian are always symmetric, we use only the lower left part of the provided spherical Hessian, so the upper part may not be initialized. However, we still do fill up the complete array we create, with guaranteed symmetry.

      Parameters:
      sHessian - Hessian with respect to spherical coordinates {{d2f/dr2, d2f/drdθ, d2f/drdΦ}, {d2f/drdθ, d2f/dθ2, d2f/dθdΦ}, {d2f/drdΦ, d2f/dθdΦ, d2f/dΦ2}
      sGradient - gradient with respect to spherical coordinates {df/dr, df/dθ, df/dΦ}
      Returns:
      Hessian with respect to Cartesian coordinates {{d2f/dx2, d2f/dxdy, d2f/dxdz}, {d2f/dxdy, d2f/dy2, d2f/dydz}, {d2f/dxdz, d2f/dydz, d2f/dz2}}
    • computeJacobian

      private void computeJacobian()
      Lazy evaluation of (r, θ, φ) Jacobian.
    • computeHessians

      private void computeHessians()
      Lazy evaluation of Hessians.
    • writeReplace

      private Object writeReplace()
      Replace the instance with a data transfer object for serialization.
      Returns:
      data transfer object that will be serialized