# MATERNOISE is the jMatern module of jLab.

``` MATERNOISE  Realizations of the Matern process and variations, including fBm. [with A. Sykulski]

Z=MATERNOISE(DT,N,SIGMA,ALPHA,LAMBDA) simulates a length N complex-
valued Matern random process Z having variance SIGMA^2, slope parameter
ALPHA, and damping parameter LAMBDA.

DT is the sample interval.  Note that LAMBDA is understood to have the
same units as the inverse sample interval 1/DT.  For values of LAMBDA
greater than about 1/DT, the process becomes essentially white noise.
Thus typical values will have LAMBDA<(1/DT).

Z=MATERNOISE(DT,N,A,ALPHA,0) generates realizations of fractional
Brownian motion.  In this case, the third input argument is the
spectral amplitude A, not the standard deviation SIGMA.

Z=MATERNOISE(DT,[N,M],SIGMA,ALPHA,LAMBDA) generate M realizations of
the process, so that Z is of size N x M.

For details, including the fast generation method described below, see:

Lilly, Sykulski, Early, and Olhede, (2017).  Fractional Brownian
motion, the Matern process, and stochastic modeling of turbulent
dispersion.  Nonlinear Processes in Geophysics, 24: 481--514.
__________________________________________________________________

Extensions

Several extensions of the basic Matern form are supported, all of which
are discussed in more detail in MATERNSPEC.

Oscillatory Matern
Z=MATERNOISE(DT,N,SIGMA,ALPHA,LAMBDA,NU)
Generalized Matern (+ optional oscillations)
Z=MATERNOISE(DT,N,SIGMA,ALPHA,LAMBDA,GAMMA,'general')
Z=MATERNOISE(DT,N,SIGMA,ALPHA,LAMBDA,GAMMA,NU,'general')
Extended Matern  (+ optional oscillations)
Z=MATERNOISE(DT,N,SIGMA,ALPHA,LAMBDA,MU,'extended')
Z=MATERNOISE(DT,N,SIGMA,ALPHA,LAMBDA,MU,NU,'extended')
Composite Matern
Z=MATERNOISE(DT,N,SIGMA,ALPHA,LAMBDA,MU,NU,'composite')
__________________________________________________________________

Real-valued processes

By default MATERNOISE generates a complex-valued process.

X=MATERNOISE(...,'real') instead generates a real-valued Matern
process. This also works with any of extended versions described above.
__________________________________________________________________

Multiple parameter values

The input arguments SIGMA, ALPHA, etc. may all be either scalars, or
arrays of the same length, say K.

Z=MATERNOISE(DT,N,SIGMA,ALPHA,...), with at least one of SIGMA, ALPHA,
etc. being an array of length K, returns a matrix Z that is N x K.

Z=MATERNOISE(DT,[N M],SIGMA,ALPHA,...) then gives Z of size N x M x K.
__________________________________________________________________

Algorithm

MATERNOISE uses a Cholesky matrix decomposition method which makes the
autocovariance matrix of the generated process Z have exactly the form
of a sampled Matern autocovariance function, for nonzero LAMBDA, or of
fractional Brownian motion for LAMBDA=0.

Note that since the Cholesky decomposition requires O(N^3) operations,
generating very long time series (>2000 points or so) may be slow.
__________________________________________________________________

Fast algorithm

MATERNOISE(...,'fast') uses a fast approximate generation algorithm
described in Lilly et al. (2017).  This method works by making use of
the known analytic form for the Matern impulse response function.

In the fast algorithm, oversampling is used to ensure that the
structure of the Green's function is accurately resolved.

[Z,ERR]=MATERNOISE(...,'fast') also returns the fractinal error ERR
involved in the fast algorithm's approximation of the autocovariance
sequence.  This is the total squared error between the actual and
approximated autocovariance sequences, divided by the summed squared
magnitude of the actual autocovariance sequence.  Note that this is for
testing purposes only, as it substantially slows down the algorithm.
__________________________________________________________________

'maternoise --t' runs some tests.
'maternoise --f' generates a sample figure.

Usage: z=maternoise(dt,N,sigma,alpha,lambda);
z=maternoise(dt,N,sigma,alpha,lambda,'fast');
[z,err]=maternoise(dt,N,sigma,alpha,lambda,'fast');
z=maternoise(dt,[N,M],sigma,alpha,lambda,mu,nu);
z=maternoise(dt,N,A,alpha,0);
__________________________________________________________________
This is part of JLAB --- type 'help jlab' for more information
(C) 2013--2020  A.M. Sykulski and J.M. Lilly
--- type 'help jlab_license' for details
```