gunz_cm.reconstructions.objectives#

Module contents#

Initialization module for the objectives package.

DOP Phase 4 (v2.21.0) introduced frozen config dataclasses and free singledispatch loss functions as the canonical loss-computation surface. DOP Phase 8 (v2.25.0) REMOVED the OOP class wrappers (MultiDimensionalScaling, WeightedMultiDimensionalScaling, GeneralError) that were introduced in v2.21.0 as back-compat shims around the free functions. Use the canonical surface directly:

from gunz_cm.reconstructions.objectives import (

MDSConfig, WMDSConfig, GeneralErrorConfig, # data mds_loss, wmds_loss, general_error_loss, # computation

)

Examples

pass

class gunz_cm.reconstructions.objectives.GeneralErrorConfig(term: str = 'square', reduction: str = 'mean')[source]#

Bases: object

Immutable configuration for the general-purpose error loss.

Parameters:

  • term (str, default='square') – Term function. Must be in VALID_TERM_GENERAL. The values 'abs' and 'square' are normalised to 'l1' / 'l2' at construction.

  • reduction (str, default='mean') – Reduction method. Must be in VALID_REDUCTION.

Raises:

ReconstructionError – If term or reduction is invalid.

Examples

>>> cfg = GeneralErrorConfig(term='square', reduction='mean')
>>> cfg.term
'l2'
reduction: str = 'mean'#
term: str = 'square'#
class gunz_cm.reconstructions.objectives.MDSConfig(term: str = 'abs', reduction: str = 'mean', eps: float = 1e-08)[source]#

Bases: object

Immutable configuration for the Multi-Dimensional Scaling loss.

Parameters:

  • term (str, default='abs') – Element-wise function applied to the error and target. Must be one of VALID_TERM_MDS = {‘abs’, ‘square’}.

  • reduction (str, default='mean') – Method for reducing element-wise losses to a single value. Must be one of VALID_REDUCTION = {‘mean’, ‘sum’}.

  • eps (float, default=1e-8) – Small epsilon added to the denominator for numerical stability.

Raises:

ReconstructionError – If term or reduction is not in the allowed set.

Examples

>>> cfg = MDSConfig(term='abs', reduction='mean')
>>> cfg.term
'abs'
eps: float = 1e-08#
reduction: str = 'mean'#
term: str = 'abs'#
class gunz_cm.reconstructions.objectives.WMDSConfig(term: str = 'square', reduction: str = 'mean', weight_exp: float = 1.0, eps: float = 1e-08)[source]#

Bases: object

Immutable configuration for the Weighted Multi-Dimensional Scaling loss.

Parameters:

  • term (str, default='square') – Element-wise function. Must be in VALID_TERM_MDS.

  • reduction (str, default='mean') – Reduction method. Must be in VALID_REDUCTION.

  • weight_exp (float, default=1.0) – Exponent applied to target to compute per-element weights.

  • eps (float, default=1e-8) – Small epsilon added to the denominator of the weighted mean.

Raises:

ReconstructionError – If term or reduction is invalid.

Examples

>>> cfg = WMDSConfig(term='square', reduction='mean', weight_exp=1.0)
>>> cfg.weight_exp
1.0
eps: float = 1e-08#
reduction: str = 'mean'#
term: str = 'square'#
weight_exp: float = 1.0#
gunz_cm.reconstructions.objectives.general_error_loss(input: Any, target: Any, config: GeneralErrorConfig) → Any[source]#
gunz_cm.reconstructions.objectives.general_error_loss(input: ndarray, target: ndarray, config: GeneralErrorConfig) → float
gunz_cm.reconstructions.objectives.general_error_loss(input: Tensor, target: Tensor, config: GeneralErrorConfig) → Tensor

Compute the general error loss for the given input type.

Parameters:

  • input (numpy.ndarray or torch.Tensor) – The input data.

  • target (numpy.ndarray or torch.Tensor) – The target data.

  • config (GeneralErrorConfig) – Frozen configuration holding term (one of {l1, l2, abs, square}; abs and square are normalised to l1 / l2 at config construction) and reduction.

Returns:

The reduced error value.

Return type:

float or torch.Tensor

Examples

>>> cfg = GeneralErrorConfig(term='square', reduction='mean')
>>> import numpy as np
>>> general_error_loss(np.array([1.0, 2.0]), np.array([4.0, 5.0]), cfg)
gunz_cm.reconstructions.objectives.mds_loss(input: Any, target: Any, config: MDSConfig) → Any[source]#
gunz_cm.reconstructions.objectives.mds_loss(input: ndarray, target: ndarray, config: MDSConfig) → float
gunz_cm.reconstructions.objectives.mds_loss(input: Tensor, target: Tensor, config: MDSConfig) → Tensor

Compute the MDS loss for the given input type.

Parameters:

  • input (numpy.ndarray or torch.Tensor) – The input data (predictions).

  • target (numpy.ndarray or torch.Tensor) – The target data (ground truth).

  • config (MDSConfig) – Frozen configuration holding term, reduction, eps.

Returns:

The reduced loss value. Type matches input.

Return type:

float or torch.Tensor

Raises:

NotImplementedError – If input is neither np.ndarray nor torch.Tensor (the singledispatch default implementation).

Examples

>>> cfg = MDSConfig(term='abs', reduction='mean')
>>> import numpy as np
>>> mds_loss(np.array([1.0, 2.0]), np.array([4.0, 5.0]), cfg)
gunz_cm.reconstructions.objectives.wmds_loss(input: Any, target: Any, config: WMDSConfig) → Any[source]#
gunz_cm.reconstructions.objectives.wmds_loss(input: ndarray, target: ndarray, config: WMDSConfig) → float
gunz_cm.reconstructions.objectives.wmds_loss(input: Tensor, target: Tensor, config: WMDSConfig) → Tensor

Compute the Weighted MDS loss for the given input type.

Parameters:

  • input (numpy.ndarray or torch.Tensor) – The input data.

  • target (numpy.ndarray or torch.Tensor) – The target data.

  • config (WMDSConfig) – Frozen configuration holding term, reduction, weight_exp, eps.

Returns:

The reduced weighted loss value.

Return type:

float or torch.Tensor

Raises:

NotImplementedError – If input is neither np.ndarray nor torch.Tensor.

Examples

>>> cfg = WMDSConfig(term='square', reduction='mean', weight_exp=1.0)
>>> import numpy as np
>>> wmds_loss(np.array([1.0, 2.0]), np.array([4.0, 5.0]), cfg)