# Hamiltonian¶

class gala.potential.hamiltonian.Hamiltonian(potential, frame=None)

Bases: `gala.potential.common.CommonBase`

Represents a composition of a gravitational potential and a reference frame.

This class is used to integrate orbits and compute quantities when working in non-inertial reference frames. The input potential and frame objects must have the same dimensionality and the same unit system. If both the potential and the frame are implemented in C, numerical orbit integration will use the C-implemented integrators and will be fast (to check if your object is C-enabled, check the `.c_enabled` attribute).

Parameters
potential`PotentialBase` subclass

The gravitational potential.

frame`FrameBase` subclass (optional)

The reference frame.

Attributes Summary

Methods Summary

 Call self as a function. `energy`(w[, t]) Compute the energy (the value of the Hamiltonian) at the given phase-space position(s). `gradient`(w[, t]) Compute the gradient of the Hamiltonian at the given phase-space position(s). `hessian`(w[, t]) Compute the Hessian of the Hamiltonian at the given phase-space position(s). `integrate_orbit`(w0[, Integrator, …]) Integrate an orbit in the current potential using the integrator class provided.

Attributes Documentation

units

Methods Documentation

__call__(w)

Call self as a function.

energy(w, t=0.0)

Compute the energy (the value of the Hamiltonian) at the given phase-space position(s).

Parameters
w

The phase-space position to compute the value of the Hamiltonian. If the input object has no units (i.e. is an `ndarray`), it is assumed to be in the same unit system as the potential class.

Returns
H`Quantity`

Energy per unit mass or value of the Hamiltonian. If the input phase-space position has shape `w.shape`, the output energy will have shape `w.shape[1:]`.

Compute the gradient of the Hamiltonian at the given phase-space position(s).

Parameters
w

The phase-space position to compute the value of the Hamiltonian. If the input object has no units (i.e. is an `ndarray`), it is assumed to be in the same unit system as the potential class.

Returns
TODO: `this` can’t `return` `a` `quantity`, `because` `units` `are` `different` dH/dq vs. dH/dp
grad`Quantity`

The gradient of the potential. Will have the same shape as the input phase-space position, `w`.

hessian(w, t=0.0)

Compute the Hessian of the Hamiltonian at the given phase-space position(s).

Parameters
w

The phase-space position to compute the value of the Hamiltonian. If the input object has no units (i.e. is an `ndarray`), it is assumed to be in the same unit system as the potential class.

Returns
# TODO: `see` `TODO` `about` `units` `about`
hess`Quantity`

The Hessian matrix of second derivatives of the potential. If the input position has shape `w.shape`, the output energy will have shape `(w.shape[0],w.shape[0]) + w.shape[1:]`. That is, an `n_dim` by `n_dim` array (matrix) for each position, where the dimensionality of phase-space is `n_dim`.

integrate_orbit(w0, Integrator=None, 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

Initial conditions.

Integrator`Integrator` (optional)

Integrator class to use. By default, uses `LeapfrogIntegrator` if the frame is static and `DOPRI853Integrator` else.

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. Most commonly, this is a timestep `dt` and number of steps `n_steps`, or a timestep `dt`, initial time `t1`, and final time `t2`. You may also pass in a time array with `t`. See documentation for `parse_time_specification` for more information.

Returns
orbit`Orbit`