# CylSplinePotential#

class gala.potential.potential.CylSplinePotential(grid_R, grid_z, grid_Phi, *, units=None, origin=None, R=None, **kwargs)[source]#

Bases: `CPotentialBase`

A flexible potential model that uses spline interpolation over a 2D grid in cylindrical R-z coordinates.

Parameters:
grid_R`Quantity`, `numeric` [`length`]

A 1D grid of cylindrical radius R values. This should start at 0.

grid_z`Quantity`, `numeric` [`length`]

A 1D grid of cylindrical z values. This should start at 0.

grid_Phi`Quantity`, `numeric` [`specific` `energy`]

A 2D grid of potential values, evaluated at all R,z locations.

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). `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). `from_file`(filename, **kwargs) Load a potential instance from an Agama export file. `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. `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. `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. `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. `value`(*args, **kwargs)

Attributes Documentation

grid_Phi = <PotentialParameter: grid_Phi [specific energy]>#
grid_R = <PotentialParameter: grid_R [length]>#
grid_z = <PotentialParameter: grid_z [length]>#
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`.

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

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.

classmethod from_file(filename, **kwargs)[source]#

Load a potential instance from an Agama export file.

Parameters:
filenamepath-like

The path to the Agama expoirt file, either as a string or `pathlib.Path` object.

**kwargs

Other keyword arguments are passed to the initializer.

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`
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, 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`
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.
replicate(**kwargs)#

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.

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.

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.

value(*args, **kwargs)#