Initial Commit

.gitignore

@@ -0,0 +1,104 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "src/cox"]
+	path = src/cox
+	url = git@github.com:andrewilyas/cox.git

README.rst

@@ -0,0 +1,137 @@
+robustness package
+==================
+``robustness`` is a package we (students in the `MadryLab <http://madry-lab.ml>`_) created
+to make training, evaluating, and exploring neural networks flexible and easy.
+We use it in almost all of our projects (whether they involve
+adversarial training or not!) and it will be a dependency in many of our
+upcoming code releases. A few projects using the library include:
+
+- `Code <https://github.com/MadryLab/robust_representations>`_  for
+  "Learning Perceptually-Aligned Representations via Adversarial Robustness"
+  [EIS+19]_ 
+- `Code <https://github.com/MadryLab/robustness_applications>`_ for
+  "Image Synthesis with a Single (Robust) Classifier" [STE+19]_
+
+*(Have you used the package and found it useful? Let us know!)*. We
+demonstrate how to use the library in a set of walkthroughs and our API
+reference. Functionality provided by the library includes:
+
+- Training and evaluating standard and robust models for a variety of
+  datasets/architectures using a :doc:`CLI interface
+  <example_usage/cli_usage>`. The library also provides support for adding
+  :doc:`custom datasets and model architectures
+  <example_usage/training_lib_part_2#TODO>`.
+
+.. code-block:: bash
+
+   python -m robustness.main --dataset cifar --data /path/to/cifar \
+      --adv-train 0 --arch resnet18 --out-dir /logs/checkpoints/dir/
+
+- Performing :doc:`input manipulation
+  <example_usage/input_space_manipulation>` using robust (or standard)
+  models---this includes making adversarial examples, inverting representations,
+  feature visualization, etc. The library offers a variety of optimization
+  options (e.g. choice between real/estimated gradients, Fourier/pixel basis,
+  custom loss functions etc.), and is easily extendable.
+
+.. code-block:: python
+   
+   import torch as ch
+   from robustness.datasets import CIFAR
+   from robustness.model_utils import make_and_restore_model
+
+   ds = CIFAR('/path/to/cifar')
+   model, _ = make_and_restore_model(arch='resnet50', dataset=ds, 
+                resume_path='/path/to/model', state_dict_path='model')
+   model.eval()
+   attack_kwargs = {
+      'constraint': 'inf', # L-inf PGD 
+      'eps': 0.05, # Epsilon constraint (L-inf norm)
+      'step_size': 0.01, # Learning rate for PGD
+      'iterations': 100, # Number of PGD steps
+      'targeted': True # Targeted attack
+      'custom_loss': None # Use default cross-entropy loss
+   }
+
+   _, test_loader = ds.make_loaders(workers=0, batch_size=10)
+   im, label = next(iter(test_loader))
+   target_label = (label + ch.randint_like(label, high=9)) % 10
+   adv_out, adv_im = model(im, target_label, make_adv, **attack_kwargs)
+
+- Importing :samp:`robustness` as a package, which allows for easy training of
+  neural networks with support for custom loss functions, logging, data loading,
+  and more! A good introduction can be found in :doc:`this walkthrough
+  <example_usage/use_as_training_lib>`.
+
+.. code-block:: python
+
+   from robustness import model_utils, datasets, train, defaults
+   from robustness.datasets import CIFAR
+
+   # We use cox (http://github.com/MadryLab/cox) to log, store and analyze 
+   # results. Read more at https//cox.readthedocs.io.
+   from cox.utils import Parameters
+   import cox.store
+
+   # Hard-coded dataset, architecture, batch size, workers
+   ds = CIFAR('/path/to/cifar')
+   m, _ = model_utils.make_and_restore_model(arch='resnet50', dataset=ds)
+   train_loader, val_loader = ds.make_loaders(batch_size=128, workers=8)
+
+   # Create a cox store for logging
+   out_store = cox.store.Store(OUT_DIR)
+
+   # Hard-coded base parameters
+   train_kwargs = {
+       'out_dir': "train_out",
+       'adv_train': 1,
+       'constraint': '2',
+       'eps': 0.5,
+       'attack_lr': 1.5,
+       'attack_steps': 20
+   }
+   train_args = Parameters(train_kwargs)
+
+   # Fill whatever parameters are missing from the defaults
+   train_args = defaults.check_and_fill_args(train_args,
+                           defaults.TRAINING_ARGS, CIFAR)
+   train_args = defaults.check_and_fill_args(train_args,
+                           defaults.PGD_ARGS, CIFAR)
+
+   # Train a model
+   train.train_model(train_args, m, (train_loader, val_loader), store=out_store)
+
+Citation
+--------
+If you use this library in your research, cite it as
+follows:
+
+.. code-block:: bibtex
+   
+   @misc{robustness,
+      title={Robustness},
+      author={},
+      year={2019},
+      url={git.io/robustness-lib}
+   }
+
+Walkthroughs
+------------
+
+.. toctree::
+   example_usage/cli_usage
+   example_usage/input_space_manipulation
+   example_usage/use_as_training_lib
+
+API Reference
+-------------
+
+We provide an API reference where we discuss the role of each module and
+provide extensive documentation.
+
+.. toctree::
+   api
+
+.. [EIS+19] Engstrom L., Ilyas A., Santurkar S., Tsipras D., Tran B., Madry A. (2019). Learning Perceptually-Aligned Representations via Adversarial Robustness. arXiv, arXiv:1906.00945 
+
+.. [STE+19] Santurkar S., Tsipras D., Tran B., Ilyas A., Engstrom L., Madry A. (2019). Image Synthesis with a Single (Robust) Classifier. arXiv, arXiv:1906.09453

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,15 @@
+API Reference
+=============
+
+.. toctree::
+   api/robustness.attack_steps
+   api/robustness.attacker
+   api/robustness.data_augmentation
+   api/robustness.datasets
+   api/robustness.defaults
+   api/robustness.loaders
+   api/robustness.main
+   api/robustness.model_utils
+   api/robustness.train  
+   api/robustness.tools
+

