Skip to content

lalapps_PredictFstat --maxStartTime changes meaning with/without --DataFiles

@karl-wette looks like I found another problem related to inconsistent interpretation of the notorious word "maxStartTime" for our SFT-based codes. (c.f. #334 (closed)) lalapps_PredictFstat seems to actually interpret the same user argument in two different ways depending on whether or not it also loads --DataFiles:

  1. If it does, then the half-open interval [minStartTime,maxStartTime) is used as a constraint, following as usual the convention from XLALCWGPSinRange. (With its counterintuitive consequence: a SFT timestamp exactly matching maxStartTime will be excluded. But it allows for naively setting maxStartTime=startTime+duration to get all SFTs, with the latter 2 variables interpreted as per MFD -- as the test script does without my initially proposed fix in !1422 (merged).)
  2. But when setting up its own timestamps from just --minStartTime --maxStartTime input, without --DataFiles, then it does duration = XLALGPSDiff( &(uvar->maxStartTime), &(uvar->minStartTime)) + Tsft and follows the XLALMakeTimeStamps convention of "the returned list of timestamps are guaranteed to cover the interval [tStart, tStart+duration)", meaning an SFT timestamp exactly matching maxStartTime will be included. Here the test script currently gets an inconsistent result (without failing, due to overly generous tolerance).

To demonstrate:

mkdir testPredictFstat
lalapps_Makefakedata_v4 --Alpha=2.0 --Delta=-0.5 --IFO=H1 --Tsft=1800 --startTime=700000000 --duration=3600 --h0=1 --cosi=-0.3 --psi=0.6 --phi0=1.5 --fmin=99.1235 --Band=2.0 --Freq=100.12345 --outSFTbname=./testPredictFstat/ --noiseSqrtSh=0.5 --randSeed=1

tmpPFS=./testPredictFstat/tmpPFS.dat

$ lalapps_PredictFstat --outputFstat=$tmpPFS --h0=1 --cosi=-0.3 --psi=0.6 --Alpha=2 --Delta=-0.5 --assumeSqrtSX=0.5 --DataFiles=./testPredictFstat/*.sft && grep Loaded $tmpPFS

421.9
%% Loaded SFTs: [ LHO_4k:2 ]
$ lalapps_PredictFstat --outputFstat=$tmpPFS --h0=1 --cosi=-0.3 --psi=0.6 --Alpha=2 --Delta=-0.5 --assumeSqrtSX=0.5 --DataFiles=./testPredictFstat/*.sft --minStartTime=700000000 --maxStartTime=700001800 && grep Loaded $tmpPFS

228.4
%% Loaded SFTs: [ LHO_4k:1 ]
$ lalapps_PredictFstat --outputFstat=$tmpPFS --h0=1 --cosi=-0.3 --psi=0.6 --Alpha=2 --Delta=-0.5 --assumeSqrtSX=0.5 --DataFiles=./testPredictFstat/*.sft --minStartTime=700000000 --maxStartTime=700003600 && grep Loaded $tmpPFS

421.9
%% Loaded SFTs: [ LHO_4k:2 ]
$ lalapps_PredictFstat --outputFstat=$tmpPFS --h0=1 --cosi=-0.3 --psi=0.6 --Alpha=2 --Delta=-0.5 --assumeSqrtSX=0.5 --IFOs=H1 --minStartTime=700000000 --maxStartTime=700001800 && grep Loaded $tmpPFS

421.9
%% Loaded SFTs: [ LHO_4k:2 ]
$ lalapps_PredictFstat --outputFstat=$tmpPFS --h0=1 --cosi=-0.3 --psi=0.6 --Alpha=2 --Delta=-0.5 --assumeSqrtSX=0.5 --IFOs=H1 --minStartTime=700000000 --maxStartTime=700003600 && grep Loaded $tmpPFS

623.4
%% Loaded SFTs: [ LHO_4k:3 ]

I would say the second behaviour matches the intuitive meaning of the word "maxStartTime" better, but since it contradicts the XLALCWGPSinRange convention, it's technically wrong, and intuitive != correct is especially problematic for users.

If I haven't twisted my brain the wrong way around this whole issue, I suggest not silently changing either case, but:

  1. introduce a new user option --duration for use without --DataFiles, when it will be passed straight through to XLALMakeMultiTimestamps
  2. throw an error when using --maxStartTime without --DataFiles explaining that it's ambiguous, the old behaviour was wrong, and asking to use --duration instead
  3. (optional): also allow --duration with --DataFiles, where it would be used to set maxStartTime=minStartTime+duration (lazy and a bit confusing, but as per above should actually work)

cc @rodrigo.tenorio