HMI_Logo HMI Ring Diagrams
Pipeline Module Specifications


Module Version
	0.8	19 VIII 2010

General Description
	rdfitf implements the procedure of Haber et al. (ApJ 570, 855;
	Solar Phys 192, 335) for fitting 3-d solar acoustic power spectra
	to a model for transverse advective terms and other line background

	This version has been superseded by Version 0.9

	Included in JSOC release 5.10
	In use for ring-diagram pipelines 2010.11.18 – 2019.04.20

	The source code and Makefile are in the JSOC CVS repository

	Earlier α and β versions were included in JSOC releases 5.7 & 5.9

	rdfitf [-flags] in= InputDescriptor out= OutputDescriptor
	    [param= val ...]
	-f	write out spatial wavenumber filter
	-n	no fitting (diagnostics only)
	-U	write out azimuthally unwrapped power spectrum
	-v	run verbose
	-x	run really verbose
	-2	do not use second derivatives in parameter errors

	in		Name of an input data set (record selection);
			Default: mdi.rdVpspec_dp[1988][180][180][0]
	out		Name of the output data series (or file)
			Default: fit.out
			The value of the out parameter is interpreted as the name of
			of a data series, and if such a series exists with insert
			permission, the output fit file and ancillary FITS files
			will be inserted as records in that series; otherwise, the
			value will be interpreted as the name of a file to which
			the fit parameters are written
	guessfile	Name of a file containing parametrizations for the each
			fitting parameter; should be a rooted pathname.
			Default: /home/dhaber/coefhrtest.dat
	unwrap		Name of the segment in the output data record to which the
			azimuthally unwrapped power spectrum will be written if the
			-U flag is set. Default: unwrap
	filter		Name of the segment in the output data record to which the
			spatial wavenumber filter will be written if the -f flag is
			set. Default: filter
	filtps		Name of the segment in the output data record to which the
			spatially filtered subsampled unwrapped power spectrum will
			be written if the -u flag is set. Default: filtps
	nmin		Minimum radial (vertical) order to fit. Default: 0
	nmax		Maximum radial order to fit. Default: 6
	npar		Number of parameters to fit. Default: 7
	ntht		Number of azimuth values for initial unwrapping of the power
			spectrum, usually = πnk; should be divisible by 4. Default: 400
	nthts		Number of azimuth values after subsampling, generally a factor of
			10 less than ntht; should also be divisible by 4. Default: 40
	nrdtot		Number of ridges in guessfile. As long as there are 16 or less,
			the default should work. Default: 16
	ux		Initial guess for zonal flow speed [m/s]. Default: 0.0
	uy		Initial guess for meridional flow speed [m/s]. Default: 0.0
	smooth		Amount of smoothing wanted [wavenumber bins]. Default: 0
	mdata		Number of azimuthal Fourier components to keep when subsampling
			the data. Default: 16
	mfilt		Highest azimuthal Fourier component to use in filtering the data.
			Default: 8
	kstart		Array of starting kbin values for each order.
			Default: {11, 7,  6,  6,  6,  6,  7,  8}
	kstop		Ending kbin values for each order.
			Default: {55, 55, 45, 44, 37, 27, 23, 20}
	xtol		Termination tolerance on fitting parameters. Default: 1e-4
	ftol		Termination tolerance on fitting function. Default: 1e-8
	feps		Accuracy of function values from FUNC. Default: 1e-16
	delta0		Initial radius of the trust region. Default: 0.0
	maxeval		Maximum number of iterations for each fit; Default: 750
	igrad		If set to 0, F' is calculated numerically. If 1, the subroutine
			DF1 is used to calculate F'. If set to 2, DF1 is called to
			calculate F' initially, and the results from GRAD are checked by
			comparing them to the F' obtained using finite differences.
			Default: 1
	iextrap		If set to 1, safeguarded quadratic/cubic interpolation and
			extrapolation are performed. Default: 1
	idiag		If set to 0, the initial approximation to the Hessian is I.
			If set to 1, the diagonal of the true Hessian is computed initially
			using a finite difference approximation. Default: 0
	iprint		Set to 1 to print information after each iteration. Default: 0

Input Data series class:
	power spectra of data cubes

Input keys used or inspected:

Sample input series:

Output Data series class:
	ring diagram mode fits

Output keys set (if possible):
	Quality, CarrTime*, Module, Source, n_n_fits

	* if not propagated

Input keys propagated to output (if possible):
	CarrRot, CMLon, CarrTime, LonHG, LatHG, LonCM, MidTime, Duration, Cadence,
	LonSpan, T_START, T_STOP, Coverage, Size, Width, Height, ZonalTrk, ZonalVel,
	MeridTrk, MeridVel, MapScale, MapProj, Map_PA, RSunRef, PosAng, MAI,

Sample output series:

Bugs in current version
	The code assumes that the values of CRPIX1 and CRPIX2, describing the
	location of the pixel corresponding to zero spatial frequency, are too
	small by 0.5. This corrects for a bug in versions of module pspec3
	prior to Version 1.2.
	It is implictly assumed that in the input spectrum, NAXIS1 = NAXIS2,
	CRPIX1 = CRPIX2, CRVAL1 = CRVAL2, and CDELT1 = CDELT2. It is not clear
	that the code would work properly if NAXIS1 and NAXIS2 are odd.

	Several of the named value arguments are really just flags or enums.

	None of the run parameters are put into the DRMS output record.

	Writing of intermediate data files (unwrapped spectra etc.) is only
	supported in DRMS, there is no direct FITS write to named file.
	The test on lnbase in cart_to_polar is probably wrong, since lnbase
	will be returned as NaN rather than 0 if the keyword is missing.

	It is not clear what happens if npar > 6; npar < 6 is forbidden.

	Most or all of the internally written information when the verbose flag
	is set should be written to the Log segment.

	The default values of kstart and kstop refer to the number of k bins,
	and need to be adjusted for different sizes of tiles; they should be
	calculated, not read in as parameters.

	The decision as to whether the output specifier refers to a data series
	or a file name based on whether it can be referred to a series
	writeable by the user is not sensible, but probably not particularly

Valid HTML 4.01 Transitional HMI Ring Diagrams 7 May 2019, 10:23-0700