Targets

Target functional contracts for update-support problems.

exception updatesupport.targets.UnsupportedTargetError[source]

Bases: TypeError

Raised when a target functional is outside the supported contract.

class updatesupport.targets.TargetCapabilities(supports_adequacy, supports_interval, supports_fiber_decomposition, supports_exact_lower=False, supports_exact_upper=False, supports_conservative_interval=False)[source]

Bases: object

Capability flags for target-level operations.

Parameters:

  • supports_adequacy (bool)

  • supports_interval (bool)

  • supports_fiber_decomposition (bool)

  • supports_exact_lower (bool)

  • supports_exact_upper (bool)

  • supports_conservative_interval (bool)

supports_adequacy: bool
supports_interval: bool
supports_fiber_decomposition: bool
supports_exact_lower: bool = False
supports_exact_upper: bool = False
supports_conservative_interval: bool = False
classmethod none()[source]
Return type:

TargetCapabilities

classmethod linear()[source]
Return type:

TargetCapabilities

as_dict()[source]
Return type:

dict[str, bool]

class updatesupport.targets.TargetContract(kind, name, formula, description, fixed_after_compilation, supports_adequacy, supports_interval, supports_fiber_decomposition, limitations=(), supports_exact_lower=None, supports_exact_upper=None, supports_conservative_interval=None)[source]

Bases: object

Human- and machine-readable contract for a target functional.

Parameters:

  • kind (str)

  • name (str)

  • formula (str)

  • description (str)

  • fixed_after_compilation (bool)

  • supports_adequacy (bool)

  • supports_interval (bool)

  • supports_fiber_decomposition (bool)

  • limitations (tuple[str, ...])

  • supports_exact_lower (bool | None)

  • supports_exact_upper (bool | None)

  • supports_conservative_interval (bool | None)

kind: str
name: str
formula: str
description: str
fixed_after_compilation: bool
supports_adequacy: bool
supports_interval: bool
supports_fiber_decomposition: bool
limitations: tuple[str, ...] = ()
supports_exact_lower: bool | None = None
supports_exact_upper: bool | None = None
supports_conservative_interval: bool | None = None
property capabilities: TargetCapabilities
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.targets.UnsupportedTarget(name, kind, formula, description='', reason='This target functional is not supported by the current fixed linear target backend.', limitations=())[source]

Bases: object

Explicit marker for target functionals not yet supported by core solvers.

Parameters:
name: str
kind: str
formula: str
description: str = ''
reason: str = 'This target functional is not supported by the current fixed linear target backend.'
limitations: tuple[str, ...] = ()
property contract: TargetContract
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.targets.ProcedureTargetContext(data, public, hidden, weight=None, min_cell_weight=1.0, q='saturated', q_radius=None)[source]

Bases: object

Context supplied when compiling a representation-dependent target.

A procedure target is compiled by tabular workflows before a finite FiniteProblem is constructed. The compiler should return a column name or row metric for the supplied public representation.

Parameters:
data: Any
public: tuple[str, ...]
hidden: tuple[str, ...]
weight: str | None = None
min_cell_weight: float = 1.0
q: Any = 'saturated'
q_radius: float | None = None
property row_count: int | None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.targets.ProcedureTarget(name, compiler, description='', formula='public representation -> compiled target values -> reported aggregate', limitations=())[source]

Bases: object

Representation-dependent target compiled by tabular workflows.

compiler receives a ProcedureTargetContext and must return the actual column name or row metric to use for that representation. The compiled target is then treated as a fixed hidden-cell target by the finite solver.

Parameters:
name: str
compiler: Callable[[ProcedureTargetContext], Any]
description: str = ''
formula: str = 'public representation -> compiled target values -> reported aggregate'
limitations: tuple[str, ...] = ()
property contract: TargetContract
property compiler_name: str
compile(context)[source]

Return the column name or row metric for context.

Parameters:

context (ProcedureTargetContext)

Return type:

Any

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.targets.LinearTarget(values, name='linear_target', description='fixed linear plug-in target', source=None)[source]

Bases: object

Fixed linear plug-in target psi(q) = sum_d h(d) q(d).

Parameters:
values: Mapping[Hashable, float]
name: str = 'linear_target'
description: str = 'fixed linear plug-in target'
source: str | None = None
property contract: TargetContract
value(state)[source]
Parameters:

state (Hashable)

Return type:

float

point_value(state)[source]
Parameters:

state (Hashable)

Return type:

float

support_key(state)[source]
Parameters:

state (Hashable)

Return type:

float

dot(states, vector)[source]
Parameters:
Return type:

float

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.targets.UncertainLinearTarget(values, standard_errors, name='uncertain_linear_target', description='fixed linear target with estimator standard errors', confidence_multiplier=1.96, source=None)[source]

Bases: object

Fixed linear plug-in target with hidden-cell estimator standard errors.

Parameters:
values: Mapping[Hashable, float]
standard_errors: Mapping[Hashable, float]
name: str = 'uncertain_linear_target'
description: str = 'fixed linear target with estimator standard errors'
confidence_multiplier: float = 1.96
source: str | None = None
property contract: TargetContract
value(state)[source]
Parameters:

state (Hashable)

Return type:

float

point_value(state)[source]
Parameters:

state (Hashable)

Return type:

float

standard_error(state)[source]
Parameters:

state (Hashable)

Return type:

float

support_key(state)[source]
Parameters:

