Anticipator — module

Contrafactual Anticipators

Wrappers that synthesize structured counterfactual futures on top of a base projector and optional perturbations.

class qmlhc.predictors.anticipator.AnticipatorConfig(branches=3, symmetric=True)

Bases: object

Static configuration controlling counterfactual generation semantics.

Parameters:

• branches (int, optional) – Number of base branches K produced by the projector, by default 3. Must satisfy K >= 2 in downstream usage.

• symmetric (bool, optional) – When True, for every perturbation v around the center, also add its mirrored counterpart (2 * center - v). Default is True.

branches: int = 3

symmetric: bool = True

class qmlhc.predictors.anticipator.ContrafactualAnticipator(projector, perturbations=None, config=None)

Bases: object

Generate structured counterfactual futures on top of a base projector.

Given a current state s_t, first obtains a base set of futures from Projector.project. Then, for each user-provided perturbation, it adds a single variant (and optionally its symmetric mirror) around the base center.

Notes

The final future set is the concatenation of: - the projector’s base set (K, D), - one row per perturbation, - (optionally) one mirrored row per perturbation.

generate(s_t)

Produce a combined future set (K', D) from base projection and variants.

Steps

1. Call the base projector to obtain base_set with shape (K, D).

2. If perturbations are provided, compute the center as mean(base_set, axis=0).

3. For each perturbation p, append p(center) as a new row.

4. If symmetric is enabled, also append the mirrored row 2 * center - p(center).

type s_t:

Union[ndarray, Sequence[float]]

param s_t:

Current state vector (D,).

type s_t:

TensorLike

returns:

Concatenated futures matrix with shape (K', D), where K' >= K depends on the number of perturbations and symmetry.

rtype:

Array