Module s2_vect_mod

module s2_vect_mod

        ! Uses
    use s2_types_mod
    use s2_error_mod

        ! Types
    public type s2_vect

        ! Variables
    integer, public, parameter :: S2_VECT_TYPE_CART = 0
    integer, public, parameter :: S2_VECT_TYPE_S2 = 1
    integer, private, parameter :: S2_VECT_CART_DIM = 3

        ! Interfaces
    public interface s2_vect_init

        ! Subroutines and functions
    private function s2_vect_init_cart (x) result (vect)
    private function s2_vect_init_sph (r, theta, phi) result (vect)
    private function s2_vect_init_copy (orig) result (copy)
    public subroutine s2_vect_free (vect)
    public subroutine s2_vect_convert (vect, type)
    private subroutine s2_vect_compute_sph (vect)
    private subroutine s2_vect_compute_cart (vect)
    public function s2_vect_rad_to_arcmin (theta_rad) result (theta_arcmin)
    public function s2_vect_arcmin_to_rad (theta_arcmin) result (theta_rad)
    public function s2_vect_dot (a, b) result (dot)
    public subroutine s2_vect_rotate (vect, alpha, beta, gamma)
    private subroutine s2_vect_rotmat_direct (R, alpha, beta, gamma)
    private subroutine s2_vect_rotmat_point (R, alpha, beta, gamma)
    private subroutine s2_vect_rotmat_x_point (R, ang)
    private subroutine s2_vect_rotmat_y_point (R, ang)
    private subroutine s2_vect_rotmat_z_point (R, ang)
    private subroutine s2_vect_rotmat_axis (R, alpha, beta, gamma)
    private subroutine s2_vect_rotmat_x_axis (R, ang)
    private subroutine s2_vect_rotmat_y_axis (R, ang)
    private subroutine s2_vect_rotmat_z_axis (R, ang)
    public subroutine s2_vect_set_unit (vect)
    public function s2_vect_get_init (vect) result (init)
    public function s2_vect_get_x (vect) result (x)
    public function s2_vect_get_r (vect) result (r)
    public function s2_vect_get_theta (vect) result (theta)
    public function s2_vect_get_phi (vect) result (phi)
    public function s2_vect_get_type (vect) result (type)

end module s2_vect_mod

Provide functionality to support and rotate vectors in R^3, represented in either cartesian or spherical coordinates.

Author: J. D. McEwen (mcewen@mrao.cam.ac.uk)

Version: 0.1 September 2004

Description of Types

s2_vect

public type s2_vect
    private
    logical :: init = .false.
    real (kind=s2_sp), dimension (S2_VECT_CART_DIM) :: x = 0.0e0
    real (kind=s2_sp) :: r = 0.0e0
    real (kind=s2_sp) :: theta = 0.0e0
    real (kind=s2_sp) :: phi = 0.e0
    integer :: type = S2_VECT_TYPE_CART
end type s2_vect

Description of Variables

S2_VECT_TYPE_CART

integer, public, parameter :: S2_VECT_TYPE_CART = 0

Cartesian coordinate status type.

S2_VECT_TYPE_S2

integer, public, parameter :: S2_VECT_TYPE_S2 = 1

Spherical coordinate status type.

S2_VECT_CART_DIM

integer, private, parameter :: S2_VECT_CART_DIM = 3

Dimension of 3d cartesian vector.

Description of Interfaces

s2_vect_init

public interface s2_vect_init
    module procedure s2_vect_init_cart
    module procedure s2_vect_init_sph
    module procedure s2_vect_init_copy
end interface s2_vect_init

Description of Subroutines and Functions

s2_vect_init_cart

private function s2_vect_init_cart (x) result (vect)
    real (kind=s2_sp), intent(in), dimension (:) :: x
    type (s2_vect) :: vect
    ! Calls: s2_error
end function s2_vect_init_cart

Initialise a vector in cartesian coordinates.

Variables:

x: array of 3 cartesian values (x,y,z).
vect: Initialised vector.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_init_sph

