chronostar.utils package#

Submodules#

chronostar.utils.coordinate module#

coordinate.py

Module to handle various coordinate transformations.

TODO: Update docstrings to reflect the removal of astropy

chronostar.utils.coordinate.calc_eq2gc_matrix(a_deg=192.8595, d_deg=27.1283, th_deg=122.9319)#

Generate matrix to transform cartesian points determined by equatorial coordinates to cartesian points determined by Galactic coordinates

Using the RA (a) DEC (d) of Galactic north, and theta, generate matrix Default values are from J2000

Parameters:

  • a_deg (float (deg)) – right ascension of the north galactic pole

  • d_deg (float (deg)) – declination of the north galactic pole

  • th_deg (float (deg)) – position angle of the North Celestial Pole relative to the great semicircle passing through the NGP and zero Galactic longitude

Returns:

res

Return type:

[3x3] array

chronostar.utils.coordinate.calc_gc2eq_matrix(a_deg=192.8595, d_deg=27.1283, th_deg=122.9319)#

Generate a matrix that takes Galactic coordinates to equatorial

This is simply the inverse of the EQ to GC matrix

Parameters:

  • a_deg (float (deg)) – right ascension of the north galactic pole

  • d_deg (float (deg)) – declination of the north galactic pole

  • th_deg (float (deg)) – position angle of the North Celestial Pole relative to the great semicircle passing through the NGP and zero Galactic longitude

Returns:

result

Return type:

[6x6] array

chronostar.utils.coordinate.calc_pm_coord_matrix(a_deg, d_deg)#

Generate a coordinate matrix for calculating proper motions

This is matrix A in Johnson & Soderblom (1987)

chronostar.utils.coordinate.convert_angles2cartesian(theta_deg, phi_deg, radius=1.0)#

theta : angle (as astropy degrees) about the north pole (longitude, RA) phi : angle (as astropy degrees) from the plane (lattitude, dec))

Tested

chronostar.utils.coordinate.convert_astrometry2helioxyzuvw(a_deg, d_deg, pi, mu_a, mu_d, rv)#

Converts astrometry to heliocentric XYZUVW values

Parameters:

  • a_deg ((deg) right ascention) –

  • d_deg ((deg) declination) –

  • pi ((as) parallax) –

  • mu_a ((as/yr) proper motion in right ascension) –

  • mu_d ((as/yr) proper motion in declination) –

  • rv ((km/s) line of sight velocity) –

chronostar.utils.coordinate.convert_astrometry2lsrxyzuvw(astro, mas=True)#

Take a point straight from a catalogue, return it as XYZUVW

This function takes astrometry in conventional units, and converts them into internal units for convenience.

Parameters:

  • a ((deg) right ascention) –

  • d ((deg) declination) –

  • pi ((mas) parallax) –

  • mu_a ((mas/yr) proper motion in right ascension) –

  • mu_d ((mas/yr) proper motion in declination) –

  • rv ((km/s) line of sight velocity) –

  • mas (Boolean {True}) – set if input parallax and proper motions are in mas

Returns:

XYZUVW

Return type:

(pc, pc, pc, km/s, km/s, km/s)

chronostar.utils.coordinate.convert_cart2curvilin(data, ro=8.0, vo=220.0)#

MZ (2020 - 01 - 17)

Converts cartesian coordinates XYZUVW (given with respect to the LSR) to the curvilinear system. Curvilinear system is corotating so its radial component xi is always pointing towards the galactic center. Coordinates in the curvilinear system are [xi, eta, zeta, xidot, etadot, zetadot]

Parameters:

data ([6, (npoints)] float np.array) – [pc, pc, pc, km/s,km/s,km/s] [X, Y, Z, U, V, W]

Returns:

curvilin_coordinates – xi : radial distance from the origin in LSR eta : zeta : vertical distance from plane xidot : etadot : zetadot:

Return type:

[6, (npoints)] float np.array

