Hypercausal Policy

Projection Policies

Strategies to aggregate K candidate futures into a single representative vector.

This module provides three policies:

• MeanPolicy: element-wise arithmetic mean across branches.

• MedianPolicy: element-wise median across branches.

• MinRiskPolicy: selects the single branch that minimizes a user-provided risk functional.

class qmlhc.hc.policy.MeanPolicy(*args, **kwargs)

Bases: ProjectionPolicy

Element-wise arithmetic mean across branches.

Notes

The representative vector is computed as mean(futures, axis=0). Diagnostic info includes the policy name and number of branches.

select(futures)

Select a representative by averaging all candidate branches.

Parameters:

futures (Array) – Matrix of candidate futures with shape (K, D).

Returns:

(rep, diag) where: - rep is the element-wise mean with shape (D,). - diag contains {"policy": "mean", "branches": K}.

Return type:

tuple

Raises:

ValueError – If futures is not a 2-D array.

class qmlhc.hc.policy.MedianPolicy(*args, **kwargs)

Bases: ProjectionPolicy

Element-wise median across branches.

Notes

The representative vector is computed as median(futures, axis=0). Diagnostic info includes the policy name and number of branches.

select(futures)

Select a representative by taking the median per dimension.

Parameters:

futures (Array) – Matrix of candidate futures with shape (K, D).

Returns:

(rep, diag) where: - rep is the element-wise median with shape (D,). - diag contains {"policy": "median", "branches": K}.

Return type:

tuple

Raises:

ValueError – If futures is not a 2-D array.

class qmlhc.hc.policy.MinRiskPolicy(risk)

Bases: ProjectionPolicy

Select the single branch minimizing a provided risk functional.

Parameters:

risk (RiskFunctional) – Callable that scores a branch (D,) → float, where lower is better.

Notes

The chosen representative is futures[argmin(scores)]. Diagnostics include the policy name, number of branches, the chosen index, and the minimal score value.

select(futures)

Select a representative by minimizing the risk score across branches.

Parameters:

futures (Array) – Matrix of candidate futures with shape (K, D).

Returns:

(rep, diag) where: - rep is the selected branch with shape (D,). - diag contains - {"policy": "min-risk", "branches": K, "chosen_index": i, "min_score": s}.

Return type:

tuple

Raises:

ValueError – If futures is not a 2-D array.