Merge pull request #988 from KonduitAI/master

Refactor Examples repository

Author: treo

.gitignore

@@ -62,3 +62,5 @@ Word2vec-index/
 *end.model
 
 arbiterExample/
+dl4j-examples/*.zip
+

LICENSE.txt

@@ -1,3 +1,4 @@
+Copyright (c) 2020 Konduit K.K
 Copyright 2015-2019 Skymind Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,71 +18,19 @@ limitations under the License.
 
 -- Misc files --
 *README.md
+*FAQ.md
 *readme.md
-.github/CONTRIBUTING.md
+CONTRIBUTORS.md
 .github/ISSUE_TEMPLATE.md
 .github/PULL_REQUEST_TEMPLATE.md
 org/deeplearning4j/examples/misc/customlayers/CustomLayerExampleReadme.md
-org/deeplearning4j/examples/tictactoe/ReadMe.txt
-lstm-hdfs/src/resources/test/f1
-lstm-hdfs/src/resources/test/f2
-lstm-hdfs/src/resources/train/f1
-lstm-hdfs/src/resources/train/f2
-lstm-hdfs/src/resources/train/f3
-nd4j-examples/src/main/resources/numpy_cheatsheet/file.csv
-nd4j-examples/src/main/resources/numpy_cheatsheet/file.txt
-nd4j-examples/src/main/resources/numpy_cheatsheet/saveFile.csv
-nd4j-examples/src/main/resources/numpy_cheatsheet/saveFile.txt
+nd4j-ndarray-examples/src/main/resources/numpy_cheatsheet/file.txt
+nd4j-ndarray-examples/src/main/resources/numpy_cheatsheet/saveFile.txt
+nd4j-ndarray-examples/src/main/resources/numpyz.npz
 pydatavec-examples/basic_example.csv
 pydatavec-examples/reduction_example.csv
-rl4j-examples/cartpole.gif
-rl4j-examples/cliffwalk.gif
-rl4j-examples/cliffwalk_block.gif
-rl4j-examples/doom.gif
-rl4j-examples/scoregraph.png
-tutorials/00. Quickstart for Deeplearning4j.json
-tutorials/00. Quickstart for Deeplearning4j.zepp.ipynb
-tutorials/01. MultiLayerNetwork and ComputationGraph.json
-tutorials/01. MultiLayerNetwork and ComputationGraph.zepp.ipynb
-tutorials/02. Built-in Data Iterators.json
-tutorials/02. Built-in Data Iterators.zepp.ipynb
-tutorials/03. Logistic Regression.json
-tutorials/03. Logistic Regression.zepp.ipynb
-tutorials/04. Feed-forward.json
-tutorials/04. Feed-forward.zepp.ipynb
-tutorials/05. Basic Autoencoder- Anomaly Detection Using Reconstruction Error.json
-tutorials/05. Basic Autoencoder- Anomaly Detection Using Reconstruction Error.zepp.ipynb
-tutorials/06. Advanced Autoencoder- Trajectory Clustering using AIS.json
-tutorials/06. Advanced Autoencoder- Trajectory Clustering using AIS.zepp.ipynb
-tutorials/07. Convolutions- Train FaceNet Using Center Loss.json
-tutorials/07. Convolutions- Train FaceNet Using Center Loss.zepp.ipynb
-tutorials/08. RNNs- Sequence Classification of Synthetic Control Data.json
-tutorials/08. RNNs- Sequence Classification of Synthetic Control Data.zepp.ipynb
-tutorials/09. Early Stopping.ipynb
-tutorials/09. Early Stopping.zepp.json
-tutorials/10. Layers and Preprocessors.ipynb
-tutorials/10. Layers and Preprocessors.zepp.json
-tutorials/11. Hyperparameter Optimization.json
-tutorials/11. Hyperparameter Optimization.zepp.ipynb
-tutorials/12. Clinical Time Series LSTM Example.json
-tutorials/12. Clinical Time Series LSTM Example.zepp.ipynb
-tutorials/13. Clinical LSTM Time Series Example Using SKIL.json
-tutorials/13. Clinical LSTM Time Series Example Using SKIL.zepp.ipynb
-tutorials/14. Parallel Training.json
-tutorials/14. Parallel Training.zepp.ipynb
-tutorials/15. Sea Temperature Convolutional LSTM Example.json
-tutorials/15. Sea Temperature Convolutional LSTM Example.zepp.ipynb
-tutorials/16. Sea Temperature Convolutional LSTM Example 2.json
-tutorials/16. Sea Temperature Convolutional LSTM Example 2.zepp.ipynb
-tutorials/17. Instacart Multitask Example.json
-tutorials/17. Instacart Multitask Example.zepp.ipynb
-tutorials/18. Instacart Single Task Example.json
-tutorials/18. Instacart Single Task Example.zepp.ipynb
-tutorials/19. Cloud Detection Example.json
-tutorials/19. Cloud Detection Example.zepp.ipynb
-
-
 
+Copyright (c) 2020 Konduit K.K
 Copyright (c) 2015-2019 Skymind, Inc.
 Apache 2.0 License
 

README.md

@@ -1,60 +1,79 @@
-Deeplearning4J Examples
-=========================
+<pre>
+                                ########  ##       ##              ##
+                                ##     ## ##       ##    ##        ##
+                                ##     ## ##       ##    ##        ##
+                       **$**    ##     ## ##       ##    ##        ##    **$**
+                                ##     ## ##       ######### ##    ##
+                                ##     ## ##             ##  ##    ##
+                                ########  ########       ##   ######
+              .   :::: :   :    :   :     : ::::  :     ::::    :::::  :::: ::::  :::::   .
+              .   :    :   :   : :  ::   :: :   : :     :       :   :  :    :   : :   :   .
+              .   :     : :   :   : : : : : :   : :     :       :   :  :    :   : :   :   .
+              .   :::    :    :   : :  :  : ::::  :     :::     :::::  :::  ::::  :   :   .
+              .   :     : :   ::::: :     : :     :     :       :  :   :    :     :   :   .
+              .   :    :   :  :   : :     : :     :     :       :   :  :    :     :   :   .
+              .   :::: :   :  :   : :     : :     ::::: ::::    :    : :::: :     :::::   .
+</pre>
 
-## NOTE: HOW to interpret these examples
+## Introduction
+The **Eclipse Deeplearning4J** (DL4J) ecosystem is a set of projects intended to support all the needs of a JVM based deep learning application. This means starting with the raw data, loading and preprocessing it from wherever and whatever format it is in to building and tuning a wide variety of simple and complex deep learning networks.
 
-## Data Loading
-In this repository, you may likely see custom [datasetiterators](https://github.com/eclipse/deeplearning4j/blob/master/nd4j/nd4j-backends/nd4j-api-parent/nd4j-api/src/main/java/org/nd4j/linalg/dataset/api/iterator/DataSetIterator.java) - these iterators are only for special examples and 1 off use cases. Consult the [gitter](https://gitter.im/deeplearning4j/deeplearning4j) if you are not sure how to proceed.
-Once you find a record reader for your use case, you then should use one of pre made iterators that knows how to interpret record reader output, either [RecordReaderDataSetIterator](https://deeplearning4j.org/api/latest/org/deeplearning4j/datasets/datavec/RecordReaderDataSetIterator.html) for normal data or [SequenceRecordReaderDataSetIterator](https://deeplearning4j.org/api/latest/org/deeplearning4j/datasets/datavec/SequenceRecordReaderDataSetIterator.html) for sequence data. For more on sequences, please see our [rnns page](http://deeplearning4j.org/usingrnns)
+The DL4J stack comprises of:
+- **DL4J**: High level API to build MultiLayerNetworks and ComputationGraphs with a variety of layers, including custom ones. Supports importing Keras models from h5, including tf.keras models (as of 1.0.0-beta7) and also supports distributed training on Apache Spark
+- **ND4J**: General purpose linear algebra library with over 500 mathematical, linear algebra and deep learning operations. ND4J is based on the highly-optimized C++ codebase LibND4J that provides CPU (AVX2/512) and GPU (CUDA) support and acceleration by libraries such as OpenBLAS, OneDNN (MKL-DNN), cuDNN, cuBLAS, etc
+- **SameDiff** : Part of the ND4J library, SameDiff is our automatic differentiation / deep learning framework. SameDiff uses a graph-based (define then run) approach, similar to TensorFlow graph mode. Eager graph (TensorFlow 2.x eager/PyTorch) graph execution is planned. SameDiff supports importing TensorFlow frozen model format .pb (protobuf) models. Import for ONNX, TensorFlow SavedModel and Keras models are planned. Deeplearning4j also has full SameDiff support for easily writing custom layers and loss functions.
+- **DataVec**: ETL for machine learning data in a wide variety of formats and files (HDFS, Spark, Images, Video, Audio, CSV, Excel etc)
+- **Arbiter**: Library for hyperparameter search
+- **LibND4J** : C++ library that underpins everything. For more information on how the JVM acceses native arrays and operations refer to [JavaCPP](https://github.com/bytedeco/javacpp)
 
+All projects in the DL4J ecosystem support Windows, Linux and macOS. Hardware support includes CUDA GPUs (10.0, 10.1, 10.2 except OSX), x86 CPU (x86_64, avx2, avx512), ARM CPU (arm, arm64, armhf) and PowerPC (ppc64le).
 
-We have special iterators for 1 off use cases where normal data does not quite exist, or sometimes it is legacy.
-99% of the time you should be using [datavec](https://deeplearning4j.org/datavec) and writing your own custom [record readers](https://deeplearning4j.org/api/latest/org/datavec/api/records/reader/RecordReader.html) if one of our pre provided ones is not suitable. If you are not sure what is available, please again consult the [gitter](https://gitter.im/deeplearning4j/deeplearning4j) - In general, you can find both [normal record readers](https://deeplearning4j.org/api/latest/org/datavec/api/records/reader/RecordReader.html) and [sequence record readers](https://deeplearning4j.org/api/latest/org/datavec/api/records/reader/SequenceRecordReader.html) in the datavec [javadoc](https://deeplearning4j.org/docs/latest/datavec-overview).
+## Prerequisites
+This example repo consists of several separate Maven Java projects, each with their own pom files. Maven is a popular build automation tool for Java Projects. The contents of a "pom.xml" file dictate the configurations. Read more about how to configure Maven [here](https://deeplearning4j.konduit.ai/config/maven).
 
+Users can also refer to the [simple sample project provided](./mvn-project-template/pom.xml) to get started with a clean project from scratch.
 
-## Dependencies
+Build tools are considered standard software engineering best practice. Besides this the complexities posed by the projects in the DL4J ecosystem make dependencies too difficult to manage manually. All the projects in the DL4J ecosystem can be used with other build tools like Gradle, SBT etc. More information on that can be found [here](https://deeplearning4j.konduit.ai/config/buildtools).
 
-Note that this repository contains all dl4j examples for all modules. It will download about 1.5g of dependencies from maven central when you are first starting out. That being said, this makes it easier to get started without worrying about what to download. This examples repository is meant to be a reference point to get started with most common use cases.
-It is broken up in to modules. If you would like to just have a more minimal/simple, guide please go [here](http://www.dubs.tech/guides/maven-essentials/)
+## Example Content
+Projects are based on what functionality the included examples demonstrate to the user and not necessarily which library in the DL4J stack the functionality lives in.
 
+Examples in a project are in general separated into "quickstart" and "advanced".
 
-Repository of Deeplearning4J neural net examples:
+Each project README also lists all the examples it contains, with a recommended order to explore them in.
 
-- MLP Neural Nets
-- Convolutional Neural Nets
-- Recurrent Neural Nets
-- TSNE
-- Word2Vec
-- Anomaly Detection
-- User interface examples.
+- [dl4j-examples](dl4j-examples/README.md)
+This project contains a set of examples that demonstrate use of the high level DL4J API to build a variety of neural networks.
+Some of  these examples are end to end, in the sense they start with raw data, process it and then build and train neural networks on it.
 
-DL4J-Examples is released under an Apache 2.0 license. By contributing code to this repository, you agree to make your contribution available under an Apache 2.0 license.
+- [tensorflow-keras-import-examples](tensorflow-keras-import-examples/README.md)
+This project contains a set of examples that demonstrate how to import Keras h5 models and TensorFlow frozen pb models into the DL4J ecosystem. Once imported into DL4J these models can be treated like any other DL4J model - meaning you can continue to run training on them or modify them with the transfer learning API or simply run inference on them.
 
----
+- [dl4j-distributed-training-examples](dl4j-distributed-training-examples/README.md)
+This project contains a set of examples that demonstrate how to do distributed training, inference and evaluation in DL4J on Apache Spark. DL4J distributed training employs a "hybrid" asynchronous SGD approach - further details can be found in the distributed deep learning documentation [here](https://deeplearning4j.konduit.ai/distributed-deep-learning/intro)
 
-## Build and Run
+- [cuda-specific-examples](cuda-specific-examples/README.md)
+This project contains a set of examples that demonstrate how to leverage multiple GPUs for data-parallel training of neural networks for increased performance.
 
-Use [Maven](https://maven.apache.org/) to build the examples.
+- [samediff-examples](samediff-examples/README.md)
+This project contains a set of examples that demonstrate the SameDiff API. SameDiff (which is part of the ND4J library) can be used to build lower level auto-differentiating computation graphs. An analogue to the SameDiff API vs the DL4J API is the low level TensorFlow API vs the higher level of abstraction Keras API.
 
-```
-mvn clean package
-```
+- [data-pipeline-examples](data-pipeline-examples/README.md)
+This project contains a set of examples that demonstrate how raw data in various formats can be loaded, split and preprocessed to build serializable (and hence reproducible) ETL pipelines.
 
-This downloads binaries for all platforms, but we can also append `-Djavacpp.platform=` with `android-arm`, `android-x86`, `linux-ppc64le`, `linux-x86_64`, `macosx-x86_64`, or `windows-x86_64` to get binaries for only one platform and produce much smaller archives.
+- [nd4j-ndarray-examples](nd4j-ndarray-examples/README.md)
+This project contains a set of examples that demonstrate how to manipulate NDArrays. The functionality of ND4J demonstrated here can be likened to NumPy.
 
-Run the `runexamples.sh` script to run the examples (requires [bash](https://www.gnu.org/software/bash/)). It will list the examples and prompt you for the one to run. Pass the `--all` argument to run all of them. (Other options are shown with `-h`).
+- [arbiter-examples](arbiter-examples/README.md)
+This project contains a set of examples that demonstrate usage of the Arbiter library for hyperparameter tuning of Deeplearning4J neural networks.
 
-```
-./runexamples.sh [-h | --help]
-```
+- [rl4j-examples](rl4j-examples/README.md)
+This project contains examples of using RL4J, the reinforcement learning library in DL4J.
 
+- [android-examples](android-examples/README.md)
+This project contains an Android example project, that shows DL4J being used in an Android application.
 
-## Documentation
-For more information, check out [deeplearning4j.org](http://deeplearning4j.org/) and its [JavaDoc](https://deeplearning4j.org/docs/latest/).
-
-`GradientsListenerExample.java` in dl4j-examples/src/main/java/org/deeplearning4j/examples/userInterface uses JavaFX. If you're using Java 8 or greater, it should run as is.  If you're using Java 7 or an earlier version, you should set JAVAFX_HOME to point to the root directory of the JavaFX 2.0 SDK.
-
-## Other Issues
-
-If you notice issues, please log them, and if you want to contribute, submit a pull request. Input is welcome here.
-
+## Feedback & Contributions
+While these set of examples don't cover all the features available in DL4J the intent is to cover functionality required for most users - beginners and advanced.  File an issue [here](https://github.com/eclipse/deeplearning4j-examples/issues) if you have feedback or feature requests that are not covered here. We are also available via our [community forum](https://community.konduit.ai/) for questions.
+We welcome contributions from the community. More information can be found [here](CONTRIBUTORS.md)
+We **love** hearing from you. Cheers!

android-examples/.gitignore

@@ -0,0 +1,14 @@
+*.iml
+.gradle
+/local.properties
+/.idea/caches
+/.idea/libraries
+/.idea/modules.xml
+/.idea/workspace.xml
+/.idea/navEditor.xml
+/.idea/assetWizardSettings.xml
+.DS_Store
+/build
+/captures
+.externalNativeBuild
+.cxx

android-examples/README.md

@@ -0,0 +1,25 @@
+# Eclipse Deeplearning4J Examples for Android
+
+This project shows a simple example of using Deeplearning4J in an Android application. As Gradle is the preferred build tool for Android, this project uses Gradle instead of Maven.
+
+The neural networks shown in this example are the same as are used in the [Moon](../dl4j-examples/src/main/java/org/deeplearning4j/examples/quickstart/modeling/feedforward/classification/MoonClassifier.java) and [Saturn](../dl4j-examples/src/main/java/org/deeplearning4j/examples/quickstart/modeling/feedforward/classification/SaturnClassifier.java) examples of the dl4j-examples.
+
+The build configuration for Android can be found in [app/build.gradle](./app/build.gradle).
+
+[Go back](../README.md) to the main repository page to explore other features/functionality of the **Eclipse Deeplearning4J** ecosystem. File an issue [here](https://github.com/eclipse/deeplearning4j-examples/issues) to request new features.
+
+# Known Issues
+Due to an unfortunately timed change, the 1.0.0-beta7 release doesn't work well with most Android devices. For this reason, this example project uses the SNAPSHOT version.
+
+Again unfortunately, gradle has issues retrieving SNAPSHOT versions when combined with classifiers, which are used here to retrieve only the android specific backend dependencies.
+
+If you want to run this example locally, you will therefore need to have Maven installed in order to download those specific dependencies.
+
+Once you have installed Maven, you will need to run the following commands from the command line to download the correct android backend files:
+
+```
+mvn dependency:get -DremoteRepositories=snapshots::::https://oss.sonatype.org/content/repositories/snapshots -Dartifact=org.nd4j:nd4j-native:1.0.0-SNAPSHOT:jar:android-arm
+mvn dependency:get -DremoteRepositories=snapshots::::https://oss.sonatype.org/content/repositories/snapshots -Dartifact=org.nd4j:nd4j-native:1.0.0-SNAPSHOT:jar:android-arm64
+mvn dependency:get -DremoteRepositories=snapshots::::https://oss.sonatype.org/content/repositories/snapshots -Dartifact=org.nd4j:nd4j-native:1.0.0-SNAPSHOT:jar:android-x86
+mvn dependency:get -DremoteRepositories=snapshots::::https://oss.sonatype.org/content/repositories/snapshots -Dartifact=org.nd4j:nd4j-native:1.0.0-SNAPSHOT:jar:android-x86_64
+```

android-examples/app/.gitignore

@@ -0,0 +1 @@
+/build