API reference

tropygal

tropygal.V_d(dim)

Volume of (unit-radius) hyper-sphere of dimension d

Parameters:

dim (int) – dimension

Returns:

the volume [pi^(dim/2.)]/Gamma(dim/2. + 1)

Return type:

float number

tropygal.density(data, data_base=None, k=1, correct_bias=False, vol_correction='cube', l_cube_over_d=None, workers=-1)

Estimate the density (pdf) for best use in NN entropy estimate.

f_i = exp(psi(k)) / [ (M-1) * V_d * D^d ], where: M is size of sample building the tree psi is the digamma function V_d is the volume of unitary hypersphere in d-dimensions D is the Euclidean distance to kth neighbor

Parameters:

• data (array [N, dim]) – Data points to be queried

• data_base (array [M, dim]) – Data points of sample that will serve to build the tree, while previous data array is for the query points. If data_base is not provided, it’s assumed that data_base = data and M = N

• k (in number) – kth nearest neighbor

• correct_bias (Boolean) – If correct for bias due to boundary effects as proposed by Charzynska & Gambin 2015

• vol_correction (string) – strategy for correction: - ‘cube’: the support is assumed to be a paralelepiped, and the volume around each point is a cube

• l_cube_over_d (float) – Side of cube around each point divided by D, the distance to the k-neighbor. A typically good choice is a cube inscribed in the sphere, i.e. side/D = 2/sqrt(dim). If None, this is set by default

• workers (int (default: -1, meaning using all CPUs available).) – Number of CPUs to be used to parallelize the seacrh for NNs.

Returns:

density estimate f_i = exp(psi(k)) / [ (M-1) * V_d * D^d ]

Return type:

float

References

[1]

14. Leonenko, L. Pronzato, V. Savani, “A class of Rényi information estimators for multidimensional densities.”, Ann. Statist. 36 (5) 2153 - 2182, 2008

tropygal.entropy(data, mu=1, k=1, correct_bias=False, vol_correction='cube', l_cube_over_d=None, workers=-1)

Estimate of (Shannon/Jaynes) differential entropy S = - int f ln (f/mu) d^dim x.

The factor mu ensures that f/mu is dimensionless. It also stores the density of states if the DF is a function of integrals only. For precise estimates, we also want all (x_1, x_2…, x_dim) to be order unit.

