NumPy 1.14 - __array_interface__

ऐरे इंटरफ़ेस




numpy

ऐरे इंटरफ़ेस

ध्यान दें

यह पृष्ठ अन्य सी एक्सटेंशन से एक खस्ता सरणी की सामग्री तक पहुंचने के लिए संख्यात्मक-विशिष्ट एपीआई का वर्णन करता है। PEP 3118 - The Revised Buffer Protocol किसी भी विस्तार मॉड्यूल का उपयोग करने के लिए समान, मानकीकृत एपीआई पाइथन 2.6 और 3.0 का परिचय देता है। Cython के बफर एरे समर्थन PEP 3118 API का उपयोग करता है; साइथन संख्यात्मक ट्यूटोरियल देखें । साइथॉन कोड लिखने का एक तरीका प्रदान करता है जो पाइथन संस्करणों के साथ 2.6 से अधिक पुराने बफर प्रोटोकॉल का समर्थन करता है क्योंकि इसमें एक बैकवर्ड-संगत कार्यान्वयन है जो यहां वर्णित सरणी इंटरफ़ेस का उपयोग करता है।

संस्करण: 3

सरणी इंटरफ़ेस (कभी-कभी सरणी प्रोटोकॉल कहा जाता है) 2005 में सरणी-जैसे पायथन ऑब्जेक्ट्स के लिए एक-दूसरे के डेटा बफ़र्स को फिर से उपयोग करने के लिए बुद्धिमानी से संभव के रूप में बनाया गया था। सजातीय एन-आयामी सरणी इंटरफ़ेस एन-आयामी सरणी मेमोरी और सूचना साझा करने के लिए वस्तुओं के लिए एक डिफ़ॉल्ट तंत्र है। इंटरफ़ेस में दो विशेषताओं का उपयोग करके पायथन-साइड और एक सी-साइड होते हैं। आवेदन कोड में एन-आयामी सरणी माना जाने की इच्छा रखने वाली वस्तुओं को इनमें से कम से कम एक विशेषता का समर्थन करना चाहिए। अनुप्रयोग कोड में एन-आयामी सरणी का समर्थन करने के इच्छुक वस्तुओं को इनमें से कम से कम एक विशेषता को देखना चाहिए और उचित रूप से प्रदान की गई जानकारी का उपयोग करना चाहिए।

यह इंटरफ़ेस इस अर्थ में सजातीय सरणियों का वर्णन करता है कि सरणी के प्रत्येक आइटम में समान "प्रकार" है। यह प्रकार बहुत सरल हो सकता है या यह काफी मनमानी और जटिल सी-जैसी संरचना हो सकती है।

इंटरफ़ेस का उपयोग करने के दो तरीके हैं: एक पायथन साइड और एक सी-साइड। दोनों अलग-अलग विशेषताएँ हैं।

अजगर पक्ष

इंटरफ़ेस के इस दृष्टिकोण में __array_interface__ विशेषता वाले ऑब्जेक्ट होते हैं।

__array_interface__

वस्तुओं का एक शब्दकोश (3 आवश्यक और 5 वैकल्पिक)। शब्दकोश में वैकल्पिक कुंजियों को प्रदान नहीं किए जाने पर चूक को निहित किया है।

चाबियाँ हैं:

आकार (आवश्यक)

टपल जिसके तत्व प्रत्येक आयाम में सरणी आकार हैं। प्रत्येक प्रविष्टि एक पूर्णांक (एक पायथन इंट या लंबी) है। ध्यान दें कि ये पूर्णांक प्लेटफ़ॉर्म "int" या "लॉन्ग" से बड़े हो सकते हैं (एक पायथन इंट एक C लंबा है)। यह उचित रूप से इस विशेषता को संभालने के लिए इस कोड का उपयोग करना है; अतिप्रवाह संभव होने पर या तो त्रुटि उठाकर या आकार के लिए C प्रकार के रूप में Py_LONG_LONG का उपयोग करके।

टाइपस्ट्रे (आवश्यक)

एक प्रकार के समरूप सरणी के मूल प्रकार प्रदान करने वाली एक स्ट्रिंग में मूल स्ट्रिंग प्रारूप 3 भाग होते हैं: डेटा के बाइटऑर्डर का वर्णन करने वाला वर्ण ( < : Little-endian, > : big-endian;;: not-प्रासंगिक), एक वर्ण कोड। सरणी का मूल प्रकार, और एक पूर्णांक बाइट्स की संख्या प्रदान करता है जो प्रकार का उपयोग करता है।

मूल प्रकार वर्ण कोड हैं:

