pyts package¶

Subpackages¶

Submodules¶

pyts.api module¶

This is the PyTurbSim python advanced programming interface (API). This module provides a fully-customizable high-level object-oriented interface to the PyTurbSim program.

The four components of this API are:

1) The tsrun class, which is the controller/run object for PyTurbSim simulations.

2) The tsGrid class, which is used to define the TurbSim grid.

The ‘model’ classes, which include:

a) profModels (aliased here as ‘pm’), contains the mean velocity profile models.

b) specModels (aliased here as ‘sm’), contains the TKE spectral models.

c) stressModels (aliased here as ‘rm’), contains the Reynold’s stress profile models.

d) cohereModels (aliased here as ‘cm’), contains the spatial coherence models.

4) The io module, which supports reading and writing of TurbSim input (.inp) and output files (e.g. .bl, .wnd, etc.)

Example usage of this API can be found in the <pyts_root>/Examples/api.py file.

"""
This script provides an example usage of the PyTurbSim API.
"""
# Begin by importing the PyTurbSim API:
import pyts.api as pyts

# Define some variables for the PyTurbSim run:
refht = 10.
ustar = 0.03
Uref = 3.

# First we initialize a PyTurbSim 'run' object:
tsr = pyts.tsrun()

# Next we give this run object a grid:
tsr.grid = pyts.tsGrid(
    center=refht, ny=5, nz=5, height=5, width=9, time_sec=1000, dt=0.5)

# Now we define a mean 'profile model',
prof_model = pyts.profModels.h2l(Uref, refht, ustar)
# and assign it to the run object,
tsr.prof = prof_model
# These two steps can be completed in one as:
#tsr.profModel=pyts.profModels.h2l(U,refht,ustar)

# Next we define and assign a 'spectral model' to the run object,
tsr.spec = pyts.specModels.tidal(ustar, refht)

# ... and define/assign a 'coherence model',
tsr.cohere = pyts.cohereModels.nwtc()

# ... and define/assign a 'stress model',
tsr.stress = pyts.stressModels.tidal(ustar, refht)

# Now simply 'call' the run oject to produce the TurbSim output.
turbsim_output = tsr()

# We can save the output in 'bladed' format,
turbsim_output.writeBladed('ExampleOutput.bl')

pyts.base module¶

This is the ‘base’ module for the PyTurbSim program.

This module:

imports common numpy functions/methods (from pyts_numpy.py),

defines the gridObj class (and the tsGrid() helper function),

imports the tslib Fortran module (if it is available) and

Defines several abstract base classes.

class pyts.base.calcObj[source]¶

Bases: pyts.base.tsBaseObj

This is a base class for objects that are have .array properties. It creates a shortcut for accessing the array through the getitem method.

This is used in each of the model packages as a base-class for the output ‘statistics’ of that class. In other words: profObj, specObj, stressObj, and cohereObj all derive from this class.

class pyts.base.gridObj[source]¶

Bases: pyts.base.tsBaseObj

The base ‘grid’ class.

In general, functions should be used to construct the grid.

Notes

The grid is defined so that the first row is the bottom and the last is the top.
Irregular grids are not yet supported.

center¶

clockwise = True¶

df¶

dist(ii, jj)[source]¶

Compute the distance between the points ii and jj.

Parameters:

ii : Index of first grid-point.

jj : Index of second grid-point.

Returns:

r : The distance between the two grid points.

Notes

Each input index can either be a grid-point pair (e.g. a tuple, indicating the grid-point, or a linear index such as would be returned by sub2ind).

dy¶

dz¶

flatten(arr)[source]¶: Reshape arr so that the z-y grid points are one-dimension of the array (e.g. prior to Cholesky factorization).

height¶

ihub¶

ind2sub(ind)[source]¶: Return the subscripts (iz,iy) corresponding to the ‘flattened’ index ind (row/C-order) for this grid.

n_f¶

n_p¶

n_tower = 0¶

n_y¶

n_z¶

