Model

Thinc uses just one model class for almost all layer types. Instead of creating subclasses, you’ll usually instantiate the Model class directly, passing in a forward function that actually performs the computation. You can find examples of this in the library itself, in thinc.layers (also see the layers documentation).


Model	Class for implementing Thinc models and layers.
Utilities	Helper functions for implementing models.
Shim	Interface for external models. Users can create subclasses of `Shim` to wrap external libraries.

Model class

Class for implementing Thinc models and layers.

Typing

Model can be used as a generic type with two parameters: the expected input and expected output. For instance, Model[List[Floats2d], Floats2d] denotes a model that takes a list of two-dimensional arrays of floats as inputs and outputs a two-dimensional array of floats. A mismatch will cause a type error. For more details, see the docs on type checking.

from typing import List
from thinc.api import Model
from thinc.types import Floats2d

def my_function(model: Model[List[Floats2d], Floats2d]):
    ...

Attributes

Name	Type	Description
`name`	`str`	The name of the layer type.
`ops`	`Ops`	Perform array operations.
`id`	`int`	ID number for the model instance.

Properties

Name	Type	Description
`layers`	`List[Model]`	A list of child layers of the model. You can use the list directly, including modifying it in-place: the standard way to add a layer to a model is simply `model.layers.append(layer)`. However, you cannot reassign the `model.layers` attribute to a new variable: `model.layers = []` will fail.
`shims`	`List[Shim]`	A list of child shims added to the model.
`attrs`	`Dict[str, Any]`	The model attributes. You can use the dict directly and assign to it – but you cannot reassign `model.attrs` to a new variable: `model.attrs = {}` will fail.
`param_names`	`Tuple[str, …]`	Get the names of registered parameter (including unset).
`grad_names`	`Tuple[str, …]`	Get the names of parameters with registered gradients (including unset).
`dim_names`	`Tuple[str, …]`	Get the names of registered dimensions (including unset).
`ref_names`	`Tuple[str, …]`	Get the names of registered node references (including unset).

Model.init method

Initialize a new model.

Examplemodel = Model(
    "linear",
    linear_forward,
    init=linear_init,
    dims={"nO": nO, "nI": nI},
    params={"W": None, "b": None},
)

Argument	Type	Description
`name`	`str`	The name of the layer type.
`forward`	`Callable`	Function to compute the forward result and the backpropagation callback.
keyword-only
`init`	`Callable`	Function to define the initialization logic.
`dims`	`Dict[str, Optional[int]]`	Dictionary describing the model’s dimensions. Map unknown dimensions to `None`.
`params`	`Dict[str, Optional[FloatsXd]]`	Dictionary with the model’s parameters. Set currently unavailable parameters to `None`.
`refs`	`Dict[str, Optional[Model]]`	Dictionary mapping specific nodes (sublayers) of the network to a name.
`attrs`	`Dict[str, Any]`	Dictionary of non-parameter attributes.
`layers`	`List[Model]`	List of child layers.
`shims`	`List[Shim]`	List of interfaces for external models.
`ops`	`Optional[Union[NumpyOps, AppleOps, CupyOps, MPSOps]]`	An `Ops` instance, which provides mathematical and memory operations.

Model.define_operators classmethodcontextmanager

Bind arbitrary binary functions to Python operators, for use in any Model instance. The method can (and should) be used as a contextmanager, so that the overloading is limited to the immediate block. This allows concise and expressive model definition. The following operators are supported: +, -, *, @, /, //, %, **, <<, >>, &, ^ and |.

Examplefrom thinc.api import Model, Relu, Softmax, chain

with Model.define_operators({">>": chain}):
    model = Relu(512) >> Relu(512) >> Softmax()

Argument	Type	Description
`operators`	`Dict[str, Callable]`	Functions mapped to operators.

Model.initialize method

Finish initialization of the model, optionally providing a batch of example input and output data to perform shape inference. Until Model.initialize is called, the model may not be in a ready state to operate on data: parameters or dimensions may be unset. The Model.initialize method will usually delegate to the init function given to Model.__init__.

If sample data is provided, it will be validated against the type annotations of the forward function, if available. A DataValidationError is raised in case of a mismatch, e.g. if the forward pass expects a two-dimensional array but the model is initialized with a three-dimensional array.

Examplefrom thinc.api import Linear, zero_init
import numpy

