# Copyright 2015 The TensorFlow Authors. All Rights Reserved.

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

# ==============================================================================

"""Wrappers for primitive Neural Net (NN) Operations."""

from __future__ import absolute_import

from __future__ import division

from __future__ import print_function

import numbers

import numpy as np

from tensorflow.python.framework import dtypes

from tensorflow.python.framework import graph_util

from tensorflow.python.framework import ops

from tensorflow.python.framework import tensor_shape

from tensorflow.python.framework import tensor_util

from tensorflow.python.ops import array_ops

from tensorflow.python.ops import gen_nn_ops

from tensorflow.python.ops import math_ops

from tensorflow.python.ops import random_ops

# go/tf-wildcard-import

# pylint: disable=wildcard-import

from tensorflow.python.ops.gen_nn_ops import *

# pylint: enable=wildcard-import

# Aliases for some automatically-generated names.

local_response_normalization = gen_nn_ops.lrn

def _non_atrous_convolution(input, filter, padding, data_format=None, # pylint: disable=redefined-builtin

strides=None, name=None):

"""Computes sums of N-D convolutions (actually cross correlation).

It is required that 1 <= N <= 3.

This is used to implement the more generic `convolution` function, which

extends the interface of this function with a `dilation_rate` parameter.

Args:

input: Rank N+2 tensor of type T of shape

`[batch_size] + input_spatial_shape + [in_channels]` if `data_format`

does not start with `"NC"`, or

`[batch_size, in_channels] + input_spatial_shape` if `data_format` starts

with `"NC"`.

filter: Rank N+2 tensor of type T of shape

`filter_spatial_shape + [in_channels, out_channels]`. Rank of either

`input` or `filter` must be known.

padding: Padding method to use, must be either "VALID" or "SAME".

data_format: A string or None. Specifies whether the channel dimension of

the `input` and output is the last dimension (default, or if `data_format`

does not start with "NC"), or the second dimension (if `data_format`

starts with "NC"). For N=1, the valid values are "NWC" (default) and

"NCW". For N=2, the valid values are "NHWC" (default) and "NCHW". For

N=3, the valid value is "NDHWC".

strides: Sequence of N positive integers, defaults to `[1] * N`.

name: Name prefix to use.

Returns:

Rank N+2 tensor of type T of shape

`[batch_size] + output_spatial_shape + [out_channels]`, where

if padding == "SAME":

output_spatial_shape = input_spatial_shape

if padding == "VALID":

output_spatial_shape = input_spatial_shape - filter_spatial_shape + 1.

Raises:

ValueError: if ranks are incompatible.

"""

with ops.name_scope(name, "non_atrous_convolution", [input, filter]) as scope:

input = ops.convert_to_tensor(input, name="input")

filter = ops.convert_to_tensor(filter, name="filter")

filter_shape = filter.get_shape().with_rank(input.get_shape().ndims)

input_shape = input.get_shape().with_rank(filter_shape.ndims)

if input_shape.ndims is None:

raise ValueError("Rank of convolution must be known")

if input_shape.ndims < 3 or input_shape.ndims > 5:

raise ValueError(

"`input` and `filter` must have rank at least 3 and at most 5")

conv_dims = input_shape.ndims - 2

if strides is None:

strides = [1] * conv_dims

elif len(strides) != conv_dims:

raise ValueError("len(strides)=%d, but should be %d" %

(len(strides), conv_dims))

if conv_dims == 1:

# conv1d uses the 2-d data format names

if data_format is None or data_format == "NWC":

data_format_2d = "NHWC"

elif data_format == "NCW":

data_format_2d = "NCHW"

else:

raise ValueError("data_format must be \"NWC\" or \"NCW\".")

return conv1d(

value=input,

filters=filter,

stride=strides[0],

padding=padding,

data_format=data_format_2d,

name=scope)

elif conv_dims == 2:

if data_format is None or data_format == "NHWC":

data_format = "NHWC"

strides = [1] + list(strides) + [1]

elif data_format == "NCHW":

strides = [1, 1] + list(strides)

else:

raise ValueError("data_format must be \"NHWC\" or \"NCHW\".")

return gen_nn_ops.conv2d(

input=input,

filter=filter,

strides=strides,

padding=padding,

data_format=data_format,

name=name)

elif conv_dims == 3:

if data_format is None or data_format == "NDHWC":

strides = [1] + list(strides) + [1]

else:

raise ValueError("data_format must be \"NDHWC\".")

return gen_nn_ops.conv3d(

input=input,

filter=filter,

strides=strides,

padding=padding,

name=name)

