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(java.lang.String, double) once fixings occur. This is a RISK ledger, not a cash ledger: premium and settlement cash legs are deliberately untracked (the same delta-only stance for cash equities — no settlement cash — and options — 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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    CentralRiskBook.CrbReport
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    CentralRiskBook()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    bookCashEquity(String desk, String symbol, double qty, double price)
    Cash equity: qty shares (signed) at price.
    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).
    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).
    void
    bookFxSpot(String desk, String pair, double baseNotional, double rate)
    FX spot on pair ("EURUSD"): buy baseNotional of the base currency (signed) at rate.
    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.
    void
    bookNdf(String desk, String pair, double baseNotional, double fwdRate)
    NDF: buy baseNotional of base forward at fwdRate.
    double
    deskExposure(String desk, String factor)
    One desk's net contribution to a factor.
    Set<String>
    desks()
     
    double
    exposure(String factor)
    Net exposure on a factor (0 for a factor never booked).
    FactorRegistry
    factors()
     
    long
    flowsBooked()
     
    double
    grossExposure(String factor)
    Gross (sum of |flow|) on a factor — what the desks did severally.
    double[]
    netExposures()
    Net exposures over all factors, indexed by registry id.
    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.
    double
    pendingFixing(String pair)
    Non-deliverable notional still awaiting its fixing, per pair.
    void
    readState(DataInput in)
    Restores state written by writeState(java.io.DataOutput) into THIS (fresh) book.
    CentralRiskBook.CrbReport
    report(double[][] covariance, double confidence)
    The book-level risk report.
    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.
    void
    writeState(DataOutput out)
    Serializes the whole netted book — factor names, net/gross, per-desk attribution, pending fixings, flow count — for a persist.Checkpoint section.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CentralRiskBook

      public CentralRiskBook()

  • Method Details

    • bookCashEquity

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

    • 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).

    • 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.

    • 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.

    • 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).

    • 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.

    • 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.

    • 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(java.io.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(java.io.DataOutput) into THIS (fresh) book.
      Throws:
      IOException