Class CentralRiskBook

java.lang.Object
com.quantfinlib.crb.CentralRiskBook
public final class CentralRiskBook extends Object
The central risk book — one netted view of the firm's market risk across desks and products. Every instrument is decomposed into a common risk-factor space at booking time, and that is the entire point: an FX-option delta nets against a spot position, an equity-option delta nets against cash shares, and two desks' opposite flows cancel before anyone pays a spread to the street.

Factor naming and units (query via exposure(String)):

  • EQ:<sym> — equity delta in book-currency notional (cash shares contribute qty·price; options contribute Δ·spot·contracts·multiplier);
  • EQGAMMA:<sym> / EQVEGA:<sym> — dollar gamma per 1% move (Γ·S²/100 per contract-adjusted unit) and vega per vol point;
  • CCY:<ccy>: currency exposure in native units of that currency (an EURUSD buy of 10M books CCY:EUR +10M euros and CCY:USD −10M·rate dollars). This is what lets spot, swaps, NDFs and option deltas net at the currency level;
  • FXPOINTS:<pair> — forward-points risk of swaps: P&L in quote units per 1.0 move in the far−near differential;
  • FXGAMMA:<pair> / FXVEGA:<pair> — dollar gamma per 1% and vega per vol point, in quote-currency units.

Sign convention: positive quantity/notional = the book is long. Book what the book absorbs (a client sell hits the book as a buy). NDFs carry currency delta until fixing; the pending non-deliverable notional is tracked per pair in pendingFixing(String) and released via settleFixing(String, double) once fixings occur. This is a risk ledger, not a cash ledger: premium and settlement cash legs are not tracked (the same delta-only stance applies to cash equities, with no settlement cash, and to options, with no premium), and lifecycle events (expiry, exercise, settlement) re-book as offsetting flows. Deterministic, single-threaded, research/warm lane — pair it with InternalizationEngine for flow decisions and CrbAutoHedger for the hedging loop.

  • Constructor Details

    • CentralRiskBook

      public CentralRiskBook()
      Creates an instance; the explicit form of the default constructor.

  • Method Details

    • deskId

      public int deskId(String desk)
      Dense id of a desk, registered on first sight. The desk appears in desks() once it books a flow.
      Parameters:
      desk - desk name, non-blank
      Returns:
      the desk id

    • equityHandle

      public int equityHandle(String symbol)
      Handle of an equity symbol for the int-keyed equity booking methods. Registers no risk factor until the first booking.
      Parameters:
      symbol - equity symbol
      Returns:
      the handle

    • fxPairHandle

      public int fxPairHandle(String pair)
      Handle of an FX pair ("EURUSD") for the int-keyed FX booking methods. Registers no risk factor until the first booking.
      Parameters:
      pair - six-letter pair
      Returns:
      the handle

    • bookCashEquity

      public void bookCashEquity(String desk, String symbol, double qty, double price)
      Cash equity: qty shares (signed) at price.

    • bookCashEquity

      public void bookCashEquity(int desk, int equity, double qty, double price)
      As bookCashEquity(String, String, double, double) with dense ids from deskId(String) and equityHandle(String). No allocation after the first booking on the handle.
      Parameters:
      desk - desk id
      equity - equity handle
      qty - signed shares
      price - price per share

    • bookEquityOption

      public void bookEquityOption(String desk, String symbol, BlackScholes.OptionType type, double contracts, double multiplier, double spot, double strike, double rate, double carry, double vol, double timeYears)
      Listed equity option: contracts signed, multiplier shares per contract (100 for US listed). Greeks come from BlackScholes with the house q-convention (carry = dividend yield).

    • bookEquityOption

      public void bookEquityOption(int desk, int equity, BlackScholes.OptionType type, double contracts, double multiplier, double spot, double strike, double rate, double carry, double vol, double timeYears)
      As the String-keyed overload with dense ids from deskId(String) and equityHandle(String).
      Parameters:
      desk - desk id
      equity - equity handle
      type - call or put
      contracts - signed contracts
      multiplier - shares per contract
      spot - underlying price
      strike - strike
      rate - risk-free rate
      carry - dividend yield
      vol - volatility
      timeYears - time to expiry in years

    • bookFxSpot

      public void bookFxSpot(String desk, String pair, double baseNotional, double rate)
      FX spot on pair ("EURUSD"): buy baseNotional of the base currency (signed) at rate. Decomposes into the two currency legs so it nets against every other product's FX delta.

    • bookFxSpot

      public void bookFxSpot(int desk, int pair, double baseNotional, double rate)
      As the String-keyed overload with dense ids from deskId(String) and fxPairHandle(String). No allocation after the first booking on the handle.
      Parameters:
      desk - desk id
      pair - pair handle
      baseNotional - signed base-currency notional
      rate - spot rate

    • bookFxSwap

      public void bookFxSwap(String desk, String pair, double baseNotional, double nearRate, double farRate)
      FX swap (buy-sell base for positive notional): near leg at nearRate, far leg back at farRate. The base-currency legs cancel exactly (that is what a swap is); what remains is the quote-currency cash-flow imbalance and the forward-points risk. The FXPOINTS factor is the sensitivity: a buy-sell locked in at today's (far − near) must close out at tomorrow's, so its P&L per +1.0 move in the market's far−near differential is −baseNotional — points widening hurts the buy-sell.

      The quote-leg imbalance B·(far − near) is booked at face, undiscounted and without its value date; the risk report therefore measures it on undiscounted notional. For long-dated swaps discount the imbalance before booking if the report must be on present value.

    • bookFxSwap

      public void bookFxSwap(int desk, int pair, double baseNotional, double nearRate, double farRate)
      As the String-keyed overload with dense ids from deskId(String) and fxPairHandle(String). No allocation after the first booking on the handle.
      Parameters:
      desk - desk id
      pair - pair handle
      baseNotional - signed base notional of the far leg
      nearRate - near all-in rate
      farRate - far all-in rate

    • bookNdf

      public void bookNdf(String desk, String pair, double baseNotional, double fwdRate)
      NDF: buy baseNotional of base forward at fwdRate. Economically a forward until the fixing (full currency delta on both legs), with the non-deliverable notional tracked per pair (settlement is cash in the deliverable currency; what fixes at the fixing is the rate, and until then the book is exposed). Both legs are booked at face (undiscounted, date-blind); see bookFxSwap(String, String, double, double, double) for what that means for the report.

    • bookNdf

      public void bookNdf(int desk, int pair, double baseNotional, double fwdRate)
      As the String-keyed overload with dense ids from deskId(String) and fxPairHandle(String). No allocation after the first booking on the handle.
      Parameters:
      desk - desk id
      pair - pair handle
      baseNotional - signed base notional
      fwdRate - contracted forward rate

    • bookFxOption

      public void bookFxOption(String desk, String pair, BlackScholes.OptionType type, double baseNotional, double spotRate, double strike, double domesticRate, double foreignRate, double vol, double timeYears)
      FX option via Garman-Kohlhagen (BlackScholes with carry = foreign rate): baseNotional signed (long calls on base). Delta decomposes into the two currency legs; gamma/vega stay pair-keyed in quote-currency units.

    • bookFxOption

      public void bookFxOption(int desk, int pair, BlackScholes.OptionType type, double baseNotional, double spotRate, double strike, double domesticRate, double foreignRate, double vol, double timeYears)
      As the String-keyed overload with dense ids from deskId(String) and fxPairHandle(String). No allocation after the first booking on the handle.
      Parameters:
      desk - desk id
      pair - pair handle
      type - call or put on the base currency
      baseNotional - signed base notional
      spotRate - spot rate
      strike - strike
      domesticRate - quote-currency rate
      foreignRate - base-currency rate
      vol - volatility
      timeYears - time to expiry in years

    • exposure

      public double exposure(String factor)
      Net exposure on a factor (0 for a factor never booked).

    • grossExposure

      public double grossExposure(String factor)
      Gross (sum of |flow|) on a factor — what the desks did severally.

    • deskExposure

      public double deskExposure(String desk, String factor)
      One desk's net contribution to a factor.

    • netExposures

      public double[] netExposures()
      Net exposures over all factors, indexed by registry id.

    • nettingEfficiency

      public double nettingEfficiency()
      How much risk the netting destroyed before anyone hedged: 1 − Σ|net| / Σgross — 0 when every flow is one-way, → 1 when the desks' flows offset each other entirely.

    • pendingFixing

      public double pendingFixing(String pair)
      Non-deliverable notional still awaiting its fixing, per pair.

    • settleFixing

      public void settleFixing(String pair, double notional)
      Releases notional (positive, gross) of pending fixing after the fixing occurs. Without this the pending number only ever grows and goes stale the day after the first fixing. The fixed NDF's currency delta must be re-booked separately as the offsetting flow when it cash-settles (position decomposition, not lifecycle; see class doc). Over-settling throws: releasing more than is pending means the caller's fixing ledger disagrees with the book's, which is a reconciliation problem, not a rounding one.

    • flowsBooked

      public long flowsBooked()

    • factors

      public FactorRegistry factors()

    • desks

      public Set<String> desks()

    • report

      public CentralRiskBook.CrbReport report(double[][] covariance, double confidence)
      The book-level risk report. covariance is over the factor space in registry order (factors().name(i)) with entries in (factor-return)² units matching each factor's exposure units — the same contract as VarEngine. The headline number is the diversification benefit: standalone desk VaRs minus the netted book's VaR, i.e. what running the risk centrally is worth.

      VaR and ES are second order (VarEngine.deltaGammaVar(double[], double[][], double[][], double), VarEngine.deltaGammaEs(double[], double[][], double[][], double), Cornish-Fisher). Dollar gamma is not an exposure to a factor return of its own, so the EQGAMMA: and FXGAMMA: rows are taken out of the linear vector and placed in the gamma matrix on their underlying factors, with factor returns read as relative moves:

      • EQGAMMA:s with dollar gamma G per 1% (G = Γ·S²/100) adds ½·100·G·r_s², i.e. Γ[EQ:s][EQ:s] += 100·G;
      • FXGAMMA:BBBQQQ adds ½·100·G·(r_BBB − r_QQQ)² on the two CCY: factors (the pair's relative move is the difference of the two currencies' moves against the reporting currency); G is in quote-currency units, so the report is in one currency only when the quote currency is the reporting one or the caller has converted.

      The covariance rows of the gamma factors are not used and may be zero. Vega rows (EQVEGA:, FXVEGA:) stay linear: their factor return is the change in implied vol in points. For a book without options the result equals delta-normal VaR exactly.

    • writeState

      public void writeState(DataOutput out) throws IOException
      Serializes the whole netted book (factor names, net/gross, per-desk attribution, pending fixings, flow count) for a persist.Checkpoint section. Restore into a fresh instance via readState(DataInput): a book that relearns its positions every morning is not a book.
      Throws:
      IOException

    • readState

      public void readState(DataInput in) throws IOException
      Restores state written by writeState(DataOutput) into this (fresh) book.
      Throws:
      IOException