-----------------------------------------
lines 6-165 of file: src/sample_fixed.cpp
-----------------------------------------

{xrst_begin sample_fixed}
{xrst_spell
  msg
  rng
}

Sample Posterior for Fixed Effects
##################################

Syntax
******

| *error_msg* = *mixed_object* . ``sample_fixed`` (
| |tab| *sample* ,
| |tab| *hes_fixed_obj_rcv* ,
| |tab| *solution* ,
| |tab| *fixed_lower* ,
| |tab| *fixed_upper*
| )

See Also
********
:ref:`sample_random-name`

Prototype
*********
{xrst_literal
   // BEGIN PROTOTYPE
   // END PROTOTYPE
}

Purpose
*******
This routine draws independent samples from
the asymptotic posterior distribution for the
fixed effects (given the model and the data).

Constant Fixed Effects
**********************
If the upper and lower limits for the *j*-th fixed effect are equal::

   fixed_lower[j] == fixed_upper[j]

we refer to the *j*-th fixed effect as constant.

Constraints
***********
Only the constant fixed effect constants are taken into account.
(This is an over estimate of the variance, but is faster to calculate
than trying to identify active constraints and treating them as equality
constraints.)
It can result in samples that are outside the limits
for the fixed effects that are not constant.
You may want to adjust the samples to be within
their upper and lower limits before you use them.

Covariance
**********
Each sample of the fixed effects
(excluding the constant fixed effects)
has covariance equal to the inverse of the
:ref:`information matrix<information_mat-name>`
(where the constant fixed effects have been removed).

manage_gsl_rng
**************
It is assumed that
:ref:`manage_gsl_rng@get_gsl_rng` will return
a pointer to a GSL random number generator.

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.

sample
******
The size *sample* . ``size`` () is a multiple of
:ref:`derived_ctor@n_fixed` .
The input value of its elements does not matter.
We define::

   n_sample = sample_size / n_fixed

If *error_msg* is empty, upon return
for *i* = 0 , ..., *n_sample*-1 ,
*j* = 0 , ..., *n_fixed*-1 ::

   sample[i * n_fixed + j]

is the *j*-th component of the *i*-th sample of the
optimal fixed effects :math:`\hat{\theta}`.

#. These samples are independent for different :math:`i` .
#. For each :math:`i`, the corresponding sample has the specified
   :ref:`sample_fixed@Covariance` .
#. The constraints are only enforced for the
   :ref:`sample_fixed@Constant Fixed Effects` ; i.e.,
   if the *j*-th fixed effect is not constant,
   the sample may not satisfy the condition::

      fixed_lower[j] <= sample[i * n_fixed + j] <= fixed_upper[j]


hes_fixed_obj_rcv
*****************
This is a sparse matrix representation for the
lower triangle of the observed information matrix corresponding to
*solution* ; i.e., the matrix returned by

| *hes_fixed_obj_rcv* = *mixed_object* . ``hes_fixed_obj`` (
| |tab| *solution* , *random_opt*
| )

where *random_opt* is the optimal random effects corresponding
to *solution* .

solution
********
is the :ref:`optimize_fixed@solution`
for a the call to :ref:`optimize_fixed-name` corresponding to
*hes_fixed_obj_rcv* .
The only necessary information in this structure is
*solution* . ``fixed_opt`` .

fixed_lower
***********
is the same as
:ref:`optimize_fixed@fixed_lower`
in the call to ``optimize_fixed`` that corresponding to *solution* .

fixed_upper
***********
is the same as
:ref:`optimize_fixed@fixed_upper`
in the call to ``optimize_fixed`` that corresponding to *solution* .

error_msg
*********
If *error_msg* is empty (non-empty),
:ref:`sample_fixed@sample`
values have been calculated (have not been calculated).
If *error_msg* is non-empty,
it is a message describing the problem.
{xrst_toc_hidden
   example/user/sample_fixed.cpp
   src/eigen/sample_conditional.cpp
}
Example
*******
The file :ref:`sample_fixed.cpp-name` is an example
and test of ``sample_fixed`` .

Other Method
************
The routine :ref:`sample_conditional-name` , is a old method that is no
longer used for computing these samples.

{xrst_end sample_fixed}