add comments: utils and options

Author: junyanz

data/aligned_dataset.py

@@ -17,7 +17,7 @@ def __init__(self, opt):
         """Initialize this dataset class.
 
         Parameters:
-            opt -- options (needs to be a subclass of BaseOptions)
+            opt -- stores all the experiment flags; needs to be a subclass of BaseOptions
         """
         BaseDataset.__init__(self, opt)
         self.dir_AB = os.path.join(opt.dataroot, opt.phase)  # get the image directory

data/base_dataset.py

@@ -22,7 +22,7 @@ def __init__(self, opt):
         """Initialize the class; save the options in the class
 
         Parameters:
-            opt -- options (needs to be a subclass of BaseOptions)
+            opt -- stores all the experiment flags; needs to be a subclass of BaseOptions
         """
         self.opt = opt
         self.root = opt.dataroot

data/single_dataset.py

@@ -13,7 +13,7 @@ def __init__(self, opt):
         """Initialize this dataset class.
 
         Parameters:
-            opt -- options (needs to be a subclass of BaseOptions)
+            opt -- stores all the experiment flags; needs to be a subclass of BaseOptions
         """
         BaseDataset.__init__(self, opt)
         self.A_paths = sorted(make_dataset(opt.dataroot, opt.max_dataset_size))

data/template_dataset.py

@@ -37,7 +37,8 @@ def __init__(self, opt):
         """Initialize this dataset class.
 
         Parameters:
-            opt -- training/test options
+            opt -- stores all the experiment flags; needs to be a subclass of BaseOptions
+
         A few things can be done here.
         - save the options (have been done in BaseDataset)
         - get image paths and meta information of the dataset.

data/unaligned_dataset.py

@@ -20,7 +20,7 @@ def __init__(self, opt):
         """Initialize this dataset class.
 
         Parameters:
-            opt -- options (needs to be a subclass of BaseOptions)
+            opt -- stores all the experiment flags; needs to be a subclass of BaseOptions
         """
         BaseDataset.__init__(self, opt)
         self.dir_A = os.path.join(opt.dataroot, opt.phase + 'A')  # create a path '/path/to/data/trainA'

docs/overview.md

@@ -29,7 +29,7 @@ To help users better understand and use our codebase, we briefly overview the fu
 * [networks.py](../models/networks.py) module implements network architectures (both generators and discriminators), as well as normalization layers, initialization methods, optimization scheduler (i.e., learning rate policy), and GAN objective function (`vanilla`, `lsgan`, `wgangp`).
 * [test_model.py](../models/test_model.py) implements a model that can be used to generate CycleGAN results for only one direction. This option will automatically set `--dataset_mode single`, which only loads the images from one set. See the test [instruction](https://github.com/junyanz/pytorch-CycleGAN-and-pix2pix#apply-a-pre-trained-model-cyclegan) for more details.
 
-[options](../options) directory includes our option modules: training options, test options and, basic options (used in both training and test). `TrainOptions` and `TestOptions` are both subclasses of `BaseOptions`. They will reuse the options defined in `BaseOptions`.
+[options](../options) directory includes our option modules: training options, test options, and basic options (used in both training and test). `TrainOptions` and `TestOptions` are both subclasses of `BaseOptions`. They will reuse the options defined in `BaseOptions`.
 * [\_\_init\_\_.py](../options/__init__.py)  is required to make Python treat the directory `options` as containing packages,
 * [base_options.py](../options/base_options.py) includes options that are used in both training and test. It also implements a few helper functions such as parsing, printing, and saving the options. It also gathers additional options defined in `modify_commandline_options` functions in both dataset class and model class.
 * [train_options.py](../options/train_options.py) includes options that are only used during training time.
@@ -41,5 +41,5 @@ To help users better understand and use our codebase, we briefly overview the fu
   * [get_data.py](../util/get_data.py) provides a Python script for downloading CycleGAN and pix2pix datasets.  Alternatively, You can also use bash scripts such as [download_pix2pix_model.sh](../scripts/download_pix2pix_model.sh) and [download_cyclegan_model.sh](../scripts/download_cyclegan_model.sh).
   * [html.py](../util/html.py) implements a module that saves images into a single HTML file.  It consists of functions such as `add_header` (add a text header to the HTML file), `add_images` (add a row of images to the HTML file), `save` (save the HTML to the disk). It is based on Python library `dominate`, a Python library for creating and manipulating HTML documents using an elegant DOM API.
   * [image_pool.py](../util/image_pool.py) implements an image buffer that stores previously generated images. This buffer enables us to update discriminators using a history of generated images rather than the ones produced by the latest generators. The original idea was discussed in this [paper](http://openaccess.thecvf.com/content_cvpr_2017/papers/Shrivastava_Learning_From_Simulated_CVPR_2017_paper.pdf). The size of the buffer is controlled by the flag `--pool_size`.
-  * [visualizer.py](../util/visualizer.py) includes several functions to display and save images as well as print and save logging information. It is based on Python library `visdom` display.
-  * [util.py](../util/util.py) consists of simple helper functions such as `tensor2im` (convert a tensor array to a numpy image array), `diagnose_network` (print the mean and stddev of weights for each layer), and `mkdirs` (create multiple directories).
+  * [visualizer.py](../util/visualizer.py) includes several functions that can display/save images and print/save logging information. It uses a Python library `visdom` for display and a Python library `dominate` (wrapped in `HTML`) for creating HTML files with images.
+  * [util.py](../util/util.py) consists of simple helper functions such as `tensor2im` (convert a tensor array to a numpy image array), `diagnose_network` (calculate and print the mean of average absolute value of gradients), and `mkdirs` (create multiple directories).

options/__init__.py

@@ -0,0 +1 @@
+"""This package options includes option modules: training options, test options, and basic options (used in both training and test)."""

options/base_options.py

@@ -7,10 +7,18 @@
 
 
 class BaseOptions():
+    """This class defines options that are used during both training and test time.
+
+    It also implements several helper functions such as parsing, printing, and saving the options.
+    It also gathers additional options defined in <modify_commandline_options> functions in both dataset class and model class.
+    """
+
     def __init__(self):
+        """Reset the class; indicates the class hasn't been initailized"""
         self.initialized = False
 
     def initialize(self, parser):
