Package: dm-sonnet
SonnetDocumentation|ExamplesSonnet is a library built on top ofTensorFlow 2designed to provide simple, composable abstractions for machine learning
research.IntroductionSonnet has been designed and built by researchers at DeepMind. It can be used to
construct neural networks for many different purposes (un/supervised learning,
reinforcement learning, ...). We find it is a successful abstraction for our
organization, you might too!More specifically, Sonnet provides a simple but powerful programming model
centered around a single concept:snt.Module. Modules can hold references to
parameters, other modules and methods that apply some function on the user
input. Sonnet ships with many predefined modules (e.g.snt.Linear,snt.Conv2D,snt.BatchNorm) and some predefined networks of modules (e.g.snt.nets.MLP) but users are also encouraged to build their own modules.Unlike many frameworks Sonnet is extremely unopinionated abouthowyou will
use your modules. Modules are designed to be self contained and entirely
decoupled from one another. Sonnet does not ship with a training framework and
users are encouraged to build their own or adopt those built by others.Sonnet is also designed to be simple to understand, our code is (hopefully!)
clear and focussed. Where we have picked defaults (e.g. defaults for initial
parameter values) we try to point out why.Getting StartedExamplesThe easiest way to try Sonnet is to use Google Colab which offers a free Python
notebook attached to a GPU or TPU.Predicting MNIST with an MLPTraining a Little GAN on MNISTDistributed training withsnt.distributeInstallationTo get started install TensorFlow 2.0 and Sonnet 2:$pipinstalltensorflowtensorflow-probability
$pipinstalldm-sonnetYou can run the following to verify things installed correctly:importtensorflowastfimportsonnetassntprint("TensorFlow version{}".format(tf.__version__))print("Sonnet version{}".format(snt.__version__))Using existing modulesSonnet ships with a number of built in modules that you can trivially use. For
example to define an MLP we can use thesnt.Sequentialmodule to call a
sequence of modules, passing the output of a given module as the input for the
next module. We can usesnt.Linearandtf.nn.reluto actually define our
computation:mlp=snt.Sequential([snt.Linear(1024),tf.nn.relu,snt.Linear(10),])To use our module we need to "call" it. TheSequentialmodule (and most
modules) define a__call__method that means you can call them by name:logits=mlp(tf.random.normal([batch_size,input_size]))It is also very common to request all the parameters for your module. Most
modules in Sonnet create their parameters the first time they are called with
some input (since in most cases the shape of the parameters is a function of
the input). Sonnet modules provide two properties for accessing parameters.Thevariablesproperty returnsalltf.Variables that are referenced by
the given module:all_variables=mlp.variablesIt is worth noting thattf.Variables are not just used for parameters of your
model. For example they are used to hold state in metrics used insnt.BatchNorm. In most cases users retrieve the module variables to pass them
to an optimizer to be updated. In this case non-trainable variables should
typically not be in that list as they are updated via a different mechanism.
TensorFlow has a built in mechanism to mark variables as "trainable" (parameters
of your model) vs. non-trainable (other variables). Sonnet provides a mechanism
to gather all trainable variables from your module which is probably what you
want to pass to an optimizer:model_parameters=mlp.trainable_variablesBuilding your own moduleSonnet strongly encourages users to subclasssnt.Moduleto define their own
modules. Let's start by creating a simpleLinearlayer calledMyLinear:classMyLinear(snt.Module):def__init__(self,output_size,name=None):super(MyLinear,self).__init__(name=name)self.output_size=output_size@snt.oncedef_initialize(self,x):initial_w=tf.random.normal([x.shape[1],self.output_size])self.w=tf.Variable(initial_w,name="w")self.b=tf.Variable(tf.zeros([self.output_size]),name="b")def__call__(self,x):self._initialize(x)returntf.matmul(x,self.w)+self.bUsing this module is trivial:mod=MyLinear(32)mod(tf.ones([batch_size,input_size]))By subclassingsnt.Moduleyou get many nice properties for free. For example
a default implementation of__repr__which shows constructor arguments (very
useful for debugging and introspection):>>>print(repr(mod))MyLinear(output_size=10)You also get thevariablesandtrainable_variablesproperties:>>>mod.variables(<tf.Variable'my_linear/b:0'shape=(10,)...)>,<tf.Variable'my_linear/w:0'shape=(1,10)...)>)You may notice themy_linearprefix on the variables above. This is because
Sonnet modules also enter the modules name scope whenever methods are called.
By entering the module name scope we provide a much more useful graph for tools
like TensorBoard to consume (e.g. all operations that occur inside my_linear
will be in a group called my_linear).Additionally your module will now support TensorFlow checkpointing and saved
model which are advanced features covered later.SerializationSonnet supports multiple serialization formats. The simplest format we support
is Python'spickle, and all built in modules are tested to make sure they can
be saved/loaded via pickle in the same Python process. In general we discourage
the use of pickle, it is not well supported by many parts of TensorFlow and in
our experience can be quite brittle.TensorFlow CheckpointingReference:https://www.tensorflow.org/alpha/guide/checkpointsTensorFlow checkpointing can be used to save the value of parameters
periodically during training. This can be useful to save the progress of
training in case your program crashes or is stopped. Sonnet is designed to work
cleanly with TensorFlow checkpointing:checkpoint_root="/tmp/checkpoints"checkpoint_name="example"save_prefix=os.path.join(checkpoint_root,checkpoint_name)my_module=create_my_sonnet_module()# Can be anything extending snt.Module.# A `Checkpoint` object manages checkpointing of the TensorFlow state associated# with the objects passed to it's constructor. Note that Checkpoint supports# restore on create, meaning that the variables of `my_module` do **not** need# to be created before you restore from a checkpoint (their value will be# restored when they are created).checkpoint=tf.train.Checkpoint(module=my_module)# Most training scripts will want to restore from a checkpoint if one exists. This# would be the case if you interrupted your training (e.g. to use your GPU for# something else, or in a cloud environment if your instance is preempted).latest=tf.train.latest_checkpoint(checkpoint_root)iflatestisnotNone:checkpoint.restore(latest)forstep_numinrange(num_steps):train(my_module)# During training we will occasionally save the values of weights. Note that# this is a blocking call and can be slow (typically we are writing to the# slowest storage on the machine). If you have a more reliable setup it might be# appropriate to save less frequently.ifstep_numandnotstep_num%1000:checkpoint.save(save_prefix)# Make sure to save your final values!!checkpoint.save(save_prefix)TensorFlow Saved ModelReference:https://www.tensorflow.org/alpha/guide/saved_modelTensorFlow saved models can be used to save a copy of your network that is
decoupled from the Python source for it. This is enabled by saving a TensorFlow
graph describing the computation and a checkpoint containing the value of
weights.The first thing to do in order to create a saved model is to create asnt.Modulethat you want to save:my_module=snt.nets.MLP([1024,1024,10])my_module(tf.ones([1,input_size]))Next, we need to create another module describing the specific parts of our
model that we want to export. We advise doing this (rather than modifying the
original model in-place) so you have fine grained control over what is actually
exported. This is typically important to avoid creating very large saved models,
and such that you only share the parts of your model you want to (e.g. you only
want to share the generator for a GAN but keep the discriminator private).@tf.function(input_signature=[tf.TensorSpec([None,input_size])])definference(x):returnmy_module(x)to_save=snt.Module()to_save.inference=inferenceto_save.all_variables=list(my_module.variables)tf.saved_model.save(to_save,"/tmp/example_saved_model")We now have a saved model in the/tmp/example_saved_modelfolder:$ls-lh/tmp/example_saved_model
total24K
drwxrwsr-t2tomhennigan1544320984.0KApr2800:14assets
-rw-rw-r--1tomhennigan15443209814KApr2800:15saved_model.pb
drwxrwsr-t2tomhennigan1544320984.0KApr2800:15variablesLoading this model is simple and can be done on a different machine without any
of the Python code that built the saved model:loaded=tf.saved_model.load("/tmp/example_saved_model")# Use the inference method. Note this doesn't run the Python code from `to_save`# but instead uses the TensorFlow Graph that is part of the saved model.loaded.inference(tf.ones([1,input_size]))# The all_variables property can be used to retrieve the restored variables.assertlen(loaded.all_variables)>0Note that the loaded object is not a Sonnet module, it is a container object
that has the specific methods (e.g.inference) and properties (e.g.all_variables) that we added in the previous block.Distributed trainingExample:https://github.com/deepmind/sonnet/blob/v2/examples/distributed_cifar10.ipynbSonnet has support for distributed training usingcustom TensorFlow distribution strategies.A key difference between Sonnet and distributed training usingtf.kerasis
that Sonnet modules and optimizers do not behave differently when run under
distribution strategies (e.g. we do not average your gradients or sync your
batch norm stats). We believe that users should be in full control of these
aspects of their training and they should not be baked into the library. The
trade off here is that you need to implement these features in your training
script (typically this is just 2 lines of code to all reduce your gradients
before applying your optimizer) or swap in modules that are explicitly
distribution aware (e.g.snt.distribute.CrossReplicaBatchNorm).Ourdistributed Cifar-10example walks through doing multi-GPU training with Sonnet.