Package: jampy
The JamPy PackageJeans Anisotropic Modelling for Galactic DynamicsJamPyis a Python implementation of the Jeans Anisotropic Modelling (JAM)
formalism for the dynamical modelling of galaxies.This software can be used e.g. to measure the mass of supermassive black holes
in galaxies, to infer their dark-matter content or to measure galaxy masses and
density profiles.The method calculates all the first and second velocity moments, for both the
intrinsic and the projected kinematics, in spherical and axisymmetric geometry.The JAM solution assuming a cylindrically-oriented velocity ellipsoid was introduced inCappellari (2008),
while the solution assuming a spherically-oriented velocity ellipsoid was introduced inCappellari (2020)ContentsThe JamPy PackageAttributionInstallationDocumentationjam_axi_projPurposeCalling SequenceInput ParametersOptional KeywordsOutput Parametersjam_axi_intrPurposeCalling SequenceInput ParametersOptional KeywordsOutput ParametersLicenseChangelogAttributionIf you use this software for your research, please citeCappellari (2008)for the cylindrically-aligned JAM solution andCappellari (2020)for the spherically-aligned JAM solution.The BibTeX entry for the two main JAM papers are respectively:@ARTICLE{Cappellari2008,
    author = {{Cappellari}, Michele},
    title = "{Measuring the inclination and mass-to-light ratio of axisymmetric
        galaxies via anisotropic Jeans models of stellar kinematics}",
    journal = {MNRAS},
    eprint = {0806.0042},
    year = 2008,
    volume = 390,
    pages = {71-86},
    doi = {10.1111/j.1365-2966.2008.13754.x}
}