S is estimated as - (1/N) * sum_i ( ln(f_i) - ln(mu_i), where f_i is the estimate of the DF f around point/particle/star i For NN (Nerest Neighbor) method: From e.g. Eq. (10) in Leonenko, Pronzato, Savani (2008): f_i = exp(psi(k)) / [ (N-1) * V_d * D^d ], where: N is sample size psi is the digamma function V_d is the volume of unitary hypersphere in d-dimensions D is the Euclidean distance to kth neighbor

Parameters:

• data (array [N, dim]) – Data points

• mu (float number or array of size N) – It ensures the argument of ln() is dimensionless. If x -> = x/sigma_x, y -> y/sigma_y… -> mu = 1/(sigma_x*sigma_y…). It is also the density of states, e.g. mu = g(E), mu = g(E,L) or mu = (2pi)^3, in cases where the DF depends only on integrals, e.g. energy, or energy and angular momentum, or actions, respectively.

• k (int value) – kth nearest neighbor

• correct_bias (Boolean) – If correct for bias due to boundary effects as proposed by Charzynska & Gambin 2015

• vol_correction (string) – strategy for correction: - ‘cube’: the support is assumed to be a paralelepiped, and the volume around each point is a cube

• l_cube_over_d (float) – side of cube around each point divided by D, the distance to the k-neighbor. A typically good choice is a cube inscribed in the sphere, i.e. side/D = 2/sqrt(dim). If None, this is set by default

• workers (int (default: -1, meaning using all CPUs available)) – Number of CPUs to be used to parallelize the seacrh for NNs.

Returns:

entropy estimate -<ln(f/mu)> = - (1/N)*sum_i ln(f_i/mu_i)

Return type:

float

References

[1]

14. Leonenko, L. Pronzato, V. Savani, “A class of Rényi information estimators for multidimensional densities.”, Ann. Statist. 36 (5) 2153 - 2182, 2008

tropygal.cross_entropy(data, data_base, mu=1, k=1, correct_bias=False, vol_correction='cube', l_cube_over_d=None, workers=-1)

Estimate of the cross entropy H = - int f0 ln (f/mu) d^dim x. The factor mu ensures that f/mu is dimensionless and it also stores the density of states if the DF is a function of integrals only. For precise estimates, we also want all (x_1, x_2…, x_dim) to be order unit. H is estimated as (1/N) * sum_i=1^N ln(f_i), where f_i is the estimate of the DF f based on the dist. of point i in sample 1 to its kth neighbor in sample 2. For NN (Nerest Neighbor) method: From e.g. Eq. (11) in Leonenko, Pronzato, Savani (2008): f_i = exp(psi(k)) / [ M * V_d * D^d ], where: N is size of sample 1, M is size of sample 2, psi is the digamma function, V_d is the volume of unitary hypersphere in d-dimensions, D is the Euclidean distance of particle i in sample 1 to its kth neighbor in sample 2.

Parameters:

• data (array [N, dim]) – Data points of sample 1

• data_base (array [M, dim]) – Data points of sample 2

• mu (float number or array of size N) – It ensures the argument of ln() is dimensionless. If x -> = x/sigma_x, y -> y/sigma_y… -> mu = 1/(sigma_x*sigma_y…). It is also the density of states, e.g. mu = g(E), mu = g(E,L) or mu = (2pi)^3, in cases where the DF depends only on integrals, e.g. energy, or energy and angular momentum, or actions, respectively.

• k (int value) – kth nearest neighbor

• correct_bias (Boolean) – If correct for bias due to boundary effects as proposed by Charzynska & Gambin 2015

• vol_correction (string) – strategy for correction: - ‘cube’: the support is assumed to be a paralelepiped, and the volume around each point is a cube

• l_cube_over_d (float) – Side of cube around each point divided by D, the distance to the k-neighbor. A typically good choice is a cube inscribed in the sphere, i.e. side/D = 2/sqrt(dim). If None, this is set by default

• workers (int (default: -1, meaning using all CPUs available).) – Number of CPUs to be used to parallelize the seacrh for NNs.

Returns:

cross entropy estimate -<ln(f/mu)> = - (1/N)*sum_i=1^N ln(f_i/mu_i)

Return type:

float

tropygal.C_k(q, k=1)

For Renyi entropy. Check Eq. (7) in Leonenko, Pronzato, Savani (2008)

Parameters:

• q (float number) – q index in Rényi entropy (must be != 1)

• k (int value) – kth nearest neighbor

Returns:

C_k

Return type:

float

tropygal.renyi_entropy(data, mu=1, q=2, k=1)

Estimate of Rényi entropy S_q = [1/(1 - q)] ln int f (f/mu)^(q-1) d^dim x, for q != 1. The factor mu ensures that f/mu is dimensionless.

S_q is estimated as [1/(1-q)] ln (1/N) * sum_i=1^N (f_i/mu_i)^(q-1), where f_i is the estimate of the DF f around point/particle/star i For NN (Nerest Neighbor) method: From e.g. Eq. (7) in Leonenko, Pronzato, Savani (2008): f_i = 1/[ (N-1) * C_k * V_d * D^dim ], where C_k = [Gamma(k)/Gamma(k+1-q)]^[1/(1-q)]

Parameters:

• data (array [N, dim]) – Data points

• mu (float number or array of size N) – It ensures the argument of ln() is dimensionless. If x’ = x/sigma_x, y’ = y/sigma_y… -> mu = 1/(sigma_x*sigma_y…). It is also the density of states, e.g. mu = g(E), mu = g(E,L) or mu = (2pi)^3, in cases where the DF depends only on integrals, e.g. energy, or energy and angular momentum, or actions, respectively.

• q (float value) – q-parameter of the entropy; needs to be q != 1

• k (int value) – kth nearest neighbor

Returns:

entropy estimate [1/(1 - q)] ln <(f/mu)^(q-1)>

Return type:

float

tropygal.tsallis_entropy(data, mu=1, q=2, k=1)

Estimate of Tsallis entropy S_q = [1/(q - 1)][ 1 - int f (f/mu)^(q-1) d^dim x ], for q != 1. The factor mu ensures that f/mu is dimensionless.

S_q is estimated as [1/(q - 1)] [ 1 - (1/N) * sum_i=1^N (f_i/mu_i)^(q-1) ], where f_i is the estimate of the DF f around point/particle/star i For NN (Nerest Neighbor) method: From e.g. Eq. (7) in Leonenko, Pronzato, Savani (2008): f_i = 1/[ (N-1) * C_k * V_d * D^dim ], where C_k = [Gamma(k)/Gamma(k+1-q)]^[1/(1-q)]

Parameters:

• data (array [N, dim]) – Data points

• mu (float number or array of size N) – It ensures the argument of ln() is dimensionless. If x -> = x/sigma_x, y -> y/sigma_y… -> mu = 1/(sigma_x*sigma_y…). It is also the density of states, e.g. mu = g(E), mu = g(E,L) or mu = (2pi)^3, in cases where the DF depends only on integrals, e.g. energy, or energy and angular momentum, or actions, respectively.

• q (int value) – q-parameter of the entropy; needs to be q != 1

• k (int value) – kth nearest neighbor

Returns:

entropy estimate [1/(q - 1)] [ 1 - <f^(q-1)> ]

Return type:

float

tropygal.DF_Isochrone(E, M, b, G=4.300831457814024e-06)

Distribution Function (DF) of isochrone model - see [1]_, Eq. (4.54).

Parameters:

• E (float) – energy

• M (float) – total mass

• b (float) – scale lenght

• G (float) – gravitational constant (standard value in kpc Msun^-1 (km/s)2)

Returns:

the DF

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.g_Isochrone(E, M, b, G=4.300831457814024e-06)

The density of states for the isotropic isochrone model – see [1]_.

Parameters:

• E (float) – energy

• M (float) – total mass

• b (float) – scale lenght

• G (float) – gravitational constant (standard value in kpc Msun^-1 (km/s)2)

Returns:

the density of states

Return type:

float

References

[1]

Binney, J., & Petrou, M. 1985, MNRAS, 214, 449

tropygal.Tr_Isochrone(E, M, G=4.300831457814024e-06)

The period of radial oscillation for the isochrone model

Parameters:

• E (float) – energy

• M (float) – total mass

• G (float) – gravitational constant (standard value in kpc Msun^-1 (km/s)2)

Returns:

the period of radial motion

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.gEL_Isochrone(E, L, M, G=4.300831457814024e-06)

The density of states for the isochrone model, but assuming (generically) a DF that depends on energy and angular momentum

Parameters:

• E (float) – energy

• L (float) – angular momentum

• M (float) – total mass

• G (float) – gravitational constant (standard value in kpc Msun^-1 (km/s)2)

Returns:

the density of states

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.DF_Hernquist(E, M, b, G=4.300831457814024e-06)

Distribution Function (DF) of Hernquist model - see Hernquist (1990)

Parameters:

• E (float) – energy

• M (float) – total mass

• b (float) – scale lenght

• G (float) – gravitational constant (standard value in kpc Msun^-1 (km/s)2)

Returns:

the DF

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

[2]

Hernquist, L. (1990)

tropygal.g_Hernquist(E, M, b, G=4.300831457814024e-06)

The density of states for the Hernquist model

Parameters:

• E (float) – energy

• M (float) – total mass

• b (float) – scale lenght

• G (float) – gravitational constant (standard value in kpc Msun^-1 (km/s)2)

• params (array) – the parameters to be used in Phi and dPhi_dr

Returns:

the density of states

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

[2]

Hernquist, L. (1990)

tropygal.Tr_Spherical(E, L, Phi, dPhi_dr, params)

The period of radial oscillation, T_r, for the a generic spherical potential. See Binney & Tremaine (2008) - eq. (3.17). T_r can be used, among other things, to calculate the density of states for DFs assumed to depend on energy and angular momentum as g(E,L) = 8 pi^2 L T_r(E,L).

Parameters:

• E (array (or scalar)) – energy of particle

• L (array (or scalar)) – angular momentum of particle

• Phi (function) – function with signature (r, params), evaluating the potential at each radius

• dPhi_dr (function) – function with signature (r, params), evaluating the derivative of the potential at each radius

• params (array) – the parameters to be used in Phi and dPhi_dr

Returns:

The period of radial motion

Return type:

float array

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.gEL_Spherical(E, L, Phi, dPhi_dr, params)

The density of states assuming a DF that depends on energy and angular momentum, in a generic spherical potential. It requires a function calculating the potential Phi and another calculating its derivative

Parameters:

• E (array (or scalar)) – energy of particle

• L (array (or scalar)) – angular momentum of particle

• Phi (function) – total potential

• dPhi_dr (function) – derivative of the potential

• params (array) – the parameters to be used in Phi and dPhi_dr

Returns:

the density of states

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.find_Phi_eff_min(L, dPhi_dr, params, range_0=(0.001, 1000.0), max_range=100000000.0)

Find the location of the minimum of the effective potential. The effective potential is defined as Phi_eff = Phi + L**2/(2.*r**2). This function is primarily to calculate the peri- and apo-center radii rper and rapo, but can also be used with any other purposes. rper and rapo, on the other hand, are primarily calculated to calculate the period of radial motion T_r. T_r on its turn can be used to calculate the density of states for DFs assumed to depend on energy and angular momentum as g(E,L) = 8 pi^2 L T_r(E,L).

Parameters:

• L (array (or scalar)) – angular momentum of particle

• dPhi_dr (function) – function with signature (r, params), evaluating the derivative of the potential at each radius

• params (array) – the parameters to be used in Phi and dPhi_dr

• range_0 (tuple) – the initial range within which we search for the root of dPhi_eff_dr

Returns:

Arrays containing rper and rapo for all particles used at input

Return type:

array, array

tropygal.find_rper_rapo(E, L, Phi, dPhi_dr, params, range_0=(0.01, 100.0), max_range=100000000.0)

Find peri- and apo-center distances with interval adjustments. It first identifies rmin, the location of the minimum of the effective potential. The effective potential is defined as Phi_eff = Phi + L**2/(2.*r**2). Then it defines the range where brentq should look for roots, such that the pericenter radius rper is searched from rmin inwards, and rapo is searched from rmin outwards. rper and rapo are primarily calculated to calculate the period of radial motion T_r. T_r on its turn can be used to calculate the density of states for DFs assumed to depend on energy and angular momentum as g(E,L) = 8 pi^2 L T_r(E,L).

Parameters:

• E (array (or scalar)) – energy of particle

• L (array (or scalar)) – angular momentum of particle

• Phi (function) – function with signature (r, params), evaluating the potential at each radius

• dPhi_dr (function) – function with signature (r, params), evaluating the derivative of the potential at each radius

• params (array) – the parameters to be used in Phi and dPhi_dr

• range_0 (tuple) – the initial range within which we search for the roots defining rper and rapo

Returns:

Arrays containing rper and rapo for all particles used at input

Return type:

array, array

tropygal.Phi_Isochrone(r, params)

The gravitational potential for the Isochrone model.

Parameters:

• r (array (or scalar)) – radial coordinate of particle

• params (array) – the parameters to be used in the potential.

Returns:

The potential evaluated at radius r.

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.dPhi_dr_Isochrone(r, params)

The derivative of the gravitational potential for the Isochrone model.

Parameters:

• r (array (or scalar)) – radial coordinate of particle

• params (array) – the parameters to be used in the potential.

Returns:

The derivative of the potential, evaluated at a radius r.

Return type:

float

References

[1]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.Phi_Hernquist(r, params)

The gravitational potential for the Hernquist model.

Parameters:

• r (array (or scalar)) – radial coordinate of particle

• params (array) – the parameters to be used in the potential.

Returns:

The potential evaluated at radius r.

Return type:

float

References

[1]

Hernquist, L (1990).

[2]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press

tropygal.dPhi_dr_Hernquist(r, params)

The derivative of the gravitational potential for the Hernquist model.

Parameters:

• r (array (or scalar)) – radial coordinate of particle

• params (array) – the parameters to be used in the potential.

Returns:

The derivative of the potential, evaluated at a radius r.

Return type:

float

References

[1]

Hernquist, L (1990).

[2]

Binney, J., & Tremaine, S. (2008). Galactic Dynamics (2nd ed.). Princeton University Press