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” позволяет итерацию по типам ссылок, таким как массивы object. “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, также экспонируется через C API Numpy.

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

Примеры

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

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 и отладочную информацию в стандартный вывод.
enable_external_loop()	Если при создании не использовался «external_loop», но он требуется, это изменяет поведение итератора так, как будто флаг был указан.
iternext()	Проверить, остались ли итерации, и выполнить одну внутреннюю итерацию без возвращения результата.
next	x.next() -> следующее значение или исключение StopIteration
remove_axis(i)	Удаляет ось i из итератора.
remove_multi_index()	Если был указан флаг «multi_index», это удаляет его, что позволяет дополнительно оптимизировать внутреннюю структуру итерации.
reset()	Сбросить итератор в его начальное состояние.