nvalchemi.data.LevelSchema#

class nvalchemi.data.LevelSchema(group_to_attrs=None, segmented_groups=None, dtypes=None)[source]#

Registry mapping attributes to levels, dtypes, and level kinds.

Parameters:
  • group_to_attrs (dict[str, set[str]] | None, optional) – Mapping from group names to sets of attribute names. Defaults to None (uses DEFAULT_ATTRIBUTE_MAP).

  • segmented_groups (set[str] | None, optional) – Group names whose data has variable segment lengths. Defaults to None (uses DEFAULT_SEGMENTED_GROUPS).

  • dtypes (dict[str, str] | None, optional) – Per-attribute dtype strings (keys of TORCH_DTYPE_MAP). Defaults to None (uses DEFAULT_DTYPES).

Raises:

ValueError – If dtypes is provided but its keys don’t match the attribute set.

add_level(name, *, segmented)[source]#

Register an ordinary uniform or segmented level.

Repeating the same definition is an idempotent operation.

Parameters:
  • name (str) – Name of the level.

  • segmented (bool) – Whether the level has variable per-system cardinality.

Raises:
  • TypeError – If name is not a string or segmented is not a Boolean.

  • ValueError – If name is empty or already has a different kind.

Return type:

None

add_product_level(name, *, left, right)[source]#

Register a segmented Cartesian product of two base levels.

Product levels preserve parent order and may use the same segmented parent on both axes. Repeating an identical definition is idempotent.

Parameters:
  • name (str) – Name of the product level.

  • left (str) – Registered segmented level for the left entity axis.

  • right (str) – Registered segmented level for the right entity axis.

Raises:
  • TypeError – If any level name is not a string.

  • KeyError – If either parent is not registered.

  • ValueError – If a name is empty, a parent is not a segmented base level, or the requested definition conflicts with an existing level.

Return type:

None

clone()[source]#

Return an independent deep copy.

Return type:

LevelSchema

dtype(attr_name)[source]#

Return the dtype string for attr_name.

Raises:

KeyError – If attr_name has no registered dtype.

Parameters:

attr_name (str)

Return type:

str

group(attr_name)[source]#

Return the group name for attr_name.

Raises:

KeyError – If attr_name is not registered.

Parameters:

attr_name (str)

Return type:

str

is_segmented_attr(attr_name)[source]#

Return whether attr_name belongs to a segmented group.

Raises:

KeyError – If attr_name is not registered.

Parameters:

attr_name (str)

Return type:

bool

is_segmented_group(group_name)[source]#

Return whether group_name is segmented.

Parameters:

group_name (str)

Return type:

bool

level_kind(name)[source]#

Return the kind of a registered level.

Parameters:

name (str) – Name of the level.

Returns:

"uniform", "segmented", or "product".

Return type:

LevelKind

Raises:

KeyError – If name is not a registered level.

property level_names: tuple[str, ...]#

Return registered level names in deterministic definition order.

mark_group_segmented(group_name)[source]#

Mark group_name as segmented.

Parameters:

group_name (str)

Return type:

None

set(attr_name, group_name, dtype=None, is_segmented=None)[source]#

Register or update an attribute’s group, dtype, and segmentation.

Parameters:
  • attr_name (str) – Name of the attribute.

  • group_name (str) – Target group for the attribute.

  • dtype (str or torch.dtype, optional) – Data type for the attribute.

  • is_segmented (bool, optional) – Whether group_name should be marked as segmented.

Raises:

ValueError – If the requested segmentation would invalidate a product level or dtype is an unsupported torch.dtype value.

Return type:

None

unmark_group_segmented(group_name)[source]#

Remove the segmented flag from group_name.

Raises:
  • KeyError – If group_name is not currently segmented.

  • ValueError – If group_name is a product or a parent of a product.

Parameters:

group_name (str)

Return type:

None