# Migration guide¶

The goal of this section is to help with upgrading code that was written for an older version of NengoDL. Note that this is not a list of all the new features available in newer versions. Here we will only look at features that were present in older versions, and how they have changed.

See the release history for complete details on what has changed in each version.

## NengoDL 2 to 3¶

NengoDL 3 makes some significant changes to the API, mainly motivated by the release of TensorFlow 2.0. TensorFlow 2.0 adopts the Keras API as the standard high-level interface, so in NengoDL 3 we make the same change, modifying the API to better integrate with Keras.

### Simulator changes¶

**Use**`Simulator.fit`

**instead of**`Simulator.train`

.`Simulator.fit`

is the new access point for optimizing a NengoDL model. It is closely based on the Keras Model.fit function. One important difference between`fit`

and`train`

is that the optimizer and loss functions are specified in a separate`Simulator.compile`

step (analogous to Keras’ Model.compile) rather than directly in`Simulator.train`

. Another difference is that input and target data are specified in separate`x`

and`y`

arguments, rather than a single`data`

argument.Also note that you should use the updated TensorFlow 2.0 optimizers/loss functions in

`tf.optimizers`

and`tf.losses`

, rather than the deprecated optimizers in`tf.compat.v1.train`

.with nengo.Network() as example_net: node = nengo.Node([0]) ens = nengo.Ensemble(10, 1) nengo.Connection(node, ens, synapse=None) probe = nengo.Probe(ens)

NengoDL 2:

with nengo_dl.Simulator(example_net) as sim: sim.train( data={node: np.zeros((1, 1, 1)), probe: np.zeros((1, 1, 1))}, optimizer=tf.train.AdamOptimizer(0.01), objective=nengo_dl.objectives.mse, n_epochs=10, )

NengoDL 3:

with nengo_dl.Simulator(example_net) as sim: sim.compile(optimizer=tf.optimizers.Adam(0.01), loss=tf.losses.mse) sim.fit( x={node: np.zeros((1, 1, 1))}, y={probe: np.zeros((1, 1, 1))}, epochs=10 )

**Use**`Simulator.evaluate`

**instead of**`Simulator.loss`

. In the same way as`train`

is replaced by`fit`

,`loss`

is replaced by`evaluate`

, which is equivalent to the Keras Model.evaluate function. It differs from`loss`

in all the same ways (separate`compile`

step and independently specified inputs and targets).NengoDL 2:

with nengo_dl.Simulator(example_net) as sim: sim.loss( data={node: np.zeros((1, 1, 1)), probe: np.zeros((1, 1, 1))}, objective=nengo_dl.objectives.mse, )

NengoDL 3:

with nengo_dl.Simulator(example_net) as sim: sim.compile(loss=tf.losses.mse) sim.evaluate( x={node: np.zeros((1, 1, 1))}, y={probe: np.zeros((1, 1, 1))})

**Extra simulator steps will no longer be hidden**. When simulating a number of timesteps that is not evenly divisible by`Simulator.unroll_simulation`

, extra simulation steps will be executed (this is true in both 2 and 3). In NengoDL 2 these extra steps and any data associated with them were hidden from the user. In NengoDL 3 the number of steps executed is unchanged, but the simulation is now updated to reflect the number of steps that were actually executed (rather than the number the user requested).NengoDL 2:

with nengo_dl.Simulator(example_net, unroll_simulation=5) as sim: sim.run_steps(18) assert sim.n_steps == 18 assert len(sim.data[probe]) == 18

NengoDL 3:

with nengo_dl.Simulator(example_net, unroll_simulation=5) as sim: sim.run_steps(18) assert sim.n_steps == 20 assert len(sim.data[probe]) == 20

`Simulator.save_params`

**and**`Simulator.load_params`

**arguments**`include_global`

**and**`include_local`

**replaced with**`include_non_trainable`

. TensorFlow 2.0 removed the division of Variables into “global” and “local” collections. Instead, Keras organizes Variables according to whether they are trainable or not. Generally speaking, in NengoDL 2 global variables were trainable and local variables were not, so the two organization schemes are roughly equivalent. However, it is possible for users to manually create non-trainable global variables or trainable local variables, in which case these two organization schemes would not be equivalent.NengoDL 2:

with nengo_dl.Simulator(example_net) as sim: sim.save_params("trainable", include_global=True, include_local=False) sim.save_params("non_trainable", include_global=False, include_local=True) sim.save_params("both", include_global=True, include_local=True)

NengoDL 3:

with nengo_dl.Simulator(example_net) as sim: sim.save_params("trainable", include_non_trainable=False) sim.save_params("both", include_non_trainable=True)

Note that with the simplified single argument it is no longer possible to save only the non-trainable parameters. However, it is still possible to save these parameters manually if it is critical that trainable parameters not be included.

with nengo_dl.Simulator(example_net) as sim: np.savez_compressed( "non_trainable", *tf.keras.backend.batch_get_value(sim.keras_model.non_trainable_weights) )