t बिट फ़ील्ड (पूर्णांक के बाद बिट क्षेत्र में बिट्स की संख्या देता है)।
b बूलियन (पूर्णांक प्रकार जहां सभी मान केवल सत्य या गलत हैं)
i पूर्णांक
u निरुपित पूर्णांक
f तैरनेवाला स्थल
c जटिल अस्थायी बिंदु
m Timedelta
M दिनांक समय
O ऑब्जेक्ट (यानी मेमोरी में PyObject लिए एक पॉइंटर होता है)
S स्ट्रिंग (चार-लंबाई का निश्चित क्रम)
U यूनिकोड ( Py_UNICODE का निश्चित-लम्बाई क्रम)
V अन्य (शून्य * - प्रत्येक आइटम मेमोरी का एक निश्चित आकार का हिस्सा है)

descr (वैकल्पिक)

सजातीय सरणी में प्रत्येक आइटम के लिए मेमोरी लेआउट का अधिक विस्तृत विवरण प्रदान करने वाली टुपल्स की एक सूची। सूची में प्रत्येक टपल में दो या तीन तत्व हैं। आमतौर पर, इस विशेषता का उपयोग तब किया जाएगा जब टाइपस्ट्र्र V[0-9]+ , लेकिन यह एक आवश्यकता नहीं है। केवल आवश्यकता यह है कि टाइपस्ट्र कुंजी में प्रतिनिधित्व बाइट्स की संख्या वही है जो बाइट्स की कुल संख्या का प्रतिनिधित्व करती है। विचार सी-जैसी संरचनाओं के विवरण का समर्थन करना है जो सरणी तत्व बनाते हैं। सूची में प्रत्येक टपल के तत्व हैं

  1. डेटाटाइप के इस भाग से जुड़ा एक नाम प्रदान करने वाली एक स्ट्रिंग। यह ('full name', 'basic_name') का एक टपल भी हो सकता है ('full name', 'basic_name') जहाँ मूल नाम फ़ील्ड के पूर्ण नाम का प्रतिनिधित्व करने वाला एक मान्य पायथन चर नाम होगा।
  2. या तो एक बुनियादी प्रकार का विवरण स्ट्रिंग टाइपस्टार में या दूसरी सूची में (नेस्टेड संरचित प्रकारों के लिए)
  3. एक वैकल्पिक आकार टपल प्रदान करता है कि संरचना के इस हिस्से को कितनी बार दोहराया जाना चाहिए। यदि यह नहीं दिया जाता है तो कोई दोहराए नहीं जाते हैं। इस सामान्य इंटरफ़ेस का उपयोग करके बहुत जटिल संरचनाओं का वर्णन किया जा सकता है। हालाँकि, सूचना है कि सरणी का प्रत्येक तत्व अभी भी एक ही डेटा-प्रकार का है। इस इंटरफ़ेस का उपयोग करने के कुछ उदाहरण नीचे दिए गए हैं।

डिफ़ॉल्ट : [('', typestr)]

डेटा (वैकल्पिक)

2-ट्यूपल जिसका पहला तर्क एक पूर्णांक है (यदि आवश्यक हो तो एक लंबा पूर्णांक) जो सरणी सामग्री को संग्रहीत करने वाले डेटा-क्षेत्र को इंगित करता है। यह सूचक डेटा के पहले तत्व को इंगित करना चाहिए (दूसरे शब्दों में किसी भी ऑफसेट को हमेशा इस मामले में अनदेखा किया जाता है)। टपल में दूसरी प्रविष्टि एक रीड-ओनली फ्लैग है (सही मायने में डेटा क्षेत्र केवल-पढ़ने के लिए है)।

यह विशेषता buffer interface को उजागर करने वाली एक वस्तु भी हो सकती है जिसका उपयोग डेटा साझा करने के लिए किया जाएगा। यदि यह कुंजी मौजूद नहीं है (या None लौटाता है), तो मेमोरी साझाकरण स्वयं ऑब्जेक्ट के बफर इंटरफ़ेस के माध्यम से किया जाएगा। इस मामले में, ऑफसेट कुंजी का उपयोग बफर की शुरुआत को इंगित करने के लिए किया जा सकता है। यदि मेमोरी क्षेत्र सुरक्षित किया जाना है, तो सरणी इंटरफ़ेस को उजागर करने वाली ऑब्जेक्ट के संदर्भ को नई ऑब्जेक्ट द्वारा संग्रहीत किया जाना चाहिए।

डिफ़ॉल्ट : None

स्ट्राइड्स (वैकल्पिक)

