Coordinates¶

This modules converts between different coordinate systems. It also allows conversions between cartesian and spherical coordinates.

Tools for coordinate transformation and vector calculations

coord.alt2zen(elevation)[source]¶

Transforms an elevation angle [radians] in zenith angles

Parameters: elevation – elevation angle in radians
Returns: zenith angle in degrees

coord.ang2vec(phi, theta)[source]¶

Get vector from spherical angles (phi, theta)

Parameters

phi – range (pi, -pi), 0 points in x-direction, pi/2 in y-direction
theta – range (pi/2, -pi/2), pi/2 points in z-direction

Returns

vector of shape (3, n)

coord.angle(v1, v2, each2each=False)[source]¶

Angular distance in radians for each pair from two (lists of) vectors. Use each2each=True to calculate every combination.

Parameters

v1 – vector(s) of shape (3, n)
v2 – vector(s) of shape (3, n)
each2each – if true calculates every combination of the two lists v1, v2

Returns

angular distance in radians

coord.atleast_kd(array, k)[source]¶: Extends numpy.atleast_1d() to arbitrary number of dimensions.

coord.date_to_julian_day(year, month, day)[source]¶

Returns the Julian day number of a date from: http://code-highlights.blogspot.de/2013/01/julian-date-in-python.html http://code.activestate.com/recipes/117215/

Parameters

year – year (measured after christ)
month – month (january: 1, december: 12)
day – day in the month (1 - 31)

coord.distance(v1, v2)[source]¶

Linear distance between each pair from two (lists of) vectors.

Parameters

v1 – vector(s) of shape (3, n)
v2 – vector(s) of shape (3, n)

Returns

linear distance between each pair

coord.dms2rad(degree, minutes, seconds)[source]¶

Transform declination (degree, minute, second) to radians

Parameters

degree – integer angle of declination in degree
minutes – arc minute of the declination angle
seconds – arc second of the declination angle

Returns

declination angle in radians

coord.ecl2eq(v)[source]¶

Rotate ecliptic to equatorial coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in ecliptic coordinate system
Returns: vector(s) of shape (3, n) in equatorial coordinate system

coord.eq2ecl(v)[source]¶

Rotate equatorial to ecliptic coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in equatorial coordinate system
Returns: vector(s) of shape (3, n) in ecliptic coordinate system

coord.eq2gal(v)[source]¶

Rotate equatorial to galactical coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in equatorial coordinate system
Returns: vector(s) of shape (3, n) in galactic coordinate system

coord.eq2sgal(v)[source]¶

Rotate equatorial to supergalactic coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in equatorial coordinate system
Returns: vector(s) of shape (3, n) in supergalactic coordinate system

coord.equatorial_scrambling(v, n=1, coord_system='gal', seed=None)[source]¶

Performs a scrambling of the input vectors v around the equatorial z-axis. In this sense it keeps the declination while assigning new uniform azimuth angles.

Parameters

v – Input vectors in equatoial coordinates and shape (3, ncrs)
n – Number of scrambled output sets
coord_system – coordinate system for input vectors

Returns

scrambled vectors in shape (3, n, ncrs)

coord.exposure_equatorial(dec, a0=- 35.25, zmax=60)[source]¶

Relative exposure per solid angle of a detector at latitude a0 (-90, 90 degrees, default: Auger), with maximum acceptance zenith angle zmax (0, 90 degrees, default: 60) and for given equatorial declination dec (-pi/2, pi/2) or vectoe. See astro-ph/0004016

Parameters

vec_or_dec – value(s) of declination in radians (-pi/2, pi/2)
a0 – latitude of detector (-90, 90) degrees (default: Auger)
zmax – maximum acceptance zenith angle (0, 90) degrees

Returns

exposure value(s) for input declination value(s)

coord.gal2eq(v)[source]¶

Rotate galactic to equatorial coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in galactic coordinate system
Returns: vector(s) of shape (3, n) in equatorial coordinate system

coord.gal2sgal(v)[source]¶

Rotate galactic to supergalactic coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in galactic coordinate system
Returns: vector(s) of shape (3, n) in supergalactic coordinate system

coord.get_declination(v, coord_system='gal')[source]¶

Return equatorial declination angle.

Parameters

v – vector(s) of shape (3, n)
coord_system – coordinate system of the input vectors