def with_space_to_batch(

input, # pylint: disable=redefined-builtin

dilation_rate,

padding,

op,

filter_shape=None,

spatial_dims=None,

data_format=None):

"""Performs `op` on the space-to-batch representation of `input`.

This has the effect of transforming sliding window operations into the

corresponding "atrous" operation in which the input is sampled at the

specified `dilation_rate`.

In the special case that `dilation_rate` is uniformly 1, this simply returns:

op(input, num_spatial_dims, padding)

Otherwise, it returns:

batch_to_space_nd(

op(space_to_batch_nd(input, adjusted_dilation_rate, adjusted_paddings),

num_spatial_dims,

"VALID")

adjusted_dilation_rate,

adjusted_crops),

where:

adjusted_dilation_rate is an int64 tensor of shape [max(spatial_dims)],

adjusted_{paddings,crops} are int64 tensors of shape [max(spatial_dims), 2]

defined as follows:

We first define two int64 tensors `paddings` and `crops` of shape

`[num_spatial_dims, 2]` based on the value of `padding` and the spatial

dimensions of the `input`:

If `padding = "VALID"`, then:

paddings, crops = required_space_to_batch_paddings(

input_shape[spatial_dims],

dilation_rate)

If `padding = "SAME"`, then:

dilated_filter_shape =

filter_shape + (filter_shape - 1) * (dilation_rate - 1)

paddings, crops = required_space_to_batch_paddings(

input_shape[spatial_dims],

dilation_rate,

[(dilated_filter_shape - 1) // 2,

dilated_filter_shape - 1 - (dilated_filter_shape - 1) // 2])

Because `space_to_batch_nd` and `batch_to_space_nd` assume that the spatial

dimensions are contiguous starting at the second dimension, but the specified

`spatial_dims` may not be, we must adjust `dilation_rate`, `paddings` and

`crops` in order to be usable with these operations. For a given dimension,

if the block size is 1, and both the starting and ending padding and crop

amounts are 0, then space_to_batch_nd effectively leaves that dimension alone,

which is what is needed for dimensions not part of `spatial_dims`.

Furthermore, `space_to_batch_nd` and `batch_to_space_nd` handle this case

efficiently for any number of leading and trailing dimensions.

For 0 <= i < len(spatial_dims), we assign:

adjusted_dilation_rate[spatial_dims[i] - 1] = dilation_rate[i]

adjusted_paddings[spatial_dims[i] - 1, :] = paddings[i, :]

adjusted_crops[spatial_dims[i] - 1, :] = crops[i, :]

All unassigned values of `adjusted_dilation_rate` default to 1, while all

unassigned values of `adjusted_paddings` and `adjusted_crops` default to 0.

Note in the case that `dilation_rate` is not uniformly 1, specifying "VALID"

padding is equivalent to specifying `padding = "SAME"` with a filter_shape of

`[1]*N`.

Advanced usage. Note the following optimization: A sequence of

`with_space_to_batch` operations with identical (not uniformly 1)

`dilation_rate` parameters and "VALID" padding

net = with_space_to_batch(net, dilation_rate, "VALID", op_1)

...

net = with_space_to_batch(net, dilation_rate, "VALID", op_k)

can be combined into a single `with_space_to_batch` operation as follows:

def combined_op(converted_input, num_spatial_dims, _):

result = op_1(converted_input, num_spatial_dims, "VALID")

...

result = op_k(result, num_spatial_dims, "VALID")

net = with_space_to_batch(net, dilation_rate, "VALID", combined_op)

This eliminates the overhead of `k-1` calls to `space_to_batch_nd` and

`batch_to_space_nd`.

Similarly, a sequence of `with_space_to_batch` operations with identical (not

uniformly 1) `dilation_rate` parameters, "SAME" padding, and odd filter

dimensions

net = with_space_to_batch(net, dilation_rate, "SAME", op_1, filter_shape_1)

...

net = with_space_to_batch(net, dilation_rate, "SAME", op_k, filter_shape_k)

can be combined into a single `with_space_to_batch` operation as follows:

def combined_op(converted_input, num_spatial_dims, _):

result = op_1(converted_input, num_spatial_dims, "SAME")

...

result = op_k(result, num_spatial_dims, "SAME")

net = with_space_to_batch(net, dilation_rate, "VALID", combined_op)

Args:

input: Tensor of rank > max(spatial_dims).

dilation_rate: int32 Tensor of *known* shape [num_spatial_dims].

padding: str constant equal to "VALID" or "SAME"

op: Function that maps (input, num_spatial_dims, padding) -> output

filter_shape: If padding = "SAME", specifies the shape of the convolution

kernel/pooling window as an integer Tensor of shape [>=num_spatial_dims].

If padding = "VALID", filter_shape is ignored and need not be specified.

spatial_dims: Monotonically increasing sequence of `num_spatial_dims`

integers (which are >= 1) specifying the spatial dimensions of `input`

and output. Defaults to: `range(1, num_spatial_dims+1)`.

data_format: A string or None. Specifies whether the channel dimension of

the `input` and output is the last dimension (default, or if `data_format`

does not start with "NC"), or the second dimension (if `data_format`

starts with "NC"). For N=1, the valid values are "NWC" (default) and

"NCW". For N=2, the valid values are "NHWC" (default) and "NCHW". For

N=3, the valid value is "NDHWC".

Returns:

The output Tensor as described above.

Raises:

ValueError: if `padding` is invalid or the arguments are incompatible.

ValueError: if `spatial_dims` are invalid.

"""

