Utilities

class sdofmv2.utils.utils.AttributeDict[source]

Bases: dict

A dictionary subclass that allows attribute-style access to its keys.

This class lets you use dot notation like obj.key to get and set dictionary items. It keeps all standard dictionary methods and uses __slots__ to save memory by preventing the creation of an instance dictionary.

Parameters:

  • *args – Positional arguments passed to the dict constructor.

  • **kwargs – Keyword arguments passed to the dict constructor.

Returns:

A new AttributeDict instance.

sdofmv2.utils.utils.apply_hmi_mask(data, hmi_mask, value)[source]

Apply an HMI mask to solar image data.

Replaces pixels outside the solar disk (where hmi_mask is 0) with a specified scalar value. The mask is applied only to HMI channels; AIA channels remain unchanged.

Parameters:

  • data (torch.Tensor) – The input data tensor of shape (B, C, H, W) or (C, H, W).

  • hmi_mask (torch.Tensor) – A binary mask where 1 represents pixels inside the solar disk and 0 represents pixels outside.

  • value (float) – The scalar value to replace masked pixels with.

Returns:

The masked data tensor with the same shape as input.

Return type:

torch.Tensor

sdofmv2.utils.utils.days_hours_mins_secs_str(total_seconds)[source]

Convert a duration in seconds to a human-readable string.

Parameters:

total_seconds (int or float) – The total number of seconds.

Returns:

A formatted string in the format ‘Dd:Hh:Mm:Ss’.

Return type:

str

sdofmv2.utils.utils.flatten_dict(d, parent_key='', sep='_')[source]

Flatten a nested dictionary into a single-level dictionary.

Parameters:

  • d (dict) – The input dictionary to flatten.

  • parent_key (str, optional) – The prefix for nested keys. Defaults to “”.

  • sep (str, optional) – The separator between parent and child keys. Defaults to “_”.

Returns:

A flattened dictionary with keys joined by the separator.

Return type:

dict

sdofmv2.utils.utils.get_1d_sincos_pos_embed_from_grid(embed_dim, pos)[source]

Generate 1D sine-cosine positional embeddings.

Parameters:

  • embed_dim (int) – The output dimension for each position (must be even).

  • pos (ndarray) – A list or array of positions to be encoded, shape (M,).

Returns:

Positional embeddings of shape (M, embed_dim).

Return type:

ndarray

sdofmv2.utils.utils.get_2d_sincos_pos_embed(embed_dim, grid_size, cls_token=False)[source]

Generate 2D sine-cosine positional embeddings.

Parameters:

  • embed_dim (int) – The embedding dimension for each position.

  • grid_size (int) – The grid height and width (assumed square).

  • cls_token (bool, optional) – If True, prepends a zero vector for CLS token. Defaults to False.

Returns:

Positional embeddings of shape

[grid_size*grid_size, embed_dim] or [1+grid_size*grid_size, embed_dim] (with cls_token).

Return type:

ndarray

sdofmv2.utils.utils.get_2d_sincos_pos_embed_from_grid(embed_dim, grid)[source]

Generate 2D sine-cosine positional embeddings from a grid.

Parameters:

  • embed_dim (int) – The embedding dimension (must be even).

  • grid (ndarray) – A 2xHxW array containing the 2D grid coordinates.

Returns:

The positional embeddings of shape (H*W, embed_dim).

Return type:

ndarray

sdofmv2.utils.utils.get_3d_sincos_pos_embed(embed_dim, grid_size, cls_token=False)[source]

Generate 3D sine-cosine positional embeddings.

Parameters:

  • embed_dim (int) – The embedding dimension (must be divisible by 16).

  • grid_size (tuple) – A 3-tuple of (t, h, w) representing the grid dimensions.

  • cls_token (bool, optional) – If True, prepends a zero vector for CLS token. Defaults to False.

Returns:

Positional embeddings of shape (L, embed_dim) where

L = t * h * w (or L = 1 + t * h * w with cls_token).

