# Keras Backend

## Overview

Keras is a model-level library, providing high-level building blocks for developing deep learning models. It does not handle itself low-level operations such as tensor products, convolutions and so on. Instead, it relies on a specialized, well-optimized tensor manipulation library to do so, serving as the “backend engine” of Keras.

The R interface to Keras uses TensorFlow™ as it’s default tensor backend engine, however it’s possible to use other backends if desired. At this time, Keras has three backend implementations available:

- TensorFlow is an open-source symbolic tensor manipulation framework developed by Google.

- Theano is an open-source symbolic tensor manipulation framework developed by LISA Lab at Université de Montréal.

- CNTK is an open-source toolkit for deep learning developed by Microsoft.

## Selecting a Backend

Keras uses the TensorFlow backend by default. If you want to switch to Theano or CNTK call the `use_backend()` function just after your call to `library(keras)`. For example:

    library(keras)
    use_backend("theano")

If you want to use the CNTK backend then you should follow the installation instructions for CNTK and then speicfy “cntk” in your call to `use_backend()`:

    library(keras)
    use_backend("cntk")

## Selecting an Implementation

Keras specifies an API that can be implemented by multiple providers. By default, the Keras R package uses the implementation provided by the Keras Python package (“keras”). TensorFlow also provides an integrated implementation of Keras which you can use by specifying “tensorflow” in a call to the `use_implementation()` function. For example:

    library(keras)
    use_implementation("tensorflow")

You would typically specify the “tensorflow” implementation when using Keras with the tfestimators package, as this implementation allows you to use Keras models seamlessly as TensorFlow Estimators.

### Keras Configuration File

If you have run Keras at least once, you will find the Keras configuration file at:

`~/.keras/keras.json`

If it isn’t there, you can create it.

The default configuration file looks like this:

    {
        "image_data_format": "channels_last",
        "epsilon": 1e-07,
        "floatx": "float32",
        "backend": "tensorflow"
    }

You can change these settings by editing `$HOME/.keras/keras.json`.

- `image_data_format`: String, either `"channels_last"` or `"channels_first"`. It specifies which data format convention Keras will follow. (`backend()$image_data_format()` returns it.)
  - For 2D data (e.g. image), `"channels_last"` assumes `(rows, cols, channels)` while `"channels_first"` assumes `(channels, rows, cols)`.
  - For 3D data, `"channels_last"` assumes `(conv_dim1, conv_dim2, conv_dim3, channels)` while `"channels_first"` assumes `(channels, conv_dim1, conv_dim2, conv_dim3)`.
- `epsilon`: Float, a numeric fuzzing constant used to avoid dividing by zero in some operations.
- `floatx`: String, `"float16"`, `"float32"`, or `"float64"`. Default float precision.
- `backend`: String, `"tensorflow"`, `"theano"`, or `"cntk"`.

## Using the Backend

If you want the Keras modules you write to be compatible with all available backends, you have to write them via the abstract Keras backend API. Backend API functions have a `k_` prefix (e.g. `k_placeholder`, `k_constant`, `k_dot`, etc.).

For example, the code below instantiates an input placeholder. It’s equivalent to `tf$placeholder()`:

    library(keras)
    inputs <- k_placeholder(shape = c(2, 4, 5))
    # also works:
    inputs <-  k_placeholder(shape = list(NULL, 4, 5))
    # also works:
    inputs <- k_placeholder(ndim = 3)

The code below instantiates a variable. It’s equivalent to `tf$Variable()`:

    val <- array(runif(60), dim = c(3L, 4L, 5L))
    var <- k_variable(value = val)

    # all-zeros variable:
    var <- k_zeros(shape = c(3, 4, 5))
    # all-ones:
    var <- k_ones(shape = c(3, 4, 5))

## Backend Functions