input = ops.convert_to_tensor(input, name="input")

dilation_rate = ops.convert_to_tensor(dilation_rate,

dtypes.int32,

name="dilation_rate")

try:

rate_shape = dilation_rate.get_shape().with_rank(1)

except ValueError:

raise ValueError("rate must be rank 1")

if not dilation_rate.get_shape().is_fully_defined():

raise ValueError("rate must have known shape")

num_spatial_dims = rate_shape[0].value

if data_format is not None and data_format.startswith("NC"):

starting_spatial_dim = 2

else:

starting_spatial_dim = 1

if spatial_dims is None:

spatial_dims = range(starting_spatial_dim,

num_spatial_dims + starting_spatial_dim)

orig_spatial_dims = list(spatial_dims)

spatial_dims = sorted(set(int(x) for x in orig_spatial_dims))

if spatial_dims != orig_spatial_dims or any(x < 1 for x in spatial_dims):

raise ValueError(

"spatial_dims must be a montonically increasing sequence of positive "

"integers") # pylint: disable=line-too-long

if data_format is not None and data_format.startswith("NC"):

expected_input_rank = spatial_dims[-1]

else:

expected_input_rank = spatial_dims[-1] + 1

try:

input.get_shape().with_rank_at_least(expected_input_rank)

except ValueError:

ValueError("input tensor must have rank %d at least" %

(expected_input_rank))

const_rate = tensor_util.constant_value(dilation_rate)

rate_or_const_rate = dilation_rate

if const_rate is not None:

rate_or_const_rate = const_rate

if np.any(const_rate < 1):

raise ValueError("dilation_rate must be positive")

if np.all(const_rate == 1):

return op(input, num_spatial_dims, padding)

# We have two padding contributions. The first is used for converting "SAME"

# to "VALID". The second is required so that the height and width of the

# zero-padded value tensor are multiples of rate.

# Padding required to reduce to "VALID" convolution

if padding == "SAME":

if filter_shape is None:

raise ValueError("filter_shape must be specified for SAME padding")

filter_shape = ops.convert_to_tensor(filter_shape, name="filter_shape")

const_filter_shape = tensor_util.constant_value(filter_shape)

if const_filter_shape is not None:

filter_shape = const_filter_shape

# Spatial dimensions of the filters and the upsampled filters in which we

# introduce (rate - 1) zeros between consecutive filter values.

filter_spatial_shape = filter_shape[:num_spatial_dims]

dilated_filter_spatial_shape = (filter_spatial_shape +

(filter_spatial_shape - 1) *

(rate_or_const_rate - 1))

pad_extra_shape = dilated_filter_spatial_shape - 1

# When full_padding_shape is odd, we pad more at end, following the same

# convention as conv2d.

pad_extra_start = pad_extra_shape // 2

pad_extra_end = pad_extra_shape - pad_extra_start

base_paddings = array_ops.stack([[pad_extra_start[i], pad_extra_end[i]]

for i in range(num_spatial_dims)])

elif padding == "VALID":

base_paddings = np.zeros([num_spatial_dims, 2], np.int32)

else:

raise ValueError("Invalid padding method %r" % padding)

# Handle input whose shape is unknown during graph creation.

input_spatial_shape = None

if input.get_shape().ndims is not None:

input_shape_list = input.get_shape().as_list()

input_spatial_shape = [input_shape_list[i] for i in spatial_dims]

if input_spatial_shape is None or None in input_spatial_shape:

input_spatial_shape = array_ops.gather(array_ops.shape(input), spatial_dims)

paddings, crops = array_ops.required_space_to_batch_paddings(

input_shape=input_spatial_shape,

base_paddings=base_paddings,

block_shape=dilation_rate)

def adjust(orig, fill_value):

