VeraGridEngine.Devices.Profiles package

Submodules

VeraGridEngine.Devices.Profiles.profile_bool module

class VeraGridEngine.Devices.Profiles.profile_bool.ProfileBool(default_value: bool, arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for bool values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileBool

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: bool) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: bool, map_data: dict[int, bool] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: bool

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[bool]

Get the declared type.

Returns:

bool.

fill(value: bool) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the boolean profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, bool]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[bool]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Reject scaling because boolean profiles are not numeric.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense boolean array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[bool]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayBool | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense boolean array.

tolist() → list[bool]

Get the dense list representation.

Returns:

Dense list.

VeraGridEngine.Devices.Profiles.profile_device module

class VeraGridEngine.Devices.Profiles.profile_device.ProfileDevice(default_value: EditableDevice | str | None, device_type: DeviceType, arr: np.ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for editable-device references.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileDevice

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: EditableDevice | str | None) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: EditableDevice | str | None, map_data: dict[int, 'EditableDevice | str | None'] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: EditableDevice | str | None

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: DeviceType

Get the declared selector type.

Returns:

Device selector.

fill(value: EditableDevice | str | None) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the device profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, 'EditableDevice | str | None']

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list['EditableDevice | str | None']]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

rebind_device_references(objects_by_idtag: dict[str, 'EditableDevice']) → None

Rebind stored device references to equivalent objects from a target lookup.

Parameters:

objects_by_idtag – idtag -> target object lookup.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Reject scaling because device profiles are not numeric.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense device-reference array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list['EditableDevice | str | None']) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayDevice | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense object array.

tolist() → list['EditableDevice | str | None']

Get the dense list representation.

Returns:

Dense list.

VeraGridEngine.Devices.Profiles.profile_enum module

class VeraGridEngine.Devices.Profiles.profile_enum.ProfileEnum(default_value: Enum | None, enum_type: type[Enum], arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for enum values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileEnum

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: Enum | None) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: Enum | None, map_data: dict[int, Enum | None] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: Enum | None

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[Enum]

Get the declared enum type.

Returns:

Enum class.

fill(value: Enum | None) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the enum profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, Enum | None]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[Enum | None]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Reject scaling because enum profiles are not numeric.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense enum array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[Enum | None]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayEnum | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense object array.

tolist() → list[Enum | None]

Get the dense list representation.

Returns:

Dense list.

VeraGridEngine.Devices.Profiles.profile_float module

class VeraGridEngine.Devices.Profiles.profile_float.ProfileFloat(default_value: float, arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for float values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileFloat

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: float) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: float, map_data: dict[int, float] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: float

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[float]

Get the declared type.

Returns:

float.

fill(value: float) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Replace NaN values in place.

Parameters:

default_value – Replacement value.

Returns:

None.

get_sparse_map() → dict[int, float]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[float]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Scale the profile by a scalar.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense float array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[float]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayFloat | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense float array.

tolist() → list[float]

Get the dense list representation.

Returns:

Dense list.

VeraGridEngine.Devices.Profiles.profile_int module

class VeraGridEngine.Devices.Profiles.profile_int.ProfileInt(default_value: int, arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for int values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileInt

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: int) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: int, map_data: dict[int, int] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: int

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[int]

Get the declared type.

Returns:

int.

fill(value: int) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the integer profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, int]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[int]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Scale the profile by a scalar.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense integer array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[int]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayInt | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense integer array.

tolist() → list[int]

Get the dense list representation.

Returns:

Dense list.

VeraGridEngine.Devices.Profiles.sparse_array_bool module

class VeraGridEngine.Devices.Profiles.sparse_array_bool.SparseArrayBool(default_value: bool, size: int = 0)

Bases: object

Sparse array specialized for bool values.

at(idx: int) → bool

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayBool

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: bool, data: dict[int, bool] | None = None) → SparseArrayBool

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: bool) → SparseArrayBool

Create the sparse array from a dense array.

Parameters:

• array – Dense boolean array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: bool, size: int, map_data: dict[int, bool]) → SparseArrayBool

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: bool

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[bool]

Get the declared type.

Returns:

bool.

fill(value: bool) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, bool]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[bool]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: bool) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, bool]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[bool]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayBool

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense boolean array.

VeraGridEngine.Devices.Profiles.sparse_array_device module

