jampy 5.0.21

JamPy: Jeans Anisotropic Models of Galactic Dynamics

Jeans Anisotropic Modelling of Galactic Dynamics

JamPy is a Python implementation of the Jeans Anisotropic Modelling (JAM) formalism of Cappellari (2008), for galactic dynamics, in spherical and axisymmetric geometry.

JamPy also includes the updates for proper motions in axisymmetric and spherical geometry of Cappellari (2012) and Cappellari (2015) respectively.

Contents

• Attribution

• Installation

• Documentation

• Purpose of jam_axi_rms

• Calling Sequence

• Input Parameters

• Optional Keywords

• Output Parameters

• License

• Changelog

Attribution

If you use this software for your research, please cite Cappellari (2008). And if you use it for proper motions, also cite the relevant papers above. The BibTeX entry for the main JAM paper is:

@ARTICLE{Cappellari2008,
    author = {{Cappellari}, M.},
    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}
}

Installation

install with:

pip install jampy

Without writing access to the global site-packages directory, use:

pip install --user jampy

Documentation

Full documentation is contained in the individual files headers.

Usage examples are contained in the directory jampy/examples, which is copied by pip within the site-packages folder.

What follows is the documentation of one of the main procedures, extracted from the Python file header.

Purpose of jam_axi_rms

This procedure calculates a prediction for the projected second velocity moment V_RMS = sqrt(V**2 + sigma**2), or optionally any of the six components of the symmetric proper motion dispersion tensor, for an anisotropic axisymmetric galaxy model. It implements the solution of the anisotropic Jeans equations presented in equation (28) and note 5 of Cappellari (2008). PSF convolution in done as described in the Appendix of that paper. See Cappellari (2012; C12) for explicit formulas for the full proper motion tensor.

Calling Sequence

rmsModel, ml, chi2, flux = \
   jam_axi_rms(surf_lum, sigma_lum, qobs_lum, surf_pot, sigma_pot, qobs_pot,
                inc, mbh, distance, xbin, ybin, beta=None, erms=None,
                flux_obs=None, goodbins=None, ml=None, nang=10, normpsf=1.,
                nrad=20, pixang=0., pixsize=0., plot=True, quiet=False,
                rbh=0.01, rms=None, sigmapsf=0., step=0., tensor='zz',
                vmax=None, vmin=None)

Input Parameters

SURF_LUM:

vector of length N containing the peak surface brightness of the MGE Gaussians describing the galaxy surface brightness in units of Lsun/pc**2 (solar luminosities per parsec**2).

SIGMA_LUM:

vector of length N containing the dispersion in arcseconds of the MGE Gaussians describing the galaxy surface brightness.

QOBS_LUM:

vector of length N containing the observed axial ratio of the MGE Gaussians describing the galaxy surface brightness.

SURF_POT:

vector of length M containing the peak value of the MGE Gaussians describing the galaxy surface density in units of Msun/pc**2 (solar masses per parsec**2). This is the MGE model from which the model potential is computed.

In a common usage scenario, with a self-consistent model, one has the same Gaussians for both the surface brightness and the potential. This implies SURF_POT = SURF_LUM, SIGMA_POT = SIGMA_LUM and QOBS_POT = QOBS_LUM. The global M/L of the model is fitted by the routine when passing the RMS and ERMS keywords with the observed kinematics.

SIGMA_POT:

vector of length M containing the dispersion in arcseconds of the MGE Gaussians describing the galaxy surface density.

QOBS_POT:

vector of length M containing the observed axial ratio of the MGE Gaussians describing the galaxy surface density.

INC:

inclination in degrees (90 being edge-on).

MBH:

Mass of a nuclear supermassive black hole in solar masses.

VERY IMPORTANT: The model predictions are computed assuming SURF_POT gives the total mass. In the common self-consistent case one has SURF_POT = SURF_LUM and if requested (keyword ML) the program can scale the output RMSMODEL to best fit the data. The scaling is equivalent to multiplying both SURF_POT and MBH by a factor M/L. To avoid mistakes, the actual MBH used by the output model is printed on the screen.

DISTANCE:

distance of the galaxy in Mpc.

XBIN:

Vector of length P with the 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).

When no PSF/pixel convolution is performed (SIGMAPSF=0 or PIXSIZE=0) there is a singularity at (0,0) which should be avoided by the input coordinates.

YBIN:

Vector of length P with the 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 Keywords

BETA:

Vector of length N with the anisotropy beta_z = 1 - (sigma_z/sigma_R)**2 of the individual MGE Gaussians.

ERMS:

Vector of length P with the 1sigma errors associated to the RMS measurements. From the error propagation:

ERMS = sqrt((dVel*velBin)^2 + (dSig*sigBin)^2)/RMS,

