{
    "info": {
        "author": "Cl\u00e9ment Pinard",
        "author_email": "clement.pinard@ensta-paristech.fr",
        "bugtrack_url": null,
        "classifiers": [
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: MIT License",
            "Operating System :: POSIX :: Linux",
            "Programming Language :: Python :: 3",
            "Topic :: Scientific/Engineering :: Artificial Intelligence"
        ],
        "description": "[![PyPI](https://img.shields.io/pypi/v/spatial-correlation-sampler.svg)](https://pypi.org/project/spatial-correlation-sampler/)\n\n\n# Pytorch Correlation module\n\nthis is a custom C++/Cuda implementation of Correlation module, used e.g. in [FlowNetC](https://arxiv.org/abs/1504.06852)\n\nThis [tutorial](http://pytorch.org/tutorials/advanced/cpp_extension.html) was used as a basis for implementation, as well as\n[NVIDIA's cuda code](https://github.com/NVIDIA/flownet2-pytorch/tree/master/networks/correlation_package)\n\n- Build and Install C++ and CUDA extensions by executing `python setup.py install`,\n- Benchmark C++ vs. CUDA by running `python benchmark.py {cpu, cuda}`,\n- Run gradient checks on the code by running `python grad_check.py --backend {cpu, cuda}`.\n\n# Requirements\n\nThis module is expected to compile for Pytorch `1.2`, on `Python > 3.5` and `Python 2.7`.\n\n# Installation\n\nthis module is available on pip\n\n`pip install spatial-correlation-sampler`\n\nFor a cpu-only version, you can install from source with\n\n`python setup_cpu.py install`\n\n# Known Problems\n\nThis module needs compatible gcc version and CUDA to be compiled.\nNamely, CUDA 9.1 and below will need gcc5, while CUDA 9.2 and 10.0 will need gcc7\nSee [this issue](https://github.com/ClementPinard/Pytorch-Correlation-extension/issues/1) for more information\n\n# Usage\n\nAPI has a few difference with NVIDIA's module\n * output is now a 5D tensor, which reflects the shifts horizontal and vertical.\n ```\ninput (B x C x H x W) -> output (B x PatchH x PatchW x oH x oW)\n ```\n * Output sizes `oH` and `oW` are no longer dependant of patch size, but only of kernel size and padding\n * Patch size `patch_size` is now the whole patch, and not only the radii.\n * `stride1` is now `stride` and`stride2` is `dilation_patch`, which behave like dilated convolutions\n * equivalent `max_displacement` is then `dilation_patch * (patch_size - 1) / 2`.\n * to get the right parameters for FlowNetC, you would have\n ```\nkernel_size=1\npatch_size=21,\nstride=1,\npadding=0,\ndilation_patch=2\n ```\n\n# Benchmark\n\n * default parameters are from `benchmark.py`, FlowNetC parameters are same as use in `FlowNetC` with a batch size of 4, described in [this paper](https://arxiv.org/abs/1504.06852), implemented [here](https://github.com/lmb-freiburg/flownet2) and [here](https://github.com/NVIDIA/flownet2-pytorch/blob/master/networks/FlowNetC.py).\n * Feel free to file an issue to add entries to this with your hardware !\n\n## CUDA Benchmark\n\n * See [here](https://gist.github.com/ClementPinard/270e910147119831014932f67fb1b5ea) for a benchmark script working with [NVIDIA](https://github.com/NVIDIA/flownet2-pytorch/tree/master/networks/correlation_package)'s code, and Pytorch.\n * Benchmark are launched with environment variable `CUDA_LAUNCH_BLOCKING` set to `1`.\n * Only `float32` is benchmarked.\n * FlowNetC correlation parameters where launched with the following command:\n \n ```bash\n CUDA_LAUNCH_BLOCKING=1 python benchmark.py --scale ms -k1 --patch 21 -s1 -p0 --patch_dilation 2 -b4 --height 48 --width 64 -c256 cuda\n \n CUDA_LAUNCH_BLOCKING=1 python NV_correlation_benchmark.py --scale ms -k1 --patch 21 -s1 -p0 --patch_dilation 2 -b4 --height 48 --width 64 -c256\n ```\n\n | implementation | Correlation parameters |  device |     pass |      min time |      avg time |\n | -------------- | ---------------------- | ------- | -------- | ------------: | ------------: |\n |           ours |                default | 980 GTX |  forward |  **5.745 ms** |  **5.851 ms** |\n |           ours |                default | 980 GTX | backward |     77.694 ms |     77.957 ms |\n |         NVIDIA |                default | 980 GTX |  forward |     13.779 ms |     13.853 ms |\n |         NVIDIA |                default | 980 GTX | backward | **73.383 ms** | **73.708 ms** |\n |                |                        |         |          |               |               |\n |           ours |               FlowNetC | 980 GTX |  forward |  **26.102 ms** |  **26.179 ms** |\n |           ours |               FlowNetC | 980 GTX | backward | **208.091 ms** | **208.510 ms** |\n |         NVIDIA |               FlowNetC | 980 GTX |  forward |      35.363 ms |      35.550 ms |\n |         NVIDIA |               FlowNetC | 980 GTX | backward |     283.748 ms |     284.346 ms |\n \n### Notes\n * The overhead of our implementation regarding `kernel_size` > 1 during backward needs some investigation, feel free to\n dive in the code to improve it !\n * The backward pass of NVIDIA is not entirely correct when stride1 > 1 and kernel_size > 1, because not everything\n is computed, see [here](https://github.com/NVIDIA/flownet2-pytorch/blob/master/networks/correlation_package/src/correlation_cuda_kernel.cu#L120).\n\n## CPU Benchmark\n\n  * No other implementation is avalaible on CPU.\n  * It is obviously not recommended to run it on CPU if you have a GPU.\n\n | Correlation parameters |               device |     pass |    min time |    avg time |\n | ---------------------- | -------------------- | -------- | ----------: | ----------: |\n |                default | E5-2630 v3 @ 2.40GHz |  forward |  159.616 ms |  188.727 ms |\n |                default | E5-2630 v3 @ 2.40GHz | backward |  282.641 ms |  294.194 ms |\n |               FlowNetC | E5-2630 v3 @ 2.40GHz |  forward |  2.138 s |  2.144 s |\n |               FlowNetC | E5-2630 v3 @ 2.40GHz | backward | 7.006 s | 7.075 s |",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/ClementPinard/Pytorch-Correlation-extension",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "spatial-correlation-sampler",
        "package_url": "https://pypi.org/project/spatial-correlation-sampler/",
        "platform": "",
        "project_url": "https://pypi.org/project/spatial-correlation-sampler/",
        "project_urls": {
            "Homepage": "https://github.com/ClementPinard/Pytorch-Correlation-extension"
        },
        "release_url": "https://pypi.org/project/spatial-correlation-sampler/0.2.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Correlation module for pytorch",
        "version": "0.2.1"
    },
    "last_serial": 5776843,
    "releases": {
        "0.0.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e91c5163a7fb006e477273c92cc975d8",
                    "sha256": "adcd9846cbd0ed12717dd24e144bfe4813a6a7d59ac460fb97549cd44465fb4e"
                },
                "downloads": -1,
                "filename": "spatial_correlation_sampler-0.0.5.tar.gz",
                "has_sig": false,
                "md5_digest": "e91c5163a7fb006e477273c92cc975d8",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 6797,
                "upload_time": "2018-08-17T15:35:36",
                "url": "https://files.pythonhosted.org/packages/b0/2b/f1d8d71a695f31e8d2f59ec9ec5824ecf3e253cf799c821b4c2067e392b2/spatial_correlation_sampler-0.0.5.tar.gz"
            }
        ],
        "0.0.8": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3cb51ee53bb8271f027265af761bffdc",
                    "sha256": "c4f1b72cb47c6160d24971ffcb69a8649c7af0b341b3069455924d3364abc5e2"
                },
                "downloads": -1,
                "filename": "spatial_correlation_sampler-0.0.8.tar.gz",
                "has_sig": false,
                "md5_digest": "3cb51ee53bb8271f027265af761bffdc",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 7665,
                "upload_time": "2018-08-22T22:05:11",
                "url": "https://files.pythonhosted.org/packages/74/5d/e51bd2126527d7339025febcda13630f1423afc0d9c945806879d242eb80/spatial_correlation_sampler-0.0.8.tar.gz"
            }
        ],
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3b03cac9f5262351972f17a9a70878b1",
                    "sha256": "897b0bb3c8c9c0c7e0fb6641b25eeaa8a00dac7ca7bf83452417243de5e715e3"
                },
                "downloads": -1,
                "filename": "spatial_correlation_sampler-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "3b03cac9f5262351972f17a9a70878b1",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 7892,
                "upload_time": "2019-04-24T13:43:52",
                "url": "https://files.pythonhosted.org/packages/a6/d1/aa0a71739ce998f655286d966c0ad7aff765648431c054c34db7d58b811b/spatial_correlation_sampler-0.1.0.tar.gz"
            }
        ],
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e757defbc7b060c42897dead50b4284d",
                    "sha256": "d161f80f09eb1cda02fc27ec2ec785bfa115d05afc34001674c95010f5b5c462"
                },
                "downloads": -1,
                "filename": "spatial_correlation_sampler-0.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "e757defbc7b060c42897dead50b4284d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 8160,
                "upload_time": "2019-09-03T15:28:30",
                "url": "https://files.pythonhosted.org/packages/0e/81/37a407309ba447a7a710d74aa06bfcfed29f160862d824d76e7cdbae57c7/spatial_correlation_sampler-0.2.0.tar.gz"
            }
        ],
        "0.2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4f7f3d51c8aabcdec65633bfd92f67c3",
                    "sha256": "9a699c5a68359a161311fc3b4bb615cfab173b9b98ea1f8c627f0cc394f30831"
                },
                "downloads": -1,
                "filename": "spatial_correlation_sampler-0.2.1.tar.gz",
                "has_sig": false,
                "md5_digest": "4f7f3d51c8aabcdec65633bfd92f67c3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 8159,
                "upload_time": "2019-09-03T16:03:47",
                "url": "https://files.pythonhosted.org/packages/69/62/96bda9bf47f2a2ea978ec86a2e0ac3631036e6650d02ee81ba769d8d5dae/spatial_correlation_sampler-0.2.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "4f7f3d51c8aabcdec65633bfd92f67c3",
                "sha256": "9a699c5a68359a161311fc3b4bb615cfab173b9b98ea1f8c627f0cc394f30831"
            },
            "downloads": -1,
            "filename": "spatial_correlation_sampler-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "4f7f3d51c8aabcdec65633bfd92f67c3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 8159,
            "upload_time": "2019-09-03T16:03:47",
            "url": "https://files.pythonhosted.org/packages/69/62/96bda9bf47f2a2ea978ec86a2e0ac3631036e6650d02ee81ba769d8d5dae/spatial_correlation_sampler-0.2.1.tar.gz"
        }
    ]
}