Summary
This document summarizes processing for the Evaluation Date. By default QuantLib stores the evaluation date as a global variable shared by all objects in the current QuantLib instance. Under this implementation, all objects in a given QuantLibAddin session - for example, all open workbooks in a given Excel session - share a single global instance of the evaluation date.
Alternatively QuantLib offers support for Sessions which allow the client application to implement multiple instances of the evaluation date. When this functionality is enabled, QuantLibAddin defines a session as an Excel workbook, so that a group of related objects which require a common instance of the evaluation date can be isolated in a single workbook.
Within any given context, the value of the evaluation date can be set with QuantLibAddin function qlSettingsSetEvaluationDate and queried with function qlSettingsEvaluationDate.
QuantLib
In QuantLib, the evaluation date is implemented in a global object (called Settings). QuantLib supports various methods which enable the client application to set the value of the evaluation date. Any object which depends on the evaluation date consults this global value when required. If the evaluation date is not set explicitly then it defaults to the current date as computed by the system clock (and the value is incremented when the clock passes midnight).
Session
The behavior described above may lead to undesired results, for example if two different objects require different evaluation dates within a single running instance of QuantLib. To cater for this situation, QuantLib supports the concept of a Session. A session constitutes a separate instance of the global state, i.e. a separate instance of the evaluation date variable.
QuantLib doesn't specify what constitutes the physical implementation of a session and client applications are left to define this as required for the local environment. For example a session could be implemented as a thread, or as a web service. Multiple sessions share a single instance of QuantLib.
QuantLibAddin
The QuantLibAddin default build doesn't implement QuantLib's session functionality.
At present the only means for specifying the evaluation date that is exposed by the QuantLibAddin interface is function qlSettingsSetEvaluationDate. Before any call to qlSettingsSetEvaluationDate, the evaluation date defaults to the current date on the system clock; any call to qlSettingsSetEvaluationDate explicitly specifies the evaluation date.
Consider a single Excel session in which multiple cells invoke qlSettingsSetEvaluationDate, specifying different values for the evaluation date. Each call overwrites the global value. The sequence in which the calls are executed is dictated by Excel's dependency calculation tree. Other cells in the Excel session which depend on the evaluation date will see a different value depending on when they are refreshed.
Workbook as Session
QuantLibAddin can be configured to support QuantLib sessions. QuantLibAddin implements a session as a workbook. Whenever the value of the evaluation date is set - either through an explicit call to qlSettingsSetEvaluationDate, or by being left to default to the current system date - that value prevails for all sheets and cells in the given workbook. This has the following implications:
- If multiple distinct values are required for evaluation date, this can be effected by using multiple workbooks. Each workbook contains 1) a single cell which sets the evaluation date and 2) any objects which may depend on that value
- Within a single workbook there is still the potential problem that multiple calls to qlSettingsSetEvaluationDate overwrite the workbook-wide value of evaluation date. Multiple objects requiring different instances of the evaluation date must not reside in a single workbook.
Implementation
To enable support for sessions in QuantLib/QuantLibAddin, edit file
QuantLib\ql\userconfig.hpp
and uncomment line
#define QL_ENABLE_SESSIONS
then recompile QuantLib and QuantLibAddin.
Multithreading
Much of the discussion about QuantLib sessions has centered on the topic of multithreading, which is not relevant to QuantLibAddin. QuantLibAddin executes in a single process thread which is shared by all open workbooks in a given Excel session.
Cross-Platform Support
At present QuantLibAddin implements QuantLib sessions only on the Microsoft Excel platform.
Links
Follow the links below for relevant threads in the QuantLib mailing lists.