या तो None सी-शैली सन्निहित सरणी या स्ट्राइड्स के एक टपल को इंगित करने के लिए जो संबंधित आयाम में अगले सरणी तत्व पर कूदने के लिए आवश्यक बाइट्स की संख्या प्रदान करता है। प्रत्येक प्रविष्टि एक पूर्णांक (एक पायथन int या long ) होनी चाहिए। आकार के साथ, मान एक सी "इंट" या "लॉन्ग" द्वारा दर्शाए जा सकते हैं। कॉलिंग कोड को इसे उचित रूप से संभालना चाहिए, या तो एक त्रुटि को बढ़ाकर या सी में Py_LONG_LONG का उपयोग करके। डिफ़ॉल्ट None जो सी-शैली सन्निहित स्मृति बफर का अर्थ है। इस मॉडल में, सरणी का अंतिम आयाम सबसे तेज़ बदलता है। उदाहरण के लिए, डिफ़ॉल्ट एक ऐसी वस्तु के लिए टपल बनाता है जिसकी सरणी प्रविष्टियाँ 8 बाइट लंबी होती हैं और जिसका आकार (10,20,30) होगा (4800, 240, 8)

डिफ़ॉल्ट : None (C- शैली सन्निहित)

मुखौटा (वैकल्पिक)

सरणी इंटरफ़ेस को उजागर करने वाला None या ऑब्जेक्ट None है। मुखौटा सरणी के सभी तत्वों को केवल सही या सही संकेत के रूप में व्याख्या की जानी चाहिए, जो यह बताता है कि इस सरणी के कौन से तत्व मान्य हैं। इस ऑब्जेक्ट का आकार मूल सरणी के आकार के लिए “broadcastable” होना चाहिए।

डिफ़ॉल्ट : None (सभी सरणी मान मान्य हैं)

ऑफसेट (वैकल्पिक)

एक पूर्णांक सरणी डेटा क्षेत्र में ऑफसेट होता है। इसका उपयोग केवल तब किया जा सकता है जब डेटा None या buffer ऑब्जेक्ट लौटाता हो।

डिफ़ॉल्ट : 0।

संस्करण (आवश्यक)

इंटरफ़ेस का संस्करण दिखाने वाला पूर्णांक (इस संस्करण के लिए 3)। इंटरफ़ेस के भविष्य के संस्करणों को उजागर करने वाली वस्तुओं को अमान्य करने के लिए इसका उपयोग न करने के लिए सावधान रहें।

सी-स्ट्रक्चर एक्सेस

सरणी इंटरफ़ेस के लिए यह दृष्टिकोण केवल एक विशेषता लुकअप और एक अच्छी तरह से परिभाषित सी-संरचना का उपयोग करके किसी सरणी में तेज़ पहुंच की अनुमति देता है।

__array_struct__

A: c: प्रकार: PyCObject जिसके voidptr सदस्य में एक भरा हुआ PyArrayInterface संरचना का सूचक होता है। संरचना के लिए मेमोरी गतिशील रूप से बनाई गई है और PyCObject भी एक उपयुक्त डिस्ट्रक्टर के साथ बनाई गई है, इसलिए इस विशेषता की पुनर्प्राप्ति को केवल Py_DECREF को इस विशेषता द्वारा दी गई वस्तु पर लागू करना होगा जब यह समाप्त हो जाता है। इसके अलावा, या तो डेटा को कॉपी करने की आवश्यकता है, या इस विशेषता को उजागर करने वाले ऑब्जेक्ट के संदर्भ को यह सुनिश्चित करने के लिए आयोजित किया जाना चाहिए कि डेटा को मुक्त नहीं किया गया है। __array_struct__ इंटरफ़ेस को उजागर करने वाली वस्तुओं को भी अपनी मेमोरी को पुनः प्राप्त नहीं करना चाहिए यदि अन्य ऑब्जेक्ट उन्हें संदर्भित कर रहे हैं।

PyArrayInterface संरचना को numpy/ndarrayobject.h में परिभाषित किया गया है:

typedef struct {
  int two;              /* contains the integer 2 -- simple sanity check */
  int nd;               /* number of dimensions */
  char typekind;        /* kind in array --- character code of typestr */
  int itemsize;         /* size of each element */
  int flags;            /* flags indicating how the data should be interpreted */
                        /*   must set ARR_HAS_DESCR bit to validate descr */
  Py_intptr_t *shape;   /* A length-nd array of shape information */
  Py_intptr_t *strides; /* A length-nd array of stride information */
  void *data;           /* A pointer to the first element of the array */
  PyObject *descr;      /* NULL or data-description (same as descr key
                                of __array_interface__) -- must set ARR_HAS_DESCR
                                flag or this will be ignored. */
} PyArrayInterface;

झंडे के सदस्य में 5 बिट्स हो सकते हैं जिसमें दिखाया गया है कि डेटा की व्याख्या कैसे की जानी चाहिए और एक बिट दिखा रहा है कि इंटरफ़ेस की व्याख्या कैसे की जानी चाहिए। डेटा-बिट्स CONTIGUOUS (0x1), FORTRAN (0x2), NOTSWAPPED (0x100), NOTSWAPPED (0x200), और WRITEABLE (0x400) हैं। एक अंतिम ध्वज ARR_HAS_DESCR ( ARR_HAS_DESCR ) इंगित करता है कि इस संरचना में एअरडेस्क्रे फ़ील्ड है या नहीं। जब तक यह ध्वज मौजूद नहीं है, तब तक फ़ील्ड को एक्सेस नहीं किया जाना चाहिए।

