fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Iterative Cap Redistribution

Install and import#

bash
npm install fintech-algorithms
ts
import { calculate } from "fintech-algorithms/index-and-benchmark-engineering/weighting-and-capping/iterative-cap-redistribution";

Signature#

calculate(data)

The redistribution engine behind every capped index. Cap the offenders, spread the excess across the rest in proportion, repeat until nothing breaches — the loop is necessary because each pass can create new breaches.

Parameters#

NameTypeNotes
data{ ids: string[]; rawWeights: number[]; cap: number; tolerance: number; maxIterations: number }tolerance is the convergence threshold and maxIterations the bound that keeps a pathological input from looping forever.

Returns#

{ ids, weights, cap, iterations, maxWeight, weightSum }

Converged weights with the iteration count. weightSum should be 1 to within tolerance — if it is not, the loop hit its bound.

Errors#

  • When cap × count < 1, which makes compliance impossible — throws

Complexity: time O(n × iterations), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

data
{
  "ids": ["A", "B", "C", "D", "E", "F"],
  "rawWeights": [0.42, 0.22, 0.14, 0.1, 0.07, 0.05],
  "cap": 0.25,
  "tolerance": 1e-10,
  "maxIterations": 100
}

Call#

calculate(data)

Returns#

object with 6 fields: ids, weights, cap, iterations, maxWeight, weightSum

{
  "ids": ["A", "B", "C", "D", "E", "F"],
  "weights": [0.25, 0.25, 0.194444, 0.138889, 0.097222, 0.069444],
  "cap": 0.25,
  "iterations": 3,
  "maxWeight": 0.25,
  "weightSum": 1
}

Diagrams#

Iterative Cap Redistribution — article hero
Iterative Cap Redistribution — failure guard
Iterative Cap Redistribution — worked example

Calculation flow#

Iterative Cap Redistribution calculation flow 
flowchart LR
    A["Point-in-time inputs"] --> B["Validate units and timing"]
    B --> C{"Contract feasible?"}
    C -->|No| D["Reject with reason"]
    C -->|Yes| E["Calculate Iterative Cap Redistribution"]
    E --> F["Recompute invariants"]
    F --> G{"Checks pass?"}
    G -->|No| D
    G -->|Yes| H["Publish audited output"]
Iterative Cap Redistribution methodology state 
stateDiagram-v2
    [*] --> FrozenInputs
    FrozenInputs --> Validated: contract passes
    FrozenInputs --> Rejected: missing or infeasible
    Validated --> Calculated: apply named rule
    Calculated --> Audited: invariants pass
    Calculated --> Rejected: invariant fails
    Audited --> Published: version and timestamp recorded
    Published --> Revised: approved correction
    Revised --> FrozenInputs: rebuild from retained source state

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the Weighting and Capping family#