From 31058198466964af80f979f2f6e24f194426d2b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicola=20Pellican=C3=B2?= <nicola.pellicano01@gmail.com>
Date: Thu, 24 Nov 2022 18:34:18 +0100
Subject: [PATCH] [Doc] Document undefined symbol error with torch version <
 1.13 (#707)

* Create VERSIONING_ISSUES.md

* Update README.md

* Update README.md

* Update VERSIONING_ISSUES.md

* Update VERSIONING_ISSUES.md

* Update README.md

* Update VERSIONING_ISSUES.md

* Update VERSIONING_ISSUES.md

* Update VERSIONING_ISSUES.md
---
 README.md                           |  3 +++
 knowledge_base/VERSIONING_ISSUES.md | 23 +++++++++++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 knowledge_base/VERSIONING_ISSUES.md

diff --git a/README.md b/README.md
index 194472a3736..946d202e62e 100644
--- a/README.md
+++ b/README.md
@@ -506,6 +506,9 @@ and not
 OS: macOS **** (x86_64)
 ```
 
+Versioning issues can cause error message of the type ```undefined symbol``` and such. For these, refer to the [versioning issues document](knowledge_base/VERSIONING_ISSUES.md) for a complete explanation and proposed workarounds.
+
+
 ## Running examples
 Examples are coded in a very similar way but the configuration may change from one algorithm to another (e.g. async/sync data collection, hyperparameters, ratio of model updates / frame etc.)
 
diff --git a/knowledge_base/VERSIONING_ISSUES.md b/knowledge_base/VERSIONING_ISSUES.md
new file mode 100644
index 00000000000..2a80aecddf3
--- /dev/null
+++ b/knowledge_base/VERSIONING_ISSUES.md
@@ -0,0 +1,23 @@
+# Versioning Issues
+
+## Pytorch version
+This issue is related to https://github.com/pytorch/rl/issues/689. Using PyTorch versions <1.13 and installing stable package leads to undefined symbol errors. For example:
+```
+ImportError: /usr/local/lib/python3.7/dist-packages/torchrl/_torchrl.so: undefined symbol: _ZN8pybind116detail11type_casterIN2at6TensorEvE4loadENS_6handleEb
+```
+
+### How to reproduce
+1. Create an Colab Notebook (at 24/11/2022 Colab enviroment has Python 3.7 and Pytorch 1.12 installed by default).
+2. ``` !pip install torchrl ```
+3. ``` import torchrl ```
+
+In Colab you can solve the issue by running:
+``` 
+!pip3 install torch --extra-index-url https://download.pytorch.org/whl/cpu -U 
+```
+before the ```!pip install torchrl``` command. This will install the latest pytorch. Instructions can be found [here](https://pytorch.org/get-started/locally/).
+
+### Workarounds
+There are two workarounds to this issue
+1. Install/upgrade to the latest pytorch release before installing torchrl.
+2. If you need to use a previous pytorch relase: Install functorch version related to your torch distribution: e.g. ``` pip install functorch==0.2.0 ``` and install library from source ``` pip install git+https://github.com/pytorch/rl@<lib_version_here> ```.