Credit.chs

module QuantLib.Instrument.Credit
  (
    -- * Types
    CreditDefaultSwap
  , SyntheticCDO
  , NthToDefault
  , ProtectionSide(..)
  , Claim(..)

    -- * Constructors
    -- ** Credit-default swaps and options
  , creditDefaultSwap
  , creditDefaultSwapWithUpfront
  , cdsOption
    -- ** Portfolio credit
  , syntheticCdo
  , nthToDefault

    -- * Inspectors
    -- ** Credit-default swaps and options
  , atmRate
  , impliedVolatility
  , riskyAnnuity
  , accrualRebateNpv
  , conventionalSpread
  , couponLegBps
  , couponLegNpv
  , coupons
  , defaultLegNpv
  , fairUpfront
  , impliedHazardRate
  , upfrontBps
  , upfrontNpv
    -- ** Synthetic CDOs
  , fairPremium
  , fairUpfrontPremium
  , premiumValue
  , protectionValue
  , premiumLegNpv
  , protectionLegNpv
  , cdoRemainingNotional
  , implicitCorrelation
    -- ** Nth-to-default
  , ntdFairPremium
  ) where
import Data.List.NonEmpty(NonEmpty)

import QuantLib.Internal
import QuantLib.Internal.Common
import QuantLib.Internal.Type
{#import QuantLib.Instrument#}(PricingModel)

#include "qlTypesC2HS.h"
#include "qlEnumC2HS.h"
#include "qlEnumObjects.h"

#include "ql.h"

{#enum ProtectionSide{} deriving(Show, Eq, Read)#}

{#pointer *QlCreditDefaultSwap as CreditDefaultSwap foreign -> CCreditDefaultSwap' nocode#}
{#pointer *QlYieldTermStructure as YieldTermStructure foreign -> CYieldTermStructure' nocode#}
{#pointer *QlDefaultProbabilityTermStructure as DefaultProbabilityTermStructure foreign -> CDefaultProbabilityTermStructure' nocode#}
{#pointer *QlCdsOption as CdsOption foreign -> CCdsOption' nocode#}
{#pointer *QlBond as Bond foreign -> CBond' nocode#}
{#pointer *QlInstrument as Instrument foreign -> CInstrument' nocode#}
{#pointer *DayCounter foreign -> CDayCounter nocode#}
{#pointer *Leg foreign -> CLeg' nocode#}
{#pointer *Schedule foreign -> CSchedule nocode#}
{#pointer *QlClaim as Claim foreign -> CQlClaim nocode#}
{#pointer *QlExercise nocode#}
{#pointer *QlBasket as TrancheBasket foreign -> CBasket nocode#}
{#pointer *QlBasket as DigitalBasket foreign -> CBasket nocode#}
{#pointer *QlSyntheticCDO as SyntheticCDO foreign -> CSyntheticCDO' nocode#}
{#pointer *QlNthToDefault as NthToDefault foreign -> CNthToDefault' nocode#}

-- |CDS quoted as running-spread only.
-- side Whether the protection is bought or sold. notional Notional value spread Running spread in fractional units. schedule Coupon schedule. paymentConvention Business-day convention for payment-date adjustment. dayCounter Day-count convention for accrual. settlesAccrual Whether or not the accrued coupon is due in the event of a default. paysAtDefaultTime If set to true, any payments triggered by a default event are due at default time. If set to false, they are due at the end of the accrual period. protectionStart The first date where a default event will trigger the contract.
{#fun qlCreditDefaultSwap as creditDefaultSwap{`ProtectionSide',`Double' -- ^notional
  ,`Double' -- ^spread
  ,withSchedule*`Schedule',fromEnumC`BusinessDayConvention',withDayCounter*`DayCounter',`Bool' -- ^settlesAccrual
  ,`Bool' -- ^paysAtDefaultTime
  ,withMaybeDay*`Maybe Day' -- ^protectionStart
  ,withClaim*`Claim'
  ,withDayCounter*`DayCounter' -- ^lastPeriodDayCounter
  ,`Bool' -- ^rebatesAccrual
  ,withMaybeDay*`Maybe Day' -- ^tradeDate
  ,fromIntegral`Word' -- ^cashSettlementDays
  ,preErrorCheck-`String'errorCheck*-}->`CreditDefaultSwap'peekCreditDefaultSwap*#}

-- |CDS quoted as upfront and running spread.
-- side Whether the protection is bought or sold. notional Notional value upfront Upfront in fractional units. spread Running spread in fractional units. schedule Coupon schedule. paymentConvention Business-day convention for payment-date adjustment. dayCounter Day-count convention for accrual. settlesAccrual Whether or not the accrued coupon is due in the event of a default. paysAtDefaultTime If set to true, any payments triggered by a default event are due at default time. If set to false, they are due at the end of the accrual period. protectionStart The first date where a default event will trigger the contract. upfrontDate Settlement date for the upfront payment.
{#fun qlCreditDefaultSwap1 as creditDefaultSwapWithUpfront{`ProtectionSide',`Double' -- ^notional
  ,`Double' -- ^upfront
  ,`Double' -- ^spread
  ,withSchedule*`Schedule',fromEnumC`BusinessDayConvention',withDayCounter*`DayCounter',`Bool' -- ^settlesAccrual
  ,`Bool' -- ^paysAtDefaultTime
  ,withMaybeDay*`Maybe Day' -- ^protectionStart
  ,withMaybeDay*`Maybe Day' -- ^upfrontDate
  ,withClaim*`Claim'
  ,withDayCounter*`DayCounter' -- ^lastPeriodDayCounter
  ,`Bool' -- ^rebatesAccrual
  ,withMaybeDay*`Maybe Day' -- ^tradeDate
  ,fromIntegral`Word' -- ^cashSettlementDays
  ,preErrorCheck-`String'errorCheck*-}->`CreditDefaultSwap'peekCreditDefaultSwap*#}

-- |The fair running spread implied by the underlying CDS's term structures at the option's exercise.
{#fun qlCdsOptionAtmRate as atmRate{withCdsOption*`CdsOption',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |An option giving the right to enter the underlying CDS, buying protection and paying coupon.
{#fun qlCdsOption as cdsOption{withGenInstrument*`CreditDefaultSwap',withExercise*`Exercise',`Bool' -- ^knocksOut
  ,preErrorCheck-`String'errorCheck*-}->`CdsOption'peekCdsOption*#}

-- |Volatility that reproduces a given option price under the pricing engine's volatility model.
{#fun qlCdsOptionImpliedVolatility as impliedVolatility{withCdsOption*`CdsOption',`Double' -- ^price
  ,withYieldTermStructure*`GenYieldTermStructure y',withGenTermStructure*`DefaultProbabilityTermStructure'
  ,`Double' -- ^recoveryRate
  ,`Double' -- ^accuracy
  ,fromIntegral`Word' -- ^maxEvaluations
  ,`Double' -- ^minVol
  ,`Double' -- ^maxVol
  ,preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |The risky annuity used to convert between the option's price and its implied volatility.
{#fun qlCdsOptionRiskyAnnuity as riskyAnnuity{withCdsOption*`CdsOption',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |Conventional/standard upfront-to-spread conversion.
-- Under a standard ISDA model and a set of standardised instrument characteristics, it is the running only quoted spread that will make a CDS contract have an NPV of 0 when quoted for that running only spread. Refer to: "ISDA Standard CDS converter specification." May 2009.The conventional recovery rate to apply in the calculation is as specified by ISDA, not necessarily equal to the market-quoted one. It is typically 0.4 for SeniorSec and 0.2 for subordinate.The conversion employs a flat hazard rate. As a result, you will not recover the market quotes.This method performs the calculation with the instrument characteristics. It will coincide with the ISDA calculation if your object has the standard characteristics. Notably: The calendar should have no bank holidays, just weekends.The yield curve should be LIBOR piecewise constant in fwd rates, with a discount factor of 1 on the calculation date, which coincides with the trade date.Convention should be Following for yield curve and contract cashflows.The CDS should pay accrued and mature on standard IMM dates, settle on trade date +1 and upfront settle on trade date +3.
{#fun qlCreditDefaultSwapConventionalSpread as conventionalSpread{withGenInstrument*`CreditDefaultSwap',`Double'
  ,withYieldTermStructure*`GenYieldTermStructure y',withDayCounter*`DayCounter'
  ,`PricingModel' -- ^model
  ,preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |Returns the variation of the fixed-leg value given a one-basis-point change in the running spread.
{#fun qlCreditDefaultSwapCouponLegBPS as couponLegBps{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |NPV of the coupon (premium) leg.
{#fun qlCreditDefaultSwapCouponLegNPV as couponLegNpv{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |The coupon-leg cash flows of the CDS.
{#fun qlCreditDefaultSwapCoupons as coupons{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Leg'peekLeg*#}

-- |NPV of the default (protection) leg.
{#fun qlCreditDefaultSwapDefaultLegNPV as defaultLegNpv{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |Returns the upfront spread that, given the running spread and the quoted recovery rate, will make the instrument have an NPV of 0.
{#fun qlCreditDefaultSwapFairUpfront as fairUpfront{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |Implied hazard rate calculation.
-- This method performs the calculation with the instrument characteristics. It will coincide with the ISDA calculation if your object has the standard characteristics. Notably: The calendar should have no bank holidays, just weekends.The yield curve should be LIBOR piecewise constant in fwd rates, with a discount factor of 1 on the calculation date, which coincides with the trade date.Convention should be Following for yield curve and contract cashflows.The CDS should pay accrued and mature on standard IMM dates, settle on trade date +1 and upfront settle on trade date +3.
{#fun qlCreditDefaultSwapImpliedHazardRate as impliedHazardRate{withGenInstrument*`CreditDefaultSwap',`Double' -- ^targetNPV
  ,withYieldTermStructure*`GenYieldTermStructure y',withDayCounter*`DayCounter',`Double' -- ^recoveryRate
  ,`Double' -- ^accuracy
  ,`PricingModel' -- ^model
  ,preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |Returns the variation of the upfront payment value given a one-basis-point change in the upfront.
{#fun qlCreditDefaultSwapUpfrontBPS as upfrontBps{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |NPV of the upfront payment.
{#fun qlCreditDefaultSwapUpfrontNPV as upfrontNpv{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |NPV of the rebate paid/received on an early default for the fraction of the accrual period
-- elapsed since the last coupon date; zero unless the CDS was constructed with @rebatesAccrual@.
{#fun qlCreditDefaultSwapAccrualRebateNPV as accrualRebateNpv{withGenInstrument*`CreditDefaultSwap',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |A synthetic CDO tranche over a tranche-loss basket. @notional@ overrides the basket tranche.
syntheticCdo :: TrancheBasket -> ProtectionSide -> Schedule -> Double -> Double -> DayCounter -> BusinessDayConvention
  -> Maybe Double -> IO SyntheticCDO
syntheticCdo basket side sched upfrontRate runningRate dc conv notional =
  syntheticCDO_ basket side sched upfrontRate runningRate dc conv (maybe False (const True) notional) (maybe 0 id notional)
{#fun qlSyntheticCDO as syntheticCDO_{withTrancheBasket*`TrancheBasket',`ProtectionSide',withSchedule*`Schedule',`Double',`Double'
  ,withDayCounter*`DayCounter',fromEnumC`BusinessDayConvention',`Bool',`Double'
  ,preErrorCheck-`String'errorCheck*-}->`SyntheticCDO'peekSyntheticCDO*#}

-- |The fair running premium that makes the tranche's NPV zero (holding the upfront fixed).
{#fun qlSyntheticCDOFairPremium as fairPremium{withGenInstrument*`SyntheticCDO',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |The fair upfront premium that makes the tranche's NPV zero (holding the running rate fixed).
{#fun qlSyntheticCDOFairUpfrontPremium as fairUpfrontPremium{withGenInstrument*`SyntheticCDO',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |NPV of the premium (running plus upfront) leg.
{#fun qlSyntheticCDOPremiumValue as premiumValue{withGenInstrument*`SyntheticCDO',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |NPV of the protection leg.
{#fun qlSyntheticCDOProtectionValue as protectionValue{withGenInstrument*`SyntheticCDO',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |NPV of the premium (running plus upfront) leg, as a plain NPV (not divided by notional).
{#fun qlSyntheticCDOPremiumLegNPV as premiumLegNpv{withGenInstrument*`SyntheticCDO',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |NPV of the protection leg, as a plain NPV.
{#fun qlSyntheticCDOProtectionLegNPV as protectionLegNpv{withGenInstrument*`SyntheticCDO',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |Total outstanding tranche notional, not wiped out by realized losses.
{#fun qlSyntheticCDORemainingNotional as cdoRemainingNotional{withGenInstrument*`SyntheticCDO',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |The flat Gaussian-copula LHP correlation (constant along time and portfolio loss level)
-- that makes the tranche's NPV equal @targetNPV@.
-- recoveries One recovery rate per basket name, in the basket's own name order. discountCurve Curve to discount both legs with. targetNPV NPV to match; 0 for a fairly-priced tranche. accuracy Root-finding accuracy on the correlation.
{#fun qlSyntheticCDOImplicitCorrelation as implicitCorrelation{withGenInstrument*`SyntheticCDO'
  ,withNonEmptyDoubleArray*`NonEmpty Double'& -- ^recoveries
  ,withYieldTermStructure*`GenYieldTermStructure y' -- ^discountCurve
  ,`Double' -- ^targetNPV
  ,`Double' -- ^accuracy
  ,preErrorCheck-`String'errorCheck*-}->`Double'#}

-- |Protection against the @n@-th default in a 'QuantLib.Credit.DigitalBasket'.
{#fun qlNthToDefault as nthToDefault{withDigitalBasket*`DigitalBasket',fromIntegral`Word',`ProtectionSide'
  ,withSchedule*`Schedule',`Double',`Double',withDayCounter*`DayCounter',`Double',`Bool'
  ,preErrorCheck-`String'errorCheck*-}->`NthToDefault'peekNthToDefault*#}

-- |The fair running premium that makes the nth-to-default swap's NPV zero.
{#fun qlNthToDefaultFairPremium as ntdFairPremium{withGenInstrument*`NthToDefault',preErrorCheck-`String'errorCheck*-}->`Double'#}

-- vim: set ff=unix ts=8 sts=2 sw=2 et: