Add README and comments for VAE examples (variational autoencoder folder)

Author: NA-V10

dl4j-examples/src/main/java/org/deeplearning4j/examples/quickstart/modeling/variationalautoencoder/README.md

@@ -0,0 +1,58 @@
+# Variational Autoencoder (VAE) Examples – DeepLearning4J
+
+This folder contains two examples demonstrating how to use Variational Autoencoders (VAEs) in DeepLearning4J.  
+VAEs are generative models that learn latent representations of data and can be used for visualization, sampling, and anomaly detection.
+
+---
+
+## 🧩 VaeMNIST2dPlots.java
+Trains a VAE on the MNIST digit dataset and visualizes the **2-dimensional latent space**.
+
+### What this example shows
+- How to build a VAE in DL4J  
+- Encoding MNIST images into a 2D latent space  
+- Plotting how digits cluster in latent space  
+- How VAEs learn smooth and continuous representations  
+
+### Why it’s useful
+A 2D latent space allows easy visualization of how the model separates digits.
+
+---
+
+## ⚠️ VaeMNISTAnomaly.java
+Uses a trained VAE for **anomaly detection** on MNIST.
+
+### Key Concepts
+- VAEs reconstruct normal data well  
+- They reconstruct anomalies poorly  
+- Reconstruction error can be used as an anomaly score  
+
+### What this example demonstrates
+- Reconstructing MNIST digits  
+- Computing reconstruction probability  
+- Detecting out-of-distribution or corrupted samples  
+
+---
+
+## ✔ How to Run Any Example
+
+mvn -q exec:java -Dexec.mainClass="org.deeplearning4j.examples.quickstart.modeling.variationalautoencoder.<ClassName>"
+
+
+Example:
+
+
+
+mvn -q exec:java -Dexec.mainClass="org.deeplearning4j.examples.quickstart.modeling.variationalautoencoder.VaeMNIST2dPlots"
+
+
+---
+
+## 🙌 Why This README Helps
+The VAE folder previously had no documentation.  
+This README explains:
+- Purpose of each example  
+- The ML concepts involved  
+- How to run and understand the results  
+
+This improves clarity for beginners working with generative models in DL4J.

dl4j-examples/src/main/java/org/deeplearning4j/examples/quickstart/modeling/variationalautoencoder/VaeMNIST2dPlots.java

@@ -17,6 +17,10 @@
  * SPDX-License-Identifier: Apache-2.0
  ******************************************************************************/
 
+  // VaeMNIST2dPlots.java
+ // Trains a Variational Autoencoder (VAE) on MNIST and visualizes the 2D latent space.
+// Shows how VAEs compress images into smooth, continuous latent variables.
+
 package org.deeplearning4j.examples.quickstart.modeling.variationalautoencoder;
 
 import org.deeplearning4j.datasets.iterator.impl.MnistDataSetIterator;
@@ -98,10 +102,13 @@ public static void main(String[] args) throws IOException {
         MultiLayerNetwork net = new MultiLayerNetwork(conf);
         net.init();
 
+        // Build a VAE with a 2-dimensional latent space for visualization
+
         //Get the variational autoencoder layer
         org.deeplearning4j.nn.layers.variational.VariationalAutoencoder vae
             = (org.deeplearning4j.nn.layers.variational.VariationalAutoencoder) net.getLayer(0);
 
+         
 
         //Test data for plotting
         DataSet testdata = new MnistDataSetIterator(10000, false, rngSeed).next();
@@ -121,12 +128,15 @@ public static void main(String[] args) throws IOException {
         // (b) collect the reconstructions at each point in the grid
         net.setListeners(new PlottingListener(100, testFeatures, latentSpaceGrid, latentSpaceVsEpoch, digitsGrid));
 
-        //Perform training
+         //Perform training
+        // Train the VAE to encode and reconstruct MNIST digits
         for (int i = 0; i < nEpochs; i++) {
             log.info("Starting epoch {} of {}",(i+1),nEpochs);
             net.pretrain(trainIter);    //Note use of .pretrain(DataSetIterator) not fit(DataSetIterator) for unsupervised training
         }
 
+        // Visualize how different digit classes cluster in the latent space
+
         //plot by default
         if (visualize) {
             //Plot MNIST test set - latent space vs. iteration (every 100 minibatches by default)

dl4j-examples/src/main/java/org/deeplearning4j/examples/quickstart/modeling/variationalautoencoder/VaeMNISTAnomaly.java

@@ -17,6 +17,10 @@
  * SPDX-License-Identifier: Apache-2.0
  ******************************************************************************/
 
+  // VaeMNISTAnomaly.java
+ // Demonstrates anomaly detection using a Variational Autoencoder (VAE).
+// Normal digits reconstruct well, anomalies reconstruct poorly.
+
 package org.deeplearning4j.examples.quickstart.modeling.variationalautoencoder;
 
 import org.deeplearning4j.datasets.iterator.impl.MnistDataSetIterator;
@@ -94,6 +98,9 @@ public static void main(String[] args) throws IOException {
                 .build())
             .build();
 
+            // Load trained VAE model and MNIST test data
+
+
         MultiLayerNetwork net = new MultiLayerNetwork(conf);
         net.init();
 
@@ -151,6 +158,10 @@ public int compare(Pair<Double, INDArray> o1, Pair<Double, INDArray> o2) {
             Collections.sort(list, c);
         }
 
+         // Compute reconstruction probability for each test image
+        // Low probability indicates an anomaly
+    
+
         //Select the 5 best and 5 worst numbers (by reconstruction probability) for each digit
         List<INDArray> best = new ArrayList<>(50);
         List<INDArray> worst = new ArrayList<>(50);