private function s2_vect_init_sph (r, theta, phi) result (vect)
    real (kind=s2_sp), intent(in) :: r
    real (kind=s2_sp), intent(in) :: theta
    real (kind=s2_sp), intent(in) :: phi
    type (s2_vect) :: vect
    ! Calls: s2_error
end function s2_vect_init_sph

Initialise a vector in spherical coordinates.

Variables:

r: R spherical coordinate.
theta: Theta spherical coordinate.
phi: Phi spherical coordinate.
vect: Initialised vector.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_init_copy

private function s2_vect_init_copy (orig) result (copy)
    type (s2_vect), intent(in) :: orig
    type (s2_vect) :: copy
    ! Calls: s2_error
end function s2_vect_init_copy

Initialise a vector by making a copy of another vector.

Variables:

orig: Original vector to copy.
copy: The copy vector initialised.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_free

public subroutine s2_vect_free (vect)
    type (s2_vect), intent(inout) :: vect
    ! Calls: s2_error
end subroutine s2_vect_free

Reset vector values. (No memory to be freed.)

Variables:

vect: Vector to free.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_convert

public subroutine s2_vect_convert (vect, type)
    type (s2_vect), intent(inout) :: vect
    integer, intent(in) :: type
    ! Calls: s2_error, s2_vect_compute_cart, s2_vect_compute_sph
end subroutine s2_vect_convert

Convert a vector to the coordinates system specified by type. If the vector is already in the soordinate system then do nothing.

Variables:

vect: Vector to convert coordinate type.
type: Coordinate type to convert to.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_compute_sph

private subroutine s2_vect_compute_sph (vect)
    type (s2_vect), intent(inout) :: vect
    ! Calls: s2_error
end subroutine s2_vect_compute_sph

Compute spherical coordinates of a vector from cartesian coordinates.

Variables:

vect: Vector to compute spherical coordinates of.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_compute_cart

private subroutine s2_vect_compute_cart (vect)
    type (s2_vect), intent(inout) :: vect
    ! Calls: s2_error
end subroutine s2_vect_compute_cart

Compute cartesian coordinates of a vector from spherical coordinates.

Variables:

vect: Vector to compute cartesian coordinates of.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_rad_to_arcmin

public function s2_vect_rad_to_arcmin (theta_rad) result (theta_arcmin)
    real (kind=s2_sp), intent(in) :: theta_rad
    real (kind=s2_sp) :: theta_arcmin
end function s2_vect_rad_to_arcmin

Convert an angle from radians to arcmins.

Variables:

theta_rad: Angle in radians to be converted.
theta_arcmin: Equivalent angle in arcmins.

Author: J. D. McEwen

Version: 0.1 November 2004

s2_vect_arcmin_to_rad

public function s2_vect_arcmin_to_rad (theta_arcmin) result (theta_rad)
    real (kind=s2_sp), intent(in) :: theta_arcmin
    real (kind=s2_sp) :: theta_rad
end function s2_vect_arcmin_to_rad

Convert an angle from arcmins to radians.

Variables:

theta_arcmin: Angle in arcmins to be converted.
theta_rad: Equivalent angle in radians.

Author: J. D. McEwen

Version: 0.1 November 2004

s2_vect_dot

public function s2_vect_dot (a, b) result (dot)
    type (s2_vect), intent(inout) :: a
    type (s2_vect), intent(inout) :: b
    real (kind=s2_sp) :: dot
    ! Calls: s2_error
end function s2_vect_dot

Compute the dot product of two vectors.

Variables:

a: First vector of dot product.
b: Second vector of dot product.
dot: Dot product of a and b computed.

Author: J. D. McEwen

Version: 0.1 April 2006

s2_vect_rotate

public subroutine s2_vect_rotate (vect, alpha, beta, gamma)
    type (s2_vect), intent(inout) :: vect
    real (kind=s2_sp), intent(in) :: alpha
    real (kind=s2_sp), intent(in) :: beta
    real (kind=s2_sp), intent(in) :: gamma
    ! Calls: s2_error, s2_vect_convert, s2_vect_rotmat_point