X = numpy.zeros((128, 16), dtype="f")
Y = numpy.zeros((128, 10), dtype="f")
model = Linear(init_W=zero_init)
model.initialize(X=X, Y=Y)

Argument	Type	Description
`X`	`Optional[Any]`	An example batch of input data.
`Y`	`Optional[Any]`	An example batch of output data.
RETURNS	`Model`	The model instance.

Model.call method

Call the model’s forward function, returning the output and a callback to compute the gradients via backpropagation.

Examplefrom thinc.api import Linear
import numpy

X = numpy.zeros((128, 10), dtype="f")
model = Linear(10)
model.initialize(X=X)
Y, backprop = model(X, is_train=True)

Argument	Type	Description
`X`	`Any`	A batch of input data.
`is_train`	`bool`	A boolean indicating whether the model is running in a training (as opposed to prediction) context.
RETURNS	`Tuple[Any, Callable]`	A batch of output data and the `backprop` callback.

Model.begin_update method

Call the model’s forward function with is_train=True, and return the output and the backpropagation callback, which is a function that takes a gradient of outputs and returns the corresponding gradient of inputs. The backpropagation callback may also increment the gradients of the model parameters, via calls to Model.inc_grad.

Examplefrom thinc.api import Linear
import numpy

X = numpy.zeros((128, 10), dtype="f")
model = Linear(10)
model.initialize(X=X)
Y, backprop = model.begin_update(X)

Argument	Type	Description
`X`	`Any`	A batch of input data.
RETURNS	`Tuple[Any, Callable]`	A batch of output data and the `backprop` callback.

Model.predict method

Call the model’s forward function with is_train=False, and return only the output, instead of the (output, callback) tuple.

Examplefrom thinc.api import Linear
import numpy

X = numpy.zeros((128, 10), dtype="f")
model = Linear(10)
model.initialize(X=X)
Y = model.predict(X)

Argument	Type	Description
`X`	`Any`	A batch of input data.
RETURNS	`Any`	A batch of output data.

Model.finish_update method

Update parameters using the current parameter gradients. The Optimizer instance contains the functionality to perform the stochastic gradient descent.

Examplefrom thinc.api import Adam, Linear

optimizer = Adam()
model = Linear(10)
model.finish_update(optimizer)

Argument	Type	Description
`optimizer`	`Optimizer`	The optimizer, which is called with each parameter and gradient of the model.

Model.use_params contextmanager

Contextmanager to temporarily set the model’s parameters to specified values.

Argument	Type	Description
`params`	`Dict[int, FloatsXd]`	A dictionary keyed by model IDs, whose values are arrays of weight values.

Model.walk method

Iterate out layers of the model, in breadth-first order.

Examplefrom thinc.api import Relu

model = Relu(512, normalize=True)
for node in model.walk():
    print(node.name)

The walk method supports three iteration orders through the order argument:

"bfs": breadth-first. Iteration order of the example above: 1 - 2 - 4 - 3 - 5
"dfs_pre": depth-first preorder, outputs a node before its children. Iteration order of the example above: 1 - 2 - 3 - 4 - 5
"dfs_post": depth-first postorder, outputs children before a node itself. Iteration order of the example above: 3 - 2 - 5 - 4 - 1

Argument	Type	Description
`order`	`str`	Node iteration order. `"bfs"` (breadth-first), `"dfs_pre"` (depth-first preorder), `"dfs_post"` (depth-first postorder) Default: `"bfs"`.
RETURNS	`Iterable[Model]`	The layers of the model.

Model.remove_node method

Remove a node from all layers lists, and then update references. References that no longer point to a node within the tree will be set to None. For instance, if a node has its grandchild as a reference and the child is removed, the grandchild reference will be left dangling, so will be set to None.

Argument	Type	Description
`node`	`Model`	The node to remove.

Model.has_dim method

Check whether the model has a dimension of a given name. If the dimension is registered but the value is unset, returns None.

Examplefrom thinc.api import Linear
import numpy

model = Linear(10)
assert model.has_dim("nI") is None
model.initialize(X=numpy.zeros((128, 16), dtype="f"))
assert model.has_dim("nI") is True

Argument	Type	Description
`name`	`str`	The name of the dimension, e.g. `"nO"`.
RETURNS	`Optional[bool]`	A ternary value (`True`, `False`, or `None`).

