SCFPotential¶

class
gala.potential.scf.
SCFPotential
(m, r_s, Snlm, Tnlm, units=None, origin=None, R=None)¶ Bases:
gala.potential.potential.CPotentialBase
A gravitational potential represented as a basis function expansion. This uses the selfconsistent field (SCF) method of Hernquist & Ostriker (1992) and Lowing et al. (2011), and represents all coefficients as real quantities.
 Parameters
 mnumeric
Scale mass.
 r_snumeric
Scale length.
 Snlmarray_like
Array of coefficients for the cos() terms of the expansion. This should be a 3D array with shape
(nmax+1, lmax+1, lmax+1)
, wherenmax
is the number of radial expansion terms andlmax
is the number of spherical harmonicl
terms. Tnlmarray_like
Array of coefficients for the sin() terms of the expansion. This should be a 3D array with shape
(nmax+1, lmax+1, lmax+1)
, wherenmax
is the number of radial expansion terms andlmax
is the number of spherical harmonicl
terms. unitsiterable
Unique list of nonreducable units that specify (at minimum) the length, mass, time, and angle units.
Attributes Summary
mass_enclosed
(q, t)Estimate the mass enclosed within the given position by assuming the potential is spherical.
Change the unit system of this potential.
Methods Summary
__call__
(q)Call self as a function.
acceleration
(q[, t])Compute the acceleration due to the potential at the given position(s).
circular_velocity
(q[, t])Estimate the circular velocity at the given position assuming the potential is spherical.
density
(q[, t])Compute the density value at the given position(s).
energy
(q[, t])Compute the potential energy at the given position(s).
gradient
(q[, t])Compute the gradient of the potential at the given position(s).
hessian
(q[, t])Compute the Hessian of the potential at the given position(s).
integrate_orbit
(*args, **kwargs)Warning
This is now deprecated. Convenient orbit integration should
plot_contours
(grid[, filled, ax, labels, …])Plot equipotentials contours.
plot_density_contours
(grid[, filled, ax, …])Plot density contours.
save
(f)Save the potential to a text file.
to_latex
()total_energy
(x, v)Compute the total energy (per unit mass) of a point in phasespace in this potential.
value
(*args, **kwargs)Attributes Documentation

mass_enclosed
(q, t)¶ Estimate the mass enclosed within the given position by assuming the potential is spherical. This is not so good!
 Parameters
 qarray_like, numeric
Position to compute the mass enclosed.

replace_units
¶ Change the unit system of this potential.
 Parameters
 units
UnitSystem
Set of nonreducable units that specify (at minimum) the
 length, mass, time, and angle units.
 copybool (optional)
If True, returns a copy, if False, changes this object.
 units

units
¶
Methods Documentation

__call__
(q)¶ Call self as a function.

acceleration
(q, t=0.0)¶ Compute the acceleration due to the potential at the given position(s).
 Parameters
 q
PhaseSpacePosition
,Quantity
, array_like Position to compute the acceleration at.
 q
 Returns
 acc
Quantity
The acceleration. Will have the same shape as the input position array,
q
.
 acc

circular_velocity
(q, t=0.0)¶ Estimate the circular velocity at the given position assuming the potential is spherical.
 Parameters
 qarray_like, numeric
Position(s) to estimate the circular velocity.
 Returns
 vcirc
Quantity
Circular velocity at the given position(s). If the input position has shape
q.shape
, the output energy will have shapeq.shape[1:]
.
 vcirc

density
(q, t=0.0)¶ Compute the density value at the given position(s).
 Parameters
 q
PhaseSpacePosition
,Quantity
, array_like The position to compute the value of the potential. If the input position object has no units (i.e. is an
ndarray
), it is assumed to be in the same unit system as the potential.
 q
 Returns
 dens
Quantity
The potential energy or value of the potential. If the input position has shape
q.shape
, the output energy will have shapeq.shape[1:]
.
 dens

energy
(q, t=0.0)¶ Compute the potential energy at the given position(s).
 Parameters
 q
PhaseSpacePosition
,Quantity
, array_like The position to compute the value of the potential. If the input position object has no units (i.e. is an
ndarray
), it is assumed to be in the same unit system as the potential.
 q
 Returns
 E
