# CompositePotential#

class gala.potential.potential.CompositePotential(**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 a dictionary, 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.,
```

Attributes Summary

Methods Summary

 Call self as a function. `acceleration`(q[, t]) Compute the acceleration due to the potential at the given position(s). `as_interop`(package, **kwargs) Interoperability with other Galactic dynamics packages `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). `fromkeys`(/, iterable[, value]) Create a new ordered dictionary with keys from iterable and values set to value. `get`(key[, default]) Return the value for key if key is in the dictionary, else default. `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) Integrate an orbit in the current potential using the integrator class provided. `mass_enclosed`(q[, t]) Estimate the mass enclosed within the given position by assuming the potential is spherical. `move_to_end`(/, key[, last]) Move an existing element to the end (or beginning if last is false). `plot_contours`(grid[, t, filled, ax, labels, ...]) Plot equipotentials contours. `plot_density_contours`(grid[, t, filled, ax, ...]) Plot density contours. `plot_rotation_curve`(R_grid[, t, ax, labels]) Plot the rotation curve or circular velocity curve for this potential on the input grid of cylindrical radii. `pop`(/, key[, default]) If the key is not found, return the default if given; otherwise, raise a KeyError. `popitem`(/[, last]) Remove and return a (key, value) pair from the dictionary. `replace_units`(units) Change the unit system of this potential. `replicate`(**kwargs) Return a copy of the potential instance with some parameter values changed. Save the potential to a text file. `setdefault`(/, key[, default]) Insert key with a value of default if key is not in the dictionary. `to_galpy_potential`([ro, vo]) Deprecated since version v1.8. Return a string LaTeX representation of this potential Return a representation of this potential class as a sympy expression `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)

Attributes Documentation

ndim = 3#
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

Position to compute the acceleration at.

Returns:
acc`Quantity`

The acceleration. Will have the same shape as the input position array, `q`.

as_interop(package, **kwargs)#

Interoperability with other Galactic dynamics packages

Parameters:
package`str`

The package to export the potential to. Currently supported packages are `"galpy"` and `"agama"`.

kwargs

Any additional keyword arguments are passed to the interop function.

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

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.

Returns:
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

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.

Returns:
E`Quantity`

The potential energy per unit mass or value of the potential.

fromkeys(/, iterable, value=None)#

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)#

Return the value for key if key is in the dictionary, else default.

Compute the gradient of the potential at the given position(s).

Parameters:
q

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.

Returns:
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

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.

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, an `n_dim` by `n_dim` array (matrix) for each position.

integrate_orbit(*args, **kwargs)#

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

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

store_allbool (optional)

Controls whether to store the phase-space position at all intermediate timesteps. Set to False to store only the final values (i.e. the phase-space position(s) at the final timestep). Default is True.

**time_spec

Specification of how long to integrate. See documentation for `parse_time_specification`.

Returns:
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

Position(s) to estimate the enclossed mass.

Returns:
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(/, key, last=True)#

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

plot_contours(grid, t=0.0, 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.

tquantity-like (optional)

The time to evaluate at.

filledbool (optional)

Use `contourf()` instead of `contour()`. Default is `True`.

ax`matplotlib.Axes` (optional)
labelsiterable (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().

Returns:
fig`Figure`
plot_density_contours(grid, t=0.0, filled=True, ax=None, labels=None, subplots_kw={}, **kwargs)#

Plot density contours. Computes the density on a grid (specified by the array `grid`).

Warning

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

tquantity-like (optional)

The time to evaluate at.

filledbool (optional)

Use `contourf()` instead of `contour()`. Default is `True`.

ax`matplotlib.Axes` (optional)
labelsiterable (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().

Returns:
fig`Figure`
plot_rotation_curve(R_grid, t=0.0, ax=None, labels=None, **plot_kwargs)#

Plot the rotation curve or circular velocity curve for this potential on the input grid of cylindrical radii.

Parameters:
R_gridarray_like

A grid of radius values to compute the rotation curve at. This should be a one-dimensional grid.

tquantity-like (optional)

The time to evaluate at.

ax`matplotlib.Axes` (optional)
labelsiterable (optional)

List of axis labels. Set to False to disable adding labels.

plot_kwargs`dict`

kwargs passed to plot().

Returns:
fig`Figure`
ax`Axes`
pop(/, key, default=<unrepresentable>)#

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem(/, 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.

replace_units(units)[source]#

Change the unit system of this potential.

Parameters:
units`UnitSystem`

Set of non-reducable units that specify (at minimum) the length, mass, time, and angle units.

replicate(**kwargs)[source]#

Return a copy of the potential instance with some parameter values changed. This always produces copies of any parameter arrays.

Parameters:
**kwargs

All other keyword arguments are used to overwrite parameter values when making the copy. The keywords passed in should be the same as the potential component names, so you can pass in dictionaries to set parameters for different subcomponents of this composite potential.

Returns:
replicant`PotentialBase` subclass instance

The replicated potential.

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(/, key, default=None)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

to_galpy_potential(ro=None, vo=None)#

Deprecated since version v1.8: This has been replaced by a more general interoperability framework.

Convert a Gala potential to a Galpy potential instance

Parameters:
roquantity-like (optional)
voquantity-like (optional)
classmethod to_latex()#

Return a string LaTeX representation of this potential

Returns:
latex_str`str`

The latex expression as a Python string.

classmethod to_sympy()#

Return a representation of this potential class as a sympy expression

Returns:
expr`sympy` `expression`
vars`dict`

A dictionary of sympy symbols used in the expression.

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:
xarray_like, `numeric`

Position.

varray_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#