.. index:: pair: page; Installation Instructions .. _doxid-installation: Installation Instructions ========================= The instructions required to install NRP-core from the source (the only option currently available) are listed below. .. _doxid-installation_1installation_requirements: Requirements ~~~~~~~~~~~~ **WARNING:** Previous versions of the NRP install forked versions of several libraries, particularly NEST and Gazebo. Installing NRP-core in a system where a previous version of NRP is installed is known to cause conflicts. We strongly recommend not to do it. .. _doxid-installation_1os: Operative System ---------------- NRP-core has only been tested on **Ubuntu 20.04** at the moment, and therefore this OS and version are recommended. Installation in other environments might be possible but has not been tested yet. .. _doxid-installation_1nest_version: NEST ---- NRP-core only supports **NEST 3**. As part of the installation process NEST 3 is built and installed. If you have an existing installation of NEST and don't NRP-Core to mess with your environment add the parameter *-DBUILD_NEST_ENGINE_SERVER=OFF* to your NRP-Core cmake command. The NEST Engine won't be built in this case but still can be used from a docker container in experiments. In any case, be aware that NEST 2.x is incompatible with NRP-core. .. _doxid-installation_1installation_dependencies: Dependency Installation ~~~~~~~~~~~~~~~~~~~~~~~ .. ref-code-block:: bash # Start of dependencies installation # 1 - Pistache REST Server sudo add-apt-repository ppa:pistache+team/unstable # 2- Gazebo Install sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list' wget https://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - sudo apt update sudo apt install git cmake libpistache-dev libboost-python-dev libboost-filesystem-dev libboost-numpy-dev libcurl4-openssl-dev nlohmann-json3-dev libzip-dev cython3 python3-numpy libgrpc++-dev protobuf-compiler-grpc libprotobuf-dev doxygen libgsl-dev libopencv-dev python3-opencv python3-pil python3-pip libgmock-dev libclang-dev libomp-dev # required by gazebo engine sudo apt install libgazebo11-dev gazebo11 gazebo11-plugin-base # 3- Install required python packages # Remove flask if it was installed to ensure it is installed from pip sudo apt remove python3-flask python3-flask-cors # required by Python engine # If you are planning to use The Virtual Brain framework, you will most likely have to use flask version 1.1.4. # By installing flask version 1.1.4 markupsafe library (included with flask) has to be downgraded to version 2.0.1 to run properly with gunicorn # You can install that version with # pip install flask==1.1.4 gunicorn markupsafe==2.0.1 pip install flask gunicorn paho-mqtt # required by nest-server (which is built and installed along with nrp-core) sudo apt install python3-restrictedpython uwsgi-core uwsgi-plugin-python3 pip install flask_cors mpi4py docopt # required by nrp-server, which uses gRPC python bindings pip install "grpcio-tools>=1.49.1" pytest psutil docker # Required for using docker with ssh pip install paramiko # The Python packages 'python_on_whales' and 'pyyaml' are optionally required to invoke nrp-core remotely with the Docker Compose (see guides/remote_docker_compose.dox for details). pip install python-on-whales pyyaml # 4- Installing ROS # Install ROS: follow the installation instructions: http://wiki.ros.org/noetic/Installation/Ubuntu. To enable ros support in nrp on `ros-noetic-ros-base` is required. # 5- Setting CATKIN workspace # If there is an existing catkin workspace in your environment and you would like nrp-core to use it, export the variable CATKIN_WS pointing to it: # E.g. export CATKIN_WS= # Otherwise nrp-core will create and compile a new catkin workspace at: ${HOME}/catkin_ws # 6- Install SpiNNaker # Follow the instructions at: https://spinnakermanchester.github.io/development/gitinstall.html. # Ensure that if using a virtualenv, this is active when running any SpiNNaker scripts. # 8- Installing Paho MQTT C and CPP # MQTT Paho library, required by datatransfer engine for streaming data over network # More information on the project web site https://github.com/eclipse/paho.mqtt.cpp # If you do not want to add network data streaming feature, you can skip this step. # MQTT Paho C library git clone https://github.com/eclipse/paho.mqtt.c.git cd paho.mqtt.c git checkout v1.3.8 cmake -Bbuild -H. -DPAHO_ENABLE_TESTING=OFF -DPAHO_BUILD_STATIC=OFF -DPAHO_BUILD_SHARED=ON -DPAHO_WITH_SSL=ON -DPAHO_HIGH_PERFORMANCE=ON -DCMAKE_INSTALL_PREFIX="${NRP_DEPS_INSTALL_DIR}" cmake --build build/ --target install sudo ldconfig && cd .. # MQTT Paho CPP git clone https://github.com/eclipse/paho.mqtt.cpp.git cd paho.mqtt.cpp git checkout v1.2.0 cmake -Bbuild -H. -DPAHO_BUILD_STATIC=OFF -DPAHO_BUILD_SHARED=ON -DCMAKE_INSTALL_PREFIX="${NRP_DEPS_INSTALL_DIR}" -DCMAKE_PREFIX_PATH="${NRP_DEPS_INSTALL_DIR}" cmake --build build/ --target install sudo ldconfig && cd .. # CUDA Support # The EDLUT simulator supports running on CUDA GPUs. This option can be enabled if EDLUT_WITH_CUDA cmake option is set to ON while configuring nrp-core. # It is highly recommended to install a CUDA version >=11.0 due to compatibility version with GCC9 (default compiler for Ubuntu 20.04) # In order to ensure that you can follow these steps which install CUDA 12.0: sudo apt-get --purge -y remove 'cuda*' sudo apt-get --purge -y remove 'nvidia*' wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-keyring_1.0-1_all.deb sudo dpkg -i cuda-keyring_1.0-1_all.deb sudo apt update sudo apt install cuda echo 'export PATH=/usr/local/cuda/bin${PATH:+:${PATH}}' >> ~/.bashrc # End of dependencies installation .. _doxid-installation_1installation_procedure: Installation ~~~~~~~~~~~~ .. ref-code-block:: bash # Start of installation git clone https://bitbucket.org/hbpneurorobotics/nrp-core.git cd nrp-core mkdir build cd build export LD_LIBRARY_PATH=${NRP_DEPS_INSTALL_DIR}/lib:${LD_LIBRARY_PATH} # if you have ROS installed (Step 4 in dependencies installation), you need to source its setup.bash file before cmake. If you don't need ROS (and did not install it) skip the next line. . /opt/ros/noetic/setup.bash # make sure that NRP_INSTALL_DIR is set properly as mentioned at the beginning of tutorial # See the section "Common NRP-core CMake options" in the documentation for the additional ways to configure the project with CMake cmake .. -DCMAKE_INSTALL_PREFIX="${NRP_INSTALL_DIR}" -DNRP_DEP_CMAKE_INSTALL_PREFIX="${NRP_DEPS_INSTALL_DIR}" mkdir -p "${NRP_INSTALL_DIR}" # the installation process might take some time, as it downloads and compiles Nest as well. # If you haven't installed MQTT libraries (Step 8 in dependencies installation), add ENABLE_MQTT=OFF definition to cmake (-DENABLE_MQTT=OFF). make make install # just in case of wanting to build the documentation. Documentation can then be found in a new doxygen folder make nrp_doxygen # End of installation .. _doxid-installation_1installation_options: Common NRP-core CMake options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Here is the list of the CMake options which can help to modify the project configuration (turn on and turn off the support of some components and features). Developers options: * **COVERAGE** enables generation of the code coverage reports during the testing; * **BUILD_RST** enables generation of the reStructuredText source files from the Doxygen documentation. Communication protocols options: * **ENABLE_ROS** enables compilation with the ROS support; * **ENABLE_MQTT** enables compilation with the MQTT support. ENABLE_SIMULATOR and BUILD_SIMULATOR_ENGINE_SERVER options: * **ENABLE_NEST** and **BUILD_NEST_ENGINE_SERVER**; * **ENABLE_GAZEBO** and **BUILD_GAZEBO_ENGINE_SERVER**. The ENABLE_SIMULATOR and BUILD_SIMULATOR_ENGINE_SERVER flags allow to disable the compilation of those parts of nrp-core that depends on or install a specific simulator (eg. gazebo, nest) The expected behavior for each of these pairs flags is as follows: * the NRPCoreSim is always built regardless of any of the flags values. * if ENABLE_SIMULATOR is set to OFF: * the related simulator won't be assumed to be installed in the system, ie. make won't fail if it isn't. Also it won't be installed in the compilation process if this possibility is available (as in the case of nest) * The engines connected with this simulator won't be built (nor client nor server components) * tests that would fail if the related simulator is not available won't be built * if the ENABLE_SIMULATOR is set to ON and BUILD_SIMULATOR_ENGINE_SERVER is set to OFF: Same as above, but: * the engine clients connected to this simulator will be built. This means that they should not depend on or link to any specific simulator * the engine server side components might or might not be built, depending on if the related simulator is required at compilation time * if the both flags are set to ON the simulator is assumed to be installed or it will be installed from source if this option is available. All targets connected with this simulator will be built This flag system allows to configure the resulting nrp-core depending on which simulators are available on the system, both for avoiding potential dependency conflicts between simulators and enforcing modularity, opening the possibility of having specific engine servers running on a different machine or inside containers. .. _doxid-installation_1installation_environment: Setting the environment ~~~~~~~~~~~~~~~~~~~~~~~ In order to properly set the environment to run experiments with NRP-core, please make sure to add the lines below to your ~/.bashrc file .. ref-code-block:: bash export NRP_INSTALL_DIR="/home/${USER}/.local/nrp" export NRP_DEPS_INSTALL_DIR="/home/${USER}/.local/nrp_deps" source ${NRP_INSTALL_DIR}/bin/.nrp_env . /usr/share/gazebo-11/setup.sh . /opt/ros/noetic/setup.bash .. _doxid-installation_1installation_sim: Steps for installing additional simulators ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section includes installation steps for simulators that may be used with :ref:`Python JSON Engine ` and :ref:`PySim Engine `. The :ref:`PySim engine ` allows to connect a set of simulators with Python interfaces with NRP-Core, these include OpenAI Gym, Mujoco, and OpenSim. .. _doxid-installation_1installation_sim_tvb: Installation of The Virtual Brain --------------------------------- The instructions below install TVB root and data directly from git repositories. It is also possible to install them via pip, but then certain features and data sets may not be accessible. Complete instructions can be found at `tvb-root `__ and `tvb-data `__ repository pages. .. ref-code-block:: bash # Install a tool that aliases python3 as python. Needed for TVB installation sudo apt install python-is-python3 # TVB data mkdir $HOME/tvb cd $HOME/tvb git clone https://github.com/the-virtual-brain/tvb-data.git cd tvb-data sudo python3 setup.py develop # TVB root cd $HOME/tvb git clone https://github.com/the-virtual-brain/tvb-root.git cd tvb-root/tvb_build ./install_full_tvb.sh # You may need to adjust your numpy version for TVB to work: pip install numpy==1.21 .. _doxid-installation_1installation_sim_openai: OpenAI installation ------------------- For OpenAI installation (complete instructions at `https://gym.openai.com/docs `__): .. ref-code-block:: bash pip install gym pygame .. _doxid-installation_1installation_sim_bullet: Bullet installation ------------------- For Bullet installation (complete instructions at `https://pybullet.org/wordpress/ `__): .. ref-code-block:: bash pip install pybullet .. _doxid-installation_1installation_sim_mujoco: Mujoco installation ------------------- For Mujoco installation (complete instructions at `https://mujoco.org `__): .. ref-code-block:: bash MUJOCO_PATH=$HOME/.mujoco WORKING_DIR=~/Documents/Tmujoco sudo apt install -y libosmesa6-dev patchelf mkdir -p $WORKING_DIR cd $WORKING_DIR wget https://mujoco.org/download/mujoco210-linux-x86_64.tar.gz -O mujoco.tar.gz mkdir -p $MUJOCO_PATH tar -xf mujoco.tar.gz -C $MUJOCO_PATH rm mujoco.tar.gz echo 'export LD_LIBRARY_PATH='$MUJOCO_PATH'/mujoco210/bin:$LD_LIBRARY_PATH' >> $HOME/.bashrc echo 'export MUJOCO_PY_MUJOCO_PATH='$MUJOCO_PATH'/mujoco210/' >> $HOME/.bashrc echo 'export LD_LIBRARY_PATH=/usr/lib/nvidia:$LD_LIBRARY_PATH' >> $HOME/.bashrc source $HOME/.bashrc cd $HOME rm -r $WORKING_DIR pip3 install mujoco_py python3 -c "import mujoco_py" .. _doxid-installation_1installation_sim_opensim: OpenSim installation -------------------- For OpenSim installation (complete instructions at `https://github.com/opensim-org/opensim-core `__): .. ref-code-block:: bash # Install opensim dependecies that are available through apt sudo apt install cmake doxygen git pip openjdk-8-jdk python3-dev wget build-essential libtool autoconf pkg-config gfortran libopenblas-dev freeglut3-dev libxi-dev libxmu-dev # Install python dependencies. # Version 1.21 of numpy is used to stay compatible with TVB pip install numpy==1.21 # Create opensim directories OPENSIM_ROOT=${HOME}/opensim OPENSIM_INSTALL_PATH=${HOME}/opensim/install OPENSIM_BUILD_PATH=${HOME}/opensim/build OPENSIM_DEPS_INSTALL_PATH=${HOME}/opensim/dependencies_install OPENSIM_DEPS_BUILD_PATH=${HOME}/opensim/dependencies_build mkdir $OPENSIM_ROOT mkdir $OPENSIM_BUILD_PATH mkdir $OPENSIM_INSTALL_PATH mkdir $OPENSIM_DEPS_BUILD_PATH mkdir $OPENSIM_DEPS_INSTALL_PATH # Compile and install (globally) the latest version of swig # The version available through apt (4.0.1) is incompatible with the latest opensim sudo apt install -y libpcre2-dev bison byacc cd ${OPENSIM_ROOT} git clone https://github.com/swig/swig cd ${OPENSIM_ROOT}/swig ./autogen.sh ./configure make -j4 sudo make install # Clone opensim # NOTE: # Both opensim and its dependencies should be built in Release mode (CMAKE_BUILD_TYPE=Release)! # Building with Debug Symbols makes the size of the resulting image unacceptable cd ${OPENSIM_ROOT} git clone https://github.com/opensim-org/opensim-core.git # Build some of the dependencies (simbody, spdlog...) as part of OpenSim 'superbuild' # OPENSIM_WITH_CASADI=ON and OPENSIM_WITH_TROPTER=ON switches will trigger # builds of certain necessary dependencies, like casadi, adolc, colpack, etc. cd ${OPENSIM_DEPS_BUILD_PATH} cmake ../opensim-core/dependencies/ \ -DCMAKE_INSTALL_PREFIX=${OPENSIM_DEPS_INSTALL_PATH} \ -DCMAKE_BUILD_TYPE=Release \ -DOPENSIM_WITH_CASADI=ON \ -DOPENSIM_WITH_TROPTER=ON make -j8 make -j8 install # Fixes "opensim/modeling/SmoothSphereHalfSpaceForce.java:49: error: unmappable character for encoding ASCII" export JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF8 # Build opensim cd ${OPENSIM_BUILD_PATH} cmake ../opensim-core \ -DCMAKE_INSTALL_PREFIX="${OPENSIM_INSTALL_PATH}" \ -DCMAKE_BUILD_TYPE=Release \ -DOPENSIM_DEPENDENCIES_DIR="${OPENSIM_DEPS_INSTALL_PATH}" \ -DBUILD_PYTHON_WRAPPING=ON \ -DBUILD_JAVA_WRAPPING=ON \ -DWITH_BTK=ON make -j8 make -j8 install cd $HOME # Export opensim python wrappers and packages echo 'export PYTHONPATH=$HOME/opensim_install/lib/python3.8/site-packages/:$PYTHONPATH' >> .bashrc # Export opensim libraries # Some of the dependecies (ipopt, adolc) arent installed with 'make install', we have to export them too echo 'export LD_LIBRARY_PATH=$HOME/opensim/dependencies_install/ipopt/lib/:$LD_LIBRARY_PATH' >> .bashrc echo 'export LD_LIBRARY_PATH=$HOME/opensim/dependencies_install/adol-c/lib64/:$LD_LIBRARY_PATH' >> .bashrc echo 'export LD_LIBRARY_PATH=$HOME/opensim/install/lib/:$LD_LIBRARY_PATH' >> .bashrc source $HOME/.bashrc