Deprecate remaining old-style FD dividend options.

Replacing them with the new FD Black-Scholes option causes a few tests
to fail.  We should check if the new-style option can be made to pass them.

Author: lballabio

ql/pricingengines/vanilla/fddividendamericanengine.hpp

@@ -32,18 +32,8 @@
 namespace QuantLib {
 
     //! Finite-differences pricing engine for dividend American options
-    /*! \deprecated Use FDDividendAmericanEngineMerton73 instead if you
-                    want to use the Merton 73 escowed dividend model;
-                    use FdBlackScholesVanillaEngine otherwise.
+    /*! \deprecated Use FdBlackScholesVanillaEngine instead.
                     Deprecated in version 1.17.
-
-        \ingroup vanillaengines
-
-        \test
-        - the correctness of the returned greeks is tested by
-          reproducing numerical derivatives.
-        - the invariance of the results upon addition of null
-          dividends is tested.
     */
     template <template <class> class Scheme = CrankNicolson>
     class QL_DEPRECATED FDDividendAmericanEngine
@@ -61,9 +51,11 @@ namespace QuantLib {
 
 
     //! Finite-differences pricing engine for dividend American options
-    /*! This engine uses the Merton 73 escowed dividend model. */
+    /*! \deprecated Use FdBlackScholesVanillaEngine instead.
+                    Deprecated in version 1.17.
+    */
     template <template <class> class Scheme = CrankNicolson>
-    class FDDividendAmericanEngineMerton73
+    class QL_DEPRECATED FDDividendAmericanEngineMerton73
         : public FDEngineAdapter<FDAmericanCondition<
                                      FDDividendEngineMerton73<Scheme> >,
                                  DividendVanillaOption::engine> {

ql/pricingengines/vanilla/fddividendeuropeanengine.hpp

@@ -30,18 +30,8 @@
 namespace QuantLib {
 
     //! Finite-differences pricing engine for dividend European options
-    /*! \deprecated Use FDDividendEuropeanEngineMerton73 instead if you
-                    want to use the Merton 73 escowed dividend model;
-                    use FdBlackScholesVanillaEngine otherwise.
+    /*! \deprecated Use FdBlackScholesVanillaEngine instead.
                     Deprecated in version 1.17.
-
-        \ingroup vanillaengines
-
-        \test
-        - the correctness of the returned greeks is tested by
-          reproducing numerical derivatives.
-        - the invariance of the results upon addition of null
-          dividends is tested.
     */
     template <template <class> class Scheme = CrankNicolson>
     class QL_DEPRECATED FDDividendEuropeanEngine
@@ -59,9 +49,11 @@ namespace QuantLib {
 
 
     //! Finite-differences pricing engine for dividend European options
-    /*! This engine uses the Merton 73 escowed dividend model. */
+    /*! \deprecated Use FdBlackScholesVanillaEngine instead.
+                    Deprecated in version 1.17.
+    */
     template <template <class> class Scheme = CrankNicolson>
-    class FDDividendEuropeanEngineMerton73
+    class QL_DEPRECATED FDDividendEuropeanEngineMerton73
         : public FDEngineAdapter<FDDividendEngineMerton73<Scheme>,
                                  DividendVanillaOption::engine> {
         typedef FDEngineAdapter<FDDividendEngineMerton73<Scheme>,

test-suite/dividendoption.cpp

@@ -622,10 +622,11 @@ void DividendOptionTest::testFdEuropeanValues() {
                             new BlackScholesMertonProcess(Handle<Quote>(spot),
                                                           qTS, rTS, volTS));
 
-          ext::shared_ptr<PricingEngine> engine(
-              new FDDividendEuropeanEngineMerton73<CrankNicolson>(stochProcess,
-                                                                  timeSteps,
-                                                                  gridPoints));
+          ext::shared_ptr<PricingEngine> engine =
+              MakeFdBlackScholesVanillaEngine(stochProcess)
+              .withTGrid(timeSteps)
+              .withXGrid(gridPoints)
+              .withCashDividendModel(FdBlackScholesVanillaEngine::Escrowed);
 
           ext::shared_ptr<PricingEngine> ref_engine(
                             new AnalyticDividendEuropeanEngine(stochProcess));
@@ -674,9 +675,9 @@ void DividendOptionTest::testFdEuropeanValues() {
 
 namespace {
 
-    template <class Engine>
     void testFdGreeks(const Date& today,
-                      const ext::shared_ptr<Exercise>& exercise) {
+                      const ext::shared_ptr<Exercise>& exercise,
+                      FdBlackScholesVanillaEngine::CashDividendModel model) {
 
         std::map<std::string,Real> calculated, expected, tolerance;
         tolerance["delta"] = 5.0e-3;
@@ -719,8 +720,10 @@ namespace {
                             new BlackScholesMertonProcess(Handle<Quote>(spot),
                                                           qTS, rTS, volTS));
 
-                ext::shared_ptr<PricingEngine> engine(
-                                                    new Engine(stochProcess));
+                ext::shared_ptr<PricingEngine> engine =
+                    MakeFdBlackScholesVanillaEngine(stochProcess)
+                    .withCashDividendModel(model);
+                
                 DividendVanillaOption option(payoff, exercise,
                                              dividendDates, dividends);
                 option.setPricingEngine(engine);
@@ -809,8 +812,8 @@ void DividendOptionTest::testFdEuropeanGreeks() {
     for (Size i=0; i<LENGTH(lengths); i++) {
         Date exDate = today + lengths[i]*Years;
         ext::shared_ptr<Exercise> exercise(new EuropeanExercise(exDate));
-        testFdGreeks<FDDividendEuropeanEngineMerton73<CrankNicolson> >(today,exercise);
-        testFdGreeks<FdBlackScholesVanillaEngine>(today,exercise);
+        testFdGreeks(today,exercise,FdBlackScholesVanillaEngine::Spot);
+        testFdGreeks(today,exercise,FdBlackScholesVanillaEngine::Escrowed);
     }
 }
 
@@ -826,19 +829,18 @@ void DividendOptionTest::testFdAmericanGreeks() {
 
     for (Size i=0; i<LENGTH(lengths); i++) {
         Date exDate = today + lengths[i]*Years;
-        ext::shared_ptr<Exercise> exercise(
-                                          new AmericanExercise(today,exDate));
-        testFdGreeks<FDDividendAmericanEngineMerton73<CrankNicolson> >(today,exercise);
-        testFdGreeks<FdBlackScholesVanillaEngine>(today,exercise);
+        ext::shared_ptr<Exercise> exercise(new AmericanExercise(today,exDate));
+        testFdGreeks(today,exercise,FdBlackScholesVanillaEngine::Spot);
+        testFdGreeks(today,exercise,FdBlackScholesVanillaEngine::Escrowed);
     }
 }
 
 
 namespace {
 
-    template <class Engine>
     void testFdDegenerate(const Date& today,
-                          const ext::shared_ptr<Exercise>& exercise) {
+                          const ext::shared_ptr<Exercise>& exercise,
+                          FdBlackScholesVanillaEngine::CashDividendModel model) {
 
         DayCounter dc = Actual360();
         ext::shared_ptr<SimpleQuote> spot(new SimpleQuote(54.625));
@@ -853,8 +855,11 @@ namespace {
         Size timeSteps = 300;
         Size gridPoints = 300;
 
-        ext::shared_ptr<PricingEngine> engine(
-                                    new Engine(process,timeSteps,gridPoints));
+        ext::shared_ptr<PricingEngine> engine =
+              MakeFdBlackScholesVanillaEngine(process)
+              .withTGrid(timeSteps)
+              .withXGrid(gridPoints)
+              .withCashDividendModel(model);
 
         ext::shared_ptr<StrikedTypePayoff> payoff(
                                   new PlainVanillaPayoff(Option::Call, 55.0));
@@ -905,7 +910,8 @@ void DividendOptionTest::testFdEuropeanDegenerate() {
 
     ext::shared_ptr<Exercise> exercise(new EuropeanExercise(exDate));
 
-    testFdDegenerate<FDDividendEuropeanEngineMerton73<CrankNicolson> >(today,exercise);
+    testFdDegenerate(today,exercise,FdBlackScholesVanillaEngine::Spot);
+    testFdDegenerate(today,exercise,FdBlackScholesVanillaEngine::Escrowed);
 }
 
 void DividendOptionTest::testFdAmericanDegenerate() {
@@ -921,7 +927,8 @@ void DividendOptionTest::testFdAmericanDegenerate() {
 
     ext::shared_ptr<Exercise> exercise(new AmericanExercise(today,exDate));
 
-    testFdDegenerate<FDDividendAmericanEngineMerton73<CrankNicolson> >(today,exercise);
+    testFdDegenerate(today,exercise,FdBlackScholesVanillaEngine::Spot);
+    testFdDegenerate(today,exercise,FdBlackScholesVanillaEngine::Escrowed);
 }
 
 
@@ -1001,23 +1008,6 @@ void DividendOptionTest::testEscrowedDividendModel() {
                    << "\n    difference: " << std::fabs(pdeNPV - analyticNPV)
                    << "\n    tolerance:  " << tol);
     }
-
-    option.setPricingEngine(
-        ext::make_shared<FDDividendEuropeanEngineMerton73<> >(
-            process, 50, 200));
-
-    const Real deprecatedPDENPV = option.NPV();
-
-    if (std::fabs(deprecatedPDENPV - analyticNPV) > tol) {
-        BOOST_FAIL("Failed to reproduce European option values "
-                "with the escrowed dividend model and the "
-                "FDDividendEuropeanEngineMerton73 engine"
-                   << "\n    calculated: " << pdeNPV
-                   << "\n    expected:   " << analyticNPV
-                   << "\n    difference: "
-                   << std::fabs(deprecatedPDENPV - analyticNPV)
-                   << "\n    tolerance:  " << tol);
-    }
 }
 
 test_suite* DividendOptionTest::suite() {