What is an Instrument
Instrument is a class that inherits
from the
Priceable class
and is used to represent financial objects that can be priced, such as derivative instruments.
Priceable
exposes several methods common to all instruments, such as
as_dict()
which returns a dictionary of all the public, non-null properties and values and
calc(risk_measure)
which is used to evaluate various risk measures. More about the latter in the
Measures tutorial
gs-quant offers a number of
Instrument
implementations, such as
equity options,
interest rate swaptions
and
fx options.
Please refer to supported instruments for a list of externally supported
instruments.
Note
Examples require an initialized GsSession and relevant entitlements. Please refer to Sessions for details.
How to Create an Instrument
Let's now create an instance of an instrument implementation. For this example, we will create an
Interest Rate Swaption, which the
IRSwaption
class implements.
We will start by importing
IRSwaption
from the Instrument
package as well as PayReceive, Currency to represent commonly used constants.
from gs_quant.instrument import IRSwaption
from gs_quant.common import PayReceive, CurrencyWe will now instantiate an
IRSwaption
object. Note that all
Instruments, including
IRSwaption,
take some non-keyworded required arguments (first 3 in this example), and some optional keyworded
arguments (**kwargs). If the optional arguments are not supplied, default market conventions will
be used as described in each instrument's signature. Signatures can be found in the
the Instrument Package by
clicking on the desired instrument.
swaption = IRSwaption(PayReceive.Receive, '5y', Currency.USD, expiration_date='13m', strike='atm+40', notional_amount=1e8)We can now use the
as_dict()
method inherited from
Priceable to
view all public non-null properties and values of this swaption instance.
swaption.as_dict()Output:
{'pay_or_receive': Receive,
'expiration_date': '13m',
'premium': 0,
'termination_date': '5y',
'asset_class': Rates,
'fee': 0,
'notional_currency': USD,
'type': Swaption,
'notional_amount': 100000000.0,
'strike': 'atm+40'}Instrument Resolution
The above output shows only the inputs specified, many of which are relative (i.e. expiration date,
strike). Calling the
resolve()
method will resolve these parameters to absolute values as well as fill in any defaulted parameters
using the
PricingContext.
Please refer to the above mentioned
Instrument Package for
each instrument's available parameters and to the
Pricing Context tutorial for further details
on
PricingContext.
swaption.resolve()
swaption.as_dict()Output:
{'floating_rate_spread': 0.0,
'floating_rate_day_count_fraction': ACT/360,
'asset_class': Rates,
'floating_rate_designated_maturity': '3m',
'fixed_rate_business_day_convention': Modified Following,
'premium': 0.0,
'expiration_date': '2020-11-02',
'settlement': Phys.CLEARED,
'termination_date': '2025-11-04',
'notional_currency': USD,
'pay_or_receive': 'Receive',
'effective_date': '2020-11-04',
'strike': 0.017845989434194357,
'premium_payment_date': '2019-10-04',
'fee': 0.0,
'floating_rate_frequency': '3m',
'fixed_rate_day_count_fraction': 30/360,
'type': Swaption,
'floating_rate_option': 'USD-LIBOR-BBA',
'floating_rate_business_day_convention': Modified Following,
'fixed_rate_frequency': '6m',
'notional_amount': 100000000.0}Note
resolve()
will change the state of the instrument object. In the code snippet above, calling
resolve()
mutates several specified relative parameters, for example:
expiration_date, specified as '13m', was resolved to '2020-11-02'strikespecified as 'atm+40', was resolved to '0.017845989434194357'
resolve()
will also add any unspecified default parameters - note the additions when calling
as_dict()
before and after
resolve().
For example:
- 'fixed_rate_frequency': '6m'
- 'premium_payment_date': '2019-10-04'
Accessing any of the unspecified parameters on the unresolved swaption will resolve the swaption in place.
Additionally, as discussed in the
measures tutorial, if
resolve()
is not called prior to calling
price()
or calculating risk, the instrument object will be copied and resolved on the fly without mutating
the original swaption object.
The preferred behavior may depend on the
PricingContext -
more on this in the Pricing Context
tutorial.
Supported Instruments
Below are the instruments covered, names they are referred to as in gs_quant and brief definitions as well as links to the technical documentation for each. Each instrument corresponds to a model maintained by Goldman Sachs Securities Division.
| Instrument | gs_quant name | Description |
|---|---|---|
| Credit Index | CDIndex | An index of credit default swaps |
| Credit Index Option | CDIndexOption | An option on an underlying index of credit default swaps |
| Eq Option | EqOption | An option on an underlying equity security |
| FX Forward | FXForward | An exchange of cashflows in different currencies at a determined future time |
| FX Option | FXOption | An option on an FX Forward |
| FX Binary | FXBinary | An option where the buyer receives a fixed amount if a certain currency pair fixes above or below a specified level on a specified date |
| FX Multi Cross Binary | FXMultiCrossBinary | An option where the buyer receives a fixed amount if each of the currency pairs fixes above or below a specified level on a specified date |
| FX Volatility Swap | FXVolatilitySwap | An exchange of cashflows based on the realized volatility of the underlying FX cross and a pre-determined fixed volatility level |
| Inflation Swap | InflationSwap | A zero coupon vanilla inflation swap of fixed vs floating cashflows adjusted to inflation rate |
| Interest Rate Swap | IRSwap | A vanilla interest rate swap of fixed vs floating cashflows in the same currency |
| Interest Rate Basis Swap | IRBasisSwap | An exchange of cashflows from different interest rate indices in the same currency |
| Interest Rate Xccy Swap | IRXccySwap | An exchange of cashflows from different interest rate indices in different currencies |
| Interest Rate Xccy Swap Fix Fix | IRXccySwapFixFix | An exchange of fixed cashflows in different currencies |
| Interest Rate Xccy Swap Fix Float | IRXccySwapFixFlt | A vanilla interest rate swap of fixed vs floating cashflows in different currencies |
| Interest Rate Swaption | IRSwaption | An option to enter into a vanilla interest rate swap of fixed vs floating cashflows |
| Interest Rate Cap | IRCap | An instrument in which the buyer receives payments at the end of each period in which the interest rate exceeds the agreed strike price |
| Interest Rate Floor | IRFloor | An instrument in which the buyer receives payments at the end of each period in which the interest rate is below the agreed strike price |
| Interest Rate CMS Option | IRCMSOption | An option on a single date where the payoff is based on the CMS rate |
| Interest Rate CMS Option Strip | IRCMSOptionStrip | A strip of CMS Options |
| Interest Rate CMS Spread Option | IRCMSSpreadOption | An option on a single date where the payoff is dependent on the spread of two CMS rates compared to the strike of the option. |
| Interest Rate CMS Spread Option Strip | IRCMSSpreadOptionStrip | A strip of CMS Spread Options |
Note that IRDelta is additional available for Interest Rate Futures and Bond Futures upon request.
Related Content
Next - Measures
arrow_forwardWas this page useful?
Give feedback to help us improve developer.gs.com and serve you better.