0
# Input/Output Functions
1

2
File input/output operations for saving and loading CuPy arrays and data. These functions provide compatibility with NumPy's I/O format while handling GPU-CPU data transfers automatically.
3

4
## Capabilities
5

6
### Array File I/O
7

8
Save and load arrays in NumPy's binary formats with automatic GPU-CPU data transfers.
9

10
```python { .api }
11
def save(file, arr, allow_pickle=True, fix_imports=True):
12
    """
13
    Save an array to a binary file in NumPy .npy format.
14
    
15
    Parameters:
16
    - file: str or file-like, filename or file object
17
    - arr: cupy.ndarray, array to save
18
    - allow_pickle: bool, allow saving object arrays using Python pickles
19
    - fix_imports: bool, only useful for loading Python 2 generated pickled files
20
    """
21

22
def savez(file, *args, **kwds):
23
    """
24
    Save several arrays into a single file in uncompressed .npz format.
25
    
26
    Parameters:
27
    - file: str or file-like, filename or file object
28
    - args: cupy.ndarray, arrays to save as positional arguments
29
    - kwds: cupy.ndarray, arrays to save as keyword arguments
30
    """
31

32
def savez_compressed(file, *args, **kwds):
33
    """
34
    Save several arrays into a single file in compressed .npz format.
35
    
36
    Parameters:
37
    - file: str or file-like, filename or file object  
38
    - args: cupy.ndarray, arrays to save as positional arguments
39
    - kwds: cupy.ndarray, arrays to save as keyword arguments
40
    """
41

42
def load(file, mmap_mode=None, allow_pickle=False, fix_imports=True, encoding='ASCII'):
43
    """
44
    Load arrays or pickled objects from .npy, .npz or pickled files.
45
    
46
    Parameters:
47
    - file: str or file-like, filename or file object
48
    - mmap_mode: {None, 'r+', 'r', 'w+', 'c'}, memory-mapping mode
49
    - allow_pickle: bool, allow loading pickled object arrays
50
    - fix_imports: bool, only useful for loading Python 2 generated pickled files
51
    - encoding: str, encoding used to decode py2 strings
52
    
53
    Returns:
54
    cupy.ndarray, dict, or object: loaded array(s) or object
55
    """
56
```
57

58
### Text File I/O
59

60
Load and save arrays in text formats with automatic data type conversion.
61

62
```python { .api }
63
def loadtxt(fname, dtype=float, comments='#', delimiter=None, converters=None, 
64
           skiprows=0, usecols=None, unpack=False, ndmin=0, encoding='bytes',
65
           max_rows=None):
66
    """
67
    Load data from a text file into a GPU array.
68
    
69
    Parameters:
70
    - fname: str or file-like, filename or file object
71
    - dtype: data-type, data type of the resulting array
72
    - comments: str or sequence, characters marking comments
73
    - delimiter: str, string used to separate values
74
    - converters: dict, mapping column to function for conversion
75
    - skiprows: int, number of lines to skip at beginning
76
    - usecols: int or sequence, columns to read
77
    - unpack: bool, if True, return arrays for each column
78
    - ndmin: int, minimum number of dimensions
79
    - encoding: str, encoding to decode input
80
    - max_rows: int, maximum number of rows to read
81
    
82
    Returns:
83
    cupy.ndarray: array from text file
84
    """
85

86
def savetxt(fname, X, fmt='%.18e', delimiter=' ', newline='\n', header='',
87
           footer='', comments='# ', encoding=None):
88
    """
89
    Save a GPU array to a text file.
90
    
91
    Parameters:
92
    - fname: str or file-like, filename or file object
93
    - X: cupy.ndarray, 1-D or 2-D array to save
94
    - fmt: str or sequence, format string for array elements
95
    - delimiter: str, string separating columns
96
    - newline: str, string separating lines
97
    - header: str, text written at beginning of file
98
    - footer: str, text written at end of file  
99
    - comments: str, string to prepend to header and footer
100
    - encoding: str, encoding used to encode file
101
    """
102

103
def genfromtxt(fname, dtype=float, comments='#', delimiter=None, skip_header=0,
104
              skip_footer=0, converters=None, missing_values=None, 
105
              filling_values=None, usecols=None, names=None, excludelist=None,
106
              deletechars=''.join(sorted(set(string.punctuation) - set('_'))),
107
              defaultfmt="f%i", autostrip=False, replace_space='_',
108
              case_sensitive=True, unpack=None, invalid_raise=True, 
109
              max_rows=None, encoding='bytes'):
110
    """
111
    Load data from a text file with missing values handled as specified.
112
    
113
    Parameters:
114
    - fname: str or file-like, filename or file object
115
    - dtype: data-type, data type of the resulting array
116
    - comments: str or sequence, characters marking comments
117
    - delimiter: str, string used to separate values
118
    - skip_header: int, number of lines to skip at beginning
119
    - skip_footer: int, number of lines to skip at end
120
    - converters: dict, mapping column to conversion function
121
    - missing_values: set, strings corresponding to missing values
122
    - filling_values: set, values to use for missing data
123
    - usecols: sequence, columns to read
124
    - names: {None, True, str, sequence}, field names for structured array
125
    - excludelist: sequence, names of fields to exclude
126
    - deletechars: str, characters to remove from field names
127
    - defaultfmt: str, format of field names
128
    - autostrip: bool, whether to strip whitespace from values
129
    - replace_space: str, character to replace spaces in field names
130
    - case_sensitive: bool, whether field names are case sensitive
131
    - unpack: bool, if True, return separate variables for each column
132
    - invalid_raise: bool, whether to raise exception for inconsistent data
133
    - max_rows: int, maximum number of rows to read
134
    - encoding: str, encoding to decode input
135
    
136
    Returns:
137
    cupy.ndarray: array from text file with missing values handled
138
    """
139
```
140