`k_abs` | Element-wise absolute value.
`k_all` | Bitwise reduction (logical AND).
`k_any` | Bitwise reduction (logical OR).
`k_arange` | Creates a 1D tensor containing a sequence of integers.
`k_argmax` | Returns the index of the maximum value along an axis.
`k_argmin` | Returns the index of the minimum value along an axis.
`k_backend` | Active Keras backend
`k_batch_dot` | Batchwise dot product.
`k_batch_flatten` | Turn a nD tensor into a 2D tensor with same 1st dimension.
`k_batch_get_value` | Returns the value of more than one tensor variable.
`k_batch_normalization` | Applies batch normalization on x given mean, var, beta and gamma.
`k_batch_set_value` | Sets the values of many tensor variables at once.
`k_bias_add` | Adds a bias vector to a tensor.
`k_binary_crossentropy` | Binary crossentropy between an output tensor and a target tensor.
`k_cast_to_floatx` | Cast an array to the default Keras float type.
`k_cast` | Casts a tensor to a different dtype and returns it.
`k_categorical_crossentropy` | Categorical crossentropy between an output tensor and a target tensor.
`k_clear_session` | Destroys the current TF graph and creates a new one.
`k_clip` | Element-wise value clipping.
`k_concatenate` | Concatenates a list of tensors alongside the specified axis.
`k_constant` | Creates a constant tensor.
`k_conv1d` | 1D convolution.
`k_conv2d_transpose` | 2D deconvolution (i.e. transposed convolution).
`k_conv2d` | 2D convolution.
`k_conv3d_transpose` | 3D deconvolution (i.e. transposed convolution).
`k_conv3d` | 3D convolution.
`k_cos` | Computes cos of x element-wise.
`k_count_params` | Returns the static number of elements in a Keras variable or tensor.
`k_ctc_batch_cost` | Runs CTC loss algorithm on each batch element.
`k_ctc_decode` | Decodes the output of a softmax.
`k_ctc_label_dense_to_sparse` | Converts CTC labels from dense to sparse.
`k_cumprod` | Cumulative product of the values in a tensor, alongside the specified axis.
`k_cumsum` | Cumulative sum of the values in a tensor, alongside the specified axis.
`k_depthwise_conv2d` | 2D convolution with separable filters.
`k_dot` | Multiplies 2 tensors (and/or variables) and returns a tensor.
`k_dropout` | Sets entries in `x` to zero at random, while scaling the entire tensor.
`k_dtype` | Returns the dtype of a Keras tensor or variable, as a string.
`k_elu` | Exponential linear unit.
`k_epsilon` `k_set_epsilon` | Fuzz factor used in numeric expressions.
`k_equal` | Element-wise equality between two tensors.
`k_eval` | Evaluates the value of a variable.
`k_exp` | Element-wise exponential.
`k_expand_dims` | Adds a 1-sized dimension at index “axis”.
`k_eye` | Instantiate an identity matrix and returns it.
`k_flatten` | Flatten a tensor.
`k_floatx` `k_set_floatx` | Default float type
`k_foldl` | Reduce elems using fn to combine them from left to right.
`k_foldr` | Reduce elems using fn to combine them from right to left.
`k_function` | Instantiates a Keras function
`k_gather` | Retrieves the elements of indices `indices` in the tensor `reference`.
`k_get_session` `k_set_session` | TF session to be used by the backend.
`k_get_uid` | Get the uid for the default graph.
`k_get_value` | Returns the value of a variable.
`k_get_variable_shape` | Returns the shape of a variable.
`k_gradients` | Returns the gradients of `variables` w.r.t. `loss`.
`k_greater_equal` | Element-wise truth value of (x >= y).
`k_greater` | Element-wise truth value of (x > y).
`k_hard_sigmoid` | Segment-wise linear approximation of sigmoid.
`k_identity` | Returns a tensor with the same content as the input tensor.
`k_image_data_format` `k_set_image_data_format` | Default image data format convention (‘channels_first’ or ‘channels_last’).
`k_in_test_phase` | Selects `x` in test phase, and `alt` otherwise.
`k_in_top_k` | Returns whether the `targets` are in the top `k` `predictions`.
`k_in_train_phase` | Selects `x` in train phase, and `alt` otherwise.
`k_int_shape` | Returns the shape of tensor or variable as a list of int or NULL entries.
`k_is_keras_tensor` | Returns whether `x` is a Keras tensor.
`k_is_placeholder` | Returns whether `x` is a placeholder.
`k_is_sparse` | Returns whether a tensor is a sparse tensor.
`k_l2_normalize` | Normalizes a tensor wrt the L2 norm alongside the specified axis.
`k_learning_phase` | Returns the learning phase flag.
`k_less_equal` | Element-wise truth value of (x <= y).
`k_less` | Element-wise truth value of (x < y).
`k_local_conv1d` | Apply 1D conv with un-shared weights.
`k_local_conv2d` | Apply 2D conv with un-shared weights.
`k_log` | Element-wise log.
`k_logsumexp` | Computes log(sum(exp(elements across dimensions of a tensor))).
`k_manual_variable_initialization` | Sets the manual variable initialization flag.
`k_map_fn` | Map the function fn over the elements elems and return the outputs.
`k_max` | Maximum value in a tensor.
`k_maximum` | Element-wise maximum of two tensors.
`k_mean` | Mean of a tensor, alongside the specified axis.
`k_min` | Minimum value in a tensor.
`k_minimum` | Element-wise minimum of two tensors.
`k_moving_average_update` | Compute the moving average of a variable.
`k_ndim` | Returns the number of axes in a tensor, as an integer.
`k_normalize_batch_in_training` | Computes mean and std for batch then apply batch_normalization on batch.
`k_not_equal` | Element-wise inequality between two tensors.
`k_one_hot` | Computes the one-hot representation of an integer tensor.
`k_ones_like` | Instantiates an all-ones variable of the same shape as another tensor.
`k_ones` | Instantiates an all-ones tensor variable and returns it.
`k_permute_dimensions` | Permutes axes in a tensor.
`k_placeholder` | Instantiates a placeholder tensor and returns it.
`k_pool2d` | 2D Pooling.
`k_pool3d` | 3D Pooling.
`k_pow` | Element-wise exponentiation.
`k_print_tensor` | Prints `message` and the tensor value when evaluated.
`k_prod` | Multiplies the values in a tensor, alongside the specified axis.
`k_random_binomial` | Returns a tensor with random binomial distribution of values.
`k_random_normal_variable` | Instantiates a variable with values drawn from a normal distribution.
`k_random_normal` | Returns a tensor with normal distribution of values.
`k_random_uniform_variable` | Instantiates a variable with values drawn from a uniform distribution.
`k_random_uniform` | Returns a tensor with uniform distribution of values.
`k_relu` | Rectified linear unit.
`k_repeat_elements` | Repeats the elements of a tensor along an axis.
`k_repeat` | Repeats a 2D tensor.
`k_reset_uids` | Reset graph identifiers.
`k_reshape` | Reshapes a tensor to the specified shape.
`k_resize_images` | Resizes the images contained in a 4D tensor.
`k_resize_volumes` | Resizes the volume contained in a 5D tensor.
`k_reverse` | Reverse a tensor along the specified axes.
`k_rnn` | Iterates over the time dimension of a tensor
`k_round` | Element-wise rounding to the closest integer.
`k_separable_conv2d` | 2D convolution with separable filters.
`k_set_learning_phase` | Sets the learning phase to a fixed value.
`k_set_value` | Sets the value of a variable, from an R array.
`k_shape` | Returns the symbolic shape of a tensor or variable.
`k_sigmoid` | Element-wise sigmoid.
`k_sign` | Element-wise sign.
`k_sin` | Computes sin of x element-wise.
`k_softmax` | Softmax of a tensor.
`k_softplus` | Softplus of a tensor.
`k_softsign` | Softsign of a tensor.
`k_sparse_categorical_crossentropy` | Categorical crossentropy with integer targets.
`k_spatial_2d_padding` | Pads the 2nd and 3rd dimensions of a 4D tensor.
`k_spatial_3d_padding` | Pads 5D tensor with zeros along the depth, height, width dimensions.
`k_sqrt` | Element-wise square root.
`k_square` | Element-wise square.
`k_squeeze` | Removes a 1-dimension from the tensor at index “axis”.
`k_stack` | Stacks a list of rank `R` tensors into a rank `R+1` tensor.
`k_std` | Standard deviation of a tensor, alongside the specified axis.
`k_stop_gradient` | Returns `variables` but with zero gradient w.r.t. every other variable.
`k_sum` | Sum of the values in a tensor, alongside the specified axis.
`k_switch` | Switches between two operations depending on a scalar value.
`k_tanh` | Element-wise tanh.
`k_temporal_padding` | Pads the middle dimension of a 3D tensor.
`k_tile` | Creates a tensor by tiling `x` by `n`.
`k_to_dense` | Converts a sparse tensor into a dense tensor and returns it.
`k_transpose` | Transposes a tensor and returns it.
`k_truncated_normal` | Returns a tensor with truncated random normal distribution of values.
`k_update_add` | Update the value of `x` by adding `increment`.
`k_update_sub` | Update the value of `x` by subtracting `decrement`.
`k_update` | Update the value of `x` to `new_x`.
`k_var` | Variance of a tensor, alongside the specified axis.
`k_variable` | Instantiates a variable and returns it.
`k_zeros_like` | Instantiates an all-zeros variable of the same shape as another tensor.
`k_zeros` | Instantiates an all-zeros variable and returns it.