QS.LOAN.SETTINGS

Creates optional loan terms: balloon principal, amortization, borrower credit, resets, coupon bounds and prepayment; pass the handle to QS.INSTRUMENT.LOAN

Category: QuantSupport - Instruments.

QS.LOAN.SETTINGS(name: text, balloon_fraction: number or blank, amortization_rate: number or blank, credit_index: text or blank, recovery: number or blank, fixing_frequency: text or blank, fixing_lag: number or blank, index_tenor: text or blank, calendar: text or blank, business_day_convention: text or blank, floor: number or blank, cap: number or blank, introductory_periods: number or blank, introductory_rate: number or blank, annual_cpr: number or blank, base_cpr: number or blank, incentive_multiplier: number or blank, maximum_cpr: number or blank) → text handle
Parameters:

  • name (text) – Workbook-unique object name; unchanged recalculation reuses its current handle

  • balloon_fraction (number or blank) – Principal fraction left for the final balloon, e.g. 0.25 = 25% of original principal; required only for Balloon repayment; invalid with French or Bullet; blank = unset

  • amortization_rate (number or blank) – Annual decimal all-in rate used to build principal instalments, e.g. 0.05 = 5%; optional override; blank uses the initial fixed coupon or uses the first floating observation from the explicit construction context; does not set the floating spread

  • credit_index (text or blank) – Optional Credit:<entity> curve index; blank leaves borrower credit unset

  • recovery (number or blank) – Optional fraction of opening principal recovered on borrower default, in [0,1], e.g. 0.40 = 40%; blank defaults to 0.40; used with credit_index

  • fixing_frequency (text or blank) – Optional floating reset frequency, e.g. Quarterly or Annual; reset dates must align with payment boundaries; blank uses index metadata (payment_frequency for daily indices); distinct from index_tenor

  • fixing_lag (number or blank) – Whole business days to move backwards from each reset date to its fixing, e.g. 2; nonnegative; blank defaults to 0; uses the selected calendar

  • index_tenor (text or blank) – Optional floating index observation tenor, e.g. 3M or 12M; distinct from payment/reset frequency; blank uses index metadata; must be positive

  • calendar (text or blank) – Optional payment/fixing calendar, e.g. TARGET; blank defaults to NullCalendar (every day is a business day); contractual accrual boundaries remain unadjusted

  • business_day_convention (text or blank) – Optional payment-date adjustment: Following, ModifiedFollowing, Preceding, ModifiedPreceding or Unadjusted (blank default); contractual accrual dates remain unadjusted

  • floor (number or blank) – Optional floor on the all-in floating coupon (index + spread), annual decimal, e.g. 0 = 0%; blank = no floor; requires scalar market_index; incompatible with coupon arrays and FairRate solving

  • cap (number or blank) – Optional cap on the all-in floating coupon (index + spread), annual decimal, e.g. 0.06 = 6%; blank = no cap; requires scalar market_index; incompatible with coupon arrays and FairRate solving

  • introductory_periods (number or blank) – Optional positive count of initial fixed payments, e.g. 12 = first year for Monthly; supply introductory_rate too; must leave a floating payment; incompatible with coupon arrays; blank = no introduction

  • introductory_rate (number or blank) – Annual decimal fixed coupon during introductory_periods, e.g. 0.03 = 3%; afterwards scalar rate is the spread over market_index; supply both introductory fields on a floating loan; blank = no introduction

  • annual_cpr (number or blank) – Optional constant annual prepayment fraction in [0,1], e.g. 0.10 = 10% per year, not per payment; omit for dated CPRs or refinancing settings; all prepayment fields blank = no prepayment

  • base_cpr (number or blank) – Refinancing base annual CPR in [0,1], e.g. 0.02 = 2%; supply all three refinancing fields and a QS.LOAN.PRICER benchmark; excludes annual_cpr/dated CPRs; all prepayment fields blank = no prepayment

  • incentive_multiplier (number or blank) – Nonnegative CPR increase per unit of positive coupon-minus-benchmark incentive, e.g. 4 adds 0.04 CPR for a 0.01 incentive; supply base_cpr and maximum_cpr too; all prepayment fields blank = no prepayment

  • maximum_cpr (number or blank) – Refinancing annual CPR ceiling in [0,1], at least base_cpr, e.g. 0.30 = 30% per year; supply base_cpr and incentive_multiplier too; blank with all prepayment inputs = no prepayment

Returns:

LoanSettings handle for QS.INSTRUMENT.LOAN. Blank fields mean no credit, prepayment, bounds or introductory coupon; 40% recovery, zero fixing lag, NullCalendar and Unadjusted payments. Floating-first French/Balloon initial amortization is built during instrument construction when amortization_rate is blank.

Return Type:

text handle

Errors:

#VALUE! for invalid settings or conflicting prepayment models; repayment-specific validation occurs when the loan is built.

Formula

=QS.LOAN.SETTINGS(name, balloon_fraction, amortization_rate, credit_index, recovery, fixing_frequency, fixing_lag, index_tenor, calendar, business_day_convention, floor, cap, introductory_periods, introductory_rate, annual_cpr, base_cpr, incentive_multiplier, maximum_cpr)

Calculation

Runs on Excel’s main calculation thread.

Native Declaration

fn qs_loan_settings (name : & str , balloon_fraction : Option < f64 > , amortization_rate : Option < f64 > , credit_index : Option < String > , recovery : Option < f64 > , fixing_frequency : Option < String > , fixing_lag : Option < f64 > , index_tenor : Option < String > , calendar : Option < String > , business_day_convention : Option < String > , floor : Option < f64 > , cap : Option < f64 > , introductory_periods : Option < f64 > , introductory_rate : Option < f64 > , annual_cpr : Option < f64 > , base_cpr : Option < f64 > , incentive_multiplier : Option < f64 > , maximum_cpr : Option < f64 > ,) -> Result < String , XllError >

Rust source