# KeplerPotential¶

class `gala.potential.potential.``KeplerPotential`(m, *, units=None, origin=None, R=None, **kwargs)

The Kepler potential for a point mass.

Parameters
m`Quantity`, `numeric` [`mass`]

Point mass value.

units`UnitSystem` (optional)

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

origin`Quantity` (optional)

The origin of the potential, the default being 0.

R`Rotation`, array_like (optional)

A Scipy `Rotation` object or an array representing a rotation matrix that specifies a rotation of the potential. This is applied after the origin shift. Default is the identity matrix.

Attributes Summary

Methods Summary

 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 `mass_enclosed`(q, t) Estimate the mass enclosed within the given position by assuming the potential is spherical. `plot_contours`(grid[, filled, ax, labels, …]) Plot equipotentials contours. `plot_density_contours`(grid[, filled, ax, …]) Plot density contours. `replace_units`(units) Change the unit system of this potential. Save the potential to a text file. Return a string LaTeX representation of this potential `to_sympy`(v, p) 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. `value`(*args, **kwargs)

Attributes Documentation

`m` = <gala.potential.common.PotentialParameter object>
`ndim` = 3
`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`.

`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:]`.

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

`gradient`(q, t=0.0)

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,q.shape) + 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

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.

**time_spec

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

Returns
orbit`Orbit`
`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.

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

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

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`
`replace_units`(units)

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

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`(v, p)

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.

`value`(*args, **kwargs)