R语言 rootSolve包 stode()函数中文帮助文档(中英文对照)

loveR

stode(rootSolve)
stode()所属R语言包：rootSolve

                                         Iterative steady-state solver for ordinary differential equations (ODE) and a full or banded Jacobian.
                                         常微分方程（ODE）和一个完整的或带状的雅可比迭代稳态解算器。

                                         译者：生物统计家园网 机器人LoveR

描述----------Description----------

Estimates the steady-state condition for a system of  ordinary differential equations (ODE) written in the form:
估计系统的稳态条件的常微分方程（ODE）以书面的形式：

i.e. finds the values of y for which f(t,y) = 0.
即发现yF（T，Y）= 0的值。

Uses a newton-raphson method, implemented in Fortran 77.
采用了Newton-Raphson方法，实现在Fortran 77。

The system of ODE's is written as an R function or defined in compiled code that has been dynamically loaded.
该系统的ODE的书面一个R函数或定义在编译的代码已被动态加载。


用法----------Usage----------


stode(y, time = 0, func, parms = NULL,
      rtol = 1e-6, atol = 1e-8, ctol = 1e-8,
      jacfunc = NULL, jactype = "fullint", verbose = FALSE,
      bandup = 1, banddown = 1, positive = FALSE,
      maxiter = 100, ynames = TRUE,
      dllname = NULL, initfunc = dllname, initpar = parms,
      rpar = NULL, ipar = NULL, nout = 0, outnames = NULL,



参数----------Arguments----------

参数：y
the initial guess of (state) values for the ode system, a vector. If y has a name attribute, the names will be used to label the output matrix.  
（州）的初始估计值，的颂歌系统，一个向量。 y如果有一个name属性，名称将被用于标记输出矩阵。


参数：time
time for which steady-state is wanted; the default is time=0.  
想稳定状态的时间，默认为time= 0。


参数：func
either a user-supplied function that computes the values of the derivatives in the ode system (the model definition) at time time, or a character string giving the name of a compiled function in a dynamically loaded shared library.  If func  is a user-supplied function, it must be called as: yprime = func(t, y, parms, ...).  t is the time point at which the steady-state is wanted, 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 of parameters (which may have a names attribute).  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 (possibly with a names attribute) are global values that are required as output.  The derivatives should be specified in the same order as the state variables y.  If func is a string, then dllname must give the name of the shared library (without extension) which must be loaded before stode() is called. see Details for more information.  
任何一个用户提供的函数，计算在的颂歌系统（模型定义）的衍生工具的价值time，或者是一个字符串给一个已编译的函数动态加载的共享库的名称。如果func是一个用户提供的函数，它必须被称为：yprime = func(t, y, parms, ...)。 t是在稳定状态的时间点被通缉，y是目前估计的颂歌系统中的变量。如果初始值y有一个名称属性，名称将是提供内func。 parms是一个向量的参数（其可以有一个名称属性）。 func的返回值应该是一个列表的第一个元素是一个包含y衍生工具的矢量就到time外，而其下一个元素（可能与一个names 属性）是全球所需要的值作为输出。衍生工具应以相同的顺序指定的作为状态变量y。如果func是一个字符串，然后dllname必须放弃之前必须加载stode()被称为共享库（没有扩展名）的名称。查看更多信息。


参数：parms
other parameters passed to func and jacfunc.  
其他参数传递给func和jacfunc。


参数：rtol
relative error tolerance, either a scalar or a vector, one value for each y.  
相对误差，无论是一个标量或向量，每一个y。


参数：atol
absolute error tolerance, either a scalar or a vector, one value for each y.  
绝对误差，无论是一个标量或向量，每一个y。


参数：ctol
if between two iterations, the maximal change in y is less than this amount, steady-state is assumed to be reached.  
如果两次迭代之间，最大的改变y低于这一数额，被假定为达到稳态。


参数：jacfunc
if not NULL, either a user-supplied R function that estimates the Jacobian of the system of differential equations dydot(i)/dy(j), or a character string giving the name of a compiled function in a dynamically loaded shared library as provided in dllname. In some circumstances, supplying jacfunc can speed up the computations.  The R calling sequence for jacfunc is identical to that of func.        If the Jacobian is a full matrix, jacfunc should return a matrix dydot/dy, where the ith row contains the derivative of dy_i/dt with respect to y_j, or a vector containing the matrix elements by columns (the way R and Fortran store matrices).  If the Jacobian is banded, jacfunc should return a matrix containing only the nonzero bands of the jacobian, (dydot/dy), rotated row-wise.  
如果非NULL，无论是作为用户提供的R函数，估计雅可比系统的微分方程dydot（I）/ DY（j）条，或一个字符串给一个已编译的函数的名称，在一个动态加载的共享库中提供的dllname。在某些情况下，提供jacfunc可以加快计算。的R调用jacfunc的序列是相同的func。如果雅可比是一个完整的矩阵，jacfunc应该返回一个矩阵dydot / DY，其中第i行包含衍生工具的dy_i/dty_j，或一个向量，包含矩阵元素列的方式（R和Fortran的商店矩阵）。如果是带状的雅可比，jacfunc应该返回一个矩阵的非零带的雅可比，（dydot / DY），逐行旋转。


参数：jactype
the structure of the Jacobian, one of "fullint", "fullusr", "bandusr", or "bandint" - either full or banded and estimated internally or by the user.  
的雅可比矩阵，其中一个“fullint”中，“fullusr”，“bandusr”，或“bandint” - 无论是完整的或带状的和估计内部或由用户的结构。


参数：verbose
if TRUE: full output to the screen, e.g. will output the steady-state settings.  
如果TRUE：完整的输出到屏幕上，例如将输出的稳定状态设置。


参数：bandup
number of non-zero bands above the diagonal, in case the Jacobian is banded.  
数量的非零对角线以上频带的情况下，是带状的Jacobian。


参数：banddown
number of non-zero bands below the diagonal, in case the jacobian is banded.  
对角以下的数量的非零频带的情况下，是带状的雅可比。


参数：positive
either a logical or a vector with indices of the state variables that have to be non-negative; if TRUE, all state variables y are forced to be non-negative numbers.  
逻辑或一个矢量指数有非负的状态变量;如果TRUE，所有的状态变量y被迫成为非负数。


参数：maxiter
maximal number of iterations during one call to the solver.\  
最大的迭代次数，在一个呼叫的解算器。\


参数：ynames
if FALSE: names of state variables are not passed to function func ; this may speed up the simulation especially for multi-D models.  
如果为FALSE：状态变量的名称传递给函数func;这可能加快模拟，特别是对多-D模型。


参数：dllname
a string giving the name of the shared library (without extension) that contains all the compiled function or subroutine definitions referred to in func and jacfunc.  
一个字符串，给出的共享库（不带扩展名），其中包含所有已编译的函数或子程序定义中提到func和jacfunc的名称。


参数：initfunc
if not NULL, the name of the initialisation function (which initialises values of parameters), as provided in "dllname". See details.  
的初始化功能的名称（初始化的参数的值），如果不为NULL，如设置在dllname。查看详细信息。


参数：initpar
only when "dllname" is specified and an initialisation function initfunc is in the dll: the parameters passed to the initialiser, to initialise the common blocks (FORTRAN) or global variables (C, C++).  
只有当dllname指定一个初始化函数initfunc是在dll中传递的参数的初始化程序，初始化的常见块（FORTRAN）或全局变量（C，C + +） 。


参数：rpar
only when "dllname" is specified: a vector with double precision values passed to the dll-functions whose names are specified by func and jacfunc.  
只有当dllname指定一个向量，其双精度值传递的DLL函数的名称所指定的func和jacfunc。


参数：ipar
only when "dllname" is specified: a vector with integer values passed to the dll-functions whose names are specified by func and jacfunc.  
只有当dllname指定一个向量，其整数值传递的DLL函数的名称所指定的func和jacfunc。


参数：nout
only used if "dllname" is specified and the model is defined in compiled code: the number of output variables calculated in the compiled function func, present in the shared library. Note: it is not automatically checked whether this is indeed the number of output variables calculated in the dll - you have to perform this check in the code - see package vignette.  
仅用于dllname指定和编译后的代码输出的数量计算的变量在编译的函数func，目前在共享库中定义的模型。注意：它不会自动检查是否这确实是在dll中的输出变量计算 - 你必须在代码中执行此检查 - 包小插曲。


参数：outnames
only used if "dllname" is specified and nout > 0: the names of output variables calculated in the compiled function func, present in the shared library.  
如果只使用dllname指定和nout> 0：输出计算的变量在编译的函数func，目前在共享库的名字。


参数：forcings
only used if "dllname" is specified: a vector with the  forcing function values, or a list with the forcing function data sets,  each present as a two-columned matrix, with (time,value); interpolation  outside the interval [min(times), max(times)] is done by  taking the value at the closest data extreme.  This feature is here for compatibility with models defined in compiled code from package deSolve; see deSolve's package vignette "compiledCode".  
如果只使用dllname的指定的：与强迫函数值，或与强制函数数据集的列表，每个作为一个两列的矩阵存在，与（时间值）的矢量;插值外分（times），最大（times）是通过在最近的数据极端值。此功能是这里的模型定义在编译后的代码包deSolve的兼容性; deSolve的的包小插曲"compiledCode"。


参数：initforc
if not NULL, the name of the forcing function initialisation function, as provided in "dllname". It MUST be present if forcings has been given a value. See deSolve's package vignette "compiledCode".  
如果不是NULL，强制函数初始化函数的名称，设置在dllname。它必须是forcings如果已被赋予了价值。请参阅deSolve的的包小插曲"compiledCode"。


参数：fcontrol
A list of control parameters for the forcing functions. See deSolve's package vignette "compiledCode".  
列表控制参数的强制功能。请参阅deSolve的的包小插曲"compiledCode"。


参数：...
additional arguments passed to func and jacfunc allowing this to be a generic function.  
额外的参数传递到func和jacfunc这是一个通用的功能。


Details

详细信息----------Details----------

The work is done by a Fortran 77 routine that implements the Newton-Raphson method. It uses code from LINPACK.
的工作是由一个Fortran 77程序实现了Newton-Raphson方法。它使用代码LINPACK。

The form of the Jacobian can be specified by jactype which can take the following values:
的雅可比矩阵的形式可以指定jactype，可采取以下值：

jactype = "fullint" : a full jacobian, calculated internally by the solver, the default.
jactype =“fullint”：一个完整的雅可比，内部计算的求解器，默认值。

jactype = "fullusr" : a full jacobian, specified by user function jacfunc.
jactype =“fullusr”：一个完整的雅可比，指定用户功能jacfunc。

jactype = "bandusr" : a banded jacobian, specified by user function jacfunc; the size of the bands specified by bandup and banddown.
jactype =“bandusr”：一个带状的雅可比，指定的用户功能jacfunc指定的bandup和banddown的乐队的大小。

jactype = "bandint" : a banded jacobian, calculated by the solver; the size of the bands specified by bandup and banddown.
jactype =“bandint”：一个带状的雅可比矩阵的求解，计算指定的bandup和banddown的乐队的大小。

if jactype= "fullusr" or "bandusr" then the user must supply a subroutine jacfunc.
如果jactype=“fullusr”或“bandusr”，那么用户必须提供子程序jacfunc。

The input parameters rtol, atol and ctol determine the error control performed by the solver.
的输入参数rtol，atol和ctol确定错误的求解器进行控制。

The solver will control the vector e of estimated local errors in y, according to an inequality of the form max-norm of ( e/ewt ) <= 1, where ewt is a vector of positive error weights.  The values of rtol and atol should all be non-negative. The form of ewt is:
求解器将控制在y的估计误差矢量e，根据不平等的最大规范的形式（E / EWT）<=1，EWT是一个积极的错误权重向量。 rtol和atol都应该是非负的值。 EWT的形式是：

where multiplication of two vectors is element-by-element.
两个向量的乘法是元素的元素。

In addition, the solver will stop if between two iterations, the maximal change in the values of y is less than ctol.
此外，求解器将停止，如果两次迭代之间，最大的变化在y的值是小于ctol。

Models may be defined in compiled C or Fortran code, as well as in R.
模型可以定义在编译的C或Fortran代码，以及在R.

If func or jacfunc are a string, then they are assumed to be compiled code.
如果func或jacfunc是一个字符串，然后他们被认为将编译后的代码。

In this case, dllname must give the name of the shared library (without extension) which must be loaded before stode() is called.
在这种情况下，dllname必须给之前必须加载stode()被称为共享库（没有扩展名）的名称。

See vignette("rooSolve") for how a model has to be specified in compiled code. Also, vignette("compiledCode") from package deSolve contains examples of how to do this.
见小插曲（“rooSolve”）为一个模型被指定在编译后的代码。此外，小插曲（“compiledCode”）从包装deSolve包含如何做到这一点的例子。

If func is a user-supplied R-function, it must be called as: yprime = func(t, y, parms,...). t is the time at which the steady-state should be estimated, y is the current estimate of the variables in the ode system. 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 contains output variables whose values at steady-state are also required.
如果func是用户提供的R-函数，它必须的称为：yprime =功能（T，Y，PARMS，...）。 t是time的稳定状态，应估计，y是目前估计的颂歌系统中的变量。 func的返回值应该是一个列表的第一个元素是一个向量，就y的包含time的衍生工具，而其下一个元素都包含输出变量，其值在稳定状态也是必需的。

An example is given below:
下面给出一个例子：

model<-function(t,y,pars)<br> {<br> with (as.list(c(y,pars)),{<br>  Min       = r*OM<br> oxicmin   = Min*(O2/(O2+ks))<br> anoxicmin = Min*(1-O2/(O2+ks))* SO4/(SO4+ks2<br> dOM  = Flux - oxicmin - anoxicmin<br> dO2  = -oxicmin      -2*rox*HS*(O2/(O2+ks)) + D*(BO2-O2)<br> dSO4 = -0.5*anoxicmin  +rox*HS*(O2/(O2+ks)) + D*(BSO4-SO4)<br> dHS  =  0.5*anoxicmin  -rox*HS*(O2/(O2+ks)) + D*(BHS-HS)
model<-function(t,y,pars)参考{参考with (as.list(c(y,pars)),{参考Min       = r*OM参考oxicmin   = Min*(O2/(O2+ks))参考anoxicmin = Min*(1-O2/(O2+ks))* SO4/(SO4+ks2参考 X>参考dOM  = Flux - oxicmin - anoxicmin参考dO2  = -oxicmin      -2*rox*HS*(O2/(O2+ks)) + D*(BO2-O2)参考dSO4 = -0.5*anoxicmin  +rox*HS*(O2/(O2+ks)) + D*(BSO4-SO4)

list(c(dOM,dO2,dSO4,dHS),SumS=SO4+HS)<br> })<br> }<br>
list(c(dOM,dO2,dSO4,dHS),SumS=SO4+HS)参考})参考}<BR>

This model can be solved as follows:
该模型可以解决如下：

pars <- c(D=1,Flux=100,r=0.1,rox =1,<br> ks=1,ks2=1,BO2=100,BSO4=10000,BHS = 0)<br>      
pars <- c(D=1,Flux=100,r=0.1,rox =1,参考ks=1,ks2=1,BO2=100,BSO4=10000,BHS = 0)参考

y<-c(OM=1,O2=1,SO4=1,HS=1)<br>        ST <- stode(y=y,func=model,parms=pars,pos=TRUE))<br>
y<-c(OM=1,O2=1,SO4=1,HS=1)参考ST <- stode(y=y,func=model,parms=pars,pos=TRUE))参考


值----------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. If y has a names attribute, it will be used to label the output values.  
从最后一次迭代在估算过程中的方程系统的稳态状况的状态变量值的一个矢量。如果y有一个名称属性，它会被用来标注的输出值。


参数：...
the number of "global" values returned.  
返回的“全球性”的价值观。

The output will have the attribute steady, which returns TRUE, if steady-state has been reached and the attribute precis with an estimate of the precision attained during each iteration, the mean absolute rate of change (sum(abs(dy))/n).
输出将有steady，它返回的属性TRUE，如果稳态已达到和属性precis达到的精度在每次迭代的估计，平均绝对速度变动（总和（绝对值（DY））/ n）的。


注意----------Note----------

The implementation of stode and substantial parts of the help file is similar to the implementation of the integration routines (e.g. lsode) from package deSolve.
stode和大量的帮助文件实施的积分程序的执行类似的（例如lsode）从包deSolve的。


（作者）----------Author(s)----------



Karline Soetaert &lt;karline.soetaert@nioz.nl&gt;




参考文献----------References----------


Numerical Recipes in FORTRAN. The Art of Scientific computing. 2nd edition. Cambridge University Press.

LINPACK user's guide, SIAM, Philadelphia.

参见----------See Also----------

steady, for a general interface to most of the steady-state solvers
steady，一个通用的接口，大部分的稳态解算器

steady.band, to find the steady-state of ODE models with a banded Jacobian
steady.band，找到稳定状态的ODE模型的一个带状的雅可比

steady.1D, steady.2D, steady.3D steady-state solvers for 1-D, 2-D and 3-D partial differential equations.
steady.1D，steady.2D，steady.3D1-D，2-D和3-D偏微分方程的稳态解算器。

stodes, iterative steady-state solver for ODEs with arbitrary sparse Jacobian.
stodes，常微分方程任意稀疏Jacobian迭代稳态解算器。

runsteady, steady-state solver by dynamically running to steady-state
runsteady，通过动态运行到稳定状态的稳态求解器


实例----------Examples----------


## =======================================================================[＃================================================= ======================]
## Example 1. A simple sediment biogeochemical model[＃示例1。一个简单的沉积物生物地球化学模型]
## =======================================================================[＃================================================= ======================]

model<-function(t, y, pars)
{

with (as.list(c(y, pars)),{

  Min       = r*OM
  oxicmin   = Min*(O2/(O2+ks))
  anoxicmin = Min*(1-O2/(O2+ks))* SO4/(SO4+ks2)

  dOM  = Flux - oxicmin - anoxicmin
  dO2  = -oxicmin      -2*rox*HS*(O2/(O2+ks)) + D*(BO2-O2)
  dSO4 = -0.5*anoxicmin  +rox*HS*(O2/(O2+ks)) + D*(BSO4-SO4)
  dHS  = 0.5*anoxicmin   -rox*HS*(O2/(O2+ks)) + D*(BHS-HS)

  list(c(dOM, dO2, dSO4, dHS), SumS = SO4+HS)
})
}

# parameter values[参数值]
pars <- c(D = 1, Flux = 100, r = 0.1, rox = 1,
          ks = 1, ks2 = 1, BO2 = 100, BSO4 = 10000, BHS = 0)
# initial conditions[初始条件]
y<-c(OM = 1, O2 = 1, SO4 = 1, HS = 1)

# direct iteration  - enforces  positivitiy..[直接迭代 - 强制执行positivitiy ..]
ST <- stode(y = y, func = model, parms = pars, pos = TRUE)

ST

## =======================================================================[＃================================================= ======================]
## Example 2. 1000 simultaneous equations[＃例2。 1000联立方程组]
## =======================================================================[＃================================================= ======================]

model <- function (time, OC, parms, decay, ing) {
# model describing organic Carbon (C) in a sediment, [模型在沉积物中的有机碳（C），]
# Upper boundary = imposed flux, lower boundary = zero-gradient[上边界=施加通量，下边界=零梯度]
Flux  &lt;- v * c(OC[1] ,OC) +              # advection[平流]
          -Kz*diff(c(OC[1],OC,OC[N]))/dx  # diffusion;[扩散;]
Flux[1]&lt;- flux     # imposed flux[征收通量]

# Rate of change= Flux gradient and first-order consumption[变化率=通量梯度和一阶消费]
dOC   <- -diff(Flux)/dx - decay*OC

# Fraction of OC in first 5 layers is translocated to mean depth[业主立案法团的分数被转运至第5层平均深度]
dOC[1:5]  <- dOC[1:5] - ing*OC[1:5]
dOC[N/2]  <- dOC[N/2] + ing*sum(OC[1:5])
list(dOC)
}

v    &lt;- 0.1    # cm/yr[厘米/年]
flux <- 10
dx   <- 0.01
N    <- 1000
dist <- seq(dx/2,by=dx,len=N)
Kz   &lt;- 1  #bioturbation (diffusion), cm2/yr[生物扰动（扩散），cm2/yr的]
print( system.time(
ss   <- stode(runif(N), func = model, parms = NULL, positive = TRUE,
              decay = 5, ing = 20)))

plot(ss$y[1:N], dist, ylim = rev(range(dist)), type = "l", lwd = 2,
     xlab = "Nonlocal exchange", ylab = "sediment depth",
     main = "stode, full jacobian")

## =======================================================================[＃================================================= ======================]
## Example 3. Solving a system of linear equations[＃3。一个系统的线性方程组的求解]
## =======================================================================[＃================================================= ======================]

# this example is included to demonstrate how to use the "jactype" option.[这个例子演示了如何使用的“jactype”选项。]
# (and that stode is quite efficient).[（及，stode是相当有效的）。]

A <- matrix(nrow = 500, ncol = 500, runif(500*500))
B <- 1:500

# this is how one would solve this in R[这是怎么一会解决这个问题在R]
print(system.time(X1 <- solve(A, B)))

# to use stode:[使用stode：]
# 1. create a function that receives the current estimate of x[1。创建一个函数，接收，目前估计的x]
# and that returns the difference A%*%x-b, as a list:[和返回A％*％的XB，作为一个列表：]

fun &lt;- function (t, x, p)  # t and p are dummies here...[t和p在这里的伪...]
  list(A%*%x-B)

# 2. jfun returns the Jacobian: here this equals "A"[2。 jfun返回的雅可比在这等于“A”]
jfun &lt;- function (t, x, p) # all input parameters are dummies[所有的输入参数是傻瓜]
  A

# 3. solve with jactype="fullusr" (a full Jacobian, specified by user)[3。解决的jactype =的“fullusr”（一个完整的雅可比矩阵，由用户指定）]
print (system.time(
  X <- stode(y = 1:500, func = fun, jactype = "fullusr", jacfunc = jfun)
  ))

# the results are the same (within precision)[的结果是相同的（精度）]
sum((X1-X$y)^2)

转载请注明:出自 生物统计家园网(http://www.biostatistic.net)。


注：
注1：为了方便大家学习，本文档为生物统计家园网机器人LoveR翻译而成，仅供个人R语言学习参考使用，生物统计家园保留版权。
注2：由于是机器人自动翻译，难免有不准确之处，使用时仔细对照中、英文内容进行反复理解，可以帮助R语言的学习。
注3：如遇到不准确之处，请在本贴的后面进行回帖，我们会逐渐进行修订。