class VeraGridEngine.Devices.Profiles.sparse_array_device.SparseArrayDevice(default_value: EditableDevice | str | None, device_type: DeviceType, size: int = 0)

Bases: object

Sparse array specialized for editable-device references.

at(idx: int) → EditableDevice | str | None

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayDevice

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: EditableDevice | str | None, data: dict[int, 'EditableDevice | str | None'] | None = None) → SparseArrayDevice

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: np.ndarray, default_value: EditableDevice | str | None) → SparseArrayDevice

Create the sparse array from a dense array.

Parameters:

• array – Dense object array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: EditableDevice | str | None, size: int, map_data: dict[int, 'EditableDevice | str | None']) → SparseArrayDevice

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: EditableDevice | str | None

Get the default sparse value.

Returns:

Default sparse value.

property dtype: DeviceType

Get the declared selector type.

Returns:

Device selector.

fill(value: EditableDevice | str | None) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, 'EditableDevice | str | None']

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list['EditableDevice | str | None']]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: EditableDevice | str | None) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

rebind_device_references(objects_by_idtag: dict[str, 'EditableDevice']) → None

Rebind stored device references to equivalent objects from a target lookup.

Parameters:

objects_by_idtag – idtag -> target object lookup.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, 'EditableDevice | str | None']) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list['EditableDevice | str | None']) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayDevice

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense object array.

VeraGridEngine.Devices.Profiles.sparse_array_enum module

class VeraGridEngine.Devices.Profiles.sparse_array_enum.SparseArrayEnum(default_value: Enum | None, enum_type: type[Enum], size: int = 0)

Bases: object

Sparse array specialized for enum values.

at(idx: int) → Enum | None

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayEnum

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: Enum | None, data: dict[int, Enum | None] | None = None) → SparseArrayEnum

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: Enum | None) → SparseArrayEnum

Create the sparse array from a dense array.

Parameters:

• array – Dense object array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: Enum | None, size: int, map_data: dict[int, Enum | None]) → SparseArrayEnum

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: Enum | None

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[Enum]

Get the declared enum type.

Returns:

Enum class.

fill(value: Enum | None) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, Enum | None]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[Enum | None]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: Enum | None) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, Enum | None]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[Enum | None]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayEnum

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense object array.

VeraGridEngine.Devices.Profiles.sparse_array_float module

class VeraGridEngine.Devices.Profiles.sparse_array_float.SparseArrayFloat(default_value: float, size: int = 0)

Bases: object

Sparse array specialized for float values.

at(idx: int) → float

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayFloat

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: float, data: dict[int, float] | None = None) → SparseArrayFloat

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: float) → SparseArrayFloat

Create the sparse array from a dense array.

Parameters:

• array – Dense float array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: float, size: int, map_data: dict[int, float]) → SparseArrayFloat

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: float

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[float]

Get the declared type.

Returns:

float.

fill(value: float) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, float]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[float]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: float) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, float]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[float]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayFloat

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense float array.

VeraGridEngine.Devices.Profiles.sparse_array_int module

class VeraGridEngine.Devices.Profiles.sparse_array_int.SparseArrayInt(default_value: int, size: int = 0)

Bases: object

Sparse array specialized for int values.

at(idx: int) → int

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayInt

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: int, data: dict[int, int] | None = None) → SparseArrayInt

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: int) → SparseArrayInt

Create the sparse array from a dense array.

Parameters:

• array – Dense integer array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: int, size: int, map_data: dict[int, int]) → SparseArrayInt

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: int

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[int]

Get the declared type.

Returns:

int.

fill(value: int) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, int]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[int]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: int) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, int]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[int]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayInt

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense integer array.

VeraGridEngine.Devices.Profiles.type_checks module

VeraGridEngine.Devices.Profiles.type_checks.check_if_sparse(arr: ndarray, sparsity: float = 0.8) → tuple[bool, Any]

Check whether an array should be stored as sparse.

Parameters:

• arr – Array to inspect.

• sparsity – Minimum repetition ratio required for sparse storage.

Returns:

Tuple (is_sparse, most_frequent_value).

VeraGridEngine.Devices.Profiles.type_checks.check_type(dtype: type[bool] | type[int] | type[float] | type[Enum] | DeviceType, value: Any) → bool

Check that a value is compatible with a declared profile type.

Parameters:

• dtype – Declared profile type.

• value – Value to validate.

Returns:

True when value matches dtype.

VeraGridEngine.Devices.Profiles.type_checks.coerce_bool_value(value: Any) → bool

Convert an incoming value into a boolean.

Parameters:

value – Value to coerce.

Returns:

Boolean representation of value.

VeraGridEngine.Devices.Profiles.type_checks.is_enum_data_type(data_type: Any) → bool

Check whether the declared profile type is an enum class.

Parameters:

data_type – Declared profile type.

Returns:

True when the type is an enum class, False otherwise.

Module contents

class VeraGridEngine.Devices.Profiles.ProfileBool(default_value: bool, arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for bool values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileBool

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: bool) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: bool, map_data: dict[int, bool] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: bool

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[bool]

Get the declared type.

Returns:

bool.

fill(value: bool) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the boolean profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, bool]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[bool]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Reject scaling because boolean profiles are not numeric.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense boolean array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[bool]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayBool | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense boolean array.

tolist() → list[bool]

Get the dense list representation.

Returns:

Dense list.

class VeraGridEngine.Devices.Profiles.ProfileDevice(default_value: EditableDevice | str | None, device_type: DeviceType, arr: np.ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for editable-device references.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileDevice

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: EditableDevice | str | None) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: EditableDevice | str | None, map_data: dict[int, 'EditableDevice | str | None'] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: EditableDevice | str | None

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: DeviceType

Get the declared selector type.

Returns:

Device selector.

fill(value: EditableDevice | str | None) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the device profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, 'EditableDevice | str | None']

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list['EditableDevice | str | None']]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

rebind_device_references(objects_by_idtag: dict[str, 'EditableDevice']) → None

Rebind stored device references to equivalent objects from a target lookup.

Parameters:

objects_by_idtag – idtag -> target object lookup.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Reject scaling because device profiles are not numeric.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense device-reference array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list['EditableDevice | str | None']) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayDevice | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense object array.

tolist() → list['EditableDevice | str | None']

Get the dense list representation.

Returns:

Dense list.

class VeraGridEngine.Devices.Profiles.ProfileEnum(default_value: Enum | None, enum_type: type[Enum], arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for enum values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileEnum

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: Enum | None) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: Enum | None, map_data: dict[int, Enum | None] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: Enum | None

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[Enum]

Get the declared enum type.

Returns:

Enum class.

fill(value: Enum | None) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the enum profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, Enum | None]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[Enum | None]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Reject scaling because enum profiles are not numeric.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense enum array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[Enum | None]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayEnum | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense object array.

tolist() → list[Enum | None]

Get the dense list representation.

Returns:

Dense list.

class VeraGridEngine.Devices.Profiles.ProfileFloat(default_value: float, arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for float values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileFloat

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: float) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: float, map_data: dict[int, float] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: float

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[float]

Get the declared type.

Returns:

float.

fill(value: float) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Replace NaN values in place.

Parameters:

default_value – Replacement value.

Returns:

None.

get_sparse_map() → dict[int, float]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[float]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Scale the profile by a scalar.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense float array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[float]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayFloat | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense float array.

tolist() → list[float]

Get the dense list representation.

Returns:

Dense list.

class VeraGridEngine.Devices.Profiles.ProfileInt(default_value: int, arr: ndarray | None = None, sparsity_threshold: float = 0.8, is_sparse: bool = False)

Bases: object

Profile specialized for int values.

astype(tpe: Any) → ndarray

Cast the dense representation to another dtype.

Parameters:

tpe – Target dtype.

Returns:

Cast dense array.

clear() → None

Clear the profile contents.

Returns:

None.

convert_sparse_to_dense() → None

Convert the sparse profile into dense storage.

Returns:

None.

copy() → ProfileInt

Build a deep copy of the profile.

Returns:

New profile copy.

create_dense(size: int, default_value: int) → None

Create the profile in dense form.

Parameters:

• size – Logical size.

• default_value – Dense fill value.

Returns:

None.

create_sparse(size: int, default_value: int, map_data: dict[int, int] | None = None) → None

Create the profile in sparse form.

Parameters:

• size – Logical size.

• default_value – Sparse default value.

• map_data – Optional sparse map.

Returns:

None.

property default_value: int

Get the profile default value.

Returns:

Default value.