chronostar.utils.coordinate.convert_cartesian2angles(x, y, z, return_dist=False)#

Tested

TODO: This takes up 10% of a run Uses astropy angles which slows everything down

chronostar.utils.coordinate.convert_curvilin2cart(data, ro=8.0, vo=220.0, lsr_centered=True)#

MZ (2020 - 01 - 17)

chronostar.utils.coordinate.convert_dec2deg(deg, arcm, arcs)#

Convert measurement of declination in deg arcmin, arcsec to decimal degrees

Parameters:

  • deg (int -or- string -or- float) – degrees value

  • arcm (int -or- string -or- float) – arc minute value

  • arcs (int -or- string -or- float) – arc second value

Returns:

result – declination in degrees

Return type:

float

chronostar.utils.coordinate.convert_equatorial2galactic(theta_deg, phi_deg)#

Convert equatorial (ra, dec) to galactic (longitude, latitude)

Parameters:

  • theta ((float) right ascension in degrees) –

  • phi ((float) declination in degrees) –

  • value ((bool) {True} Set flag if output desired as raw float (as opposed) – to an astropy unit object)

  • Output –

  • ------ –

  • pos_gc ((float, float) Galactic coordinates l and b, in degrees) –

chronostar.utils.coordinate.convert_galactic2equatorial(theta_deg, phi_deg, value=True)#

Convert galactic (longitude, latitude) to equatorial (ra, dec)

Parameters:

  • theta ((float) galactic l in degrees) –

  • phi ((float) galactic b in degrees) –

  • value ((bool) {True} Set flag if output desired as raw float (as opposed) – to an astropy unit object)

  • Output –

  • ------ –

  • pos_gc ((float, float) Equatorial coordinates RA and DEC, in degrees) –

chronostar.utils.coordinate.convert_helio2lsr(xyzuvw_helio, kpc=False)#

Convert cartesian xyzuvw position from helio-centred to LSR-centred

Assumes position is in pc unless stated otherwise

Parameters:

  • xyzuvw_helio ([6] array) – 3 position [pc] and 3 velocity with respect to the the sun

  • kpc (bool {False}) – If set, then treats input units of position as kpc (as opposed to pc)

Returns:

result – 3 position [pc] (or [kpc] if kpc set to True) and 3 velocity with respect to the local standard of rest

Return type:

[6] array

chronostar.utils.coordinate.convert_heliospacevelocity2pm(a_deg, d_deg, pi, u, v, w)#

Take the position and space velocities, return proper motions and rv

Parameters:

  • a_deg ((deg) right ascension) –

  • d_deg ((deg) declination) –

  • pi ((as) parallax) –

  • u ((km/s) heliocentric velocity towards galactic centre) –

  • v ((km/s) heliocentric velocity towards in direction of circular orbit) –

  • w ((km/s) heliocentric velocity towards galactic north) –

Returns:

  • mu_a ((as/yr) proper motion in right ascension)

  • mu_d ((as/yr) proper motion in declination)

  • rv ((km/s) line of sight velocity)

chronostar.utils.coordinate.convert_helioxyzuvw2astrometry(xyzuvw_helio)#

Takes as input heliocentric XYZUVW values, returns astrometry

Parameters:

xyzuvw_helio ((pc, pc, pc, km/s, km/s, km/s) array) – The position and velocity of a star in a right handed cartesian system centred on the sun

Returns:

  • a_deg ((deg) right ascention)

  • d_deg ((deg) declination)

  • pi ((as) parallax)

  • mu_a ((as/yr) proper motion in right ascension)

  • mu_d ((as/yr) proper motion in declination)

  • rv ((km/s) line of sight velocity)

chronostar.utils.coordinate.convert_lsr2helio(xyzuvw_lsr, kpc=False)#

Convert cartesian xyzuvw position from LSR-centred to helio-centred

Assumes position is in pc unless stated otherwise

