# Free-Float Market-Cap Index

        **Catalog ID:** `D03-F02-A03`  
        **Domain:** Index and Benchmark Engineering  
        **Family:** Weighting and Capping  
        **Difficulty:** 3/5  
        **Status:** Video-ready

        ## Executive summary

        Free-Float Market-Cap Index lets a benchmark engineer weight constituents by the market value available to public investors. The package implements one transparent educational convention with explicit inputs, timing, diagnostics, and failure behavior. It does not reproduce a proprietary provider index or guarantee investability.

        ## Problem and financial relevance

        An index level is the output of a dated methodology, not a raw market fact. A small mistake in the divisor, free-float factor, tax assumption, FX quote, rebalance weight, or eligibility timestamp can create a false return that propagates into products, performance reports, and research. This topic makes the decision rule inspectable from input record to published output.

        ## Learning objectives

        After completing this topic, a reader can:

        - explain the economic purpose of Free-Float Market-Cap Index;
        - calculate its canonical example and audit every intermediate state;
        - implement the rule in Python and TypeScript from a shared fixture;
        - distinguish sourced provider policy from this package's implementation choices;
        - detect the central failure condition: validate free-float factors in [0,1] and preserve their effective dates.

        ## Prerequisites

        Understand finite numeric data, returns, weights that sum to one, effective dates, and point-in-time constituent records. **Historical Constituent Reconstruction**, **Corporate-Action Divisor Bridge**, and **Point-in-Time Availability Guard** provide the upstream security-master and timing foundations.

        ## Scope and variants

        This package teaches the named calculation at one reproducible level. Production benchmarks additionally require a complete rulebook covering calendars, pricing sources, corporate actions, review schedules, corrections, governance, licensing, and disruption handling. Provider-specific conventions are labeled as such rather than treated as universal mathematics.

        ## Input data contract

        - Numeric values must be finite and use the units declared in the shared fixture.
        - Weights, factors, tax rates, participation rates, and caps use decimal fractions, not percentages.
        - Prices, shares, FX rates, constituent membership, and divisor state share one effective timestamp.
        - FX quotes declare direction; return variants declare dividend and tax treatment.
        - Cross-sectional inputs are point-in-time snapshots; time-series inputs are causally ordered.
        - Missing required inputs, invalid constraints, and ambiguous states are rejected.
        - All distributed data are deterministic synthetic teaching fixtures.

        The exact canonical input is in [`tests/shared_fixture.json`](tests/shared_fixture.json). The extended dataset in [`datasets/synthetic-series.csv`](datasets/synthetic-series.csv) contains enough observations or entities to reveal drift, constraints, and failure boundaries.

        ## Output contract

        The reference implementation returns JSON-compatible values rounded to six decimals at the public boundary. It never mutates input. Weight outputs sum to one within numerical tolerance; index levels remain positive; constraint algorithms expose iteration counts or rejection.

        ## Mathematical formulation

        $$
        w_i = P_i Q_i F_i X_i / \sum_j P_j Q_j F_j X_j
        $$

        Symbols inherit their units from the fixture: $I$ is an index level, $D$ a divisor, $M$ a methodology-defined numerator, $P$ price, $Q$ index shares, $F$ float or adjustment factor, $X$ FX conversion, $w$ weight, and $r$ return. Topic-specific symbols are named in the fixture and worked example. The formula is followed by implementation diagnostics rather than being treated as sufficient on its own.

        ## Algorithm

        1. Freeze the point-in-time inputs and methodology version.
        2. Validate dimensions, finiteness, units, bounds, and feasibility.
        3. Calculate `float_cap` without using future observations.
        4. Recompute invariants: continuity, positive level, weight sum, or constraint satisfaction.
        5. Emit the result with diagnostics needed to reproduce the decision.
        6. Reject the calculation when the declared contract cannot be satisfied.

        ## Canonical worked example

        The shared fixture produces:

        ```json
        {
  "ids": [
    "A",
    "B",
    "C",
    "D"
  ],
  "floatMarketValues": [
    13000000,
    18000000,
    13200000,
    12960000
  ],
  "weights": [
    0.227432,
    0.314906,
    0.230931,
    0.226732
  ]
}
        ```

        Python and TypeScript must return this exact public result. The light guided lab extends the fixture with canonical, boundary, and rejection scenarios and begins in an informative pre-populated state.

        ## Implementation guide

        - Python: [`implementations/python/free_float_market_cap_index.py`](implementations/python/free_float_market_cap_index.py)
        - TypeScript: [`implementations/typescript/free_float_market_cap_index.ts`](implementations/typescript/free_float_market_cap_index.ts)
        - Shared engine contract: [`../../shared/python/index_engine.py`](../../shared/python/index_engine.py)
        - Pseudocode: [`examples/PSEUDOCODE.md`](examples/PSEUDOCODE.md)
        - Shared fixture: [`tests/shared_fixture.json`](tests/shared_fixture.json)

        The topic files expose one small `calculate` function while the domain-level engines centralize validated arithmetic shared across all D03 packages. This avoids forty drifting implementations of divisor, rounding, matrix, and capping primitives.

        ## Testing and validation

        Tests cover the canonical fixture, input immutability, invalid input, JSON finiteness, and Python/TypeScript parity. Domain validation additionally checks catalog parity, package completeness, dataset density, SVG bounds, Mermaid rendering, lab controls, reduced motion, responsive layouts, article embeds, and production builds.

        Definition-level tests prove that the implementation matches the declared convention. They do not prove that the methodology has desirable investment performance, low tracking error, legal benchmark status, or provider parity.

        ## Edge cases and limitations

        - stale prices, FX rates, shares, factors, or divisor state;
        - infeasible caps, singular covariance, or non-convergent iteration;
        - zero denominators, non-positive levels, and extreme returns;
        - missing dividends, tax assumptions, financing rates, or forward rolls;
        - review data revised after the selection cutoff;
        - rounding drift across many constituents or sessions;
        - exceptional market closures and provider discretion.

        The central guard is to validate free-float factors in [0,1] and preserve their effective dates. A plausible chart is not evidence that the operational methodology was followed.

        ## Evidence and limitations

        The [S&P DJI mathematics guide](https://www.spglobal.com/spdji/en/documents/methodologies/methodology-index-math.pdf) and [FTSE Russell Capping Methodology](https://www.lseg.com/content/dam/ftse-russell/en_us/documents/policy-documents/capping-methodology-guide.pdf) show why weighting rules and redistribution order must be explicit. Full source roles, versions, access dates, and limitations are recorded in [`REFERENCES.md`](REFERENCES.md). All datasets are synthetic. This is educational material, not investment, legal, tax, or benchmark-administration advice.

        ## Visual explanations

        - [`visuals/mermaid/calculation-flow.md`](visuals/mermaid/calculation-flow.md) maps inputs to audited output.
        - [`visuals/mermaid/methodology-state.md`](visuals/mermaid/methodology-state.md) shows the decision lifecycle.
        - [`visuals/static/article-hero.svg`](visuals/static/article-hero.svg) separates methodology state from market movement.
        - [`visuals/static/worked-example.svg`](visuals/static/worked-example.svg) annotates the canonical numbers.
        - [`visuals/static/failure-guard.svg`](visuals/static/failure-guard.svg) explains the rejection boundary.
        - [`visuals/animated/playground.html`](visuals/animated/playground.html) is the guided light lab.

        ## Publication derivatives

        - [Publication-ready article](article/ARTICLE.md)
        - [Scene-based video script](video/VIDEO-SCRIPT.md)
        - [Visual asset and validation plan](visuals/VISUAL-PLAN.md)

        ## Related catalog topics

        - Upstream: Historical Constituent Reconstruction and Corporate-Action Divisor Bridge
        - Current family: Weighting and Capping
        - Continue with: **Capped Free-Float Market-Cap Index**

        ## References

        Primary and authoritative sources are documented in [`REFERENCES.md`](REFERENCES.md).