reshape(arr)[source]¶: Reshape arr so that its z-y grid points are two-dimensions of the array.

rotor_diam¶

Return the min of the grid width and height.

This is how TurbSim quantifies rotor diameter.

shape¶: The grid shape: (n_z, n_y).

shape_wf¶: The grid shape, including frequency (n_z, n_y, n_f).

sub2ind(subs)[source]¶: Return the ‘flattened’ index (row/C-order) corresponding to the subscript subs (iz,iy) for this grid.

time_sec_out¶

width¶

zhub¶: The height of the hub.

class pyts.base.gridProps[source]¶

Bases: pyts.base.tsBaseObj

An abstract base class that provides shortcuts for objects that have the grid as one of their attributes.

dt¶

f¶

n_f¶

n_p¶

n_y¶

n_z¶

y¶

z¶

class pyts.base.modelBase[source]¶

Bases: pyts.base.tsBaseObj

An abstract base class for all TurbSim models.

model_desc¶: The model description is the first line of the docstring.

model_name¶: The model name is the class definition name

parameters¶

This property stores information about the TurbSim model initialization variables, for writing to summary files.

This functionality is not yet implemented, and this is a placeholder for now.

class pyts.base.statObj(dat, ubar=None)[source]¶

Bases: float

mean¶

class pyts.base.tsBaseObj[source]¶

Bases: object

An abstract, base object, that contains the component (u,v,w) information for derived classes.

comp = [0, 1, 2]¶

comp_name = ['u', 'v', 'w']¶

n_comp = 3¶

pyts.base.tsGrid(center=None, ny=None, nz=None, width=None, height=None, dy=None, dz=None, nt=None, time_sec=None, time_min=None, dt=None, time_sec_out=None, findClose_nt_lowPrimeFactors=True, prime_max=31, clockwise=True)[source]¶

Create a TurbSim grid.

Parameters:

center : float

height of the center of the grid.

ny, nz : int, optional*

number of points in the y and z directions.

width,height : float, optional*

total width and height of grid.

dy, dz : float, optional*

spacing between points in the y and z directions.

nt : int, optional*

number of timesteps

time_sec : float, optional*

length of run (seconds)

time_min : float, optional*

length of run (minutes, subordinate to time_sec)

dt : float, optional*

timestep (seconds, subordinate to nt and time_sec)

time_sec_out : float, optional (time_sec)

length of output timeseries in seconds, must be >=`time_sec`

findClose_nt_lowPrimeFactors : bool, optional (True)

Adjust nfft to be a multiple of low primes?

prime_max : int, optional (31)

The maximum prime number allowed as a ‘low prime’.

clockwise : bool, optional (True)

Should the simulation write a ‘clockwise’ rotation output file. This is only used when writing ‘Bladed’ output files.

Notes

Each grid dimension (z,y,time) can be specified by any combination of 2 inputs. For the y-grid, for example, you may specify: dy and ny, or width and dy, or width and ny. If all three are specified, dy ignored and computed from ny and width.

pyts.dbg module¶

This is the PyTurbSim debug package. It contains debugging tools specifically valuable to PyTurbSim.

class pyts.dbg.timer(label='NONE')[source]¶

Bases: object

A timer class for tracking ‘real’ time (rather than CPU time).

reset()[source]¶

start()[source]¶

stop()[source]¶

pyts.main module¶

This module brings together the main components of the TurbSim program and defines the primary high-level objects that users of the Python interface will utilize.

This module, however, contains more functions and objects than the typical user will want access to. For a more compact version of the PyTurbSim interface import the ./api.py package.

class pyts.main.tsdata(grid)[source]¶

Bases: pyts.base.gridProps

TurbSim output data object. In addition to the output of a simulation (velocity timeseries array) it also includes all information for reproducing the simulation.

Parameters:

grid : gridObj

TurbSim data objects are initialized with a TurbSim grid.

Ti¶: The turbulence intensity, std(u’)/U, at each point in the grid.

UHUB¶: The hub-height mean velocity.

ctke¶

ihub¶: The index of the hub.

