0
# NumPy Utilities (enp)
1

2
Enhanced NumPy utilities providing array specifications, compatibility layers, mathematical operations, and geometry utilities for scientific computing and machine learning workflows.
3

4
## Capabilities
5

6
### Array Specifications
7

8
Define and work with array shape and dtype specifications.
9

10
```python { .api }
11
class ArraySpec:
12
    """
13
    Specification for array shape and data type.
14
    """
15
    def __init__(self, shape: tuple[int, ...], dtype: np.dtype) -> None: ...
16
    
17
    @property
18
    def shape(self) -> tuple[int, ...]: ...
19
    @property
20
    def dtype(self) -> np.dtype: ...
21
```
22

23
### NumPy Module Wrapper
24

25
Enhanced NumPy module with additional utilities.
26

27
```python { .api }
28
class NpModule:
29
    """
30
    NumPy module wrapper with enhanced functionality.
31
    """
32
    def __init__(self, module: ModuleType) -> None: ...
33
```
34

35
### Array Validation and Processing
36

37
Functions for checking and normalizing arrays.
38

39
```python { .api }
40
def check_and_normalize_arrays(
41
    fn: Callable | None = None,
42
    *,
43
    strict: bool = True
44
) -> Callable:
45
    """
46
    Decorator for functions that validates and normalizes array inputs.
47
    
48
    Args:
49
        fn: Function to decorate (when used without parentheses)
50
        strict: Whether to apply strict validation rules
51
        
52
    Returns:
53
        Decorated function that validates array inputs
54
        
55
    Example:
56
        @check_and_normalize_arrays
57
        def process_arrays(arr1, arr2):
58
            return arr1 + arr2
59
    """
60

61
def is_array_str(arr: np.ndarray) -> bool:
62
    """
63
    Check if array contains string data.
64
    
65
    Args:
66
        arr: Input array
67
        
68
    Returns:
69
        True if array contains strings, False otherwise
70
    """
71

72
def is_dtype_str(dtype: np.dtype) -> bool:
73
    """
74
    Check if dtype represents string data.
75
    
76
    Args:
77
        dtype: NumPy data type
78
        
79
    Returns:
80
        True if dtype is string type, False otherwise
81
    """
82

83
def normalize_bytes2str(arr: np.ndarray) -> np.ndarray:
84
    """
85
    Convert bytes arrays to string arrays.
86
    
87
    Args:
88
        arr: Array containing bytes
89
        
90
    Returns:
91
        Array with bytes converted to strings
92
    """
93
```
94

95
### Shape Manipulation (Einops Integration)
96

97
Advanced array reshaping using einops patterns.
98

99
```python { .api }
100
def flatten(arr: np.ndarray, pattern: str) -> np.ndarray:
101
    """
102
    Flatten array using einops pattern.
103
    
104
    Args:
105
        arr: Input array
106
        pattern: Einops pattern string (e.g., 'h w c -> (h w) c')
107
        
108
    Returns:
109
        Flattened array according to pattern
110
    """
111

112
def unflatten(arr: np.ndarray, pattern: str, **axes_lengths) -> np.ndarray:
113
    """
114
    Unflatten array using einops pattern.
115
    
116
    Args:
117
        arr: Input flattened array
118
        pattern: Einops pattern string (e.g., '(h w) c -> h w c')
119
        **axes_lengths: Lengths for axes (e.g., h=28, w=28)
120
        
121
    Returns:
122
        Unflattened array according to pattern
123
    """
124
```
125

126
### Mathematical Operations
127

128
Enhanced mathematical functions and interpolation.
129

130
```python { .api }
131
def interp(
132
    x: np.ndarray,
133
    xp: np.ndarray,
134
    fp: np.ndarray,
135
    **kwargs
136
) -> np.ndarray:
137
    """
138
    Enhanced interpolation function.
139
    
140
    Args:
141
        x: X-coordinates at which to evaluate interpolated values
142
        xp: X-coordinates of data points
143
        fp: Y-coordinates of data points
144
        **kwargs: Additional interpolation options
145
        
146
    Returns:
147
        Interpolated values
148
    """
149
```
150

151
### Geometry Utilities
152

153
Vector and geometric operations for 3D mathematics.
154

155
```python { .api }
156
def angle_between(v1: np.ndarray, v2: np.ndarray) -> float:
157
    """
158
    Calculate angle between two vectors.
159
    
160
    Args:
161
        v1: First vector
162
        v2: Second vector
163
        
164
    Returns:
165
        Angle between vectors in radians
166
    """
167

168
def batch_dot(a: np.ndarray, b: np.ndarray) -> np.ndarray:
169
    """
170
    Batch dot product of arrays.
171
    
172
    Args:
173
        a: First array batch
174
        b: Second array batch
175
        
176
    Returns:
177
        Array of dot products
178
    """
179

180
def project_onto_plane(
181
    vector: np.ndarray,
182
    plane_normal: np.ndarray
183
) -> np.ndarray:
184
    """
185
    Project vector onto a plane defined by its normal.
186
    
187
    Args:
188
        vector: Vector to project
189
        plane_normal: Normal vector of the plane
190
        
191
    Returns:
192
        Projected vector on the plane
193
    """
194

195
def project_onto_vector(
196
    vector: np.ndarray,
197
    target_vector: np.ndarray
198
) -> np.ndarray:
199
    """
200
    Project vector onto another vector.
201
    
202
    Args:
203
        vector: Vector to project
204
        target_vector: Target vector for projection
205
        
206
    Returns:
207
        Projected vector
208
    """
209
```
210

