Package 'pinnr'

Description

Estimated parameters

Usage

## S3 method for class 'pinn_fit'
coef(object, ...)

Arguments

Value

Named numeric vector of estimated unknown parameters (empty if the problem had none).

Description

Conditions are enforced as soft penalties on points sampled where they apply. Each condition fixes one or more domain variables (where) and samples the remaining variables over their full range.

Usage

pinn_dirichlet(
  where,
  value = 0,
  output = NULL,
  n = 100,
  weight = 1,
  name = NULL
)

pinn_neumann(
  where,
  along,
  value = 0,
  output = NULL,
  n = 100,
  weight = 1,
  name = NULL
)

pinn_initial(
  value,
  time = "t",
  output = NULL,
  n = 100,
  weight = 1,
  name = NULL
)

pinn_condition(where, fn, n = 100, weight = 1, name = NULL)

Arguments

Details

• pinn_dirichlet() fixes the value of the solution, $u = g$.

• pinn_neumann() fixes a first derivative, $\partial u / \partial v = g$.

• pinn_initial() is a Dirichlet condition at the lower end of the time variable.

• pinn_condition() takes any residual function, for Robin, periodic or other conditions.

Value

An object of class pinn_condition.

Locations

Each element of where is a number or one of the strings "lower", "upper" or "both", which refer to the ends of that variable's range. where = list(x = "both") places points on both ends of x. When several variables are fixed, every combination of their values is used: where = list(x = "both", y = "both") places points on the four corners.

Values

value can be a number, a numeric vector named by output, or a function. A function's arguments are matched by name to the domain variables, outputs and parameters, so value = function(x) sin(pi * x) uses the spatial variable x. Inside these functions the arguments are torch tensors, so use arithmetic and maths functions (sin, exp, log, ...) rather than control flow such as if or ifelse.

Examples

# u = 0 on both ends of x
pinn_dirichlet(where = list(x = "both"), value = 0)

# u(x, 0) = sin(pi x)
pinn_initial(function(x) sin(pi * x), time = "t")

# insulated right boundary: du/dx = 0 at x = 1
pinn_neumann(where = list(x = "upper"), along = "x")

# Robin condition du/dx + 2 u = 0 at x = 1, as a custom residual
pinn_condition(where = list(x = "upper"),
               fn = function(u, x, d) d(u, x) + 2 * u)

Description

Each argument names an input variable of the problem and gives its range as c(lower, upper). The order of the arguments is the order in which the variables enter the network.

Usage

pinn_domain(...)

Arguments

Value

An object of class pinn_domain.

Examples

pinn_domain(x = c(-1, 1), t = c(0, 1))

Description

Fits a fully connected network to a pinn_problem() (or a problem from pinn_ode()) by minimising

$w_r L_{residual} + w_c L_{conditions} + w_d L_{data},$

where each term is a mean squared error. Training runs epochs steps of Adam and then, optionally, lbfgs_iter iterations of L-BFGS, which often sharpens the solution considerably.

Usage

pinn_fit(
  problem,
  hidden = c(32, 32, 32),
  activation = "tanh",
  epochs = 5000,
  lr = 0.001,
  lr_unknown = NULL,
  lbfgs_iter = 0,
  n_collocation = 1000,
  sampling = c("lhs", "uniform"),
  resample_every = 0,
  weights = c(residual = 1, conditions = 1, data = 1),
  precision = c("float32", "float64"),
  device = "cpu",
  seed = NULL,
  verbose = interactive(),
  record_every = 10,
  windows = 1
)

Arguments

Value

An object of class pinn_fit, with methods for predict(), coef(), residuals(), plot() and summary().

Choosing settings

The defaults solve small problems on a CPU in seconds to minutes. If the loss stalls, try more epochs, a wider or deeper network, more collocation points, or lbfgs_iter = 500. For parameter estimation, a larger lr_unknown lets the parameters move faster than the network weights. Long time horizons are hard for PINNs; shorter windows, or more data, help.

Long time horizons

PINNs often converge to a wrong, flat solution when an ODE is solved over a long horizon with fast early dynamics (for example an epidemic starting from a few cases). For problems from pinn_ode(), windows = k splits the time range into k equal windows and trains one network per window, each starting from the end state of the previous one ("time marching"). This is available for forward problems (no unknown parameters).

Pressing Esc (or Ctrl+C) stops training early and returns the model as trained so far, with a warning. If the loss becomes NaN or infinite, training stops and the weights with the lowest loss seen so far are returned, also with a warning (and diverged = TRUE in the result).

Examples

# Exponential decay dy/dt = -k y
decay <- function(t, y, parms) list(-parms["k"] * y)
prob <- pinn_ode(decay, y0 = c(y = 1), times = seq(0, 5, by = 0.5),
                 parms = c(k = 0.5))
fit <- pinn_fit(prob, hidden = c(16, 16), epochs = 1500, seed = 1)
head(predict(fit))

Description

A multilayer perceptron with Xavier-normal initial weights and zero biases, the standard choice for PINNs.

Usage

pinn_mlp(n_in, hidden = c(32, 32, 32), n_out = 1, activation = "tanh")

Arguments

Value

A torch::nn_module.

Examples

net <- pinn_mlp(2, c(16, 16), 1)
net(torch::torch_randn(5, 2))

Description

Turns an ordinary differential equation written for deSolve::ode() into a pinn_problem(). The same derivative function can be used to solve the system (a forward problem) or, with unknown and data, to estimate its parameters from observations.

Usage