+        """Define the common options that are used in both training and test."""
         # basic parameters
         parser.add_argument('--dataroot', required=True, help='path to images (should have subfolders trainA, trainB, valA, valB, etc)')
         parser.add_argument('--name', type=str, default='experiment_name', help='name of the experiment. It decides where to store samples and models')
@@ -50,10 +58,13 @@ def initialize(self, parser):
         return parser
 
     def gather_options(self):
-        # initialize parser with basic options
-        if not self.initialized:
-            parser = argparse.ArgumentParser(
-                formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+        """Initialize our parser with basic options(only once).
+        Add additional model - specific and dataset - specific options.
+        These options are difined in the < modify_commandline_options > function
+        in model and dataset classes.
+        """
+        if not self.initialized:  # check if it has been initalized
+            parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter)
             parser = self.initialize(parser)
 
         # get the basic options
@@ -63,18 +74,23 @@ def gather_options(self):
         model_name = opt.model
         model_option_setter = models.get_option_setter(model_name)
         parser = model_option_setter(parser, self.isTrain)
-        opt, _ = parser.parse_known_args()  # parse again with the new defaults
+        opt, _ = parser.parse_known_args()  # parse again with new defaults
 
         # modify dataset-related parser options
         dataset_name = opt.dataset_mode
         dataset_option_setter = data.get_option_setter(dataset_name)
         parser = dataset_option_setter(parser, self.isTrain)
 
+        # save and return the parser
         self.parser = parser
-
         return parser.parse_args()
 
     def print_options(self, opt):
+        """Print and save options
+
+        It will print both current options and default values(if different).
+        It will save options into a text file / [checkpoints_dir] / opt.txt
+        """
         message = ''
         message += '----------------- Options ---------------\n'
         for k, v in sorted(vars(opt).items()):
@@ -95,7 +111,7 @@ def print_options(self, opt):
             opt_file.write('\n')
 
     def parse(self):
-
+        """Parse our options, create checkpoints directory suffix, and set up gpu device."""
         opt = self.gather_options()
         opt.isTrain = self.isTrain   # train or test
 

options/test_options.py