parameters¶

shape¶: The shape of the turbulence time-series (output) array.

stats¶

Compute and return relevant statistics for this turbsim time-series.

Returns:

stats : dict

A dictionary containing various statistics of interest.

stress¶: The Reynold’s stress tensor.

time¶: The time vector, in seconds, starting at zero.

tke¶: The turbulence kinetic energy.

u¶: The total (mean + turbulent), u-component of velocity.

uhub¶: The hub-height u-component time-series.

upvp_¶: The u’v’ component of the Reynold’s stress.

upwp_¶: The u’w’ component of the Reynold’s stress.

utotal¶: The total (mean + turbulent), 3-d velocity array

v¶: The total (mean + turbulent), v-component of velocity.

vhub¶: The hub-height v-component time-series.

vpwp_¶: The v’w’ component of the Reynold’s stress.

w¶: The total (mean + turbulent), w-component of velocity.

whub¶: The hub-height w-component time-series.

write_bladed(filename)[source]¶

Save the data in this tsdata object in ‘bladed’ format (.wnd).

Parameters:

filename : str

The filename to which the data should be written.

write_formatted(filename)[source]¶

Save the data in this tsdata object in ‘formatted’ format (.u, .v, .w files).

Parameters:

filename : string

‘.u’, ‘.v’, and ‘.w’ will be appended to the end of the filename.

write_sum(filename)[source]¶: Currently PyTurbSim does not support writing summary (.sum) files.

write_turbsim(filename)[source]¶

Save the data in this tsdata object in ‘TurbSim’ format.

Parameters:

filename : str

The filename to which the data should be written.

class pyts.main.tsrun(RandSeed=None, ncore=1)[source]¶

Bases: object

This is the PyTurbSim ‘run’ class. This class provides the interface for controlling PyTurbSim simulations and output.

Examples of how to use this class, and the PyTurbSim interface in general can be found in the PyTurbSim /examples directory.

Parameters:

RandSeed : int,optional (‘random value’)

Initialize the run-object with a RandSeed.

ncore : int,optional (1)

Number of cores (processors) to use for the pyTurbSim run

__call__()¶

Run PyTurbSim.

Before calling this method be sure to set the following attributes to their desired values:

tsrun.prof: The mean profile model, object or array.
tsrun.spec: The tke spectrum model, object or array.
tsrun.cohere: The coherence model, object or array.
tsrun.stress: The Reynold’s stress model, object or array.

Returns:	tsdata : `tsdata`

cohere¶

This is the ‘coherence’ input property.

This property always returns a cohereObj.

Because the bulk of PyTurbSim’s computational requirements (memory and processor time) are consumed by dealing with this statistic, it behaves somewhat differently from the others. In particular, rather than relying on arrays for holding data ‘coherence objects’ define functions that are called as needed. This dramatically reduces the memory requirements of PyTurbSim without increasing. See the cohereModels package documentation for further details. Fortunately, at this level, coherence is specified identically to other statistics…

This property can be defined with three types of objects:

define it with a ‘coherence model’ (recommended):
```
ts_run.cohere=a_coherence_model
```
In this case the model is set to my_ts_run.cohereModel, and this model sets the is called at runtime to produce the phase array. At the end of the ts_run call that phase array is cleared so that subsequent runs do not use a fixed phase information (i.e. in the case that the coherence model is modified or another model/object that the coherence model depends on is changed between runs).
define it with a cohereObj directly
```
ts_run.spec=a_coherence_model(ts_run)
```
In this case the cohereObj is FIXED. That is, all subsequent PyTurbSim runs will utilize this coherence model, which is based on the state of ts_run at the time of execution of this command.
define it with an array directly:
```
ts_run.cohere=a_numpy_array  - [units: non-dimensional]
```
In this case the coherence will be fixed and defined by this input array. The numpy array dimensions must match those of the gridObj. That is, the dimensions of the array should be (3 x grid.n_p x grid.n_p x grid.n_f). The first dimension is for each component of the spectrum (u,v,w), the next two are for each point-pair (z,y) in the grid, and the last dimension is the frequency dependence of the spectrum.

