# 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
potentialPotentialBase subclass

The gravitational potential.

frameFrameBase 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
wPhaseSpacePosition, array_like

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
HQuantity

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

gradient(w, t=0.0)

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

Parameters
wPhaseSpacePosition, array_like

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
gradQuantity

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
wPhaseSpacePosition, array_like

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
hessQuantity

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
w0PhaseSpacePosition, array_like

Initial conditions.

IntegratorIntegrator (optional)

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

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. 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
orbitOrbit