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.

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.

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

Related Content