Dataclass Primitives#

DRDMannTurb operates with four fundamental data classes that configure the DRD model to be used, physical parameters of the scenario, training data generation, and loss functions. Please refer to this UML diagram to see how these are composed to inform the CalibrationProblem and OnePointSpectraDataGenerator classes.

Neural Network Parameters#

class drdmannturb.NNParameters(nlayers: int = 2, input_size: int = 3, hidden_layer_size: int = 10, hidden_layer_sizes: ~typing.List[int] = <factory>, activations: ~typing.List[~torch.nn.modules.module.Module] = <factory>, output_size: int = 3)[source]#

This class provides a generic and convenient method of storing and passing around values required for the definition of the different neural networks that are implemented in this package; this also offers default values.

Parameters:

nlayers (int) – Number of layers to be used in neural network model
input_size (int) – Size of input spectra vector (typically just 3).
hidden_layer_size (int) – Determines widths of network layers if they are constant.
hidden_layer_sizes (List[int]) – Determines widths of network layers (input-output pairs must match); used for CustomNet
activations (List[torch.Module]) – List of activation functions. The list should have the same length as the number of layers, otherwise the activation functions begin to repeat from the beginning of the list.
output_size (int) – Dimensionality of the output vector (typically 3 for spectra-fitting tasks).

Physical Parameters#

class drdmannturb.PhysicalParameters(L: float, Gamma: float, sigma: float, Uref: float = 10.0, zref: float = 1.0, ustar: float = 1.0, domain: Tensor = tensor([0.1000, 0.1438, 0.2069, 0.2976, 0.4281, 0.6158, 0.8859, 1.2743, 1.8330, 2.6367, 3.7927, 5.4556, 7.8476, 11.2884, 16.2378, 23.3572, 33.5982, 48.3293, 69.5193, 100.0000], device='cpu'))[source]#

This class provides a convenient method of storing and passing around the physical parameters required to define a problem; this also offers generic default values.

Parameters:

L (float) – Characteristic length scale of the problem; 0.59 for Kaimal
Gamma (float) – Characteristic time scale of the problem; 3.9 for Kaimal
sigma (float) – Spectrum amplitude; 3.2 for Kaimal
Uref (float, optional) – Reference velocity value at hub height (m/s)
zref (float, optional) – Reference height value; should be measured at hub height (meters)
domain (torch.Tensor) – \(k_1\) domain over which spectra data are defined.
ustar (float) –

Problem/Training Parameters#

class drdmannturb.ProblemParameters(learning_rate: float = 0.1, tol: float = 0.001, nepochs: int = 10, init_with_noise: bool = False, noise_magnitude: float = 0.001, data_type: DataType = DataType.KAIMAL, eddy_lifetime: EddyLifetimeType = EddyLifetimeType.CUSTOMMLP, power_spectra: PowerSpectraType = PowerSpectraType.RDT, wolfe_iter_count: int = 20, learn_nu: bool = False)[source]#

This class provides a convenient method of storing and passing around generic numerical parameters; this also offers default values

Parameters:

learning_rate (float) – Initial earning rate for optimizer.
tol (float) – Tolerance for solution error (training terminates if this is reached before the maximum number of epochs allowed)
nepochs (int) – Number of epochs to train for
init_with_noise (bool) – Whether or not to initialize learnable parameters with random noise; by default, neural network parameters are initialized with the Kaiming initialization while physical parameters are initialized with 0.
noise_magnitude (float) – Magnitude of aforementioned noise contribution
data_type (DataType) – Type of spectra data used. These can be generated from the Kaimal spectra, provided raw as CUSTOM data, interpolated, filtered with AUTO, or use the Von Karman model.
eddy_lifetime (EddyLifetimeType) – Type of model to use for eddy lifetime function. This determines whether a neural network is to be used to learn to approximate the function, or if a known model, such as the Mann eddy lifetime is to be used.
power_spectra (PowerSpectraType) – Type of model to use for power spectra
wolfe_iter_count (int) – Sets the number of Wolfe iterations that each step of LBFGS uses
learn_nu (bool) – If true, learns also the exponent \(\nu\), by default True

Loss Function Parameters#

Also refer to LossAggregator for loss function evaluation from these parameters. The loss function for spectra fitting is determined by the following minimization problem:

\[\min _{\boldsymbol{\theta}}\left\{\operatorname{MSE}[\boldsymbol{\theta}]+\alpha \operatorname{Pen}[\boldsymbol{\theta}]+\beta \operatorname{Reg}\left[\boldsymbol{\theta}_{\mathrm{NN}}\right]\right\}\]

where the loss terms are defined as follows:

\[\operatorname{MSE}[\boldsymbol{\theta}]:=\frac{1}{L} \sum_{i=1}^4 \sum_{j=1}^L\left(\log \left|J_i\left(f_j\right)\right|-\log \left|\widetilde{J}_i\left(f_j, \boldsymbol{\theta}\right)\right|\right)^2,\]

where \(L\) is the number of data points \(f_j \in \mathcal{D}\). The data \(J_i (f_j)\) is evaluated using the Kaimal spectra. The second-order penalization term is defined as

\[\operatorname{Pen}_2[\boldsymbol{\theta}]:=\frac{1}{|\mathcal{D}|} \sum_{i=1}^4\left\|\operatorname{ReLU}\left(\frac{\partial^2 \log \left|\widetilde{J}_i(\cdot, \boldsymbol{\theta})\right|}{\left(\partial \log k_1\right)^2}\right)\right\|_{\mathcal{D}}^2,\]

and the first-order penalization term is defined as

\[\operatorname{Pen}_1[\boldsymbol{\theta}]:=\frac{1}{|\mathcal{D}|} \sum_{i=1}^4\left\|\operatorname{ReLU}\left(\frac{\partial \log \left|\widetilde{J}_i(\cdot, \boldsymbol{\theta})\right|}{\partial \log k_1}\right)\right\|_{\mathcal{D}}^2.\]

Note that the norm \(||\cdot||_{\mathcal{D}}\) is defined as

\[\|g\|_{\mathcal{D}}^2:=\int_{\mathcal{D}}|g(f)|^2 \mathrm{~d}(\log f).\]

The regularization term is defined as

\[\operatorname{Reg}\left[\boldsymbol{\theta}_{\mathrm{NN}}\right]:=\frac{1}{N} \sum_{i=1}^N \theta_{\mathrm{NN}, i}^2.\]

The LossParameters class correspondingly sets the weights of these terms.

class drdmannturb.LossParameters(alpha_pen1: float = 0.0, alpha_pen2: float = 0.0, beta_reg: float = 0.0)[source]#

This class provides a convenient method of storing and passing around the loss function term coefficients; this also offers default values, which result in the loss function consisting purely of an MSE loss.

Note

Using the regularization term \(\beta\) requires a neural network-based approximation to the eddy lifetime function.

Parameters:

alpha_pen1 (float) – Set the first-order penalization term coefficient \(\alpha_1\), by default 0.0
alpha_pen2 (float) – Set the second-order penalization term coefficient \(\alpha_2\), by default 0.0
beta_reg (float) – Set the regularization term coefficient \(\beta\), by default 0.0