Version 0.1.0

.flake8

@@ -0,0 +1,26 @@
+[flake8]
+max-line-length = 88
+extend-ignore =
+    # Line too long
+    E501
+    # Module level import not at top of file
+    E402
+show_source = True
+exclude =
+    # No need to traverse our git directory
+    .git,
+    # There's no value in checking cache directories
+    __pycache__,
+    # The conf file is mostly autogenerated, ignore it
+    docs/source/conf.py,
+    # The old directory contains Flake8 2.0
+    old,
+    # This contains our built documentation
+    build,
+    # This contains builds of flake8 that we don't want to check
+    dist,
+    # Ignore notebook checkpoints
+    .ipynb_checkpoints
+per-file-ignores =
+    # imported but unused + 'from module import *' used
+    __init__.py: F401,F403

.github/workflows/test.yaml

@@ -0,0 +1,58 @@
+# Template: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python package using Pip
+
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main, dev ]
+
+env:
+  CACHE_NUMBER: 0  # increase to reset cache manually
+
+# Cancel workflow if a new push occurs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest,windows-latest,macos-latest]
+        python-version: ["3.8", "3.11"]
+
+    steps:
+    # --- INSTALLATIONS ---
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Install package
+      run: |
+        python -m pip install -e .[dev]
+
+    # --- TESTS ---
+    - name: Lint with flake8
+      run: |
+        python -m flake8 --config .flake8 --exit-zero --show-source --statistics src
+
+    - name: Check format with Black
+      run: |
+        python -m black --check --diff src
+
+    - name: Print install info
+      run: |
+        torchoutil-info
+
+    - name: Test with pytest
+      run: |
+        python -m pytest -v

.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+# exclude: ""
+
+repos:
+    # Format Code
+    - repo: https://github.com/ambv/black
+      rev: 23.11.0
+      hooks:
+        - id: black
+
+    # Sort imports
+    - repo: https://github.com/PyCQA/isort
+      rev: 5.12.0
+      hooks:
+      - id: isort
+        args: ["--profile", "black"]
+
+    # Formatting, Whitespace, etc
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v2.2.3
+      hooks:
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-ast
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: requirements-txt-fixer
+      - id: mixed-line-ending
+        args: ['--fix=no']
+      - id: flake8
+        # args: ['--ignore=E203,E501,F811,E712,W503']
+        args: ['--config=.flake8']

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+python:
+   install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] 2024-01-29
+### Added
+- 47 torch functions and 40 torch modules.

CITATION.cff

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+cff-version: 1.2.0
+title: torchoutil
+message: 'If you use this software, please cite it as below.'
+type: software
+authors:
+  - given-names: Étienne
+    family-names: Labbé
+    email: labbeti.pub@gmail.com
+    affiliation: IRIT
+    orcid: 'https://orcid.org/0000-0002-7219-5463'
+repository-code: 'https://github.com/Labbeti/torchoutil/'
+abstract: Collection of functions and modules to help development in PyTorch.
+keywords:
+  - pytorch
+  - deep-learning
+license: MIT
+version: 0.1.0
+date-released: '2024-01-29'

README.md

@@ -1 +1,90 @@
-# extentorch
+# torchoutil
+
+<center>
+
+<a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/-Python 3.8+-blue?style=for-the-badge&logo=python&logoColor=white"></a>
+<a href="https://pytorch.org/get-started/locally/"><img alt="PyTorch" src="https://img.shields.io/badge/-PyTorch 1.4+-ee4c2c?style=for-the-badge&logo=pytorch&logoColor=white"></a>
+<a href="https://black.readthedocs.io/en/stable/"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-black.svg?style=for-the-badge&labelColor=gray"></a>
+
+Collection of functions and modules to help development in PyTorch.
+
+</center>
+
+
+## Installation
+```bash
+pip install torchoutil
+```
+
+The only requirements are `python>=3.8` and `torch>=1.10`.
+
+## Usage
+
+### Batch of padded sequences
+```python
+import torch
+from torchoutil import masked_mean
+
+x = torch.as_tensor([1, 2, 3, 4])
+mask = torch.as_tensor([True, True, False, False])
+result = masked_mean(x, mask)
+# result contains the mean of the values marked as True: 1.5
+```
+
+```python
+import torch
+from torchoutil import lengths_to_non_pad_mask
+
+x = torch.as_tensor([3, 1, 2])
+pad_mask = lengths_to_non_pad_mask(x, max_len=4)
+# tensor([[True, True, True, False],
+#         [True, False, False, False],
+#         [True, True, False, False]])
+```
+
+### Multilabel conversions
+```python
+import torch
+from torchoutil import probs_to_names
+
+probs = torch.as_tensor([[0.9, 0.1], [0.6, 0.9]])
+names = probs_to_names(probs, threshold=0.5, idx_to_name={0: "Cat", 1: "Dog"})
+# [["Cat"], ["Cat", "Dog"]]
+```
+
+```python
+import torch
+from torchoutil import multihot_to_indices
+
+multihot = torch.as_tensor([[1, 0, 0], [0, 1, 1], [0, 0, 0]])
+indices = multihot_to_indices(multihot)
+# [[0], [1, 2], []]
+```
+
+### ...and more tensor manipulations!
+
+```python
+import torch
+from torchoutil import insert_at_indices
+
+x = torch.as_tensor([1, 2, 3, 4])
+result = insert_at_indices(x, indices=[0, 2], values=5)
+# result contains tensor with inserted values: tensor([5, 1, 2, 5, 3, 4])
+```
+
+```python
+import torch
+from torchoutil import get_inverse_perm
+
+perm = torch.randperm(10)
+inv_perm = get_inverse_perm(perm)
+
+x1 = torch.rand(10)
+x2 = x1[perm]
+x3 = x2[inv_perm]
+# inv_perm are indices that allow us to get x1 from x3, i.e. x1 == x3 here
+```
+
+## Contact
+Maintainer:
+- Étienne Labbé "Labbeti": labbeti.pub@gmail.com

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/conf.py

@@ -0,0 +1,96 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+import torchoutil
+
+# -- Project information -----------------------------------------------------
+
+project = torchoutil.__name__
+copyright = f"{torchoutil.__author__}"
+author = torchoutil.__author__
+
+# The short X.Y version
+version = torchoutil.__version__
+
+# The full version, including alpha/beta/rc tags
+release = f"{torchoutil.__status__}-{torchoutil.__version__}"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.intersphinx",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "press"
+
+html_theme_options = {
+    "external_links": [
+        ("Github", "https://github.com/Labbeti/torchoutil"),
+        ("PyPI", "https://pypi.org/project/torchoutil/"),
+    ],
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+add_module_names = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
+    "torch": ("https://pytorch.org/docs/master/", None),
+}
+maximum_signature_line_length = 10