Extrapolation

Extrapolate finite-radius waveforms from SpEC simulations to infinite radius.

The main function is Extrapolate, which reads waveforms extracted at several finite radii from an HDF5 file in the format written by SpEC, extrapolates them to infinite radius at several polynomial orders, and writes the results along with convergence plots. The remaining functions read and validate the input data, or manage batches of extrapolations run in many directories.

The functions in this module that read HDF5 files need h5py.

GWFrames.Extrapolation.PickChMass(filename='Horizons.h5')

Deduce the Christodoulou mass of a binary from its horizons file.

The total Christodoulou mass of the two horizons is binned over time, and the most common value is returned.

Parameters:

filename (str, default 'Horizons.h5') – The horizons file. If this is a directory, 'Horizons.h5' is appended to it.

Returns:

float

GWFrames.Extrapolation.MonotonicIndices(T, MinTimeStep=0.001)

Return the indices that make an array of times strictly increasing.

This is the same as GWFrames.MonotonicIndices, with a different default MinTimeStep.

GWFrames.Extrapolation.ValidateSingleWaveform(h5file, filename, WaveformName, ExpectedNModes, ExpectedNTimes, LModes)

Check the shapes of the datasets of one finite-radius waveform.

The areal radius, the average lapse, and each mode must have ExpectedNTimes rows, and there must be ExpectedNModes modes with \(\ell\) in LModes. Problems are printed.

Returns:

bool – True if the waveform passed all checks.

GWFrames.Extrapolation.ValidateGroupOfWaveforms(h5file, filename, WaveformNames, LModes)

Check that all of the finite-radius waveforms in a file are consistent.

Each waveform is checked with ValidateSingleWaveform against the number of times and modes of the first one. The names of any invalid waveforms are printed.

Returns:

bool – True if every waveform passed all checks.

GWFrames.Extrapolation.ReadFiniteRadiusWaveform(
n,
filename,
WaveformName,
ChMass,
InitialAdmEnergy,
YLMRegex,
LModes,
DataType,
SpinWeight,
Ws,
)

Read a single finite-radius waveform for ReadFiniteRadiusData.

This worker function reads one waveform from an HDF5 file of many, and is not usually called directly.

GWFrames.Extrapolation.ReadFiniteRadiusData(
ChMass=0.0,
filename='rh_FiniteRadii_CodeUnits.h5',
CoordRadii=[],
LModes=range(2, 100),
EnforceQualityAssurance=True,
)

Read the waveforms extracted at several radii, as functions of retarded time.

The retarded time is computed with the tortoise coordinate of each radius.

Parameters:

  • ChMass (float) – The Christodoulou mass, in the units of the data, which are rescaled so that this mass is 1. It must be nonzero.

  • filename (str, default 'rh_FiniteRadii_CodeUnits.h5') – The HDF5 file of finite-radius data.

  • CoordRadii (list, optional) – The radii to read, given as strings or as integer indices into the list of waveforms in the file. If empty (the default), all radii are read.

  • LModes (sequence of int, default range(2, 100)) – The values of \(\ell\) to read.

  • EnforceQualityAssurance (bool, default True) – If true, raise an error if the data fail ValidateGroupOfWaveforms.

Returns:

  • Ws (list of Waveform) – The waveforms, one for each radius.

  • Radii (list of ndarray) – The areal radius of each extraction sphere as a function of time.

  • CoordRadii (list of str) – The coordinate radii that were read.

GWFrames.Extrapolation.SetCommonTime(Ws, Radii, MinTimeStep=0.005, EarliestTime=-3e+300, LatestTime=3e+300)

Interpolate waveforms and radius data to a common set of times.

The common times are the intersection of the times of all the waveforms, found with GWFrames.Intersection. The waveforms and radii in Ws and Radii are replaced in place.

Parameters:

  • Ws (list of Waveform) – The waveforms.

  • Radii (list of array_like) – The radius of each waveform as a function of its times.

  • MinTimeStep (float, default 0.005) – The smallest allowed time step.

  • EarliestTime (float, default -3e300 and 3e300) – Bounds on the common times.

  • LatestTime (float, default -3e300 and 3e300) – Bounds on the common times.

GWFrames.Extrapolation.Extrapolate(**kwargs)

Extrapolate finite-radius data to infinite radius.

All arguments are optional keywords. The data are read with ReadFiniteRadiusData, interpolated to common times, extrapolated in powers of \(1/r\) at each of the requested orders, transformed to the output frame, and written to files, together with the differences between successive orders and plots of their convergence.

