Orblib

Classes related to orbit libraries.

API

Classes:

LegacyOrbitLibrary([config, mod_dir, parset])	Orbit libraries calculated from legacy Fortan programs
OrbitLibrary([config])	An abstract class for orbit libraries.

class orblib.LegacyOrbitLibrary(config=None, mod_dir=None, parset=None)

Orbit libraries calculated from legacy Fortan programs

Methods:

classify_orbits([make_diagnostic_plots])	Perform orbit classification.
combine_orblibs(orblib1, orblib2)	Combine two LOSVD histograms into one.
create_fortran_input_orblib(path)	write input files for Fortran orbit library programs
duplicate_flip_and_interlace_intmoms(intmom)	equiv of duplicate_flip_and_interlace_orblib for intrinsic moments
duplicate_flip_and_interlace_orblib(orblib)	flip the tube orbits
find_threshold_angular_momentum([...])	Find threshold angular momentum dL for use in orbit classification
get_model_intrinsic_moment_constructor()	Get a function to constrcut the model's intrinsic moments in 3D grid
get_orbit_ics()	Execute the bash script to calculate orbit ICs
get_orbit_library()	Execute the bash script to calculate orbit libraries
get_orbit_library_par()	Execute the bash script to calculate orbit libraries in parallel
get_orblib()	main method to calculate orbit libraries
read_losvd_histograms()	Read the orbit library
read_orbit_base(fileroot[, ...])	Read orbit library from file datfil/{fileroot}.dat.bz2'
read_orbit_intrinsic_moments([cache])	Read the intrinsic moments of the orbit library.
read_orbit_property_file()	Read the *orbclass.out files
read_orbit_property_file_base(file, ncol, nrow)	Base method to read in *orbclass.out files
write_executable_for_ics()	Write the bash script to calculate orbit ICs
write_executable_for_integrate_orbits()	Write the bash script to calculate orbit libraries
write_executable_for_integrate_orbits_par()	Write the bash script to calculate orbit libraries

classify_orbits(make_diagnostic_plots=False)

Perform orbit classification.

Orbits are classified in 3D angular momentum space (Lx, Ly, Lz) according to a threshold angular momdentum dL. Ideally, we would classify as follows:

• |Lx|,|Ly|,|Lz|<dL –> box

• |Lx|>dL, |Ly|,|Lz|<dL –> x-axis tube

• |Ly|>dL, |Lx|,|Lz|<dL –> y-axis tube (theoretically unstable)

• |Lz|>dL, |Lx|,|Ly|<dL –> z-axis tube

This “exact” classification leaves many orbits unclassified. Instead we classify tube orbits using the less strict criteria:

• not a box, |Lx|>|Ly|, |Lx|>|Lz| –> x-axis tube “-ish”

• not a box, |Ly|>|Lz|, |Ly|>|Lz| –> y-axis tube “-ish”

• not a box, |Lz|>|Lx|, |Lz|>|Ly| –> z-axis tube “-ish”

The method logs the fraction of all orbits in each classification, and the fraction of each type which are “exact” according to the stricter criteria. The results saved in self.orb_classification are for the less strict criteria.

Parameters:

make_diagnostic_plotsbool, optional

whether to make diagnostic plot in find_threshold_angular_momentum, by default False.

Returns:

None

sets result to self.orb_classification, a dictionary containing 5 keys bool_{box,xtish,ytish,ztish,other} where e.g. bool_box is a boolean array with shape [N_bundles, N_orbits] set to True at the location of box orbits. bool_other should be False everywhere.

combine_orblibs(orblib1, orblib2)

Combine two LOSVD histograms into one.

Parameters:

orblib1dyn.kinematics.Histogram

orblib2dyn.kinematics.Histogram

Returns:

dyn.kinematics.Histogram

the combined orbit libraries

create_fortran_input_orblib(path)

write input files for Fortran orbit library programs

Parameters:

pathstring

path of the model’s infil directory

Returns:

Cretaes the following files in the infil directory:

• parameters_pot.in

• parameters_lum.in

• orblib.in

• orblibbox.in

• triaxmass.in

• triaxmassbin.in

duplicate_flip_and_interlace_intmoms(intmom)

equiv of duplicate_flip_and_interlace_orblib for intrinsic moments

duplicate_flip_and_interlace_orblib(orblib)

flip the tube orbits

Take an orbit library, create a duplicate library with the velocity signs flipped, then interlace the two i.e. so that resulting library alternates between flipped/unflipped. This creates an orbit library consistent with the Fortran output, enforcing the ordering created by the for loops in lines 157-178 of triaxnnls_CRcut.f90

Parameters:

orblibdyn.kinematics.Histogram

Returns:

dyn.kinematics.Histogram

the duplicated, flipped and interlaced orblib

find_threshold_angular_momentum(make_diagnostic_plots=False)

Find threshold angular momentum dL for use in orbit classification

Currently uses a hard coded value of 0.090909 * 10^18 km km/s. TODO: generalise this to automatically select dL based on the orblib.

Parameters:

make_diagnostic_plotsbool, optional

If True, plot diagnostic angular momentum histograms. The default is False.

Returns:

dlfloat

The threshold angular momentum dL.

get_model_intrinsic_moment_constructor()

Get a function to constrcut the model’s intrinsic moments in 3D grid

Returns a function and a list. The function takes weights and returns intrinsic model moments in a 3D grid. The list contains the bin edges of the 3D grid. Example usage:

` moment_constructor, bin_edges = orblib.get_model_intrinsic_moment_constructor() moments = moment_constructor(weights) `