property dense_array: ndarray | None

Get the dense backing array.

Returns:

Dense array or None.

property dtype: type[int]

Get the declared type.

Returns:

int.

fill(value: int) → None

Fill the profile with a single value.

Parameters:

value – Fill value.

Returns:

None.

fix_nan(default_value: float = 0.0) → None

Keep the integer profile API aligned with the generic profile.

Parameters:

default_value – Unused placeholder.

Returns:

None.

get_sparse_map() → dict[int, int]

Get the sparse map when the profile is sparse.

Returns:

Sparse map or an empty dictionary.

get_sparse_representation() → tuple[list[int], list[int]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

property is_initialized: bool

Get whether the profile has been initialized.

Returns:

Initialization state.

property is_sparse: bool

Get whether the profile uses sparse storage.

Returns:

Sparse state.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the profile in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the profile.

Parameters:

n – New logical size.

Returns:

None.

scale(value: float | int) → None

Scale the profile by a scalar.

Parameters:

value – Scalar multiplier.

Returns:

None.

set(arr: ndarray) → bool

Set the profile from a dense array.

Parameters:

arr – Dense integer array.

Returns:

True when the assignment succeeds.

set_initialized() → None

Mark the profile as initialized.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[int]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the profile size.

Returns:

Logical size.

property sparse_array: SparseArrayInt | None

Get the sparse backing array.

Returns:

Sparse array or None.

property sparsity: float

Get the sparse stored-entry ratio.

Returns:

Sparsity ratio.

toarray() → ndarray

Get the dense numpy representation.

Returns:

Dense integer array.

tolist() → list[int]

Get the dense list representation.

Returns:

Dense list.

class VeraGridEngine.Devices.Profiles.SparseArrayBool(default_value: bool, size: int = 0)

Bases: object

Sparse array specialized for bool values.

at(idx: int) → bool

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayBool

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: bool, data: dict[int, bool] | None = None) → SparseArrayBool

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: bool) → SparseArrayBool

Create the sparse array from a dense array.

Parameters:

• array – Dense boolean array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: bool, size: int, map_data: dict[int, bool]) → SparseArrayBool

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: bool

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[bool]

Get the declared type.

Returns:

bool.

fill(value: bool) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, bool]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[bool]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: bool) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, bool]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[bool]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayBool

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense boolean array.

class VeraGridEngine.Devices.Profiles.SparseArrayDevice(default_value: EditableDevice | str | None, device_type: DeviceType, size: int = 0)

Bases: object

Sparse array specialized for editable-device references.

at(idx: int) → EditableDevice | str | None

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayDevice

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: EditableDevice | str | None, data: dict[int, 'EditableDevice | str | None'] | None = None) → SparseArrayDevice

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: np.ndarray, default_value: EditableDevice | str | None) → SparseArrayDevice

Create the sparse array from a dense array.

Parameters:

• array – Dense object array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: EditableDevice | str | None, size: int, map_data: dict[int, 'EditableDevice | str | None']) → SparseArrayDevice

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: EditableDevice | str | None

Get the default sparse value.

Returns:

Default sparse value.

property dtype: DeviceType

Get the declared selector type.

Returns:

Device selector.

fill(value: EditableDevice | str | None) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, 'EditableDevice | str | None']

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list['EditableDevice | str | None']]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: EditableDevice | str | None) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

rebind_device_references(objects_by_idtag: dict[str, 'EditableDevice']) → None

Rebind stored device references to equivalent objects from a target lookup.

Parameters:

objects_by_idtag – idtag -> target object lookup.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, 'EditableDevice | str | None']) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list['EditableDevice | str | None']) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayDevice

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense object array.

class VeraGridEngine.Devices.Profiles.SparseArrayEnum(default_value: Enum | None, enum_type: type[Enum], size: int = 0)

Bases: object

Sparse array specialized for enum values.

at(idx: int) → Enum | None

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayEnum

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: Enum | None, data: dict[int, Enum | None] | None = None) → SparseArrayEnum

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: Enum | None) → SparseArrayEnum

Create the sparse array from a dense array.

Parameters:

• array – Dense object array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: Enum | None, size: int, map_data: dict[int, Enum | None]) → SparseArrayEnum

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: Enum | None

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[Enum]

Get the declared enum type.

Returns:

Enum class.

