Metadata-Version: 2.1
Name: robustness
Version: 1.0
Summary: Tools for Robustness
Home-page: UNKNOWN
Author: MadryLab
Author-email: ailyas@mit.edu
License: MIT
Keywords: logging tools madrylab
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: tqdm
Requires-Dist: grpcio
Requires-Dist: psutil
Requires-Dist: gitpython
Requires-Dist: py3nvml

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 for "Learning Perceptually-Aligned Representations via Adversarial Robustness" <https://github.com/MadryLab/robust_representations>`_ (https://arxiv.org/abs/1906.00945) 
- `Code for
  "Image Synthesis with a Single (Robust) Classifier" <https://github.com/MadryLab/robustness_applications>`_ (https://arxiv.org/abs/1906.09453)

*(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 `CLI interface
  <https://robustness.readthedocs.io/en/latest/example_usage/cli_usage.html>`_. The library also provides support for adding
  `custom datasets <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_2.html#training-on-custom-datasets>`_ and `model architectures <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_2.html#training-with-custom-architectures>`_.

.. code-block:: bash

   python -m robustness.main --dataset cifar --data /path/to/cifar \
      --adv-train 0 --arch resnet18 --out-dir /logs/checkpoints/dir/

- Performing `input manipulation
  <https://robustness.readthedocs.io/en/latest/example_usage/input_space_manipulation.html>`_ 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 ``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 our two-part walkthrough
  (`Part 1 <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_1.html>`_, 
  `Part 2 <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_2.html>`_).

.. 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}
   }

Documentation
--------------
https://robustness.readthedocs.io/en/latest/index.html



