numeraire.core.simulate

Weight-stream portfolio simulator: drift-and-rebalance accounting, conventions explicit.

Given target weights issued at decision (signal) dates and asset returns at data frequency, the simulator produces the realized gross/net portfolio return stream plus per-rebalance turnover and costs. Published papers differ on the exact turnover and cost conventions, so every convention here is an explicit named parameter, never an implicit default buried in the accounting:

• Timing. A weight decided at signal date s first earns the return realized over the data period strictly after s (the same no-look-ahead pairing the OOS engine uses).

• Two accounting modes. target_weight (default): the target is applied to every data row of its holding span — the constant-mix convention of academic horse races (equivalent to cost-free re-trading back to target each row; with one data row per rebalance, the common monthly case, the two modes’ gross returns coincide). drifted_holdings: weights drift with realized returns between rebalances (begin-of-period weights = prior end-of-period weights unless a rebalance overrides — the Return.portfolio behavioral reference).

• Turnover is L1 against the pre-trade drifted weights, sum_i |target_i - drifted_i| (buys plus sells; halve for the long-only one-way figure). The first rebalance trades out of cash, so its turnover is the full initial funding.

• Costs are proportional (cost_bps per unit of L1 turnover), charged once per rebalance to NAV before the holding-period return: net = (1 - cost) * (1 + gross) - 1 on the trade row.

• Cash is the residual 1 - sum(w) and earns rf (zero if not given); negative cash borrows at the same rate (no spread in v1).

• Missing returns on a held asset follow missing: "error" (default — silent zeros bias large panels) or "zero".

• Normalization of incoming targets is a policy, not automatic: "none" (default — academic long-short books are intentionally net-0/gross-2), "net_budget" or "gross_budget".

simulate_weights	Simulate a target-weight stream over data-frequency returns (conventions in module doc).
RebalanceSchedule	Decision (signal) dates mapped to the half-open data-row spans they govern.
SimulationResult	Realized simulation output plus the accounting provenance every result row needs.