gunz_cm.reconstructions.objectives package

Submodules

gunz_cm.reconstructions.objectives.consts module

Defines shared constants related to reconstruction functions.

This module centralizes mappings from string identifiers to NumPy and PyTorch functions used for mathematical operations and loss calculations, ensuring consistent access throughout the library.

Examples

gunz_cm.reconstructions.objectives.general_error module

Implements a general-purpose error function that is compatible with both NumPy and PyTorch, applying specified term and reduction operations.

Examples

class gunz_cm.reconstructions.objectives.general_error.GeneralError(term: str = 'square', reduction: str = 'mean')

Bases: BaseBinaryOP

A general error function for computing loss between an input and a target.

This class provides a flexible way to calculate errors by combining different term functions (‘l1’, ‘l2’) and reduction methods (‘mean’, ‘sum’). It handles both NumPy and PyTorch tensors.

termstr, default=’square’

The term function to use. Valid options are ‘abs’, ‘square’, ‘l1’, ‘l2’. ‘abs’ is mapped to ‘l1’, and ‘square’ is mapped to ‘l2’.

reductionstr, default=’mean’

The reduction method to apply to the loss. Valid options are ‘mean’, ‘sum’.

ValueError

If an invalid term or reduction is specified.

For PyTorch, this class leverages F.l1_loss and F.mse_loss, which are efficient as they combine the term and reduction steps. For NumPy, the operations are performed sequentially.

Examples

gunz_cm.reconstructions.objectives.mds module

Implements Multi-Dimensional Scaling (MDS) and its weighted variant as loss functions compatible with both NumPy and PyTorch.

Examples

class gunz_cm.reconstructions.objectives.mds.MultiDimensionalScaling(term: str = 'abs', reduction: str = 'mean', eps: float = 1e-08)

Bases: BaseBinaryOP

Computes the Multi-Dimensional Scaling (MDS) loss between two tensors.

This loss is calculated as the ratio of the error between input and target to the magnitude of the target, aggregated by a reduction function.

It supports both NumPy arrays and PyTorch tensors.

termstr, default=’abs’

The element-wise function to apply to the error and the target. Must be one of {‘abs’, ‘square’}.

reductionstr, default=’mean’

The method for reducing the element-wise losses to a single value. Must be one of {‘mean’, ‘sum’}.

epsfloat, default=1e-8

A small epsilon value added to the denominator for numerical stability to prevent division by zero.

ValueError

If an invalid term or reduction is specified.

The formula is: Loss = reduction(term(target - input) / term(target))

Examples

class gunz_cm.reconstructions.objectives.mds.WeightedMultiDimensionalScaling(term: str = 'square', reduction: str = 'mean', weight_exp: float = 1.0, eps: float = 1e-08)

Bases: BaseBinaryOP

Computes a weighted Multi-Dimensional Scaling (WMDS) loss.

This loss function applies a weight to the term-wise error, where the weight is derived from the target tensor.

termstr, default=’square’

The element-wise function to apply to the error. Must be one of {‘abs’, ‘square’}.

reductionstr, default=’mean’

The reduction method. Must be one of {‘mean’, ‘sum’}.

weight_expfloat, default=1.0

The exponent applied to the target to calculate the weights.

epsfloat, default=1e-8

A small epsilon value for numerical stability, used in the denominator of the weighted mean calculation.

ValueError

If an invalid term or reduction is specified.

The formula is:

weights = target ** weight_exp weighted_loss = weights * term(target - input)

For ‘mean’ reduction, the result is sum(weighted_loss) / sum(weights). For ‘sum’ reduction, the result is sum(weighted_loss).

Examples

gunz_cm.reconstructions.objectives.procrustes module

Procrustes Analysis

This code provides functions to perform Procrustes analysis on two sets of points.

This version includes standard (L2), robust (L1), and IRLS methods for both NumPy and PyTorch backends.

The tool uses NumPy for data handling, SciPy for the core Procrustes algorithm.

Examples

class gunz_cm.reconstructions.objectives.procrustes.Method(value)

Bases: str, Enum

Class Method.

Examples

Notes

IRLS = 'irls'

ROBUST_L1 = 'robust-l1'

VANILLA = 'vanilla'

exception gunz_cm.reconstructions.objectives.procrustes.ProcrustesError

Bases: Exception

Custom exception for errors during Procrustes analysis.

Examples

class gunz_cm.reconstructions.objectives.procrustes.ProcrustesResult(distance: float | Tensor, scaled_input: ndarray | Tensor, aligned_target: ndarray | Tensor, centered_input: ndarray | Tensor, centered_target: ndarray | Tensor, rotation_matrix: ndarray | Tensor)

Bases: object

A dataclass to hold the results of a Procrustes analysis.

Examples

aligned_target: ndarray | Tensor

centered_input: ndarray | Tensor

centered_target: ndarray | Tensor

distance: float | Tensor

rotation_matrix: ndarray | Tensor

scaled_input: ndarray | Tensor

gunz_cm.reconstructions.objectives.procrustes.procrustes_analysis(input: Any, target: Any, method: Method = Method.VANILLA, max_iter: int = 100, tol: float = 1e-06) → ProcrustesResult

gunz_cm.reconstructions.objectives.procrustes.procrustes_analysis(input: ndarray, target: ndarray, method: Method = Method.VANILLA, max_iter: int = 100, tol: float = 1e-06) → ProcrustesResult

gunz_cm.reconstructions.objectives.procrustes.procrustes_analysis(input: Tensor, target: Tensor, method: Method = Method.VANILLA, max_iter: int = 100, tol: float = 1e-06) → ProcrustesResult

Function procrustes_analysis.

Examples

Notes

Module contents