16 जून 2006 से नया:

अतीत में अधिकांश कार्यान्वयन में PyCObject के "अवरोही" सदस्य का उपयोग किया गया था (ऊपर दिए गए PyArrayInterface संरचना के "descr" सदस्य के साथ इसे भ्रमित न करें - वे इंटरफ़ेस को उजागर करने वाली वस्तु के लिए सूचक रखने के लिए दो अलग-अलग चीजें हैं)। यह अब इंटरफ़ेस का एक स्पष्ट हिस्सा है। जब PyCObject का उपयोग करके PyCObject_FromVoidPtrAndDesc बनाया जाता है, तो ऑब्जेक्ट के संदर्भ के लिए स्वयं को सुनिश्चित करें।

वर्णन उदाहरण लिखें

स्पष्टता के लिए यह विवरण के कुछ उदाहरण और संबंधित __array_interface__ 'descr' प्रविष्टियां प्रदान करने के लिए उपयोगी है। इन उदाहरणों के लिए स्कॉट गिल्बर्ट का धन्यवाद:

प्रत्येक मामले में, 'descr' कुंजी वैकल्पिक है, लेकिन निश्चित रूप से अधिक जानकारी प्रदान करती है जो विभिन्न अनुप्रयोगों के लिए महत्वपूर्ण हो सकती है:

* Float data
    typestr == '>f4'
    descr == [('','>f4')]

* Complex double
    typestr == '>c8'
    descr == [('real','>f4'), ('imag','>f4')]

* RGB Pixel data
    typestr == '|V3'
    descr == [('r','|u1'), ('g','|u1'), ('b','|u1')]

* Mixed endian (weird but could happen).
    typestr == '|V8' (or '>u8')
    descr == [('big','>i4'), ('little','<i4')]

* Nested structure
    struct {
        int ival;
        struct {
            unsigned short sval;
            unsigned char bval;
            unsigned char cval;
        } sub;
    }
    typestr == '|V8' (or '<u8' if you want)
    descr == [('ival','<i4'), ('sub', [('sval','<u2'), ('bval','|u1'), ('cval','|u1') ]) ]

* Nested array
    struct {
        int ival;
        double data[16*4];
    }
    typestr == '|V516'
    descr == [('ival','>i4'), ('data','>f8',(16,4))]

* Padded structure
    struct {
        int ival;
        double dval;
    }
    typestr == '|V16'
    descr == [('ival','>i4'),('','|V4'),('dval','>f8')]

यह स्पष्ट होना चाहिए कि इस इंटरफ़ेस का उपयोग करके किसी भी संरचित प्रकार का वर्णन किया जा सकता है।

ऐरे इंटरफ़ेस के साथ अंतर (संस्करण 2)

संस्करण 2 इंटरफ़ेस बहुत समान था। मतभेद काफी हद तक सौंदर्यवादी थे। विशेष रूप से:

  1. PyArrayInterface संरचना के अंत में कोई अवरोही सदस्य नहीं था (और इसलिए कोई ध्वज ARR_HAS_ESES नहीं था)
  2. PyCObject के अवर सदस्य __array_struct__ से लौटे निर्दिष्ट नहीं थे। आमतौर पर, यह एरे को उजागर करने वाली वस्तु थी (ताकि सी-ऑब्जेक्ट के नष्ट होने पर इसका एक संदर्भ रखा जा सके और नष्ट किया जा सके)। अब यह टपल होना चाहिए जिसका पहला तत्व "PyArrayInterface संस्करण #" के साथ एक स्ट्रिंग है और जिसका दूसरा तत्व सरणी को उजागर करने वाली वस्तु है।
  3. टपल __array_interface __ ['डेटा'] से लौटा है जो एक हेक्स-स्ट्रिंग हुआ करता था (अब यह एक पूर्णांक या एक लंबा पूर्णांक है)।
  4. __Array_interface__ डिक्शनरी में सभी कुंजियों (संस्करण को छोड़कर) की बजाय कोई __array_interface__ विशेषता नहीं थी। शब्दकोश उनकी अपनी विशेषता थी: इस प्रकार पायथन-साइड जानकारी प्राप्त करने के लिए आपको अलग-अलग विशेषताओं तक पहुंचना था:
    • __array_data__
    • __array_shape__
    • __array_strides__
    • __array_typestr__
    • __array_descr__
    • __array_offset__
    • __array_mask__