% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mappers.R
\name{bm_logsumexp}
\alias{bm_logsumexp}
\alias{bru_mapper_logsumexp}
\title{Mapper for log-sum-exp aggregation}
\usage{
bm_logsumexp(rescale = FALSE, n_block = NULL)

bru_mapper_logsumexp(...)
}
\arguments{
\item{rescale}{logical; For \code{bm_aggregate} and \code{bm_logsumexp},
specifies if the blockwise sums should be normalised by the blockwise weight
sums or not:
\itemize{
\item \code{FALSE}: (default) Straight weighted sum, no rescaling.
\item \code{TRUE}: Divide by the sum of the weight values within each block.
This is useful for integration averages, when the given weights are plain
integration weights. If the weights are \code{NULL} or all ones, this is
the same as dividing by the number of entries in each block.
}}

\item{n_block}{Predetermined number of output blocks. If \code{NULL}, overrides
the maximum block index in the inputs. The priority order is \code{input$n_block},
the mapper definition \code{n_block}, then \code{max(input$block)}.}

\item{\dots}{Arguments passed on to \code{\link[=bm_logsumexp]{bm_logsumexp()}}}
}
\description{
Constructs a mapper
that aggregates elements of \code{exp(state)}, with optional non-negative
weighting, and then takes the \code{log()}, so it can be used e.g.
for  \eqn{v_k=\log[\sum_{i\in I_k} w_i \exp(u_i)]
}{log(blocksum(w*exp(state)))}
and \eqn{v_k=\log[\sum_{i\in I_k} w_i \exp(u_i) / \sum_{i\in I_k} w_i]
}{log(blocksum(w*exp(state)/blocksum(w)))}
calculations.  Relies on the input handling methods for
\code{bm_aggregate}, but also allows the weights to be supplied on a
logarithmic scale as \code{log_weights}. To avoid numerical overflow, it uses the
common method of internally shifting the state blockwise;
\eqn{v_k=s_k+\log[\sum_{i\in I_k} \exp(u_i + \log(w_i)- s_k)]
}{log(blocksum(w*exp(state)))},
where \eqn{s_k=\max_{i\in I_k} u_i + \log(w_i)}{s=blockmax(u+log(w))} is the
shift for block \eqn{k}{k}.
}
\examples{
m <- bm_logsumexp()
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4), 11:14)
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4, n_block = 3), 11:14)

}
\seealso{
\link{bru_mapper}, \link{bru_mapper_generics}

Other mappers: 
\code{\link{bm_aggregate}()},
\code{\link{bm_collect}()},
\code{\link{bm_const}()},
\code{\link{bm_factor}()},
\code{\link{bm_fm_mesh_1d}},
\code{\link{bm_fmesher}()},
\code{\link{bm_harmonics}()},
\code{\link{bm_index}()},
\code{\link{bm_linear}()},
\code{\link{bm_logitaverage}()},
\code{\link{bm_marginal}()},
\code{\link{bm_matrix}()},
\code{\link{bm_multi}()},
\code{\link{bm_pipe}()},
\code{\link{bm_reparam}()},
\code{\link{bm_repeat}()},
\code{\link{bm_scale}()},
\code{\link{bm_shift}()},
\code{\link{bm_sum}()},
\code{\link{bm_taylor}()},
\code{\link{bru_get_mapper}()},
\code{\link{bru_mapper}()}
}
\concept{mappers}
