numpy.nditer

class numpy.nditer [source]

Эффективный многомерный итератор для перебора массивов. Чтобы начать использовать этот объект, см. вводное руководство по итерации массивов.

Параметры:

op : ndarray или последовательность массивов Массив(ы) для перебора. flags : последовательность строк, необязательно Флаги для управления поведением итератора. “buffered” включает буферизацию при необходимости. “c_index” отслеживает индекс в порядке C. “f_index” отслеживает индекс в порядке Fortran. “multi_index” отслеживает многомерный индекс или кортеж индексов, по одному на размерность итерации. “common_dtype” приводит все операнды к общему типу данных с копированием или буферизацией по необходимости. “delay_bufalloc” откладывает выделение буферов до вызова reset(). Позволяет операндам “allocate” быть инициализированными до копирования их значений в буферы. “external_loop” приводит операнды, указанные в values, к одномерным массивам с несколькими значениями вместо нульмерных массивов. “grow_inner” позволяет делать размер массивов value больше размера буфера, когда используются оба флага “buffered” и “external_loop”. “ranged” позволяет ограничить итератор подмножеством значений iterindex. “refs_ok” позволяет итерацию по ссылкам, таким как массивы объектов. “reduce_ok” позволяет итерацию по операндам “readwrite”, которые транслируются, также известным как операнды сокращения. “zerosize_ok” позволяет itersize быть равным нулю. op_flags : список списков строк, необязательно Это список флагов для каждого операнда. По меньшей мере, один из флагов “readonly”, “readwrite” или “writeonly” должен быть указан. “readonly” указывает, что операнд будет только считываться. “readwrite” указывает, что операнд будет считываться и записываться. “writeonly” указывает, что операнд будет только записываться. “no_broadcast” предотвращает трансляцию операнда. “contig” заставляет данные операнда быть непрерывными. “aligned” заставляет данные операнда быть выровненными. “nbo” заставляет данные операнда быть в родном порядке байтов. “copy” позволяет временную только для чтения копию при необходимости. “updateifcopy” позволяет временную копию для чтения и записи при необходимости. “allocate” заставляет массив быть выделенным, если он равен None в параметре op. “no_subtype” предотвращает использование подтипа операндом “allocate”. “arraymask” указывает, что этот операнд — маска, используемая для выбора элементов при записи в операнды с флагом ‘writemasked’. Итератор не проверяет это, но при записи из буфера обратно в массив он копирует только те элементы, которые указаны этой маской. ‘writemasked’ указывает, что будут записаны только элементы, где выбранный операнд ‘arraymask’ равен True. op_dtypes : dtype или кортеж dtype(s), необязательно Требуемый(е) тип(ы) данных операндов. Если включено копирование или буферизация, данные будут преобразованы в/из их исходных типов. order : {‘C’, ‘F’, ‘A’, ‘K’}, необязательно Управляет порядком итерации. ‘C’ означает порядок C, ‘F’ означает порядок Fortran, ‘A’ означает ‘F’ порядок, если все массивы имеют непрерывный порядок Fortran, в противном случае — ‘C’ порядок, а ‘K’ означает как можно ближе к порядку, в котором элементы массива появляются в памяти. Это также влияет на порядок памяти элементов операндов “allocate”, поскольку они выделяются для совместимости с порядком итерации. По умолчанию — ‘K’. casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, необязательно Управляет видом преобразования данных, которое может произойти при копировании или буферизации. Не рекомендуется устанавливать значение ‘unsafe’, поскольку это может негативно сказаться на накоплении. ‘no’ означает, что типы данных вообще не должны преобразовываться. ‘equiv’ означает, что разрешены только изменения порядка байтов. ‘safe’ означает, что разрешены только преобразования, которые могут сохранить значения. ‘same_kind’ означает, что разрешены только безопасные преобразования или преобразования в пределах одного вида, например, float64 в float32. ‘unsafe’ означает, что могут быть произведены любые преобразования данных. op_axes : список списков целых чисел, необязательно Если предоставлен, представляет собой список целых чисел или None для каждого операнда. Список осей для операнда — это отображение из измерений итератора на измерения операнда. Значение -1 можно поместить для элементов, заставляя эту размерность обрабатываться как “newaxis”. itershape : кортеж целых чисел, необязательно Желаемая форма итератора. Это позволяет операндам “allocate” с размерностью, сопоставленной с op_axes, не соответствующей размерности другого операнда, получить значение, отличное от 1 для этой размерности. buffersize : целое число, необязательно При включенной буферизации управляет размером временных буферов. Устанавливается в 0 для значения по умолчанию.

Примечания

nditer заменяет flatiter. Реализация итератора за nditer также доступна в Numpy C API.