Returns

declination angle (-pi/2, pi/2)

coord.get_exposure(v, coord_system='gal', **kwargs)[source]¶

Returns exposure values of direction.

Parameters

v – vector(s) of shape (3, n)
coord_system – coordinate system of the input vectors
kwargs – Additionally named keyword arguments passed to exposure_equatorial()

Returns

exposure values

coord.get_greenwich_siderial_time(time)[source]¶

Convert civil time to (mean, wrt the mean equinox) Greenwich sidereal time. uncertainty of not taking the apparent time (wrt true equinox) is less then 0.01 deg time must be a datetime object adapted from http://infohost.nmt.edu/tcc/help/lang/python/examples/sidereal/ims/SiderealTime-gst.html

Parameters: time – class instance of datetime.date
Returns: Greenwich sidereal time

coord.get_hour_angle(ra, lst)[source]¶

Returns the hour angle (in radians) for a specific right ascension and local sidereal time

Parameters

ra – right ascension in radians
lst – local sidereal time in radians

Returns

hour angle in radians

coord.get_latitude(v, coord_system='gal')[source]¶

Return galactic latitude angle.

Parameters

v – vector(s) of shape (3, n)
coord_system – coordinate system of the input vectors

Returns

latitude angle (-pi/2, pi/2)

coord.get_local_sidereal_time(time, ra)[source]¶

Convert civil time to local sidereal time

Parameters

time – class instance of datetime.date
ra – right ascension in radians

Returns

Local sidereal time (in radians)

coord.get_longitude(v, coord_system='gal')[source]¶

Return galactic longitude angle.

Parameters

v – vector(s) of shape (3, n)
coord_system – coordinate system of the input vectors

Returns

longitude angle (-pi, pi)

coord.get_right_ascension(v, coord_system='gal')[source]¶

Return equatorial right ascension angle.

Parameters

v – vector(s) of shape (3, n)
coord_system – coordinate system of the input vectors

Returns

declination angle (-pi, pi)

coord.hms2rad(hour, minutes, seconds)[source]¶

Transform right ascension (hour, minute, second) to radians

Parameters

hour – integer hour of right ascension
minutes – arc minute of the right ascension angle
seconds – arc second of the right ascension angle

Returns

right ascension angle in radians

coord.normed(v)[source]¶

Return the normalized (lists of) vectors.

Parameters: v – vector(s) of shape (3, n)
Returns: corresponding normalized vectors of shape (3, n)

coord.rand_exposure_vec(a0=- 35.25, zmax=60, n=1, coord_system='gal', res_theta=5000, seed=None)[source]¶

Random vecs following the exposure of an experiment (equatorial coordinates). If you need other coordinates, change ‘coord_system’ keyword to eg. ‘eq’ or ‘sgal’. This method bins theta and samples from corresponding probabilities as the corresponding probability function is not integratable and invertable.

Parameters

a0 – latitude of detector (-90, 90) in degrees (default: Auger)
zmax – maximum acceptance zenith angle (0, 90) degrees
n – number of samples that are drawn
coord_system – coordinate system of the returned vectors (default: ‘gal’)
res_theta – resolution of theta, number of bins in (-pi/2, pi/2)

Returns

random unit vectors from exposure of shape (3, n), equatorial coordinates

coord.rand_fisher(kappa, n=1, seed=None)[source]¶

Random angles to the center of a Fisher distribution with concentration parameter kappa.

Parameters

kappa – concentration parameter, kappa=1/sigma^2 (sigma: smearing angle in radians) either float, or np.array (n is set to kappa.shape[0] then)
n – number of vectors drawn from fisher distribution

Returns

theta values (angle towards the mean direction)

coord.rand_fisher_vec(vmean, kappa, n=1, seed=None)[source]¶

Random Fisher distributed vectors with mean direction vmean and concentration parameter kappa.

Parameters

vmean – mean direction of the fisher distribution, (x, y, z), either shape (3) or (3, n)
kappa – concentration parameter, translates to 1/sigma^2 (sigma: smearing angle in radians)
n – number of vectors drawn from fisher distribution, becomes m if vmean has shape (3, m)

Returns

vectors from fisher distribution of shape (3, n)

coord.rand_phi(n=1, seed=None)[source]¶

