Merge pull request #324 from thowell/installation

Improve installation instructions

Author: erez-tom

README.md

@@ -66,48 +66,110 @@ Humanoid motion-capture tracking:
 
 [![Tracking](http://img.youtube.com/vi/tEBVK-MO1Sw/hqdefault.jpg)](https://www.youtube.com/watch?v=tEBVK-MO1Sw)
 
-
 ## Graphical User Interface
 
 For a detailed dive of the graphical user interface, see the
 [MJPC GUI](docs/GUI.md) documentation.
 
 ## Installation
+MJPC is tested with [Ubuntu 20.04](https://releases.ubuntu.com/focal/) and [macOS-12](https://www.apple.com/by/macos/monterey/). In principle, other versions and Windows operating system should work with MJPC, but these are not tested.
+
+### Prerequisites
+Operating system specific dependencies:
+
+#### macOS
+Install [Xcode](https://developer.apple.com/xcode/).
+
+Install `ninja` and `zlib`:
+```sh
+brew install ninja zlib
+```
+
+#### Ubuntu 20.04
+```sh
+sudo apt-get update && sudo apt-get install cmake libgl1-mesa-dev libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev ninja-build zlib1g-dev clang-12
+```
+
+### Clone MuJoCo MPC
+```sh
+git clone https://github.com/google-deepmind/mujoco_mpc
+```
+
+### Build and Run MJPC GUI application
+1. Change directory:
+```sh
+cd mujoco_mpc
+```
+
+2. Create and change to build directory:
+```sh
+mkdir build
+cd build
+```
+
+3. Configure:
+
+#### macOS-12
+```sh
+cmake .. -DCMAKE_BUILD_TYPE:STRING=Release -G Ninja -DMJPC_BUILD_GRPC_SERVICE:BOOL=ON
+```
+
+#### Ubuntu 20.04
+```sh
+cmake .. -DCMAKE_BUILD_TYPE:STRING=Release -G Ninja -DCMAKE_C_COMPILER:STRING=clang-12 -DCMAKE_CXX_COMPILER:STRING=clang++-12 -DMJPC_BUILD_GRPC_SERVICE:BOOL=ON
+```
+**Note: gRPC is a large dependency and can take 10-20 minutes to initially download.**
+
+4. Build
+```sh
+cmake --build . --config=Release
+```
+
+6. Run GUI application
+```sh
+cd bin
+./mjpc
+```
 
-You will need [CMake](https://cmake.org/) and a working C++20 compiler to build
-MJPC. We recommend using [VSCode](https://code.visualstudio.com/) and 2 of its
+### Build and Run MJPC GUI application using VSCode
+We recommend using [VSCode](https://code.visualstudio.com/) and 2 of its
 extensions ([CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
 and [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools))
 to simplify the build process.
 
-1. Clone the repository: `git clone https://github.com/google-deepmind/mujoco_mpc.git`
+1. Open the cloned directory `mujoco_mpc`.
 2. Configure the project with CMake (a pop-up should appear in VSCode)
-3. Build and run the `mjpc` target in "release" mode (VSCode defaults to
+3. Set compiler to `clang-12`.
+4. Build and run the `mjpc` target in "release" mode (VSCode defaults to
    "debug"). This will open and run the graphical user interface.
 
-### macOS
-Additionally, install [Xcode](https://developer.apple.com/xcode/).
-
-### Ubuntu
-Additionally, install:
-```shell
-sudo apt-get install libgl1-mesa-dev libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev ninja-build
-```
-
 ### Build Issues
 If you encounter build issues, please see the
 [Github Actions configuration](https://github.com/google-deepmind/mujoco_mpc/blob/main/.github/workflows/build.yml).
-This provides the exact setup we use for building MJPC for testing.
-
-We recommend building with `clang` and not `gcc`.
+This provides the exact setup we use for building MJPC for testing with Ubuntu 20.04 and macOS-12.
 
 # Python API
+We provide a simple Python API for MJPC. This API is still experimental and expects some more experience from its users. For example, the correct usage requires that the model (defined in Python) and the MJPC task (i.e., the residual and transition functions defined in C++) are compatible with each other. Currently, the Python API does not provide any particular error handling for verifying this compatibility and may be difficult to debug without more in-depth knowledge about MuJoCo and MJPC.
 
-We provide a simple Python API for MJPC. This API is still experimental and expects some more experience from its users. For example, the correct usage requires that the model (defined in Python) and the MJPC task (i.e., the residual and transition functions defined in C++) are compatible with each other. Currently, the Python API does not provide any particular error handling for verifying this compatibility and may be difficult to debug without more in-depth knowledge about mujoco and MJPC.
+## Installation
+
+### Prerequisites
+1. Build MJPC (see instructions above).
+
+2. Python 3.10
 
-## Installing via Pip
-First, build MJPC (see above).
+3. (Optionally) Create a conda environment with **Python 3.10**:
+```sh
+conda create -n mjpc python=3.10
+conda activate mjpc
+```
 
+4. Install MuJoCo
+```sh
+pip install mujoco
+```
+
+### Install API
 Next, change to the python directory:
 ```sh
 cd python
@@ -123,11 +185,14 @@ Test that installation was successful:
 python "mujoco_mpc/agent_test.py"
 ```
 
-Additionally, the [Python version of MuJoCo](https://pypi.org/project/mujoco/#history) should match the MJPC version (this information can be found in the terminal while the application is running).
-
+Example scripts are found in `python/mujoco_mpc/demos`. For example from `python/`:
+```sh
+python mujoco_mpc/demos/agent/cartpole_gui.py
+```
+will run the MJPC GUI application using MuJoCo's passive viewer via Python.
 
-## Example Usage
-See [cartpole.py](python/mujoco_mpc/demos/agent/cartpole.py) for example usage for planning.
+### Python API Installation Issues
+If your installation fails or is terminated prematurely, we recommend deleting the MJPC build directory and starting from scratch as the build will likely be corrupted. Additionally, delete the files generated during the installation process from the `python/` directory.
 
 ## Predictive Control
 

python/setup.py

@@ -208,7 +208,7 @@ def run(self):
   def _configure_and_build_agent_server(self):
     """Check for CMake."""
     cmake_command = "cmake"
-    build_cfg = "Debug"
+    build_cfg = "Release"
     mujoco_mpc_root = Path(__file__).parent.parent
     mujoco_mpc_build_dir = mujoco_mpc_root / "build"
     cmake_configure_args = [
@@ -278,7 +278,7 @@ def _configure_and_build_agent_server(self):
         "Topic :: Scientific/Engineering",
     ],
     packages=setuptools.find_packages(),
-    python_requires=">=3.8",
+    python_requires=">=3.10",
     setup_requires=[
         "grpcio-tools",
         "grpcio",