make mismatch cutoff in XLALFstatMaximumSFTLength() user-configurable

• introducing a new XLALFstatCheckSFTLengthMismatch() wrapper and a macro DEFAULT_MAX_MISMATCH_FROM_SFT_LENGTH as a fallback
• user override needs to be passed through FstatInput->common struct
• developer override option and friendly error message in CFS_v2
• closes https://git.ligo.org/CW/lalsuite/issues/41

@karl-wette That's the most elegant solution I could come up with, let me know if you dislike the addition to FstatInput->common or know a better way.

I still need to update documentation of XLALFstatMaximumSFTLength(), and add one to the new checking wrapper function, but best if you have an initial look first.

testing the function itself through python:

before patch:
>>> import lalpulsar
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0)
2054.3790449111466

after patch:
>>> import lalpulsar
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0,0)
2054.3790449111466
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0,0.01)
1373.8460690310508
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0,0.1)
2443.0821771208302:
>>> import lalpulsar
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0)
2054.3790449111466

after:
>>> import lalpulsar
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0,0)
2054.3790449111466
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0,0.01)
1373.8460690310508
>>> lalpulsar.FstatMaximumSFTLength(2000,0,0,0.1)
2443.0821771208302

testing CFSv2:

# default test case with 100Hz signal
NOCLEANUP=1 ./testCFSv2.sh
grep twoF testCFSv2.d/Fstat_loudest.dat
twoF     =  589.214;

# remake data at 3000Hz
../Injections/lalapps_Makefakedata_v4 --Alpha=2.0 --Delta=-0.5 --IFO=H1 --Tsft=1800 --startTime=711595934 --duration=144000 --h0=1 --cosi=-0.3 --psi=0.6 --phi0=1.5 --fmin=2999.1235 --Band=2.0 --Freq=3000.12345 --outSFTbname=testCFSv2.d/H1-sfts.sft --f1dot=-1e-10 --outSingleSFT --refTime=711595934 --noiseSqrtSh=5 --randSeed=1

# new error message
./lalapps_ComputeFstatistic_v2 --IFO=H1 --Alpha=2.0 --Delta=-0.5 --Freq=3000.1234465277778 --dFreq=1.388888888888889e-08 --f1dot=-1e-10 --f1dotBand=0 --df1dot=1 --DataFiles='testCFSv2.d/*.sft' --NumCandidatesToKeep=500 --Dterms=8 --outputLoudest=testCFSv2.d/Fstat_loudest.dat --refTime=711595934 --outputFstat=testCFSv2.d/testCFSv2.dat --TwoFthreshold=0 --FreqBand=6.944444444444445e-06
2018-11-15 11:24:56.2935 (7788) [normal]: Finding all SFTs to load ... done. (found 80 SFTs)
2018-11-15 11:24:56.6159 (7788) [normal]: Setting up template grid ... template grid ready.
XLAL Error - XLALFstatCheckSFTLengthMismatch (ComputeFstat.c:173): Length of input SFTs (1800 s) must be less than 1677.27 s for CW signal with frequency = 3000.44, binary asini = 0, period = 0 to stay below mismatch of 0.05.
XLAL Error - XLALFstatCheckSFTLengthMismatch (ComputeFstat.c:173): Invalid argument
XLAL Error - InitFstat (ComputeFstatistic_v2.c:1461): Excessive mismatch would be incurred due to SFTs being too long for the current search setup. Please double-check your parameter ranges or provide shorter input SFTs. If you really know what you're doing, you could also consider using the --allowedMismatchFromSFTLength override.
XLAL Error - InitFstat (ComputeFstatistic_v2.c:1461): Internal function call failed: Invalid argument
XLAL Error - main (ComputeFstatistic_v2.c:413): Check failed: InitFstat( &GV, &uvar) == XLAL_SUCCESS
XLAL Error - main (ComputeFstatistic_v2.c:413): Internal function call failed: Invalid argument

# override it
./lalapps_ComputeFstatistic_v2 --IFO=H1 --Alpha=2.0 --Delta=-0.5 --Freq=3000.1234465277778 --dFreq=1.388888888888889e-08 --f1dot=-1e-10 --f1dotBand=0 --df1dot=1 --DataFiles='testCFSv2.d/*.sft' --NumCandidatesToKeep=500 --Dterms=8 --outputLoudest=testCFSv2.d/Fstat_loudest.dat --refTime=711595934 --outputFstat=testCFSv2.d/testCFSv2.dat --TwoFthreshold=0 --FreqBand=6.944444444444445e-06 --allowedMismatchFromSFTLength=0.1
2018-11-15 11:25:19.7774 (7802) [normal]: Finding all SFTs to load ... done. (found 80 SFTs)
2018-11-15 11:25:20.0772 (7802) [normal]: Setting up template grid ... template grid ready.
%% cmdline: /home/dkeitel/git/lvc/lalsuite/lalapps/src/pulsar/Fstatistic/.libs/lalapps_ComputeFstatistic_v2 --Alpha=2 --Delta=-0.5 --Freq=3000.123446527778 --f1dot=-1e-10 --FreqBand=6.944444444444445e-06 --f1dotBand=0 --dFreq=1.388888888888889e-08 --df1dot=1 --DataFiles="testCFSv2.d/*.sft" --IFO="H1" --TwoFthreshold=0 --refTime=711595934 --outputFstat="testCFSv2.d/testCFSv2.dat" --outputLoudest="testCFSv2.d/Fstat_loudest.dat" --NumCandidatesToKeep=500 --Dterms=8 --allowedMismatchFromSFTLength=0.1
%% LAL: 6.19.0.1 (CLEAN 3b0573e1e881e20ecb0e33a465952c8579f718dc)
%% LALFrame: 1.4.4.1 (CLEAN 3b0573e1e881e20ecb0e33a465952c8579f718dc)
%% LALSimulation: 1.8.0.1 (CLEAN 3b0573e1e881e20ecb0e33a465952c8579f718dc)
%% LALPulsar: 1.17.0.1 (UNCLEAN 3b0573e1e881e20ecb0e33a465952c8579f718dc)
%% LALApps: 6.22.0.1 (UNCLEAN 3b0573e1e881e20ecb0e33a465952c8579f718dc)
%% FstatMethod used: 'DemodSSE'
%% Started search: 2018-11-15 11:25:20.0868
%% Loaded SFTs: [ H1:80 ]
%% GPS starttime         = 711595934 (Thu Jul 25 01:32:01 2002 GMT)
%% Total time spanned    = 144000 s (40.00 hours)
%% Pulsar-params refTime = 711595934
%% Spin-range at refTime: fkdot = [ 3000.123446527778:3000.123453472223, -1e-10:-1e-10, 0:0, 0:0, 0:0, 0:0, 0:0 ]
2018-11-15 11:25:20.0895 (7802) [normal]: Sorting toplist ... done.
2018-11-15 11:25:20.0916 (7802) [normal]: Search finished.

# no error, but hmmm we got more than 10% mismatch...?
grep twoF testCFSv2.d/Fstat_loudest.dat
twoF     =  441.65;

Note that mismatch seems much bigger than allowed, but quite likely it's some other options that shouldn't be naively kept the same when going from 100Hz to 3000Hz in this test case, which I haven't looked at in detail.