Return type:

ndarray

sdofmv2.utils.utils.hmi_mask(hmi_data)[source]

Generate a binary mask for HMI solar disk data.

Creates a binary mask where 1 indicates pixels within the solar disk (non-zero magnetic field values) and 0 indicates pixels outside.

Parameters:

hmi_data (torch.Tensor) – The HMI magnetogram data tensor.

Returns:

A binary mask tensor of the same shape as input.

Return type:

torch.Tensor

sdofmv2.utils.utils.norm_target(target) → torch.Tensor[source]

Normalize target values using z-score normalization.

Applies z-score normalization to the target tensor along the last dimension, computing mean and variance per sample in the batch.

Parameters:

target (torch.Tensor) – The input tensor to normalize.

Returns:

The normalized tensor with the same shape as input.

Return type:

torch.Tensor

sdofmv2.utils.utils.patchify(imgs, patch_size, tubelet_size)[source]

Convert image tensors into sequences of patches.

Takes a 5D image tensor and reorganizes it into a sequence of flattened patches suitable for Vision Transformer (ViT) processing.

Parameters:

  • imgs (torch.Tensor) – Input images of shape (B, C, T, H, W).

  • patch_size (int) – The spatial size of each square patch.

  • tubelet_size (int) – The temporal size of each tubelet.

Returns:

Patched tensor of shape (B, L, D) where L is the

number of patches and D is the flattened patch dimension.

Return type:

torch.Tensor

sdofmv2.utils.utils.spatial_to_patch_mask(mask_2d: torch.Tensor, patch_size: int, num_frames: int = 1) → torch.Tensor[source]

Convert 2D spatial mask to patch-level mask.

Parameters:

  • mask_2d – 2D binary mask of shape (H, W).

  • patch_size – Spatial size of each patch.

  • num_frames – Number of frames (temporal). Default: 1.

Returns:

1D boolean tensor of shape (L,) where True = off-limb patch.

Return type:

torch.Tensor

sdofmv2.utils.utils.stonyhurst_to_patch_index(lat, lon, patch_size, img_w=512, img_h=512)[source]

Convert Heliographic Stonyhurst coordinates to patch indices.

Transforms latitude and longitude coordinates in the Heliographic Stonyhurst frame to corresponding patch indices in an image grid.

Parameters:

  • lat (float) – Latitude in degrees.

  • lon (float) – Longitude in degrees.

  • patch_size (int) – The size of each patch in pixels.

  • img_w (int, optional) – Image width in pixels. Defaults to 512.

  • img_h (int, optional) – Image height in pixels. Defaults to 512.

Returns:

A tensor of shape (2,) containing the patch indices [x, y].

Return type:

torch.Tensor

Warns:

UserWarning – If image dimensions exceed 1024, indicating potential precision loss in coordinate conversion.

sdofmv2.utils.utils.unflatten_dict(dictionary, sep='_', wandb_mode=True)[source]

Unflatten a dictionary back into a nested dictionary structure.

Parameters:

  • dictionary (dict) – The flattened dictionary to unflatten.

  • sep (str, optional) – The separator used to join keys. Defaults to “_”.

  • wandb_mode (bool, optional) – If True, extracts values from ‘value’ keys in nested dicts. Defaults to True.

Returns:

A nested dictionary with keys split by the separator.

Return type:

AttributeDict

sdofmv2.utils.utils.unpatchify(x, img_size, patch_size, tubelet_size)[source]

Reconstruct image tensors from sequences of patches.

Takes a sequence of flattened patches and reorganizes them back into a 5D image tensor.

Parameters:

  • x (torch.Tensor) – Patched tensor of shape (B, L, D).

  • img_size (int) – The spatial size of the original images (assumed square).

  • patch_size (int) – The spatial size of each patch.

  • tubelet_size (int) – The temporal size of each tubelet.

Returns:

Reconstructed images of shape (B, C, T, H, W).

Return type:

torch.Tensor