.. _chap_installation:

Installation
============


In order to get you up and running for hands-on learning experience, we
need to set you up with an environment for running Python, Jupyter
notebooks, the relevant libraries, and the code needed to run the book
itself.

Installing JDK 11 (not jre)
---------------------------

JDK 11 (or above) are required to run the examples provided in this
folder.

To confirm the java path is configured properly, run:

.. code:: bash

    java --list-modules | grep "jdk.jshell"

    > jdk.jshell@12.0.1

Install jupyter notebook on python3
-----------------------------------

Use the following command to install Jupyter Notebook in Python 3:

.. code:: bash

    pip3 install jupyter

Install Java kernel for jupyter notebook
----------------------------------------

By default jupyter notebook runs only Python3. You need to install the
Java kernel to run Java code such as DJL.

.. code:: bash

    git clone https://github.com/frankfliu/IJava.git
    cd IJava/
    ./gradlew installKernel

Downloading the D2L-Java Notebooks
----------------------------------

Next, we need to download the code for this book. You can clone our
`repository <https://github.com/deepjavalibrary/d2l-java>`__ and browse
all the notebooks using Jupyter Notebook.

.. code:: bash

    git clone https://github.com/deepjavalibrary/d2l-java
    cd d2l-java

Running Jupyter Notebook
------------------------

Once the above dependencies are installed, we can now open the Jupyter
notebook by running:

.. code:: bash

    jupyter notebook

At this point, you can open http://localhost:8888 (it usually opens
automatically) in your Web browser. Then we can run the code for each
section of the book. Remember to switch the Kernel to Java instead of
Python3.

Adding the dependencies on DJL and the MXNet engine
---------------------------------------------------

You can add maven dependencies on DJL and MXNet by adding a Java cell
including:

.. code:: java

    // Add the maven dependencies
    %maven ai.djl:api:0.20.0
    %maven org.slf4j:slf4j-simple:2.0.1
            
    // See https://github.com/deepjavalibrary/djl/blob/master/mxnet/mxnet-engine/README.md
    // for more MXNet library selection options
    %maven ai.djl.mxnet:mxnet-engine:0.20.0

To avoid repeatedly adding maven dependencies and import required
packages, we just load a predefined jupyter notebook:

::

    %load ../utils/djl-imports.ipynb

Now you can import and run different modules in DJL.

.. _subsec_gpu:

GPU Support
-----------


We recommend using the automatic dependency. When using this option, DJL
will detect your operating system and whether you have a GPU available.
It will automatically download the corresponding MXNet GPU native
libraries for your environment. No specific requirement needed to run
the notebook on GPU machines. To use specific builds of MXNet engine,
please refer to our
`documentation <https://github.com/deepjavalibrary/djl/tree/master/mxnet/mxnet-engine>`__.

Exercises
---------

1. Download the code for the book and install the runtime environment.