---------------------------------------------
lines 12-130 of file: src/optimize_random.cpp
---------------------------------------------

{xrst_begin optimize_random}

Optimize Random Effects
#######################

Syntax
******
*random_out*  =

| *mixed_object* . ``optimize_random`` (
| |tab| *options* , *fixed_vec* , *random_lower* , *random_upper* , *random_in*
| )

Purpose
*******
This routine maximizes the
:ref:`random likelihood<ran_likelihood-name>`
corresponding to the object *mixed_object* .

mixed_object
************
We use :ref:`derived_ctor@mixed_object`
to denote an object of a class that is
derived from the ``cppad_mixed`` base class.

options
*******
This argument  has the prototype

   ``const std::string&`` *options*

This is the :ref:`ipopt_options-name` for optimizing the random effects
with the following qualifications:

evaluation_method
=================
There is an additional :ref:`ipopt_options@String` option with
*name* = ``evaluation_method``
and *value* is either ``ipopt_random``  or ``ipopt_solve`` .
The ``ipopt_random`` choice uses
``CppAD::mixed::ipopt_random`` for optimizing random effects.
This special purpose class
is expected to eventually be the faster choice.
This is the default choice; i.e., ``ipopt_random`` will be used
if this option is not present.
The ``ipopt_solve`` choice uses
``CppAD::ipopt::solve`` for optimizing random effects.
Currently this is sometimes faster and so this choice is still included
(but may be removed in the future).

fixed_vec
*********
This argument has prototype

   ``const CppAD::vector<double>&`` *fixed_vec*

It specifies the value of the
:ref:`fixed effects<problem@Notation@Fixed Effects, theta>`
vector :math:`\theta`.

random_lower
************
This argument has prototype

   ``const CppAD::vector<double>&`` *random_lower*

It must have size equal to
:ref:`derived_ctor@n_random` and
specifies the lower limits for the optimization of the
:ref:`random effects<problem@Notation@Random Effects, u>`
vector :math:`u`.
The value minus infinity can be used to specify no lower limit.

random_upper
************
This argument has prototype

   ``const CppAD::vector<double>&`` *random_upper*

It must have size equal to
:ref:`derived_ctor@n_random` and
specifies the upper limits for the optimization of the random effect.
The value plus infinity can be used to specify no lower limit.

random_in
*********
This argument has prototype

   ``const CppAD::vector<double>&`` *random_in*

It must have size equal to
:ref:`derived_ctor@n_random` and
specifies the initial value used for the optimization of the
:ref:`random effects<problem@Notation@Random Effects, u>` vector :math:`u`.
It must hold that

   *random_lower* [ *i* ] <= *random_in* [ *i* ] <= *random_upper* [ *i* ]

for each valid index *i* .

random_out
**********
The return value  has prototype

   ``CppAD::vector<double>`` *random_out*

It is the final value (obtained by optimization) of the
:ref:`random effects<problem@Notation@Random Effects, u>`
vector :math:`u`.
{xrst_toc_hidden
   example/user/optimize_random.cpp
}
Example
*******
The file :ref:`optimize_random.cpp-name` contains an example
and test of this procedure.
It returns true, if the test passes, and false otherwise.

{xrst_end optimize_random}