Python-интерфейс предоставляет два интерфейса итерации: один, который следует протоколу Python-итератора, и другой, который отражает шаблон стиля C do-while. Подход на основе Python лучше в большинстве случаев, но если вам нужны координаты или индекс итератора, используйте шаблон стиля C.

Примеры

Вот как мы можем написать функцию iter_add, используя протокол Python-итератора:

def iter_add_py(x, y, out=None):
    addop = np.add
    it = np.nditer([x, y, out], [],
                [['readonly'], ['readonly'], ['writeonly','allocate']])
    for (a, b, c) in it:
        addop(a, b, out=c)
    return it.operands[2]

Вот та же функция, но следующая шаблону стиля C:

def iter_add(x, y, out=None):
    addop = np.add

    it = np.nditer([x, y, out], [],
                [['readonly'], ['readonly'], ['writeonly','allocate']])

    while not it.finished:
        addop(it[0], it[1], out=it[2])
        it.iternext()

    return it.operands[2]

Вот пример функции внешнего произведения:

def outer_it(x, y, out=None):
    mulop = np.multiply

    it = np.nditer([x, y, out], ['external_loop'],
            [['readonly'], ['readonly'], ['writeonly', 'allocate']],
            op_axes=[range(x.ndim)+[-1]*y.ndim,
                     [-1]*x.ndim+range(y.ndim),
                     None])

    for (a, b, c) in it:
        mulop(a, b, out=c)

    return it.operands[2]

>>> a = np.arange(2)+1
>>> b = np.arange(3)+1
>>> outer_it(a,b)
array([[1, 2, 3],
       [2, 4, 6]])

Вот пример функции, которая работает как «лямбда»-функция ufunc:

def luf(lamdaexpr, *args, **kwargs):
    "luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)"
    nargs = len(args)
    op = (kwargs.get('out',None),) + args
    it = np.nditer(op, ['buffered','external_loop'],
            [['writeonly','allocate','no_broadcast']] +
                            [['readonly','nbo','aligned']]*nargs,
            order=kwargs.get('order','K'),
            casting=kwargs.get('casting','safe'),
            buffersize=kwargs.get('buffersize',0))
    while not it.finished:
        it[0] = lamdaexpr(*it[1:])
        it.iternext()
    return it.operands[0]

>>> a = np.arange(5)
>>> b = np.ones(5)
>>> luf(lambda i,j:i*i + j/2, a, b)
array([  0.5,   1.5,   4.5,   9.5,  16.5])

Атрибуты

dtypes	(кортеж dtype(s)) Типы данных значений, предоставленных в value. Это может отличаться от типов данных операндов, если включена буферизация.
finished	(bool) Закончена ли итерация по операндам.
has_delayed_bufalloc	(bool) Если True, итератор был создан с флагом “delay_bufalloc”, и на нём ещё не вызывалась функция reset().
has_index	(bool) Если True, итератор был создан с флагом “c_index” или “f_index”, и свойство index может быть использовано для его получения.
has_multi_index	(bool) Если True, итератор был создан с флагом “multi_index”, и свойство multi_index может быть использовано для его получения.
index :	Когда использовался флаг “c_index” или “f_index”, это свойство обеспечивает доступ к индексу. Вызывает ValueError, если обращение происходит, когда has_index равен False.
iterationneedsapi	(bool) Требуется ли доступ к Python API для итерации, например, если один из операндов — массив объектов.
iterindex	(int) Индекс, соответствующий порядку итерации.
itersize	(int) Размер итератора.
itviews :	Структурированный(ые) вид(ы) operands в памяти, соответствующий переупорядоченному и оптимизированному шаблону доступа к итератору.
multi_index :	Когда использовался флаг “multi_index”, это свойство обеспечивает доступ к индексу. Вызывает ValueError, если обращение происходит, когда has_multi_index равен False.
ndim	(int) Размерность итератора.
nop	(int) Количество операндов итератора.
operands	(кортеж операндов) Массив(ы) для перебора.
shape	(кортеж целых чисел) Кортеж формы, форма итератора.
value :	Значение operands на текущей итерации. Обычно это кортеж из массивов скаляров, но если используется флаг “external_loop”, это кортеж одномерных массивов.

Методы

copy()	Получить копию итератора в его текущем состоянии.
debug_print()	Вывести текущее состояние экземпляра nditer и отладочную информацию в stdout.
enable_external_loop()	Если «external_loop» не использовался во время создания, но требуется, это изменяет поведение итератора так, как если бы флаг был указан.
iternext()	Проверить, есть ли оставшиеся итерации, и выполнить одну внутреннюю итерацию без возврата результата.
next	x.next() -> следующее значение или исключение StopIteration
remove_axis(i)	Удаляет ось i из итератора.
remove_multi_index()	Если был указан флаг «multi_index», он удаляет его, что позволяет дальнейшей оптимизации внутренней структуры итерации.
reset()	Сбросить итератор в исходное состояние.