pyts.cohereModels package

Submodules

pyts.cohereModels.api module

A central purpose of TurbSim is to produce time-series of velocity that are correlated spatially and in a way that is consistent with observations. In particular, TurbSim produces time-series with specific frequency-dependent correlations between all pairs of points; this is the ‘coherence’.

Loosely defined, coherence is the frequency dependence of the correlation between velocity signals at different points in space. Specically, for two signals u1 and u2 (e.g. velocity signals at points z1,y1 and z2,y2), the coherence is defined as:

\[Coh_{u1,u2} = \frac{|C_{u1,u2}|^2}{S_{u1}S_{u2}}\]

Where \(C_{u1,u2}\) is the cross-spectral density between signals u1 and u2, and \(S_{u1}\) is the auto-spectral density of signal u1 (similar for \(S_{u2}\)).

This module provides ‘coherence models’ which are specific spatial coherence forms (functions of frequency) for each component of velocity for all pairs of points in the grid.

Available coherence models

main.iec (alias: iec)

The IEC spatial coherence model

main.nwtc (alias: nwtc)

The NWTC ‘non-IEC’ coherence model.

main.none (alias: none)

A ‘no coherence’ model.

cohereModelBase

This is the base class for coherence models. To create a new one, subclass this class or subclass and modify an existing coherence model.

cohereObj

This is the ‘coherence object’ class. All coherence model __call__ methods must take a tsrun as input and return this class.

Further details on creating your own coherence model, can be found in pyts.cohereModels.base documentation.

pyts.cohereModels.base module

This is the coherence package’s base module.

The coherence models work somewhat different than other packages. In particular, rather than storing the full coherence matrix in an array, pieces of that matrix are compute as needed at runtime. This is because that array can be very large for large number of grid points and timesteps (np^2 x nf).

Because of this, when creating new coherence ‘models’, the cohereModel and cohereObj must be defined. While it would be possible to merge these classes, they have been kept separate to maintain the PyTurbSim ‘model’ vs. ‘object’ framework. That is: a ‘model’ defines the coherence independent of the grid, while the ‘object’ is specific to the grid.

class pyts.cohereModels.base.cohereModelBase

Bases: pyts.base.modelBase, pyts.base.gridProps

Examples

When a coherence model class is called, it returns a ‘coherence model instance’ (as expected) e.g. cm = myCohereModel(inarg1,inarg2,…)

A ‘coherence model instance’ is an instance of a specific coherence model that is independent of a turbsim run (i.e. the coherence model instance holds parameters that are specific the grid, mean profile model, or spectral model).

When a ‘coherence model instance’ is called, it returns a ‘coherence object’ instance, e.g. coh=cm(tsr)

Where tsr is a ‘tsrun’ object.

__call__(tsrun)

Calculate the coherence matrix for TurbSim run tsrun according to this coherence model. The grid, profile and spectrum (tsrun.grid, tsrun.prof, tsrun.spec) must already be defined for the tsrun.

Parameters:

tsrun - A ‘TurbSim run’ object that contains the grid, prof and spec

attributes.

Returns:

A coherence instance (array or ‘calculator’), e.g.

cohi=thisCohereModel(tsrun)

The coherence instance is either an array of the full

cross-spectral matrix (3 x n_p x n_p x n_f), or a ‘calculator’

that returns the components of that array. Either way, the

components of the cross-spectral matrix (csm) can be obtained

from

csm_u=cohi[0]

csm_v=cohi[1]

csm_w=cohi[2]

class cohereObj(tsrun)

Bases: pyts.base.gridProps, pyts.base.calcObj

This ‘cohereObj’ class operate somewhat differently than ‘xxxObj’s in other packages (profObj,specObj,stressObj). In particular, cohereObj does not store the ‘array’ of coherence internally by default because that array is extremely large (np x np x nf). Instead, cohereObj’s compute the coherence for specific points as needed.

It is possible to compute the full array of coherence, by accessing this objects ‘array’ property. This recursively calls the functions for computing the coherence and returns the result. However, be warned that for PyTurbSim runs involving large numbers of grid-points and time-steps, this will utilize large amounts of memory.

Parameters:

tsrun : tsrun type

The PyTurbSim run object in which the coherence will be used.

array

This property computes and returns the full coherence array.

This array utilizes significant memory (3 x np x np x nf) and should be avoided unless needed. By default PyTurbSim avoids holding the entire array in memory and instead computes small pieces of it as needed.

Avoid accessing this property on PyTurbSim runs involving many grid-points or timesteps.

calcCoh(f, comp, ii, jj)

THIS IS A PLACEHOLDER METHOD WHICH SHOULD BE OVER-WRITTEN FOR ALL SUB-CLASSES OF cohereModelBase. THIS METHOD ONLY RAISES AN ERROR.

A functioning version of this method (i.e. in a subclass of cohereModelBase) should return the a length-n_f vector that is the coherence between point ii`=(iz,iy) and `jj`=(jz,jy) for velocity component `comp.

Parameters:

cohi : A ‘coherence calculator’ instance (for the given tsrun).

comp : an integer (0,1,2) indicating the velocity component

for which to compute the coherence.

ii,jj : Two-integer elements indicating the grid-points

between which to calculate the coherence. For example, ii=(1,3),jj=(2,3)

calc_phases(phases)

Compute the correlated phases for each grid-point from the input phases based on the coherence function of this coherence object.

Parameters:

phases : array_like(np,nf)

The input (generally randomized) phases for each point for each frequency.

Returns:

phases : array_like(np,nf)

The correlated phases according to this cohereObj’s coherence model (see calcCoh()).

See also

calcCoh

computes the coherence for individual grid-point pairs.

Notes

This method should not be called explicitly. It is called by a cohereObj instance’s __call__ method.

This routine utilizes a model’s ‘calcCoh’ method, which must be defined explicitly for all sub-classes of this class.

class pyts.cohereModels.base.cohereObj(tsrun)

Bases: pyts.base.gridProps, pyts.base.calcObj

This ‘cohereObj’ class operate somewhat differently than ‘xxxObj’s in other packages (profObj,specObj,stressObj). In particular, cohereObj does not store the ‘array’ of coherence internally by default because that array is extremely large (np x np x nf). Instead, cohereObj’s compute the coherence for specific points as needed.

It is possible to compute the full array of coherence, by accessing this objects ‘array’ property. This recursively calls the functions for computing the coherence and returns the result. However, be warned that for PyTurbSim runs involving large numbers of grid-points and time-steps, this will utilize large amounts of memory.

Parameters:

tsrun : tsrun type

The PyTurbSim run object in which the coherence will be used.

array

This property computes and returns the full coherence array.

This array utilizes significant memory (3 x np x np x nf) and should be avoided unless needed. By default PyTurbSim avoids holding the entire array in memory and instead computes small pieces of it as needed.

Avoid accessing this property on PyTurbSim runs involving many grid-points or timesteps.

calcCoh(f, comp, ii, jj)

THIS IS A PLACEHOLDER METHOD WHICH SHOULD BE OVER-WRITTEN FOR ALL SUB-CLASSES OF cohereModelBase. THIS METHOD ONLY RAISES AN ERROR.

A functioning version of this method (i.e. in a subclass of cohereModelBase) should return the a length-n_f vector that is the coherence between point ii`=(iz,iy) and `jj`=(jz,jy) for velocity component `comp.

Parameters:

cohi : A ‘coherence calculator’ instance (for the given tsrun).

comp : an integer (0,1,2) indicating the velocity component

for which to compute the coherence.

ii,jj : Two-integer elements indicating the grid-points

between which to calculate the coherence. For example, ii=(1,3),jj=(2,3)

calc_phases(phases)

Compute the correlated phases for each grid-point from the input phases based on the coherence function of this coherence object.

Parameters:

phases : array_like(np,nf)

The input (generally randomized) phases for each point for each frequency.

Returns:

phases : array_like(np,nf)

The correlated phases according to this cohereObj’s coherence model (see calcCoh()).

See also

calcCoh

computes the coherence for individual grid-point pairs.

Notes

This method should not be called explicitly. It is called by a cohereObj instance’s __call__ method.

This routine utilizes a model’s ‘calcCoh’ method, which must be defined explicitly for all sub-classes of this class.

class pyts.cohereModels.base.cohereUser(array)

Bases: pyts.cohereModels.base.cohereObj

Specify the coherence explicitly as an array.

The array must have the dimensions 3 x np x np x nf, where np is the number of points in the grid, and nf is the number of frequencies for the inverse fft. The dimensions of the array are,

0. velocity component (u,v,w)
1. first spatial point,
2. second spatial point,
3. frequency.

The ordering of the spatial points (dims 1,2) must match the ordering of the TurbSim grid. See the tsGrid classes ‘sub2ind’, ‘ind2sub’, ‘flatten’ and ‘reshape’ methods for more details on this.

calc_phases(phases)

Compute and set the full cross-spectral matrix for component comp for ‘coherence calculator’ instance cohi.

This method should not be called explicitly. It is called by a ‘coherence calculator’ instance’s __call__ method.

This routine utilizes a model’s ‘calcCoh’ method, which must be defined explicitly for all sub-classes of cohereModelBase.

pyts.cohereModels.main module

This module defines two coherence models: nwtc - The NWTC ‘non-IEC’ coherence model. iec - The IEC coherence model.

class pyts.cohereModels.main.cohereObjIEC(tsrun)

Bases: pyts.cohereModels.base.cohereObj

calcCoh(f, comp, ii, jj)

Calculate the coherence for a velocity component, between two points.

Parameters:

f : array_like(nf,dtype=float)

comp : int {0,1,2}

indicating the velocity component for which to compute the coherence.

ii,jj : array_like(int,2)

indicating the grid-points between which to calculate the coherence. for example: ii=(1,3),jj=(2,3)

Returns:

coh : array_like(nf,dtype=float)

The coherence between the two points as a function of frequency.

