menu
Tutorials

Instruments

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.

info

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, Currency

We 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'
  • strike specified 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.

Instrumentgs_quant nameDescription
Eq OptionEqOptionAn option on an underlying equity security
FX ForwardFXForwardAn exchange of cashflows in different currencies at a determined future time
FX OptionFXOptionAn option on an FX Forward
FX BinaryFXBinaryAn 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 BinaryFXMultiCrossBinaryAn 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 SwapFXVolatilitySwapAn exchange of cashflows based on the realized volatility of the underlying FX cross and a pre-determined fixed volatility level
Inflation SwapInflationSwapA zero coupon vanilla inflation swap of fixed vs floating cashflows adjusted to inflation rate
Interest Rate SwapIRSwapA vanilla interest rate swap of fixed vs floating cashflows in the same currency
Interest Rate Basis SwapIRBasisSwapAn exchange of cashflows from different interest rate indices in the same currency
Interest Rate Xccy SwapIRXccySwapAn exchange of cashflows from different interest rate indices in different currencies
Interest Rate Xccy Swap Fix FixIRXccySwapFixFixAn exchange of fixed cashflows in different currencies
Interest Rate Xccy Swap Fix FloatIRXccySwapFixFltA vanilla interest rate swap of fixed vs floating cashflows in different currencies
Interest Rate SwaptionIRSwaptionAn option to enter into a vanilla interest rate swap of fixed vs floating cashflows
Interest Rate CapIRCapAn 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 FloorIRFloorAn 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 OptionIRCMSOptionAn option on a single date where the payoff is based on the CMS rate
Interest Rate CMS Option StripIRCMSOptionStripA strip of CMS Options
Interest Rate CMS Spread OptionIRCMSSpreadOptionAn 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 StripIRCMSSpreadOptionStripA strip of CMS Spread Options

Note that IRDelta is additional available for Interest Rate Futures and Bond Futures upon request.


Related Content