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

 ndim units

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. 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(f) Save the potential to a text file. to_galpy_potential([ro, vo]) Convert a Gala potential to a Galpy potential instance to_latex() Return a string LaTeX representation of this potential to_sympy() 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
accQuantity

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
vcircQuantity

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
densQuantity

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
EQuantity

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

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
hessQuantity

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

IntegratorIntegrator (optional)

Integrator class to use.

Integrator_kwargsdict (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
orbitOrbit
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
mencQuantity

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
gridtuple

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.

axmatplotlib.Axes (optional)
labelsiterable (optional)

List of axis labels.

subplots_kwdict

kwargs passed to matplotlib’s subplots() function if an axes object is not specified.

kwargsdict

kwargs passed to either contourf() or plot().

Returns
figFigure
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
gridtuple

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.

axmatplotlib.Axes (optional)
labelsiterable (optional)

List of axis labels.

subplots_kwdict

kwargs passed to matplotlib’s subplots() function if an axes object is not specified.

kwargsdict

kwargs passed to either contourf() or plot().

Returns
figFigure
replace_units(units, copy=True)[source]

Change the unit system of this potential.

Parameters
unitsUnitSystem

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
fstr, 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_strstr

The latex expression as a Python string.

classmethod to_sympy()[source]

Return a representation of this potential class as a sympy expression

Returns
exprsympy expression
varsdict

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]