Parameters:

  • xyzuvw_lsr ([6] array) – 3 position [pc] and 3 velocity with respect to the local standard of rest

  • kpc (bool {False}) – If set, then treats input units of position as kpc (as opposed to pc) and outputs in kpc. Use this flag if inputing position into Galpy!!!

Returns:

result – 3 position [pc] (or [kpc] if kpc set to True) and 3 velocity with respect to the sun

Return type:

[6] array

chronostar.utils.coordinate.convert_lsrxyzuvw2astrometry(xyzuvw_lsr)#

Takes as input heliocentric XYZUVW values, returns astrometry

Parameters:

xyzuvw_lsr ((pc, pc, pc, km/s, km/s, km/s) array) – The position and velocity of a star in a right handed cartesian system corotating with and centred on the local standard of rest

Returns:

  • a ((deg) right ascention)

  • d ((deg) declination)

  • pi ((mas) parallax)

  • mu_a ((mas/yr) proper motion in right ascension)

  • mu_d ((mas/yr) proper motion in declination)

  • rv ((km/s) line of sight velocity)

chronostar.utils.coordinate.convert_many_astrometry2lsrxyzuvw(astr_arr, mas=True)#

Take a point straight from a catalogue, return it as XYZUVW

This function takes astrometry in conventional units, and converts them into internal units for convenience.

Parameters:

  • a ((deg) right ascention) –

  • d ((deg) declination) –

  • pi ((mas) parallax) –

  • mu_a ((mas/yr) proper motion in right ascension) –

  • mu_d ((mas/yr) proper motion in declination) –

  • rv ((km/s) line of sight velocity) –

  • mas (Boolean {True}) – set if input parallax and proper motions are in mas

chronostar.utils.coordinate.convert_many_lsrxyzuvw2astrometry(xyzuvw_lsrs)#

Takes as input heliocentric XYZUVW values, returns astrometry

Parameters:

xyzuvw_lsr ((pc, pc, pc, km/s, km/s, km/s) array) – The position and velocity of a star in a right handed cartesian system corotating with and centred on the local standard of rest

Return type:

ndarray[Any, dtype[float64]]

Returns:

  • a ((deg) right ascention)

  • d ((deg) declination)

  • pi ((mas) parallax)

  • mu_a ((mas/yr) proper motion in right ascension)

  • mu_d ((mas/yr) proper motion in declination)

  • rv ((km/s) line of sight velocity)

chronostar.utils.coordinate.convert_pm2heliospacevelocity(a_deg, d_deg, pi, mu_a, mu_d, rv)#

Convert proper motions to space velocities

Parameters:

  • a_deg ((deg) right ascension in equatorial coordinates) –

  • d_deg ((deg) declination in equatorial coordinates) –

  • pi ((arcsec) parallax) –

  • mu_a ((arcsec/yr) proper motion in right ascension) –

  • mu_d ((arcsec/yr) proper motion in declination) –

  • rv ((km/s) radial velocity) –

Returns:

UVW

Return type:

[3] array

chronostar.utils.coordinate.convert_ra2deg(hh, mm, ss)#

Convert measurement of right ascension in hh:mm:ss to decimal degrees

Parameters:

  • hh (int -or- string -or- float) – hours component of right ascension

  • mm (int -or- string -or- float) – minutes component of right ascension

  • ss (int -or- string -or- float) – seconds component of right ascension

Returns:

result – Right ascension in degrees

Return type:

float

chronostar.utils.transform module#

A module which aids in the transformation of a covariance matrix between two coordinate frames.

These functions are used to convert astrometric covariance matrices into cartesian covariance matrices. Also to project cartesian Gaussian distributions forward (or backward) through the Galactic potential.

chronostar.utils.transform.calc_jacobian(trans_func, loc, dim=6, h=0.001, args=())#

Calculate the Jacobian of the coordinate transfromation trans_func about loc.

trans_func should take a vector of dimension dim to a new vector of same dimension. This function then calculates the 2nd order partial derivative at point loc. Extra arguments for trans_func can be provided as a tuple to args.

