Detailed API documentation

Detailed API documentation#

class lbparticles.Potential#

Describes a potential function including its first and second derivatives.

This is an abstract class; always extend and override, never call directly.

For example implementations see LogPotential, HernquistPotential, NFWPotential, and PowerlawPotential.

abstract __call__(r: float)#

The expression for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

abstract ddr(r: float)#

The first derivative for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

abstract ddr2(r: float)#

The second derivative for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

abstract name()#: Describes the potential for use in uniquely identifying the Precomputer object once computation has finished

class lbparticles.LogPotential(vcirc, nur=None)#

__call__(r)#

The expression for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

ddr(r, IZ=0)#

The first derivative for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

ddr2(r, IZ=0)#

The second derivative for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

name()#: A unique identifier

class lbparticles.HernquistPotential(scale, mass, gravity=0.00449987)#

Create a HernquistPotential object.

Parameters:

scale (float) – The scale radius of the potential in parsecs.
mass (float) – The mass of the material producing the potential, in solar masses.
gravity (float) – The gravitational constant.

classmethod vcirc(scale, vcirc, gravity=0.00449987) → HernquistPotential#

classmethod mass(scale, mass, gravity=0.00449987) → HernquistPotential#

__call__(r)#

The expression for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

ddr(r)#

The first derivative for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

ddr2(r)#

The second derivative for the potential function with r being the variable

Parameters:: r (float) – The variable (radius) for central potential.

name()#: A unique name for the object

class lbparticles.PotentialWrapper(potential: Potential, nur=None, dlnnudr=None)#

DOCSTRING

__call__(r, Iz0=0)#: Call self as a function.

initialize_deltapsi()#

Omega(r, Iz0=0)#

kappa(r, Iz0=0)#

ddr(r, Iz0=0)#

ddr2(r, Iz0=0)#

vc(r, Iz0=0)#: The minus sign is due to the force being inward towards the centre and thus having a negative sign in the potential

gamma(r, Iz0=0)#: gamma = kappa/Omega = sqrt(2(beta+1)), where beta=dlnvc/dlnr

nu(r, Iz0=0)#

name() → str#

class lbparticles.Precomputer(time_order=10, shape_order=100, nchis=1000, N_grid_e=10, N_grid_nuk=4, grid_e_min=0.05, grid_e_max=0.95, grid_nuk_min=0.25, grid_nuk_max=0.6, Necc=10, Nnuk=5, alpha=2.2, logodds_initialized=False, eps=1e-08, use_multiprocessing=True)#

DOCSTRING

invert(order_shape)#

get_chi_index_arr(N)#: The precomputer evaluates several integrals on a grid uniformly-spaced (in chi) from 0 to 2pi. By default this grid has 1000 entries. Each particleLB generates its map between t and chi by querying lbprecomputer::get_t_terms, which returns an array of values at an array of chi values. The process of finding the values to return is often the most expensive part of initializing a particle. The particle may not need all 1000 entries. In this case, we need to find the points in the original 1000-element array that we would like to use in the new smaller array. This method returns that mapping. Given a new N (number of points to evaluate chi from 0 to 2pi), returns an array of size N with the indices into the full array 0,1,2,…self.nchis-1. The corresponding chi’s can be found by evaluating self.chi_eval[arr] where arr is the array returned by this method. This is done in the method lbprecomputer::get_chi_arr.

get_chi_arr(N)#: A convenience function to find the points where chi is evaluated if N points are requested. See documentation for lbprecomputer::get_chi_index_arr.

get_t_terms(kIn, eIn, Necc=None, nchis=None, includeNu=True, maxorder=None, debug=False)#

precompute_inverses_up_to(max_shape_order, hard_reset=False)#

classmethod load(filename) → Precomputer#

save() → None#

class lbparticles.Particle(xCartIn, vCartIn, psir, lbdata: None, ordershape=10, ordertime=10, quickreturn=False, nchis=300, Nevalz=1000, atolz=1e-07, rtolz=1e-07, zopt=VertOptionEnum.INTEGRATE, Necc=10)#

Instantiate a particle

Parameters:

