From fe506214a306985bc4080b796c54fac9f8eb6bee Mon Sep 17 00:00:00 2001 From: Louis Aslett Date: Fri, 23 Aug 2024 19:20:55 +0100 Subject: [PATCH] Further docs tidying, bringing opre_l up to date and also improving references to literature with DOI links etc --- R/RcppExports.R | 4 ++-- R/mlmc.R | 6 +++--- R/opre_l.R | 46 ++++++++++++++++++++++++++-------------------- R/plot.mlmc.test.R | 1 + man/mcqmc06_l.Rd | 4 ++-- man/mlmc.Rd | 6 +++--- man/opre_l.Rd | 46 ++++++++++++++++++++++++++-------------------- src/mcqmc06_l.cpp | 4 ++-- 8 files changed, 65 insertions(+), 52 deletions(-) diff --git a/R/RcppExports.R b/R/RcppExports.R index e616465..84fd44d 100644 --- a/R/RcppExports.R +++ b/R/RcppExports.R @@ -3,7 +3,7 @@ #' Financial options using a Milstein discretisation #' -#' Financial options based on scalar geometric Brownian motion, similar to Mike Giles' MCQMC06 paper, using a Milstein discretisation. +#' Financial options based on scalar geometric Brownian motion, similar to Mike Giles' MCQMC06 paper, Giles (2008), using a Milstein discretisation. #' #' This function is based on GPL-2 C++ code by Mike Giles. #' @@ -26,7 +26,7 @@ #' @author Mike Giles #' #' @references -#' M.B. Giles. 'Improved multilevel Monte Carlo convergence using the Milstein scheme', p.343-358 in \emph{Monte Carlo and Quasi-Monte Carlo Methods 2006}, Springer, 2007. +#' Giles, M. (2008) 'Improved Multilevel Monte Carlo Convergence using the Milstein Scheme', in A. Keller, S. Heinrich, and H. Niederreiter (eds) \emph{Monte Carlo and Quasi-Monte Carlo Methods 2006}. Berlin, Heidelberg: Springer, pp. 343–358. Available at: \url{https://doi.org/10.1007/978-3-540-74496-2_20}. #' #' @examples #' \dontrun{ diff --git a/R/mlmc.R b/R/mlmc.R index 3322c56..a618bb4 100644 --- a/R/mlmc.R +++ b/R/mlmc.R @@ -27,11 +27,11 @@ #' @author Tigran Nagapetyan #' #' @references -#' M.B. Giles. Multilevel Monte Carlo path simulation. \emph{Operations Research}, 56(3):607-617, 2008. +#' Giles, M.B. (2008) 'Multilevel Monte Carlo Path Simulation', \emph{Operations Research}, 56(3), pp. 607–617. Available at: \url{https://doi.org/10.1287/opre.1070.0496}. #' -#' M.B. Giles. Multilevel Monte Carlo methods. \emph{Acta Numerica}, 24:259-328, 2015. +#' Giles, M.B. (2015) 'Multilevel Monte Carlo methods', \emph{Acta Numerica}, 24, pp. 259–328. Available at: \url{https://doi.org/10.1017/S096249291500001X}. #' -#' S. Heinrich. Monte Carlo complexity of global solution of integral equations. \emph{Journal of Complexity}, 14(2):151-175, 1998. +#' Heinrich, S. (1998) 'Monte Carlo Complexity of Global Solution of Integral Equations', \emph{Journal of Complexity}, 14(2), pp. 151–175. Available at: \url{https://doi.org/10.1006/jcom.1998.0471}. #' #' @param Lmin #' the minimum level of refinement. Must be \eqn{\ge 2}. diff --git a/R/opre_l.R b/R/opre_l.R index 2e1dfa0..4baf712 100644 --- a/R/opre_l.R +++ b/R/opre_l.R @@ -15,7 +15,7 @@ mu <- function(x, h) { #' Financial options using an Euler-Maruyama discretisation #' -#' Financial options based on scalar geometric Brownian motion and Heston models, similar to Mike Giles' original 2008 Operations Research paper, using an Euler-Maruyama discretisation +#' Financial options based on scalar geometric Brownian motion and Heston models, similar to Mike Giles' original 2008 Operations Research paper, Giles (2008), using an Euler-Maruyama discretisation #' #' This function is based on GPL-2 'Matlab' code by Mike Giles. #' @@ -39,7 +39,7 @@ mu <- function(x, h) { #' @author Tigran Nagapetyan #' #' @references -#' M.B. Giles. Multilevel Monte Carlo path simulation. \emph{Operations Research}, 56(3):607-617, 2008. +#' Giles, M.B. (2008) 'Multilevel Monte Carlo Path Simulation', \emph{Operations Research}, 56(3), pp. 607–617. Available at: \url{https://doi.org/10.1287/opre.1070.0496}. #' #' @examples #' \dontrun{ @@ -53,41 +53,40 @@ mu <- function(x, h) { #' # -- the new MLMC driver is a little different #' # -- switch to X_0=100 instead of X_0=1 #' -#' M <- 4 # refinement cost factor #' N0 <- 1000 # initial samples on coarse levels #' Lmin <- 2 # minimum refinement level #' Lmax <- 6 # maximum refinement level #' #' test.res <- list() #' for(option in 1:5) { -#' if(option==1) { +#' if(option == 1) { #' cat("\n ---- Computing European call ---- \n") -#' N <- 2000000 # samples for convergence tests +#' N <- 1000000 # samples for convergence tests #' L <- 5 # levels for convergence tests #' Eps <- c(0.005, 0.01, 0.02, 0.05, 0.1) -#' } else if(option==2) { +#' } else if(option == 2) { #' cat("\n ---- Computing Asian call ---- \n") -#' N <- 2000000 # samples for convergence tests +#' N <- 1000000 # samples for convergence tests #' L <- 5 # levels for convergence tests #' Eps <- c(0.005, 0.01, 0.02, 0.05, 0.1) -#' } else if(option==3) { +#' } else if(option == 3) { #' cat("\n ---- Computing lookback call ---- \n") -#' N <- 2000000 # samples for convergence tests +#' N <- 1000000 # samples for convergence tests #' L <- 5 # levels for convergence tests #' Eps <- c(0.01, 0.02, 0.05, 0.1, 0.2) -#' } else if(option==4) { +#' } else if(option == 4) { #' cat("\n ---- Computing digital call ---- \n") -#' N <- 3000000 # samples for convergence tests +#' N <- 4000000 # samples for convergence tests #' L <- 5 # levels for convergence tests #' Eps <- c(0.02, 0.05, 0.1, 0.2, 0.5) -#' } else if(option==5) { +#' } else if(option == 5) { #' cat("\n ---- Computing Heston model ---- \n") #' N <- 2000000 # samples for convergence tests #' L <- 5 # levels for convergence tests #' Eps <- c(0.005, 0.01, 0.02, 0.05, 0.1) #' } #' -#' test.res[[option]] <- mlmc.test(opre_l, M, N, L, N0, Eps, Lmin, Lmax, option=option) +#' test.res[[option]] <- mlmc.test(opre_l, N, L, N0, Eps, Lmin, Lmax, option = option) #' #' # print exact analytic value, based on S0=K #' T <- 1 @@ -95,18 +94,25 @@ mu <- function(x, h) { #' sig <- 0.2 #' K <- 100 #' +#' k <- 0.5*sig^2/r; #' d1 <- (r+0.5*sig^2)*T / (sig*sqrt(T)) #' d2 <- (r-0.5*sig^2)*T / (sig*sqrt(T)) #' -#' if(option==1) { +#' if(option == 1) { #' val <- K*( pnorm(d1) - exp(-r*T)*pnorm(d2) ) -#' cat(sprintf("\n Exact value: %f, MLMC value: %f \n", val, test.res[[option]]$P[1])) -#' } else if(option==3) { -#' k <- 0.5*sig^2/r +#' } else if(option == 2) { +#' val <- NA +#' } else if(option == 3) { #' val <- K*( pnorm(d1) - pnorm(-d1)*k - exp(-r*T)*(pnorm(d2) - pnorm(d2)*k) ) -#' cat(sprintf("\n Exact value: %f, MLMC value: %f \n", val, test.res[[option]]$P[1])) -#' } else if(option==4) { +#' } else if(option == 4) { #' val <- K*exp(-r*T)*pnorm(d2) +#' } else if(option == 5) { +#' val <- NA +#' } +#' +#' if(is.na(val)) { +#' cat(sprintf("\n Exact value unknown, MLMC value: %f \n", test.res[[option]]$P[1])) +#' } else { #' cat(sprintf("\n Exact value: %f, MLMC value: %f \n", val, test.res[[option]]$P[1])) #' } #' @@ -116,7 +122,7 @@ mu <- function(x, h) { #' } #' #' # The level sampler can be called directly to retrieve the relevant level sums: -#' opre_l(l=7, N=10, option=1) +#' opre_l(l = 7, N = 10, option = 1) #' #' @importFrom stats rnorm #' @export diff --git a/R/plot.mlmc.test.R b/R/plot.mlmc.test.R index 3f126d6..ac21a4e 100644 --- a/R/plot.mlmc.test.R +++ b/R/plot.mlmc.test.R @@ -27,6 +27,7 @@ #' #' @references #' Giles, M.B. (2015) 'Multilevel Monte Carlo methods', \emph{Acta Numerica}, 24, pp. 259–328. Available at: \url{https://doi.org/10.1017/S096249291500001X}. +#' #' @examples #' \dontrun{ #' tst <- mlmc.test(opre_l, N = 2000000, diff --git a/man/mcqmc06_l.Rd b/man/mcqmc06_l.Rd index 8c5dc28..67a8496 100644 --- a/man/mcqmc06_l.Rd +++ b/man/mcqmc06_l.Rd @@ -22,7 +22,7 @@ The options are: }} } \description{ -Financial options based on scalar geometric Brownian motion, similar to Mike Giles' MCQMC06 paper, using a Milstein discretisation. +Financial options based on scalar geometric Brownian motion, similar to Mike Giles' MCQMC06 paper, Giles (2008), using a Milstein discretisation. } \details{ This function is based on GPL-2 C++ code by Mike Giles. @@ -83,7 +83,7 @@ mcqmc06_l(l = 7, N = 10, option = 1) } \references{ -M.B. Giles. 'Improved multilevel Monte Carlo convergence using the Milstein scheme', p.343-358 in \emph{Monte Carlo and Quasi-Monte Carlo Methods 2006}, Springer, 2007. +Giles, M. (2008) 'Improved Multilevel Monte Carlo Convergence using the Milstein Scheme', in A. Keller, S. Heinrich, and H. Niederreiter (eds) \emph{Monte Carlo and Quasi-Monte Carlo Methods 2006}. Berlin, Heidelberg: Springer, pp. 343–358. Available at: \url{https://doi.org/10.1007/978-3-540-74496-2_20}. } \author{ Louis Aslett diff --git a/man/mlmc.Rd b/man/mlmc.Rd index 0d32e06..fc38e9e 100644 --- a/man/mlmc.Rd +++ b/man/mlmc.Rd @@ -92,11 +92,11 @@ mlmc(2, 10, 1000, 0.01, mcqmc06_l, option = 1) } \references{ -M.B. Giles. Multilevel Monte Carlo path simulation. \emph{Operations Research}, 56(3):607-617, 2008. +Giles, M.B. (2008) 'Multilevel Monte Carlo Path Simulation', \emph{Operations Research}, 56(3), pp. 607–617. Available at: \url{https://doi.org/10.1287/opre.1070.0496}. -M.B. Giles. Multilevel Monte Carlo methods. \emph{Acta Numerica}, 24:259-328, 2015. +Giles, M.B. (2015) 'Multilevel Monte Carlo methods', \emph{Acta Numerica}, 24, pp. 259–328. Available at: \url{https://doi.org/10.1017/S096249291500001X}. -S. Heinrich. Monte Carlo complexity of global solution of integral equations. \emph{Journal of Complexity}, 14(2):151-175, 1998. +Heinrich, S. (1998) 'Monte Carlo Complexity of Global Solution of Integral Equations', \emph{Journal of Complexity}, 14(2), pp. 151–175. Available at: \url{https://doi.org/10.1006/jcom.1998.0471}. } \author{ Louis Aslett diff --git a/man/opre_l.Rd b/man/opre_l.Rd index c9b2093..00d1f78 100644 --- a/man/opre_l.Rd +++ b/man/opre_l.Rd @@ -22,7 +22,7 @@ The options are: }} } \description{ -Financial options based on scalar geometric Brownian motion and Heston models, similar to Mike Giles' original 2008 Operations Research paper, using an Euler-Maruyama discretisation +Financial options based on scalar geometric Brownian motion and Heston models, similar to Mike Giles' original 2008 Operations Research paper, Giles (2008), using an Euler-Maruyama discretisation } \details{ This function is based on GPL-2 'Matlab' code by Mike Giles. @@ -39,41 +39,40 @@ This function is based on GPL-2 'Matlab' code by Mike Giles. # -- the new MLMC driver is a little different # -- switch to X_0=100 instead of X_0=1 -M <- 4 # refinement cost factor N0 <- 1000 # initial samples on coarse levels Lmin <- 2 # minimum refinement level Lmax <- 6 # maximum refinement level test.res <- list() for(option in 1:5) { - if(option==1) { + if(option == 1) { cat("\n ---- Computing European call ---- \n") - N <- 2000000 # samples for convergence tests + N <- 1000000 # samples for convergence tests L <- 5 # levels for convergence tests Eps <- c(0.005, 0.01, 0.02, 0.05, 0.1) - } else if(option==2) { + } else if(option == 2) { cat("\n ---- Computing Asian call ---- \n") - N <- 2000000 # samples for convergence tests + N <- 1000000 # samples for convergence tests L <- 5 # levels for convergence tests Eps <- c(0.005, 0.01, 0.02, 0.05, 0.1) - } else if(option==3) { + } else if(option == 3) { cat("\n ---- Computing lookback call ---- \n") - N <- 2000000 # samples for convergence tests + N <- 1000000 # samples for convergence tests L <- 5 # levels for convergence tests Eps <- c(0.01, 0.02, 0.05, 0.1, 0.2) - } else if(option==4) { + } else if(option == 4) { cat("\n ---- Computing digital call ---- \n") - N <- 3000000 # samples for convergence tests + N <- 4000000 # samples for convergence tests L <- 5 # levels for convergence tests Eps <- c(0.02, 0.05, 0.1, 0.2, 0.5) - } else if(option==5) { + } else if(option == 5) { cat("\n ---- Computing Heston model ---- \n") N <- 2000000 # samples for convergence tests L <- 5 # levels for convergence tests Eps <- c(0.005, 0.01, 0.02, 0.05, 0.1) } - test.res[[option]] <- mlmc.test(opre_l, M, N, L, N0, Eps, Lmin, Lmax, option=option) + test.res[[option]] <- mlmc.test(opre_l, N, L, N0, Eps, Lmin, Lmax, option = option) # print exact analytic value, based on S0=K T <- 1 @@ -81,18 +80,25 @@ for(option in 1:5) { sig <- 0.2 K <- 100 + k <- 0.5*sig^2/r; d1 <- (r+0.5*sig^2)*T / (sig*sqrt(T)) d2 <- (r-0.5*sig^2)*T / (sig*sqrt(T)) - if(option==1) { + if(option == 1) { val <- K*( pnorm(d1) - exp(-r*T)*pnorm(d2) ) - cat(sprintf("\n Exact value: \%f, MLMC value: \%f \n", val, test.res[[option]]$P[1])) - } else if(option==3) { - k <- 0.5*sig^2/r + } else if(option == 2) { + val <- NA + } else if(option == 3) { val <- K*( pnorm(d1) - pnorm(-d1)*k - exp(-r*T)*(pnorm(d2) - pnorm(d2)*k) ) - cat(sprintf("\n Exact value: \%f, MLMC value: \%f \n", val, test.res[[option]]$P[1])) - } else if(option==4) { + } else if(option == 4) { val <- K*exp(-r*T)*pnorm(d2) + } else if(option == 5) { + val <- NA + } + + if(is.na(val)) { + cat(sprintf("\n Exact value unknown, MLMC value: \%f \n", test.res[[option]]$P[1])) + } else { cat(sprintf("\n Exact value: \%f, MLMC value: \%f \n", val, test.res[[option]]$P[1])) } @@ -102,11 +108,11 @@ for(option in 1:5) { } # The level sampler can be called directly to retrieve the relevant level sums: -opre_l(l=7, N=10, option=1) +opre_l(l = 7, N = 10, option = 1) } \references{ -M.B. Giles. Multilevel Monte Carlo path simulation. \emph{Operations Research}, 56(3):607-617, 2008. +Giles, M.B. (2008) 'Multilevel Monte Carlo Path Simulation', \emph{Operations Research}, 56(3), pp. 607–617. Available at: \url{https://doi.org/10.1287/opre.1070.0496}. } \author{ Louis Aslett diff --git a/src/mcqmc06_l.cpp b/src/mcqmc06_l.cpp index d17ff68..7a6ab66 100644 --- a/src/mcqmc06_l.cpp +++ b/src/mcqmc06_l.cpp @@ -8,7 +8,7 @@ using namespace Rcpp; //' Financial options using a Milstein discretisation //' -//' Financial options based on scalar geometric Brownian motion, similar to Mike Giles' MCQMC06 paper, using a Milstein discretisation. +//' Financial options based on scalar geometric Brownian motion, similar to Mike Giles' MCQMC06 paper, Giles (2008), using a Milstein discretisation. //' //' This function is based on GPL-2 C++ code by Mike Giles. //' @@ -31,7 +31,7 @@ using namespace Rcpp; //' @author Mike Giles //' //' @references -//' M.B. Giles. 'Improved multilevel Monte Carlo convergence using the Milstein scheme', p.343-358 in \emph{Monte Carlo and Quasi-Monte Carlo Methods 2006}, Springer, 2007. +//' Giles, M. (2008) 'Improved Multilevel Monte Carlo Convergence using the Milstein Scheme', in A. Keller, S. Heinrich, and H. Niederreiter (eds) \emph{Monte Carlo and Quasi-Monte Carlo Methods 2006}. Berlin, Heidelberg: Springer, pp. 343–358. Available at: \url{https://doi.org/10.1007/978-3-540-74496-2_20}. //' //' @examples //' \dontrun{