# CompositePotential¶

class gala.potential.potential.CompositePotential(*args, **kwargs)[source]

A potential composed of several distinct components. For example, two point masses or a galactic disk and halo, each with their own potential model.

A CompositePotential is created like a Python dictionary, e.g.:

>>> p1 = SomePotential(func1)
>>> p2 = SomePotential(func2)
>>> cp = CompositePotential(component1=p1, component2=p2)


This object actually acts like an OrderedDict, so if you want to preserve the order of the potential components, use:

>>> cp = CompositePotential()
>>> cp['component1'] = p1
>>> cp['component2'] = p2


You can also use any of the built-in Potential classes as components:

>>> from gala.potential import HernquistPotential
>>> cp = CompositePotential()
>>> cp['spheroid'] = HernquistPotential(m=1E11, c=10., units=(u.kpc,u.Myr,u.Msun,u.radian))


Attributes Summary

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. clear() copy() density(q[, t]) Compute the density value at the given position(s). energy(q[, t]) Compute the potential energy at the given position(s). fromkeys(S[, v]) If not specified, the value defaults to None. get(k[,d]) 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 items() keys() mass_enclosed(q[, t]) Estimate the mass enclosed within the given position by assuming the potential is spherical. move_to_end Move an existing element to the end (or beginning if last==False). plot_contours(grid[, filled, ax, labels, …]) Plot equipotentials contours. plot_density_contours(grid[, filled, ax, …]) Plot density contours. pop(k[,d]) value. popitem($self, /[, last]) Remove and return a (key, value) pair from the dictionary. save(f) Save the potential to a text file. setdefault(k[,d]) total_energy(x, v) Compute the total energy (per unit mass) of a point in phase-space in this potential. update([E, ]**F) If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k] value(*args, **kwargs) values() Attributes Documentation parameters 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. acc : Quantity The acceleration. Will have the same shape as the input position array, q. circular_velocity(q, t=0.0) Estimate the circular velocity at the given position assuming the potential is spherical. Parameters: q : array_like, numeric Position(s) to estimate the circular velocity. vcirc : Quantity Circular velocity at the given position(s). If the input position has shape q.shape, the output energy will have shape q.shape[1:]. clear() → None. Remove all items from od. copy() → a shallow copy of od 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. dens : Quantity The potential energy or value of the potential. If the input position has shape q.shape, the output energy will have shape q.shape[1:]. 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. E : Quantity The potential energy per unit mass or value of the potential. fromkeys(S[, v]) → New ordered dictionary with keys from S. If not specified, the value defaults to None. get(k[, d]) → D[k] if k in D, else d. d defaults to None. 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. grad : Quantity The gradient of the potential. Will have the same shape as the input position. 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. 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, an n_dim by n_dim array (matrix) for each position. 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 the Hamiltonian constructor. Integrate an orbit in the current potential using the integrator class provided. Uses same time specification as Integrator.run() – see the documentation for gala.integrate for more information. Parameters: w0 : PhaseSpacePosition, array_like Initial conditions. Integrator : Integrator (optional) Integrator class to use. Integrator_kwargs : dict (optional) Any extra keyword argumets to pass to the integrator class when initializing. Only works in non-Cython mode. cython_if_possible : bool (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. orbit : Orbit items() → a set-like object providing a view on D's items keys() → a set-like object providing a view on D's keys mass_enclosed(q, t=0.0) Estimate the mass enclosed within the given position by assuming the potential is spherical. Parameters: q : PhaseSpacePosition, Quantity, array_like Position(s) to estimate the enclossed mass. menc : Quantity Mass enclosed at the given position(s). If the input position has shape q.shape, the output energy will have shape q.shape[1:]. move_to_end() Move an existing element to the end (or beginning if last==False). Raises KeyError if the element does not exist. When last=True, acts like a fast version of self[key]=self.pop(key). 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: grid : tuple Coordinate grids or slice value for each dimension. Should be a tuple of 1D arrays or numbers. filled : bool (optional) Use contourf() instead of contour(). Default is True. ax : matplotlib.Axes (optional) labels : iterable (optional) List of axis labels. subplots_kw : dict kwargs passed to matplotlib’s subplots() function if an axes object is not specified. kwargs : dict kwargs passed to either contourf() or plot(). fig : Figure 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: grid : tuple Coordinate grids or slice value for each dimension. Should be a tuple of 1D arrays or numbers. filled : bool (optional) Use contourf() instead of contour(). Default is True. ax : matplotlib.Axes (optional) labels : iterable (optional) List of axis labels. subplots_kw : dict kwargs passed to matplotlib’s subplots() function if an axes object is not specified. kwargs : dict kwargs passed to either contourf() or plot(). fig : Figure pop(k[, d]) → v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised. popitem($self, /, last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

save(f)

Save the potential to a text file. See save() for more information.

Parameters: f : str, file_like A filename or file-like object to write the input potential object to.
setdefault(k[, d]) → od.get(k,d), also set od[k]=d if k not in od
total_energy(x, v)

Compute the total energy (per unit mass) of a point in phase-space in this potential. Assumes the last axis of the input position / velocity is the dimension axis, e.g., for 100 points in 3-space, the arrays should have shape (100,3).

Parameters: x : array_like, numeric Position. v : array_like, numeric Velocity.
update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

value(*args, **kwargs)
values() → an object providing a view on D's values