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 = √(x²+y²+z²)
• θ = 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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	SphericalCoordinates.DataTransferObject	Internal class used only for serialization.

Field Summary

Fields

Modifier and Type	Field	Description
private double[][]	jacobian	Jacobian of (r, θ invalid input: '&Phi').
private final double	phi	Polar angle (co-latitude) Φ.
private double[][]	phiHessian	Hessian of polar (co-latitude) angle Φ.
private final double	r	Radius.
private double[][]	rHessian	Hessian of radius.
private static final long	serialVersionUID	Serializable UID.
private final double	theta	Azimuthal angle in the x-y plane θ.
private double[][]	thetaHessian	Hessian of azimuthal angle in the x-y plane θ.
private final 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

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 Object	writeReplace()	Replace the instance with a data transfer object for serialization.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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, θ 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()
• 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 {{d²f/dr², d²f/drdθ, d²f/drdΦ}, {d²f/drdθ, d²f/dθ², d²f/dθdΦ}, {d²f/drdΦ, d²f/dθdΦ, d²f/dΦ²}

sGradient - gradient with respect to spherical coordinates {df/dr, df/dθ, df/dΦ}

Returns:

Hessian with respect to Cartesian coordinates {{d²f/dx², d²f/dxdy, d²f/dxdz}, {d²f/dxdy, d²f/dy², d²f/dydz}, {d²f/dxdz, d²f/dydz, d²f/dz²}}

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