"""Returns an `adjusted` version of `orig` based on `spatial_dims`.

Tensor of the same type as `orig` and with shape

`[max(spatial_dims), ...]` where:

adjusted[spatial_dims[i] - 1, ...] = orig[i, ...]

for 0 <= i < len(spatial_dims), and

adjusted[j, ...] = fill_value

for j != spatial_dims[i] - 1 for some i.

If `orig` is a constant value, then the result will be a constant value.

Args:

orig: Tensor of rank > max(spatial_dims).

fill_value: Numpy scalar (of same data type as `orig) specifying the fill

value for non-spatial dimensions.

Returns:

`adjusted` tensor.

"""

fill_dims = orig.get_shape().as_list()[1:]

dtype = orig.dtype.as_numpy_dtype

parts = []

const_orig = tensor_util.constant_value(orig)

const_or_orig = const_orig if const_orig is not None else orig

prev_spatial_dim = 0

i = 0

while i < len(spatial_dims):

start_i = i

start_spatial_dim = spatial_dims[i]

if start_spatial_dim > 1:

# Fill in any gap from the previous spatial dimension (or dimension 1 if

# this is the first spatial dimension) with `fill_value`.

parts.append(

np.full(

[start_spatial_dim - 1 - prev_spatial_dim] + fill_dims,

fill_value,

dtype=dtype))

# Find the largest value of i such that:

# [spatial_dims[start_i], ..., spatial_dims[i]]

# == [start_spatial_dim, ..., start_spatial_dim + i - start_i],

# i.e. the end of a contiguous group of spatial dimensions.

while (i + 1 < len(spatial_dims) and

spatial_dims[i + 1] == spatial_dims[i] + 1):

i += 1

parts.append(const_or_orig[start_i:i + 1])

prev_spatial_dim = spatial_dims[i]

i += 1

if const_orig is not None:

return np.concatenate(parts)

else:

return array_ops.concat(parts, 0)

dilation_rate = adjust(dilation_rate, 1)

paddings = adjust(paddings, 0)

crops = adjust(crops, 0)

input_converted = array_ops.space_to_batch_nd(

input=input,

block_shape=dilation_rate,

paddings=paddings)

result = op(input_converted, num_spatial_dims, "VALID")

result_converted = array_ops.batch_to_space_nd(

input=result, block_shape=dilation_rate, crops=crops)

return result_converted

def _get_strides_and_dilation_rate(num_spatial_dims, strides, dilation_rate):

"""Helper function for verifying strides and dilation_rate arguments.

This is used by `convolution` and `pool`.

Args:

num_spatial_dims: int

strides: Optional. List of N ints >= 1. Defaults to [1]*N. If any value

of strides is > 1, then all values of dilation_rate must be 1.

dilation_rate: Optional. List of N ints >= 1. Defaults to [1]*N. If any

value of dilation_rate is > 1, then all values of strides must be 1.

Returns:

Normalized (strides, dilation_rate) as int32 numpy arrays of shape

[num_spatial_dims].

Raises:

ValueError: if the parameters are invalid.

"""

if dilation_rate is None:

dilation_rate = [1] * num_spatial_dims

elif len(dilation_rate) != num_spatial_dims:

raise ValueError("len(dilation_rate)=%d but should be %d" %

(len(dilation_rate), num_spatial_dims))

dilation_rate = np.array(dilation_rate, dtype=np.int32)

if np.any(dilation_rate < 1):

raise ValueError("all values of dilation_rate must be positive")

if strides is None:

strides = [1] * num_spatial_dims

elif len(strides) != num_spatial_dims:

raise ValueError("len(strides)=%d but should be %d" %

(len(strides), num_spatial_dims))

strides = np.array(strides, dtype=np.int32)

if np.any(strides < 1):

raise ValueError("all values of strides must be positive")

if np.any(strides > 1) and np.any(dilation_rate > 1):

raise ValueError(

"strides > 1 not supported in conjunction with dilation_rate > 1")

return strides, dilation_rate

def convolution(input, filter, # pylint: disable=redefined-builtin

padding, strides=None, dilation_rate=None,

name=None, data_format=None):

# pylint: disable=line-too-long

