Final adjustments for 1.2.

This contains the following changes:
- Improved installation instructions.
- Moved documentation from class attributes to initializer arguments.
- Imports TensorFlow from `tensorflow.compat.v1` to suppress warnings.
- Examples now use PackedTensors class shipped with library.
- Updated API docs.

PiperOrigin-RevId: 263625422
Change-Id: I06f699b50f44c70a028d335d09e1b68842ebdb7f

Author: Johannes Ball?

README.md

@@ -39,10 +39,11 @@ and a description of the range coding operators
 
 ## Installation
 
-***Note: Precompiled packages are currently only provided for Linux and Darwin
-(Mac OS). To use these packages on Windows, consider using a [TensorFlow
-Docker image](https://www.tensorflow.org/install/docker) and installing
-tensorflow-compression using pip inside the Docker container.***
+***Note: Precompiled packages are currently only provided for Linux (Python 2.7,
+3.7) and Darwin/Mac OS (Python 2.7, 3.3-3.6). To use these packages on Windows,
+consider using a
+[TensorFlow Docker image](https://www.tensorflow.org/install/docker) and
+installing tensorflow-compression using pip inside the Docker container.***
 
 Set up an environment in which you can install precompiled binary Python
 packages using the `pip` command. Refer to the
@@ -61,7 +62,7 @@ pip install tensorflow
 ```
 for CPU-only.
 
-Then, run the following command to install the tensorflow-compression `pip`
+Then, run the following command to install the tensorflow-compression pip
 package:
 ```bash
 pip install tensorflow-compression
@@ -74,8 +75,10 @@ python -m tensorflow_compression.python.all_test
 Once the command finishes, you should see a message ```OK (skipped=11)``` or
 similar in the last line.
 
+### Docker
+
 To use a Docker container (e.g. on Windows), be sure to install Docker
-(e.g., [Docker Desktop](https://www.docker.com/products/docker-desktop),
+(e.g., [Docker Desktop](https://www.docker.com/products/docker-desktop)),
 use a [TensorFlow Docker image](https://www.tensorflow.org/install/docker),
 and then run the `pip install` command inside the Docker container, not on the
 host. For instance, you can use a command line like this:
@@ -84,9 +87,24 @@ docker run tensorflow/tensorflow:latest-py3 bash -c \
     "pip install tensorflow-compression &&
      python -m tensorflow_compression.python.all_test"
 ```
-This will fetch the latest TensorFlow Docker image, install the `pip` package
+This will fetch the latest TensorFlow Docker image, install the pip package
 and then run the unit tests to confirm that it works.
 
+### Anaconda
+
+It seems that [Anaconda](https://www.anaconda.com/distribution/) ships its own
+binary version of TensorFlow which is incompatible with our pip package. It
+also installs Python 3.7 by default, which we currently don't support on Linux.
+To solve this, make sure to use Python 3.6 on Linux, and always install
+TensorFlow via `pip` rather than `conda`. For example, this creates an Anaconda
+environment with Python 3.6 and CUDA libraries, and then installs TensorFlow
+and tensorflow-compression with GPU support:
+```bash
+conda create --name ENV_NAME python=3.6 cudatoolkit=10.0 cudnn
+conda activate ENV_NAME
+pip install tensorflow-gpu tensorflow-compression
+```
+
 ## Usage
 
 We recommend importing the library from your Python code as follows:
@@ -168,20 +186,20 @@ python bls2017.py [options] compress original.png compressed.tfci
 python bls2017.py [options] decompress compressed.tfci reconstruction.png
 ```
 
-## Building `pip` packages
+## Building pip packages
 
-This section describes the necessary steps to build your own `pip` packages of
+This section describes the necessary steps to build your own pip packages of
 tensorflow-compression. This may be necessary to install it on platforms for
 which we don't provide precompiled binaries (currently only Linux and Darwin).
 
 We use the Docker image `tensorflow/tensorflow:nightly-custom-op` for building
-`pip` packages. Note that this is different from `tensorflow/tensorflow:devel`.
-To be compatible with the TensorFlow `pip` package, the GCC version must match,
+pip packages. Note that this is different from `tensorflow/tensorflow:devel`.
+To be compatible with the TensorFlow pip package, the GCC version must match,
 but `tensorflow/tensorflow:devel` has a different GCC version installed.
 
 Inside a Docker container from the image, the following steps need to be taken.
 
-1. Install TensorFlow `pip` package.
+1. Install TensorFlow pip package.
 2. Clone the `tensorflow/compression` repo from GitHub.
 3. Run `:build_pip_pkg` inside the cloned repo:
 
@@ -190,7 +208,7 @@ sudo docker run -v /tmp/tensorflow_compression:/tmp/tensorflow_compression \
     tensorflow/tensorflow:nightly-custom-op bash -c \
     "pip install tensorflow &&
      git clone https://github.com/tensorflow/compression.git
-         /tensorflow_compression && 
+         /tensorflow_compression &&
      cd /tensorflow_compression &&
      bazel run -c opt --copt=-mavx :build_pip_pkg"
 ```
@@ -213,7 +231,7 @@ python -m tensorflow_compression.python.all_test
 popd
 ```
 
-When done, you can uninstall the `pip` package again:
+When done, you can uninstall the pip package again:
 ```bash
 pip uninstall tensorflow-compression
 ```

build_pip_pkg.py

@@ -76,7 +76,7 @@ def main(srcdir):
       distclass=BinaryDistribution,
       # PyPI package information.
       classifiers=[
-          'Development Status :: 4 - Beta',
+          'Development Status :: 5 - Production/Stable',
           'Intended Audience :: Developers',
           'Intended Audience :: Education',
           'Intended Audience :: Science/Research',

docs/api_docs/python/index.md

@@ -1,5 +1,6 @@
 # All symbols in TensorFlow/compression
 
+## Primary symbols
 *  <a href="./tfc.md"><code>tfc</code></a>
 *  <a href="./tfc/EntropyBottleneck.md"><code>tfc.EntropyBottleneck</code></a>
 *  <a href="./tfc/EntropyModel.md"><code>tfc.EntropyModel</code></a>
@@ -9,6 +10,7 @@
 *  <a href="./tfc/LaplacianConditional.md"><code>tfc.LaplacianConditional</code></a>
 *  <a href="./tfc/LogisticConditional.md"><code>tfc.LogisticConditional</code></a>
 *  <a href="./tfc/NonnegativeParameterizer.md"><code>tfc.NonnegativeParameterizer</code></a>
+*  <a href="./tfc/PackedTensors.md"><code>tfc.PackedTensors</code></a>
 *  <a href="./tfc/Parameterizer.md"><code>tfc.Parameterizer</code></a>
 *  <a href="./tfc/RDFTParameterizer.md"><code>tfc.RDFTParameterizer</code></a>
 *  <a href="./tfc/SignalConv1D.md"><code>tfc.SignalConv1D</code></a>
@@ -55,6 +57,9 @@
 *  <a href="./tfc/unbounded_index_range_encode.md"><code>tfc.python.ops.range_coding_ops.unbounded_index_range_encode</code></a>
 *  <a href="./tfc/python/ops/spectral_ops.md"><code>tfc.python.ops.spectral_ops</code></a>
 *  <a href="./tfc/irdft_matrix.md"><code>tfc.python.ops.spectral_ops.irdft_matrix</code></a>
+*  <a href="./tfc/python/util.md"><code>tfc.python.util</code></a>
+*  <a href="./tfc/python/util/packed_tensors.md"><code>tfc.python.util.packed_tensors</code></a>
+*  <a href="./tfc/PackedTensors.md"><code>tfc.python.util.packed_tensors.PackedTensors</code></a>
 *  <a href="./tfc/range_decode.md"><code>tfc.range_decode</code></a>
 *  <a href="./tfc/range_encode.md"><code>tfc.range_encode</code></a>
 *  <a href="./tfc/same_padding_for_kernel.md"><code>tfc.same_padding_for_kernel</code></a>

docs/api_docs/python/tfc.md

@@ -5,17 +5,19 @@
 
 # Module: tfc
 
-Data compression tools.
 
+<table class="tfo-notebook-buttons tfo-api" align="left">
+
+<td>
+  <a target="_blank" href="https://github.com/tensorflow/compression/tree/master/tensorflow_compression/__init__.py">
+    <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
+    View source on GitHub
+  </a>
+</td></table>
 
 
 
-<table class="tfo-github-link" align="left">
-<a target="_blank" href="https://github.com/tensorflow/compression/tree/master/tensorflow_compression/__init__.py">
-  <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
-  View source on GitHub
-</a>
-</table>
+Data compression tools.
 
 <!-- Placeholder for "Used in" -->
 
@@ -42,6 +44,8 @@ Data compression tools.
 
 [`class NonnegativeParameterizer`](./tfc/NonnegativeParameterizer.md): Object encapsulating nonnegative parameterization as needed for GDN.
 
+[`class PackedTensors`](./tfc/PackedTensors.md): Packed representation of compressed tensors.
+
 [`class Parameterizer`](./tfc/Parameterizer.md): Parameterization object (abstract base class).
 
 [`class RDFTParameterizer`](./tfc/RDFTParameterizer.md): Object encapsulating RDFT reparameterization.
@@ -54,7 +58,7 @@ Data compression tools.
 
 [`class StaticParameterizer`](./tfc/StaticParameterizer.md): A parameterizer that returns a non-variable.
 
-[`class SymmetricConditional`](./tfc/SymmetricConditional.md): Symmetric conditional entropy model.
+[`class SymmetricConditional`](./tfc/SymmetricConditional.md): Symmetric conditional entropy model (base class).
 
 ## Functions
 

docs/api_docs/python/tfc/EntropyBottleneck.md

@@ -55,6 +55,18 @@
 
 # tfc.EntropyBottleneck
 
+
+<table class="tfo-notebook-buttons tfo-api" align="left">
+
+<td>
+  <a target="_blank" href="https://github.com/tensorflow/compression/tree/master/tensorflow_compression/python/layers/entropy_models.py">
+    <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
+    View source on GitHub
+  </a>
+</td></table>
+
+
+
 ## Class `EntropyBottleneck`
 
 Entropy bottleneck layer.
@@ -63,19 +75,9 @@ Inherits From: [`EntropyModel`](../tfc/EntropyModel.md)
 
 ### Aliases:
 
-* Class `tfc.EntropyBottleneck`
 * Class `tfc.python.layers.entropy_models.EntropyBottleneck`
 
 
-
-
-<table class="tfo-github-link" align="left">
-<a target="_blank" href="https://github.com/tensorflow/compression/tree/master/tensorflow_compression/python/layers/entropy_models.py">
-  <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
-  View source on GitHub
-</a>
-</table>
-
 <!-- Placeholder for "Used in" -->
 
 This layer models the entropy of the tensor passing through it. During
@@ -117,64 +119,6 @@ which are only significant for compression and decompression. To use the
 compression feature, the auxiliary loss must be minimized during or after
 training. After that, the update op must be executed at least once.
 
-#### Arguments:
-
-
-* <b>`init_scale`</b>: Float. A scaling factor determining the initial width of the
-  probability densities. This should be chosen big enough so that the
-  range of values of the layer inputs roughly falls within the interval
-  [`-init_scale`, `init_scale`] at the beginning of training.
-* <b>`filters`</b>: An iterable of ints, giving the number of filters at each layer of
-  the density model. Generally, the more filters and layers, the more
-  expressive is the density model in terms of modeling more complicated
-  distributions of the layer inputs. For details, refer to the paper
-  referenced above. The default is `[3, 3, 3]`, which should be sufficient
-  for most practical purposes.
-* <b>`tail_mass`</b>: Float, between 0 and 1. The bottleneck layer automatically
-  determines the range of input values based on their frequency of
-  occurrence. Values occurring in the tails of the distributions will not be
-  encoded with range coding, but using a Golomb-like code. `tail_mass`
-  determines the amount of probability mass in the tails which will be
-  Golomb-coded. For example, the default value of `2 ** -8` means that on
-  average, one 256th of all values will use the Golomb code.
-* <b>`likelihood_bound`</b>: Float. If positive, the returned likelihood values are
-  ensured to be greater than or equal to this value. This prevents very
-  large gradients with a typical entropy loss (defaults to 1e-9).
-* <b>`range_coder_precision`</b>: Integer, between 1 and 16. The precision of the range
-  coder used for compression and decompression. This trades off computation
-  speed with compression efficiency, where 16 is the slowest but most
-  efficient setting. Choosing lower values may increase the average
-  codelength slightly compared to the estimated entropies.
-* <b>`data_format`</b>: Either `'channels_first'` or `'channels_last'` (default).
-* <b>`trainable`</b>: Boolean. Whether the layer should be trained.
-* <b>`name`</b>: String. The name of the layer.
-* <b>`dtype`</b>: `DType` of the layer's inputs, parameters, returned likelihoods, and
-  outputs during training. Default of `None` means to use the type of the
-  first input.
-
-Read-only properties:
-  init_scale: See above.
-  filters: See above.
-  tail_mass: See above.
-  likelihood_bound: See above.
-  range_coder_precision: See above.
-  data_format: See above.
-  name: String. See above.
-  dtype: See above.
-  trainable_variables: List of trainable variables.
-  non_trainable_variables: List of non-trainable variables.
-  variables: List of all variables of this layer, trainable and non-trainable.
-  updates: List of update ops of this layer.
-  losses: List of losses added by this layer. Always contains exactly one
-    auxiliary loss, which must be added to the training loss.
-
-#### Mutable properties:
-
-
-* <b>`trainable`</b>: Boolean. Whether the layer should be trained.
-* <b>`input_spec`</b>: Optional `InputSpec` object specifying the constraints on inputs
-  that can be accepted by the layer.
-
 <h2 id="__init__"><code>__init__</code></h2>
 
 <a target="_blank" href="https://github.com/tensorflow/compression/tree/master/tensorflow_compression/python/layers/entropy_models.py">View source</a>
@@ -188,8 +132,24 @@ __init__(
 )
 ```
 
+Initializer.
 
 
+#### Arguments:
+
+
+* <b>`init_scale`</b>: Float. A scaling factor determining the initial width of the
+  probability densities. This should be chosen big enough so that the
+  range of values of the layer inputs roughly falls within the interval
+  [`-init_scale`, `init_scale`] at the beginning of training.
+* <b>`filters`</b>: An iterable of ints, giving the number of filters at each layer
+  of the density model. Generally, the more filters and layers, the more
+  expressive is the density model in terms of modeling more complicated
+  distributions of the layer inputs. For details, refer to the paper
+  referenced above. The default is `[3, 3, 3]`, which should be sufficient
+  for most practical purposes.
+* <b>`data_format`</b>: Either `'channels_first'` or `'channels_last'` (default).
+* <b>`**kwargs`</b>: Other keyword arguments passed to superclass (`EntropyModel`).