nvmath-python-0.2.1 (#14)

Author: markjolah

.gitignore

@@ -13,15 +13,13 @@ dist
 build
 wheelhouse
 
-#Pytest
+#Test
 .pytest_cache
+*.pickle
+.hypothesis/*
 
 #Pipenv
 .env*
 Pipfile*
 .venv*
 .pipenv-cache
-
-#Test outputs
-*.pickle
-.hypothesis/*

.markdownlint.yaml

@@ -1,7 +1,9 @@
 MD013:
-  line_length: 120
+  line_length: 92
+  code_block_line_length: 88
   code_blocks: true
   tables: false
+  stern: true
 MD033:
   allowed_elements:
     - img

.pre-commit-config.yaml

@@ -108,7 +108,15 @@ repos:
     rev: v0.41.0
     hooks:
       - id: markdownlint
-        args: ["--fix"]
+      # Ignore old internal README that will not be rendered as docs page
+        args: ["--fix", "--ignore", "internal/gtc2024/README.md"]
+
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: v1.0.0
+    hooks:
+      - id: sphinx-lint
+        args: ["--enable", "all", "--max-line-length", "92"]
+        exclude: ^(.*)generated/(.*)\.rst$
 
 default_language_version:
-      python: python3
+  python: python310

CONTRIBUTING.md

@@ -1,18 +1,21 @@
 # Contributing
 
-Thank you for your interest in contributing to `nvmath-python`! Based on the type of contribution, it will fall into
-three categories:
+Thank you for your interest in contributing to `nvmath-python`! Based on the type of
+contribution, it will fall into three categories:
 
 1. You want to report a bug, feature request, or documentation issue
-    - File an [issue](https://github.com/NVIDIA/nvmath-python/issues) describing what you encountered or what you want
-    to see changed.
-    - The NVIDIA team will evaluate the issues and triage them, scheduling them for a release. If you believe the issue
-    needs priority attention comment on the issue to notify the team.
+    - File an [issue](https://github.com/NVIDIA/nvmath-python/issues) describing what you
+    encountered or what you want to see changed.
+    - The NVIDIA team will evaluate the issues and triage them, scheduling them for a
+    release. If you believe the issue needs priority attention comment on the issue to
+    notify the team.
 2. You want to implement a feature or bug-fix
-    - At this time we do not accept code contributions. However, we do plan to change and accept contributions in the
-    near future, although the timeline is TBD. Please let us know if you're interested in contributing (and in what
-    aspect) so that we can plan accordingly.
+    - At this time we do not accept code contributions. However, we do plan to change and
+    accept contributions in the near future, although the timeline is TBD. Please let us
+    know if you're interested in contributing (and in what aspect) so that we can plan
+    accordingly.
 3. You want to share your nice work built upon `nvmath-python`:
-    - We would love to hear more about your work! Please share with us on [NVIDIA/nvmath-python GitHub
-    Discussions](https://github.com/NVIDIA/nvmath-python/discussions)! We also take any `nvmath-python`-related
-    questions on this forum.
+    - We would love to hear more about your work! Please share with us on
+    [NVIDIA/nvmath-python GitHub
+    Discussions](https://github.com/NVIDIA/nvmath-python/discussions)! We also take any
+    `nvmath-python`-related questions on this forum.

DESCRIPTION.rst

@@ -2,8 +2,10 @@
 nvmath-python: NVIDIA Math Libraries for the Python Ecosystem
 *************************************************************
 
-`nvmath-python <https://developer.nvidia.com/nvmath-python>`_ brings the power and performance of NVIDIA math libraries to the Python ecosystem
-with intuitive, pythonic APIs. The ultimate goal is to provide users full access to all of the available library features in a variety of execution spaces.
+`nvmath-python <https://developer.nvidia.com/nvmath-python>`_ brings the power and
+performance of NVIDIA math libraries to the Python ecosystem with intuitive, pythonic APIs.
+The ultimate goal is to provide users full access to all of the available library features
+in a variety of execution spaces.
 
 * `Documentation <https://docs.nvidia.com/cuda/nvmath-python/index.html>`_
 * `Examples <https://github.com/NVIDIA/nvmath-python/tree/main/examples>`_
@@ -15,4 +17,6 @@ Installation
 
    pip install nvmath-python[cu12]
 
-Please refer to the `installation instructions <https://docs.nvidia.com/cuda/nvmath-python/latest/getting-started.html>`_ for different ways of installing nvmath-python, including building from source.
+Please refer to the `installation instructions
+<https://docs.nvidia.com/cuda/nvmath-python/latest/installation.html>`_ for different
+ways of installing nvmath-python, including building from source.

README.md

@@ -1,41 +1,48 @@
 <h1 align="center"><img
     src="docs/sphinx/_static/nvmath-python-green-r4.svg"
-    alt="A green cube with three sides visible. Dots, a sine wave, and a grid on the three faces."
+    alt="A cube with three sides visible. Dots, a sine wave, and a grid on the faces."
     width="200"/>
 </h1>
 
 # nvmath-python: NVIDIA Math Libraries for the Python Ecosystem
 
-nvmath-python brings the power of the NVIDIA math libraries to the Python ecosystem. The package aims to provide
-intuitive pythonic APIs that provide users full access to all the features offered by NVIDIA's libraries in a variety of
-execution spaces. nvmath-python works seamlessly with existing Python array/tensor frameworks and focuses on providing
+nvmath-python brings the power of the NVIDIA math libraries to the Python ecosystem. The
+package aims to provide intuitive pythonic APIs that provide users full access to all the
+features offered by NVIDIA's libraries in a variety of execution spaces. nvmath-python works
+seamlessly with existing Python array/tensor frameworks and focuses on providing
 functionality that is missing from those frameworks.
 
 ## Some Examples
 
-Using the nvmath-python API allows access to all parameters of the underlying NVIDIA cuBLASLt library. Some of these
-parameters are unavailable in other wrappings of NVIDIA's C-API libraries.
+Using the nvmath-python API allows access to all parameters of the underlying NVIDIA
+cuBLASLt library. Some of these parameters are unavailable in other wrappings of NVIDIA's
+C-API libraries.
 
 ```python
 import cupy as cp
 import nvmath
 
-# Prepare sample input data. nvmath-python accepts input tensors from pytorch, cupy, and numpy.
+# Prepare sample input data. nvmath-python accepts input tensors from pytorch, cupy, and
+# numpy.
 m, n, k = 123, 456, 789
 a = cp.random.rand(m, k).astype(cp.float32)
 b = cp.random.rand(k, n).astype(cp.float32)
 bias = cp.random.rand(m, 1).astype(cp.float32)
 
-# Use the stateful Matmul object in order to perform multiple matrix multiplications without replanning. The nvmath API
-# allows us to fine-tune our operations by, for example, selecting a mixed-precision compute type.
+# Use the stateful Matmul object in order to perform multiple matrix multiplications
+# without replanning. The nvmath API allows us to fine-tune our operations by, for
+# example, selecting a mixed-precision compute type.
 mm = nvmath.linalg.advanced.Matmul(
     a,
     b,
-    options={"compute_type": nvmath.linalg.advanced.MatmulComputeType.COMPUTE_32F_FAST_16F},
+    options={
+        "compute_type": nvmath.linalg.advanced.MatmulComputeType.COMPUTE_32F_FAST_16F
+    },
 )
 
-# Plan the matrix multiplication. Planning returns a sequence of algorithms that can be configured. We can also select
-# epilog operations which are applied to the result of the multiplication without a separate function call.
+# Plan the matrix multiplication. Planning returns a sequence of algorithms that can be
+# configured. We can also select epilog operations which are applied to the result of
+# the multiplication without a separate function call.
 mm.plan(
     epilog=nvmath.linalg.advanced.MatmulEpilog.BIAS,
     epilog_inputs={"bias": bias},
@@ -47,23 +54,27 @@ result = mm.execute()
 # Remember to free the Matmul object when finished or use it as a context manager
 mm.free()
 
-# Synchronize the default stream, since by default the execution is non-blocking for GPU operands.
+# Synchronize the default stream, since by default the execution is non-blocking for
+# GPU operands.
 cp.cuda.get_current_stream().synchronize()
 print(f"Input types = {type(a), type(b)}, device = {a.device, b.device}")
 print(f"Result type = {type(result)}, device = {result.device}")
 ```
 
-nvmath-python exposes NVIDIA's device-side (Dx) APIs. This allows developers to call NVIDIA library functions inside
-their custom device kernels. For example, a numba jit function can call cuFFT in order to implement FFT-based
-convolution.
+nvmath-python exposes NVIDIA's device-side (Dx) APIs. This allows developers to call NVIDIA
+library functions inside their custom device kernels. For example, a numba jit function can
+call cuFFT in order to implement FFT-based convolution.
 
 ```python
 import numpy as np
 from numba import cuda
 from nvmath.device import fft
 
 def random_complex(shape, real_dtype):
-    return np.random.randn(*shape).astype(real_dtype) + 1.j * np.random.randn(*shape).astype(real_dtype)
+    return (
+        np.random.randn(*shape).astype(real_dtype)
+        + 1.j * np.random.randn(*shape).astype(real_dtype)
+    )
 
 def main():
 
@@ -148,9 +159,9 @@ if __name__ == "__main__":
     main()
 ```
 
-nvmath-python provides the ability to write custom prologs and epilogs for FFT functions as a Python functions and
-compiled them LTO-IR. For example, to have unitary scaling for an FFT, we can define an epilog which rescales the output
-by 1/sqrt(N).
+nvmath-python provides the ability to write custom prologs and epilogs for FFT functions as
+a Python functions and compiled them LTO-IR. For example, to have unitary scaling for an
+FFT, we can define an epilog which rescales the output by 1/sqrt(N).
 
 ```python
 import cupy as cp
@@ -175,7 +186,8 @@ with cp.cuda.Device():
 # Perform the forward FFT, applying the filter as a epilog...
 r = nvmath.fft.fft(a, axes=[-1], epilog={"ltoir": epilog})
 
-# Finally, we can test that the fused FFT run result matches the result of separate calls
+# Finally, we can test that the fused FFT run result matches the result of separate
+# calls
 s = cp.fft.fftn(a, axes=[-1], norm="ortho")
 
 assert cp.allclose(r, s)
@@ -187,5 +199,6 @@ All files hosted in this repository are subject to the [Apache 2.0](./LICENSE) l
 
 ## Disclaimer
 
-nvmath-python is in a Beta state. Beta products may not be fully functional, may contain errors or design flaws, and may
-be changed at any time without notice. We appreciate your feedback to improve and iterate on our Beta products.
+nvmath-python is in a Beta state. Beta products may not be fully functional, may contain
+errors or design flaws, and may be changed at any time without notice. We appreciate your
+feedback to improve and iterate on our Beta products.

SECURITY.md

@@ -1,28 +1,32 @@
 # Security
 
-NVIDIA is dedicated to the security and trust of our software products and services, including all source code
-repositories managed through our organization.
+NVIDIA is dedicated to the security and trust of our software products and services,
+including all source code repositories managed through our organization.
 
-If you need to report a security issue, please use the appropriate contact points outlined below. **Please do not report
-security vulnerabilities through GitHub/GitLab.**
+If you need to report a security issue, please use the appropriate contact points outlined
+below. **Please do not report security vulnerabilities through GitHub/GitLab.**
 
 ## Reporting Potential Security Vulnerability in nvmath-python
 
 To report a potential security vulnerability in nvmath-python:
 
-- Web: [Security Vulnerability Submission Form](https://www.nvidia.com/object/submit-security-vulnerability.html)
+- Web: [Security Vulnerability Submission
+  Form](https://www.nvidia.com/object/submit-security-vulnerability.html)
 - E-Mail: <[email protected]>
-  - We encourage you to use the following PGP key for secure email communication: [NVIDIA public PGP Key for communication](https://www.nvidia.com/en-us/security/pgp-key)
+  - We encourage you to use the following PGP key for secure email communication: [NVIDIA
+    public PGP Key for communication](https://www.nvidia.com/en-us/security/pgp-key)
   - Please include the following information:
     - Product/Driver name and version/branch that contains the vulnerability
     - Type of vulnerability (code execution, denial of service, buffer overflow, etc.)
     - Instructions to reproduce the vulnerability
     - Proof-of-concept or exploit code
-    - Potential impact of the vulnerability, including how an attacker could exploit the vulnerability
+    - Potential impact of the vulnerability, including how an attacker could exploit the
+      vulnerability
 
-While NVIDIA currently does not have a bug bounty program, we do offer acknowledgement when an externally reported
-security issue is addressed under our coordinated vulnerability disclosure policy. Please visit our [Product Security
-Incident Response Team (PSIRT)](https://www.nvidia.com/en-us/security/psirt-policies/) policies page for more
+While NVIDIA currently does not have a bug bounty program, we do offer acknowledgement when
+an externally reported security issue is addressed under our coordinated vulnerability
+disclosure policy. Please visit our [Product Security Incident Response Team
+(PSIRT)](https://www.nvidia.com/en-us/security/psirt-policies/) policies page for more
 information.
 
 ## NVIDIA Product Security

builder/utils.py

@@ -93,10 +93,11 @@ def _prep_includes_libs_rpaths(self, lib_name):
             if lib_name is not None:
                 ldflag = "-Wl,--disable-new-dtags"
                 if lib_name == "nvpl":
-                    # 1. the nvpl bindings land in site-packages/nvmath/bindings/nvpl/_internal/
-                    # as opposed to other packages that have their bindings in
-                    # site-packages/nvmath/bindings/_internal/, so we need one extra `..`
-                    # to get into `site-packages` and then the lib_name=nvpl is not in nvidia
+                    # 1. the nvpl bindings land in
+                    # site-packages/nvmath/bindings/nvpl/_internal/ as opposed to other
+                    # packages that have their bindings in
+                    # site-packages/nvmath/bindings/_internal/, so we need one extra `..` to
+                    # get into `site-packages` and then the lib_name=nvpl is not in nvidia
                     # dir but directly in the site-packages.
                     # 2. mkl lib is placed directly in the python `lib` directory, not in
                     # python{ver}/site-packages

docs/Makefile

@@ -3,7 +3,7 @@ SHELL=/bin/bash
 
 # You can set these variables from the command line or environment
 SPHINX_NVMATH_PYTHON_VER ?= $(shell [[ $$(< ../nvmath/_version.py) =~ __version__[^0-9.]*([0-9.]*) ]] && echo $${BASH_REMATCH[1]})
-SPHINXOPTS    ?= -j auto
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = sphinx
 BUILDDIR      ?= _build/html
@@ -27,4 +27,10 @@ html: Makefile
 	cd $(BUILDDIR) && cp -a ${SPHINX_NVMATH_PYTHON_VER}/* latest/
 	cp $(BUILDDIR)/latest/objects.inv $(BUILDDIR)
 
-.PHONY: help Makefile clean html
+
+linkcheck: Makefile
+	$(eval $@_BUILDDIR := $(shell mktemp -d))
+	$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rm -rf $($@_BUILDDIR)
+
+.PHONY: help Makefile clean html linkcheck