{"id":15293008,"url":"https://github.com/ryanlucas3/hr_neural_networks","last_synced_at":"2025-05-07T03:46:00.371Z","repository":{"id":65586240,"uuid":"595169917","full_name":"RyanLucas3/HR_Neural_Networks","owner":"RyanLucas3","description":"Certified robustness of deep neural networks","archived":false,"fork":false,"pushed_at":"2024-08-20T21:34:36.000Z","size":5929,"stargazers_count":19,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T03:45:38.353Z","etag":null,"topics":["deep-learning","pytorch"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RyanLucas3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-30T14:43:49.000Z","updated_at":"2024-10-28T05:35:09.000Z","dependencies_parsed_at":"2024-08-21T21:18:57.673Z","dependency_job_id":null,"html_url":"https://github.com/RyanLucas3/HR_Neural_Networks","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RyanLucas3%2FHR_Neural_Networks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RyanLucas3%2FHR_Neural_Networks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RyanLucas3%2FHR_Neural_Networks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RyanLucas3%2FHR_Neural_Networks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RyanLucas3","download_url":"https://codeload.github.com/RyanLucas3/HR_Neural_Networks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252810274,"owners_count":21807759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","pytorch"],"created_at":"2024-09-30T16:37:41.689Z","updated_at":"2025-05-07T03:46:00.336Z","avatar_url":"https://github.com/RyanLucas3.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Holistic Robust (HR) Neural Networks\n\n\u003cp align=\"left\"\u003e\n  \u003cimg width=\"150\" height=\"40\" src=\"Misc/python.svg\"\u003e\n   \u003cimg width=\"180\" height=\"40\" src=\"Misc/tf.svg\"\u003e\n    \u003cimg width=\"150\" height=\"40\" src=\"Misc/pt_badge.svg\"\u003e\n\u003c/p\u003e\n\n```python\npip install HR_Neural_Networks\n```\n\n### This code base is an open-source implementation of the paper [\"Certified Robust Neural Networks: Generalization and Corruption Resistance\"](https://arxiv.org/pdf/2303.02251.pdf).\n\nHolistic Robust Learning (HR) is a learning approach which provides _certified_ protection against data poisoning and evasion attacks, while enjoying _guaranteed_ generalization. HR minimizes a loss function that is guaranteed to be an upper bound on the out-of-sample performance of the trained networks with high probability. Hence, when training with HR, the out-of-sample performance is at least as good as the observed in-sample performance. This is both guaranteed theoretically and verified empirically.\nRobustness is controlled by three parameters: \n* $\\alpha$: controls protection against generic data poisoning at training time. This encompasses any kind of corruption in the training data; for instance training examples that have been obscured or which are wholly misspecified. For a given chosen $\\alpha$, HR is certified when up to a fraction $\\alpha$ of data points are corrupted.\n* $\\epsilon$: controls protection against small perturbations to the testing or training examples, such as noise or evasive attacks. HR is certified to any adversarial attacks limited to the norm ball { $\\delta: ||\\delta|| \\leq \\epsilon$ }. The current implementation supports $\\ell_2$ and $\\ell_\\infty$ balls.\n* $r$: controls protection against overfitting to the training instances. The parameter sets the desired strength of generalization and the conservativeness of training. It also reduces variance to randomness of the training data. HR in-sample loss is guaranteed to be an upper bound on the out-of-sample loss with probability $1-e^{-nr +O(1)}$ where $n$ is the data size.\n\nWe provide a robust loss function that can be automatically differentiated in Pytorch. If not using Pytorch, we also provide framework-agnostic importance weights that can be integrated with Tensorflow or another deep learning library. Doing so involves minimal disruption to standard training pipelines.\n\nClick here for a **Colab tutorial applying HR for MNIST classification**: \n\n\u003cp align=\"left\"\u003e\u003ca href= \"https://colab.research.google.com/drive/1d5BZvCDGWHS_UxFR77YneKGB3mMGR-tY?usp=sharing\"\u003e\n  \u003cimg width=\"247.8\" height=\"42.6\" src=\"Misc/colab.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n## Training of HR Neural Networks in Pytorch\n\nHR can be implemented for neural network training with minimal disruption to typical training pipelines. The core output of the code is a Pytorch loss function which can be optimized via ordinary backpropagation commands. For example, see below for a contrast between regular training and HR training where the difference is basically in one line.\n \n### Natural training\n\n```python\n\nimport torch.nn as nn\n\ncriterion = nn.CrossEntropyLoss(reduction=\"mean\")\n\ndef train(model, device, train_loader, optimizer, epoch):\n    model.train()\n    for batch_idx, (data, target) in enumerate(train_loader):\n        data, target = data.to(device), target.to(device)\n        optimizer.zero_grad()\n        loss = criterion(model(data), target)\n        loss.backward()\n        optimizer.step()\n        \n ```\n\n### HR training\nYou can install HR simply with a `pip` command\n\n```python\npip install HR_Neural_Networks\n```\n\nTraining with the HR loss requires then only to change one line of the training code.\n\n```python\n\nimport torch.nn as nn\n\ncriterion = nn.CrossEntropyLoss(reduction = 'none') # note the change from mean -\u003e none\n\n########### HR Model Instantiation ###############\n\nfrom HR_Neural_Networks.HR import * \n\nα_choice = 0.05 \nr_choice = 0.1\nϵ_choice = 0.5\n       \nHR = HR_Neural_Networks(NN_model = model,\n                        train_batch_size = 128,\n                        loss_fn = criterion,\n                        normalisation_used = None,\n                        α_choice = α_choice, \n                        r_choice = r_choice,\n                        ϵ_choice = ϵ_choice)\n\n########### Training Loop ###############\n\ndef train(HR, model, device, train_loader, optimizer, epoch):\n    model.train()\n    for batch_idx, (data, target) in enumerate(train_loader):\n        data, target = data.to(device), target.to(device)\n        optimizer.zero_grad()\n\n        HR_loss = HR.HR_criterion(inputs = data, targets = target, device = device)\n\n        HR_loss.backward()\n        optimizer.step()\n```\n\n## Background\n\nHR considers the following setting of learning under corruption: $n$ data points are first sampled from a true clean distribution $\\mathcal{D}$ and then less than $\\alpha n$ data points are corrupted (poisoning attacks), resulting in an observed corrupted empirical distribution \n$\\mathcal{D}\\_n$\nconstituting training data. At test time, samples from $\\mathcal{D}$ are perturbed with noise in a set $\\mathcal{N}$ (evasive attacks), and the model is tested with distribution $\\mathcal{D}\\_{\\text{test}}$ of perturbed instances.\n\nHR seeks to minimizes an upper bound on the testing loss constructed using the provided corrupted training data. This upper bound–HR loss–is designed using distributionally robust optimization (DRO), by constructing an ambiguity set $\\mathcal{U}\\_{\\mathcal{N}, \\alpha, r}(\\mathcal{D}\\_n)$ around the corrupted empirical distribution $\\mathcal{D}\\_n$ and optimizing the worst-case loss over distributions realizing in this set. The ambiguity set is constructed to contain the testing distribution $\\mathcal{D}\\_{\\text{test}}$ with high probability. The HR loss writes therefore as\n\n```math\n\\begin{equation}\n\\max_{\\mathcal{D}' \\in \\mathcal{U}_{\\mathcal{N}, \\alpha, r}(\\mathcal{D}_n)} \\mathbb{E}_{(X, Y) \\sim \\mathcal{D}'}[\\ell(\\theta, X, Y)]\n\\end{equation}\n```\nwhere $\\ell$ is the given loss function and $\\theta$ the network's parameters.\n\nThe HR objective function is an upper bound on the test performance with probability $1-e^{-rn+O(1)}$ when less then a fraction $\\alpha$ of all $n$ samples are tampered by poisoning, and the evasion corruption is bounded within the set $\\mathcal{N}$.\nThe parameters $\\mathcal{N}, r$ and $\\alpha$ hence are important design choices and directly reflect the desired robustness. In this implementation, we chose $\\mathcal{N} =$ { $\\delta: ||\\delta|| \\leq \\epsilon $}.\n\nThe HR loss is also proven to be a ``tight'' upper bound. That is, corruption and generalization are efficiently captured and the provided robustness is not overly conservative. In particular, HR captures efficiently the interaction between generalization and corruption. \nFor example, when used in conjunction $\\mathcal{N}$ and $r$ can provide protection to the well-known phenomenon of  [robust overfitting](https://arxiv.org/abs/2002.11569), where adversarial training exhibit severe overfitting.\n\n## Reference\n```\n@article{bennouna2023certified,\n  title={Certified Robust Neural Networks: Generalization and Corruption Resistance},\n  author={Bennouna, Amine and Lucas, Ryan and Van Parys, Bart},\n  journal={arXiv preprint arXiv:2303.02251},\n  year={2023}\n}\n```\n\nPlease contact amineben@mit.edu and ryanlu@mit.edu if you have any question about the paper or the codes.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanlucas3%2Fhr_neural_networks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryanlucas3%2Fhr_neural_networks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanlucas3%2Fhr_neural_networks/lists"}