141
### Array String Formatting
142

143
Format arrays as strings for display and output purposes.
144

145
```python { .api }
146
def array_str(a, max_line_width=None, precision=None, suppress_small=None):
147
    """
148
    Return a string representation of an array.
149
    
150
    Parameters:
151
    - a: cupy.ndarray, input array
152
    - max_line_width: int, maximum line width for printing
153
    - precision: int, floating point precision
154
    - suppress_small: bool, whether to suppress small values
155
    
156
    Returns:
157
    str: string representation of array
158
    """
159

160
def array_repr(arr, max_line_width=None, precision=None, suppress_small=None):
161
    """
162
    Return string representation of array that recreates the array.
163
    
164
    Parameters:
165
    - arr: cupy.ndarray, input array
166
    - max_line_width: int, maximum line width for printing
167
    - precision: int, floating point precision  
168
    - suppress_small: bool, whether to suppress small values
169
    
170
    Returns:
171
    str: string representation of array
172
    """
173

174
def array2string(a, max_line_width=None, precision=None, suppress_small=None,
175
                separator=' ', prefix="", style=float, formatter=None, 
176
                threshold=None, edgeitems=None, sign=None, floatmode=None,
177
                suffix="", legacy=None):
178
    """
179
    Return a string representation of an array with full control over formatting.
180
    
181
    Parameters:
182
    - a: cupy.ndarray, input array
183
    - max_line_width: int, maximum line width
184
    - precision: int, floating point precision
185
    - suppress_small: bool, suppress small values in scientific notation
186
    - separator: str, separator between array elements
187
    - prefix: str, string prepended to each line
188
    - style: function, formatting function for array elements
189
    - formatter: dict, custom formatting functions for different data types
190
    - threshold: int, total number of elements triggering summarization
191
    - edgeitems: int, number of edge items to show in summary
192
    - sign: str, controls printing of the sign of floats
193
    - floatmode: str, controls precision of floating point output
194
    - suffix: str, string appended to each line
195
    - legacy: str, legacy printing mode compatibility
196
    
197
    Returns:
198
    str: formatted string representation of array
199
    """
200
```
201

202
### Usage Examples
203

204
```python
205
import cupy as cp
206

207
# Save and load single array
208
x = cp.array([1, 2, 3, 4, 5])
209
cp.save('array.npy', x)
210
loaded_x = cp.load('array.npy')
211

212
# Save multiple arrays
213
y = cp.array([[1, 2], [3, 4]])
214
z = cp.array([5, 6, 7])
215
cp.savez('arrays.npz', x=x, y=y, z=z)
216

217
# Load multiple arrays
218
data = cp.load('arrays.npz')
219
print(data['x'], data['y'], data['z'])
220

221
# Text file I/O
222
data_2d = cp.random.rand(10, 3)
223
cp.savetxt('data.txt', data_2d, fmt='%.6f', delimiter=',')
224
loaded_data = cp.loadtxt('data.txt', delimiter=',')
225

226
# Array string formatting
227
arr = cp.array([[1.23456789, 2.34567890], [3.45678901, 4.56789012]])
228
print(cp.array_str(arr, precision=3))
229
print(cp.array_repr(arr, precision=2))
230
```