Notes

This method is only used if tslib is not available.

calc_phases(phases)

Compute and set the full cross-coherence matrix for component comp for ‘coherence calculator’ instance cohi.

Compute the coherence array for coherence instance cohi for the IEC model.

class pyts.cohereModels.main.cohereObjNWTC(tsrun)

Bases: pyts.cohereModels.base.cohereObj

calcCoh(f, comp, ii, jj)

The base function for calculating coherence for non-IEC spectral models.

See the TurbSim documentation for further information.

This function is only used if the TSlib fortran library is not available.

calc_phases(phases)

Compute the correlated phases for each grid-point from the input phases based on the coherence NWTC ‘non-IEC coherence model.

Parameters:

phases : array_like(np, nf)

The input (generally randomized) phases for each point for each frequency.

Returns:

phases : array_like(np, nf)

The correlated phases according to this cohereObj’s coherence model (see calcCoh()).

See also

calcCoh

computes the coherence for individual grid-point pairs.

Notes

This method should not be called explicitly. It is called by a cohereObj instance’s __call__ method.

class pyts.cohereModels.main.cohereObjNone(tsrun)

Bases: pyts.cohereModels.base.cohereObj

This is a ‘dummy’ coherence object that forces the coherence to zero.

calcCoh(f, comp, ii, jj)

calc_phases(phases)

class pyts.cohereModels.main.iec(IECedition=3)

Bases: pyts.cohereModels.base.cohereModelBase

IEC coherence model.

This coherence model only include u-component coherence.

Parameters:

IECedition : int {2, 3},

Different IEC editions have slightly different coefficients to the spectral model.

Notes

The IEC coherence is zero for the v- and w-components (coherence matrix is the identity matrix so that auto-spectra are retained).

The form of this model is for the u-component is,

\[Coh=exp(-a*((f*r/uhub)^2+(0.12*r/Lc)^2)^0.5)\]

Where,

f is frequency.

r is the distance between the two points.

uhub is the hub-height mean velocity.

If IECedition<=2: a = 8.8, Lc = 2.45*min(30m,HubHt)

If IECedition>=3: a = 12, Lc = 5.67*min(60m,HubHt)

Examples

When a coherence model class is called, it returns a ‘coherence model instance’ (as expected) e.g. cm = myCohereModel(inarg1,inarg2,…)

A ‘coherence model instance’ is an instance of a specific coherence model that is independent of a turbsim run (i.e. the coherence model instance holds parameters that are specific the grid, mean profile model, or spectral model).

When a ‘coherence model instance’ is called, it returns a ‘coherence object’ instance, e.g. coh=cm(tsr)

Where tsr is a ‘tsrun’ object.

cohereObj

alias of cohereObjIEC

set_coefs(cohereObj)

Initialize a coherence instance for the IEC coherence model.

class pyts.cohereModels.main.none

Bases: pyts.cohereModels.base.cohereModelBase

This is a ‘dummy’ coherence model that forces the coherence to zero.

cohereObj

alias of cohereObjNone

class pyts.cohereModels.main.nwtc(a=[None, None, None], b=[0.0, 0.0, 0.0], CohExp=0.0)

Bases: pyts.cohereModels.base.cohereModelBase

NWTC coherence model.

This is also known as the ‘non-IEC’ coherence model.

Parameters:

a : array_like(3)

The ‘a’ exponential ‘coherence decrement’ coefficients of the coherence function for each velocity component.

b : a

The ‘b’ exponential ‘coherence decrement’ coefficients of the coherence function for each velocity component.

CohExp : float

The ‘Coherence Exponent’ parameter for the coherence function.

Notes

The NWTC ‘non-IEC’ coherence model for velocity component ‘k’ between two points (z_i,y_i) and (z_j,y_j) is

\[Coh_k=exp(-a_k (r/z_m)^CohExp ((f r / u_m)^2 + (b_k r)^2) k=u,v,w\]

Where,

f is frequency.

r is the distance between the two points.

a_k and b_k are ‘coherence decrement’ input parameters for each of the velocity components.

u_m is the average velocity of the two points.

z_m is the average height of the two points.

CohExp is the ‘coherence exponent’ input parameter (default is 0).

Examples

When a coherence model class is called, it returns a ‘coherence model instance’ (as expected) e.g. cm = myCohereModel(inarg1,inarg2,…)

A ‘coherence model instance’ is an instance of a specific coherence model that is independent of a turbsim run (i.e. the coherence model instance holds parameters that are specific the grid, mean profile model, or spectral model).

When a ‘coherence model instance’ is called, it returns a ‘coherence object’ instance, e.g. coh=cm(tsr)

Where tsr is a ‘tsrun’ object.

cohereObj

alias of cohereObjNWTC

set_coefs(cohereObj)

This method is called by the coherence model __call__ method just before returning the coherence instance cohi.

Module contents

This is the PyTurbSim ‘coherence models’ package.

For more information or to use this module import the cohereModels.api package, e.g.: import pyts.cohereModels.api as cm