where velBin and sigBin are the velocity and dispersion in each bin and dVel and dSig are the corresponding errors. (Default: constant errors ERMS=0.05*np.median(RMS))

FLUX_OBS:

Optional mean surface brightness of each bin for plotting.

GOODBINS:

Boolean vector of length P with values True for the bins which have to be included in the fit (if requested) and chi**2 calculation. (Default: fit all bins).

ML:

Mass-to-light ratio to multiply the values given by SURF_POT. Setting this keyword is completely equivalent to multiplying the output RMSMODEL by np.sqrt(M/L) after the fit. This implies that the BH mass becomes MBH*(M/L).

If this keyword is not set, or set to a negative number in input, the M/L is fitted from the data and the best-fitting M/L is returned in output. The BH mass of the best-fitting model is MBH*(M/L).

NORMPSF:

Vector of length Q with the fraction of the total PSF flux contained in the circular Gaussians describing the PSF of the observations. It has to be np.sum(NORMPSF) = 1. The PSF will be used for seeing convolution of the model kinematics.

NANG:

Same as for NRAD, but for the number of angular intervals (default: NANG=10).

NRAD:

Number of logarithmically spaced radial positions for which the models 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 magnitutes in radius (default: NRAD=20). The computation time scales as NRAD*NANG.

PIXANG:

angle between the observed spaxels and the galaxy major axis X.

PIXSIZE:

Size 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.

If this is not set, or PIXSIZE=0, then convolution is not performed.

PLOT:

Set this keyword to produce a plot at the end of the calculation.

QUIET:

Set this keyword to avoid printing values on the screen.

RBH:

This scalar gives the sigma in arcsec of the Gaussian representing the central black hole of mass MBH (See Section 3.1.2 of Cappellari 2008.) The gravitational potential is indistinguishable from a point source for radii > 2*RBH, so the default RBH=0.01 arcsec is appropriate in most current situations.

RBH should not be decreased unless actually needed!

RMS:

Vector of length P with the input observed velocity second moment:

V_RMS = sqrt(velBin**2 + sigBin**2)

at the coordinates positions given by the vectors XBIN and YBIN.

If RMS is set and ML is negative or not set, then the model is fitted to the data, otherwise the adopted ML is used and just the chi**2 is returned.

SIGMAPSF:

Vector of length Q with the dispersion in arcseconds of the circular Gaussians describing the PSF of the observations.

If this is not set, or SIGMAPSF=0, then convolution is not performed.

IMPORTANT: PSF convolution is done by creating a 2D image, with pixels size given by STEP=MAX(SIGMAPSF, PIXSIZE/2)/4, and convolving it with the PSF + aperture. If the input radii RAD are very large with respect to STEP, 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 separately from those at large radii, where PSF convolution is not needed.

STEP:

Spatial step for the model calculation and PSF convolution in arcsec. This value is automatically computed by default as STEP=MAX(SIGMAPSF,PIXSIZE/2)/4. It is assumed that when PIXSIZE or SIGMAPSF are big, high resolution calculations are not needed. In some cases however, e.g. to accurately estimate the central Vrms in a very cuspy galaxy inside a large aperture, one may want to override the default value to force smaller spatial pixels using this keyword.

TENSOR:

String specifying the component of the velocity dispersion tensor.

TENSOR='xx' gives sigma_xx=sqrt<V_x’^2> of the component of the proper motion dispersion tensor in the direction parallel to the projected major axis.

TENSOR='yy' gives sigma_yy=sqrt<V_y’^2> of the component of the proper motion dispersion tensor in the direction parallel to the projected symmetry axis.

TENSOR='zz' (default) gives the usual line-of-sight V_rms=sqrt<V_z’^2>.

TENSOR='xy' gives the mixed component <V_x’V_y’> of the proper motion dispersion tensor.

TENSOR='xz' gives the mixed component <V_x’V_z’> of the proper motion dispersion tensor.

TENSOR='yz' gives the mixed component <V_y’V_z’> of the proper motion dispersion tensor.

VMAX:

Maximum value of the Vrms to plot.

VMIN:

Minimum value of the Vrms to plot.

Output Parameters

RMSMODEL:

Vector of length P with the model predictions for the velocity second moments for each bin:

V_RMS = sqrt(vel**2 + sig**2)

Any of the six components of the symmetric proper motion dispersion tensor can be provided in output using the TENSOR keyword.

ML:

Best fitting M/L.

CHI2:

Reduced chi**2 describing the quality of the fit:

chi2 = (((rms[goodBins] - rmsModel[goodBins])/erms[goodBins])**2).sum()
     / goodBins.sum()

FLUX:

Vector of length P with the PSF-convolved MGE surface brightness of each bin in Lsun/pc**2, used to plot the isophotes on the model results.

