PotentialBase

class gala.potential.PotentialBase(parameters, units=None)

Bases: object

A baseclass for defining pure-Python gravitational potentials.

Subclasses must define (at minimum) a method that evaluates the value (energy) of the potential at a given position q and time t: _value(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().

Methods Summary

__call__(q)
acceleration(q[, t])	Compute the acceleration due to the potential at the given position(s).
density(q[, t])	Compute the density value 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(w0[, Integrator, ...])	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.
plot_contours(grid[, ax, labels, subplots_kw])	Plot equipotentials contours.
plot_densty_contours(grid[, ax, labels, ...])	Plot density contours.
save(f)	Save the potential to a text file.
total_energy(x, v)	Compute the total energy (per unit mass) of a point in phase-space in this potential.
value(q[, t])	Compute the value of the potential at the given position(s).

Methods Documentation

__call__(q)

acceleration(q, t=0.0)

Compute the acceleration due to the potential at the given position(s).

Parameters:

q : array_like, numeric

Position to compute the acceleration at.

Returns:

acc : ndarray

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

density(q, t=0.0)

Compute the density value at the given position(s).

Parameters:

q : 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.

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

gradient(q, t=0.0)

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

Parameters:

q : 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.

Returns:

grad : Quantity

The gradient of the potential. Will have the same shape as the input position array, q.

hessian(q, t=0.0)

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

Parameters:

q : 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.

Returns:

hess : Quantity

TODO:

integrate_orbit(w0, Integrator=<class 'gala.integrate.pyintegrators.leapfrog.LeapfrogIntegrator'>, Integrator_kwargs={}, cython_if_possible=True, **time_spec)

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.

Returns:

orbit : CartesianOrbit

mass_enclosed(q, t=0.0)

Estimate the mass enclosed within the given position by assuming the potential is spherical.

Parameters:

x : array_like, numeric

Position to estimate the enclossed mass.

Returns:

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

plot_contours(grid, ax=None, labels=None, subplots_kw={}, **kwargs)

Plot equipotentials contours. Computes the potential value 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.

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().

Returns:

fig : Figure

plot_densty_contours(grid, 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.

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().

Returns:

fig : Figure

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.

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.

value(q, t=0.0)

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

Parameters:

q : 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.

Returns:

E : Quantity

The potential energy per unit mass or value of the potential. If the input position has shape q.shape, the output energy will have shape q.shape[1:].