@@ -2,16 +2,21 @@
 
 
 class TestOptions(BaseOptions):
+    """This class includes options that are only used during test time.
+
+    It also includes shared options defined in BaseOptions.
+    """
+
     def initialize(self, parser):
-        parser = BaseOptions.initialize(self, parser)
+        parser = BaseOptions.initialize(self, parser)  # define shared options
         parser.add_argument('--ntest', type=int, default=float("inf"), help='# of test examples.')
         parser.add_argument('--results_dir', type=str, default='./results/', help='saves results here.')
         parser.add_argument('--aspect_ratio', type=float, default=1.0, help='aspect ratio of result images')
         parser.add_argument('--phase', type=str, default='test', help='train, val, test, etc')
-        #  Dropout and Batchnorm has different behavioir during training and test.
+        # Dropout and Batchnorm has different behavioir during training and test.
         parser.add_argument('--eval', action='store_true', help='use eval mode during test time.')
         parser.add_argument('--num_test', type=int, default=50, help='how many test images to run')
-
+        # rewrite devalue values
         parser.set_defaults(model='test')
         # To avoid cropping, the load_size should be the same as crop_size
         parser.set_defaults(load_size=parser.get_default('crop_size'))

options/train_options.py

@@ -2,8 +2,14 @@
 
 
 class TrainOptions(BaseOptions):
+    """This class includes options that are only used during training time.
+
+    It also includes shared options defined in BaseOptions.
+    """
+
     def initialize(self, parser):
         parser = BaseOptions.initialize(self, parser)
+        # visdom and HTML visualization parameters
         parser.add_argument('--display_freq', type=int, default=400, help='frequency of showing training results on screen')
         parser.add_argument('--display_ncols', type=int, default=4, help='if positive, display all images in a single visdom web panel with certain number of images per row.')
         parser.add_argument('--display_id', type=int, default=1, help='window id of the web display')
@@ -12,19 +18,21 @@ def initialize(self, parser):
         parser.add_argument('--display_port', type=int, default=8097, help='visdom port of the web display')
         parser.add_argument('--update_html_freq', type=int, default=1000, help='frequency of saving training results to html')
         parser.add_argument('--print_freq', type=int, default=100, help='frequency of showing training results on console')
+        parser.add_argument('--no_html', action='store_true', help='do not save intermediate training results to [opt.checkpoints_dir]/[opt.name]/web/')
+        # network saving and loading parameters
         parser.add_argument('--save_latest_freq', type=int, default=5000, help='frequency of saving the latest results')
         parser.add_argument('--save_epoch_freq', type=int, default=5, help='frequency of saving checkpoints at the end of epochs')
         parser.add_argument('--save_by_iter', action='store_true', help='whether saves model by iteration')
         parser.add_argument('--continue_train', action='store_true', help='continue training: load the latest model')
         parser.add_argument('--epoch_count', type=int, default=1, help='the starting epoch count, we save the model by <epoch_count>, <epoch_count>+<save_latest_freq>, ...')
         parser.add_argument('--phase', type=str, default='train', help='train, val, test, etc')
+        # training parameters
         parser.add_argument('--niter', type=int, default=100, help='# of iter at starting learning rate')
         parser.add_argument('--niter_decay', type=int, default=100, help='# of iter to linearly decay learning rate to zero')
         parser.add_argument('--beta1', type=float, default=0.5, help='momentum term of adam')
         parser.add_argument('--lr', type=float, default=0.0002, help='initial learning rate for adam')
         parser.add_argument('--gan_mode', type=str, default='lsgan', help='the type of GAN objective. [vanilla| lsgan ｜ wgangp]. vanilla GAN loss is the cross-entropy objective used in the original GAN paper.')
         parser.add_argument('--pool_size', type=int, default=50, help='the size of image buffer that stores previously generated images')
-        parser.add_argument('--no_html', action='store_true', help='do not save intermediate training results to [opt.checkpoints_dir]/[opt.name]/web/')
         parser.add_argument('--lr_policy', type=str, default='lambda', help='learning rate policy. [lambda | step | plateau | cosine]')
         parser.add_argument('--lr_decay_iters', type=int, default=50, help='multiply by a gamma every lr_decay_iters iterations')