imops 0.8.2__cp36-cp36m-win32.whl → 0.8.3__cp36-cp36m-win32.whl

imops/__init__.py

@@ -4,6 +4,7 @@ from .crop import crop_to_box, crop_to_shape
 from .interp1d import interp1d
 from .measure import label
 from .morphology import binary_closing, binary_dilation, binary_erosion, binary_opening
+from .numeric import copy, fill_, full, pointwise_add
 from .pad import pad, pad_to_divisible, pad_to_shape, restore_crop
 from .radon import inverse_radon, radon
 from .zoom import _zoom, zoom, zoom_to_shape

imops/__version__.py

@@ -1 +1 @@
-__version__ = '0.8.2'
+__version__ = '0.8.3'

imops/backend.py

@@ -1,14 +1,15 @@
-import contextlib
+from contextlib import contextmanager
 from dataclasses import dataclass
 from typing import Dict, Type, Union
+from warnings import warn
 
 
 class Backend:
     def __init_subclass__(cls, **kwargs):
         name = cls.__name__
-        if name in AVAILABLE_BACKENDS:
+        if name in _AVAILABLE_BACKENDS:
             raise ValueError(f'The name "{name}" is already in use.')
-        AVAILABLE_BACKENDS[name] = cls
+        _AVAILABLE_BACKENDS[name] = cls
         if not hasattr(Backend, name):
             setattr(Backend, name, cls)
 
@@ -22,18 +23,18 @@ class Backend:
 
 
 BackendLike = Union[str, Backend, Type[Backend], None]
-AVAILABLE_BACKENDS: Dict[str, Type[Backend]] = {}
+_AVAILABLE_BACKENDS: Dict[str, Type[Backend]] = {}
 
 
-def resolve_backend(value: BackendLike) -> Backend:
+def resolve_backend(value: BackendLike, warn_stacklevel: int = 1) -> Backend:
     if value is None:
         return DEFAULT_BACKEND
 
     if isinstance(value, str):
-        if value not in AVAILABLE_BACKENDS:
-            raise ValueError(f'"{value}" is not in the list of available backends: {tuple(AVAILABLE_BACKENDS)}.')
+        if value not in _AVAILABLE_BACKENDS:
+            raise ValueError(f'"{value}" is not in the list of available backends: {tuple(_AVAILABLE_BACKENDS)}.')
 
-        return AVAILABLE_BACKENDS[value]()
+        return _AVAILABLE_BACKENDS[value]()
 
     if isinstance(value, type):
         value = value()
@@ -41,6 +42,9 @@ def resolve_backend(value: BackendLike) -> Backend:
     if not isinstance(value, Backend):
         raise ValueError(f'Expected a `Backend` instance, got {value}.')
 
+    if isinstance(value, Cython) and value.fast:
+        warn('`fast=True` has no effect for `Cython` backend for now.', stacklevel=warn_stacklevel)
+
     return value
 
 
@@ -51,7 +55,7 @@ def set_backend(backend: BackendLike) -> Backend:
     return current
 
 
-@contextlib.contextmanager
+@contextmanager
 def imops_backend(backend: BackendLike):
     previous = set_backend(backend)
     try:
@@ -87,5 +91,5 @@ class Scipy(Backend):
 
 DEFAULT_BACKEND = Cython()
 
-BACKEND2NUM_THREADS_VAR_NAME = {Cython.__name__: 'OMP_NUM_THREADS', Numba.__name__: 'NUMBA_NUM_THREADS'}
+BACKEND_NAME2ENV_NUM_THREADS_VAR_NAME = {Cython.__name__: 'OMP_NUM_THREADS', Numba.__name__: 'NUMBA_NUM_THREADS'}
 SINGLE_THREADED_BACKENDS = (Scipy.__name__,)

imops/crop.py

@@ -1,5 +1,7 @@
 import numpy as np
 
+from .backend import BackendLike
+from .numeric import _NUMERIC_DEFAULT_NUM_THREADS
 from .pad import pad
 from .utils import AxesLike, AxesParams, broadcast_axis, fill_by_indices
 
