# util¶

The util module provides a collection of general purpose methods.

class nutils.util.NanVec(length)

Bases: `numpy.ndarray`

nan-initialized vector

nutils.util.tri_merge(tri, x, mergetol=0)

Create connected triangulation by connecting (near) identical points.

Based on a set of coordinates `x`, create a modified copy of `tri` with any occurrence of `j` replaced by `i` if `x[i]` equals `x[j]` within specified tolerance. The result is a triangulation that remains valid for any associated data vector that follows the same equality relations.

Example:

```>>> x = [0,0], [1,0], [0,1], [1,0], [1,1] # note: x[1] == x[3])
>>> tri = [0,1,2], [2,3,4]
>>> tri_merge(tri, x)
array([[0, 1, 2],
[2, 1, 4]])
```

Requires scipy.

Parameters
• x (`float` array) – Vertex coordinates.

• tri (`int` array) – Triangulation.

• mergetol (`float` (optional, default 0)) – Distance within which two points are considered equal. If mergetol == 0 then points are considered equal if and only if their coordinates are identical. If mergetol > 0 (required scipy) then points are considered equal if they are within euclidian distance < mergetol. If mergetol < 0 then tri is returned unchanged.

Returns

merged_tri

Return type

`int` array

class nutils.util.tri_interpolator(tri, x, mergetol=0)

Bases: `object`

Interpolate function values defined in triangulation vertices.

Convenience object that implements 2D interpolation on top of matplotlib’s triangulation routines. Unlike matplotlib’s own `LinearTriInterpolator`, the `tri_interpolator` allows for interpolation of multi-dimensional arrays, as well as repeated interpolations of different vertex values.

The arguments are identical to `tri_merge()`.

After instantiation of the interpolator object, interpolation coordinates are specified via the object’s getitem operator. The resulting callable performs the interpolation:

```>>> trix = [0,0], [1,0], [0,1], [1,1] # vertex coordinates
>>> triu = 0, 0, 10, 0 # vertex values
>>> interpolate = tri_interpolator([[0,1,2],[1,3,2]], trix)
>>> x = [.1,.1], [.1,.9], [.9,.9] # interpolation coordinates
>>> u = interpolate[x](triu) # interpolated values
```

Requires matplotlib.

__weakref__

list of weak references to the object (if defined)

nutils.util.obj2str(obj)

compact, lossy string representation of arbitrary object

class nutils.util.single_or_multiple(f)

Bases: `object`

Method wrapper, converts first positional argument to tuple: tuples/lists are passed on as tuples, other objects are turned into tuple singleton. Return values should match the length of the argument list, and are unpacked if the original argument was not a tuple/list.

```>>> class Test:
...   @single_or_multiple
...   def square(self, args):
...     return [v**2 for v in args]
...
>>> T = Test()
>>> T.square(2)
4
>>> T.square([2,3])
(4, 9)
```
Parameters

f (`callable`) – Method that expects a tuple as first positional argument, and that returns a list/tuple of the same length.

Returns

Wrapped method.

__weakref__

list of weak references to the object (if defined)

class nutils.util.positional_only(f)

Bases: `object`

Change all positional-or-keyword arguments to positional-only.

Python introduces syntax to define positional-only parameters in version 3.8, but the same effect can be achieved in older versions by using a wrapper with a var-positional argument. The `positional_only()` decorator uses this technique to treat all positional-or-keyword arguments as positional-only. In order to avoid name clashes between the positional-only arguments and variable keyword arguments, the wrapper additionally introduces the convention that the last argument receives the variable keyword argument dictionary in case is has a default value of … (ellipsis).

Example:

```>>> @positional_only
... def f(x, *, y):
...   pass
>>> inspect.signature(f)
<Signature (x, /, *, y)>
```
```>>> @positional_only
... def f(x, *args, y, kwargs=...):
...   pass
>>> inspect.signature(f)
<Signature (x, /, *args, y, **kwargs)>
```
Parameters

f (`callable`) – Function to be wrapped.

__weakref__

list of weak references to the object (if defined)

Find and load a dynamic library using `ctypes.CDLL`. For each (supported) platform the name of the library should be specified as a keyword argument, including the extension, where the keywords should match the possible values of `sys.platform`.

Example

To load the Intel MKL runtime library, write:

```loadlib(linux='libmkl_rt.so', darwin='libmkl_rt.dylib', win32='mkl_rt.dll')
```

Parameters

path (`os.PathLike`, `str` or `io.TextIOBase`) – Path-like or file-like object pointing to the data to be read.

Returns

File data as `str`.

nutils.util.binaryfile(path)

Parameters

path (`os.PathLike`, `str` or `io.BufferedIOBase`) – Path-like or file-like object pointing to the data to be read.

Returns

Context that returns a `io.BufferedReader` upon entry.

class nutils.util.settable(value=None)

Bases: `object`

Context-switchable data container.

A mutable container for a general Python object, which can be changed by entering the `sets` context. The current value can be accessed via the `value` attribute.

```>>> myprop = settable(2)
>>> myprop.value
2
>>> with myprop.sets(3):
...   myprop.value
3
>>> myprop.value
2
```
nutils.util.index(sequence, item)

Index of first occurrence.

Generalization of tuple.index.

nutils.util.unique(items, key=None)

Deduplicate items in sequence.

Return a tuple (unique, indices) such that items[i] == unique[indices[i]] and unique does not contain duplicate items. An optional key is applied to all items before testing for equality.