Parameters:

  • trans_func (function) – Transformation function taking us from the initial coordinate frame to the final coordinate frame

  • loc ([dim] float array) – The position (in the initial coordinte frame) around which we are calculating the jacobian

  • dim (int {6}) – The dimensionality of the coordinate frames

  • h (float {1e-3}) – The size of the increment, smaller values maybe run into numerical issues

  • args (tuple {None}) – Extra arguments required by trans_func

Returns:

  • [dim,dim] float array – A jacobian matrix

  • [dim] float array – Transformed location

Notes

OPTIMISATION TARGET

The application of trans_func is the bottleneck of Chronostar (at least when trans_func is traceorbit.trace_cartesian_orbit). Since this is a loop, there is scope for parallelisation.

chronostar.utils.transform.calc_jacobian_py(trans_func, loc, dim=6, h=0.001, args=())#

Calculate the Jacobian of the coordinate transfromation trans_func about loc.

trans_func should take a vector of dimension dim to a new vector of same dimension. This function then calculates the 2nd order partial derivative at point loc. Extra arguments for trans_func can be provided as a tuple to args.

Parameters:

  • trans_func (function) – Transformation function taking us from the initial coordinate frame to the final coordinate frame

  • loc ([dim] float array) – The position (in the initial coordinte frame) around which we are calculating the jacobian

  • dim (int {6}) – The dimensionality of the coordinate frames

  • h (float {1e-3}) – The size of the increment, smaller values maybe run into numerical issues

  • args (tuple {None}) – Extra arguments required by trans_func

Returns:

  • [dim,dim] float array – A jacobian matrix

  • [dim] float array – Transformed location

Notes

OPTIMISATION TARGET

The application of trans_func is the bottleneck of Chronostar (at least when trans_func is traceorbit.trace_cartesian_orbit). Since this is a loop, there is scope for parallelisation.

chronostar.utils.transform.transform_covmatrix(cov, trans_func, loc, dim=6, h=0.001, args=())#

Transforming a covariance matrix from one coordinate frame to another

Parameters:

  • cov ([dim,dim] float array) – Covariance matrix in the initial frame

  • trans_func (function) – Transformation function taking us from the initial coordinate frame to the final coordinate frame. Output must be mutable, i.e. single value, or an array

  • loc ([dim] float array) – The position (in the initial coordinate frame) around which we are calculating the jacobian (i.e. the mean, in the example of a Gaussian distribution)

  • dim (integer {6}) – The dimensionality of the coordinate frame

  • h (float {1e-3}) – The size of the increment, smaller values maybe run into numerical issues

  • args (tuple) – extra args to be passed to trans_func. E.g. for traceOrbitXYZUVW args = (age,) [for traceforward] or args = (-age,) [for traceback]

Returns:

  • [dim,dim] float array – The transformed covariance matrix

  • [dim] float array – The transformed location

chronostar.utils.transform.transform_covmatrix_py(cov, trans_func, loc, dim=6, h=0.001, args=())#

Transforming a covariance matrix from one coordinate frame to another

Parameters:

  • cov ([dim,dim] float array) – Covariance matrix in the initial frame

  • trans_func (function) – Transformation function taking us from the initial coordinate frame to the final coordinate frame. Output must be mutable, i.e. single value, or an array

  • loc ([dim] float array) – The position (in the initial coordinate frame) around which we are calculating the jacobian (i.e. the mean, in the example of a Gaussian distribution)

  • dim (integer {6}) – The dimensionality of the coordinate frame

  • h (float {1e-3}) – The size of the increment, smaller values maybe run into numerical issues

  • args (tuple) – extra args to be passed to trans_func. E.g. for traceOrbitXYZUVW args = (age,) [for traceforward] or args = (-age,) [for traceback]

Returns:

  • [dim,dim] float array – The transformed covariance matrix

  • [dim] float array – The transformed location

Module contents#