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, также экспонируется API NumPy C.

Экспонирование Python предоставляет два интерфейса итерации, один из которых следует протоколу итерации Python, а другой — схеме «do-while» в стиле C. В большинстве случаев подход нативной 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']])
    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()	Сброс итератора в начальное состояние.