1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
---
title: Utilities & Extras
teaser: Helpers and utility functions
---
### fix_random_seed {#fix_random_seed tag="function"}
Set the random seed for `random`, `numpy.random` and `cupy.random` (if
available). Should be called at the top of a file or function.
```python
### Example
from thinc.api import fix_random_seed
fix_random_seed(0)
```
| Argument | Type | Description |
| -------- | ------------ | -------------------------- |
| `seed` | <tt>int</tt> | The seed. Defaults to `0`. |
### require_cpu {#require_cpu tag="function"}
Allocate data and perform operations on CPU. If data has already been allocated
on GPU, it will not be moved. Ideally, this function should be called right
after importing Thinc.
```python
### Example
from thinc.api import require_cpu
require_cpu()
```
| Argument | Type | Description |
| ----------- | ------------- | ----------- |
| **RETURNS** | <tt>bool</tt> | `True`. |
### prefer_gpu {#prefer_gpu tag="function"}
Allocate data and perform operations on GPU, if available. If data has already
been allocated on CPU, it will not be moved. Ideally, this function should be
called right after importing Thinc.
```python
### Example
from thinc.api import prefer_gpu
is_gpu = prefer_gpu()
```
| Argument | Type | Description |
| ----------- | ------------- | ---------------------------------------- |
| `gpu_id` | <tt>int</tt> | Device index to select. Defaults to `0`. |
| **RETURNS** | <tt>bool</tt> | Whether the GPU was activated. |
### require_gpu {#require_gpu tag="function"}
Allocate data and perform operations on GPU. Will raise an error if no GPU is
available. If data has already been allocated on CPU, it will not be moved.
Ideally, this function should be called right after importing Thinc.
```python
### Example
from thinc.api import require_gpu
require_gpu()
```
| Argument | Type | Description |
| ----------- | ------------- | ----------- |
| **RETURNS** | <tt>bool</tt> | `True`. |
### set_active_gpu {#set_active_gpu tag="function"}
Set the current GPU device for `cupy` (and for `torch`, if installed) and return
a `cupy` device. Will raise an error if no GPU is available.
```python
### Example
from thinc.api import set_active_gpu
set_active_gpu(0)
```
| Argument | Type | Description |
| ----------- | ------------------------- | ----------------------- |
| `gpu_id` | <tt>int</tt> | Device index to select. |
| **RETURNS** | <tt>cupy.cuda.Device</tt> | The device. |
### use_pytorch_for_gpu_memory {#use_pytorch_for_gpu_memory tag="function"}
Route GPU memory allocation via PyTorch. This is recommended for using PyTorch
and `cupy` together, as otherwise OOM errors can occur when there's available
memory sitting in the other library's pool. We'd like to support routing
TensorFlow memory allocation via PyTorch as well (or vice versa), but do not
currently have an implementation for it.
```python
### Example
from thinc.api import prefer_gpu, use_pytorch_for_gpu_memory
if prefer_gpu():
use_pytorch_for_gpu_memory()
```
### use_tensorflow_for_gpu_memory {#use_tensorflow_for_gpu_memory tag="function"}
Route GPU memory allocation via TensorFlow. This is recommended for using
TensorFlow and `cupy` together, as otherwise OOM errors can occur when there's
available memory sitting in the other library's pool. We'd like to support
routing PyTorch memory allocation via TensorFlow as well (or vice versa), but do
not currently have an implementation for it.
```python
### Example
from thinc.api import prefer_gpu, use_tensorflow_for_gpu_memory
if prefer_gpu():
use_tensorflow_for_gpu_memory()
```
### get_width {#get_width tag="function"}
Infer the width of a batch of data, which could be any of: an n-dimensional
array (use the shape) or a sequence of arrays (use the shape of the first
element).
| Argument | Type | Description |
| -------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| `X` | <tt>Union[ArrayXd, Ragged, Padded, Sequence[ArrayXd]]</tt> | The array(s). |
| _keyword-only_ | | |
| `dim` | <tt>int</tt> | Which dimension to get the size for. Defaults to `-1`. |
| **RETURNS** | <tt>int</tt> | The array's inferred width. |
### to_categorical {#to_categorical tag="function"}
Converts a class vector (integers) to binary class matrix. Based on
[`keras.utils.to_categorical`](https://keras.io/utils/).
| Argument | Type | Description |
| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
| `Y` | <tt>IntsXd</tt> | Class vector to be converted into a matrix (integers from `0` to `n_classes`). |
| `n_classes` | <tt>Optional[int]</tt> | Total number of classes. |
| _keyword-only_ | | |
| `label_smoothing` | <tt>float</tt> | Smoothing-coefficient for label-smoothing. |
| **RETURNS** | <tt>Floats2d</tt> | A binary matrix representation of the input. The axis representing the classes is placed last. |
### enable_mxnet {#enable_mxnet tag="function" new="8.2.0"}
Import and enable internal support for MXNet.
### enable_tensorflow {#enable_tensorflow tag="function" new="8.2.0"}
Import and enable internal support for TensorFlow.
### xp2torch {#xp2torch tag="function"}
Convert a `numpy` or `cupy` tensor to a PyTorch tensor.
| Argument | Type | Description |
| --------------- | --------------------- | ---------------------------------------------- |
| `xp_tensor` | <tt>ArrayXd</tt> | The tensor to convert. |
| `requires_grad` | <tt>bool</tt> | Whether to backpropagate through the variable. |
| **RETURNS** | <tt>torch.Tensor</tt> | The converted tensor. |
### torch2xp {#torch2xp tag="function"}
Convert a PyTorch tensor to a `numpy` or `cupy` tensor.
| Argument | Type | Description |
| -------------- | --------------------- | ---------------------- |
| `torch_tensor` | <tt>torch.Tensor</tt> | The tensor to convert. |
| **RETURNS** | <tt>ArrayXd</tt> | The converted tensor. |
### xp2tensorflow {#xp2tensorflow tag="function"}
Convert a `numpy` or `cupy` tensor to a TensorFlow tensor.
| Argument | Type | Description |
| --------------- | -------------------------- | ----------------------------------------------------- |
| `xp_tensor` | <tt>ArrayXd</tt> | The tensor to convert. |
| `requires_grad` | <tt>bool</tt> | Whether to backpropagate through the variable. |
| `as_variable` | <tt>bool</tt> | Convert the result to a `tensorflow.Variable` object. |
| **RETURNS** | <tt>tensorflow.Tensor</tt> | The converted tensor. |
### tensorflow2xp {#tensorflow2xp tag="function"}
Convert a TensorFlow tensor to a `numpy` or `cupy` tensor.
| Argument | Type | Description |
| ------------------- | -------------------------- | ---------------------- |
| `tensorflow_tensor` | <tt>tensorflow.Tensor</tt> | The tensor to convert. |
| **RETURNS** | <tt>ArrayXd</tt> | The converted tensor. |
### xp2mxnet {#xp2mxnet tag="function"}
Convert a `numpy` or `cupy` tensor to an MXNet tensor.
| Argument | Type | Description |
| --------------- | ---------------------- | ---------------------------------------------- |
| `xp_tensor` | <tt>ArrayXd</tt> | The tensor to convert. |
| `requires_grad` | <tt>bool</tt> | Whether to backpropagate through the variable. |
| **RETURNS** | <tt>mx.nd.NDArray</tt> | The converted tensor. |
### mxnet2xp {#mxnet2xp tag="function"}
Convert an MXNet tensor to a `numpy` or `cupy` tensor.
| Argument | Type | Description |
| ----------- | ---------------------- | ---------------------- |
| `mx_tensor` | <tt>mx.nd.NDArray</tt> | The tensor to convert. |
| **RETURNS** | <tt>ArrayXd</tt> | The converted tensor. |
### Errors {#errors}
Thinc uses the following custom errors:
| Name | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ConfigValidationError` | Raised if invalid config settings are encountered by [`Config`](/docs/api-config#config) or the [`registry`](/docs/api-config#registry), or if resolving and validating the referenced functions fails. |
| `DataValidationError` | Raised if [`Model.initialize`](/docs/api-model#initialize) is called with sample input or output data that doesn't match the expected input or output of the network, or leads to mismatched input or output in any of its layer. |
|
