numpy.nditer

class numpy.nditer [source]

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

Параметры:

op : ndarray or sequence of array_like Массив(ы) для итерации. flags : sequence of str, optional Флаги для управления поведением итератора. “buffered” включает буферизацию при необходимости. “c_index” отслеживает индекс в порядке C. “f_index” отслеживает индекс в порядке Fortran. “multi_index” отслеживает многомерный индекс, или кортеж индексов, по одному на размерность итерации. “common_dtype” приводит все операнды к общему типу данных с копированием или буферизацией при необходимости. “copy_if_overlap” заставляет итератор определять, имеют ли считываемые операнды перекрытие с записываемыми операндами, и создавать временные копии по мере необходимости, чтобы избежать перекрытия. Возможны ложные срабатывания (необходимое копирование) в некоторых случаях. “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 : list of list of str, optional Это список флагов для каждого операнда. Минимально, один из “readonly”, “readwrite” или “writeonly” должен быть указан. “readonly” означает, что операнд будет только читаться. “readwrite” означает, что операнд будет читаться и записываться. “writeonly” означает, что операнд будет только записываться. “no_broadcast” предотвращает широковещание операнда. “contig” принудительно делает данные операнда непрерывными. “aligned” принудительно выравнивает данные операнда. “nbo” принудительно устанавливает порядок байтов операнда в родной. “copy” позволяет временную только-для-чтения копию при необходимости. “updateifcopy” позволяет временную чтение-запись копию при необходимости. “allocate” заставляет выделить массив, если он равен None в параметре op. “no_subtype” предотвращает использование подтипа для операнда “allocate”. “arraymask” указывает, что этот операнд - маска для выбора элементов при записи в операнды с флагом 'writemasked'. Итератор не навязывает это, но при записи из буфера обратно в массив, он копирует только те элементы, которые указаны этой маской. ‘writemasked’ указывает, что будут записаны только элементы, где выбранный операнд ‘arraymask’ равен True. “overlap_assume_elementwise” может использоваться для обозначения операндов, которые обращаются только в порядке итератора, чтобы разрешить менее консервативное копирование, когда присутствует “copy_if_overlap”. op_dtypes : dtype or tuple of dtype(s), optional Требуемые типы данных операндов. Если включено копирование или буферизация, данные будут преобразованы в/из их исходных типов. order : {‘C’, ‘F’, ‘A’, ‘K’}, optional Управляет порядком итерации. ‘C’ означает порядок C, ‘F’ — порядок Fortran, ‘A’ — порядок ‘F’, если все массивы являются непрерывными в порядке Fortran, в противном случае — порядок ‘C’, а ‘K’ — как можно ближе к порядку появления элементов массива в памяти. Это также влияет на порядок памяти элементов операндов “allocate”, так как они выделяются, чтобы соответствовать порядку итерации. По умолчанию — ‘K’. casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional Управляет тем, какие преобразования типов могут произойти при копировании или буферизации. Не рекомендуется устанавливать это в 'unsafe', так как это может негативно повлиять на накопления. ‘no’ означает, что типы данных вообще не должны преобразовываться. ‘equiv’ означает, что разрешены только изменения порядка байтов. ‘safe’ означает, что разрешены только преобразования, которые могут сохранить значения. ‘same_kind’ означает, что разрешены только безопасные преобразования или преобразования в рамках одного типа, например, float64 в float32. ‘unsafe’ означает, что любые преобразования данных могут быть выполнены. op_axes : list of list of ints, optional Если указано, представляет собой список целых чисел или None для каждого операнда. Список осей для операнда — это отображение из измерений итератора в измерения операнда. Значение -1 может быть размещено для записей, заставляя эту размерность обрабатываться как “newaxis”. itershape : tuple of ints, optional Желаемая форма итератора. Это позволяет операндам “allocate” с измерениями, сопоставленными с op_axes, не соответствующими измерениям другого операнда, получить значение, не равное 1 для этого измерения. buffersize : int, optional При включенной буферизации управляет размером временных буферов. Установите в 0 для значения по умолчанию.

Примечания

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

Интерфейс Python предоставляет два интерфейса итерации: один, следуя протоколу Python iterator, и другой, отражающий схему do-while в стиле C. Родной подход 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']])
    with it:
        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']])
    with it:
        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=[list(range(x.ndim)) + [-1] * y.ndim,
                     [-1] * x.ndim + list(range(y.ndim)),
                     None])
    with it:
        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])

Если используются флаги операндов “writeonly” или “readwrite”, операнды могут быть представлениями исходных данных со флагом WRITEBACKIFCOPY. В этом случае nditer должен использоваться как контекстный менеджер или метод nditer.close должен быть вызван перед использованием результата. Временные данные будут записаны обратно в исходные данные при вызове функции __exit__, но не раньше:

>>> a = np.arange(6, dtype='i4')[::-2]
>>> with nditer(a, [],
...        [['writeonly', 'updateifcopy']],
...        casting='unsafe',
...        op_dtypes=[np.dtype('f4')]) as i:
...    x = i.operands[0]
...    x[:] = [-1, -2, -3]
...    # a still unchanged here
>>> a, x
array([-1, -2, -3]), array([-1, -2, -3])

Важно отметить, что после выхода из итератора висячие ссылки (например, x в примере) могут или не могут совместно использовать данные с исходными данными a. Если семантика writeback была активна, то есть если x.base.flags.writebackifcopy равно True, то выход из итератора прервет связь между x и a, запись в x больше не будет записывать в a. Если семантика writeback не активна, то x.data по-прежнему будет указывать на какую-то часть a.data, и запись в одну из них будет влиять на другую.

Атрибуты:

dtypes : tuple of 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 Требуется ли доступ к API Python для итерации, например, если один из операндов является массивом объектов. iterindex : int Индекс, соответствующий порядку итерации. itersize : int Размер итератора. itviews Структурированные представления operands в памяти, соответствующие переупорядоченному и оптимизированному шаблону доступа к итератору. Действительно только до закрытия итератора. multi_index Если использовался флаг «multi_index», это свойство предоставляет доступ к индексу. Вызывает ValueError, если доступ к нему осуществляется и has_multi_index равно False. ndim : int Размерность итератора. nop : int Количество операндов итератора. operands : tuple of operand(s) operands[Slice] shape : tuple of ints Кортеж форм, форма итератора. value Значение operands на текущей итерации. Обычно это кортеж скаляров массива, но если используется флаг «external_loop», это кортеж одномерных массивов.

Методы

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