xCartIn (a 3-element numpy array of floats) – The position of the particle in Cartesian coordinates x,y,z. If a disk potential is included (see zopt below), the disk is oriented such that its midplane is at z=0. The code was built under the assumption that the units of this vector are pc, but in principle by changing the gravitational constant a different units system can be adopted.
vCartIn (a 3-element numpy array of floats) – The velocity of the particle in Cartesian coordinates, vx,vy,vz. The code was built under the assumption that the units of this vector are pc/Myr, a unit very close to km/s.
psir (PotentialWrapper) – The potential in which the particle will orbit.
lbdata (Precomputer) – A precomputer object. The accuracy of the code depends on the precomputer being used. In particular the potential used to initialize the precomputer needs to be close enough to the potential used to initialize this particle (see psir above) that k as a function of e does not change drastically. See documentation of the precomputer for more details.
ordershape (int) – The number of terms to use in a cosine series to describe the relationship between phi (the angle around the galaxy) and eta (an angle encapsulating the galactocentric radius of the particle) Values greater than 5 are generally recommended, but will be application- dependent.
ordertime (int) – The number of terms to use in a cosine series relating time to chi (an angle encapsulating the galactocentric radius of the particle). Values greater than 5 are generally recommended, but will be application- dependent.
quickreturn (bool) – Whether to return the particle object “early” after only computing the conserved quantities (pericentre, apocentre, energy, angular momentum, k, eccentricity). The particle will not be able to report its position or velocity as a function of time.
nchis (int) – Number of values of chi to use to interpolate the relationship between chi and t. Must be less than or equal to the nchi used to initialize the precomputer. Values greater than ~100 are recommended.
Nevalz (int) – Number of time points to record the numerical solution of the z-integral when zopt (see below) is set to VertOptionEnum.INTEGRATE. Ignored otherwise. Serves a similar purpose as nchis. Values greater than ~100 are recommended.
atolz (float) – Absolute tolerance of the numerical integration for the z-integral when zopt (see below) is set to VertOptionEnum.INTEGRATE. Ignored otherwise. The integrator attempts to keep its error below atolz + rtolz*abs(z).
rtolz (float) – Relative tolerance of the numerical integration for the z-integral when zopt (see below) is set to VertOptionEnum.INTEGRATE. Ignored otherwise. The integrator attempts to keep its error below atolz + rtolz*abs(z).
zopt (int) – How to deal with vertical oscillations with the inclusion of a disk potential. Must be set to one of the following: - VertOptionEnum.INTEGRATE – numerically integrate z(t) for one orbital period. Robust, accurate, and a little bit costly. See parameters Nevalz, atolz, rtolz. - VertOptionEnum.FOURIER – expand the solution to z(t) in a Fourier series. Requires evaluation of formally-infinite determinants, but generally fast and accurate. Performance will depend on properties of nu(r). - VertOptionEnum.TILT – assume there is no influence from the disk. The particle will orbit in the plane specified by its initial angular momentum vector. - VertOptionEnum.FIRST – use the first order term in the Fiore (2022) Volterra series expansion. Only valid if nu(r) is a powerlaw. Fast but not accurate - VertOptionEnum.ZERO – use the 0th order term in the Fiore (2022) Volterra series expansion. Only valid if nu(r) is a powerlaw. Fast but not accurate
Necc (int) – The number of terms to use in the Taylor series expansion for the integrand determining t(chi), in terms of e. Must be less than Necc used to initialize the precomputer.

getpart(t)#

xvinclined(t)#

xvabs(t)#

xabs(t)#

getR(t)#

vabs(t)#

uvwinclined(t)#

xrelPart(t, part, tpart)#

nu(t)#

Norb(t)#

effcos(chi)#

effsin(chi)#

initialize_z_fourier(zorder=20)#

zvz_fourier(t)#

initialize_z_numerical(atol=1e-08, rtol=1e-08, Neval=1000)#

zvz_floquet(t)#

zvz(t)#

zphase_given_tperi(t)#

chi_excess_given_tperi(t)#

chi_given_tperi(t)#

phi(eta)#

essq(u)#

ess(u)#

t(chi)#

r_given_chi(chi)#

u_given_chi(chi)#

eta_given_chi(chi)#

emphi(eta)#: m*phi = eta - (1/8)*e^2 W0twiddle * sin(2 eta)

rvectorized(t)#

rphi(t)#

class lbparticles.PiecewiseParticleWrapper(particles: list[Particle] = [], splice_ts: list[float] = [])#

Create a PiecewiseParticleWrapper object.

Parameters:

particles (list[Particle]) – The scale radius of the potential in parsecs.
splice_ts (list[float]) – The mass of the material producing the potential, in solar masses.

add(particles: list[Particle] = [], splice_ts: list[float] = [])#

exists(t)#

getpart(t)#

xabs(t)#

xvabs(t)#

Detailed API documentation

Contents

Detailed API documentation#