HMI_Logo HMI Ring Diagrams
Pipeline Module Specifications

rdfitf

Module Version
	0.9	6 V 2019

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

Status
	Included in JSOC release 9.4
	In use for ring-diagram pipelines 2019.05.06 – 
	This version supersedes Version 0.8

	The source code and Makefile are in the JSOC CVS repository

Usage
	rdfitf [-flags] in= InputDescriptor out= OutputDescriptor
	    [param= val ...]
	
Flags
	-d	do not use second derivatives in parameter errors
	-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

Parameters
	in		Name of an input data set (record selection);
			No default
	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.
			No default
	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:
	CRPIX1, CRPIX2, DELTA_K, DELTA_NU, LOG_BASE, RSunRef

Sample input series:
	hmi.rdVpspec_fd05
	hmi.rdVpspec_fd15
	hmi.rdVpspec_fd30
	mdi.rdVpspec_dp

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,
	Apode_f, APOD_MIN, APOD_MAX
	

Sample output series:
	hmi.rdVfitsf_fd05
	hmi.rdVfitsf_fd15
	hmi.rdVfitsf_fd30
	mdi.rdVfitsf_dp

Bugs in current version
	It is implictly assumed that in the input spectrum, NAXIS1 = NAXIS2,
	CRPIX1 = CRPIX2, CRVAL1 = CRVAL2, and CDELT1 = CDELT2; only the first
	and second of these are checked. Also, it is required that NAXIS1 and
	NAXIS2 are even.

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

Significant changes from Previous Version
	Modified treatment of CRPIX1,2 to reflect corrections in output of module pspec3

	Removed defaults for input power spectra and guessfile

	Changed flag 2 to d

Valid HTML 4.01 Transitional HMI Ring Diagrams 16 May 2020, 18:11-0700