This approach for specifying the coherence - while explicit and flexible - requires considerably more memory than the ‘coherence model’ approach. Furthermore using this approach one must be careful to make sure that the ordering of the array agrees with that of the ‘flattened grid’ (see the gridObj.flatten method, and/or the cohereUser coherence model for more information).

See also

pyts.cohereModels.api: to see a list of available coherence models.
pyts.cohereModels.base.cohereUser: the ‘user-defined’ or ‘array-input’ coherence model.

tsrun.prof, tsrun.spec, tsrun.stress

info¶: Model names and initialization parameters.

phase = <pyts.phaseModels.main.randPhase object>¶

prof¶

This is the ‘mean velocity profile’ input property.

This property returns a ‘profObj’.

This property can be defined with three types of objects:

define it with a ‘profile model’ (recommended):
```
ts_run.prof=a_prof_model
```
In this case the model is set to my_ts_run.profModel, and this model is called to produce a profObj AS NEEDED. At the end of the ts_run call that profObj is cleared so that subsequent runs do not use a fixed profObj (i.e. in the case that the model is modified or another model/object that the profile model depends on is changed between runs).
define it with a profObj directly (profile statistic-object):
```
ts_run.prof=a_prof_model(ts_run)
```
In this case the profObj is FIXED. That is, all subsequent PyTurbSim runs will utilize this profile, which is based on the state of the a_prof_model and ts_run at the time of the profObj creation.
define it with an array directly:
```
ts_run.prof=a_numpy_array   [units: m/s]
```
In this case the profObj is again fixed and defined by the input array. The numpy array dimensions must match those of the gridObj. That is, the dimensions of the array should be (3 x grid.n_z x grid.n_y). The first dimension is for each component of the profile (u,v,w), the next two are for each point (z,y) in the grid.

See also

pyts.profModels.api: to see available profile models.

tsrun.spec, tsrun.cohere, tsrun.stress

reset(seed=None)[source]¶: Clear the input statistics and reset the Random Number generator to its initial state.

run()[source]¶

Run PyTurbSim.

Before calling this method be sure to set the following attributes to their desired values:

tsrun.prof: The mean profile model, object or array.
tsrun.spec: The tke spectrum model, object or array.
tsrun.cohere: The coherence model, object or array.
tsrun.stress: The Reynold’s stress model, object or array.

Returns:	tsdata : `tsdata`

spec¶

This is the ‘tke spectrum’ input property.

This property always returns a .specObj.

This property can be defined with three types of objects:

define it with a ‘spectral model’ (recommended):
```
ts_run.spec=a_spec_model
```
In this case the model is set to my_ts_run.specModel, and this model is called to produce a specObj AS NEEDED. At the end of the ts_run call that specObj is cleared so that subsequent runs do not use a fixed specObj (i.e. in the case that another model/object that the spectral model depends on is changed between runs).
define it with a specObj directly:
```
ts_run.spec=a_spec_model(ts_run)
```
In this case the specObj is FIXED. That is, all subsequent PyTurbSim runs will utilize this spectral model, which is based on the state of ts_run at the time of the specObj creation.
define it with an array directly:
```
ts_run.spec=a_numpy_array  - [units: m^2/(s^2.Hz)]
```
In this case the specObj is again fixed and defined by the input array. The numpy array dimensions must match those of the gridObj. That is, the dimensions of the array should be (3 x grid.n_z x grid.n_y x grid.n_f). The first dimension is for each component of the spectrum (u,v,w), the next two are for each point (z,y) in the grid, and the last dimension is the frequency dependence of the spectrum.

See also

pyts.specModels.api: to see available spectral models.

tsrun.prof, tsrun.cohere, tsrun.stress

stress¶

This is the Reynold’s stress input property.

This property always returns a stressObj.

This property can be defined with three types of objects:

define it with a specModel (recommended):
```
ts_run.stress=a_stress_model
```
In this case the model is set to my_ts_run.stressModel, and this model is called to produce a stressObj AS NEEDED. At the end of the ts_run call that stressObj is cleared so that subsequent runs do not use a fixed stressObj (i.e. in the case that another model/object that the stress model depends on is changed between runs).
define it with a stressObj directly:
```
ts_run.stress=a_stress_model(ts_run)
```
In this case the stressObj is FIXED. That is, all subsequent PyTurbSim runs will utilize this stress model, which is based on the state of ts_run at the time of the stressObj creation.
define it with an array directly:
```
ts_run.stress=a_numpy_array  - [units: m^2/s^2]
```
In this case the stressObj is again fixed and defined by the input array. The numpy array dimensions must match those of the gridObj. That is, the dimensions of the array should be (3 x grid.n_z x grid.n_y). The first dimension is for each component of the stress (u,v,w), the next two are for each point (z,y) in the grid.

See also

pyts.stressModels.api: To see available stress models.

tsrun.prof, tsrun.spec, tsrun.cohere

pyts.misc module¶

This module contains a few random helper functions that are used throughout the code.

exception pyts.misc.InvalidConfig(msg='Invalid option specified in config file.')[source]¶

Bases: exceptions.Exception

Exception raised by the baseModel classes. Used to indicate that a model has not defined a necessary attribute.

pyts.misc.Lambda(zhub, IECedition)[source]¶

Calculate the IEC length scale.

Lambda = 0.7*min(Zhat,zhub)

Where: Zhat = 30,60 for IECedition = 2,3, respectively.

pyts.misc.fix2range(vals, minval, maxval)[source]¶

A helper function that sets the value of the array or number vals to fall within the range minval <= vals <= maxval.

Values of vals that are greater than maxval are set to maxval (and similar for minval).

Parameters:

vals : float or array_like

The value(s) to ‘fix’.

minval : float

The minimum value.

maxval : float

The maximum value.

Returns:

fixed_vals : float or array_like (matches vals)

The fixed values.

pyts.misc.lowPrimeFact_near(n, pmax=31, nmin=None, evens_only=True)[source]¶

Find the nearest integer to n with prime factors all less than pmax.

This routine is used to change the length of arrays to speed-up Fast Fourier Transforms.

Parameters:

n : int

The starting integer.

pmax : int

The maximum prime to be found.

Returns:

qp_near : int

The nearest integer to n that has prime factors less than pmax.

pyts.misc.pfactor(n, pmax=31)[source]¶

Calculate the prime factors of the integer n.

Parameters:

n : The integer for which to calculate prime-factors.

pmax : The maximum prime to use (default 31, can be up to 71).

Returns:

primes : list

A of the primes.

The first 20 primes (up to 71) are hard-coded into this

routine. You’ll need to add more primes to the list if you want

them.

pyts.misc.psiM(Ri, TurbModel=None)[source]¶

The psi_M stability parameter is used for various mean wind-speed profiles and turbulence models.

Parameters:

Ri : float

The Richardson number.

TurbModel : str

The turbulence model that is being used (optional). In some cases z/L depends on the Turbulence model.

Returns:

psiM : float

The psi_M stability parameter.

pyts.misc.zL(Ri, TurbModel=None)[source]¶

zL is the Monin-Obhukov (M-O) stability parameter z/L, where L is the M-O length.

zL > 0 means stable conditions.

Parameters:

Ri : float

The Richardson number.

TurbModel : str

The turbulence model that is being used (optional). In some cases z/L depends on the Turbulence model.

pyts.pyts_numpy module¶

This module imports the pieces of numpy that are used by PyTurbSim.

Module contents¶

This is the PyTurbSim package. For more information visit the PyTurbSim home page.

pyts package¶

Subpackages¶

Submodules¶

pyts.api module¶

pyts.base module¶

pyts.dbg module¶

pyts.main module¶

pyts.misc module¶

pyts.pyts_numpy module¶

Module contents¶

Table Of Contents

Related Topics

This Page