**Rate/spiking neuron swapping is controlled by Keras**`learning_phase`

. In Nengo DL 2 and 3 spiking neuron models are automatically swapped for rate mode equivalents during training. However, sometimes it is useful to manually enable this swapping in other functions (for example, in order to evaluate the loss function on test data but with the swapped rate neuron models). There were a couple ways to do this in NengoDL 2; in NengoDL 3 it is all controlled through the Keras`learning_phase`

.NengoDL 2:

with nengo_dl.Simulator(example_net) as sim: sim.loss( data={node: np.zeros((1, 1, 1)), probe: np.zeros((1, 1, 1))}, objective=nengo_dl.objectives.mse, training=True, ) sim.run(1.0, extra_feeds={sim.tensor_graph.signals.training: True})

NengoDL 3:

with tf.keras.backend.learning_phase_scope(1): with nengo_dl.Simulator(example_net) as sim: sim.compile(loss=tf.losses.mse) sim.evaluate( x={node: np.zeros((1, 1, 1))}, y={probe: np.zeros((1, 1, 1))}) sim.run(1.0)

**TensorBoard functionality replaced by Keras TensorBoard callback**. NengoDL allows data about training metrics or model parameters to be output and displayed in TensorBoard. In TensorFlow 2.0 the recommended way of doing this is through Keras callbacks, and NengoDL 3 adopts the same API.NengoDL 2:

with nengo_dl.Simulator(example_net, tensorboard="results") as sim: sim.train( data={node: np.zeros((1, 1, 1)), probe: np.zeros((1, 1, 1))}, optimizer=tf.train.AdamOptimizer(0.01), objective=nengo_dl.objectives.mse, n_epochs=10, summaries=["loss", ens], )

NengoDL 3:

with nengo_dl.Simulator(example_net) as sim: sim.compile(optimizer=tf.optimizers.Adam(0.01), loss=tf.losses.mse) sim.fit( x={node: np.zeros((1, 1, 1))}, y={probe: np.zeros((1, 1, 1))}, epochs=10, callbacks=[ tf.keras.callbacks.TensorBoard(log_dir="results"), nengo_dl.callbacks.NengoSummaries("results", sim, [ens]), ] )

### TensorNode changes¶

**Use**`nengo_dl.Layer`

**instead of**`nengo_dl.tensor_layer`

.`nengo_dl.tensor_layer`

was designed to mimic the`tf.layers`

API. In TensorFlow 2.0`tf.layers`

has been deprecated in favour of`tf.keras.layers`

.`nengo_dl.Layer`

has the same functionality as`nengo_dl.tensor_layer`

, but mimics the Keras Layer API instead.NengoDL 2:

with nengo.Network(): layer = nengo_dl.tensor_layer(node, tf.layers.dense, units=10)

NengoDL 3:

with nengo.Network(): layer = nengo_dl.Layer(tf.keras.layers.Dense(units=10))(node)

**Use custom Keras Layers instead of callable classes**. When making more complicated TensorNodes we sometimes need to separate the layer logic into separate preparation and execution steps. In NengoDL 2 this was done by creating a callable class that defined`pre_build`

,`__call__`

, and`post_build`

functions. In NengoDL 3 this is done by creating a custom Keras Layer subclass instead, which can define`build`

and`call`

methods. There is no longer a`post_build`

step, as this was used for TensorNodes that needed access to the TensorFlow Session object (which is no longer used in TensorFlow 2.0).NengoDL 2:

class MyLayer: def pre_build(self, shape_in, shape_out): self.w = tf.Variable(tf.ones((1,))) def __call__(self, t): return t * self.weights with nengo.Network(): tensor_node = nengo_dl.TensorNode(MyLayer())

NengoDL 3:

class MyLayer(tf.keras.layers.Layer): def build(self, input_shapes): self.w = self.add_weight( shape=(1,), initializer=tf.initializers.ones(), ) def call(self, inputs): return inputs * self.weights with nengo.Network(): tensor_node = nengo_dl.TensorNode(MyLayer())

**TensorNodes define multidimensional**`shape_in`

/`shape_out`

**rather than scalar**`size_in`

/`size_out`

. In core Nengo all inputs and outputs are vectors, and in NengoDL 2 this was also true for`TensorNodes`

. However, often when working with`TensorNodes`

it is useful to have multidimensional inputs and outputs, so in NengoDL 3 TensorNodes are defined with a full shape. Note that these shapes do not include the batch dimension (which is defined when the`Simulator`

is created).NengoDL 2:

def my_func(t, x): assert t.shape == () assert x.shape == (1, 24) return tf.reshape(x, (1, 2, 3, 4)) with nengo.Network(): tensor_node = nengo_dl.TensorNode(my_func, size_in=24, size_out=24)

NengoDL 3:

def my_func(t, x): assert t.shape == () assert x.shape == (1, 2, 12) return tf.reshape(x, (1, 2, 3, 4)) with nengo.Network(): tensor_node = nengo_dl.TensorNode( my_func, shape_in=(2, 12), shape_out=(2, 3, 4))