state (Hashable)

Return type:

float

dot(states, vector)[source]
Parameters:
Return type:

float

standard_error_for_distribution(states, vector)[source]
Parameters:
Return type:

float

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.targets.MomentTransformTarget(moments, transform, name='moment_transform', description='fixed transform of linear moments', affine_coefficients=None, intercept=0.0, curvature='unknown', monotonicity=(), cvxpy_transform=None, capabilities=None, formula=None, source=None, limitations=())[source]

Bases: object

Fixed transform of one or more linear moments.

The mathematical form is psi(q) = g(mu(q)) where each moment is mu_j(q) = sum_d m_j(d) q(d). Affine transforms reduce to fixed linear hidden-cell targets. Convex or concave transforms can expose one exact CVXPY endpoint, and monotone transforms can expose conservative interval bounds from separately optimized moment boxes.

Parameters:
moments: Mapping[str, Mapping[Hashable, float]]
transform: Callable[[Mapping[str, float]], float]
name: str = 'moment_transform'
description: str = 'fixed transform of linear moments'
affine_coefficients: Mapping[str, float] | None = None
intercept: float = 0.0
curvature: str = 'unknown'
monotonicity: Mapping[str, str] = ()
cvxpy_transform: Callable[[Any, Mapping[str, Any]], Any] | None = None
capabilities: TargetCapabilities | None = None
formula: str | None = None
source: str | None = None
limitations: tuple[str, ...] = ()
property is_affine: bool
property resolved_capabilities: TargetCapabilities
property supports_exact_lower_endpoint: bool
property supports_exact_upper_endpoint: bool
property supports_conservative_interval: bool
property has_supported_behavior: bool
property supports_linear_backend: bool
property contract: TargetContract
property values: dict[Hashable, float]
moment_value(moment, state)[source]
Parameters:
Return type:

float

moment_vector(moment, states)[source]
Parameters:
Return type:

tuple[float, …]

moment_dot(moment, states, vector)[source]
Parameters:
Return type:

float

moment_values(states, vector)[source]
Parameters:
Return type:

dict[str, float]

dot(states, vector)[source]
Parameters:
Return type:

float

point_value(state)[source]
Parameters:

state (Hashable)

Return type:

float

transform_value(moments)[source]
Parameters:

moments (Mapping[str, float])

Return type:

float

cvxpy_expression(cp, moments)[source]
Parameters:
Return type:

Any

conservative_box_values(moment_bounds)[source]
Parameters:

moment_bounds (Mapping[str, tuple[float, float]])

Return type:

tuple[float, float]

value(state)[source]
Parameters:

state (Hashable)

Return type:

float

support_key(state)[source]
Parameters:

state (Hashable)

Return type:

float | tuple[float, …]

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.targets.RatioTarget(numerator, denominator, name='ratio_target', description='fixed linear-fractional ratio target', source=None)[source]

Bases: object

Fixed ratio target psi(q) = <n,q> / <w,q>.

The denominator must be strictly positive on every retained state. General constrained-Q ratio support is intentionally narrow; saturated public-fiber environments solve ratio intervals exactly, standard CVXPY can solve local fixed-public-law ratio intervals through DQCP, and linear backends can use a ratio target when the denominator is constant over the state space.

Parameters:
numerator: Mapping[Hashable, float]
denominator: Mapping[Hashable, float] | float
name: str = 'ratio_target'
description: str = 'fixed linear-fractional ratio target'
source: str | None = None
property contract: TargetContract
property values: dict[Hashable, float]
numerator_value(state)[source]
Parameters:

state (Hashable)

Return type:

float

denominator_value(state)[source]
Parameters:

state (Hashable)

Return type:

float

point_value(state)[source]
Parameters:

state (Hashable)

Return type:

float

value(state)[source]
Parameters:

state (Hashable)

Return type:

float

support_key(state)[source]
Parameters:

state (Hashable)

Return type:

float | tuple[float, float]

numerator_dot(states, vector)[source]
Parameters:
Return type:

float

denominator_dot(states, vector)[source]
Parameters:
Return type:

float

dot(states, vector)[source]
Parameters:
Return type:

float

has_constant_denominator(states)[source]
Parameters:

states (Sequence[Hashable])

Return type:

bool

numerator_vector(states)[source]
Parameters:

states (Sequence[Hashable])

Return type:

tuple[float, …]

denominator_vector(states)[source]
Parameters:

states (Sequence[Hashable])

Return type:

tuple[float, …]

as_dict()[source]
Return type:

dict[str, Any]

updatesupport.targets.coerce_linear_target(states, value, *, name='linear_target', description='fixed linear plug-in target', source=None)[source]

Coerce mappings, sequences, callables, or LinearTarget objects.

Parameters:
Return type:

LinearTarget | UncertainLinearTarget

updatesupport.targets.coerce_target(states, value, *, name='linear_target', description='fixed linear plug-in target', source=None)[source]

Coerce a supported target functional.

Parameters:
Return type:

LinearTarget | UncertainLinearTarget | MomentTransformTarget | RatioTarget

updatesupport.targets.raise_if_unsupported_target(value, *, context)[source]

Raise when value declares a non-linear or unsupported target contract.

Parameters:
Return type:

None

updatesupport.targets.declared_target_contract(value)[source]

Return a declared target contract from marker/future target objects.

Parameters:

value (Any)

Return type:

TargetContract | None