end subroutine s2_vect_rotate

Rotate a vector by the specified Euler angles.

Variables:

vect: The vector to be rotated on input and the rotated vector on output.
alpha: Alpha Euler angle.
beta: Beta Euler angle.
gamma: Gamma Euler angle.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_rotmat_direct

private subroutine s2_vect_rotmat_direct (R, alpha, beta, gamma)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: alpha
    real (kind=s2_sp), intent(in) :: beta
    real (kind=s2_sp), intent(in) :: gamma
end subroutine s2_vect_rotmat_direct

Generate a rotation matrix to rotate a vector (in cartesian coordinates) by the speficied Euler angles. The rotation matrix is coded directly rather than multiplying rotation matrices that rotate about various axis.

Variables:

R: Rotation matrix generated.
alpha: Alpha Euler angle.
beta: Beta Euler angle.
gamma: Gamma Euler angle.

Author: D. J. Mortlock

Version: 0.1 September 2004

s2_vect_rotmat_point

private subroutine s2_vect_rotmat_point (R, alpha, beta, gamma)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: alpha
    real (kind=s2_sp), intent(in) :: beta
    real (kind=s2_sp), intent(in) :: gamma
    ! Calls: s2_vect_rotmat_y_point, s2_vect_rotmat_z_point
end subroutine s2_vect_rotmat_point

Generate a rotation matrix to rotate a vector (in cartesian coordinates) by the specified Euler angles. The point is rotated in the right hand sense (axis rotated in left hand sense).

Notes:

The rotation matrix is generated from: R = Rz(gamma) * Ry(beta) * Rz(alpha)

Variables:

R: Rotation matrix generated.
alpha: Alpha Euler angle.
beta: Beta Euler angle.
gamma: Gamma Euler angle.

Author: J. D. McEwen

Version: 0.1 April 2005

s2_vect_rotmat_x_point

private subroutine s2_vect_rotmat_x_point (R, ang)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: ang
end subroutine s2_vect_rotmat_x_point

Generate a rotation matrix to rotate about the x axis by the specified angle. The point is rotated in the right hand sense (axis rotated in left hand sense).

Variables:

R: Rotation matrix generated to rotate about x axis.
ang: Angle to rotate about x axis by.

Author: J. D. McEwen

Version: 0.1 April 2005

s2_vect_rotmat_y_point

private subroutine s2_vect_rotmat_y_point (R, ang)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: ang
end subroutine s2_vect_rotmat_y_point

Generate a rotation matrix to rotate about the y axis by the specified angle. The point is rotated in the right hand sense (axis rotated in left hand sense).

Variables:

R: Rotation matrix generated to rotate about y axis.
ang: Angle to rotate about y axis by.

Author: J. D. McEwen

Version: 0.1 April 2005

s2_vect_rotmat_z_point

private subroutine s2_vect_rotmat_z_point (R, ang)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: ang
end subroutine s2_vect_rotmat_z_point

Generate a rotation matrix to rotate about the z axis by the specified angle. The point is rotated in the right hand sense (axis rotated in left hand sense).

Variables:

R: Rotation matrix generated to rotate about z axis.
ang: Angle to rotate about z axis by.

Author: J. D. McEwen

Version: 0.1 April 2005

s2_vect_rotmat_axis

private subroutine s2_vect_rotmat_axis (R, alpha, beta, gamma)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: alpha
    real (kind=s2_sp), intent(in) :: beta
    real (kind=s2_sp), intent(in) :: gamma
    ! Calls: s2_vect_rotmat_y_axis, s2_vect_rotmat_z_axis
end subroutine s2_vect_rotmat_axis

Generate a rotation matrix to rotate a vector (in cartesian coordinates) by the specified Euler angles. The axis is rotated in the right hand sense (point rotated in left hand sense).

Notes:

The rotation matrix is generated from: R = Rz(gamma) * Ry(beta) * Rz(alpha)

Variables:

R: Rotation matrix generated.
alpha: Alpha Euler angle.
beta: Beta Euler angle.
gamma: Gamma Euler angle.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_rotmat_x_axis

private subroutine s2_vect_rotmat_x_axis (R, ang)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: ang
end subroutine s2_vect_rotmat_x_axis

Generate a rotation matrix to rotate about the x axis by the specified angle. The axis is rotated in the right hand sense (point rotated in left hand sense).

Variables:

R: Rotation matrix generated to rotate about x axis.
ang: Angle to rotate about x axis by.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_rotmat_y_axis

private subroutine s2_vect_rotmat_y_axis (R, ang)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: ang
end subroutine s2_vect_rotmat_y_axis

Generate a rotation matrix to rotate about the y axis by the specified angle. The axis is rotated in the right hand sense (point rotated in left hand sense).

Variables:

R: Rotation matrix generated to rotate about y axis.
ang: Angle to rotate about y axis by.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_rotmat_z_axis

private subroutine s2_vect_rotmat_z_axis (R, ang)
    real (kind=s2_sp), intent(out), dimension (S2_VECT_CART_DIM, S2_VECT_CART_DIM) :: R
    real (kind=s2_sp), intent(in) :: ang
end subroutine s2_vect_rotmat_z_axis

Generate a rotation matrix to rotate about the z axis by the specified angle. The axis is rotated in the right hand sense (point rotated in left hand sense).

Variables:

R: Rotation matrix generated to rotate about z axis.
ang: Angle to rotate about z axis by.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_set_unit

public subroutine s2_vect_set_unit (vect)
    type (s2_vect), intent(inout) :: vect
    ! Calls: s2_vect_convert
end subroutine s2_vect_set_unit

Scale the vector magnitude so it has unit length (orientation maintained).

Variables:

vect: Vector to scale to unit vector.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_get_init

public function s2_vect_get_init (vect) result (init)
    type (s2_vect), intent(in) :: vect
    logical :: init
end function s2_vect_get_init

Get init variable from the passed vect.

Variables:

vect: Vect object to get the variable of.
init: Object init variable returned.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_get_x

public function s2_vect_get_x (vect) result (x)
    type (s2_vect), intent(inout) :: vect
    real (kind=s2_sp), dimension (S2_VECT_CART_DIM) :: x
    ! Calls: s2_error, s2_vect_convert
end function s2_vect_get_x

Get x variable from the passed vect.

Variables:

vect: Vect object to get the variable of.
x: Object x coordinate variable returned.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_get_r

public function s2_vect_get_r (vect) result (r)
    type (s2_vect), intent(inout) :: vect
    real (kind=s2_sp) :: r
    ! Calls: s2_error, s2_vect_convert
end function s2_vect_get_r

Get r variable from the passed vect.

Variables:

vect: Vect object to get the variable of.
r: Object r coordinate variable returned.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_get_theta

public function s2_vect_get_theta (vect) result (theta)
    type (s2_vect), intent(inout) :: vect
    real (kind=s2_sp) :: theta
    ! Calls: s2_error, s2_vect_convert
end function s2_vect_get_theta

Get theta variable from the passed vect.

Variables:

vect: Vect object to get the variable of.
theta: Object theta coordinate variable returned.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_get_phi

public function s2_vect_get_phi (vect) result (phi)
    type (s2_vect), intent(inout) :: vect
    real (kind=s2_sp) :: phi
    ! Calls: s2_error, s2_vect_convert
end function s2_vect_get_phi

Get phi variable from the passed vect.

Variables:

vect: Vect object to get the variable of.
phi: Object phi coordinate variable returned.

Author: J. D. McEwen

Version: 0.1 September 2004

s2_vect_get_type

public function s2_vect_get_type (vect) result (type)
    type (s2_vect), intent(in) :: vect
    integer :: type
    ! Calls: s2_error
end function s2_vect_get_type

Get type variable from the passed vect.

Variables:

vect: Vect object to get the variable of.
type: Object type coordinate variable returned.

Author: J. D. McEwen

Version: 0.1 September 2004