Package org.apache.commons.math3.geometry.euclidean.threed

Class SphericalCoordinates

  • All Implemented Interfaces:
    java.io.Serializable
    public class SphericalCoordinates
extends java.lang.Object
implements java.io.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:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private double[][] jacobian
      Jacobian of (r, θ &Phi).
      private double phi
      Polar angle (co-latitude) Φ.
      private double[][] phiHessian
      Hessian of polar (co-latitude) angle Φ.
      private double r
      Radius.
      private double[][] rHessian
      Hessian of radius.
      private static long serialVersionUID
      Serializable UID.
      private double theta
      Azimuthal angle in the x-y plane θ.
      private double[][] thetaHessian
      Hessian of azimuthal angle in the x-y plane θ.
      private Vector3D v
      Cartesian coordinates.

    • Constructor Summary

      Constructors 
      Constructor Description
      SphericalCoordinates​(double r, double theta, double phi)
      Build a spherical coordinates transformer from spherical coordinates.
      SphericalCoordinates​(Vector3D v)
      Build a spherical coordinates transformer from Cartesian coordinates.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void computeHessians()
      Lazy evaluation of Hessians.
      private void computeJacobian()
      Lazy evaluation of (r, θ, φ) Jacobian.
      Vector3D getCartesian()
      Get the Cartesian coordinates.
      double getPhi()
      Get the polar (co-latitude) angle.
      double getR()
      Get the radius.
      double getTheta()
      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 java.lang.Object writeReplace()
      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 Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serializable UID.
        See Also:
        Constant Field Values

      • 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, θ &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 Detail

      • 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 Detail

      • getCartesian

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

      • getR

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

      • getTheta

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

      • getPhi

        public double getPhi()
        Get the polar (co-latitude) angle.
        Returns:
        polar (co-latitude) angle Φ
        See Also:
        getR(), getTheta()

      • 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 java.lang.Object writeReplace()
        Replace the instance with a data transfer object for serialization.
        Returns:
        data transfer object that will be serialized