Support time to expiry or maturity date in AmericanOption

Author: eddelbuettel

ChangeLog

@@ -1,10 +1,11 @@
 2026-03-09  Dirk Eddelbuettel  <edd@debian.org>
 
-	* src/vanilla.cpp (europeanOptionEngine): More careful about use of evaluation date,
-	new parameter daycounter
-	* R/option.R (EuropeanOption.default): Allow fractional year to
-	expiry as well as date, support daycounter
-	* man/EuropeanOption.Rd: Updated
+	* src/vanilla.cpp (europeanOptionEngine,americanOptionEngine): More
+	careful about use of evaluation date, new parameter daycounter
+	* R/option.R (EuropeanOption.default,AmericanOption.default): Allow
+	fractional year to expiry as well as date, support daycounter
+	* man/AmericanOption.Rd: Updated
+	* man/EuropeanOption.Rd: Idem
 	* inst/include/RQuantLib_RcppExports.h: Regenerated
 	* src/RcppExports.cpp: Idem
 	* R/RcppExports.R: Idem

R/RcppExports.R

@@ -232,8 +232,8 @@ europeanOptionEngine <- function(type, underlying, strike, dividendYield, riskFr
     .Call(`_RQuantLib_europeanOptionEngine`, type, underlying, strike, dividendYield, riskFreeRate, maturity, exDate, volatility, discreteDividends, discreteDividendsTimeUntil, dayCounter)
 }
 