pinn_ode(
  func,
  y0,
  times,
  parms = NULL,
  unknown = NULL,
  positive = TRUE,
  data = NULL,
  time = "time",
  hard_initial = TRUE
)

Arguments

Value

A pinn_problem() object.

Writing the model

func has the usual deSolve signature ⁠function(t, y, parms)⁠ and returns a list whose first element holds the derivatives, in the order of y0. The recommended style works unchanged:

function(t, y, parms) {
  with(as.list(c(y, parms)), {
    dS <- -beta * S * I
    ...
    list(c(dS, dI, dR))
  })
}

Indexing with y["S"], y[1] or parms["beta"] also works. Because the states are torch tensors, the body must use arithmetic and maths functions; if, ifelse, max and pmin on states do not work. Forcing functions of time can be written with tensor operations, for example torch_sin(t) or sin(t).

Initial conditions

By default the initial state is enforced exactly by writing each state as $y(t) = y_0 + \frac{t - t_0}{t_1 - t_0} N(t)$, where $N$ is the network. This removes one loss term and usually speeds up training. Set hard_initial = FALSE to use a soft penalty instead.

Examples

# Logistic growth dN/dt = r N (1 - N / K)
logistic <- function(t, y, parms) {
  with(as.list(c(y, parms)), list(r * N * (1 - N / K)))
}
prob <- pinn_ode(logistic, y0 = c(N = 0.1), times = seq(0, 10, by = 0.5),
                 parms = c(r = 1, K = 1))
prob

Description

Collects everything a PINN needs: the domain, the names of the unknown functions, the equation residual, conditions, optional observations and the equation's parameters.

Usage

pinn_problem(
  domain,
  outputs,
  residual,
  conditions = list(),
  data = NULL,
  parms = list(),
  unknown = NULL,
  positive = TRUE,
  transform = NULL
)

Arguments

Value

An object of class pinn_problem.

Writing the residual

residual is an R function whose arguments are matched by name to:

• the outputs (for example u),

• the domain variables (for example x, t),

• the parameters in parms and unknown, and

• d, the derivative operator.

d(f, x) differentiates f with respect to the variable x; d(f, x, x) gives the second derivative and d(f, x, t) a mixed derivative. The function returns the expression that should equal zero, or a list of such expressions for a system of equations. For the viscous Burgers equation $u_t + u u_x - \nu u_{xx} = 0$:

function(u, x, t, nu, d) d(u, t) + u * d(u, x) - nu * d(u, x, x)

All arguments are torch tensors with one row per point, so use arithmetic and maths functions (sin, exp, log, sqrt, ...) and avoid if, ifelse or functions that leave R's torch methods.

Output transforms

transform can enforce conditions exactly ("hard constraints"). It is called with the raw network outputs, domain variables and parameters (matched by name, as above) and returns a named list of modified outputs. For example, to make $u(0, t) = u(1, t) = 0$ hold exactly: transform = function(u, x) list(u = x * (1 - x) * u).

See Also

pinn_ode() for ordinary differential equations written in deSolve style, and pinn_fit() to train the network.

Examples

# Heat equation u_t = a u_xx with u(x, 0) = sin(pi x) and u = 0 at both ends
heat <- pinn_problem(
  domain = pinn_domain(x = c(0, 1), t = c(0, 1)),
  outputs = "u",
  residual = function(u, x, t, a, d) d(u, t) - a * d(u, x, x),
  conditions = list(
    pinn_initial(function(x) sin(pi * x), time = "t"),
    pinn_dirichlet(where = list(x = "both"), value = 0)
  ),
  parms = list(a = 0.1)
)
heat

Description

Draws training points uniformly at random or with Latin hypercube sampling. Variables listed in fixed are held at the given values, which is how boundary and initial points are generated.

Usage

pinn_sample(n, domain, method = c("lhs", "uniform"), fixed = list())

Arguments

Value

A data frame with one column per domain variable.

Examples

dom <- pinn_domain(x = c(0, 1), t = c(0, 2))
head(pinn_sample(5, dom))
pinn_sample(4, dom, fixed = list(x = c(0, 1)))

Description

Torch modules cannot be stored with saveRDS() directly. pinn_save() stores the network weights as plain arrays alongside the rest of the fit, and pinn_load() rebuilds the network.

Usage

pinn_save(fit, path)

pinn_load(path)

Arguments

Value

pinn_save() returns path invisibly; pinn_load() returns a pinn_fit.

Description

Plot a fitted PINN

Usage

## S3 method for class 'pinn_fit'
plot(x, type = c("loss", "solution", "parameters"), output = NULL, ...)

Arguments

Value

x, invisibly.

Description

Evaluates the trained network at new points.

Usage

## S3 method for class 'pinn_fit'
predict(object, newdata = NULL, ...)

Arguments

Value

A data frame with the domain variables followed by one column per output.

Examples

decay <- function(t, y, parms) list(-parms["k"] * y)
prob <- pinn_ode(decay, y0 = c(y = 1), times = c(0, 5), parms = c(k = 0.5))
fit <- pinn_fit(prob, hidden = c(16, 16), epochs = 1000, seed = 1)
predict(fit, data.frame(time = c(0, 1, 2)))

Description

Evaluates the equation residual at new points. Values close to zero mean the network satisfies the equation there; large values show where the solution is unreliable.

Usage

## S3 method for class 'pinn_fit'
residuals(object, newdata = NULL, ...)

Arguments

Value

A data frame with the domain variables followed by one residual column per equation.