Parameters:

  • InputDirectory (str, default './') – Where to find the input data. This can be relative or absolute.

  • OutputDirectory (str, default './') – Where to write the output. This directory is made if it does not exist.

  • DataFile (str, default 'rh_FiniteRadii_CodeUnits.h5') – The input file holding the data from all the radii.

  • ChMass (float, default 0.0) – The Christodoulou mass in the units of the data, which are rescaled so that this mass is 1. If it is zero, the mass is found from HorizonsFile with PickChMass.

  • HorizonsFile (str, default 'Horizons.h5') – The horizons file read when ChMass is zero.

  • CoordRadii (list, default []) – The radii to use, given as strings or as integer indices into the list of waveforms in DataFile, in the order of list(h5py.File(DataFile)), which should be the order shown by h5ls. If the list is empty, all radii that can be found are used.

  • LModes (sequence of int, default range(2, 100)) – The values of \(\ell\) to extrapolate.

  • ExtrapolationOrders (list of int, default [-1, 2, 3, 4, 5, 6]) – The orders of the extrapolating polynomials. Negative numbers select the extracted data instead, counting down from the outermost extraction radius, which is -1.

  • UseOmega (bool, default False) – Whether to extrapolate as a function of \(\lambda/r = 1/(r\, m\, \omega)\), where \(\omega\) is the instantaneous angular frequency of rotation. If this is true, the extrapolation will usually not converge for high orders; if it is false, SVD will generally cause the convergence to appear to fall to roundoff, though the accuracy is presumably not as good.

  • OutputFrame (int, default GWFrames.Inertial) – The frame to which the data are transformed before comparison and output.

  • ExtrapolatedFiles (str, default 'Extrapolated_N{N}.h5') – The names of the output files, in which the extrapolation order is substituted for {N}. The data type inferred from the name of DataFile is prepended.

  • DifferenceFiles (str, default 'ExtrapConvergence_N{N}-N{Nm1}.h5') – The names of the files of differences between successive orders, in which the order is substituted for {N} and the previous order for {Nm1}. If this is empty, these files are not written.

  • UseStupidNRARFormat (bool, default False) – If true, and ExtrapolatedFiles does not end in '.dat', the output is written in the old NRAR format, which does not convey enough information, is slow, and uses 33% more space than it needs to.

  • PlotFormat (str, default 'pdf') – The format of the output plots, which may be any format supported by matplotlib. If this is empty, no plots are made.

  • MinTimeStep (float, default 0.005) – The smallest allowed time step in the output data.

  • EarliestTime (float, default -3.0e300) – The earliest time in the output data. Some of the data at times less than 0 correspond to times when only junk radiation is present.

  • LatestTime (float, default 3.0e300) – The latest time in the output data.

  • AlignmentTime (float, optional) – The time at which the waveform is aligned with the dominant eigenvector of \(\langle LL \rangle\). If it is None (the default) or outside the data, the midpoint of the outermost waveform, (W_outer.T(0) + W_outer.T(-1)) / 2, is used.

GWFrames.Extrapolation.UnstartedExtrapolations(TopLevelOutputDir, SubdirectoriesAndDataFiles)

Return the extrapolations in a batch that have not been started.

Parameters:

  • TopLevelOutputDir (str) – The directory under which the output of each extrapolation is written.

  • SubdirectoriesAndDataFiles (list of [str, str]) – Pairs of subdirectory and data file, as returned by FindPossibleExtrapolationsToRun.

Returns:

list of [str, str] – The pairs with no .started_* marker in their output directory.

GWFrames.Extrapolation.NewerDataThanExtrapolation(TopLevelInputDir, TopLevelOutputDir, SubdirectoriesAndDataFiles)

Return the finished extrapolations whose input data have since changed.

Returns:

list of [str, str] – The pairs of subdirectory and data file whose data file or metadata.txt is newer than the .finished_* marker of the extrapolation.

GWFrames.Extrapolation.StartedButUnfinishedExtrapolations(TopLevelOutputDir, SubdirectoriesAndDataFiles)

Return the extrapolations that started but neither finished nor failed.

Returns:

list of [str, str] – The pairs of subdirectory and data file with a .started_* marker but neither a .finished_* nor an .error_* marker.

GWFrames.Extrapolation.ErroredExtrapolations(TopLevelOutputDir, SubdirectoriesAndDataFiles)

Return the extrapolations that failed.

Returns:

list of [str, str] – The pairs of subdirectory and data file with an .error_* marker.

GWFrames.Extrapolation.FindPossibleExtrapolationsToRun(TopLevelInputDir)

Find all of the extrapolations that could be run under a directory.

Every subdirectory named like Lev* that contains a metadata.txt file and one or more files of finite-radius data, such as rh_FiniteRadii_CodeUnits.h5, gives one extrapolation for each data file.

Parameters:

TopLevelInputDir (str) – The directory to search.

Returns:

list of [str, str] – Pairs of subdirectory (relative to TopLevelInputDir) and data file.

GWFrames.Extrapolation.RunExtrapolation(TopLevelInputDir, TopLevelOutputDir, Subdirectory, DataFile, Template)

Run one extrapolation as a separate Python process.

The Template is written as a script into the output directory, with {DataFile} and {Subdirectory} replaced, and run there. Marker files .started_*, .finished_*, and .error_* record the progress, for use by functions like UnstartedExtrapolations.

Returns:

int – Zero on success, or the nonzero exit status of a failed script.