HMI_Logo HMI Ring Diagrams
Pipeline Module Specifications

rdfitf

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

Status
	Included in JSOC release 5.10

	The source code and Makefile are in the JSOC CVS repository

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

	rdfitf_v08 is a compiled standalone DRMS binary built with NetDRMS 2.4
	to run in the JSOC configuration. Versions are in:
		~rick/bin/linux_x86_64/rdfitf_v08
		~rick/bin/rick/rdfitc_v08
	The source code and Makefile is in ~rick/src/ringfit/rdfitf

Usage
	rdfitf_v08 [-flags] in= InputDescriptor out= OutputDescriptor
	    [param= val ...]
	
Flags
	-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

Parameters
	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:
	CRPIX1, CRPIX2, DELTA_K, DELTA_NU, LOG_BASE, RSunRef

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

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:
	mdi.rdVfitsf_dp
	hmi_test.rdVfitsf_fd05
	hmi_test.rdVfitsf_fd15
	hmi_test.rdVfitsf_fd30

Bugs in current version
	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

Valid HTML 4.01 Transitional HMI Ring Diagrams 30 Nov 2010, 14:10-0800