@@ -43,10 +45,18 @@ def crop_to_shape(x: np.ndarray, shape: AxesLike, axis: AxesLike = None, ratio:
     ratio = fill_by_indices(np.zeros(ndim), ratio, axis)
     start = ((old_shape - new_shape) * ratio).astype(int)
 
+    # TODO: Create contiguous array?
     return x[tuple(map(slice, start, start + new_shape))]
 
 
-def crop_to_box(x: np.ndarray, box: np.ndarray, axis: AxesLike = None, padding_values: AxesParams = None) -> np.ndarray:
+def crop_to_box(
+    x: np.ndarray,
+    box: np.ndarray,
+    axis: AxesLike = None,
+    padding_values: AxesParams = None,
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
     """
     Crop `x` according to `box` along `axis`.
 
@@ -60,6 +70,11 @@ def crop_to_box(x: np.ndarray, box: np.ndarray, axis: AxesLike = None, padding_v
         axis along which `x` will be cropped
     padding_values: AxesParams
         values to pad with if box exceeds the input's limits
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
 
     Returns
     -------
@@ -86,9 +101,10 @@ def crop_to_box(x: np.ndarray, box: np.ndarray, axis: AxesLike = None, padding_v
 
     slice_start = fill_by_indices(np.zeros(x.ndim, int), slice_start, axis)
     slice_stop = fill_by_indices(x.shape, slice_stop, axis)
+    # TODO: Create contiguous array?
     x = x[tuple(map(slice, slice_start, slice_stop))]
 
     if padding_values is not None and padding.any():
-        x = pad(x, padding, axis, padding_values)
+        x = pad(x, padding, axis, padding_values, num_threads=num_threads, backend=backend)
 
     return x

imops/interp1d.py

@@ -5,6 +5,7 @@ import numpy as np
 from scipy.interpolate import interp1d as scipy_interp1d
 
 from .backend import BackendLike, resolve_backend
+from .numeric import copy as _copy
 from .src._fast_zoom import _interp1d as cython_fast_interp1d
 from .src._zoom import _interp1d as cython_interp1d
 from .utils import normalize_num_threads
@@ -74,7 +75,7 @@ class interp1d:
         num_threads: int = -1,
         backend: BackendLike = None,
     ) -> None:
-        backend = resolve_backend(backend)
+        backend = resolve_backend(backend, warn_stacklevel=3)
         if backend.name not in ('Scipy', 'Numba', 'Cython'):
             raise ValueError(f'Unsupported backend "{backend.name}".')
 
@@ -88,6 +89,7 @@ class interp1d:
             warn(
                 "Fast interpolation is only supported for ndim<=3, dtype=float32 or float64, order=1 or 'linear'. "
                 "Falling back to scipy's implementation.",
+                stacklevel=2,
             )
             self.scipy_interp1d = scipy_interp1d(x, y, kind, axis, copy, bounds_error, fill_value, assume_sorted)
         else:
@@ -114,12 +116,13 @@ class interp1d:
 
             self.fill_value = fill_value
             self.scipy_interp1d = None
-            self.x = np.copy(x) if copy else x
+            # FIXME: how to accurately pass `num_threads` and `backend` arguments to `copy`?
+            self.x = _copy(x, order='C') if copy else x
             self.n_dummy = 3 - y.ndim
             self.y = y[(None,) * self.n_dummy] if self.n_dummy else y
 
             if copy:
-                self.y = np.copy(self.y)
+                self.y = _copy(self.y, order='C')
 
             self.assume_sorted = assume_sorted
 
@@ -149,7 +152,7 @@ class interp1d:
             interpolated values. Shape is determined by replacing the interpolation axis in the original array with
             the shape of x
         """
-        num_threads = normalize_num_threads(self.num_threads, self.backend)
+        num_threads = normalize_num_threads(self.num_threads, self.backend, warn_stacklevel=3)
 
         if self.scipy_interp1d is not None:
             return self.scipy_interp1d(x_new)

imops/measure.py

@@ -19,7 +19,7 @@ from .utils import normalize_num_threads
 
 
 # (ndim, skimage_connectivity) -> cc3d_connectivity
-skimage2cc3d = {
+_SKIMAGE2CC3D = {
     (1, 1): 4,
     (2, 1): 4,
     (2, 2): 8,
@@ -90,7 +90,7 @@ def label(
         raise ValueError(f'Connectivity for {ndim}D image should be in [1, ..., {ndim}]. Got {connectivity}.')
 
     if ndim > 3:
-        warn("Fast label is only supported for ndim<=3, Falling back to scikit-image's implementation.")
+        warn("Fast label is only supported for ndim<=3, Falling back to scikit-image's implementation.", stacklevel=2)
         labeled_image, num_components = skimage_label(
             label_image, background=background, return_num=True, connectivity=connectivity
         )
@@ -110,7 +110,7 @@ def label(
 
         labeled_image, num_components = connected_components(
             label_image,
-            connectivity=skimage2cc3d[(ndim, connectivity)],
+            connectivity=_SKIMAGE2CC3D[(ndim, connectivity)],
             return_N=True,
             **{'out_dtype': dtype} if python_version()[:3] != '3.6' else {},
         )
@@ -174,19 +174,19 @@ def center_of_mass(
     if (labels is None) ^ (index is None):
         raise ValueError('`labels` and `index` should be both specified or both not specified.')
 
-    backend = resolve_backend(backend)
+    backend = resolve_backend(backend, warn_stacklevel=3)
 
     if backend.name not in ('Scipy', 'Cython'):
         raise ValueError(f'Unsupported backend "{backend.name}".')
 
-    num_threads = normalize_num_threads(num_threads, backend)
+    num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=3)
 
     if backend.name == 'Scipy':
         return scipy_center_of_mass(array, labels, index)
 
     ndim = array.ndim
     if ndim > 3:
-        warn("Fast center-of-mass is only supported for ndim<=3. Falling back to scipy's implementation.")
+        warn("Fast center-of-mass is only supported for ndim<=3. Falling back to scipy's implementation.", stacklevel=2)
         return scipy_center_of_mass(array, labels, index)
 
     if labels is None:
@@ -205,7 +205,7 @@ def center_of_mass(
             raise ValueError('`index` should consist of unique values.')
 
         if num_threads > 1:
-            warn('Using single-threaded implementation as `labels` and `index` are specified.')
+            warn('Using single-threaded implementation as `labels` and `index` are specified.', stacklevel=2)
 
         src_center_of_mass = _fast_labeled_center_of_mass if backend.fast else _labeled_center_of_mass
 

imops/morphology.py

@@ -28,12 +28,12 @@ def morphology_op_wrapper(
         num_threads: int = -1,
         backend: BackendLike = None,
     ) -> np.ndarray:
-        backend = resolve_backend(backend)
+        backend = resolve_backend(backend, warn_stacklevel=4)
         if backend.name not in {x.name for x in backend2src_op.keys()}:
             raise ValueError(f'Unsupported backend "{backend.name}".')
 
         ndim = image.ndim
-        num_threads = normalize_num_threads(num_threads, backend)
+        num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=4)
 
         if footprint is None:
             footprint = generate_binary_structure(ndim, 1)
@@ -60,7 +60,8 @@ def morphology_op_wrapper(
         if ndim > 3:
             warn(
                 f"Fast {' '.join(op_name.split('_'))} is only supported for ndim<=3. "
-                "Falling back to scipy's implementation."
+                "Falling back to scipy's implementation.",
+                stacklevel=3,
             )
             output = backend2src_op[Scipy()](image, footprint)
 
@@ -70,13 +71,13 @@ def morphology_op_wrapper(
             raise ValueError('Input image and footprint number of dimensions must be the same.')
 
         if not image.any():
-            warn(f'{op_name} is applied to the fully False mask (mask.any() == False).')
+            warn(f'{op_name} is applied to the fully False mask (mask.any() == False).', stacklevel=3)
             output.fill(False)
 
             return output
 
         if image.all():
-            warn(f'{op_name} is applied to the fully True mask (mask.all() == True).')
+            warn(f'{op_name} is applied to the fully True mask (mask.all() == True).', stacklevel=3)
             output.fill(True)
 
             return output

imops/numeric.py

@@ -0,0 +1,376 @@
+from typing import Callable, Sequence, Union
+
+import numpy as np
+
+from .backend import BackendLike, resolve_backend
+from .src._fast_numeric import (
+    _copy_3d as cython_fast_copy_3d,
+    _copy_3d_fp16 as cython_fast_copy_3d_fp16,
+    _copy_4d as cython_fast_copy_4d,
+    _copy_4d_fp16 as cython_fast_copy_4d_fp16,
+    _fill_3d as cython_fast_fill_3d,
+    _fill_4d as cython_fast_fill_4d,
+    _pointwise_add_array_3d as cython_fast_pointwise_add_array_3d,
+    _pointwise_add_array_3d_fp16 as cython_fast_pointwise_add_array_3d_fp16,
+    _pointwise_add_array_4d as cython_fast_pointwise_add_array_4d,
+    _pointwise_add_array_4d_fp16 as cython_fast_pointwise_add_array_4d_fp16,
+    _pointwise_add_value_3d as cython_fast_pointwise_add_value_3d,
+    _pointwise_add_value_3d_fp16 as cython_fast_pointwise_add_value_3d_fp16,
+    _pointwise_add_value_4d as cython_fast_pointwise_add_value_4d,
+    _pointwise_add_value_4d_fp16 as cython_fast_pointwise_add_value_4d_fp16,
+)
+from .src._numeric import (
+    _copy_3d as cython_copy_3d,
+    _copy_3d_fp16 as cython_copy_3d_fp16,
+    _copy_4d as cython_copy_4d,
+    _copy_4d_fp16 as cython_copy_4d_fp16,
+    _fill_3d as cython_fill_3d,
+    _fill_4d as cython_fill_4d,
+    _pointwise_add_array_3d as cython_pointwise_add_array_3d,
+    _pointwise_add_array_3d_fp16 as cython_pointwise_add_array_3d_fp16,
+    _pointwise_add_array_4d as cython_pointwise_add_array_4d,
+    _pointwise_add_array_4d_fp16 as cython_pointwise_add_array_4d_fp16,
+    _pointwise_add_value_3d as cython_pointwise_add_value_3d,
+    _pointwise_add_value_3d_fp16 as cython_pointwise_add_value_3d_fp16,
+    _pointwise_add_value_4d as cython_pointwise_add_value_4d,
+    _pointwise_add_value_4d_fp16 as cython_pointwise_add_value_4d_fp16,
+)
+from .utils import normalize_num_threads
+
+
+_TYPES = (np.int16, np.int32, np.int64, np.float16, np.float32, np.float64)
+_STR_TYPES = ('int16', 'int32', 'int64', 'float16', 'float32', 'float64')
+# TODO: Decide which value to use. Functions below are quite fast and simple, so parallelization overhead is noticeable.
+_NUMERIC_DEFAULT_NUM_THREADS = 4
+
+
+# TODO: Maybe dict is better?
+def _choose_cython_pointwise_add(ndim: int, summand_is_array: bool, is_fp16: bool, fast: bool) -> Callable:
+    assert ndim <= 4, ndim
+
+    if ndim <= 3:
+        if summand_is_array:
+            if is_fp16:
+                return cython_fast_pointwise_add_array_3d_fp16 if fast else cython_pointwise_add_array_3d_fp16
+
+            return cython_fast_pointwise_add_array_3d if fast else cython_pointwise_add_array_3d
+
+        if is_fp16:
+            return cython_fast_pointwise_add_value_3d_fp16 if fast else cython_pointwise_add_value_3d_fp16
+
+        return cython_fast_pointwise_add_value_3d if fast else cython_pointwise_add_value_3d
+
+    if summand_is_array:
+        if is_fp16:
+            return cython_fast_pointwise_add_array_4d_fp16 if fast else cython_pointwise_add_array_4d_fp16
+
+        return cython_fast_pointwise_add_array_4d if fast else cython_pointwise_add_array_4d
+
+    if is_fp16:
+        return cython_fast_pointwise_add_value_4d_fp16 if fast else cython_pointwise_add_value_4d_fp16
+
+    return cython_fast_pointwise_add_value_4d if fast else cython_pointwise_add_value_4d
+
+
+def _choose_cython_fill_(ndim: int, fast: bool) -> Callable:
+    assert ndim <= 4, ndim
+
+    if ndim <= 3:
+        return cython_fast_fill_3d if fast else cython_fill_3d
+
+    return cython_fast_fill_4d if fast else cython_fill_4d
+
+
+def _choose_cython_copy(ndim: int, is_fp16: bool, fast: bool) -> Callable:
+    assert ndim <= 4, ndim
+
+    if ndim <= 3:
+        if is_fp16:
+            return cython_fast_copy_3d_fp16 if fast else cython_copy_3d_fp16
+
+        return cython_fast_copy_3d if fast else cython_copy_3d
+
+    if is_fp16:
+        return cython_fast_copy_4d_fp16 if fast else cython_copy_4d_fp16
+
+    return cython_fast_copy_4d if fast else cython_copy_4d
+
+
+def pointwise_add(
+    nums: np.ndarray,
+    summand: Union[np.array, int, float],
+    output: np.ndarray = None,
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Perform pointwise addition between array and array or scalar.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    nums: np.ndarray
+        n-dimensional array
+    summand: np.ndarray | int | float
+        array of the same shape or scalar
+    output: np.ndarray
+        array of the same shape as input, into which the output is placed. By default, a new
+        array is created
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    sum: np.ndarray
+        result of summation
+
+    Examples
+    --------
+    >>> sum = pointwise_add(x, 1, x)  # inplace addition
+    >>> sum = pointwise_add(x, 1, backend='Scipy')  # just `np.add`
+    >>> sum = pointwise_add(x.astype('float32'), x.astype('float16'))  # will fail because of different dtypes
+    """
+    backend = resolve_backend(backend, warn_stacklevel=3)
+    if backend.name not in ('Scipy', 'Cython'):
+        raise ValueError(f'Unsupported backend "{backend.name}".')
+
+    dtype = nums.dtype
+
+    if dtype not in _TYPES:
+        raise ValueError(f'Input array dtype must be one of {", ".join(_STR_TYPES)}, got {dtype}.')
+
+    if output is None:
+        output = np.empty_like(nums, dtype=dtype)
+    elif output.shape != nums.shape:
+        raise ValueError(f'Input array and output array shapes must be the same, got {nums.shape} vs {output.shape}.')
+    elif dtype != output.dtype:
+        raise ValueError(f'Input array and output array dtypes must be the same, got {dtype} vs {output.dtype}.')
+
+    summand_is_array = isinstance(summand, np.ndarray)
+    if summand_is_array:
+        if dtype != summand.dtype:
+            raise ValueError(f'Input and summand arrays must have same dtypes, got {dtype} vs {summand.dtype}.')
+    elif not isinstance(summand, (*_TYPES, *(int, float))):
+        raise ValueError(f'Summand dtype must be one of {", ".join(_STR_TYPES)}, got {type(summand)}.')
+    else:
+        summand = dtype.type(summand)
+
+    ndim = nums.ndim
+    num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=3)
+
+    if backend.name == 'Scipy' or ndim > 4:
+        np.add(nums, summand, out=output)
+        return output
+
+    is_fp16 = dtype == np.float16
+    src_pointwise_add = _choose_cython_pointwise_add(ndim, summand_is_array, is_fp16, backend.fast)
+
+    n_dummy = 3 - ndim if ndim <= 3 else 0
+
+    if n_dummy:
+        nums = nums[(None,) * n_dummy]
+        output = output[(None,) * n_dummy]
+        if summand_is_array:
+            summand = summand[(None,) * n_dummy]
+
+    if is_fp16:
+        output = src_pointwise_add(
+            nums.view(np.uint16), summand.view(np.uint16), output.view(np.uint16), num_threads
+        ).view(np.float16)
+    else:
+        output = src_pointwise_add(nums, summand, output, num_threads)
+
+    if n_dummy:
+        output = output[(0,) * n_dummy]
+
+    return output
+
+
+def fill_(
+    nums: np.ndarray,
+    value: Union[np.number, int, float],
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> None:
+    """
+    Fill the array with a scalar value.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    nums: np.ndarray
+        n-dimensional array
+    value: np.number | int | float
+        scalar
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Examples
+    --------
+    >>> fill_(x, 1)
+    >>> fill_(np.empty((2, 3, 4)), 42)
+    >>> fill_(x.astype('uint16'), 3)  # will fail because of unsupported uint16 dtype
+    """
+    backend = resolve_backend(backend, warn_stacklevel=3)
+    if backend.name not in ('Scipy', 'Cython'):
+        raise ValueError(f'Unsupported backend "{backend.name}".')
+
+    ndim = nums.ndim
+    dtype = nums.dtype
+
+    if dtype not in _TYPES or backend.name == 'Scipy' or ndim > 4:
+        nums.fill(value)
+        return
+
+    is_fp16 = dtype == np.float16
+    num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=3)
+    src_fill_ = _choose_cython_fill_(ndim, backend.fast)
+    value = dtype.type(value)
+
+    n_dummy = 3 - ndim if ndim <= 3 else 0
+
+    if n_dummy:
+        nums = nums[(None,) * n_dummy]
+
+    if is_fp16:
+        src_fill_(nums.view(np.uint16), value.view(np.uint16), num_threads)
+    else:
+        src_fill_(nums, value, num_threads)
+
+    if n_dummy:
+        nums = nums[(0,) * n_dummy]
+
+
+def full(
+    shape: Union[int, Sequence[int]],
+    fill_value: Union[np.number, int, float],
+    dtype: Union[type, str] = None,
+    order: str = 'C',
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Return a new array of given shape and type, filled with `fill_value`.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    shape: int | Sequence[int]
+        desired shape
+    fill_value: np.number | int | float
+        scalar to fill array with
+    dtype: type | str
+        desired dtype to which `fill_value` will be casted. If not specified, `np.array(fill_value).dtype` will be used
+    order: str
+        whether to store multidimensional data in C or F contiguous order in memory
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Examples
+    --------
+    >>> x = full((2, 3, 4), 1.0)  # same as `np.ones((2, 3, 4))`
+    >>> x = full((2, 3, 4), 1.5, dtype=int)  # same as np.ones((2, 3, 4), dtype=int)
+    >>> x = full((2, 3, 4), 1, dtype='uint16')  # will fail because of unsupported uint16 dtype
+    """
+    nums = np.empty(shape, dtype=dtype, order=order)
+
+    if dtype is not None:
+        fill_value = nums.dtype.type(fill_value)
+
+    fill_(nums, fill_value, num_threads, backend)
+
+    return nums
+
+
+def copy(
+    nums: np.ndarray,
+    output: np.ndarray = None,
+    order: str = 'K',
+    num_threads: int = _NUMERIC_DEFAULT_NUM_THREADS,
+    backend: BackendLike = None,
+) -> np.ndarray:
+    """
+    Return copy of the given array.
+
+    Uses a fast parallelizable implementation for fp16-32-64 and int16-32-64 inputs and ndim <= 4.
+
+    Parameters
+    ----------
+    nums: np.ndarray
+        n-dimensional array
+    output: np.ndarray
+        array of the same shape and dtype as input, into which the copy is placed. By default, a new
+        array is created
+    order: str
+        controls the memory layout of the copy. `C` means C-order, `F` means F-order, `A` means `F` if a is Fortran
+        contiguous, `C` otherwise. `K` means match the layout of a as closely as possible
+    num_threads: int
+        the number of threads to use for computation. Default = 4. If negative value passed
+        cpu count + num_threads + 1 threads will be used
+    backend: BackendLike
+        which backend to use. `cython` and `scipy` are available, `cython` is used by default
+
+    Returns
+    -------
+    copy: np.ndarray
+        copy of array
+
+    Examples
+    --------
+    >>> copied = copy(x)
+    >>> copied = copy(x, backend='Scipy')  # same as `np.copy`
+    >>> copy(x, output=y)  # copied into `y`
+    """
+    backend = resolve_backend(backend, warn_stacklevel=3)
+    if backend.name not in ('Scipy', 'Cython'):
+        raise ValueError(f'Unsupported backend "{backend.name}".')
+
+    ndim = nums.ndim
+    dtype = nums.dtype
+    num_threads = normalize_num_threads(num_threads, backend, warn_stacklevel=3)
+
+    if output is None:
+        output = np.empty_like(nums, dtype=dtype, order=order)
+    elif output.shape != nums.shape:
+        raise ValueError(f'Input array and output array shapes must be the same, got {nums.shape} vs {output.shape}.')
+    elif dtype != output.dtype:
+        raise ValueError(f'Input array and output array dtypes must be the same, got {dtype} vs {output.dtype}.')
+
+    if dtype not in _TYPES or backend.name == 'Scipy' or ndim > 4:
+        output = np.copy(nums, order=order)
+        return output
+
+    is_fp16 = dtype == np.float16
+    src_copy = _choose_cython_copy(ndim, is_fp16, backend.fast)
+
+    n_dummy = 3 - ndim if ndim <= 3 else 0
+
+    if n_dummy:
+        nums = nums[(None,) * n_dummy]
+        output = output[(None,) * n_dummy]
+
+    if is_fp16:
+        src_copy(nums.view(np.uint16), output.view(np.uint16), num_threads)
+    else:
+        src_copy(nums, output, num_threads)
+
+    if n_dummy:
+        nums = nums[(0,) * n_dummy]
+        output = output[(0,) * n_dummy]
+
+    return output
+
+
+# TODO: add parallel astype?