# PotentialBase¶

class gala.potential.potential.PotentialBase(*, units=None, origin=None, R=None, **kwargs)[source]

Bases: `gala.potential.common.CommonBase`

A baseclass for defining pure-Python gravitational potentials.

Subclasses must define (at minimum) a method that evaluates the potential energy at a given position `q` and time `t`: `_energy(q, t)`. For integration, the subclasses must also define a method to evaluate the gradient, `_gradient(q, t)`. Optionally, they may also define methods to compute the density and hessian: `_density()`, `_hessian()`.

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[, copy]) Change the unit system of this potential. Save the potential to a text file. `to_galpy_potential`([ro, vo]) Convert a Gala potential to a Galpy potential instance 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. `value`(*args, **kwargs)

Attributes Documentation

ndim = 3
units

Methods Documentation

__call__(q)[source]

Call self as a function.

acceleration(q, t=0.0)[source]

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)[source]

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)[source]

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)[source]

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.

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)[source]

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)[source]

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=0.0)[source]

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

plot_contours(grid, filled=True, ax=None, labels=None, subplots_kw={}, **kwargs)[source]

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)[source]

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.

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, copy=True)[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.

copybool (optional)

If True, returns a copy, if False, changes this object.

save(f)[source]

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.

to_galpy_potential(ro=None, vo=None)[source]

Convert a Gala potential to a Galpy potential instance

Parameters
roquantity-like (optional)
voquantity-like (optional)
classmethod to_latex()[source]

Return a string LaTeX representation of this potential

Returns
latex_str`str`

The latex expression as a Python string.

classmethod to_sympy()[source]

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)[source]

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)[source]