Random uniform phi (-pi, pi).

Parameters: n – number of samples that are drawn
Returns: random numbers in range (-pi, pi)

coord.rand_theta(n=1, theta_min=- 1.5707963267948966, theta_max=1.5707963267948966, seed=None)[source]¶

Random theta (pi/2, -pi/2) from uniform cos(theta) distribution.

Parameters: n – number of samples that are drawn
Returns: random theta in range (-pi/2, pi/2) from cos(theta) distribution

coord.rand_theta_plane(n=1, seed=None)[source]¶

Random theta (pi/2, 0) on a planar surface from uniform cos(theta)^2 distribution.

Parameters: n – number of samples that are drawn
Returns: random theta on plane in range (pi/2, 0)

coord.rand_vec(n=1, seed=None)[source]¶

Random spherical unit vectors.

Parameters: n – number of vectors that are drawn
Returns: random unit vectors of shape (3, n)

coord.rand_vec_on_sphere(n, r=1, seed=None)[source]¶

Calculates n random positions x and correpsonding directions on the surface of the sphere as they would arise from an isotropic distribution of cosmic rays in the universe.

Parameters

n – number of drawn samples, int
r – size of the sphere, which scales the position vectors, default: 1

Returns

position vectors, directions

coord.rand_vec_on_surface(x0, n=1, seed=None)[source]¶

Given unit normal vectors x0 orthogonal on a surface, samples one isotropic direction for each given vector x0 from a cos(theta)*sin(theta) distribution

Parameters: x0 – ortogonal unit vector on the surface, shape: (3, N)
Returns: isotropic directions for the respective normal vectors x0

coord.rotate(v, rotation_axis, rotation_angle)[source]¶

Perform rotation for given rotation axis and angle(s).

Parameters

v – vector that is supposed to be rotated, either np.array([x, y, z]) or ndarray with shape (3, n)
rotation_axis – rotation axis, either np.array([x, y, z]) or ndarray with shape (3, n)
rotation_angle – rotation angle in radians, either float or array size n

Returns

rotated vector, same shape as input v

coord.rotate_zaxis_to_x(v, x0)[source]¶

Transfers the relative orientation between vectors v and the z-axis towards v and the reference vectors x0. Mathematically, the scalar products z_axis*v before the rotation and x0*v after rotation are the same (see e.g. unit test).

Parameters

v – vectors that should be rotated, shape: (3) or (3, n)
x0 – reference vectors of same shape like v

coord.rotation_matrix(rotation_axis, rotation_angle)[source]¶

Rotation matrix for given rotation axis and angle. See http://en.wikipedia.org/wiki/Euler-Rodrigues_parameters

Parameters

rotation_axis – rotation axis, either np.array([x, y, z]) or ndarray with shape (3, n)
rotation_angle – rotation angle in radians, either float or array size n

Returns

rotation matrix R, either shape (3, 3) or (3, 3, n)

Example: R = rotation_matrix( np.array([4,4,1]), 1.2 ) v1 = np.array([3,5,0]) v2 = np.dot(R, v1)

coord.sgal2eq(v)[source]¶

Rotate supergalactic to equatorial coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in supergalactic coordinate system
Returns: vector(s) of shape (3, n) in equatorial coordinate system

coord.sgal2gal(v)[source]¶

Rotate supergalactic to galactic coordinates (same origin)

Parameters: v – cartesian vector(s) of shape (3, n) in supergalactic coordinate system
Returns: vector(s) of shape (3, n) in galactic coordinate system

coord.sph_unit_vectors(phi, theta)[source]¶

Get spherical unit vectors e_r, e_phi, e_theta from spherical angles phi theta.

Parameters

phi – range (pi, -pi), 0 points in x-direction, pi/2 in y-direction, float or array_like
theta – range (pi/2, -pi/2), pi/2 points in z-direction, float or array_like

Returns

shperical unit vectors e_r, e_phi, e_theta; each with shape (3, N)

coord.vec2ang(v)[source]¶

Get spherical angles (phi, theta) from a (list of) vector(s).

Parameters

v – vector(s) of shape (3, n)

Returns

tuple consisting of

phi [range (pi, -pi), 0 points in x-direction, pi/2 in y-direction],
theta [range (pi/2, -pi/2), pi/2 points in z-direction]