fill(value: Enum | None) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, Enum | None]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[Enum | None]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: Enum | None) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, Enum | None]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[Enum | None]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayEnum

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense object array.

class VeraGridEngine.Devices.Profiles.SparseArrayFloat(default_value: float, size: int = 0)

Bases: object

Sparse array specialized for float values.

at(idx: int) → float

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayFloat

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: float, data: dict[int, float] | None = None) → SparseArrayFloat

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: float) → SparseArrayFloat

Create the sparse array from a dense array.

Parameters:

• array – Dense float array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: float, size: int, map_data: dict[int, float]) → SparseArrayFloat

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: float

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[float]

Get the declared type.

Returns:

float.

fill(value: float) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, float]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[float]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: float) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, float]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[float]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayFloat

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense float array.

class VeraGridEngine.Devices.Profiles.SparseArrayInt(default_value: int, size: int = 0)

Bases: object

Sparse array specialized for int values.

at(idx: int) → int

Get a value at a given position.

Parameters:

idx – Position to read.

Returns:

Value at idx.

clear() → None

Clear the sparse contents.

Returns:

None.

copy() → SparseArrayInt

Build a deep copy of the sparse array.

Returns:

New sparse array copy.

create(size: int, default_value: int, data: dict[int, int] | None = None) → SparseArrayInt

Create the sparse array from explicit sparse data.

Parameters:

• size – Logical size.

• default_value – Default sparse value.

• data – Sparse map.

Returns:

self.

create_from_array(array: ndarray, default_value: int) → SparseArrayInt

Create the sparse array from a dense array.

Parameters:

• array – Dense integer array.

• default_value – Default sparse value.

Returns:

self.

create_from_dict(default_value: int, size: int, map_data: dict[int, int]) → SparseArrayInt

Create the sparse array from a sparse map.

Parameters:

• default_value – Default sparse value.

• size – Logical size.

• map_data – Sparse map.

Returns:

self.

property default_value: int

Get the default sparse value.

Returns:

Default sparse value.

property dtype: type[int]

Get the declared type.

Returns:

int.

fill(value: int) → None

Fill the logical array with the same value.

Parameters:

value – Fill value.

Returns:

None.

get_map() → dict[int, int]

Get the sparse map.

Returns:

Sparse index-value map.

get_sparse_representation() → tuple[list[int], list[int]]

Export the sparse contents as parallel index and value lists.

Returns:

Tuple (indices, values).

get_sparsity() → float

Get the stored-entry ratio.

Returns:

Sparsity ratio.

info() → dict[str, Any]

Get diagnostic information.

Returns:

Information dictionary.

insert(i: int, x: int) → None

Insert a sparse value explicitly.

Parameters:

• i – Target index.

• x – Value to store.

Returns:

None.

resample(indices: ndarray[tuple[Any, ...], dtype[int64]]) → None

Resample the sparse array in place.

Parameters:

indices – New index selection.

Returns:

None.

resize(n: int) → None

Resize the sparse array.

Parameters:

n – New logical size.

Returns:

None.

set_data(d: dict[int, int]) → None

Replace the sparse map.

Parameters:

d – New sparse map.

Returns:

None.

set_sparse_data_from_data(indptr: list[int], data: list[int]) → None

Load sparse data from parallel lists.

Parameters:

• indptr – Sparse indices.

• data – Sparse values.

Returns:

None.

size() → int

Get the logical size.

Returns:

Logical size.

slice(indices: ndarray[tuple[Any, ...], dtype[int64]]) → SparseArrayInt

Get a resampled copy.

Parameters:

indices – New index selection.

Returns:

Resampled sparse array.

toarray() → ndarray

Expand the sparse array into a dense numpy array.

Returns:

Dense integer array.

VeraGridEngine.Devices.Profiles.check_if_sparse(arr: ndarray, sparsity: float = 0.8) → tuple[bool, Any]

Check whether an array should be stored as sparse.

Parameters:

• arr – Array to inspect.

• sparsity – Minimum repetition ratio required for sparse storage.

Returns:

Tuple (is_sparse, most_frequent_value).

VeraGridEngine.Devices.Profiles.check_type(dtype: type[bool] | type[int] | type[float] | type[Enum] | DeviceType, value: Any) → bool

Check that a value is compatible with a declared profile type.

Parameters:

• dtype – Declared profile type.

• value – Value to validate.

Returns:

True when value matches dtype.