scimba_torch.utils.scimba_tensors¶

Utility classes for handling tensors with associated labels in PyTorch.

Classes

`LabelTensor`(x[, labels])	Class for tensors representing space coordinates.
`MultiLabelTensor`(w[, labels])	A class to manage tensors with space coordinates and associated labels.

class MultiLabelTensor(w, labels=[])[source]¶

Bases: object

A class to manage tensors with space coordinates and associated labels.

Parameters:

w (Tensor) – The main tensor of coordinates, expected to have shape (batch_size, dim).
labels (list[Tensor] | None) – A list of tensors containing labels for filtering operations. Defaults to empty list.

Raises:

ValueError – If input tensor has dimension <= 1, or if w and labels have different shapes[0].

w: Tensor¶: The main tensor representing coordinates

size: int¶: Number of dimensions in the coordinates

labels: list[Tensor]¶: A list of label tensors, where each tensor contains integer labels associated with the corresponding batch entries.

shape: Size¶: The shape of the tensor w, useful for validation and debugging.

get_components(index=None)[source]¶

Retrieve specific components of the tensor w.

Parameters:

index (int | None) – The specific dimension to extract from the tensor. If None, all dimensions are extracted as a tuple of tensors.

Return type:

Tensor | tuple[Tensor, ...]

Returns:

If index is specified, a single tensor corresponding to the selected dimension.
If index is None, a tuple of tensors for all dimensions.

restrict_to_labels(component=None, labels=[])[source]¶

Filter tensor w (or one of its components) by a list of reference labels.

Parameters:

component (Tensor | None) – The specific component to be filtered. If None, self.w.
labels (list[int] | None) – A list of integers specifying the reference labels to filter rows. If None, no filtering is applied.

Returns:

If component and labels are specified, component filtered by input list of labels
If component is None and labels are specified, self.w filtered by input list of labels
If component is provided and labels is None, a copy of component
Otherwise a copy of self.w

Return type:

Filtered tensor based on the following logic

Raises:

ValueError – If provided reference labels do not match the structure of the label tensors.

class LabelTensor(x, labels=None)[source]¶

Bases: object

Class for tensors representing space coordinates.

Parameters:

x (Tensor) – Coordinates tensor.
labels (Tensor | None) – Labels for the coordinates (e.g. labels for boundary conditions, etc.). If None, creates zero labels.

Raises:

ValueError – If x has dimension <= 1, or if x and labels have different shape[0].

x: Tensor¶: Coordinate tensor

dim: int¶: Space dimension

labels: Tensor¶: Labels for the coordinates

repeat(repeats)[source]¶

Overload the repeat function.

Parameters:: repeats (int | Tensor) – The size of the repeat.
Return type:: LabelTensor
Returns:: New LabelTensor with repeated coordinates and labels.

get_components(label=None)[source]¶

Returns the components from the current LabelTensor.

Parameters:

label (int | None) – The label of the x that the users want. If None, returns all components.

Return type:

Tensor | tuple[Tensor, ...]

Returns:

The list of coordinates. If dim=1, returns single tensor, otherwise tuple of: tensors.

Raises:

ValueError – If no coordinates with the specified label are found.

static cat(inputs)[source]¶

Concatenate a list of LabelTensors.

Parameters:: inputs (Sequence[LabelTensor]) – The list of LabelTensors to concatenate.
Return type:: LabelTensor
Returns:: The LabelTensor which contains all the previous LabelTensors.

detach()[source]¶

Detach the space tensor.

Returns:: The LabelTensor where x is detached on CPU.

no_grad()[source]¶

Returns a LabelTensor with no grad on x.

Return type:: LabelTensor
Returns:: A LabelTensor with x detached from the computation graph.

unsqueeze(dim)[source]¶

Unsqueeze the space tensor.

Parameters:: dim (int) – Dimension to unsqueeze.
Return type:: LabelTensor
Returns:: A LabelTensor with the specified dimension unsqueezed.

concatenate(other, dim)[source]¶

Concatenate two LabelTensors along a specified dimension.

Parameters:

other (LabelTensor) – The LabelTensor to concatenate with the current instance.
dim (int) – The dimension along which to concatenate.

Return type:

LabelTensor

Returns:

The LabelTensor which contains the concatenation of the two LabelTensors.