Version 0.1-alpha3 (#185)

* Release 0.1-alpha3
* Fixes several failures in TensorFlow unit tests and other bug fixes.
* Resolves <#165>
* Improves README.

README.md

@@ -3,11 +3,11 @@
 
 ### INTRODUCTION
 
-This pre-release delivers hardware-accelerated TensorFlow and TensorFlow Addons for macOS 11.0+. Native hardware acceleration is supported on Macs with M1 and Intel-based Macs through Apple’s [ML Compute](https://developer.apple.com/documentation/mlcompute) framework.
+This pre-release delivers hardware-accelerated TensorFlow and TensorFlow Addons for macOS 11.0+. Native hardware acceleration is supported on M1 Macs and Intel-based Macs through Apple’s [ML Compute](https://developer.apple.com/documentation/mlcompute) framework.
 
 ### CURRENT RELEASE
 
-- 0.1-alpha2
+- 0.1-alpha3
 
 ### SUPPORTED VERSIONS
 
@@ -17,35 +17,46 @@ This pre-release delivers hardware-accelerated TensorFlow and TensorFlow Addons
 ### REQUIREMENTS
 
 - macOS 11.0+
-- Python 3.8, available from the [Xcode Command Line Tools](https://developer.apple.com/download/more/?=command%20line%20tools).
+- Python 3.8 (required to be downloaded from [Xcode Command Line Tools](https://developer.apple.com/download/more/?=command%20line%20tools) for M1 Macs).
 
 ### INSTALLATION
 
 An archive containing Python packages and an installation script can be downloaded from the [releases](https://github.com/apple/tensorflow_macos/releases).
 
-#### Details
-
 - To quickly try this out, copy and paste the following into Terminal:
 
   ```
-  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)"
+  % /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apple/tensorflow_macos/master/scripts/download_and_install.sh)"
   ```
 
-  This will verify your system, ask you for confirmation, then create a virtual environment (https://docs.python.org/3.8/tutorial/venv.html) with TensorFlow for macOS installed.
+  This will verify your system, ask you for confirmation, then create a [virtual environment](https://docs.python.org/3.8/tutorial/venv.html) with TensorFlow for macOS installed.
 
 - Alternatively, download the archive file from the [releases](https://github.com/apple/tensorflow_macos/releases). The archive contains an installation script, accelerated versions of TensorFlow, TensorFlow Addons, and needed dependencies.
 
+  ```
+  % curl -fLO https://github.com/apple/tensorflow_macos/releases/download/v0.1alpha2/tensorflow_macos-${VERSION}.tar.gz
+  % tar xvzf tensorflow_macos-${VERSION}.tar
+  % cd tensorflow_macos
+  % ./install_venv.sh --prompt
+  ```
+
 #### Installation on Conda
 
 This pre-release version supports installation and testing using the Python from Xcode Command Line Tools. See [#153](https://github.com/apple/tensorflow_macos/issues/153) for more information on installation in a Conda environment.
 
 #### Notes
 
-For Macs with M1, the following packages are currently unavailable:
+For M1 Macs, the following packages are currently unavailable:
 
 - SciPy and dependent packages
 - Server/Client TensorBoard packages
 
+When installing pip packages in a virtual environment, you may need to specify `--target` as follows:
+
+```
+% pip install --upgrade -t "${VIRTUAL_ENV}/lib/python3.8/site-packages/" PACKAGE_NAME
+```
+
 ### ISSUES AND FEEDBACK
 
 Please submit feature requests or report issues via [GitHub Issues](https://github.com/apple/tensorflow_macos/issues).
@@ -63,9 +74,17 @@ There is an optional `mlcompute.set_mlc_device(device_name='any')` API for ML Co
   from tensorflow.python.compiler.mlcompute import mlcompute
 
   # Select CPU device.
-  mlcompute.set_mlc_device(device_name='cpu') # Available options are 'cpu', 'gpu', and ‘any'.
+  mlcompute.set_mlc_device(device_name='cpu') # Available options are 'cpu', 'gpu', and 'any'.
   ```
 
+#### Unsupported TensorFlow Features
+
+The following TensorFlow features are currently not supported in this fork:
+
+- [tf.vectorized_map](https://www.tensorflow.org/api_docs/python/tf/vectorized_map)
+- [Higher-order gradients](https://www.tensorflow.org/guide/advanced_autodiff#higher-order_gradients)
+- Jacobian-vector products (aka. [forwardprop](https://www.tensorflow.org/api_docs/python/tf/autodiff/ForwardAccumulator))
+
 
 #### Logs and Debugging
 
@@ -96,10 +115,7 @@ Unlike graph mode, logging in eager mode is controlled by `TF_CPP_MIN_VLOG_LEVEL
 
 - Larger models being trained on the GPU may use more memory than is available, resulting in paging.  If this happens, try decreasing the batch size or the number of layers.
 - TensorFlow is multi-threaded, which means that different TensorFlow operations, such as` MLCSubgraphOp`, can execute concurrently. As a result, there may be overlapping logging information. To avoid this during the debugging process, set TensorFlow to execute operators sequentially by setting the number of threads to 1 (see [`tf.config.threading.set_inter_op_parallelism_threads`](https://www.tensorflow.org/api_docs/python/tf/config/threading/set_inter_op_parallelism_threads)).
-
-##### Additional tips for debugging in eager mode:
-
-- To find information about a specific tensor in the log, search for its buffer pointer in the log. If the tensor is defined by an operation that ML Compute does not support, you will need to cast it to `size_t` and search for it in log entries with the pattern `MemoryLogTensorAllocation ... true ptr: <(size_t)ptr>`.  You may also need to modify the `OpKernelContext::input()` to print out the input pointer so that you can see the entire use-def chain in the log.
-- You may disable the conversion of any eager operation to ML Compute by using `TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`. The gradient op may also need to be disabled by modifying  the file `$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py` (this avoids TensorFlow recompilation).
+- In eager mode, you may disable the conversion of any operation to ML Compute by using `TF_DISABLE_MLC_EAGER=“;Op1;Op2;...”`. The gradient op may also need to be disabled by modifying  the file `$PYTHONHOME/site-packages/tensorflow/python/ops/_grad.py` (this avoids TensorFlow recompilation).
 - To initialize allocated memory with a specific value, use `TF_MLC_ALLOCATOR_INIT_VALUE=<init-value>`.
+- To disable ML Compute acceleration (e.g. for debugging or results verification), set the environment variable `TF_DISABLE_MLC=1`.
 

RELEASE.md

@@ -1,3 +1,9 @@
+# Release 0.1-alpha3
+
+* Fixes several failures in TensorFlow unit tests and other bug fixes.
+* Resolves <https://github.com/apple/tensorflow_macos/issues/165>
+* Improves README.
+
 # Release 0.1-alpha2
 
 * Fixes several failures in TensorFlow unit tests and other bug fixes.

scripts/download_and_install.sh

@@ -2,7 +2,7 @@
 
 set -e
 
-VERSION=0.1alpha2
+VERSION=0.1alpha3
 INSTALLER_PACKAGE=tensorflow_macos-$VERSION.tar.gz
 INSTALLER_PATH=https://github.com/apple/tensorflow_macos/releases/download/v$VERSION/$INSTALLER_PACKAGE
 INSTALLER_SCRIPT=install_venv.sh

scripts/install_venv.sh

@@ -53,7 +53,7 @@ arch_list_arm64=(  numpy-1.18.5-cp38-cp38-macosx_11_0_arm64.whl
                    h5py-2.10.0-cp38-cp38-macosx_11_0_arm64.whl )
 
 
-tensorflow_version=0.1a2
+tensorflow_version=0.1a3
 
 
 function usage() {