R: Steady-state solver for 2-Dimensional ordinary differential...

steady.2D {rootSolve} | R Documentation

## Steady-state solver for 2-Dimensional ordinary differential equations

### Description

Estimates the steady-state condition for a system of ordinary differential equations that result from 2-Dimensional partial differential equation models that have been converted to ODEs by numerical differencing.

It is assumed that exchange occurs only between adjacent layers.

### Usage

    steady.2D(y, time = 0, func, parms = NULL, nspec = NULL,
              dimens, names = NULL, method = "stodes",
              jactype = NULL, cyclicBnd = NULL, times = time, ...)

### Arguments

`y` | the initial guess of (state) values for the ODE system, a vector.
`time, times` | time for which steady-state is wanted; the default is `times=0` (for `method = "stodes"`, and `times = c(0,Inf)` for `method = "runsteady"`). (note- since version 1.7, 'times' has been added as an alias to 'time').
`func` | either an R-function that computes the values of the derivatives in the ode system (the model defininition) at time `time`, or a character string giving the name of a compiled function in a dynamically loaded shared library. If `func` is an R-function, it must be defined as: `yprime = func(t, y, parms,...)`. `t` is the current time point in the integration, `y` is the current estimate of the variables in the ODE system. If the initial values `y` has a names attribute, the names will be available inside `func`. `parms` is a vector or list of parameters; ... (optional) are any other arguments passed to the function. The return value of `func` should be a list, whose first element is a vector containing the derivatives of `y` with respect to `time`, and whose next elements are global values whose steady-state value is also required. The derivatives should be specified in the same order as the state variables `y`.
`parms` | parameters passed to `func`.
`nspec` | the number of *species* (components) in the model.
`dimens` | a 2-valued vector with the dimensionality of the model, i.e. the number of *boxes* in x- and y-direction.
`method` | the solution method, one of "stodes", or "runsteady". When `method` = 'runsteady', then solver `lsodes`, the sparse solver is used by default, unless argument `jactype` is set to `"2D"`, in which case `lsode` will be used (likely less efficient). in which case `lsodes` is used and the structure of the jacobian is determined by the solver.
`jactype` | the jacobian type - default is a regular 2-D structure where layers only interact with adjacent layers in both directions. If the structure does not comply with this, the jacobian can be set equal to `'sparse'`.
`cyclicBnd` | if not `NULL` then a number or a 2-valued vector with the dimensions where a cyclic boundary is used - `1`: x-dimension, `2`: y-dimension; see details.
`names` | the names of the components; used to label the output, and for plotting.
`...` | additional arguments passed to function stodes. See example for the use of argument `positive` to enforce positive values (pos = TRUE). See details.

### Details

This is the method of choice for 2-dimensional models, that are only subjected to transport between adjacent layers.

Based on the dimension of the problem, the method first calculates the sparsity pattern of the Jacobian, under the assumption that transport is only occurring between adjacent layers. Then `stodes` is called to find the steady-state.

In some cases, a cyclic boundary condition exists. This is when the first boxes in x-or y-direction interact with the last boxes. In this case, there will be extra non-zero fringes in the Jacobian which need to be taken into account. The occurrence of cyclic boundaries can be toggled on by specifying argument `cyclicBnd`. For innstance, `cyclicBnd = 1` indicates that a cyclic boundary is required only for the x-direction, whereas `cyclicBnd = c(1,2)` imposes a cyclic boundary for both x- and y-direction. The default is no cyclic boundaries.

As `stodes` is used, it will probably be necessary to specify the length of the real work array, `lrw`.

Although a reasonable guess of `lrw` is made, it may occur that this will be too low. In this case, `steady.2D` will return with an error message telling that there was insufficient storage. In the second try then, increase `lrw`. you may need to experiment to find suitable value. The smaller the better.