"""Computes sums of N-D convolutions (actually cross-correlation).

This also supports either output striding via the optional `strides` parameter

or atrous convolution (also known as convolution with holes or dilated

convolution, based on the French word "trous" meaning holes in English) via

the optional `dilation_rate` parameter. Currently, however, output striding

is not supported for atrous convolutions.

Specifically, in the case that `data_format` does not start with "NC", given

a rank (N+2) `input` Tensor of shape

[num_batches,

input_spatial_shape[0],

...,

input_spatial_shape[N-1],

num_input_channels],

a rank (N+2) `filter` Tensor of shape

[spatial_filter_shape[0],

...,

spatial_filter_shape[N-1],

num_input_channels,

num_output_channels],

an optional `dilation_rate` tensor of shape [N] (defaulting to [1]*N)

specifying the filter upsampling/input downsampling rate, and an optional list

of N `strides` (defaulting [1]*N), this computes for each N-D spatial output

position (x[0], ..., x[N-1]):

```

output[b, x[0], ..., x[N-1], k] =

sum_{z[0], ..., z[N-1], q}

filter[z[0], ..., z[N-1], q, k] *

padded_input[b,

x[0]*strides[0] + dilation_rate[0]*z[0],

...,

x[N-1]*strides[N-1] + dilation_rate[N-1]*z[N-1],

q]

```

where `padded_input` is obtained by zero padding the input using an effective

spatial filter shape of `(spatial_filter_shape-1) * dilation_rate + 1` and

output striding `strides` as described in the

@{tf.nn.convolution$comment here}.

In the case that `data_format` does start with `"NC"`, the `input` and output

(but not the `filter`) are simply transposed as follows:

convolution(input, data_format, **kwargs) =

tf.transpose(convolution(tf.transpose(input, [0] + range(2,N+2) + [1]),

**kwargs),

[0, N+1] + range(1, N+1))

It is required that 1 <= N <= 3.

Args:

input: An N-D `Tensor` of type `T`, of shape

`[batch_size] + input_spatial_shape + [in_channels]` if data_format does

not start with "NC" (default), or

`[batch_size, in_channels] + input_spatial_shape` if data_format starts

with "NC".

filter: An N-D `Tensor` with the same type as `input` and shape

`spatial_filter_shape + [in_channels, out_channels]`.

padding: A string, either `"VALID"` or `"SAME"`. The padding algorithm.

strides: Optional. Sequence of N ints >= 1. Specifies the output stride.

Defaults to [1]*N. If any value of strides is > 1, then all values of

dilation_rate must be 1.

dilation_rate: Optional. Sequence of N ints >= 1. Specifies the filter

upsampling/input downsampling rate. In the literature, the same parameter

is sometimes called `input stride` or `dilation`. The effective filter

size used for the convolution will be `spatial_filter_shape +

(spatial_filter_shape - 1) * (rate - 1)`, obtained by inserting

(dilation_rate[i]-1) zeros between consecutive elements of the original

filter in each spatial dimension i. If any value of dilation_rate is > 1,

then all values of strides must be 1.

name: Optional name for the returned tensor.

data_format: A string or None. Specifies whether the channel dimension of

the `input` and output is the last dimension (default, or if `data_format`

does not start with "NC"), or the second dimension (if `data_format`

starts with "NC"). For N=1, the valid values are "NWC" (default) and

"NCW". For N=2, the valid values are "NHWC" (default) and "NCHW". For

N=3, the valid value is "NDHWC".

Returns:

A `Tensor` with the same type as `input` of shape

`[batch_size] + output_spatial_shape + [out_channels]`

if data_format is None or does not start with "NC", or

`[batch_size, out_channels] + output_spatial_shape`

if data_format starts with "NC",

where `output_spatial_shape` depends on the value of `padding`.

If padding == "SAME":

output_spatial_shape[i] = ceil(input_spatial_shape[i] / strides[i])

If padding == "VALID":

output_spatial_shape[i] =

ceil((input_spatial_shape[i] -

(spatial_filter_shape[i]-1) * dilation_rate[i])

/ strides[i]).

Raises:

ValueError: If input/output depth does not match `filter` shape, if padding

is other than `"VALID"` or `"SAME"`, or if data_format is invalid.

"""

# pylint: enable=line-too-long

with ops.name_scope(name, "convolution", [input, filter]) as name:

input = ops.convert_to_tensor(input, name="input")

filter = ops.convert_to_tensor(filter, name="filter")

num_total_dims = filter.get_shape().ndims

if num_total_dims is None:

num_total_dims = input.get_shape().ndims

if num_total_dims is None:

raise ValueError("rank of input or filter must be known")

num_spatial_dims = num_total_dims - 2

try:

input.get_shape().with_rank(num_spatial_dims + 2)

except ValueError:

ValueError("input tensor must have rank %d" % (num_spatial_dims + 2))

try:

filter.get_shape().with_rank(num_spatial_dims + 2)

except ValueError:

ValueError("filter tensor must have rank %d" % (num_spatial_dims + 2))

if data_format is None or not data_format.startswith("NC"):

input_channels_dim = input.get_shape()[num_spatial_dims + 1]

spatial_dims = range(1, num_spatial_dims+1)

else:

input_channels_dim = input.get_shape()[1]

spatial_dims = range(2, num_spatial_dims+2)

if not input_channels_dim.is_compatible_with(filter.get_shape()[

num_spatial_dims]):

raise ValueError(

"number of input channels does not match corresponding dimension of filter, "

"{} != {}".format(input_channels_dim, filter.get_shape()[

num_spatial_dims]))

strides, dilation_rate = _get_strides_and_dilation_rate(

num_spatial_dims, strides, dilation_rate)

def op(input_converted, _, padding):

return _non_atrous_convolution(

input=input_converted,

filter=filter,

padding=padding,

data_format=data_format,

strides=strides,

name=name)

return with_space_to_batch(

input=input,

filter_shape=array_ops.shape(filter),

spatial_dims=spatial_dims,

dilation_rate=dilation_rate,

padding=padding,

op=op)

def pool(input, # pylint: disable=redefined-builtin

window_shape,

pooling_type,

padding,

dilation_rate=None,

strides=None,

name=None,

data_format=None):

# pylint: disable=line-too-long

"""Performs an N-D pooling operation.

In the case that `data_format` does not start with "NC", computes for

0 <= b < batch_size,

0 <= x[i] < output_spatial_shape[i],

0 <= c < num_channels:

```

output[b, x[0], ..., x[N-1], c] =

REDUCE_{z[0], ..., z[N-1]}

input[b,

x[0] * strides[0] - pad_before[0] + dilation_rate[0]*z[0],

...

x[N-1]*strides[N-1] - pad_before[N-1] + dilation_rate[N-1]*z[N-1],

c],

```

where the reduction function REDUCE depends on the value of `pooling_type`,

and pad_before is defined based on the value of `padding` as described in the

@{tf.nn.convolution$comment here}.

The reduction never includes out-of-bounds positions.

In the case that `data_format` starts with `"NC"`, the `input` and output are

simply transposed as follows:

```

pool(input, data_format, **kwargs) =

tf.transpose(pool(tf.transpose(input, [0] + range(2,N+2) + [1]),

**kwargs),

[0, N+1] + range(1, N+1))

```

Args:

input: Tensor of rank N+2, of shape

`[batch_size] + input_spatial_shape + [num_channels]` if data_format does

not start with "NC" (default), or

`[batch_size, num_channels] + input_spatial_shape` if data_format starts

with "NC". Pooling happens over the spatial dimensions only.

window_shape: Sequence of N ints >= 1.

pooling_type: Specifies pooling operation, must be "AVG" or "MAX".

padding: The padding algorithm, must be "SAME" or "VALID".

See the @{tf.nn.convolution$comment here}

dilation_rate: Optional. Dilation rate. List of N ints >= 1.

Defaults to [1]*N. If any value of dilation_rate is > 1, then all values

of strides must be 1.

strides: Optional. Sequence of N ints >= 1. Defaults to [1]*N.

If any value of strides is > 1, then all values of dilation_rate must be

1.

name: Optional. Name of the op.

data_format: A string or None. Specifies whether the channel dimension of

the `input` and output is the last dimension (default, or if `data_format`

does not start with "NC"), or the second dimension (if `data_format`

starts with "NC"). For N=1, the valid values are "NWC" (default) and

"NCW". For N=2, the valid values are "NHWC" (default) and "NCHW". For

N=3, the valid value is "NDHWC".

Returns:

Tensor of rank N+2, of shape

[batch_size] + output_spatial_shape + [num_channels]

if data_format is None or does not start with "NC", or

[batch_size, num_channels] + output_spatial_shape

if data_format starts with "NC",

where `output_spatial_shape` depends on the value of padding:

If padding = "SAME":

output_spatial_shape[i] = ceil(input_spatial_shape[i] / strides[i])

If padding = "VALID":

output_spatial_shape[i] =

ceil((input_spatial_shape[i] - (window_shape[i] - 1) * dilation_rate[i])

/ strides[i]).

Raises:

ValueError: if arguments are invalid.

"""

# pylint: enable=line-too-long

with ops.name_scope(name, "%s_pool" %

(pooling_type.lower()), [input]) as scope:

input = ops.convert_to_tensor(input, name="input")

num_spatial_dims = len(window_shape)

if num_spatial_dims < 1 or num_spatial_dims > 3:

raise ValueError("It is required that 1 <= num_spatial_dims <= 3.")

input.get_shape().with_rank(num_spatial_dims + 2)

strides, dilation_rate = _get_strides_and_dilation_rate(

num_spatial_dims, strides, dilation_rate)

if padding == "SAME" and np.any(dilation_rate > 1):

raise ValueError(

"pooling with SAME padding is not implemented for dilation_rate > 1")

if np.any(strides > window_shape):

raise ValueError(

"strides > window_shape not supported due to inconsistency between "

"CPU and GPU implementations")

pooling_ops = {("MAX", 1): max_pool,

("MAX", 2): max_pool,

("MAX", 3): max_pool3d, # pylint: disable=undefined-variable

("AVG", 1): avg_pool,

("AVG", 2): avg_pool,

("AVG", 3): avg_pool3d, # pylint: disable=undefined-variable

}

op_key = (pooling_type, num_spatial_dims)

if op_key not in pooling_ops:

raise ValueError("%d-D %s pooling is not supported." %

(op_key[1], op_key[0]))

if data_format is None or not data_format.startswith("NC"):

adjusted_window_shape = [1] + list(window_shape) + [1]

adjusted_strides = [1] + list(strides) + [1]

spatial_dims = range(1, num_spatial_dims + 1)

else:

adjusted_window_shape = [1, 1] + list(window_shape)

adjusted_strides = [1, 1] + list(strides)

spatial_dims = range(2, num_spatial_dims + 2)

if num_spatial_dims == 3:

if data_format is not None and data_format != "NDHWC":

raise ValueError("data_format must be \"NDHWC\".")

data_format_kwargs = dict()

elif num_spatial_dims == 1:

if data_format is None or data_format == "NWC":

data_format_kwargs = dict(data_format="NHWC")

elif data_format == "NCW":

data_format_kwargs = dict(data_format="NCHW")

else:

raise ValueError("data_format must be either \"NWC\" or \"NCW\".")

adjusted_window_shape = [1] + adjusted_window_shape

adjusted_strides = [1] + adjusted_strides

else:

data_format_kwargs = dict(data_format=data_format)

def op(converted_input, _, converted_padding): # pylint: disable=missing-docstring

if num_spatial_dims == 1:

converted_input = array_ops.expand_dims(converted_input,

spatial_dims[0])

result = pooling_ops[op_key](converted_input,

adjusted_window_shape,

adjusted_strides,

converted_padding,

name=scope,

**data_format_kwargs)

if num_spatial_dims == 1:

result = array_ops.squeeze(result, [spatial_dims[0]])

return result

return with_space_to_batch(

input=input,

dilation_rate=dilation_rate,

padding=padding,

op=op,

spatial_dims=spatial_dims,

filter_shape=window_shape)

def atrous_conv2d(value, filters, rate, padding, name=None):

"""Atrous convolution (a.k.a. convolution with holes or dilated convolution).

Computes a 2-D atrous convolution, also known as convolution with holes or

dilated convolution, given 4-D `value` and `filters` tensors. If the `rate`

parameter is equal to one, it performs regular 2-D convolution. If the `rate`

parameter is greater than one, it performs convolution with holes, sampling

the input values every `rate` pixels in the `height` and `width` dimensions.

This is equivalent to convolving the input with a set of upsampled filters,

produced by inserting `rate - 1` zeros between two consecutive values of the

filters along the `height` and `width` dimensions, hence the name atrous

convolution or convolution with holes (the French word trous means holes in

English).

More specifically:

output[b, i, j, k] = sum_{di, dj, q} filters[di, dj, q, k] *

value[b, i + rate * di, j + rate * dj, q]

Atrous convolution allows us to explicitly control how densely to compute

feature responses in fully convolutional networks. Used in conjunction with

bilinear interpolation, it offers an alternative to `conv2d_transpose` in

dense prediction tasks such as semantic image segmentation, optical flow

computation, or depth estimation. It also allows us to effectively enlarge

the field of view of filters without increasing the number of parameters or

the amount of computation.

For a description of atrous convolution and how it can be used for dense

feature extraction, please see: [Semantic Image Segmentation with Deep

Convolutional Nets and Fully Connected CRFs](http://arxiv.org/abs/1412.7062).

The same operation is investigated further in [Multi-Scale Context Aggregation

by Dilated Convolutions](http://arxiv.org/abs/1511.07122). Previous works

that effectively use atrous convolution in different ways are, among others,

[OverFeat: Integrated Recognition, Localization and Detection using

Convolutional Networks](http://arxiv.org/abs/1312.6229) and [Fast Image

Scanning with Deep Max-Pooling Convolutional Neural Networks](http://arxiv.org/abs/1302.1700).

Atrous convolution is also closely related to the so-called noble identities

in multi-rate signal processing.

There are many different ways to implement atrous convolution (see the refs

above). The implementation here reduces

```python

atrous_conv2d(value, filters, rate, padding=padding)

```

to the following three operations:

```python

paddings = ...

net = space_to_batch(value, paddings, block_size=rate)

net = conv2d(net, filters, strides=[1, 1, 1, 1], padding="VALID")

crops = ...

net = batch_to_space(net, crops, block_size=rate)

```

Advanced usage. Note the following optimization: A sequence of `atrous_conv2d`

operations with identical `rate` parameters, 'SAME' `padding`, and filters

with odd heights/ widths:

```python

net = atrous_conv2d(net, filters1, rate, padding="SAME")

net = atrous_conv2d(net, filters2, rate, padding="SAME")

...

net = atrous_conv2d(net, filtersK, rate, padding="SAME")

```

can be equivalently performed cheaper in terms of computation and memory as:

```python

pad = ... # padding so that the input dims are multiples of rate

net = space_to_batch(net, paddings=pad, block_size=rate)

net = conv2d(net, filters1, strides=[1, 1, 1, 1], padding="SAME")

net = conv2d(net, filters2, strides=[1, 1, 1, 1], padding="SAME")

...

net = conv2d(net, filtersK, strides=[1, 1, 1, 1], padding="SAME")

net = batch_to_space(net, crops=pad, block_size=rate)

```

because a pair of consecutive `space_to_batch` and `batch_to_space` ops with

the same `block_size` cancel out when their respective `paddings` and `crops`

inputs are identical.

Args:

value: A 4-D `Tensor` of type `float`. It needs to be in the default "NHWC"

format. Its shape is `[batch, in_height, in_width, in_channels]`.

filters: A 4-D `Tensor` with the same type as `value` and shape

`[filter_height, filter_width, in_channels, out_channels]`. `filters`'

`in_channels` dimension must match that of `value`. Atrous convolution is

equivalent to standard convolution with upsampled filters with effective

height `filter_height + (filter_height - 1) * (rate - 1)` and effective

width `filter_width + (filter_width - 1) * (rate - 1)`, produced by

inserting `rate - 1` zeros along consecutive elements across the

`filters`' spatial dimensions.

rate: A positive int32. The stride with which we sample input values across

the `height` and `width` dimensions. Equivalently, the rate by which we

upsample the filter values by inserting zeros across the `height` and

`width` dimensions. In the literature, the same parameter is sometimes

called `input stride` or `dilation`.

padding: A string, either `'VALID'` or `'SAME'`. The padding algorithm.

name: Optional name for the returned tensor.

Returns:

A `Tensor` with the same type as `value`.

Raises:

ValueError: If input/output depth does not match `filters`' shape, or if

padding is other than `'VALID'` or `'SAME'`.

"""

with ops.name_scope(name, "atrous_conv2d", [value, filters]) as name:

value = ops.convert_to_tensor(value, name="value")

filters = ops.convert_to_tensor(filters, name="filters")

if not value.get_shape()[3].is_compatible_with(filters.get_shape()[2]):

raise ValueError(

"value's input channels does not match filters' input channels, "

"{} != {}".format(value.get_shape()[3], filters.get_shape()[2]))

if rate < 1:

raise ValueError("rate {} cannot be less than one".format(rate))

if rate == 1:

value = gen_nn_ops.conv2d(input=value,

filter=filters,

strides=[1, 1, 1, 1],

padding=padding)

return value

# We have two padding contributions. The first is used for converting "SAME"

# to "VALID". The second is required so that the height and width of the

# zero-padded value tensor are multiples of rate.

# Padding required to reduce to "VALID" convolution

if padding == "SAME":

# Handle filters whose shape is unknown during graph creation.

if filters.get_shape().is_fully_defined():

filter_shape = filters.get_shape().as_list()

else:

filter_shape = array_ops.shape(filters)

filter_height, filter_width = filter_shape[0], filter_shape[1]

# Spatial dimensions of the filters and the upsampled filters in which we

# introduce (rate - 1) zeros between consecutive filter values.

filter_height_up = filter_height + (filter_height - 1) * (rate - 1)

filter_width_up = filter_width + (filter_width - 1) * (rate - 1)

pad_height = filter_height_up - 1

pad_width = filter_width_up - 1

# When pad_height (pad_width) is odd, we pad more to bottom (right),

# following the same convention as conv2d().

pad_top = pad_height // 2

pad_bottom = pad_height - pad_top

pad_left = pad_width // 2

pad_right = pad_width - pad_left

elif padding == "VALID":

pad_top = 0

pad_bottom = 0

pad_left = 0

pad_right = 0

else:

raise ValueError("Invalid padding")

# Handle input whose shape is unknown during graph creation.

if value.get_shape().is_fully_defined():

value_shape = value.get_shape().as_list()

else:

value_shape = array_ops.shape(value)