Quantity
The potential energy per unit mass or value of the potential.
 E

gradient
(q, t=0.0)¶ Compute the gradient of the potential at the given position(s).
 Parameters
 q
PhaseSpacePosition
,Quantity
, array_like The position to compute the value of the potential. If the input position object has no units (i.e. is an
ndarray
), it is assumed to be in the same unit system as the potential.
 q
 Returns
 grad
Quantity
The gradient of the potential. Will have the same shape as the input position.
 grad

hessian
(q, t=0.0)¶ Compute the Hessian of the potential at the given position(s).
 Parameters
 q
PhaseSpacePosition
,Quantity
, array_like The position to compute the value of the potential. If the input position object has no units (i.e. is an
ndarray
), it is assumed to be in the same unit system as the potential.
 q
 Returns
 hess
Quantity
The Hessian matrix of second derivatives of the potential. If the input position has shape
q.shape
, the output energy will have shape(q.shape[0],q.shape[0]) + q.shape[1:]
. That is, ann_dim
byn_dim
array (matrix) for each position.
 hess

integrate_orbit
(*args, **kwargs)¶ Warning
This is now deprecated. Convenient orbit integration should happen using the
gala.potential.Hamiltonian
class. With a static reference frame, you just need to pass your potential in to theHamiltonian
constructor.Integrate an orbit in the current potential using the integrator class provided. Uses same time specification as
Integrator.run()
– see the documentation forgala.integrate
for more information. Parameters
 w0
PhaseSpacePosition
, array_like Initial conditions.
 Integrator
Integrator
(optional) Integrator class to use.
 Integrator_kwargsdict (optional)
Any extra keyword argumets to pass to the integrator class when initializing. Only works in nonCython mode.
 cython_if_possiblebool (optional)
If there is a Cython version of the integrator implemented, and the potential object has a C instance, using Cython will be much faster.
 **time_spec
Specification of how long to integrate. See documentation for
parse_time_specification
.
 w0
 Returns
 orbit
Orbit
 orbit

plot_contours
(grid, filled=True, ax=None, labels=None, subplots_kw={}, **kwargs)¶ Plot equipotentials contours. Computes the potential energy on a grid (specified by the array
grid
).Warning
Right now the grid input must be arrays and must already be in the unit system of the potential. Quantity support is coming…
 Parameters
 gridtuple
Coordinate grids or slice value for each dimension. Should be a tuple of 1D arrays or numbers.
 filledbool (optional)
Use
contourf()
instead ofcontour()
. Default isTrue
. axmatplotlib.Axes (optional)
 labelsiterable (optional)
List of axis labels.
 subplots_kwdict
kwargs passed to matplotlib’s subplots() function if an axes object is not specified.
 kwargsdict
kwargs passed to either contourf() or plot().
 Returns
 fig
Figure
 fig

plot_density_contours
(grid, filled=True, ax=None, labels=None, subplots_kw={}, **kwargs)¶ Plot density contours. Computes the density on a grid (specified by the array
grid
).Warning
Right now the grid input must be arrays and must already be in the unit system of the potential. Quantity support is coming…
 Parameters
 gridtuple
Coordinate grids or slice value for each dimension. Should be a tuple of 1D arrays or numbers.
 filledbool (optional)
Use
contourf()
instead ofcontour()
. Default isTrue
. axmatplotlib.Axes (optional)
 labelsiterable (optional)
List of axis labels.
 subplots_kwdict
kwargs passed to matplotlib’s subplots() function if an axes object is not specified.
 kwargsdict
kwargs passed to either contourf() or plot().
 Returns
 fig
Figure
 fig

save
(f)¶ Save the potential to a text file. See
save()
for more information. Parameters
 fstr, file_like
A filename or filelike object to write the input potential object to.

to_latex
()¶

total_energy
(x, v)¶ Compute the total energy (per unit mass) of a point in phasespace in this potential. Assumes the last axis of the input position / velocity is the dimension axis, e.g., for 100 points in 3space, the arrays should have shape (100,3).
 Parameters
 xarray_like, numeric
Position.
 varray_like, numeric
Velocity.

value
(*args, **kwargs)¶