Model.get_dim method

Retrieve the value of a dimension of the given name. Raises a KeyError if the dimension is either unregistered or the value is currently unset.

Examplefrom thinc.api import Linear
import numpy

model = Linear(10)
model.initialize(X=numpy.zeros((128, 16), dtype="f"))
assert model.get_dim("nI") == 16

Argument	Type	Description
`name`	`str`	The name of the dimension, e.g. `"nO"`.
RETURNS	`int`	The size of the dimension.

Model.maybe_get_dim method

Retrieve the value of a dimension of the given name, or None if the dimension is either unregistered or the value is currently unset.

Argument	Type	Description
`name`	`str`	The name of the dimension, e.g. `"nO"`.
RETURNS	`Optional[int]`	The size of the dimension, or `None`.

Model.set_dim method

Set a value for a dimension. This raises a ValueError if the dimension was previously defined with a different value, unless force is set to True.

Examplefrom thinc.api import Linear

model = Linear(10)
model.set_dim("nI", 16)
assert model.get_dim("nI") == 16

Argument	Type	Description
`name`	`str`	The name of the dimension to set.
`value`	`int`	The new value for the dimension.
`force`	`bool`	When set to `True`, allow changing the value of the dimension if it was set before. Default: `False`.

Model.has_param method

Check whether the model has a weights parameter of the given name. Returns None if the parameter is registered but currently unset.

Examplefrom thinc.api import Linear, zero_init
import numpy

model = Linear(10, init_W=zero_init)
assert model.has_param("W") is None
model.initialize(X=numpy.zeros((128, 16), dtype="f"))
assert model.has_param("W") is True

Argument	Type	Description
`name`	`str`	The name of the parameter.
RETURNS	`Optional[bool]`	A ternary value (`True`, `False`, or `None`).

Model.get_param method

Retrieve a weights parameter by name. Raises a KeyError if the parameter is unregistered or its value is undefined.

Examplefrom thinc.api import Linear, zero_init
import numpy

model = Linear(10, init_W=zero_init)
assert model.has_param("W") is None
model.initialize(X=numpy.zeros((128, 16), dtype="f"))
W = model.get_param("W")
assert W.shape == (10, 16)

Argument	Type	Description
`name`	`str`	The name of the parameter to get.
RETURNS	`FloatsXd`	The current parameter.

Model.maybe_get_param method

Retrieve a weights parameter by name. Returns None if the parameter is unregistered or its value is undefined.

Argument	Type	Description
`name`	`str`	The name of the parameter to get.
RETURNS	`Optional[FloatsXd]`	The current parameter, or `None`.

Model.set_param method

Set a weights parameter’s value.

Examplefrom thinc.api import Linear, zero_init
import numpy

model = Linear(10, init_W=zero_init)
assert model.has_param("W") is None
model.set_param("W", numpy.zeros((10, 16), dtype="f"))
assert model.has_param("W") is True

Argument	Type	Description
`name`	`str`	The name of the parameter to set a value for.
`value`	`Optional[FloatsXd]`	The new value of the parameter.

Model.has_ref method

Check whether the model has a reference of a given name. If the reference is registered but the value is unset, returns None.

Argument	Type	Description
`name`	`str`	The name of the reference.
RETURNS	`Optional[bool]`	A ternary value (`True`, `False`, or `None`).

Model.get_ref method

Retrieve the value of a reference of the given name. Raises a KeyError if unset.

Argument	Type	Description
`name`	`str`	The name of the reference.
RETURNS	`Model`	The reference.

Model.maybe_get_ref method

Retrieve the value of a reference of the given name, or None if unset.

Argument	Type	Description
`name`	`str`	The name of the reference.
RETURNS	`Optional[Model]`	The reference, or `None`.

Model.set_ref method

Set a value for a reference.

Argument	Type	Description
`name`	`str`	The name of the reference.
`value`	`Optional[Model]`	The new value for the attribute.

Model.has_grad method

Check whether the model has a non-zero gradient for the given parameter. If the gradient is allocated but is zeroed, returns None.

Argument	Type	Description
`name`	`str`	The parameter to check the gradient for.
RETURNS	`Optional[bool]`	A ternary value (`True`, `False`, or `None`).

Model.get_grad method