docs/api/robustness.attack_steps.rst

@@ -0,0 +1,7 @@
+robustness.attack\_steps module
+===============================
+
+.. automodule:: robustness.attack_steps
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.attacker.rst

@@ -0,0 +1,7 @@
+robustness.attacker module
+==========================
+
+.. automodule:: robustness.attacker
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.data_augmentation.rst

@@ -0,0 +1,7 @@
+robustness.data\_augmentation module
+====================================
+
+.. automodule:: robustness.data_augmentation
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.datasets.rst

@@ -0,0 +1,7 @@
+robustness.datasets module
+==========================
+
+.. automodule:: robustness.datasets
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.defaults.rst

@@ -0,0 +1,7 @@
+robustness.defaults module
+==========================
+
+.. automodule:: robustness.defaults
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.loaders.rst

@@ -0,0 +1,7 @@
+robustness.loaders module
+=========================
+
+.. automodule:: robustness.loaders
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.main.rst

@@ -0,0 +1,7 @@
+robustness.main module
+======================
+
+.. automodule:: robustness.main
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.model_utils.rst

@@ -0,0 +1,7 @@
+robustness.model\_utils module
+==============================
+
+.. automodule:: robustness.model_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.tools.constants.rst

@@ -0,0 +1,7 @@
+robustness.tools.constants module
+=================================
+
+.. automodule:: robustness.tools.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.tools.folder.rst

@@ -0,0 +1,7 @@
+robustness.tools.folder module
+==============================
+
+.. automodule:: robustness.tools.folder
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.tools.helpers.rst

@@ -0,0 +1,7 @@
+robustness.tools.helpers module
+===============================
+
+.. automodule:: robustness.tools.helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/robustness.tools.label_maps.rst

@@ -0,0 +1,7 @@
+robustness.tools.label\_maps module
+===================================
+
+.. automodule:: robustness.tools.label_maps
+   :members:
+   :undoc-members:
+   :show-inheritance: