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

Group-Level Capping

Install and import#

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

Signature#

calculate(data)

Caps at two levels at once: each constituent, and each group it belongs to. This is the UCITS 5/10/40 shape, and the two constraints interact — satisfying one can break the other, so both are enforced together.

Parameters#

NameTypeNotes
data{ items: Item[]; constituentCap: number; groupCaps: Record<string, number>; tolerance: number; maxIterations: number }items carry each constituent's group membership. groupCaps may differ per group — sector limits are rarely uniform.

Returns#

{ ids, weights, groupWeights, iterations, weightSum }

Weights satisfying both constraint levels, with the realised group weights so compliance is visible rather than implied.

Errors#

  • When the combination of caps is unsatisfiable — 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
{
  "items": [
    {
      "id": "A",
      "group": "Tech",
      "weight": 0.35
    },
    {
      "id": "B",
      "group": "Tech",
      "weight": 0.25
    },
    {
      "id": "C",
      "group": "Finance",
      "weight": 0.18
    }
  ],
  "constituentCap": 0.3,
  "groupCaps": {
    "Tech": 0.5,
    "Finance": 0.6,
    "Health": 0.6
  },
  "tolerance": 1e-9,
  "maxIterations": 200
}

Call#

calculate(data)

Returns#

object with 5 fields: ids, weights, groupWeights, iterations, weightSum

{
  "ids": ["A", "B", "C", "D", "E"],
  "weights": [0.263514, 0.236486, 0.209508, 0.154426, 0.136066],
  "groupWeights": {
    "Tech": 0.5,
    "Finance": 0.363934,
    "Health": 0.136066
  },
  "iterations": 4,
  "weightSum": 1
}

Diagrams#

Group-Level Capping — article hero
Group-Level Capping — failure guard
Group-Level Capping — worked example

Calculation flow#

Group-Level Capping 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 Group-Level Capping"]
    E --> F["Recompute invariants"]
    F --> G{"Checks pass?"}
    G -->|No| D
    G -->|Yes| H["Publish audited output"]
Group-Level Capping 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#