Get the gradient for a parameter, if one is available. If the parameter is undefined or no gradient has been allocated, raises a KeyError.

Argument	Type	Description
`name`	`str`	The name of the parameter to get the gradient for.
RETURNS	`FloatsXd`	The current gradient of the parameter.

Model.maybe_get_grad method

Get the gradient for a parameter, if one is available. If the parameter is undefined or no gradient has been allocated, returns None.

Argument	Type	Description
`name`	`str`	The name of the parameter to get the gradient for.
RETURNS	`Optional[FloatsXd]`	The current gradient of the parameter, or `None`.

Model.set_grad method

Set a parameter gradient to a new value.

Argument	Type	Description
`name`	`str`	The name of the parameter to assign the gradient for.
`value`	`FloatsXd`	The new gradient.

Model.inc_grad method

Increment the gradient of a parameter by value.

Argument	Type	Description
`name`	`str`	The name of the parameter.
`value`	`FloatsXd`	The value to add to its gradient.

Model.get_gradients method

Get non-zero gradients of the model’s parameters, as a dictionary keyed by the parameter ID. The values are (weights, gradients) tuples.

Argument	Type	Description
RETURNS	`Dict[Tuple[int, str], Tuple[FloatsXd, FloatsXd]]`	The gradients keyed by parameter ID.

Model.copy method

Create a copy of the model, its attributes, and its parameters. Any child layers will also be deep-copied. The copy will receive a distinct model.id value.

Examplefrom thinc.api import Linear

model = Linear()
model_copy = model.copy()

Argument	Type	Description
RETURNS	`Model`	A new copy of the model.

Model.to_gpu method

Transfer the model to a given GPU device.

Exampledevice = model.to_gpu(0)

Argument	Type	Description
`gpu_id`	`int`	Device index to select.
RETURNS	`cupy.cuda.Device`	The device.

Model.to_cpu method

Copy the model to CPU.

Examplemodel.to_cpu()

Model.to_dict method

Serialize the model to a Python dictionary. Model.to_bytes delegates to this method to create the dict, which it then dumps with MessagePack. Serialization should round-trip identically, i.e. the same dict should result from loading and serializing a model.

Examplemodel_data = model.to_dict()

Argument	Type	Description
RETURNS	`dict`	The serialized model.

Model.from_dict method

Load the model from a Python dictionary.

Examplemodel_data = model.to_dict()
model = Model("model_name", forward).from_dict(model_data)

Argument	Type	Description
`msg`	`dict`	The data to load.
RETURNS	`Model`	The loaded model.

Model.to_bytes method

Serialize the model to a bytes representation.

Examplebytes_data = model.to_bytes()

Argument	Type	Description
RETURNS	`bytes`	The serialized model.

Model.from_bytes method

Deserialize the model from a bytes representation.

Examplebytes_data = model.to_bytes()
model = Model("model_name", forward).from_bytes(bytes_data)

Argument	Type	Description
`bytes_data`	`bytes`	The bytestring to load.
RETURNS	`Model`	The loaded model.

Model.to_disk method

Serialize the model to disk. Most models will serialize to a single file, which should just be the bytes contents of Model.to_bytes.

Examplemodel.to_disk("/path/to/model")

Argument	Type	Description
`path`	`Union[Path, str]`	File or directory to save the model to.

Model.from_disk method

Deserialize the model from disk. Most models will serialize to a single file, which should just be the bytes contents of Model.to_bytes.

Examplemodel = Model().from_disk("/path/to/model")

Argument	Type	Description
`path`	`Union[Path, str]`	Directory to load the model from.
RETURNS	`Model`	The loaded model.

Model.can_from_bytes method

Check whether bytes data is compatible with the model for deserialization.

Argument	Type	Description
`bytes_data`	`bytes`	The bytestring to check.
`strict`	`bool`	Whether to require attributes to match.
RETURNS	`bool`	Whether the data is compatible.

Model.can_from_bytes method

Check whether a path is compatible with the model for deserialization.

Argument	Type	Description
`path`	`Union[Path, str]`	The path to check.
`strict`	`bool`	Whether to require attributes to match.
RETURNS	`Model`	Whether the path is compatible.

Model.can_from_dict method

Check whether a dictionary is compatible with the model for deserialization.

