HfS

Hyperfine Structure fitting

HfS. Version 2023.8

A full description of HfS, fitting strategy, calculation of the synthetic spectrum, derivation of line and physical parameters, error estimation of the fit and derived parameters, and a comparison with other fit routines can be found in Estalella (2017).

See a history of changes and old versions here

General HfS procedures

HfS (Estalella 2017) is a tool to fit the hyperfine structure of spectral lines, with multiple velocity components. The information on the transition hyperfine structure is read from the file hfs_transitions.dat. For each velocity component, four independent parameters are fitted:

Δv, hyperfine line FWHM (deconvolved from the instrumental spectral resolution);
vLSR, main line central velocity;
A (1 – e–τm), main line intensity (in the same units as the input spectra);
1 – e–τm, where τm is the optical depth of the main line.

HfS consists in different procedures:

hfs_fit: interactive graphic procedure for fitting simultaneously up to 9 velocity components of an spectral line with hyperfine structure to a data spectrum, and generating a file with the synthetic spectrum. Optional Hanning filtering of the data can be performed.
hfs_file: batch procedure for fitting (single component) spectra of a list of files, and generating a list of files with the synthetic spectra.
hfs_cube_sp (single processor) and hfs_cube_mp (multiprocessor): batch procedures for fitting simultaneously up to 9 velocity components of spectra from a 3-axes FITS data cube. A subimage of the FITS data cube can be selected, and optional boxcar averaging of pixels and Hanning filtering of the spectra can be performed.
hfs_view: interactive graphic procedure for displaying spectra from a FITS data cube and the corresponding synthetic spectra. The data and synthetic spectra at any pixel can be extracted in ASCII files.
hfs_blanking: procedure to flag the fit values in the output out and FITS files from hfs_cube, according to any line parameter value, error, or |value|/error

HfS NH3 procedures

HfS NH3 procedures fit simultaneously the hyperfine structure of NH3 (1,1) and (2,2) inversion transition spectra. The assumptions made are that the emitting region is homogeneous along the line of sight, and that the filling factor f, the excitation temperature Tex, the hyperfine components linewidth Δv, and the central velocity vLSR are the same for all the hyperfine components of the (1,1) and (2,2) transitions. However, since there is enough information, a different vLSR can be fitted for the (1,1) and the (2,2) spectra. In general, differences in central velocity of a few tenths of km s-1 are usually found between the (1,1) and (2,2) emissions.

Six independent parameters are fitted:

Δv, hyperfine line FWHM;
vLSR1, central velocity of the (1,1) main line;
A (1 – e–τ1m), intensity of the (1,1) main line;
1 – e–τ1m, where τ1m is the optical depth of the (1,1) main line;
vLSR2, central velocity of the (2,2) main line;
A (1 – e–τ2m), intensity of the (2,2) main line.

For each set of fit parameters, the optical depth of the (2,2) transition, τ2m, is obtained from the relation

[1 – e–τ2m] = [1 – e–τ1m] × [A (1 – e–τ2m)] / [A (1 – e–τ1m)],

and used to evaluate the (2,2) synthetic spectrum.

From the values of the fit parameters, five derived parameters are calculated, which are necessary for the estimation of parameters with physical interest:

A, amplitude, assumed to be the same for the (1,1) and (2,2) transitions.
τ1m, optical depth of the (1,1) main line.
A τ1m, amplitude times the (1,1) main line optical depth,
τ2m, optical depth of the (2,2) main line.
A τ2m, amplitude times the (2,2) main line optical depth,

The physical parameters that are derived from the standard analysis of NH3 (1,1) and (2,2) observations are:

Tex, excitation temperature (assuming a filling factor f = 1, and that the input spectra are given in K);
fN(1,1), fN(2,2), fN(NH3), beam-averaged column densities for both f ≪ 1 and f = 1;
Trot and Tk, rotational and kinetic temperature.

You can find a detailed explanation on the derivation of the physical parameters and their uncertainty in Estalella (2017).

The HfS NH3 procedures are similar to to the general HfS procedures:

hfs_nh3: interactive graphic procedure for fitting simultaneously up to 9 velocity components of a pair of NH3 (1,1) and (2,2) spectra.
hfs_nh3_cube_sp (single processor) and hfs_nh3_cube_mp (multiprocessor): batch procedures for fitting simultaneously up to 9 velocity components of spectra from a pair of 3-axes FITS NH3 (1,1) and (2,2) data cubes.
hfs_nh3_view: interactive graphic procedure for displaying spectra from a pair of NH3 (1,1) and (2,2) data cubes and the corresponding synthetic spectra.
hfs_nh3_blanking: procedure to flag the fit values in the output out and FITS files from hfs_nh3_cube, according to the any line parameter value, error, or |value|/error

HfS auxiliary procedures

hfs_synt: procedure to create a synthetic spectrum, with the option of adding Gaussian noise.
hfs_fits_blanking: procedure to flag the output FITS files of hfs_cube and hfs_nh3_cube, according to the parameter values, errors, or |value|/error

Requisites

Linux or Mac OS X system.
Fortran 90 compiler, e.g. gfortran.
PGplot Graphics Subroutine Library. The library has to be installed from the Linux repository. If the library is compiled locally, the program can crash in some computers. Remove old installations of PGplot and install the library. For an Ubuntu system:

$ sudo apt-get install pgplot5

Mac users can find a guide for installing PGplot on Mac OS X in mingus.as.arizona.edu/~bjw/software/pgplot_fix.html or a local copy of the page pgplot_macosx. PGplot is needed for the graphic output of HfS procedures. However, it is not needed for hfs_cube_mp, hfs_nh3_cube_mp, hfs_blanking, hfs_nh3_blanking, hfs_fits_blanking.

Open MPI is only needed for the multiprocessor procedures hfs_cube_mp and hfs_nh3_cube_mp.

Installation

Download hfs.tgz.
Untar hfs.tgz in your installation directory, for instance /usr/local/hfs,

$ sudo mkdir /usr/local/hfs

$ sudo mv hfs.tgz /usr/local/hfs

$ cd /usr/local/hfs

$ sudo tar -xzvf hfs.tgz

If necessary, edit the first lines of the shell script hfs_compile to change the lines

compiler="gfortran"

libraries="-lpgplot"

You may need to give the location of the PGplot library and link the X11 library with the option

libraries="-lpgplot -L/usr/local/lib/pgplot -lX11"

Mac users may need something like

libraries="-lpgplot -L/usr/local/lib/pgplot -lX11 -L/usr/X11/lib"

Run the compile script

$ sudo ./hfs_compile

and verify that there are no errors in the compilation.

If necessary, edit the first lines of the shell script hfs_links to change the line

exe_dir="/usr/local/bin"

and run the links script to create symbolic links in $exe_dir pointing to the HfS procedures

$ sudo ./hfs_links

Define the environment variable HFS_DIR, pointing to your installation directory. It is used by HfS to find the files hfs_transitions.dat and hfs_fit.help. This can be done by adding to your .bashrc or .bash_profile the lines

HfS