.. _variables-lognormal_uncertain:

"""""""""""""""""""
lognormal_uncertain
"""""""""""""""""""


Aleatory uncertain variable - lognormal




**Topics**


continuous_variables, aleatory_uncertain_variables



.. toctree::
   :hidden:
   :maxdepth: 1

   variables-lognormal_uncertain-lambdas
   variables-lognormal_uncertain-means
   variables-lognormal_uncertain-lower_bounds
   variables-lognormal_uncertain-upper_bounds
   variables-lognormal_uncertain-initial_point
   variables-lognormal_uncertain-descriptors


**Specification**

- *Alias:* None

- *Arguments:* INTEGER

- *Default:* no lognormal uncertain variables


**Child Keywords:**

+-------------------------+--------------------+--------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                    |
|                         | Group              |                    |                                               |
+=========================+====================+====================+===============================================+
| Required (Choose One)   | Lognormal          | `lambdas`__        | First parameter of the lognormal distribution |
|                         | Characterization   |                    | (option 3)                                    |
|                         |                    +--------------------+-----------------------------------------------+
|                         |                    | `means`__          | First parameter of the lognormal distribution |
|                         |                    |                    | (options 1 & 2)                               |
+-------------------------+--------------------+--------------------+-----------------------------------------------+
| Optional                                     | `lower_bounds`__   | Specify minimum values                        |
+----------------------------------------------+--------------------+-----------------------------------------------+
| Optional                                     | `upper_bounds`__   | Specify maximium values                       |
+----------------------------------------------+--------------------+-----------------------------------------------+
| Optional                                     | `initial_point`__  | Initial values for variables                  |
+----------------------------------------------+--------------------+-----------------------------------------------+
| Optional                                     | `descriptors`__    | Labels for the variables                      |
+----------------------------------------------+--------------------+-----------------------------------------------+

.. __: variables-lognormal_uncertain-lambdas.html
__ variables-lognormal_uncertain-means.html
__ variables-lognormal_uncertain-lower_bounds.html
__ variables-lognormal_uncertain-upper_bounds.html
__ variables-lognormal_uncertain-initial_point.html
__ variables-lognormal_uncertain-descriptors.html



**Description**


If the logarithm of an uncertain variable X has a normal distribution,
that is :math:`\log X \sim \mathcal{N}(\mu,\sigma^2)` , then :math:`X` is
distributed with a lognormal distribution.  The lognormal is often
used to model:

- time to perform some task
- variables which are the product of a large number of other quantities, by the Central Limit Theorem
- quantities which cannot have negative values.

The number of lognormal uncertain variables, their means, and either
standard deviations or error factors must be specified, while the
distribution lower and upper bounds and variable descriptors are
optional specifications. These distribution bounds can be used to
truncate the tails of lognormal distributions, which as for bounded
normal, can result in the mean and the standard deviation of the
sample data being different from the mean and standard deviation of
the underlying distribution (see "bounded lognormal" and "bounded
lognormal-n" distribution types in :cite:p:`Wyss1998`).

For the lognormal variables, one may specify either the mean :math:`\mu` and standard deviation :math:`\sigma` 
of the actual lognormal distribution (option 1), the mean :math:`\mu`  and error factor :math:`\epsilon` 
of the actual lognormal distribution (option 2), or the mean :math:`\lambda`  ("lambda") and standard deviation :math:`\zeta`  ("zeta")
of the underlying normal distribution (option 3).

..
   HIDDEN: This approach diverges from that of [\ref Wyss1998 "Wyss and
   Jorgensen, 1998"], which assumes that a specification of mean and
   standard deviation provides parameters of the underlying normal
   distribution, and a specification of mean and error factor provides
   statistics of the actual lognormal distribution.

The conversion equations from lognormal mean :math:`\mu`  and either lognormal error factor :math:`\epsilon` or lognormal standard deviation :math:`\sigma` 
to the mean :math:`\lambda`  and standard deviation :math:`\zeta` of the underlying normal distribution are as follows:

.. math:: \zeta = \frac{\ln(\epsilon)}{1.645}

.. math:: \zeta^2 = \ln\left(\frac{\sigma^2}{\mu^2} + 1\right)

.. math:: \lambda = \ln(\mu) - \frac{\zeta^2}{2}

Conversions from :math:`\lambda`  and :math:`\zeta`  back to :math:`\mu`  and :math:`\epsilon`  or :math:`\sigma`  are as follows:

.. math:: \mu = \exp \left( \lambda + \frac{\zeta^2}{2} \right) 

.. math:: \sigma^2 = \exp \left( 2\lambda + \zeta^2 \right) \left( \exp \left(\zeta^2\right) - 1\right)

.. math:: \epsilon = \exp \left( 1.645\zeta \right) 

The density function for the lognormal distribution is:

.. math::
   f(x) = \frac{1}{\sqrt{2\pi}\zeta x}
   \exp \left( -\frac{1}{2}\left(\frac{\ln(x)-\lambda}{\zeta}\right)^2 \right) 




**Theory**


When used with some methods such as design of experiments and
multidimensional parameter studies, distribution bounds are inferred
to be [0, :math:`\mu + 3 \sigma` ].

For some methods, including vector and centered parameter studies, an
initial point is needed for the uncertain variables. When not given
explicitly, these variables are initialized to their means, correcting
to bounds if needed.