0
# Memory Layout and Transposition
1

2
In-place transposition functions that minimize memory spikes during array layout conversion. Critical for efficient GPU transfers, disk I/O, and interfacing between different computing environments that expect specific memory layouts.
3

4
## Capabilities
5

6
### In-Place Matrix Transposition
7

8
Perform in-place transposition for up to 4D matrices, avoiding memory spikes associated with out-of-place operations.
9

10
```python { .api }
11
def transpose(
12
    arr: NDArray
13
) -> NDArray:
14
    """
15
    Perform in-place transposition for up to 4D matrices.
16
    
17
    Args:
18
        arr: Input numpy array to transpose
19
    
20
    Returns:
21
        The transposed numpy array
22
    """
23
```
24

25
**Usage Example:**
26

27
```python
28
import fastremap
29
import numpy as np
30

31
# 2D matrix transposition
32
arr = np.array([[1, 2, 3],
33
                [4, 5, 6]], dtype=np.float32)
34

35
# In-place transpose (memory efficient)
36
transposed = fastremap.transpose(arr)
37
# Result: [[1, 4], [2, 5], [3, 6]]
38

39
# 3D array transposition
40
arr_3d = np.random.random((100, 200, 300)).astype(np.float32)
41
transposed_3d = fastremap.transpose(arr_3d)
42
# Result: (300, 200, 100) shaped array, transposed in-place
43
```
44

45
### Fortran Order Conversion
46

47
Convert array to Fortran (column-major) order, performing in-place transposition when possible for memory efficiency.
48

49
```python { .api }
50
def asfortranarray(
51
    arr: NDArray
52
) -> NDArray:
53
    """
54
    Convert array to Fortran order, performing in-place transposition when possible.
55
    
56
    Args:
57
        arr: Input numpy array to convert
58
    
59
    Returns:
60
        Array in Fortran order
61
    """
62
```
63

64
**Usage Example:**
65

66
```python
67
import fastremap
68
import numpy as np
69

70
# C-order array
71
arr = np.ones((512, 512, 512), dtype=np.float32, order='C')
72
print(f"Original order: {arr.flags['C_CONTIGUOUS']}, {arr.flags['F_CONTIGUOUS']}")
73

74
# Convert to Fortran order efficiently
75
fortran_arr = fastremap.asfortranarray(arr)
76
print(f"Fortran order: {fortran_arr.flags['F_CONTIGUOUS']}")
77

78
# More memory efficient than np.asfortranarray for large arrays
79
# np.asfortranarray(arr)  # would create a copy, using more memory
80
```
81

82
### C Order Conversion
83

84
Convert array to C (row-major) order, performing in-place transposition when possible for memory efficiency.
85

86
```python { .api }
87
def ascontiguousarray(
88
    arr: NDArray
89
) -> NDArray:
90
    """
91
    Convert array to C order, performing in-place transposition when possible.
92
    
93
    Args:
94
        arr: Input numpy array to convert
95
    
96
    Returns:
97
        Array in C order
98
    """
99
```
100

101
**Usage Example:**
102

103
```python
104
import fastremap
105
import numpy as np
106

107
# Fortran-order array
108
arr = np.ones((512, 512, 512), dtype=np.float32, order='F')
109
print(f"Original order: {arr.flags['C_CONTIGUOUS']}, {arr.flags['F_CONTIGUOUS']}")
110

111
# Convert to C order efficiently
112
c_arr = fastremap.ascontiguousarray(arr)
113
print(f"C order: {c_arr.flags['C_CONTIGUOUS']}")
114

115
# More memory efficient than np.ascontiguousarray for large arrays
116
# Benefits are most pronounced with square or cubic arrays
117
```
118

119
## Memory Layout Considerations
120

121
### When In-Place Operations Are Used
122

123
Fastremap's memory layout functions automatically detect when in-place transposition is possible:
124

125
- **Contiguous memory**: Array must have contiguous memory layout
126
- **Rectangular arrays**: Works with 1D, 2D, 3D, and 4D arrays
127
- **Square/cubic optimization**: Square (2D) and cubic (3D) arrays benefit most from in-place operations
128

129
### Performance Benefits
130

131
```python
132
import fastremap
133
import numpy as np
134
import time
135

136
# Large array example
137
large_arr = np.random.random((1000, 1000, 100)).astype(np.float32, order='C')
138

139
# fastremap approach (in-place when possible)
140
start = time.time()
141
fast_result = fastremap.asfortranarray(large_arr)
142
fast_time = time.time() - start
143

144
# numpy approach (always creates copy)
145
start = time.time()
146
numpy_result = np.asfortranarray(large_arr)
147
numpy_time = time.time() - start
148

149
print(f"fastremap time: {fast_time:.3f}s")
150
print(f"numpy time: {numpy_time:.3f}s")
151
print(f"Memory usage advantage: {numpy_time/fast_time:.1f}x faster")
152
```
153

154
## Types
155

156
```python { .api }
157
NDArray = np.ndarray
158
```