% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods.R
\name{find_extremum}
\alias{find_extremum}
\title{Find the Extremum of a Fitted lgspline}
\usage{
find_extremum(
  object,
  vars = NULL,
  quick_heuristic = TRUE,
  initial = NULL,
  B_predict = NULL,
  minimize = FALSE,
  stochastic = FALSE,
  stochastic_draw = function(mu, sigma, ...) {
     N <- length(mu)
     rnorm(N, mu,
    sigma)
 },
  sigmasq_predict = object$sigmasq_tilde,
  custom_objective_function = NULL,
  custom_objective_derivative = NULL,
  ...
)
}
\arguments{
\item{object}{A fitted lgspline model object.}

\item{vars}{Integer or character vector; indices or names of predictors to
optimize over. Default NULL optimizes all predictors.}

\item{quick_heuristic}{Logical; if TRUE (default) searches only the
best-performing partition. If FALSE, initiates searches from all
partition local maxima.}

\item{initial}{Numeric vector; optional starting values. Useful for
fixing binary predictors. Default NULL.}

\item{B_predict}{List; optional coefficient list for prediction, e.g.
from \code{\link{generate_posterior}}. Default NULL uses
\code{object$B}.}

\item{minimize}{Logical; find minimum instead of maximum. Default FALSE.}

\item{stochastic}{Logical; add noise during optimization for exploration.
Default FALSE.}

\item{stochastic_draw}{Function; generates noise for stochastic
optimization. Takes \code{mu}, \code{sigma}, and \code{...}.
Default \code{rnorm(length(mu), mu, sigma)}.}

\item{sigmasq_predict}{Numeric; variance for stochastic draws.
Default \code{object$sigmasq_tilde}.}

\item{custom_objective_function}{Function; optional custom objective.
Takes \code{mu}, \code{sigma}, \code{y_best}, \code{...}.
Default NULL.}

\item{custom_objective_derivative}{Function; optional gradient of
\code{custom_objective_function}. Takes \code{mu}, \code{sigma},
\code{y_best}, \code{d_mu}, \code{...}. Default NULL.}

\item{...}{Additional arguments passed to internal optimization routines.}
}
\value{
A list with elements:
\describe{
  \item{t}{Numeric vector; predictor values at the extremum.}
  \item{y}{Numeric; objective value at the extremum.}
}
}
\description{
Finds the global maximum or minimum of a fitted lgspline using L-BFGS-B,
with options for partition-based heuristics, stochastic exploration, and
custom objective functions (e.g., acquisition functions for Bayesian
optimization).
}
\examples{

set.seed(1234)
t <- runif(1000, -10, 10)
y <- 2*sin(t) + -0.06*t^2 + rnorm(length(t))
model_fit <- lgspline(t, y)
plot(model_fit)

max_point <- find_extremum(model_fit)
min_point <- find_extremum(model_fit, minimize = TRUE)
abline(v = max_point$t, col = 'blue')
abline(v = min_point$t, col = 'red')

## Expected improvement acquisition function
ei_obj <- function(mu, sigma, y_best, ...) {
  d <- y_best - mu
  d * pnorm(d/sigma) + sigma * dnorm(d/sigma)
}
ei_deriv <- function(mu, sigma, y_best, d_mu, ...) {
  d <- y_best - mu
  z <- d/sigma
  d_z <- -d_mu/sigma
  pnorm(z)*d_mu - d*dnorm(z)*d_z + sigma*z*dnorm(z)*d_z
}

post_draw <- generate_posterior(model_fit)
acq <- find_extremum(model_fit,
                     stochastic = TRUE,
                     B_predict = post_draw$post_draw_coefficients,
                     sigmasq_predict = post_draw$post_draw_sigmasq,
                     custom_objective_function = ei_obj,
                     custom_objective_derivative = ei_deriv)
abline(v = acq$t, col = 'green')

}
\seealso{
\code{\link{lgspline}}, \code{\link{generate_posterior}}
}
