nanoutils.numpy_utils

Utility functions related to numpy.

Note that these functions require the NumPy package.

See also

NumPy is the fundamental package needed for scientific computing with Python. It provides:

• a powerful N-dimensional array object

• sophisticated (broadcasting) functions

• tools for integrating C/C++ and Fortran code

• useful linear algebra, Fourier transform, and random number capabilities

Index

as_nd_array(array, dtype[, ndmin, copy])	Construct a numpy array from an iterable or array-like object.
array_combinations(array[, r, axis])	Construct an array with all combinations() of ar along a use-specified axis.
fill_diagonal_blocks(array, i, j[, val])	Fill diagonal blocks in array of size \((i, j)\).
DTypeMapping([iterable])	A mapping for creating structured dtypes.
MutableDTypeMapping([iterable])	A mutable mapping for creating structured dtypes.

API

nanoutils.as_nd_array(array, dtype, ndmin=1, copy=False)

Construct a numpy array from an iterable or array-like object.

Examples

>>> from nanoutils import as_nd_array

>>> as_nd_array(1, int)
array([1])

>>> as_nd_array([1, 2, 3, 4], int)
array([1, 2, 3, 4])

>>> iterator = iter([1, 2, 3, 4])
>>> as_nd_array(iterator, int)
array([1, 2, 3, 4])

Parameters:

• array (Iterable or array-like) – An array-like object or an iterable consisting of scalars.

• dtype (type or numpy.dtype) – The data type of the to-be returned array.

• ndmin (int) – The minimum dimensionality of the to-be returned array.

• copy (bool) – If True, always return a copy.

Returns:

A numpy array constructed from value.

Return type:

numpy.ndarray

nanoutils.array_combinations(array, r=2, axis=-1)

Construct an array with all combinations() of ar along a use-specified axis.

Examples

>>> from nanoutils import array_combinations

>>> array = [[1, 2, 3, 4],
...          [5, 6, 7, 8]]

>>> array_combinations(array, r=2)
array([[[1, 2],
        [5, 6]],

       [[1, 3],
        [5, 7]],

       [[1, 4],
        [5, 8]],

       [[2, 3],
        [6, 7]],

       [[2, 4],
        [6, 8]],

       [[3, 4],
        [7, 8]]])

Parameters:

• array (array-like, shape \((m, \dotsc)\)) – An \(n\) dimensional array-like object.

• r (int) – The length of each combination.

• axis (int) – The axis used for constructing the combinations.

Returns:

A \(n+1\) dimensional array with all ar combinations (of length r) along the user-specified axis. The variable \(k\) herein represents the number of combinations: \(k = \dfrac{m! / r!}{(m-r)!}\).

Return type:

numpy.ndarray, shape \((k, \dotsc, r)\)

nanoutils.fill_diagonal_blocks(array, i, j, val=nan)

Fill diagonal blocks in array of size \((i, j)\).

The blocks are filled along the last 2 axes in array. Performs an inplace update of array.

Examples

>>> import numpy as np
>>> from nanoutils import fill_diagonal_blocks

>>> array = np.zeros((10, 15), dtype=int)
>>> i = 2
>>> j = 3

>>> fill_diagonal_blocks(array, i, j, val=1)
>>> print(array)
[[1 1 1 0 0 0 0 0 0 0 0 0 0 0 0]
 [1 1 1 0 0 0 0 0 0 0 0 0 0 0 0]
 [0 0 0 1 1 1 0 0 0 0 0 0 0 0 0]
 [0 0 0 1 1 1 0 0 0 0 0 0 0 0 0]
 [0 0 0 0 0 0 1 1 1 0 0 0 0 0 0]
 [0 0 0 0 0 0 1 1 1 0 0 0 0 0 0]
 [0 0 0 0 0 0 0 0 0 1 1 1 0 0 0]
 [0 0 0 0 0 0 0 0 0 1 1 1 0 0 0]
 [0 0 0 0 0 0 0 0 0 0 0 0 1 1 1]
 [0 0 0 0 0 0 0 0 0 0 0 0 1 1 1]]

Parameters:

• array (numpy.ndarray) – A >= 2D NumPy array whose diagonal blocks are to be filled. Gets modified in-place.

• i (int) – The size of the diagonal blocks along axis -2.

• j (int) – The size of the diagonal blocks along axis -1.

• val (float) – Value to be written on the diagonal. Its type must be compatible with that of the array a.

Return type:

None

class nanoutils.DTypeMapping(iterable=None, /, **fields)

A mapping for creating structured dtypes.

Examples

>>> from nanoutils import DTypeMapping
>>> import numpy as np

>>> DType1 = DTypeMapping({"x": float, "y": float, "z": float, "symbol": (str, 2)})
>>> print(DType1)
DTypeMapping(
    x      = float64,
    y      = float64,
    z      = float64,
    symbol = <U2,
)

>>> DType1.x
dtype('float64')

>>> DType1.symbol
dtype('<U2')

>>> @DTypeMapping.from_type
... class DType2:
...     xyz = (float, 3)
...     symbol = (str, 2)
...     charge = np.int64

>>> print(DType2)
DTypeMapping(
    xyz    = ('<f8', (3,)),
    symbol = <U2,
    charge = int64,
)

property dtype

Get a structured dtype constructed from dtype mapping.

classmethod from_type(type_obj)

Construct a new dtype mapping from all public attributes of the decorated type object.

Example

>>> from nanoutils import DTypeMapping

>>> @DTypeMapping.from_type
... class AtomsDType:
...     xyz = (float, 3)
...     symbol = (str, 2)
...     charge = np.int64

>>> print(AtomsDType)
DTypeMapping(
    xyz    = ('<f8', (3,)),
    symbol = <U2,
    charge = int64,
)

Parameters:

type_obj (type) – A type object or any object that supports vars().

classmethod fromkeys(iterable, value=None)

Create a new dictionary with keys from iterable and values set to value.

class nanoutils.MutableDTypeMapping(iterable=None, /, **fields)

A mutable mapping for creating structured dtypes.

Examples

>>> from nanoutils import DTypeMapping
>>> import numpy as np

>>> DType1 = MutableDTypeMapping({"x": float, "y": float, "z": float, "symbol": (str, 2)})
>>> print(DType1)
MutableDTypeMapping(
    x      = float64,
    y      = float64,
    z      = float64,
    symbol = <U2,
)

>>> @MutableDTypeMapping.from_type
... class DType2:
...     xyz = (float, 3)
...     symbol = (str, 2)
...     charge = np.int64

>>> print(DType2)
MutableDTypeMapping(
    xyz    = ('<f8', (3,)),
    symbol = <U2,
    charge = int64,
)

property dtype

Get a structured dtype constructed from the mapping.

update(iterable=None, /, **fields)

Update the mapping from the passed mapping or iterable.