@ARTICLE{Cappellari2020,
    author = {{Cappellari}, Michele},
    title = "{Efficient solution of the anisotropic spherically-aligned axisymmetric
        Jeans equations of stellar hydrodynamics for galactic dynamics}",
    journal = {MNRAS},
    eprint = {1907.09894},
    year = 2020,
    volume = 494,
    pages = {4819-4837},
    doi = {10.1093/mnras/staa959}
}Installationinstall with:pip install jampyWithout writing access to the globalsite-packagesdirectory, use:pip install --user jampyTo upgradeJamPyto the latest version use:pip install --upgrade jampyDocumentationFull documentation is contained in the individual files docstrings.Usage examples are contained in the directoryjampy/exampleswhich is copied bypipwithin the global foldersite-packages.What follows is the documentation of the two main procedures of theJamPypackage, extracted from their Python docstrings. The other procedures are
documented in their respective docstrings.The olderJamPyroutines from version < v6.0 are generally redundant,
but can be imported fromjampy.legacyand used like before.jam_axi_projPurposeThis procedure calculates a prediction for all the projected first or second
velocity moments for an anisotropic (three-integral) axisymmetric galaxy model.Any of the three components of the first velocity moment or any of the six
components of the symmetric velocity dispersion tensor are supported.
These include the line-of-sight velocities and the components of the proper motion.Two assumptions for the orientation of the velocity ellipsoid are supported:The cylindrically-aligned(R, z, phi)solution was presented inCappellari (2008)The spherically-aligned(r, th, phi)solution was presented inCappellari (2020)Calling Sequencefromjampy.jam_axi_projimportjam_axi_projjam=jam_axi_proj(surf_lum,sigma_lum,qobs_lum,surf_pot,sigma_pot,qobs_pot,inc,mbh,distance,xbin,ybin,align='cyl',analytic_los=True,beta=None,data=None,epsrel=1e-2,errors=None,flux_obs=None,gamma=None,goodbins=None,interp=True,kappa=None,logistic=False,ml=None,moment='zz',nang=10,nlos=1500,nodots=False,normpsf=1.,nrad=20,pixang=0.,pixsize=0.,plot=True,quiet=False,rbh=0.01,sigmapsf=0.,step=0.,vmax=None,vmin=None)vrms=jam.model# with moment='zz' the output is the LOS Vrmsjam.plot()# Generate data/model comparison when data is givenSee more examples in thejampy/examplesfolder insidesite-packages.Input Parameterssurf_lum: array_like with shape (n,)peak surface values of theMulti-Gaussian Expansion(MGE) Gaussians describing the
surface brightness of the tracer population for which the kinematics
is derived.The units are arbitrary as they cancel out in the final results.EXAMPLE: when one obtains the kinematics from optical spectroscopy,
surf_lum contains the galaxy optical surface brightness, which has
typical units ofLsun/pc^2(solar luminosities perparsec^2).sigma_lum: array_like with shape (n,)dispersion (sigma) in arcseconds of the MGE Gaussians describing the
distribution of the kinematic-tracer population.qobs_lum: array_like with shape (n,)observed axial ratio (q’) of the MGE Gaussians describing the
distribution of the kinematic-tracer population.surf_pot: array_like with shape (m,)peak value of the MGE Gaussians describing the galaxy total-mass
surface density in units ofMsun/pc^2(solar masses perparsec^2).
This is the MGE model from which the model gravitational potential is
computed.EXAMPLE: with a self-consistent model, one has the same Gaussians
for both the kinematic-tracer and the gravitational potential.
This impliessurf_pot = surf_lum,sigma_pot = sigma_lumandqobs_pot = qobs_lum. The global M/L of the model is fitted by the
routine when passing thedataanderrorskeywords with the
observed kinematics.sigma_pot: array_like with shape (m,)dispersion in arcseconds of the MGE Gaussians describing the galaxy
total-mass surface density.qobs_pot: array_like with shape (m,)observed axial ratio of the MGE Gaussians describing the galaxy
total-mass surface density.inc: floatinclination in degrees between the line-of-sight and the galaxy symmetry
axis (0 being face-on and 90 edge-on).mbh: floatMass of a nuclear supermassive black hole in solar masses.IMPORTANT: The model predictions are computed assumingsurf_potgives the total mass. In the self-consistent case, one hassurf_pot = surf_lumand if requested (keywordml) the program
can scale the outputmodelto best fit the data. The scaling is
equivalent to multiplyingbothsurf_potandmbhby a factor M/L.
To avoid mistakes, the actualmbhused by the output model is
printed on the screen.distance: floatthe distance of the galaxy inMpc. When the distance is derived
from redshift one should use the angular diameter distanceD_Ahere.xbin: array_like with shape (p,)X coordinates in arcseconds of the bins (or pixels) at which one wants
to compute the model predictions. The X-axis is assumed to coincide with
the galaxy projected major axis. The galaxy center is at(0,0).In general the coordinates(xbin, ybin)have to be rotated to bring
the galaxy major axis on the X-axis, before callingjam_axi_proj.When no PSF/pixel convolution is performed (sigmapsf=0orpixsize=0) there is a singularity at(0,0)which must be
avoided by the user in the input coordinates.ybin: array_like with shape (p,)Y coordinates in arcseconds of the bins (or pixels) at which one wants
to compute the model predictions. The Y-axis is assumed to coincide with
the projected galaxy symmetry axis.Optional Keywordsalign: {‘cyl’, ‘sph’}, optional.Assumed alignment for the velocity ellipsoid during the solution of
the Jeans equations.align='cyl'assumes a cylindrically-aligned velocity ellipsoid
using the solution ofCappellari (2008)align='sph'assumes a spherically-aligned velocity ellipsoid
using the solution ofCappellari (2020)analytic_los: bool, optionalThis isTrue(default) if the line-of-sight integral is performed
analytically andFalseif it is done via numerical quadrature.An analytic integral is only possible withalign='cyl'and only for
the second velocity moments. For this reason, when comparing the two
second-moment solutions withalign='cyl'andalign='sph', it
may be preferable to setanalytic_los=Falseto ensure that
numerical interpolation error is exactly the same in both cases.Whenalign='sph', or when the user requests a first velocity
moment, this keyword is automatically set toFalse.beta: array_like with shape (n,) or (4,)Radial anisotropy of the individual kinematic-tracer MGE Gaussians
(Default:beta=np.zeros(n)):beta = 1 - (sigma_th/sigma_r)^2  # with align='sph'
beta = 1 - (sigma_z/sigma_R)^2   # with align='cyl'Whenlogistic=Truethe procedure assumes:beta = [r_a, beta_0, beta_inf, alpha]and the anisotropy of the whole JAM model varies as a logistic
function of the logarithmic spherical radius (withalign='sph') or
of the logarithmic distance from the equatorial plane (withalign='cyl'):beta(r) = beta_0 + (beta_inf - beta_0)/[1 + (r_a/r)^alpha]    # with align='sph'
beta(z) = beta_0 + (beta_inf - beta_0)/[1 + (z_a/|z|)^alpha]  # with align='cyl'Herebeta_0represents the anisotropy atr = 0,beta_infis
the anisotropy atr = infandr_ais the anisotropy transition
radius (in arcsec likesigma_lum), withalphacontrolling the
sharpness of the transition.
In the special casebeta_0 = 0, beta_inf = 1, alpha = 2the
anisotropy variation reduces to the form by Osipkov & Merritt, but the
extra parameters allow for much more realistic anisotropy profiles. See
details and an application inSimon, Cappellari & Hartke (2024).data: array_like with shape (p,), optionalobserved first or second velocity moment used to fit the model.EXAMPLE: In the common case where one has only line-of-sight velocities
the second moment is given by:Vrms = np.sqrt(velBin**2 + sigBin**2)at the coordinates positions given by the vectorsxbinandybin.Ifdatais set andmlis negative orNone, then the model
is fitted to the data, otherwise, the adoptedmlis used and just
thechi**2is returned.epsrel: float, optionalRelative error requested for the numerical computation of the intrinsic
moments (before line-of-sight quadrature). (Default:epsrel=1e-2)errors: array_like with shape (p,), optional1sigma uncertainty associated with thedatameasurements.EXAMPLE: In the case where the data are given by theVrms =np.sqrt(velBin**2+sigBin**2), from the error propagation:errors = np.sqrt((dVel*velBin)**2 + (dSig*sigBin)**2)/Vrms,wherevelBinandsigBinare the velocity and dispersion in each
bin anddVelanddSigare the corresponding 1sigma uncertainties.
(Default: constanterrors = 0.05*np.median(data))flux_obs: array_like with shape (p,), optionalOptional mean surface brightness of each bin for plotting.gamma: array_like with shape (n,)tangential anisotropy of the individual kinematic-tracer MGE Gaussians
(Default:gamma=np.zeros(n)):gamma = 1 - (sigma_phi/sigma_r)^2  # with align='sph'
gamma = 1 - (sigma_phi/sigma_R)^2  # with align='cyl'Whenlogistic=Truethe procedure assumes:gamma = [r_a, gamma_0, gamma_inf, alpha]and the anisotropy of the whole JAM model varies as a logistic
function of the logarithmic spherical radius (withalign='sph') or
of the logarithmic distance from the equatorial plane (withalign='cyl'):gamma(r) = gamma_0 + (gamma_inf - gamma_0)/[1 + (r_a/r)^alpha]    # with align='sph'
gamma(z) = gamma_0 + (gamma_inf - gamma_0)/[1 + (z_a/|z|)^alpha]  # with align='cyl'Heregamma_0represents the anisotropy atr = 0,gamma_infis the anisotropy atr = infandr_ais the anisotropy
transition radius (in arcsec likesigma_lum), withalphacontrolling the sharpness of the transition. In the special casegamma_0 = 0, gamma_inf = 1, alpha = 2the anisotropy variation
reduces to the form by Osipkov & Merritt, but the extra parameters
allow for much more realistic anisotropy profiles.IMPORTANT:gammaonly affects the projected first velocity moments.
The projected second moments are rigorously independent ofgamma.goodbins: array_like with shape (p,)Boolean vector with valuesTruefor the bins/spaxels which have to
be included in the fit (if requested) and in thechi**2calculation.
(Default: fit all bins).interp: bool, optionalThis keyword is for advanced use only! Setinterp=Falseto force
no-interpolation on the sky plane. In this wayjam.velandjam.vel2contain all the first and second velocity moments at the
input coordinates(xbin, ybin), without PSF convolution.
By defaultinterp=Trueand one should generally not change this.IMPORTANT: Ifsigmapsf=0orpixsize=0orinterp=Falsethen
PSF convolution is not performed.This keyword is mainly useful for testing against analytic results or
to compute all moments, including proper motions,  simultaneously.kappa: float, optionalWhenkappa=None(default) the first velocity moments are scaled in
such a way that the projected angular momentum of the data and model is
the same [equation 52 ofCappellari (2008)].
Whenkappa=1the model first velocity moments are output without
any scaling.logistic: bool, optionalWhenlogistic=True, JAM interprets the anisotropy parametersbetaandgammaas defining a 4-parameters logistic function.
See the documentation of the anisotropy keywords for details.
(Defaultlogistic=False)ml: float, optionalMass-to-light ratio (M/L) to multiply the values given bysurf_pot.
Setting this keyword is completely equivalent to multiplying the
outputmodelbynp.sqrt(M/L)after the fit. This implies that
the BH mass is also scaled and becomesmbh*ml.Ifml=None(default) the M/L is fitted from the data and the
best-fitting M/L is returned in output. The BH mass of the model is
also scaled and becomesmbh*ml.moment: {‘x’, ‘y’, ‘z’, ‘xx’, ‘yy’, ‘zz’, ‘xy’, ‘xz’, ‘yz’}, optionalString specifying the component of the velocity first or second moments
requested by the user in output. All values ar inkm/s.moment='x'gives the first moment<V_x'>of the proper motion
in the direction orthogonal to the projected symmetry axis.moment='y'gives the first moment<V_y'>of the proper motion
in the direction parallel to the projected symmetry axis.moment='z'gives the first momentVlos = <V_z'>of the
line-of-sight velocity.moment='xx'givessqrt<V_x'^2>of the component of the proper
motion dispersion tensor in the direction orthogonal to the projected
symmetry axis.moment='yy'givessqrt<V_y'^2>of the component of the proper
motion dispersion tensor in the direction parallel to the projected
symmetry axis.moment='zz'(default) gives the usual line-of-sightVrms =sqrt<V_z'^2>.moment='xy'gives the mixed component<V_x'V_y'>of the proper
motion dispersion tensor.moment='xz'gives the mixed component<V_x'V_z'>of the proper
motion dispersion tensor.moment='yz'gives the mixed component<V_y'V_z'>of the proper
motion dispersion tensor.nang: int, optionalThe number of linearly-spaced intervals in the eccentric anomaly at
which the model is evaluated before interpolation and PSF convolution.
(default:nang=10)nlos: int (optional)Number of values used for the numerical line-of-sight quadrature.
(defaultnlos=1500)nodots: bool, optionalSet toTrueto hide the dots indicating the centers of the bins in
the linearly-interpolated two-dimensional map (defaultFalse).normpsf: array_like with shape (q,)fraction of the total PSF flux contained in the circular Gaussians
describing the PSF of the kinematic observations.
The PSF will be used for seeing convolution of the model kinematics.
It has to benp.sum(normpsf) = 1.nrad: int, optionalThe number of logarithmically spaced radial positions at which the
model is evaluated before interpolation and PSF convolution. One may
want to increase this value if the model has to be evaluated over many
orders of magnitude in radius (default:nrad=20).pixang: float, optionalAngle between the observed spaxels and the galaxy major axis X.
This angle only rotates the spaxels around their centers,notthe
whole coordinate system(xbin, ybin), which must be rotated
independently by the user before callingjam_axi_proj.
Using the keyword is generally unnecessary.pixsize: float, optionalSize in arcseconds of the (square) spatial elements at which the
kinematics is obtained. This may correspond to the side of the spaxel
or lenslets of an integral-field spectrograph. This size is used to
compute the kernel for the seeing and aperture convolution.IMPORTANT: Ifsigmapsf=0orpixsize=0orinterp=Falsethen
PSF convolution is not performed.plot: boolWhendata is not Nonesetting this keyword produces a plot with the
data/model comparison at the end of the calculation.quiet: boolSet this keyword to avoid printing values on the console.rbh: float, optionalThis keyword is ignored unlessalign='cyl'andanalytic_los=True.
In all other cases JAM assume a point-like central black hole.
This scalar gives the sigma in arcsec of the Gaussian approximating the
central black hole of mass MBH [See Section 3.1.2 ofCappellari (2008)]
The gravitational potential is indistinguishable from a point source
forradii > 2*rbh, so the defaultrbh=0.01arcsec is appropriate
in most current situations.When using different units as input, e.g. pc instead of arcsec, one
should check thatrbhis not too many order of magnitude smaller
than the spatial resolution of the data.sigmapsf: array_like with shape (q,)dispersion in arcseconds of the circular Gaussians describing the PSF
of the kinematic observations.IMPORTANT: Ifsigmapsf=0orpixsize=0orinterp=Falsethen
PSF convolution is not performed.IMPORTANT: PSF convolution is done by creating a 2D image, with pixels
size given bystep=np.min(sigmapsf)/4, and convolving it with the
PSF + aperture. If the input radii are very large compared tostep,
the 2D image may require a too large amount of memory. If this is the
case one may compute the model predictions at small radii with a first
call tojam_axi_projwith PSF convolution, and the model
predictions at large radii with a second call tojam_axi_projwithout PSF convolution.step: float, optionalSpatial step for the model calculation and PSF convolution in arcsec.
This value is automatically computed by default asstep=np.min(sigmapsf)/4. It is assumed that whensigmapsfis
large, high-resolution calculations are not needed. In some cases,
however, e.g. to accurately estimate the Vrms inside a large aperture,
comparable with the PSF size, one may want to override the default
value to force smaller spatial pixels using this keyword.vmax: float, optionalMaximum value of thedatato plot.vmin: float, optionalMinimum value of thedatato plot.Output ParametersStored as attributes of thejam_axi_projclass..chi2: floatReducedchi**2, namely per degree of freedom,  describing the
quality of the fit:d, m = (data/errors)[goodbins], (model/errors)[goodbins]
chi2 = ((d - m)**2).sum()/goodbins.sum()When no data are given in input, this is returned asnp.nan..flux: array_like with shape (p,)PSF-convolved MGE surface brightness of each bin inLsun/pc^2,
used to plot the isophotes of the kinematic-tracer on the model results..kappa: floatRatio by which the model was scaled to fit the observed velocity
[defined by equation 52 ofCappellari (2008)].ml: floatBest fitting M/L by which the mass was scaled to fit the observed moments..model: array_like with shape (p,)Model predictions for the selected velocity moments for each input bin(xbin, ybin). This attribute is the main output from the program.Any of the six components of the symmetric proper motion dispersion
tensor{'xx', 'yy', 'zz', 'xy', 'xz', 'yz'}, or any of the three
first velocity moments{'x', 'y', 'z'}can be returned in output.
The desired model output is selected using themomentkeyword.
See themomentdocumentation for details..vel: array_like with shape (3, p)This attribute generally contains an intermediate result of the
calculation and should not be used. Instead, the output kinematic
model predictions are contained in the.modelattribute.However, for advanced use only, when settinginterp=Falseandanalytic_los=False, this attribute contains the first velocity
moments for all the x, y and z components,notPSF convolved, at the
sky coordinates(xbin, ybin)..vel2: array_like with shape (3, 3, p)This attribute generally contains an intermediate result of the
calculation and should not be used. Instead, the output kinematic
model predictions are contained in the.modelattribute.However, for advanced use only, when settinginterp=Falseandanalytic_los=False, this attribute contains the full 3x3 second
velocity moment tensor,notPSF convolved, at the sky coordinates(xbin, ybin).jam_axi_intrPurposeThis procedure calculates all the intrinsic first and second velocity
moments for an anisotropic axisymmetric galaxy model.This program is useful e.g. to model the kinematics of galaxies
like our Milky Way, for which the intrinsic moments can be observed
directly, or to compute starting conditions for N-body numerical
simulations of galaxies.Two assumptions for the orientation of the velocity ellipsoid are supported:The cylindrically-aligned(R, z, phi)solution was presented inCappellari (2008)The spherically-aligned(r, th, phi)solution was presented inCappellari (2020)Calling Sequencefromjampy.jam_axi_intrimportjam_axi_intrjam=jam_axi_intr(dens_lum,sigma_lum,qintr_lum,dens_pot,sigma_pot,qintr_pot,mbh,Rbin,zbin,align='cyl',beta=None,data=None,epsrel=1e-2,errors=None,gamma=None,goodbins=None,interp=True,logistic=False,ml=None,nang=10,nodots=False,nrad=20,plot=True,proj_cyl=False,quiet=False)# The meaning of the output is different depending on `align`sig2R,sig2z,sig2phi,v2phi=jam.model# with align='cyl'sig2r,sig2th,sig2phi,v2phi=jam.model# with align='sph'jam.plot()# Generate data/model comparisonInput Parametersdens_lum: array_like with shape (n,)vector containing the peak value of the MGE Gaussians describing
the intrinsic density of the tracer population for which the kinematics
is derived.
The units are arbitrary as they cancel out in the final results.
Typical units are e.g.Lsun/pc^3(solar luminosities perparsec^3)sigma_lum: array_like with shape (n,)vector containing the dispersion (sigma) inpcof the MGE
Gaussians describing the galaxy kinematic-tracer population.qintr_lum: array_like with shape (n,)vector containing the intrinsic axial ratio (q) of the MGE
Gaussians describing the galaxy kinematic-tracer population.surf_pot: array_like with shape (m,)vector containing the peak value of the MGE Gaussians
describing the galaxy total-mass density in units ofMsun/pc^3(solar masses perparsec^3). This is the MGE model from which the
model gravitational potential is computed.sigma_pot: array_like with shape (m,)vector containing the dispersion inpcof the MGE
Gaussians describing the galaxy total-mass density.qintr_pot: array_like with shape (m,)vector containing the intrinsic axial ratio of the MGE
Gaussians describing the galaxy total-mass density.mbh: floatMass of a nuclear supermassive black hole in solar masses.Rbin: array_like with shape (p,)Vector with theRcoordinates inpcof the bins (or pixels) at
which one wants to compute the model predictions. This is the first
cylindrical coordinate(R, z)with the galaxy center at(0,0).There is a singularity at(0, 0)which should be avoided by the user
in the input coordinates.zbin: array_like with shape (p,)Vector with thezcoordinates inpcof the bins (or pixels) at
which one wants to compute the model predictions. This is the second
cylindrical coordinate(R, z), with the z-axis coincident with the
galaxy symmetry axis.Optional Keywordsalign: {‘cyl’, ‘sph’} optionalIfalign='cyl'the program computes the solution of the Jeans
equations with cylindrically-aligned velocity ellipsoid, presented
inCappellari (2008). Ifalign='sph'the spherically-aligned
solution ofCappellari (2020)is returned.beta: array_like with shape (n,) or (4,)Vector with the axial anisotropy of the individual kinematic-tracer
MGE Gaussians (Default:beta=np.zeros(n)):beta = 1 - (sigma_th/sigma_r)^2  # with align='sph'
beta = 1 - (sigma_z/sigma_R)^2   # with align='cyl'Whenlogistic=Truethe procedure assumes:beta = [r_a, beta_0, beta_inf, alpha]and the anisotropy of the whole JAM model varies as a logistic
function of the logarithmic spherical radius (withalign='sph') or
of the logarithmic distance from the equatorial plane (withalign='cyl'):beta(r) = beta_0 + (beta_inf - beta_0)/[1 + (r_a/r)^alpha]    # with align='sph'
beta(z) = beta_0 + (beta_inf - beta_0)/[1 + (z_a/|z|)^alpha]  # with align='cyl'Herebeta_0represents the anisotropy atr = 0,beta_infis
the anisotropy atr = infandr_ais the anisotropy transition
radius (in arcsec likesigma_lum), withalphacontrolling the
sharpness of the transition.
In the special casebeta_0 = 0, beta_inf = 1, alpha = 2the
anisotropy variation reduces to the form by Osipkov & Merritt, but the
extra parameters allow for much more realistic anisotropy profiles. See
details and an application inSimon, Cappellari & Hartke (2024).data: array_like of shape (4, p), optionalFour input vectors with the observed values of:[sigR, sigz, sigphi, vrms_phi]inkm/s, whenalign='cyl'(oralign='sph'andproj_cyl=True).vrms_phiis the square root of the velocity second moment in the
tangential direction. If the velocitiesvphi_jare measured from
individual stars thenvrms_phi = sqrt(mean(vphi_j^2)).
One can also use the relationvrms_phi = sqrt(vphi^2 + sigphi^2),
wherevphi = mean(vphi_j)andsigphi = std(vphi_j)[sigr, sigth, sigphi, vrms_phi]inkm/s, whenalign='sph',
wherevrms_phiis defined above.epsrel: float, optionalRelative error requested for the numerical quadratures, before
interpolation (Default:epsrel=1e-2).errors: array_like of shape (4, p), optional1sigmauncertainties ondata, in the same format (default 5km/s).gamma: array_like with shape (n,)Vector with the tangential anisotropy of the individual kinematic-tracer
MGE Gaussians (Default:gamma=np.zeros(n)):gamma = 1 - (sigma_phi/sigma_r)^2  # with align='sph'
gamma = 1 - (sigma_phi/sigma_R)^2  # with align='cyl'Whenlogistic=Truethe procedure assumes:gamma = [r_a, gamma_0, gamma_inf, alpha]and the anisotropy of the whole JAM model varies as a logistic
function of the logarithmic spherical radius (withalign='sph') or
of the logarithmic distance from the equatorial plane (withalign='cyl'):gamma(r) = gamma_0 + (gamma_inf - gamma_0)/[1 + (r_a/r)^alpha]    # with align='sph'
gamma(z) = gamma_0 + (gamma_inf - gamma_0)/[1 + (z_a/|z|)^alpha]  # with align='cyl'Heregamma_0represents the anisotropy atr = 0,gamma_infis the anisotropy atr = infandr_ais the anisotropy
transition radius (in arcsec likesigma_lum), withalphacontrolling the sharpness of the transition. In the special casegamma_0 = 0, gamma_inf = 1, alpha = 2the anisotropy variation
reduces to the form by Osipkov & Merritt, but the extra parameters
allow for much more realistic anisotropy profiles.IMPORTANT:gammaonly affects the projected first velocity moments.
The projected second moments are rigorously independent ofgamma.goodbins: array_like with shape (4, p), optionalBoolean vector of the same shape asdatawith valuesTruefor the bins which have to be included in the fit (if requested) andchi^2calculation (Default: fit all bins).interp: bool, optionalIfinterp=Falseno interpolation is performed and the model is
computed at every set of input (R, z) coordinates.
Ifinterp=True(default), the model is interpolated if the number
of requested input (R, z) coordinates is larger thannang*nrad.logistic: bool, optionalWhenlogistic=True, JAM interprets the anisotropy parametersbetaandgammaas defining a 4-parameters logistic function.
See the documentation of the anisotropy keywords for details.
(Defaultlogistic=False)ml: float, optionalMass-to-light ratio M/L. Ifml=None(default) the M/L is fitted to
the data and the best-fitting value is returned in output.
Thembhis also scaled and becomesmbh*ml.
Ifml=1no scaling is applied to the model.nang: int, optionalThe number of linearly-spaced intervals in the eccentric anomaly at
which the model is evaluated before interpolation (default:nang=10).nodots: bool, optionalSet toTrueto hide the dots indicating the centers of the bins in
the two-dimensional map (defaultFalse).nrad: int, optionalThe number of logarithmically spaced radial positions at which the
model is evaluated before interpolation. One may want to increase this
value if the model has to be evaluated over many orders of magnitude in
radius (default:nrad=20).plot: bool, optionalIfplot=True(default) anddata is not None, produce a plot of
the data-model comparison at the end of the calculation.proj_cyl: bool, optionalIfalign='sph'andproj_cyl=True, the function projects the
spherically-aligned moments to cylindrical coordinates and returns the[sig2R, sig2z, sig2phi, v2phi]components as in the casealign='cyl'. This is useful for a direct comparison of results with
either the spherical or cylindrical alignment, as it allows one to fit
the same data with both modelling assumptions.quiet: bool, optionalIfquiet=False(default), print the best-fitting M/L and chi2 at
the end for the calculation.Output ParametersReturned as attributes of thejam_axi_intrclass..chi2: floatReduced chi^2 (chi^2/DOF) describing the quality of the fit:d = (data/errors)[goodbins]
m = (model/errors)[goodbins]
chi2 = ((d - m)**2).sum()/goodbins.sum().flux: array_like  with shape (p,)Vector with the MGE luminosity density at each(R, z)location inLsun/pc^3, used to plot the isophotes on the model results..ml: floatBest fitting M/L. This value is fitted while ignoringsigphiand it
is strictly independent of the adopted tangential anisotropygamma..model: array_like with shape (4, p)Contains[sig2R, sig2z, sig2phi, v2phi]withalign='cyl'Contains[sig2r, sig2th, sig2phi, v2phi]withalign='sph'where the above quantities are defined as follows:sig2R (sig2r): array_like with shape (p,)squared intrinsic dispersion in(km/s)^2along the R (r)
direction at each(R, z)location.sig2z (sig2th): array_like with shape (p,)squared intrinsic dispersion in(km/s)^2along the z (th)
direction at each(R, z)location.sig2phi: array_like with shape (p,)squared intrinsic dispersion in(km/s)^2along the
tangentialphidirection at each(R, z)location.v2phi: array_like with shape (p,)the second velocity moment in(km/s)^2along the
tangentialphidirection at each(R, z)location.The mean velocity along the tangential direction can be computed asvphi = np.sqrt(v2phi - sig2phi)NOTE: I return squared velocities instead of taking the square root,
to allow for negative values (unphysical solutions).LicenseOther/Proprietary LicenseCopyright (c) 2003-2024 Michele CappellariThis software is provided as is with no warranty. You may use it for
non-commercial purposes and modify it for personal or internal use, as long
as you include this copyright and disclaimer in all copies. You may not
redistribute the code.ChangelogV7.2.4: MC, Oxford, 10 January 2024jam_axi_proj: Support prolate models withqobs_lum > 1orqobs_pot > 1.jam_axi_proj: Output unconvolved surface brightnessjam.fluxwhen no
PSF/aperture convolution is applied to the kinematics, due to zerosigmapsforpixsize.mge_vcirc: Use scale-independent integration ranges like other JamPy
functions.jam_axi_sersic: Includesigma_ein the output and enable rotated
aperture option. Updated docstring.V7.2.1: MC, Oxford, 21 July 2023jam_axi_intr: Integrate all velocity components at the same time with a
single call to the updatedquad1dandquad2d. Significant speedup.quad1d,quad2d: Allow for integration of vector functions. All
components are integrated over the same set of evaluation points.jam_axi_proj: Updated verbose output with more information.New procedurejam_axi_sersicto efficiently compute dynamical masses of
axisymmetric galaxies described by Sersic profiles while allowing for seeing
and aperture effects and assuming a given intrinsic axial ratio. This is
meant to be a simple and quick replacement for the similar but less accurate
virial estimators.New utility functioncosmology_distanceused in examples.V7.1.0: MC, Oxford, 5 June 2023Separated computation for the black hole kinematics for both the
cylindrically and spherically-aligned solutions. In both cases, this removed
one numerical quadrature. This is useful in extreme situations when the
minimum radius one wants to model around the black hole is orders of
magnitude smaller than the smallest MGE Gaussian. This change eliminated the
need for therbhkeyword injam_axi_intr, which I removed. The only
case where the black hole is still approximated with a small Gaussian is injam_axi_projwhen bothalign='cyl'andanalytic_los=True.Adopted minimum radius based onstepfor the intrinsic interpolation grid
as already done for the projected one.Simplified minimum-inclination test.Removedlegacyfolder with old redundant procedures.Moved the formalism for the LOS analytic integrand withalign='cyl'intojam_axi_proj.jam_axi_proj,jam_axi_intr,jam_sph_proj,jam_sph_intr: New
keywordlogisticto specify when JAM should interpret the input
anisotropy parametersbetaandgammaas defining a logistic function
anisotropy profile.jam_axi_intr: Use DE quadrature from[z, inf]instead of[0, 1]withalign='cyl'as already done withalign='sph'.jam_hernquist_model_example: New test against Osipkov-Merritt radial
variation of the anisotropy usinglogistic=True. Revised plot.V7.0.10: MC, Oxford, 17 January 2023Introduced an analytic radial variation of the anisotropybetaandgammausing a flexible logistic function of logarithmic radiusbeta(r) = beta_0 + (beta_inf -beta_0)/[1+(r_a/r)^alpha].
This function specifies the inner/outer anisotropybeta_0andbeta_inf, the anisotropy radiusr_aand the sharpnessalphaof the transition. This new function is an alternative to assigning
different anisotropies to different Gaussians. All proceduresjam_axi_proj,jam_axi_intr,jam_sph_projandjam_sph_intr,
with bothalign='sph'andalign='cyl', were modified, documented
and extensively tested to support the variable-anisotropy function.jam_sph_proj_example: adapted to show the usage of the new analytic
radial anisotropy variation.jam_axi_intr: Fixed program stop in the plotting function.jam_axi_proj: Raise an error whenrbhis too small.jam_axi_proj: Raise an error if the user includes the singularity(x,y) = (0,0)in the input coordinates without PSF convolution.quad1d: new defaultssingular=0andepsabs=0likequad2d.V6.4.0: MC, Oxford, 3 October 2022jam_sph_proj: Created this new function by renaming the procedurelegacy.jam_sph_rmsand changing its interface to be consistent with
the axisymmetric version.jam_sph_proj: Included special isotropic formula for testing.jam_sph_proj: Included Osipkov-Merritt anisotropy for testing.jam_sph_proj: Made quadrature limits insensitive to scaling.jam_sph_proj: Simplified integrand with formulas of Cappellari (2020)
and using recurrence relations to reduce calls to special functions.jam_sph_proj: More efficient TANH transformation of the integration
variable following Cappellari (2020).jam_sph_intr: New function to compute the intrinsic moments in
spherical symmetry.jam_axi_proj: Removed fixed minimum radius limit in pc for the
interpolation without PSF convolution. This avoids the risk of artificial
truncation when using small arbitrary spatial coordinates for testing.jam_axi_proj: Tenfold increase of LOS evaluations tonlos=1500.New procedureexamples.jam_dark_halo_bayes_example.py.Renamedquadvaasquad1dwith modified interface and newsingularkeyword to skip transforming the integration variable.V6.3.3: MC, Oxford, 7 July 2021jam_axi_proj: Clarified meaning ofinterpkeyword in docstring.
Thanks to Kai Zhu (nao.cas.cn) for the feedback.jam_axi_proj: print “No PSF/pixel convolution” wheninterp == False.V6.3.2: MC, Oxford, 28 April 2021Use the newjam_axi_projinstead oflegacysoftware in the examples.Removed redundantlegacyexamples.V6.3.1: MC, Oxford, 11 November 2020jam_axi_proj: New keywordanalytic_losto chose between numeric
or analytic line-of-sight integral for the second velocity moment,
whenalign='cyl'.jam_axi_proj: Increased default value ofnloskeyword.jam_axi_proj: Raise an error ifrbhis too small.jam_axi_projandjam_axi_intr: Removed**kwargsargument and
included newnodotskeyword passed toplot_velfield.V6.2.1: MC, Oxford, 15 September 2020jam_axi_proj: Fixed program stop whendata == ml == None.
Thank to Bitao Wang (pku.edu.cn) for reporting.V6.2.0: MC, Oxford, 17 August 2020jam_axi_proj: Avoid possible division by zero after convolution,
when the tracer MGE is much smaller than the field of view.jam_axi_proj: Fully broadcastedvmom_proj.jam_axi_proj: Removed minimum-radius clipping invmom_proj.jam_axi_proj: Newinterpkeyword to force no-interpolation
when using the full first and second velocity moments simultaneously.Madejam.plot()callable afterjam_axi_projorjam_axi_intr.New axisymmetric analytic vs MGE test inmge_vcirc_example.mge_vcirc: Upgraded formalism.Fixed Numpy 1.9VisibleDeprecationWarning.Updated documentation.V6.1.5: MC, Oxford, 23 July 2020Fixed program stop in first velocity moment without input data,
introduced in V6.1.2. Thanks to Bitao Wang (pku.edu.cn) for reporting.Implemented thekappainput keyword as scalar.V6.1.4: MC, Oxford, 16 July 2020Addedkappato the returned parameters ofjam_axi_proj.Compute both velocity and Vrms injam_axi_proj_example.V6.1.3: MC, Oxford, 13 July 2020Fixed program stop inlegacy.jam_axi_veldue to a variable name typo
introduced in V6.1.2.V6.1.2: MC, Oxford, 20 June 2020jam_axi_proj: Fixed inputmlbeing ignored. Thanks to Sabine
Thater (univie.ac.at) and Takafumi Tsukui (grad.nao.ac.jp) for reporting.jam_axi_rms: I reduced the interpolation error before the PSF
convolution for all the routines in thelegacysub-folder, as already
implemented in the newjam_axi_proj. Thanks to Takafumi Tsukui
(grad.nao.ac.jp) for reporting differences.jam_axi_intr: Request inputdata = [sigR, sigz, sigphi, vrms_phi]instead ofdata = [sigR, sigz, sigphi, vphi].jam_axi_intr: excludesigphifrommlfitting. These two
changes make the fittedmlstrictly independent of the adopted
tangential anisotropygamma.V6.0.1: MC, Oxford, 23 April 2020Fixedmodeloutput when fittingml.
Thanks to Selina Nitschai (mpia-hd.mpg.de) for reporting.V6.0.0: MC, Oxford, 22 April 2020Major changes to the wholejampypackage: from this version
I include the new spherically-aligned solution of the Jeans
equations from Cappellari (2020, MNRAS).Two new functionsjam_axi_intrandjam_axi_projnow provide either the intrinsic or the projected moments,
respectively, for both the spherically-aligned and
cylindrically-aligned JAM solutions.I moved the previous proceduresjam_axi_rms,jam_axi_velandjam_sph_rmsto thejampy.legacyfolder.V5.0.23: MC, Oxford, 31 October 2019Use analyticmge_surfin convolution.V5.0.22: MC, Oxford, 21 March 2019Reformatted documentation of all procedures.V5.0.21: MC, Oxford, 14 February 2019Significant speedup ofmge_vcirc.Formatted documentation.Created package-wide CHANGELOG: before this version, the
CHANGELOG file only refers to the procedurejam_axi_rms.V5.0.16: MC, Oxford, 27 September 2018Fixed clockDeprecationWarningin Python 3.7.V5.0.15: MC, Oxford, 12 May 2018Dropped Python 2.7 support.V5.0.14: MC, Oxford, 17 April 2018FixedMatplotlibDeprecationWarningin Matplotlib 2.2.Changed imports for jam as a package.Removed example.V5.0.13: MC, Oxford, 7 March 2018Check that PSF is normalized.V5.0.12: MC, Oxford, 22 January 2018Print a message when no PSF convolution was performed.Broadcast kernel and MGE convolution loops.Fixed missing tensor in assertion test.V5.0.11: MC, Oxford, 10 September 2017Make defaultstepdepend onsigmapsfregardless ofpixsize.V5.0.10: MC, Oxford, 10 August 2017Raise an error ifgoodbinsis all False.V5.0.9: MC, Oxford, 17 March 2017Includedflux_obskeyword. Updated documentation.FixedDeprecationWarningin Numpy 1.12.V5.0.8: MC, Oxford, 17 February 2017Use odd kernel size for convolution.Fixed corner case with coordinates falling outside the
interpolation region, due to finite machine precision.V5.0.7: MC, Oxford, 23 February 2016Scale rmsModel by the input M/L also when rms is not given.
Thanks to Alex Grainger (Oxford) for pointing out the inconsistency.Pass**kwargsfor plotting.V5.0.6: MC, Oxford, 18 September 2015Plot bad bins on the data.V5.0.5: MC, Oxford, 23 May 2015Changed the meaning ofgoodbinsto be a boolean vector.V5.0.4: MC, Sydney, 5 February 2015Introduced further checks on matching input sizes.V5.0.3: MC, Oxford, 31 October 2014Modified final plot layout.V5.0.2: MC, Oxford, 25 May 2014Support both Python 2.7 and Python 3.V5.0.1: MC, Oxford, 24 February 2014Plot bi-symmetrizedV_rmsas in IDL version.V5.0.0: MC, Paranal, 11 November 2013Translated from IDL into Python.V4.1.5: MC, Paranal, 8 November 2013Use renamed CAP* routines to avoid potential naming conflicts.V4.1.4: MC, Oxford, 12 February 2013Include _EXTRA and RANGE keywords for plotting.V4.1.3: MC, Oxford, 1 February 2013Output FLUX inLsun/pc^2.V4.1.2: MC, Oxford, 28 May 2012Updated documentation.V4.1.1: MC, Oxford, 8 December 2011Only calculates FLUX if required.V4.1.0: MC, Oxford 19 October 2010Included TENSOR keyword to calculate any of the six components of
the symmetric proper motion dispersion tensor (as in note 5 of the paper).V4.0.9: MC, Oxford, 15 September 2010Plot and output with the FLUX keyword the PSF-convolved MGE surface brightness.V4.0.8: MC, Oxford, 09 August 2010Use linear instead of smooth interpolation. After feedback from Eric Emsellem.V4.0.7: MC, Oxford, 01 March 2010Forcesq_lum && q_pot < 1.V4.0.6: MC, Oxford, 08 February 2010The routine TEST_JAM_AXISYMMETRIC_RMS with the usage example now adopts
more realistic input kinematics.Updated documentation.V4.0.5: MC, Oxford, 6 July 2009Skip unnecessary interpolation when computing a few points without PSF
convolution. After feedback from Eric Emsellem.V4.0.4: MC, Oxford, 29 May 2009Compute FLUX even when not plotting.V4.0.3: MC, Oxford 4 April 2009Added keyword RBH.V4.0.2: MC, Oxford, 21 November 2008Added keywords NRAD and NANG. Thanks to Michael Williams for
reporting possible problems with too coarse interpolation.V4.0.1: MC, Windhoek, 29 September 2008Bug fix: when ERMS was not given, the default was not properly set.
Included keyword STEP. The keyword FLUX is now only used for output:
the surface brightness for plotting is computed from the MGE model.V4.0.0: MC, Oxford, 11 September 2008Implemented PSF convolution using interpolation on a polar grid.
Dramatic speed-up of calculation. Further documentation.V3.2.0: MC, Oxford, 14 August 2008Updated documentation.V3.1.3: MC, Oxford, 12 August 2008First released version.V2.0.0: MC, Oxford, 20 September 2007Introduced a new solution of the MGE Jeans equations with constant
anisotropysig_R = b*sig_z.V1.0.0: Michele Cappellari, Vicenza, 19 November 2003Written and tested