License

Other/Proprietary License

Copyright (c) 2003-2019 Michele Cappellari

This software is provided as is without any warranty whatsoever. Permission to use, for non-commercial purposes is granted. Permission to modify for personal or internal use is granted, provided this copyright and disclaimer are included in all copies of the software. All other rights are reserved. In particular, redistribution of the code is not allowed.

Changelog

V5.0.21: MC, Oxford, 14 February 2019

• Significant speed up of mge_vcirc.

• Formatted documentation.

• Created package-wide CHANGELOG: before this version, the CHANGELOG file only refers to the procedure jam_axi_rms.

V5.0.16: MC, Oxford, 27 September 2018

• Fixed clock DeprecationWarning in Python 3.7.

V5.0.15: MC, Oxford, 12 May 2018

• Dropped Python 2.7 support.

V5.0.14: MC, Oxford, 17 April 2018

• Fixed MatplotlibDeprecationWarning in Matplotlib 2.2.

• Changed imports for jam as a package.

• Removed example.

V5.0.13: MC, Oxford, 7 March 2018

• Check that PSF is normalized.

V5.0.12: MC, Oxford, 22 January 2018

• Print 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 2017

• Make default step depend on sigmapsf regardless of pixsize.

V5.0.10: MC, Oxford, 10 August 2017

• Raise an error if goodbins is all False.

V5.0.9: MC, Oxford, 17 March 2017

• Included flux_obs keyword. Updated documentation.

• Fixed DeprecationWarning in Numpy 1.12.

V5.0.8: MC, Oxford, 17 February 2017

• Use 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 2016

• Scale rmsModel by the input M/L also when rms is not given. Thanks to Alex Grainger (Oxford) for pointing out the inconsistency.

• Pass **kwargs for plotting.

V5.0.6: MC, Oxford, 18 September 2015

• Plot bad bins on the data.

V5.0.5: MC, Oxford, 23 May 2015

• Changed meaning of goodbins to be a boolean vector.

V5.0.4: MC, Sydney, 5 February 2015

• Introduced further checks on matching input sizes.

V5.0.3: MC, Oxford, 31 October 2014

• Modified final plot layout.

V5.0.2: MC, Oxford, 25 May 2014

• Support both Python 2.7 and Python 3.

V5.0.1: MC, Oxford, 24 February 2014

• Plot bi-symmetrized V_rms as in IDL version.

V5.0.0: MC, Paranal, 11 November 2013

• Translated from IDL into Python.

V4.1.5: MC, Paranal, 8 November 2013

• Use renamed CAP_* routines to avoid potential naming conflicts.

V4.1.4: MC, Oxford, 12 February 2013

• Include _EXTRA and RANGE keywords for plotting.

V4.1.3: MC, Oxford, 1 February 2013

• Output FLUX in Lsun/pc^2.

V4.1.2: MC, Oxford, 28 May 2012

• Updated documentation.

V4.1.1: MC, Oxford, 8 December 2011

• Only calculates FLUX if required.

V4.1.0: MC, Oxford 19 October 2010

• Included 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 2010

• Plot and output with FLUX keyword the PSF-convolved MGE surface brightness.

V4.0.8: MC, Oxford, 09 August 2010

Use linear instead of smooth interpolation. After feedback from Eric Emsellem.

V4.0.7: MC, Oxford, 01 March 2010

• Forces q_lum && q_pot < 1.

V4.0.6: MC, Oxford, 08 February 2010

• The routine TEST_JAM_AXISYMMETRIC_RMS with the usage example now adopts a more realistic input kinematics.

• Updated documentation.

V4.0.5: MC, Oxford, 6 July 2009

• Skip unnecessary interpolation when computing few points without PSF convolution. After feedback from Eric Emsellem.

V4.0.4: MC, Oxford, 29 May 2009

• Compute FLUX even when not plotting.

V4.0.3: MC, Oxford 4 April 2009

• Added keyword RBH.

V4.0.2: MC, Oxford, 21 November 2008

• Added keywords NRAD and NANG. Thanks to Michael Williams for reporting possible problems with too coarse interpolation.

V4.0.1: MC, Windhoek, 29 September 2008

• Bug 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 2008

• Implemented PSF convolution using interpolation on polar grid. Dramatic speed-up of calculation. Further documentation.

V3.2.0: MC, Oxford, 14 August 2008

• Updated documentation.

V3.1.3: MC, Oxford, 12 August 2008

• First released version.

V2.0.0: MC, Oxford, 20 September 2007

• Introduced new solution of the MGE Jeans equations with constant anisotropy sig_R = b*sig_z.

V1.0.0: Michele Cappellari, Vicenza, 19 November 2003

• Written and tested