-americanOptionEngine <- function(type, underlying, strike, dividendYield, riskFreeRate, maturity, volatility, timeSteps, gridPoints, engine, discreteDividends, discreteDividendsTimeUntil) {
-    .Call(`_RQuantLib_americanOptionEngine`, type, underlying, strike, dividendYield, riskFreeRate, maturity, volatility, timeSteps, gridPoints, engine, discreteDividends, discreteDividendsTimeUntil)
+americanOptionEngine <- function(type, underlying, strike, dividendYield, riskFreeRate, maturity, exDate, volatility, timeSteps, gridPoints, engine, discreteDividends, discreteDividendsTimeUntil, dayCounter) {
+    .Call(`_RQuantLib_americanOptionEngine`, type, underlying, strike, dividendYield, riskFreeRate, maturity, exDate, volatility, timeSteps, gridPoints, engine, discreteDividends, discreteDividendsTimeUntil, dayCounter)
 }
 
 europeanOptionArraysEngine <- function(type, par) {

R/option.R

@@ -39,23 +39,24 @@ EuropeanOption.default <- function(type, underlying, strike, dividendYield,
 
 AmericanOption <- function(type, underlying, strike, dividendYield,
                            riskFreeRate, maturity, volatility,
-                           timeSteps=150, gridPoints=149,
-                           engine="BaroneAdesiWhaley",
-                           discreteDividends = NULL, discreteDividendsTimeUntil = NULL) {
+                           timeSteps=150, gridPoints=149, engine="BaroneAdesiWhaley",
+                           discreteDividends = NULL, discreteDividendsTimeUntil = NULL,
+                           dayCounter = 0) {
     UseMethod("AmericanOption")
 }
 
 AmericanOption.default <- function(type, underlying, strike, dividendYield,
                                    riskFreeRate, maturity, volatility,
-                                   timeSteps=150, gridPoints=149,
-                                   engine="BaroneAdesiWhaley",
-                                   discreteDividends = NULL, discreteDividendsTimeUntil = NULL) {
+                                   timeSteps=150, gridPoints=149, engine="BaroneAdesiWhaley",
+                                   discreteDividends = NULL, discreteDividendsTimeUntil = NULL,
+                                   dayCounter = 0) {
     type <- match.arg(type, c("call", "put"))
     engine <- match.arg(engine, c("BaroneAdesiWhaley", "CrankNicolson"))
-    val <- americanOptionEngine(type, underlying, strike, dividendYield,
-                                riskFreeRate, maturity, volatility,
-                                timeSteps, gridPoints, engine,
-                                discreteDividends, discreteDividendsTimeUntil)
+    val <- americanOptionEngine(type, underlying, strike, dividendYield, riskFreeRate,
+                                if (inherits(maturity, "numeric")) maturity else NULL,
+                                if (inherits(maturity, "Date")) maturity else NULL,
+                                volatility, timeSteps, gridPoints, engine,
+                                discreteDividends, discreteDividendsTimeUntil, dayCounter)
     class(val) <- c("AmericanOption","Option")
     val
 }

inst/include/RQuantLib_RcppExports.h

@@ -612,17 +612,17 @@ namespace RQuantLib {
         return Rcpp::as<Rcpp::List >(rcpp_result_gen);
     }
 
-    inline Rcpp::List americanOptionEngine(std::string type, double underlying, double strike, double dividendYield, double riskFreeRate, double maturity, double volatility, int timeSteps, int gridPoints, std::string engine, Rcpp::Nullable<Rcpp::NumericVector> discreteDividends, Rcpp::Nullable<Rcpp::NumericVector> discreteDividendsTimeUntil) {
-        typedef SEXP(*Ptr_americanOptionEngine)(SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP);
+    inline Rcpp::List americanOptionEngine(std::string type, double underlying, double strike, double dividendYield, double riskFreeRate, Rcpp::Nullable<double> maturity, Rcpp::Nullable<QuantLib::Date> exDate, double volatility, int timeSteps, int gridPoints, std::string engine, Rcpp::Nullable<Rcpp::NumericVector> discreteDividends, Rcpp::Nullable<Rcpp::NumericVector> discreteDividendsTimeUntil, int dayCounter) {
+        typedef SEXP(*Ptr_americanOptionEngine)(SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP,SEXP);
         static Ptr_americanOptionEngine p_americanOptionEngine = NULL;
         if (p_americanOptionEngine == NULL) {
-            validateSignature("Rcpp::List(*americanOptionEngine)(std::string,double,double,double,double,double,double,int,int,std::string,Rcpp::Nullable<Rcpp::NumericVector>,Rcpp::Nullable<Rcpp::NumericVector>)");
+            validateSignature("Rcpp::List(*americanOptionEngine)(std::string,double,double,double,double,Rcpp::Nullable<double>,Rcpp::Nullable<QuantLib::Date>,double,int,int,std::string,Rcpp::Nullable<Rcpp::NumericVector>,Rcpp::Nullable<Rcpp::NumericVector>,int)");
             p_americanOptionEngine = (Ptr_americanOptionEngine)R_GetCCallable("RQuantLib", "_RQuantLib_americanOptionEngine");
         }
         RObject rcpp_result_gen;
         {
             RNGScope RCPP_rngScope_gen;
-            rcpp_result_gen = p_americanOptionEngine(Shield<SEXP>(Rcpp::wrap(type)), Shield<SEXP>(Rcpp::wrap(underlying)), Shield<SEXP>(Rcpp::wrap(strike)), Shield<SEXP>(Rcpp::wrap(dividendYield)), Shield<SEXP>(Rcpp::wrap(riskFreeRate)), Shield<SEXP>(Rcpp::wrap(maturity)), Shield<SEXP>(Rcpp::wrap(volatility)), Shield<SEXP>(Rcpp::wrap(timeSteps)), Shield<SEXP>(Rcpp::wrap(gridPoints)), Shield<SEXP>(Rcpp::wrap(engine)), Shield<SEXP>(Rcpp::wrap(discreteDividends)), Shield<SEXP>(Rcpp::wrap(discreteDividendsTimeUntil)));
+            rcpp_result_gen = p_americanOptionEngine(Shield<SEXP>(Rcpp::wrap(type)), Shield<SEXP>(Rcpp::wrap(underlying)), Shield<SEXP>(Rcpp::wrap(strike)), Shield<SEXP>(Rcpp::wrap(dividendYield)), Shield<SEXP>(Rcpp::wrap(riskFreeRate)), Shield<SEXP>(Rcpp::wrap(maturity)), Shield<SEXP>(Rcpp::wrap(exDate)), Shield<SEXP>(Rcpp::wrap(volatility)), Shield<SEXP>(Rcpp::wrap(timeSteps)), Shield<SEXP>(Rcpp::wrap(gridPoints)), Shield<SEXP>(Rcpp::wrap(engine)), Shield<SEXP>(Rcpp::wrap(discreteDividends)), Shield<SEXP>(Rcpp::wrap(discreteDividendsTimeUntil)), Shield<SEXP>(Rcpp::wrap(dayCounter)));
         }
         if (rcpp_result_gen.inherits("interrupted-error"))
             throw Rcpp::internal::InterruptedException();

man/AmericanOption.Rd

@@ -8,17 +8,18 @@ using finite differences. The option value as well as the common first
 derivatives ("Greeks") are returned.}
 \usage{
 \method{AmericanOption}{default}(type, underlying, strike,
-		dividendYield, riskFreeRate, maturity, volatility, 
-		timeSteps=150, gridPoints=149, engine="BaroneAdesiWhaley", 
-		discreteDividends, discreteDividendsTimeUntil)
+		dividendYield, riskFreeRate, maturity, volatility,
+		timeSteps=150, gridPoints=149, engine="BaroneAdesiWhaley",
+		discreteDividends, discreteDividendsTimeUntil, dayCounter)
 }
 \arguments{
   \item{type}{A string with one of the values \code{call} or \code{put}}
   \item{underlying}{Current price of the underlying stock}
   \item{strike}{Strike price of the option}
   \item{dividendYield}{Continuous dividend yield (as a fraction) of the stock}
   \item{riskFreeRate}{Risk-free rate}
-  \item{maturity}{Time to maturity (in fractional years)}
+  \item{maturity}{Time to maturity in either fractional years or as a
+    \sQuote{Date} object specifying the expiry date)}
   \item{volatility}{Volatility of the underlying stock}
   \item{timeSteps}{Time steps for the \dQuote{CrankNicolson} finite
     differences method engine, default value is 150}
@@ -27,18 +28,20 @@ derivatives ("Greeks") are returned.}
   \item{engine}{String selecting pricing engine, currently supported are
     \dQuote{BaroneAdesiWhaley} and \dQuote{CrankNicolson}}
   \item{discreteDividends}{Vector of discrete dividends (optional)}
-  \item{discreteDividendsTimeUntil}{Vector of times to discrete dividends 
+  \item{discreteDividendsTimeUntil}{Vector of times to discrete dividends
     (in fractional years, optional)}
+  \item{dayCounter}{Integer denoting the selected QuantLib day counter
+    convention, default value is 0 for \sQuote{Actual360}}
 }
 \value{
   An object of class \code{AmericanOption} (which inherits from class
   \code{\link{Option}}) is returned. It contains a list with the
-  following components: 
+  following components:
   \item{value}{Value of option}
   \item{delta}{Sensitivity of the option value for a change in the underlying}
   \item{gamma}{Sensitivity of the option delta for a change in the underlying}
   \item{vega}{Sensitivity of the option value for a change in the
-    underlying's volatility} 
+    underlying's volatility}
   \item{theta}{Sensitivity of the option value for a change in t, the
     remaining time to maturity}
   \item{rho}{Sensitivity of the option value for a change in the
@@ -51,16 +54,16 @@ derivatives ("Greeks") are returned.}
   \dQuote{CrankNicolson} is selected, then at least delta, gamma and
   vega are available. With the default pricing engine of
   \dQuote{BaroneAdesiWhaley}, no greeks are returned.
-  
+
   The \dQuote{CrankNicolson} engine needs to be used when setting
   discrete dividends.
 }
 \details{
   The Finite Differences method is used to value the American Option.
-  
+
   Please see any decent Finance textbook for background reading, and
   the \code{QuantLib} documentation for details on the \code{QuantLib}
-  implementation. 
+  implementation.
 }
 \references{\url{https://www.quantlib.org/} for details on \code{QuantLib}.}
 \author{Dirk Eddelbuettel \email{edd@debian.org} for the \R interface;
@@ -78,4 +81,3 @@ AmericanOption("put", strike=100, volatility=0.4, 100, 0.02, 0.03, 0.5)
 AmericanOption("put", strike=100, volatility=0.4, 100, 0.02, 0.03, 0.5, engine="CrankNicolson")
 }
 \keyword{misc}
-

man/EuropeanOption.Rd

@@ -19,13 +19,15 @@
   \item{strike}{Strike price of the option}
   \item{dividendYield}{Continuous dividend yield (as a fraction) of the stock}
   \item{riskFreeRate}{Risk-free rate}
-  \item{maturity}{Time to maturity (in fractional years)}
+  \item{maturity}{Time to maturity in either fractional years or as a
+    \sQuote{Date} object specifying the expiry date)}
   \item{volatility}{Volatility of the underlying stock}
   \item{discreteDividends}{Vector of discrete dividends (optional)}
   \item{discreteDividendsTimeUntil}{Vector of times to discrete dividends
     (in fractional years, optional)}
   \item{dayCounter}{Integer denoting the selected QuantLib day counter
-    convention, default value is 0 for \sQuote{Actual360}}}
+    convention, default value is 0 for \sQuote{Actual360}}
+}
 \value{
   The \code{EuropeanOption} function returns an object of class
   \code{EuropeanOption} (which inherits from class

src/RcppExports.cpp

@@ -1521,31 +1521,33 @@ RcppExport SEXP _RQuantLib_europeanOptionEngine(SEXP typeSEXP, SEXP underlyingSE
     return rcpp_result_gen;
 }
 // americanOptionEngine
-Rcpp::List americanOptionEngine(std::string type, double underlying, double strike, double dividendYield, double riskFreeRate, double maturity, double volatility, int timeSteps, int gridPoints, std::string engine, Rcpp::Nullable<Rcpp::NumericVector> discreteDividends, Rcpp::Nullable<Rcpp::NumericVector> discreteDividendsTimeUntil);
-static SEXP _RQuantLib_americanOptionEngine_try(SEXP typeSEXP, SEXP underlyingSEXP, SEXP strikeSEXP, SEXP dividendYieldSEXP, SEXP riskFreeRateSEXP, SEXP maturitySEXP, SEXP volatilitySEXP, SEXP timeStepsSEXP, SEXP gridPointsSEXP, SEXP engineSEXP, SEXP discreteDividendsSEXP, SEXP discreteDividendsTimeUntilSEXP) {
+Rcpp::List americanOptionEngine(std::string type, double underlying, double strike, double dividendYield, double riskFreeRate, Rcpp::Nullable<double> maturity, Rcpp::Nullable<QuantLib::Date> exDate, double volatility, int timeSteps, int gridPoints, std::string engine, Rcpp::Nullable<Rcpp::NumericVector> discreteDividends, Rcpp::Nullable<Rcpp::NumericVector> discreteDividendsTimeUntil, int dayCounter);
+static SEXP _RQuantLib_americanOptionEngine_try(SEXP typeSEXP, SEXP underlyingSEXP, SEXP strikeSEXP, SEXP dividendYieldSEXP, SEXP riskFreeRateSEXP, SEXP maturitySEXP, SEXP exDateSEXP, SEXP volatilitySEXP, SEXP timeStepsSEXP, SEXP gridPointsSEXP, SEXP engineSEXP, SEXP discreteDividendsSEXP, SEXP discreteDividendsTimeUntilSEXP, SEXP dayCounterSEXP) {
 BEGIN_RCPP
     Rcpp::RObject rcpp_result_gen;
     Rcpp::traits::input_parameter< std::string >::type type(typeSEXP);
     Rcpp::traits::input_parameter< double >::type underlying(underlyingSEXP);
     Rcpp::traits::input_parameter< double >::type strike(strikeSEXP);
     Rcpp::traits::input_parameter< double >::type dividendYield(dividendYieldSEXP);
     Rcpp::traits::input_parameter< double >::type riskFreeRate(riskFreeRateSEXP);
-    Rcpp::traits::input_parameter< double >::type maturity(maturitySEXP);
+    Rcpp::traits::input_parameter< Rcpp::Nullable<double> >::type maturity(maturitySEXP);
+    Rcpp::traits::input_parameter< Rcpp::Nullable<QuantLib::Date> >::type exDate(exDateSEXP);
     Rcpp::traits::input_parameter< double >::type volatility(volatilitySEXP);
     Rcpp::traits::input_parameter< int >::type timeSteps(timeStepsSEXP);
     Rcpp::traits::input_parameter< int >::type gridPoints(gridPointsSEXP);
     Rcpp::traits::input_parameter< std::string >::type engine(engineSEXP);
     Rcpp::traits::input_parameter< Rcpp::Nullable<Rcpp::NumericVector> >::type discreteDividends(discreteDividendsSEXP);
     Rcpp::traits::input_parameter< Rcpp::Nullable<Rcpp::NumericVector> >::type discreteDividendsTimeUntil(discreteDividendsTimeUntilSEXP);
-    rcpp_result_gen = Rcpp::wrap(americanOptionEngine(type, underlying, strike, dividendYield, riskFreeRate, maturity, volatility, timeSteps, gridPoints, engine, discreteDividends, discreteDividendsTimeUntil));
+    Rcpp::traits::input_parameter< int >::type dayCounter(dayCounterSEXP);
+    rcpp_result_gen = Rcpp::wrap(americanOptionEngine(type, underlying, strike, dividendYield, riskFreeRate, maturity, exDate, volatility, timeSteps, gridPoints, engine, discreteDividends, discreteDividendsTimeUntil, dayCounter));
     return rcpp_result_gen;
 END_RCPP_RETURN_ERROR
 }
-RcppExport SEXP _RQuantLib_americanOptionEngine(SEXP typeSEXP, SEXP underlyingSEXP, SEXP strikeSEXP, SEXP dividendYieldSEXP, SEXP riskFreeRateSEXP, SEXP maturitySEXP, SEXP volatilitySEXP, SEXP timeStepsSEXP, SEXP gridPointsSEXP, SEXP engineSEXP, SEXP discreteDividendsSEXP, SEXP discreteDividendsTimeUntilSEXP) {
+RcppExport SEXP _RQuantLib_americanOptionEngine(SEXP typeSEXP, SEXP underlyingSEXP, SEXP strikeSEXP, SEXP dividendYieldSEXP, SEXP riskFreeRateSEXP, SEXP maturitySEXP, SEXP exDateSEXP, SEXP volatilitySEXP, SEXP timeStepsSEXP, SEXP gridPointsSEXP, SEXP engineSEXP, SEXP discreteDividendsSEXP, SEXP discreteDividendsTimeUntilSEXP, SEXP dayCounterSEXP) {
     SEXP rcpp_result_gen;
     {
         Rcpp::RNGScope rcpp_rngScope_gen;
-        rcpp_result_gen = PROTECT(_RQuantLib_americanOptionEngine_try(typeSEXP, underlyingSEXP, strikeSEXP, dividendYieldSEXP, riskFreeRateSEXP, maturitySEXP, volatilitySEXP, timeStepsSEXP, gridPointsSEXP, engineSEXP, discreteDividendsSEXP, discreteDividendsTimeUntilSEXP));
+        rcpp_result_gen = PROTECT(_RQuantLib_americanOptionEngine_try(typeSEXP, underlyingSEXP, strikeSEXP, dividendYieldSEXP, riskFreeRateSEXP, maturitySEXP, exDateSEXP, volatilitySEXP, timeStepsSEXP, gridPointsSEXP, engineSEXP, discreteDividendsSEXP, discreteDividendsTimeUntilSEXP, dayCounterSEXP));
     }
     Rboolean rcpp_isInterrupt_gen = Rf_inherits(rcpp_result_gen, "interrupted-error");
     if (rcpp_isInterrupt_gen) {
@@ -1663,7 +1665,7 @@ static int _RQuantLib_RcppExport_validate(const char* sig) {
         signatures.insert("std::string(*getQuantLibVersion)()");
         signatures.insert("Rcpp::LogicalVector(*getQuantLibCapabilities)()");
         signatures.insert("Rcpp::List(*europeanOptionEngine)(std::string,double,double,double,double,Rcpp::Nullable<double>,Rcpp::Nullable<QuantLib::Date>,double,Rcpp::Nullable<Rcpp::NumericVector>,Rcpp::Nullable<Rcpp::NumericVector>,int)");
-        signatures.insert("Rcpp::List(*americanOptionEngine)(std::string,double,double,double,double,double,double,int,int,std::string,Rcpp::Nullable<Rcpp::NumericVector>,Rcpp::Nullable<Rcpp::NumericVector>)");
+        signatures.insert("Rcpp::List(*americanOptionEngine)(std::string,double,double,double,double,Rcpp::Nullable<double>,Rcpp::Nullable<QuantLib::Date>,double,int,int,std::string,Rcpp::Nullable<Rcpp::NumericVector>,Rcpp::Nullable<Rcpp::NumericVector>,int)");
         signatures.insert("Rcpp::List(*europeanOptionArraysEngine)(std::string,Rcpp::NumericMatrix)");
     }
     return signatures.find(sig) != signatures.end();
@@ -1762,7 +1764,7 @@ static const R_CallMethodDef CallEntries[] = {
     {"_RQuantLib_getQuantLibVersion", (DL_FUNC) &_RQuantLib_getQuantLibVersion, 0},
     {"_RQuantLib_getQuantLibCapabilities", (DL_FUNC) &_RQuantLib_getQuantLibCapabilities, 0},
     {"_RQuantLib_europeanOptionEngine", (DL_FUNC) &_RQuantLib_europeanOptionEngine, 11},
-    {"_RQuantLib_americanOptionEngine", (DL_FUNC) &_RQuantLib_americanOptionEngine, 12},
+    {"_RQuantLib_americanOptionEngine", (DL_FUNC) &_RQuantLib_americanOptionEngine, 14},
     {"_RQuantLib_europeanOptionArraysEngine", (DL_FUNC) &_RQuantLib_europeanOptionArraysEngine, 2},
     {"_RQuantLib_zeroprice", (DL_FUNC) &_RQuantLib_zeroprice, 5},
     {"_RQuantLib_zeroyield", (DL_FUNC) &_RQuantLib_zeroyield, 5},