add readme and comments in demo/gan

demo/gan/README.md

@@ -0,0 +1,12 @@
+# Generative Adversarial Networks (GAN) 
+
+This demo implements GAN training described in the original GAN paper (https://arxiv.org/abs/1406.2661) and DCGAN (https://arxiv.org/abs/1511.06434).
+
+The general training procedures are implemented in gan_trainer.py. The neural network configurations are specified in gan_conf.py (for synthetic data) and gan_conf_image.py (for image data).
+
+In order to run the model, first download the corresponding data by running the shell script in ./data.
+Then you can run the command below. The flag -d specifies the training data (cifar, mnist or uniform) and flag --useGpu specifies whether to use gpu for training (0 is cpu, 1 is gpu).  
+
+$python gan_trainer_image.py -d cifar --useGpu 1
+
+The generated images will be stored in ./cifar_samples/

demo/gan/gan_conf.py

@@ -25,8 +25,11 @@ is_generator = mode == "generator"
 is_discriminator = mode == "discriminator"
 
 print('mode=%s' % mode)
-noise_dim = 10
+# the dim of the noise (z) as the input of the generator network
+noise_dim = 10 
+# the dim of the hidden layer
 hidden_dim = 15
+# the dim of the generated sample
 sample_dim = 2
 
 settings(
@@ -123,7 +126,6 @@ if is_generator_training or is_discriminator_training:
     classification_error_evaluator(input=prob, label=label, name=mode+'_error')
     outputs(cost)
 
-    
 if is_generator:
     noise = data_layer(name="noise", size=noise_dim)
     outputs(generator(noise))

demo/gan/gan_conf_image.py

@@ -25,8 +25,14 @@ is_discriminator_training = mode == "discriminator_training"
 is_generator = mode == "generator"
 is_discriminator = mode == "discriminator"
 
+# The network structure below follows the dcgan paper 
+# (https://arxiv.org/abs/1511.06434)
+
 print('mode=%s' % mode)
+# the dim of the noise (z) as the input of the generator network
 noise_dim = 100
+# the number of filters in the layer in generator/discriminator that is 
+# closet to the image
 gf_dim = 64
 df_dim = 64
 if dataSource == "mnist":
@@ -47,6 +53,19 @@ settings(
 def conv_bn(input, channels, imgSize, num_filters, output_x, stride, name, 
                  param_attr, bias_attr, param_attr_bn, bn, trans=False, 
                  act=ReluActivation()):
+    
+    """
+    conv_bn is a utility function that constructs a convolution/deconv layer 
+    with an optional batch_norm layer
+
+    :param bn: whether to use batch_norm_layer
+    :type bn: bool
+    :param trans: whether to use conv (False) or deconv (True)
+    :type trans: bool
+    """
+    
+    # calculate the filter_size and padding size based on the given
+    # imgSize and ouput size
     tmp =  imgSize - (output_x - 1) * stride
     if tmp <= 1 or tmp > 5:
         raise ValueError("conv input-output dimension does not fit")
@@ -240,7 +259,6 @@ if is_generator_training or is_discriminator_training:
     classification_error_evaluator(input=prob, label=label, name=mode+'_error')
     outputs(cost)
 
-    
 if is_generator:
     noise = data_layer(name="noise", size=noise_dim)
     outputs(generator(noise))