{"id":13689350,"url":"https://github.com/Vermeille/Torchelie","last_synced_at":"2025-05-01T23:33:54.779Z","repository":{"id":36295173,"uuid":"196767053","full_name":"Vermeille/Torchelie","owner":"Vermeille","description":"Torchélie is a set of utility functions, layers, losses, models, trainers and other things for PyTorch.","archived":false,"fork":false,"pushed_at":"2024-05-17T09:55:23.000Z","size":1869,"stargazers_count":111,"open_issues_count":23,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-05-23T06:49:16.089Z","etag":null,"topics":["gan","loss","perceptual","pytorch","torch","utils","vqvae"],"latest_commit_sha":null,"homepage":"https://torchelie.readthedocs.org/","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/Vermeille.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2019-07-13T21:14:50.000Z","updated_at":"2024-06-06T11:00:30.661Z","dependencies_parsed_at":"2024-06-06T11:12:22.470Z","dependency_job_id":null,"html_url":"https://github.com/Vermeille/Torchelie","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vermeille%2FTorchelie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vermeille%2FTorchelie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vermeille%2FTorchelie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vermeille%2FTorchelie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vermeille","download_url":"https://codeload.github.com/Vermeille/Torchelie/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224282238,"owners_count":17285793,"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":["gan","loss","perceptual","pytorch","torch","utils","vqvae"],"created_at":"2024-08-02T15:01:44.388Z","updated_at":"2024-11-12T13:31:29.286Z","avatar_url":"https://github.com/Vermeille.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Torchélie\n\n\u003cimg src=\"https://github.com/Vermeille/Torchelie/blob/master/logo.png\" height=\"200\"/\u003e\n\n[![License from GitHub](https://img.shields.io/github/license/Vermeille/Torchelie?color=informational\u0026label=License)](https://github.com/Vermeille/Torchelie/blob/master/LICENSE)\n\n[![GitHub Actions - Tests status](https://img.shields.io/github/workflow/status/Vermeille/Torchelie/Torch%C3%A9lie%20tests?label=Tests\u0026logo=GitHub)](https://github.com/Vermeille/Torchelie/actions/workflows/tests.yml?query=branch%3Amaster)\n[![GitHub last commit](https://img.shields.io/github/last-commit/Vermeille/Torchelie?label=Last%20commit)](https://github.com/Vermeille/Torchelie/commits/master)\n[![Read the Docs build status](https://img.shields.io/readthedocs/torchelie?label=Read%20the%20Docs%20build%20status)](https://torchelie.readthedocs.io)\n\nTorchélie is a set of tools for [PyTorch](https://pytorch.org/). It includes\nlosses, optimizers, algorithms, utils, layers, models and training loops.\n\nFeedback is absolutely welcome.\n\nYou may want to [read the detailed docs](https://torchelie.readthedocs.io/en/latest/)\n\n# Installation\n\n`pip install git+https://github.com/vermeille/Torchelie`\n\nIt depends on Pytorch (obvi), and has an optional dependency on OpenCV for some\ntransforms (Canny, as of today). It also depends on Visdom for realtime\nvisualizations, plotting, etc.\n\nTo install visdom: `pip install visdom`. Then, you need to run a Visdom server\nwith `python -m visdom.server`, direct your browser to `http://localhost:8097`.\nNow you're ready to use VisdomLogger and enjoy realtime tracking of your\nexperiments.\n\n# ⚠ WARNINGS ⚠\n\n**Torchelie API is beta and can be a bit unstable**. Minor breaking changes can\nhappen.\n\nCode, README, docs and tests might be out of sync in general. Please tell me if\nyou notice anything wrong.\n\n# Torchelie Hello World\n\nLet's say you want to do the hello-world of deep learning:\n[MNIST](https://en.wikipedia.org/wiki/MNIST_database) handwritten digits\nclassification. Let's also assume that you already have your training and\ntesting datasets organised properly, e.g. coming from the\n[Kaggle](https://www.kaggle.com/jidhumohan/mnist-png) archive:\n\n```\n$ tree mnist_png\n\nmnist_png\n├── testing\n│   ├── 0\n│   ├── 1\n│   ├── 2\n│   ├── 3\n│   ├── 4\n│   ├── 5\n│   ├── 6\n│   ├── 7\n│   ├── 8\n│   └── 9\n└── training\n    ├── 0\n    ├── 1\n    ├── 2\n    │   ├── 10009.png\n    │   ├── 10016.png\n    │   └── [...]\n    ├── 3\n    ├── 4\n    ├── 5\n    ├── 6\n    ├── 7\n    ├── 8\n    └── 9\n```\n\nTorchelie comes with a `classification` \"recipe\" out-of-the-box, which can be\nused directly to train your a model **straight from the command line**:\n\n```\n$ python3 -m torchelie.recipes.classification --trainset mnist_png/training --testset mnist_png/testing\n\n[...]\n | Ep. 0 It 1 | {'lr_0': '0.0100', 'acc': '0.0938', 'loss': '3.1385'}\n | Ep. 0 It 11 | {'lr_0': '0.0100', 'acc': '0.2017', 'loss': '2.4109'}\n | Ep. 0 It 21 | {'lr_0': '0.0100', 'acc': '0.3185', 'loss': '2.0410'}\n | Ep. 0 It 31 | {'lr_0': '0.0100', 'acc': '0.3831', 'loss': '1.8387'}\n | Ep. 0 It 41 | {'lr_0': '0.0100', 'acc': '0.4451', 'loss': '1.6513'}\n[...]\nTest | Ep. 1 It 526 | [...] 'acc': '0.9799', 'loss': '0.0797' [...]\n | Ep. 1 It 556 | {'lr_0': '0.0100', 'acc': '0.9588', 'loss': '0.1362'}\n | Ep. 1 It 566 | {'lr_0': '0.0100', 'acc': '0.9606', 'loss': '0.1341'}\n```\n\nWant to run it on your laptop which doesnt have a GPU? Simply add the `--device\ncpu` option!\n\nWith a simple use case and a properly organized dataset, we already saw how\nTorchelie can help experiment quickly. But what just happened?\n\nThe `classification` **recipe** is a whole **ready-to-use training loop**\nwhich:\n\n- handles all the image loading\n- uses the ResNet18 model from [PyTorch's\n  Torchvision](https://pytorch.org/vision/stable/index.html) to classify images\n  from the training dataset\n- computes a cross entropy loss on the predicted outputs\n- uses RAdamW to optimize the model along the way\n- periodically (default every 1k iterations) assess the accuracy of the trained\n  model using the test dataset\n- gives as much insights as possible during the training through:\n    - stdout (as shown above)\n    - visdom (TODO)\n\nThe cool thing is that all these building blocks are available!\n\n## `torchelie.recipes`\n\nClasses implementing full algorithms, from training to usage\n\n* `NeuralStyleRecipe` implements Gatys' Neural Artistic Style. Also directly\n  usable with commandline with `python3 -m torchelie.recipes.neural_style`\n* `FeatureVisRecipe` implements feature visualization through backprop. The\n  image is implemented in Fourier space which makes it powerful (see\n  [this](https://distill.pub/2018/differentiable-parameterizations/) and\n  [that](https://distill.pub/2017/feature-visualization/) ). Usable as\n  commandline as well with `python -m torchelie.recipes.feature_vis`.\n* `DeepDreamRecipe` implements something close to Deep Dream.\n  `python -m torchelie.recipes.deepdream` works.\n* `Classification` trains a model for image classification. It\n  provides logging of loss and accuracy. It has a commandline interface with\n  `python3 -m torchelie.recipes.classification` to quickly train a classifier\n  on an image folder with train images and another with test images.\n\n## `torchelie.utils`\n\nFunctions:\n\n* `freeze` and `unfreeze` that changes `requires_grad` for all tensor in a\n  module.\n* `entropy(x, dim, reduce)` computes the entropy of `x` along dimension `dim`,\n  assuming it represents the unnormalized probabilities of a categorial\n  distribution.\n* `kaiming(m)` / `xavier(m)` returns `m` after a kaiming / xavier\n  initialization of `m.weight`\n* `nb_parameters` returns the number of trainables parameters in a module\n* `layer_by_name` finds a module by its (instance) name in a module\n* `gram` / `bgram` compute gram and batched gam matrices.\n* `DetachedModule` wraps a module so that it's not detected by recursive module\n  functions.\n* `FrozenModule` wraps a module, freezes it and sets it to eval mode. All calls\n  to `.train()` (even those made from enclosing modules) will be ignored.\n\n## `torchelie.nn`\n\nDebug modules:\n\n* `Dummy` does nothing to its input.\n* `Debug` doesn't modify its input but prints some statistics. Easy to spot\n  exploding or vanishing values.\n\nNormalization modules:\n\n* `ImageNetInputNorm` for normalizing images like `torchvision.model` wants\n  them.\n* `MovingAverageBN2d`, `NoAffineMABN2d` and `ConditionalMABN2d` are the same as\n  above, except they also use moving average of the statistics at train time\n  for greater stability. Useful ie for GANs if you can't use a big ass batch\n  size and BN introduces too much noise.\n* `AdaIN2d` is adaptive instancenorm for style transfer and stylegan.\n* `Spade2d` / `MovingAverageSpade2d`, for GauGAN.\n* `PixelNorm` from ProGAN and StyleGAN.\n* `BatchNorm2d`, `NoAffineBatchNorm2d` should be strictly equivalent to\n  Pytorch's, and `ConditionalBN2d` gets its weight and bias parameter from a\n  linear projection of a `z` vector.\n* `AttenNorm2d` BN with attention (Attentive Normalization, Li et al, 2019)\n\nMisc modules:\n\n* `FiLM2d` is affine conditioning `f(z) * x + g(z)`.\n* `Noise` returns `x + a * z` where `a` is a learnable scalar, and `z` is a\n  gaussian noise of the same shape of `x`\n* `Reshape(*shape)` applies `x.view(x.shape[0], *shape)`.\n* `VQ` is a VectorQuantization layer, embedding the VQ-VAE loss in its backward\n  pass for a great ease of use.\n\nContainer modules:\n\n* `CondSeq` is an extension of `nn.Sequential` that also applies a\n  second input on the layers having `condition()`\n\nModel manipulation modules:\n\n* `WithSavedActivations(model, types)` saves all activations of `model` for its\n  layers of instance `types` and returns a dict of activations in the forward\n  pass instead of just the last value. Forward takes a `detach` boolean\n  arguments if the activations must be detached or not.\n\nNet Blocks:\n\n* `MaskedConv2d` is a masked convolution for PixelCNN\n* `TopLeftConv2d` is the convolution from PixelCNN made of two conv blocks: one\n  on top, another on the left.\n* `Conv2d`, `Conv3x3`, `Conv1x1`, `Conv2dBNReLU`, `Conv2dCondBNReLU`, etc. Many\n  different convenience blocks in `torchelie.nn.blocks.py`\n* `ResNetBlock`, `PreactResNetBlock`\n* `ResBlock` is a classical residual block with batchnorm\n* `ClassConditionalResBlock`\n* `SpadeResBlock` instead uses `Spade2d`\n* `AutoGANGenBlock` is a block for AutoGAN\n* `SNResidualDiscrBlock` is a residual block with spectral normalization\n\n## `torchelie.models`\n\n* `Patch16`, `Patch32`, `Patch70`, `Patch286` are Pix2Pix's PatchGAN's\n  discriminators\n* `UNet` for image segmentation\n* `AutoGAN` generator from the paper _AutoGAN: Neural Architecture Search for\n  Generative Adversarial Networks_\n* ResNet discriminator with spectral normalization\n* `PerceptualNet` is a VGG16 with correctly named layers for more convenient\n  use with `WithSavedActivations`\n* `attention56` from Residual Attention Networks\n\nDebug models:\n\n* `VggDebug`\n* `ResNetDebug`\n* `PreactResNetDebug`\n\n## `torchelie.loss`\n\nModules:\n\n* `PerceptualLoss(l)` is a vgg16 based perceptual loss up to layer number `l`.\n  Sum of L1 distances between `x`'s and `y`'s activations in vgg. Only `x` is\n  backproped.\n* `NeuralStyleLoss`\n* `OrthoLoss` orthogonal loss.\n* `TotalVariationLoss` TV prior on 2D images.\n* `ContinuousCEWithLogits` is a Cross Entropy loss that allows non categorical\n  targets.\n* `TemperedCrossEntropyLoss` from _Robust Bi-Tempered Logistic Loss Based on\n  Bregman Divergences_ (Amid et al, 2019)\n\nFunctions (`torchelie.loss.functional`):\n\n* `ortho(x)` applies an orthogonal regularizer as in _Brock et al (2018)_\n  (BigGAN)\n* `total_variation(x)` applies a spatial L1 loss on 2D tensors\n* `continuous_cross_entropy`\n* `tempered_cross_entropy` from _Robust Bi-Tempered Logistic Loss Based on\n  Bregman Divergences_ (Amid et al, 2019)\n\n### `torchelie.loss.gan`\n\nEach submodule is a GAN loss function. They all contain three methods:\n`real(x)` and `fake(x)` to train the discriminator, and `ŋenerated(x)` to\nimprove the Generator.\n\nAvailable:\n\n* Standard loss (BCE)\n* Hinge\n\n## `torchelie.transforms`\n\nTorchvision-like transforms:\n\n* `ResizeNoCrop` resizes the _longest_ border of an image ot a given size,\n  instead of torchvision that resize the smallest side. The image is then\n  _smaller_ than the given size and needs padding for batching.\n* `AdaptPad` pads an image so that it fits the target size.\n* `Canny` runs canny edge detector (requires OpenCV)\n* `MultiBranch` allows different transformations branches in order to transform\n  the same image in different ways. Useful for self supervision tasks for\n  instance.\n* `ResizedCrop`: deterministic version of\n  `torchvision.transforms.RandomResizedCrop`\n\n### `torchelie.transforms.differentiable`\n\nContains some transforms that can be backpropagated through. Its API is\nunstable now.\n\n## `torchelie.lr_scheduler`\n\nClasses:\n\n* `CurriculumScheduler` takes a lr schedule and an optimizer as argument. Call\n  `sched.step()` on each batch. The lr will be interpolated linearly between\n  keypoints.\n* `OneCycle` implements 1cycle policy\n\n## `torchelie.datasets`\n\n* `HorizontalConcatDataset` concatenates multiple datasets. However, while\n  torchvision's ConcatDataset just concatenates samples, torchelie's also\n  relabels classes. While a vertical concat like torchvision's is useful to add\n  more examples per class, an horizontal concat merges datasets to more\n  classes.\n* `PairedDataset` takes to datasets and returns the cartesian products of its\n  samples.\n* `MixUpDataset` takes a dataset, sample all pairs and interpolates samples\n  and labels with a random mixing value.\n* `NoexceptDataset` wraps a dataset and suppresses the exceptions raised while\n  loading samples. Useful in case of a big downloaded dataset with corrupted\n  samples for instance.\n* `WithIndexDataset` returns the sample's index as well. Useful if you want to\n  retrieve the sample or associate something to it.\n* `CachedDataset` lazily caches a dataset so that next iterations won't access\n  the original storage or recompute the initial dataset's transforms\n\n## `torchelie.datasets.debug`\n\n* `ColoredColumns` / `ColoredRows` are datasets of precedurally generated\n  images of rows / columns randomly colorized.\n\n## `torchelie.metrics`\n\n* `WindowAvg`: averages measures over a k-long sequence\n* `ExponentialAvg`: applies an exponential averaging method over measures\n* `RunningAvg`: accumulates total number of items and sum to provide an\n  accurate average estimation\n\n## `torchelie.opt`\n\n* `DeepDreamOptim` is the optimizer used by DeepDream\n* `AddSign` from _Neural Optimiser search with Reinforcment learning_\n* `RAdamW` from _On the Variance of the Adaptive Learning Rate and Beyond_,\n  with AdamW weight decay fix.\n* `Lookahead` from `Lookahead Optimizer: k steps forward, 1 step back`\n\n## `torchelie.data_learning`\n\nData parameterization for optimization, like neural style or feature viz.\n\nModules:\n\n* `PixelImage` an image to be optimized.\n* `SpectralImage` an image Fourier-parameterized to ease optimization.\n* `CorrelateColors` assumes the input is an image with decorrelated color\n  components. It correlates back the color using some ImageNet precomputed\n  correlation statistics to ease optimization.\n\n# Testing\n\n* `classification.py` tests bones for classifiers on MNIST or CIFAR10\n* `conditional.py` tests class conditional layers with a conditional\n  classification task `argmin L(f(x, z), y)` where `x` is a MNIST sample, `z` a\n  class label, and `y = 1` if `z` is the correct label for `x`, 0 otherwise.\n\n## Testing without OpenCV\n\nSince OpenCV is an optional dependency, you might want to run tests in such a\nsetup (therefore not testing Canny). You can do so by excluding the\n`require_opencv` [pytest custom\nmarker](https://docs.pytest.org/en/stable/example/markers.html) like so:\n\n```shell\npytest -m \"not require_opencv\"\n```\n\n# Contributing\n\n## Code format\n\nCode is formatted using [**YAPF**](https://github.com/google/yapf).\n\nFor now, the CI doesn't check for code format, and the config files for yapf\nisn't there, but do your best to format your code using YAPF (or at least\ncomply with [**PEP8**](https://www.python.org/dev/peps/pep-0008/) 🙂)\n\n## Lint\n\nCode is linted using [**Flake8**](https://pypi.org/project/flake8/). Do your\nbest to send code that don't make it scream too loud 😉\n\nYou can run it like this:\n\n```shell\nflake8 torchelie\n```\n\n## Type checking\n\nDespite typing being optional in Python, type hints can save a lot of time on a\nproject such as Torchélie. This project is type-checked using\n[**mypy**](http://mypy-lang.org/). Make sure it passes successfully, and\nconsider adding type hints where it makes sense to do so when contributing\ncode!\n\nYou can run it like this:\n\n```shell\nmypy torchelie\n```\n\n## Variable names\n\nCommon widespread naming best practices apply.\n\nThat being said, please specifically try to **avoid using `l` as a variable\nname**, even for iterators. First, because of\n[E741](https://www.flake8rules.com/rules/E741.html) (see [PEP8 \"names to\navoid\"](https://www.python.org/dev/peps/pep-0008/#names-to-avoid)), second\nbecause in the context of Torchélie it might mean `layer`, `label`, `loss`,\n`length`, `line`, or other words that are spread among the codebase. Therefore,\nusing `l` would make it considerably harder to understand code when reading it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVermeille%2FTorchelie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVermeille%2FTorchelie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVermeille%2FTorchelie/lists"}