Hamiltonian

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

Bases: 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

units

Methods Summary

__call__(w)	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:

# TODO: see TODO about units about

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, store_all=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.

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