Argument	Type	Description
`msg`	`dict`	The data to check.
`strict`	`bool`	Whether to require attributes to match.
RETURNS	`Model`	Whether the data is compatible.

Utilities

serialize_attr functionsingle-dispatch

Single-dispatch generic function that serializes a model attribute in Model.attrs to bytes and can be customized to support other objects and data types. By default, the function uses MessagePack to serialize the attribute value to bytes. To register a serialization function for a custom type, you can use the @serialize_attr.register decorator and call it with the custom type. If an attribute of that type exists on a model, the registered function will be used to serialize it.

Examplefrom thinc.api import serialize_attr

@serialize_attr.register(MyCustomClass)
def serialize_my_custom_class(_, value: MyCustomClass, name: str, model) -> bytes:
    # value is an instance of MyCustomClass that needs to be serialized. You
    # can perform any custom serialization here and return bytes
    return value.custom_serialization_method()

Argument	Type	Description
`_`	`Any`	An instance of the value to serialize. Its type will be used to determine which registered serialization function to apply.
`value`	`Any`	The value to serialize.
`name`	`str`	The attribute name.
`model`	`Model`	The model that’s being serialized, e.g. to retrieve other information.
RETURNS	`bytes`	The serialized attribute.

deserialize_attr functionsingle-dispatch

Single-dispatch generic function that deserializes a model attribute in Model.attrs from bytes and can be customized to support other objects and data types. By default, the function uses MessagePack to load the attribute value from bytes. To register a deserialization function for a custom type, you can use the @deserialize_attr.register decorator and call it with the custom type. If an attribute of that type exists on a model, the registered function will be used to deserialize it.

Examplefrom thinc.api import deserialize_attr

@deserialize_attr.register(MyCustomClass)
def deserialize_my_custom_class(_, value: bytes, name: str, model) -> MyCustomClass:
    # value is a bytestring that needs to be deserialized and transformed into
    # MyCustomClass. You can perform any custom deserialization here and return
    # an instance of MyCustomClass.
    return MyCustomClass().custom_load_method(value)

Argument	Type	Description
`_`	`Any`	An instance of the value to deserialize (the default value of the attribute). Its type will be used to determine which registered deserialization function to apply.
`value`	`bytes`	The bytestring to load.
`name`	`str`	The attribute name.
`model`	`Model`	The model that’s being deserialized, e.g. to perform other side-effects.
RETURNS	`Any`	The loaded attribute.

Shim class

Define a basic interface for external models. Users can create subclasses of Shim to wrap external libraries. The Thinc Model class treats Shim objects as a sort of special type of sublayer: it knows they’re not actual Thinc Model instances, but it also knows to talk to the shim instances when doing things like using transferring between devices, loading in parameters, optimization. It also knows Shim objects need to be serialized and deserialized with to/from bytes/disk, rather than expecting that they’ll be msgpack-serializable. A Shim can implement the following methods:

Method	Description
`__init__`	Initialize the model.
`__call__`	Call the model and return the output and a callback to compute the gradients via backpropagation.
`predict`	Call the model and return only the output, instead of the `(output, callback)` tuple.
`begin_update`	Run the model over a batch of data, returning the output and a callback to complete the backward pass.
`finish_update`	Update parameters with current gradients.
`use_params`	Context manager to temporarily set the model’s parameters to specified values.
`to_gpu`	Transfer the model to a given GPU device.
`to_cpu`	Copy the model to CPU.
`to_bytes`	Serialize the model to bytes.
`from_bytes`	Load the model from bytes.
`to_disk`	Serialize the model to disk. Defaults to writing the bytes representation to a file.
`from_disk`	Load the model from disk. Defaults to loading the byte representation from a file.

Available shims


`PyTorchShim`	Interface between a PyTorch model and a Thinc `Model`. For more details and examples, see the `PyTorchWrapper` layer and docs on integrating other frameworks.
`TorchScriptShim`	Interface between a TorchScript model and a Thinc `Model`. For more details and examples, see the `TorchScriptWrapper` layer and docs on integrating other frameworks.
`TensorFlowShim`	Interface between a TensorFlow model and a Thinc `Model`. For more details, see the `TensorFlowWrapper` layer and docs on integrating other frameworks
`MXNetShim`	Interface between a MXNet model and a Thinc `Model`. For more details, see the `MXNetWrapper` layer and docs on integrating other frameworks