**Connections created by**`nengo_dl.Layer`

**are non-trainable by default**. We usually don’t want these Connections to contain trainable weights (since any weights we want would be built into the TensorNode). In NengoDL 2 they needed to be manually marked as non-trainable, but that is the default behaviour in NengoDL 3.NengoDL 2:

with nengo.Network() as net: nengo_dl.configure_settings(trainable=None) layer, conn = nengo_dl.tensor_layer( node, tf.layers.dense, units=10, return_conn=True) net.config[conn].trainable = False

NengoDL 3:

with nengo.Network() as net: layer = nengo_dl.Layer(tf.keras.layers.Dense(units=10))(node)

The connection can still be manually marked as trainable if desired:

with nengo.Network() as net: nengo_dl.configure_settings(trainable=None) layer, conn = nengo_dl.Layer(tf.keras.layers.Dense(units=10))( node, return_conn=True) net.config[conn].trainable = True

### nengo_dl.objectives changes¶

`nengo_dl.objectives`

**renamed to**`nengo_dl.losses`

. This is for consistency with`tf.losses`

/`tf.keras.losses`

.**Loss functions take two arguments**`(y_true, y_pred)`

**instead of**`(outputs, targets)`

. Again this is for consistency with`tf.losses`

. Note that this swaps the order of the two arguments (so the ground truth now comes first).NengoDL 2:

def my_loss(outputs, targets): return outputs - targets

NengoDL 3:

def my_loss(y_true, y_pred): return y_pred - y_true

`nengo_dl.losses.Regularize`

**accepts two arguments**(`y_true`

**and**`y_pred`

)**instead of just**`outputs`

.`y_true`

is not used, but Keras requires all loss functions to accept two arguments regardless.NengoDL 2:

nengo_dl.objectives.Regularize()(tf.ones((1, 2, 3)))

NengoDL 3:

nengo_dl.losses.Regularize()(None, tf.ones((1, 2, 3)))

**Use**`loss_weights`

**parameter in**`Simulator.compile`

**instead of**`weight`

**parameter in**`nengo_dl.losses.Regularize`

.with example_net: p0 = nengo.Probe(node) p1 = nengo.Probe(ens)

NengoDL 2:

with nengo_dl.Simulator(example_net) as sim: sim.train( data={node: np.zeros((1, 1, 1)), probe: np.zeros((1, 1, 1))}, optimizer=tf.train.AdamOptimizer(0.01), objective={ probe: nengo_dl.objectives.mse, p0: nengo_dl.objectives.Regularize(weight=0.5), p1: nengo_dl.objectives.Regularize(weight=0.5), }, n_epochs=10, )

NengoDL 3:

with nengo_dl.Simulator(example_net) as sim: sim.compile( optimizer=tf.optimizers.Adam(0.01), loss={ probe: tf.losses.mse, p0: nengo_dl.losses.Regularize(), p1: nengo_dl.losses.Regularize(), }, loss_weights={probe: 1, p0: 0.5, p1: 0.5}, ) sim.fit( x={node: np.zeros((1, 1, 1))}, y={ probe: np.zeros((1, 1, 1)), p0: np.zeros((1, 1, 1)), p1: np.zeros((1, 1, 1)), }, epochs=10, )

`nengo_dl.objectives.mse`

**renamed to**`nengo_dl.losses.nan_mse`

. This is to distinguish it from the standard`tf.losses.mse`

, and emphasize the special treatment of`nan`

targets.NengoDL 2:

assert nengo_dl.objectives.mse(np.zeros((2, 3)), np.ones((2, 3)) * np.nan) == 0

NengoDL 3:

assert nengo_dl.losses.nan_mse(np.ones((2, 3)) * np.nan, np.zeros((2, 3))) == 0

### configure_settings changes¶

**Specify**`dtype`

**as string instead of**`tf.Dtype`

.NengoDL 2:

with nengo.Network(): nengo_dl.configure_settings(dtype=tf.float32)

NengoDL 3:

with nengo.Network(): nengo_dl.configure_settings(dtype="float32")

**Configure trainability separately within subnetworks, rather than marking networks as trainable**.NengoDL 2:

with nengo.Network() as net: nengo_dl.configure_settings(trainable=None) with nengo.Network() as subnet: ens = nengo.Ensemble(10, 1) net.config[subnet].trainable = False

NengoDL 3:

with nengo.Network() as net: with nengo.Network() as subnet: nengo_dl.configure_settings(trainable=False) ens = nengo.Ensemble(10, 1)

**Use**`tf.config`

**instead of**`session_config`

. TensorFlow 2.0 uses functions in the`tf.config`

namespace to control settings that used to be controlled through the SessionConfig object (which no longer exists). So we no longer need the`session_config`

option, and can instead just directly use those`tf.config`

functions.NengoDL 2:

with nengo.Network(): nengo_dl.configure_settings(session_config={"allow_soft_placement": True})

NengoDL 3:

tf.config.set_soft_device_placement(True)