Returns:

(callable, list)

the callable = function which takes weights and returns 3D moments. The list contains grid bin edges over spherical (r, theta, phi). Moments returned by the callable are stored in a grid of size (nr, nth, nph, 13). Final dimension indexes over: density,x,y,z,vx, vy,vz,vx^2,vy^2,vz^2,vx*vy,vy*vz,vz*vx. Density is normalised to 1, spatial moments in arcseconds, velocities in km/s.

get_orbit_ics()

Execute the bash script to calculate orbit ICs

get_orbit_library()

Execute the bash script to calculate orbit libraries

get_orbit_library_par()

Execute the bash script to calculate orbit libraries in parallel

get_orblib()

main method to calculate orbit libraries

Writes and executes bash scripts to (i) calculate orbit initial conditions, (ii) calculate orbit libraries, (iii) calculate aperture and 3D grid masses for the MGE. If orbit libraries for this model already exist, then this method does nothing.

Returns:

Creates the following output files in output/models/*/datfil/:

• begin.dat (ics for tube orbits)

• beginbox.dat (ics for box orbits)

• orblib.dat.bz2 (zipped tube orbit library)

• orblib.dat_orbclass.out (orbit classification for tube orbs)

• orblibbox.dat.bz2 (zipped box orbit library)

• orblibbox.dat_orbclass.out (orbit classification for box orbs)

• mass_aper.dat (MGE masses in apertures)

• mass_qgrid.dat (MGE masses in 3D grid)

• mass_radmass.dat (MGE masses in radial bins)

• +8 log and status files

read_losvd_histograms()

Read the orbit library

Read box orbits and tube orbits, mirrors the latter, and combines. Rescales the velocity axis according to the ml value. Sets LOSVDs and 3D grid/aperture masses of the combined orbit library.

Returns:

Sets the attributes:

• self.losvd_histograms: a list, whose i’th entry is a dyn.kinematics.Histogram object holding the orbit lib LOSVDs binned for the i’th kinematic set

• self.intrinsic_masses: 3D grid/intrinsic masses of orbit lib

• self.projected_masses: aperture/proj. masses of orbit lib

• self.n_orbs: number of orbits in the orbit library

read_orbit_base(fileroot, return_instrisic_moments=False)

Read orbit library from file datfil/{fileroot}.dat.bz2’

Parameters:

filerootstring

this will probably be either ‘orblib’ or ‘orblibbox’

return_instrisic_moments: boolean

whether to return_instrisic_moments of the orblib

Returns:

if return_instrisic_moments is False, this returns a tuple of type

(Histogram, array) where the orbit library LOSVDs are stored in the

Histogram object, and the 3D density of the orbits are stored in the

array object.

if return_instrisic_moments is True, returns a tuple

(array, list) where the array stores the intrinsic momenmts of the

orblib and the list contains the bin edges of the 3D grid.

read_orbit_intrinsic_moments(cache=True)

Read the intrinsic moments of the orbit library.

Moments stored in 3D grid over spherical co-ords (r,theta,phi). This function reads the data from files, formats them correctly, and coverts to physical units.

Parameters:

cachebool, optional

If True, the intrinsic moments and the bin edges are cached between calls to this method. The cache files are stored in the orbit library’s datfil/ directory. The default is True.

Returns:

(array, list)

array shape = (n_orb, nr, nth, nph, 16). Final dimension indexes over: density,x,y,z,vx,vy,vz,vx^2,vy^2,vz^2,vx*vy,vy*vz,vz*vx, and the final three indices (13,14,15) are some type of orbit classification (not understood - recommend not to use!). The list contains grid bin edges over spherical (r, theta, phi).

read_orbit_property_file()

Read the *orbclass.out files

These files contain time-averaged properties of individual orbits within a bundle. Results are stored in self.orb_properties, an astropy table with columns [r, Vrms, L, Lx, Ly, Lz, lmd, lmd_x, lmd_y, lmd_z] i.e. the time-averaged value of (i) radius r, (ii) V_rms = (vx^2 + vy^2 + vz^2 + 2(vxvy + vxvz + vyvz)), (iii) total angular momentum L, (iv) Lx, (v) Ly, (vi) Lz, and circularities (vii) lmd = L/V_rms, (ix) lmd_x=Lx/V_rms, (x) lmd_y, (xi) lmd_z. Each column of the table is an array of shape [N_bundle, N_orbit].

read_orbit_property_file_base(file, ncol, nrow)

Base method to read in *orbclass.out files

…which hold the information of all the orbits stored in the orbit library. The number of orbits is nE * nI2 * nI3 * dithering^3, ncol = dithering^3 and nrow = nE * nI2 * nI3. For each orbit, the time averaged values are stored: lx, ly ,lz, r = sum(sqrt( average(r^2) )), Vrms^2 = average(vx^2 + vy^2 + vz^2 + 2vx*vy + 2vxvz + 2vxvy). The files were originally stored by the fortran code orblib_f.f90, integrator_find_orbtype.

* Do not try to replace this with numpy (e.g. np.genfromtext ) since the output files are sometimes written in non-standard arrays (in a seemingly system dependent way). *

write_executable_for_ics()

Write the bash script to calculate orbit ICs

write_executable_for_integrate_orbits()

Write the bash script to calculate orbit libraries

write_executable_for_integrate_orbits_par()

Write the bash script to calculate orbit libraries

class orblib.OrbitLibrary(config=None)

An abstract class for orbit libraries.

Parameters:

systema dyn.physical_system.System object

settingsa dyn.config_reader.settings object

Inheritance Diagram