211
### Constants and Utilities
212

213
Mathematical constants and lazy utilities.
214

215
```python { .api }
216
tau: float  # Mathematical constant τ (2π)
217

218
dtypes: ModuleType  # Data type definitions module
219

220
def lazy() -> Any:
221
    """
222
    Lazy NumPy utilities for deferred loading.
223
    
224
    Returns:
225
        Lazy-loaded NumPy utilities
226
    """
227
```
228

229
### Utility Modules
230

231
Additional modules for specific functionality.
232

233
```python { .api }
234
typing: ModuleType  # NumPy typing utilities
235
compat: ModuleType  # Compatibility utilities
236
linalg: ModuleType  # Linear algebra utilities
237
testing: ModuleType  # Testing utilities (when pytest available)
238
```
239

240
### Deprecated Functions
241

242
Legacy functions maintained for compatibility.
243

244
```python { .api }
245
def get_np_module() -> ModuleType:
246
    """
247
    Get NumPy module (DEPRECATED).
248
    
249
    Returns:
250
        NumPy module
251
        
252
    Note:
253
        This function is deprecated. Use numpy directly.
254
    """
255

256
def is_array(obj: Any) -> bool:
257
    """
258
    Check if object is array (DEPRECATED).
259
    
260
    Args:
261
        obj: Object to check
262
        
263
    Returns:
264
        True if object is array-like
265
        
266
    Note:
267
        This function is deprecated. Use isinstance checks.
268
    """
269
```
270

271
## Usage Examples
272

273
### Array Specifications
274

275
```python
276
from etils import enp
277
import numpy as np
278

279
# Create array specifications
280
spec = enp.ArraySpec(shape=(224, 224, 3), dtype=np.float32)
281
print(f"Shape: {spec.shape}, Dtype: {spec.dtype}")
282

283
# Use in function signatures
284
def process_image(image: np.ndarray) -> np.ndarray:
285
    assert image.shape == spec.shape
286
    assert image.dtype == spec.dtype
287
    return image * 2.0
288
```
289

290
### Array Validation
291

292
```python
293
from etils import enp
294
import numpy as np
295

296
# Validate and normalize multiple arrays
297
arrays = [
298
    [1, 2, 3],                    # List
299
    np.array([4, 5, 6]),         # NumPy array
300
    (7, 8, 9)                    # Tuple
301
]
302

303
normalized = enp.check_and_normalize_arrays(*arrays)
304
# Result: List of numpy arrays
305

306
# Check array properties
307
str_array = np.array(['hello', 'world'])
308
is_string = enp.is_array_str(str_array)  # True
309

310
dtype_is_string = enp.is_dtype_str(str_array.dtype)  # True
311
```
312

313
### Shape Manipulation
314

315
```python
316
from etils import enp
317
import numpy as np
318

319
# Create sample image data
320
image = np.random.rand(28, 28, 3)  # Height x Width x Channels
321

322
# Flatten for neural network input
323
flattened = enp.flatten(image, 'h w c -> (h w c)')
324
# Result: Shape (2352,) = 28 * 28 * 3
325

326
# Unflatten back to original shape
327
restored = enp.unflatten(flattened, '(h w c) -> h w c', h=28, w=28, c=3)
328
# Result: Original (28, 28, 3) shape
329

330
# Batch operations
331
batch_images = np.random.rand(32, 28, 28, 3)  # Batch x H x W x C
332
batch_flat = enp.flatten(batch_images, 'b h w c -> b (h w c)')
333
# Result: Shape (32, 2352)
334
```
335

336
### Mathematical Operations
337

338
```python
339
from etils import enp
340
import numpy as np
341

342
# Interpolation
343
x = np.linspace(0, 10, 11)
344
y = np.sin(x)
345
x_new = np.linspace(0, 10, 101)
346
y_interp = enp.interp(x_new, x, y)
347

348
# Use mathematical constants
349
circumference = 2 * np.pi * radius  # Standard approach
350
circumference = enp.tau * radius    # Using tau constant
351
```
352

353
### Geometry Operations
354

355
```python
356
from etils import enp
357
import numpy as np
358

359
# Vector operations
360
v1 = np.array([1, 0, 0])
361
v2 = np.array([0, 1, 0])
362

363
# Calculate angle between vectors
364
angle = enp.angle_between(v1, v2)  # π/2 radians (90 degrees)
365

366
# Batch dot products
367
batch_a = np.random.rand(100, 3)
368
batch_b = np.random.rand(100, 3)
369
dot_products = enp.batch_dot(batch_a, batch_b)  # Shape: (100,)
370

371
# Projections
372
vector = np.array([1, 1, 1])
373
plane_normal = np.array([0, 0, 1])  # XY plane
374
projected = enp.project_onto_plane(vector, plane_normal)
375
# Result: [1, 1, 0] (projected onto XY plane)
376

377
target = np.array([1, 0, 0])  # X-axis
378
vector_proj = enp.project_onto_vector(vector, target)
379
# Result: [1, 0, 0] (component along X-axis)
380
```
381

382
### String and Bytes Handling
383

384
```python
385
from etils import enp
386
import numpy as np
387

388
# Convert bytes to strings
389
byte_array = np.array([b'hello', b'world'])
390
string_array = enp.normalize_bytes2str(byte_array)
391
# Result: array(['hello', 'world'], dtype='<U5')
392

393
# Check for string content
394
mixed_array = np.array(['text', 123])  # Mixed types
395
has_strings = enp.is_array_str(mixed_array)
396
```