array-api-negative-index 0.0.0__tar.gz → 1.0.0__tar.gz

{array_api_negative_index-0.0.0/src/array_api_negative_index.egg-info → array_api_negative_index-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: array-api-negative-index
-Version: 0.0.0
+Version: 1.0.0
 Summary: Utils for indexing arrays with {-n, -(n-1), ..., -1, 0, 1, ..., n-1, n} using array API.
 Author-email: 34j <34j.95a2p@simplelogin.com>
 License: MIT
@@ -21,6 +21,8 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: array-api-compat>=1.11.2
+Requires-Dist: types-array-api>=1.1.4
 Dynamic: license-file
 
 # Array API Negative Index
@@ -63,13 +65,73 @@ Dynamic: license-file
 
 ---
 
-Utils for indexing arrays with {-n, -(n-1), ..., -1, 0, 1, ..., n-1, n} using array API.
+Utils for indexing arrays with `{-n, -(n-1), ..., -1, 0, 1, ..., n-1, n}` using array API.
 
 ## Installation
 
 Install this via pip (or your favourite package manager):
 
-`pip install array-api-negative-index`
+```shell
+pip install array-api-negative-index
+```
+
+## Usage
+
+- This package provides a utility for packing array elements in the order `[0, 1, 2, ..., n, -n, ..., -2, -1]`.
+- This allows one to access the `i`-th element by `array[i]`, regardless of whether `i` is positive, 0 or negative, thanks to "Negative Indexing" in array API.
+- This is useful for representing the order `m` in spherical harmonics for example.
+
+```python
+from array_api_negative_index import to_symmetric, flip_symmetric, arange_asymmetric
+```
+
+### `arange_asymmetric()`
+
+```python
+import numpy as np
+
+a = arange_asymmetric(3, xp=np)
+print(a)
+```
+
+```text
+[ 0  1  2 -2 -1]
+```
+
+Not to confuse with `np.arange(-stop + 1, stop)`!
+This caused me to create bugs many times.
+
+```python
+a = np.arange(-2, 3)
+print(a)
+```
+
+```text
+[-2, -1, 0, 1, 2]
+```
+
+### `flip_symmetric()`
+
+```python
+b = flip_symmetric(a)
+print(f"{a} -> (flip) -> {b}")
+```
+
+```text
+[ 0  1  2 -2 -1] -> (flip) -> [ 0 -1 -2  2  1]
+```
+
+### `to_symmetric()`
+
+```python
+c = np.asarray([0, 3, 5])
+d = to_symmetric(c, asymmetric=True, conjugate=False)
+print(f"{c} -> (to_symmetric) -> {d}")
+```
+
+```text
+[0 3 5] -> (to_symmetric) -> [ 0  3  5 -5 -3]
+```
 
 ## Contributors ✨
 

{array_api_negative_index-0.0.0 → array_api_negative_index-1.0.0}/README.md

@@ -38,13 +38,73 @@
 
 ---
 
-Utils for indexing arrays with {-n, -(n-1), ..., -1, 0, 1, ..., n-1, n} using array API.
+Utils for indexing arrays with `{-n, -(n-1), ..., -1, 0, 1, ..., n-1, n}` using array API.
 
 ## Installation
 
 Install this via pip (or your favourite package manager):
 
-`pip install array-api-negative-index`
+```shell
+pip install array-api-negative-index
+```
+
+## Usage
+
+- This package provides a utility for packing array elements in the order `[0, 1, 2, ..., n, -n, ..., -2, -1]`.
+- This allows one to access the `i`-th element by `array[i]`, regardless of whether `i` is positive, 0 or negative, thanks to "Negative Indexing" in array API.
+- This is useful for representing the order `m` in spherical harmonics for example.
+
+```python
+from array_api_negative_index import to_symmetric, flip_symmetric, arange_asymmetric
+```
+
+### `arange_asymmetric()`
+
+```python
+import numpy as np
+
+a = arange_asymmetric(3, xp=np)
+print(a)
+```
+
+```text
+[ 0  1  2 -2 -1]
+```
+
+Not to confuse with `np.arange(-stop + 1, stop)`!
+This caused me to create bugs many times.
+
+```python
+a = np.arange(-2, 3)
+print(a)
+```
+
+```text
+[-2, -1, 0, 1, 2]
+```
+
+### `flip_symmetric()`
+
+```python
+b = flip_symmetric(a)
+print(f"{a} -> (flip) -> {b}")
+```
+
+```text
+[ 0  1  2 -2 -1] -> (flip) -> [ 0 -1 -2  2  1]
+```
+
+### `to_symmetric()`
+
+```python
+c = np.asarray([0, 3, 5])
+d = to_symmetric(c, asymmetric=True, conjugate=False)
+print(f"{c} -> (to_symmetric) -> {d}")
+```
+
+```text
+[0 3 5] -> (to_symmetric) -> [ 0  3  5 -5 -3]
+```
 
 ## Contributors ✨
 

{array_api_negative_index-0.0.0 → array_api_negative_index-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "setuptools" ]
 
 [project]
 name = "array-api-negative-index"
-version = "0.0.0"
+version = "1.0.0"
 description = "Utils for indexing arrays with {-n, -(n-1), ..., -1, 0, 1, ..., n-1, n} using array API."
 readme = "README.md"
 license = { text = "MIT" }
@@ -26,6 +26,8 @@ classifiers = [
 ]
 
 dependencies = [
+    "array-api-compat>=1.11.2",
+    "types-array-api>=1.1.4",
 ]
 urls."Bug Tracker" = "https://github.com/34j/array-api-negative-index/issues"
 urls.Changelog = "https://github.com/34j/array-api-negative-index/blob/main/CHANGELOG.md"
@@ -34,8 +36,10 @@ urls.repository = "https://github.com/34j/array-api-negative-index"
 
 [dependency-groups]
 dev = [
+  "numpy>=2.0.2",
   "pytest>=8,<9",
   "pytest-cov>=6,<7",
+  "torch>=2.8.0",
 ]
 docs = [
   "furo>=2023.5.20; python_version>='3.11'",

array_api_negative_index-1.0.0/src/array_api_negative_index/__init__.py

@@ -0,0 +1,4 @@
+__version__ = "1.0.0"
+from ._main import arange_asymmetric, flip_symmetric, to_symmetric
+
+__all__ = ["arange_asymmetric", "flip_symmetric", "to_symmetric"]

array_api_negative_index-1.0.0/src/array_api_negative_index/_main.py

@@ -0,0 +1,120 @@
+from typing import Any
+
+from array_api._2024_12 import Array, ArrayNamespaceFull
+from array_api_compat import array_namespace
+
+
+def to_symmetric(
+    input: Array,
+    /,
+    *,
+    axis: int = 0,
+    asymmetric: bool = False,
+    conjugate: bool = False,
+) -> Array:
+    """
+    Extend a tensor to its opposite symmetric form.
+
+    Parameters
+    ----------
+    input : Array
+        The input tensor.
+    axis : int, optional
+        The axis to extend, by default 0
+    asymmetric : bool, optional
+        If True, the input tensor is multiplied by -1, by default False
+    conjugate : bool, optional
+        If True, the input tensor is conjugated, by default False
+
+    Returns
+    -------
+    Array
+        The symmetric tensor.
+        If not include_zero_twice,
+        forall a < input.shape[axis] result[-a] = result[a]
+        Else,
+        forall a < input.shape[axis] result[-a-1] = result[a]
+
+    """
+    xp = array_namespace(input)
+    input_to_symmetric = input
+    if asymmetric:
+        input_to_symmetric = -input_to_symmetric
+    if conjugate:
+        input_to_symmetric = xp.conj(input_to_symmetric)
+    axis = axis % input.ndim
+    input_to_symmetric = input_to_symmetric[
+        (slice(None),) * axis + (slice(1, None), ...)
+    ]
+    input_to_symmetric = xp.flip(input_to_symmetric, axis=axis)
+    return xp.concat([input, input_to_symmetric], axis=axis)
+
+
+def arange_asymmetric(
+    stop: int,
+    /,
+    *,
+    xp: ArrayNamespaceFull,
+    dtype: Any = None,
+    device: Any = None,
+) -> Array:
+    """
+    Create a symmetric array with values from -stop+1 to stop-1.
+
+    Parameters
+    ----------
+    stop : int
+        The stop value (exclusive).
+    dtype : Any, optional
+        The desired data type of the output array, by default None
+    device : Any, optional
+        The device on which to create the array, by default None
+    xp : ArrayNamespaceFull, optional
+        The array namespace to use, by default None
+
+    Returns
+    -------
+    Array
+        An array [0, 1, ..., stop-1, -stop+1, ..., -1].
+        The shape is (2 * stop - 1,).
+
+    """
+    return to_symmetric(
+        xp.arange(stop, dtype=dtype, device=device),
+        asymmetric=True,
+    )
+
+
+def flip_symmetric(input: Array, /, *, axis: int = 0) -> Array:
+    """
+    Flip a symmetric array.
+
+    Parameters
+    ----------
+    input : Array
+        The input array.
+    axis : int, optional
+        The axis to flip, by default 0
+    include_zero_twice : bool, optional
+        If True, the zeroth element is included twice, by default False
+
+    Returns
+    -------
+    Array
+        The flipped array.
+        Forall a < input.shape[axis] result[-a-1] = result[a] = input[a] = input[-a-1]
+
+    """
+    xp = array_namespace(input)
+    axis = axis % input.ndim
+    zero = input[
+        (
+            slice(
+                None,
+            ),
+        )
+        * axis
+        + (slice(0, 1), ...)
+    ]
+    nonzero = input[(slice(None),) * axis + (slice(1, None), ...)]
+    return xp.concat([zero, xp.flip(nonzero, axis=axis)], axis=axis)

{array_api_negative_index-0.0.0 → array_api_negative_index-1.0.0/src/array_api_negative_index.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: array-api-negative-index
-Version: 0.0.0
+Version: 1.0.0
 Summary: Utils for indexing arrays with {-n, -(n-1), ..., -1, 0, 1, ..., n-1, n} using array API.
 Author-email: 34j <34j.95a2p@simplelogin.com>
 License: MIT
@@ -21,6 +21,8 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: array-api-compat>=1.11.2
+Requires-Dist: types-array-api>=1.1.4
 Dynamic: license-file
 
 # Array API Negative Index
@@ -63,13 +65,73 @@ Dynamic: license-file
 
 ---
 
-Utils for indexing arrays with {-n, -(n-1), ..., -1, 0, 1, ..., n-1, n} using array API.
+Utils for indexing arrays with `{-n, -(n-1), ..., -1, 0, 1, ..., n-1, n}` using array API.
 
 ## Installation
 
 Install this via pip (or your favourite package manager):
 
-`pip install array-api-negative-index`
+```shell
+pip install array-api-negative-index
+```
+
+## Usage
+
+- This package provides a utility for packing array elements in the order `[0, 1, 2, ..., n, -n, ..., -2, -1]`.
+- This allows one to access the `i`-th element by `array[i]`, regardless of whether `i` is positive, 0 or negative, thanks to "Negative Indexing" in array API.
+- This is useful for representing the order `m` in spherical harmonics for example.
+
+```python
+from array_api_negative_index import to_symmetric, flip_symmetric, arange_asymmetric
+```
+
+### `arange_asymmetric()`
+
+```python
+import numpy as np
+
+a = arange_asymmetric(3, xp=np)
+print(a)
+```
+
+```text
+[ 0  1  2 -2 -1]
+```
+
+Not to confuse with `np.arange(-stop + 1, stop)`!
+This caused me to create bugs many times.
+
+```python
+a = np.arange(-2, 3)
+print(a)
+```
+
+```text
+[-2, -1, 0, 1, 2]
+```
+
+### `flip_symmetric()`
+
+```python
+b = flip_symmetric(a)
+print(f"{a} -> (flip) -> {b}")
+```
+
+```text
+[ 0  1  2 -2 -1] -> (flip) -> [ 0 -1 -2  2  1]
+```
+
+### `to_symmetric()`
+
+```python
+c = np.asarray([0, 3, 5])
+d = to_symmetric(c, asymmetric=True, conjugate=False)
+print(f"{c} -> (to_symmetric) -> {d}")
+```
+
+```text
+[0 3 5] -> (to_symmetric) -> [ 0  3  5 -5 -3]
+```
 
 ## Contributors ✨
 

{array_api_negative_index-0.0.0 → array_api_negative_index-1.0.0}/src/array_api_negative_index.egg-info/SOURCES.txt

@@ -3,10 +3,11 @@ README.md
 pyproject.toml
 setup.py
 src/array_api_negative_index/__init__.py
-src/array_api_negative_index/main.py
+src/array_api_negative_index/_main.py
 src/array_api_negative_index/py.typed
 src/array_api_negative_index.egg-info/PKG-INFO
 src/array_api_negative_index.egg-info/SOURCES.txt
 src/array_api_negative_index.egg-info/dependency_links.txt
+src/array_api_negative_index.egg-info/requires.txt
 src/array_api_negative_index.egg-info/top_level.txt
 tests/test_main.py

array_api_negative_index-1.0.0/src/array_api_negative_index.egg-info/requires.txt

@@ -0,0 +1,2 @@
+array-api-compat>=1.11.2
+types-array-api>=1.1.4

array_api_negative_index-1.0.0/tests/test_main.py

@@ -0,0 +1,28 @@
+import pytest
+from array_api._2024_12 import ArrayNamespaceFull
+
+from array_api_negative_index import flip_symmetric, to_symmetric
+
+
+def test_flip_symmetric(xp: ArrayNamespaceFull) -> None:
+    array = xp.asarray([0, 1, 2, 3, 4])
+    assert xp.all(flip_symmetric(array) == xp.asarray([0, 4, 3, 2, 1]))
+    assert xp.all(flip_symmetric(flip_symmetric(array)) == array)
+
+
+@pytest.mark.parametrize("asymmetric", [True, False])
+@pytest.mark.parametrize("conjugate", [True, False])
+def test_to_symmetric_manual(
+    asymmetric: bool, conjugate: bool, xp: ArrayNamespaceFull
+) -> None:
+    array = xp.asarray([0, 1 + 1j, 2 - 1j])
+    result = to_symmetric(xp.asarray(array), asymmetric=asymmetric, conjugate=conjugate)
+    if asymmetric and conjugate:
+        expected = [0, 1 + 1j, 2 - 1j, -2 - 1j, -1 + 1j]
+    elif asymmetric and not conjugate:
+        expected = [0, 1 + 1j, 2 - 1j, -2 + 1j, -1 - 1j]
+    elif not asymmetric and conjugate:
+        expected = [0, 1 + 1j, 2 - 1j, 2 + 1j, 1 - 1j]
+    else:
+        expected = [0, 1 + 1j, 2 - 1j, 2 - 1j, 1 + 1j]
+    assert xp.all(result == xp.asarray(expected))

array_api_negative_index-0.0.0/src/array_api_negative_index/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.0.0"

array_api_negative_index-0.0.0/src/array_api_negative_index/main.py

@@ -1,3 +0,0 @@
-def add(n1: int, n2: int) -> int:
-    """Add the arguments."""
-    return n1 + n2

array_api_negative_index-0.0.0/tests/test_main.py

@@ -1,6 +0,0 @@
-from array_api_negative_index.main import add
-
-
-def test_add():
-    """Adding two number works as expected."""
-    assert add(1, 1) == 2