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

{xrst_begin sample_fixed}
{xrst_spell
  msg
  rng
  rcond
  cov
}

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* ,
| |tab| *rcond* ,
| |tab| *factor* ,
| )

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 results in an over estimate of the variance, but is faster to calculate
than trying to identify active constraints and treating them as equality
constraints.
In addition, the 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
**********
The sample of the fixed effects,
excluding the constant fixed effects,
has covariance equal to the
:ref:`sample_fixed@cov_factor` times the inverse of the
:ref:`information matrix<information_mat-name>`
where the constant fixed effects have been removed.
If *cov_factor* is one, this is the asymptotic covariance for the estimates
(excluding the constraints that are not on the constant fixed effects).

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* .

Factorization
*************
The subset of the matrix *hes_fixed_obj_rcv* that corresponds to
fixed effects that are not constant is factored into L * D * L^T
where L is lower triangular and D is diagonal.

rcond
*****
This argument is optional and its input value does not matter.
Upon return it is the reciprocal of the condition number for
the diagonal matrix D in the factorization.
In other words, it is the minimum absolute entry in *D* divided
by the maximum absolute entry in D .
If the matrix D is singular, or any entry in D is nan or infinite,
*rcond* is zero.

cov_factor
**********
This argument is optional, must be greater than zero,
and its default value is one.
It can be used to expand or contract the random variation of the
fixed effects; see :ref:`sample_fixed@Covariance` .
Note that the factor corresponding to the standard deviations of the samples
is the square root of *cov_factor* .
Also note that *cov_factor* does not affect the factorization or *rcond* .

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}