% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generic_ns.R
\name{generic_ns}
\alias{generic_ns}
\title{Non-stationary precision matrix operator with custom matrix combinations}
\usage{
generic_ns(
  theta_K,
  matrices,
  position,
  h,
  model = "generic_ns",
  B_theta_K = NULL,
  trans = NULL,
  mesh = NULL,
  zero_trace = FALSE,
  param_name = NULL,
  param_trans = NULL,
  ...
)
}
\arguments{
\item{theta_K}{List of parameter vectors (in real scale)}

\item{matrices}{List of fixed matrices to be used in the model}

\item{position}{List of vectors specifying matrix combinations (required)}

\item{h}{The integration weights vector}

\item{model}{The model type name stored on the returned operator}

\item{B_theta_K}{List of basis matrices for parameters, defaults to matrices of 1s if not provided}

\item{trans}{List of transformations for each parameter (one transformation per parameter)}

\item{mesh}{The mesh object}

\item{zero_trace}{Whether the trace of K should be zero}

\item{param_name}{Optional parameter names stored on the returned operator for diagnostics}

\item{param_trans}{Optional parameter transformations stored on the returned operator for diagnostics}

\item{...}{Additional arguments (ignored)}
}
\value{
An object of class \code{ngme_operator}. The object stores the sparse
  non-stationary precision matrix \code{K}, integration weights \code{h}, the
  flattened parameter vector \code{theta_K}, basis matrices
  \code{B_theta_K}, parameter grouping metadata \code{param_map}, matrix
  combination rules \code{position}, and an update function for rebuilding
  \code{K}. It is intended for use as the latent \code{model} inside
  \code{f()}.
}
\description{
Creates a flexible non-stationary precision matrix K by allowing both linear combinations
and matrix multiplications with parameter-dependent diagonal matrices. This enables modeling
spatially varying parameters through basis expansions.
}
\details{
The key distinction from `generic` is that `generic_ns`:
1. Requires explicit position specification for matrix combinations
2. Converts parameters to diagonal matrices for multiplication with fixed matrices
3. Allows for basis expansions via B_theta_K


The `generic_ns` operator constructs K through the following steps:

1. Create diagonal matrices for each parameter using basis expansions: D_param = diag(B_param * theta_param)
2. Combine parameter matrices with fixed matrices according to position specifications
3. Sum all the resulting combinations

The `position` parameter defines how matrices are combined:
- Each element of the list represents a term in the sum
- Each vector contains indices of matrices to multiply (parameter matrices first, then fixed matrices)
- For example: `position = list(c(1, 3), c(2, 4))` with one parameter means:
  Multiply the parameter diagonal matrix (index 1) with fixed matrix 1 (index 3),
  then add parameter diagonal matrix 2 (index 2) multiplied by fixed matrix 2 (index 4)

Spatially-varying parameters can be created using basis matrices in B_theta_K.
}
\examples{
# Simple example with one parameter
n <- 5
A <- matrix(1, n, n)
B <- matrix(2, n, n)
alpha <- 0.4

# Create a simple generic_ns model: D_alpha * A + B
model <- generic_ns(
  theta_K = list(alpha = c(alpha)),
  matrices = list(A, B),
  position = list(c(1, 2), c(3)), # D_alpha * A + B
  h = rep(1, n)
)

# AR1 model representation: rho * C + G
ar1_obj <- ar1(1:10, rho = 0.5)
g <- name2fun("tanh", inv = TRUE)
generic_ar1 <- generic_ns(
  theta_K = list(x = c(g(0.5))), # Transform from real scale
  trans = list(x = "tanh"), # Apply tanh transformation
  matrices = list(ar1_obj$C, ar1_obj$G),
  position = list(c(1, 2), c(3)), # D_rho * C + G
  h = ar1_obj$h,
  mesh = 1:10
)

# Spatially varying Matern model
# Create a simple 1D mesh
mesh <- fmesher::fm_mesh_1d(seq(0, 1, length.out = 10))

# Create basis for spatially-varying kappa
n <- 10
B_kappa <- matrix(0, n, 2)
B_kappa[1:(n / 2), 1] <- 1 # First half of the domain
B_kappa[(n / 2 + 1):n, 2] <- 1 # Second half of the domain

# Create standard Matern components
matern_model <- matern(mesh)

# Create model with space-varying kappa
ns_model <- generic_ns(
  theta_K = list(kappa = c(log(1), log(2))), # Different values for each region
  matrices = list(matern_model$C, matern_model$G),
  B_theta_K = list(kappa = B_kappa),
  trans = list(kappa = "exp2"), # kappa^2 transformation for C
  h = matern_model$h,
  position = list(c(1, 2), c(3)), # D_kappa * C + G
  mesh = mesh
)

}
