:py:mod:`kinms.KinMS2` ====================== .. py:module:: kinms.KinMS2 .. autoapi-nested-parse:: Legacy version 2 version of Kinematic modelling code KinMS. Copyright (C) 2019, Timothy A. Davis, Nikki Zabel, James M. Dawson E-mail: DavisT -at- cardiff.ac.uk, zabelnj -at- cardiff.ac.uk, dawsonj5 -at- cardiff.ac.uk Updated versions of the software are available through github: https://github.com/TimothyADavis/KinMSpy If you have found this software useful for your research, I would appreciate an acknowledgment to the use of the "KINematic Molecular Simulation (KinMS) routines of Davis et al., (2013)". [MNRAS, Volume 429, Issue 1, p.534-555] This software is provided as is without any warranty whatsoever. For details of permissions granted please see LICENCE.md Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: kinms.KinMS2.KinMS .. py:exception:: KinMSError Bases: :py:obj:`Exception` Generates errors under the flag 'KinMSError'. :class KinMSError: Instantiates the Exception error 'KinMSError', for warning the user of faults and exceptions. .. py:class:: KinMS(xs, ys, vs, cellSize, dv, beamSize, inc, posAng, gasSigma=0, diskThick=0, flux_clouds=None, sbProf=[], sbRad=[], velRad=[], velProf=[], inClouds=[], vLOS_clouds=[], massDist=[], radial_motion_func=None, ra=None, dec=None, nSamps=None, seed=None, intFlux=None, vSys=None, phaseCent=[0, 0], vOffset=0, vPosAng=[], vPhaseCent=[0, 0], restFreq=None, fileName='', fixSeed=False, cleanOut=False, returnClouds=False, huge_beam=False, verbose=False, skySampler=False, bunit='Jy/beam') :class KinMS: Main workhorse of KinMSpy, used to generate spectral cubes. .. py:method:: print_variables() If "verbose", prints a summary of parameters for the user's convenience. :return: (string) formatted display of all parameters used in KinMS() initialisation .. py:method:: makebeam(xpixels, ypixels, beamSize, cellSize=1, cent=None) Creates a psf with which one can convolve their cube based on the beam provided. :param xpixels: (float or int) Number of pixels in the x-axis :param ypixels: (float or int) Number of pixels in the y-axis :param beamSize: (float or int, or list or array of float or int) Scalar or three element list for size of convolving beam (in arcseconds). If a scalar then beam is assumed to be circular. If a list/array of length two. these are the sizes of the major and minor axes, and the position angle is assumed to be 0. If a list/array of length 3, the first 2 elements are the major and minor beam sizes, and the last the position angle (i.e. [bmaj, bmin, bpa]). :param cellSize: (float or int) Pixel size required (arcsec/pixel) :param cent: (array or list of float or int) Optional, default value is [xpixels / 2, ypixels / 2]. Central location of the beam in units of pixels. :return psf or trimmed_psf: (float array) psf required for convlution in self.model_cube(). trimmed_psf returned if self.huge_beam=False, otherwise default return is the untrimmed psf. .. py:method:: kinms_sampleFromArbDist_oneSided(sbRad, sbProf, nSamps, diskThick, fixSeed=None) Samples cloudlets from radial profiles provided given that inClouds is not provided in the __init__. :param sbRad: (numpy array) Radius vector for surface brightness profile (units of arcseconds). :param sbProf: (numpy array) Surface brightness profile (arbitrarily scaled) as a function of 'sbrad'. :param nSamps: (int) Number of cloudlets to use to create the model. Large numbers will reduce numerical noise (especially in large cubes), at the cost of increasing runtime. :param diskThick: (numpy array) The disc scaleheight in arcseconds. If a single value then this is used at all radii. If an array/list then it should have the same length as 'sbrad', and will be the disc thickness as a function of that. :param fixSeed: (bool) Whether to use a fixed (or random) seed (list of four integers). :return inClouds: (numpy array) 3 dimensional array of cloudlet positions within the cube initialised by KinMS(). .. py:method:: kinms_create_velField_oneSided(velRad, posAng_rad=None, inc_rad=None) Creates an array of line-of-sight velocities, accounting for velocity dispersion and projection. :param velRad: (numpy array) Radius vector for velocity profile (units of arcseconds). :param posAng_rad: (float or int, or array of float or int) Optional, default value is None. Position angle (PA) of the disc (a PA of zero means that the redshifted part of the cube is aligned with the positive y-axis). If single valued then the disc major axis is straight. If an array is passed then it should describe how the position angle changes as a function of `velrad` (so this can be used to create position angle warps). :param inc_rad: (float or int, or array of float or int) Optional, default value is None. Inclination angle of the gas disc on the sky (degrees). Can input a constant or a vector, giving the inclination as a function of the radius vector 'velrad' (in order to model warps etc). :return los_vel: (numpy array) Line-of-sight velocities for projected particles positioned by velRad. .. py:method:: save_fits(cube, cent) Outputs a .fits file containing the datacube and relevant header information. :param cube: (numpy array) 3 dimensional spectral cube required for saving to .fits file :param cent: (numpy array of intigers) Location of the central x and y positions (in units of pixels), and index of the central velocity channel. :return: None .. py:method:: gasGravity_velocity(x_pos, y_pos, z_pos, massDist, velRad) Calculates an array of line-of-sight velocity alterations, accounting for the effects of the mass of gas in the disk (in this case assuming spherical symmetry). :param x_pos: (numpy array) X position of each cloudlet. Units of arcseconds. :param y_pos: (numpy array) Y position of each cloudlet. Units of arcseconds. :param z_pos: (numpy array) Z position of each cloudlet. Units of arcseconds. :param massDist: (numpy array) Array of ([gasmass,distance]) - total gas mass in solar masses, total distance in Mpc. :param velRad: (numpy array) Radius vector for cloudlets (in units of pixels). :return add_to_circ_vel: (numpy array) Additions to the circular velocity due to the internal mass of the gas, in units of km/s. .. py:method:: generate_cloudlets() A helper function for generating cloudlets by running kinms_sampleFromArbDist_oneSided. Raises a KinMSError if generate_cloudlets is called but sbRad and sbProf are not set. :return: None .. py:method:: set_cloud_positions() Calculate and return the positions and velocities of the cloudlets in inClouds, and the radial distance in the x and y plane. :return: None .. py:method:: create_warp(array, r_flat) If the array provided has a length > 1, create a warp. If it's a single value, create a flat profile. :param array: (ndarray) array containing the radial profile :param r_flat: (ndarray) Radius of each cloudlet from the kinematic centre in the plane of the disc (units of pixels) :return: ndarray with the radial profile of the disc .. py:method:: inclination_projection(ang, x1, y1, z1) Apply the projection as a result of inclination to the cloudlets. :param ang: (float) inclination angle (in degrees) :param x1: (ndarray) x-positions of the cloudlets :param y1: (ndarray) y-positions of the cloudlets :param z1: (ndarray) z-positions of the cloudlets :return: x-, y-, and z-positions of the projected cloudlets .. py:method:: position_angle_rotation(ang, x2, y2, z2) Apply the projection as a result of the position angle to the cloudlets. :param ang: (float) position angle (in degrees) :param x2: (ndarray) x-positions of the cloudlets :param y2: (ndarray) y-positions of the cloudlets :param z2: (ndarray) z-positions of the cloudlets :return: x-, y-, and z-positions of the projected cloudlets .. py:method:: set_cloud_velocities() Find the los velocity and cube position of the clouds. If los velocity specified, assume that the clouds have already been projected correctly. :return: arrays with the x-, y-, and z- positions of the cloudlets, and their los velocities .. py:method:: find_clouds_in_cube(los_vel, cent, x2, y2, x_size, y_size, v_size) Returns the clouds that lie inside the cube. :param los_vel: (ndarray) contains the line of sight velocities of each cloudlet, in km/s. :param cent: (ndarray of length 2) contains the x and y coordinates of the centre of the object within the cube :param x2: (ndarray) x-positions of the cloudlets within the cube :param y2: (ndarray) y-positions of the cloudlets within the cube :param x_size: (int) size of the cube in the x-direction :param y_size: (int) size of the cube in the y-direction :param v_size: (int) size of the cube in the z-direction :return: arrays with the positions of the cloudlets within the cube, and the indices of these positions .. py:method:: add_fluxes(clouds2do, subs, x_size, y_size, v_size) If there are clouds to use, and we know the flux of each cloud, add them to the cube. If not, bin each position to get a relative flux. :param clouds2do: (ndarray) contains the x-, y-, and v-positions of the cloudslets in the cube :param subs: (ndarray) the indices of the cloudlets in the cube :param x_size: (int) size of the cube in the x-direction :param y_size: (int) size of the cube in the y-direction :param v_size: (int) size of the cube in the v-direction :return: spectral cube with fluxes added to the cloudlets .. py:method:: normalise_cube(cube, psf) Normalise cube by the known integrated flux. :param cube: (3D array) unnormalised spectral cube :param psf: (2D array) psf of the mock observations, to convolve the cube with .. py:method:: model_cube(toplot=False, **kwargs) Do the actual modelling of the spectral cube :return: ~~the cube~~