An error message that says to increase `lrw` may look like this:

     In stodes(y = y, time = time, func = func, parms = parms, nnz = c(nspec,  :
      insufficient storage in nnfc

See `stodes` for the additional options.

### Value

A list containing

`y` | a vector with the state variable values from the last iteration during estimation of steady-state condition of the system of equations.
`...` | the "global" values returned.

The output will have the `attribute` `steady`, which returns `TRUE`, if steady-state has been reached and the attribute `precis` with the precision attained during each iteration. Another attribute, called `dims` returns a.o. the length of the work array actually required. This can be specified with input argument `lrw`. See note and first example

### Note

It is advisable though not mandatory to specify BOTH `nspec` and `dimens`. In this case, the solver can check whether the input makes sense (as nspec*dimens[1]*dimens[2] = length(y))

do NOT use this method for problems that are not 2D.

It is likely that the estimated length of the work array (argument `lrw`), required for the solver stodes will be too small. If that is the case, the solver will return with an error saying to increase `lrw`. The current value of the work array can be found via the `attributes` of the output. See first example.

### Author(s)

Karline Soetaert <karline.soetaert@nioz.nl>

### See Also

`steady`, for a general interface to most of the steady-state solvers

`steady.band`, to find the steady-state of ODE models with a banded Jacobian

`steady.1D`, `steady.3D`, steady-state solvers for 1-Dand 3-D partial differential equations.

`stode`, iterative steady-state solver for ODEs with full or banded Jacobian.

`stodes`, iterative steady-state solver for ODEs with arbitrary sparse Jacobian.

`runsteady`, steady-state solver by dynamically running to steady-state

### Examples

    ## =======================================================================
    ## Diffusion in 2-D; imposed boundary conditions
    ## =======================================================================
    diffusion2D <- function(t, Y, par)   {

       y    <- matrix(nr=n,nc=n,data=Y)  # vector to 2-D matrix
       dY   <- -r*y        # consumption
       BND   <- rep(1,n)   # boundary concentration

       #diffusion in X-direction; boundaries=imposed concentration
       Flux <- -Dx * rbind(y[1,]-BND,(y[2:n,]-y[1:(n-1),]),BND-y[n,])/dx
       dY   <- dY - (Flux[2:(n+1),]-Flux[1:n,])/dx

       #diffusion in Y-direction
       Flux <- -Dy * cbind(y[,1]-BND,(y[,2:n]-y[,1:(n-1)]),BND-y[,n])/dy
       dY    <- dY - (Flux[,2:(n+1)]-Flux[,1:n])/dy

       return(list(as.vector(dY)))
    }

    # parameters
    dy    <- dx <- 1   # grid size
    Dy    <- Dx <- 1   # diffusion coeff, X- and Y-direction
    r     <- 0.025     # consumption rate

    n  <- 100
    y  <- matrix(nrow = n, ncol = n, 10.)

    # stodes is used, so we should specify the size of the work array (lrw)
    # We take a rather large value
    # By specifying pos = TRUE, only positive values are allowed.

    system.time(
    ST2 <- steady.2D(y, func = diffusion2D, parms = NULL, pos = TRUE,
                     dimens = c(n, n), lrw = 1000000,
                     atol = 1e-10, rtol = 1e-10, ctol = 1e-10)
    )

    ## Not run:   # this takes a long time...
    system.time(
    ST3 <- steady.2D(y, func = diffusion2D, parms = NULL,
                     dimens = c(n, n), lrw = 1000000, method = "runsteady",
                     time = c(0, 1e6), atol = 1e-10, rtol = 1e-10)
    )

    ## End(Not run)

    # the actual size of lrw is in the attributes()$dims vector.
    # it is best to set lrw as small as possible
    attributes(ST2)

    image(ST2, legend = TRUE)

    # The hard way of plotting:
    #y <- matrix(nr = n, nc = n, data = ST2$y)
    #     filled.contour(y, color.palette = terrain.colors)

    ## =======================================================================
    ## Diffusion in 2-D; extra flux on 2 boundaries, cyclic in y
    ## =======================================================================

    diffusion2Db <- function(t, Y, par)  {

       y    <- matrix(nr=nx,nc=ny,data=Y)  # vector to 2-D matrix
       dY   <- -r*y        # consumption

       BNDx   <- rep(1,nx)   # boundary concentration
       BNDy   <- rep(1,ny)   # boundary concentration

       #diffusion in X-direction; boundaries=imposed concentration
       Flux <- -Dx * rbind(y[1,]-BNDy,(y[2:nx,]-y[1:(nx-1),]),BNDy-y[nx,])/dx
       dY   <- dY - (Flux[2:(nx+1),]-Flux[1:nx,])/dx

       #diffusion in Y-direction
       Flux <- -Dy * cbind(y[,1]-BNDx,(y[,2:ny]-y[,1:(ny-1)]),BNDx-y[,ny])/dy
       dY    <- dY - (Flux[,2:(ny+1)]-Flux[,1:ny])/dy

       # extra flux on two sides
       dY[,1] <- dY[,1]+  10
       dY[1,] <- dY[1,]+  10

       # and exchange between sides on y-direction
       dY[,ny] <- dY[,ny]+ (y[,1]-y[,ny])*10

       return(list(as.vector(dY)))
    }

    # parameters
    dy    <- dx <- 1   # grid size
    Dy    <- Dx <- 1   # diffusion coeff, X- and Y-direction
    r     <- 0.025     # consumption rate

    nx  <- 50
    ny  <- 100
    y  <- matrix(nrow = nx, ncol = ny, 10.)

    print(system.time(
      ST2 <- steady.2D(y, func = diffusion2Db, parms = NULL, pos = TRUE,
              dimens = c(nx, ny), verbose = TRUE, lrw = 283800,
              atol = 1e-10, rtol = 1e-10, ctol = 1e-10,
              cyclicBnd = 2)       # y-direction: cyclic boundary
    ))

    image(ST2)
    #y <- matrix(nrow = nx, ncol = ny, data = ST2$y)
    #    filled.contour(y,color.palette=terrain.colors)

[Package rootSolve version 1.8.2.3 Index]