Basics

Tutorials

Models

Inference

Verification

Theory

The Heron Modelling Interface

All models implemented in the heron package are built on top of the Model class, which provides a number of useful methods to assist in creating a Gaussian process model.

class heron.models.Model[source]

This is the factory class for statistical models used for waveform generation.

A model class must expose the followi*** TODO Email about Away Dayc_ind = {j:i for i,j in columns.items()}c_ind = {j:i for i,j in columns.items()}ng methods: - distribution : produce a distribution of waveforms at a given point in the parameter space - mean : produce a mean waveform at a given point in the parameter space - train : provide an interface for training the model

All of the methods which are provided by this class are intended to be treated as private methods, which other classes build upon, and which aren’t intended to be accessed directly.

To build a new model we can begin by inheriting the Model class.

class NewModel(Model):
   pass

This will give your new model access to the various methods which are needed to produce waveform outputs from a model.

As a minimum your new model must contain three methods so that heron can interact with it properly.

distribution()

This method should return the parameters of the waveform distribution at a given location in parameter space, i.e. a vector representing the mean and variance at each requested location. The function should have the following signature

distribution(self, p, times, *args, **kwargs)

With p being a dictionary of coordinates in the parameter space, and times being a list or array of times at which the waveform distribution should be produced.

mean()

This method should return only the mean waveform at a given location in the parameter space. It should have the signature

mean(p, times, *args, **kwargs)

Where p is a dictionary of coordinates in the parameter space, and times is a list or array of times at which the waveform distribution should be produed.

train()

This method defines the correct way to “train” the model, in order to determine the optimal values of the hyperparameters for the model (using an empirical Bayesian approach). This method should, at the minimum, set self.training to True for the model, and self.evaluate to False, in order to mark the model as being in a training state, and not suitable for evaluation.

If this method conducts the entire training process you may then switch these flags to set self.evaluate to True and self.training to False before the method completes its execution. Alternatively you should define an eval() method to do this, and any other cleaning-up which should be done after training. If heron encounters a model in training state when attempting to evaluate it, it will first attempt to run the eval() method on the model.

In addition to the Model class, a number of additional helper classes exist within heron, mainly to help with the construction of gravitational wave models.

Gravitational wave-specific classes

The heron.models.gw.BBHSurrogate should be inherited in a class if it is designed to emulate binary black hole waveforms. This class provides metadata related to the intrinsic parameters of these systems. For simpler models which don’t include spin effects you should use the heron.models.gw.BBHNonSpinSurrogate class instead.

For time-domain strain models you should have your model class inherit the heron.models.gw.HofTSurrogate class. This provides interfaces to the waveform model which are particular to a time-domain model.

Frequency domain transforms

Heron is capable of performing the Fourier transform of the outputs of its models. Unlike a conventional waveform model, where the conversion from time-domain to frequency-domain requires applying the DFT to the time-domain waveform, heron must compute the transformation on the multidimensional normal distribution which the model outputs.

Fortunately, this process is straight-forward. A Heron model provides a mean waveform, and the associated covariance matrix, meaning that a waveform, $h$ drawn from the model can be represented as a series of draws of the form

\[h(t) ~ \mathcal{N}(\mu, \Sigma)\]

for \(\mu\) and \(\Sigma\) respectively the mean and covariance at the appropriate point in parameter space.

Given the Gaussian function has the property that \(\forall A \in \mathcal{C}\)

\[Ax ~ \mathcal(A \mu, A \Sigma A^{\mathrm{T}})\]

It is possible to represent the discrete Fourier transform as a matrix operator (the DFT Matrix), so for

\[\tilde{x}(f) = \mathcal{F}[x(t)] = Fx ~ \mathcal{N}(F\mu, F \Sigma F^{\mathrm{T}})\]

meaning that a draw of a frequency domain waveform can be calculated by drawing from the normal distribution with a mean of fft(mean_t) and covariance fft2(covariance_t).

The frequency_domain_waveform method can be used on models which support the conversion to provide frequency domain waveforms.