1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844 |
- """
- This is only meant to add docs to objects defined in C-extension modules.
- The purpose is to allow easier editing of the docstrings without
- requiring a re-compile.
- NOTE: Many of the methods of ndarray have corresponding functions.
- If you update these docstrings, please keep also the ones in
- core/fromnumeric.py, core/defmatrix.py up-to-date.
- """
- from numpy.core import numerictypes as _numerictypes
- from numpy.core import dtype
- from numpy.core.function_base import add_newdoc
- ###############################################################################
- #
- # flatiter
- #
- # flatiter needs a toplevel description
- #
- ###############################################################################
- add_newdoc('numpy.core', 'flatiter',
- """
- Flat iterator object to iterate over arrays.
- A `flatiter` iterator is returned by ``x.flat`` for any array `x`.
- It allows iterating over the array as if it were a 1-D array,
- either in a for-loop or by calling its `next` method.
- Iteration is done in row-major, C-style order (the last
- index varying the fastest). The iterator can also be indexed using
- basic slicing or advanced indexing.
- See Also
- --------
- ndarray.flat : Return a flat iterator over an array.
- ndarray.flatten : Returns a flattened copy of an array.
- Notes
- -----
- A `flatiter` iterator can not be constructed directly from Python code
- by calling the `flatiter` constructor.
- Examples
- --------
- >>> x = np.arange(6).reshape(2, 3)
- >>> fl = x.flat
- >>> type(fl)
- <class 'numpy.flatiter'>
- >>> for item in fl:
- ... print(item)
- ...
- 0
- 1
- 2
- 3
- 4
- 5
- >>> fl[2:4]
- array([2, 3])
- """)
- # flatiter attributes
- add_newdoc('numpy.core', 'flatiter', ('base',
- """
- A reference to the array that is iterated over.
- Examples
- --------
- >>> x = np.arange(5)
- >>> fl = x.flat
- >>> fl.base is x
- True
- """))
- add_newdoc('numpy.core', 'flatiter', ('coords',
- """
- An N-dimensional tuple of current coordinates.
- Examples
- --------
- >>> x = np.arange(6).reshape(2, 3)
- >>> fl = x.flat
- >>> fl.coords
- (0, 0)
- >>> next(fl)
- 0
- >>> fl.coords
- (0, 1)
- """))
- add_newdoc('numpy.core', 'flatiter', ('index',
- """
- Current flat index into the array.
- Examples
- --------
- >>> x = np.arange(6).reshape(2, 3)
- >>> fl = x.flat
- >>> fl.index
- 0
- >>> next(fl)
- 0
- >>> fl.index
- 1
- """))
- # flatiter functions
- add_newdoc('numpy.core', 'flatiter', ('__array__',
- """__array__(type=None) Get array from iterator
- """))
- add_newdoc('numpy.core', 'flatiter', ('copy',
- """
- copy()
- Get a copy of the iterator as a 1-D array.
- Examples
- --------
- >>> x = np.arange(6).reshape(2, 3)
- >>> x
- array([[0, 1, 2],
- [3, 4, 5]])
- >>> fl = x.flat
- >>> fl.copy()
- array([0, 1, 2, 3, 4, 5])
- """))
- ###############################################################################
- #
- # nditer
- #
- ###############################################################################
- add_newdoc('numpy.core', 'nditer',
- """
- nditer(op, flags=None, op_flags=None, op_dtypes=None, order='K', casting='safe', op_axes=None, itershape=None, buffersize=0)
- Efficient multi-dimensional iterator object to iterate over arrays.
- To get started using this object, see the
- :ref:`introductory guide to array iteration <arrays.nditer>`.
- Parameters
- ----------
- op : ndarray or sequence of array_like
- The array(s) to iterate over.
- flags : sequence of str, optional
- Flags to control the behavior of the iterator.
- * ``buffered`` enables buffering when required.
- * ``c_index`` causes a C-order index to be tracked.
- * ``f_index`` causes a Fortran-order index to be tracked.
- * ``multi_index`` causes a multi-index, or a tuple of indices
- with one per iteration dimension, to be tracked.
- * ``common_dtype`` causes all the operands to be converted to
- a common data type, with copying or buffering as necessary.
- * ``copy_if_overlap`` causes the iterator to determine if read
- operands have overlap with write operands, and make temporary
- copies as necessary to avoid overlap. False positives (needless
- copying) are possible in some cases.
- * ``delay_bufalloc`` delays allocation of the buffers until
- a reset() call is made. Allows ``allocate`` operands to
- be initialized before their values are copied into the buffers.
- * ``external_loop`` causes the ``values`` given to be
- one-dimensional arrays with multiple values instead of
- zero-dimensional arrays.
- * ``grow_inner`` allows the ``value`` array sizes to be made
- larger than the buffer size when both ``buffered`` and
- ``external_loop`` is used.
- * ``ranged`` allows the iterator to be restricted to a sub-range
- of the iterindex values.
- * ``refs_ok`` enables iteration of reference types, such as
- object arrays.
- * ``reduce_ok`` enables iteration of ``readwrite`` operands
- which are broadcasted, also known as reduction operands.
- * ``zerosize_ok`` allows `itersize` to be zero.
- op_flags : list of list of str, optional
- This is a list of flags for each operand. At minimum, one of
- ``readonly``, ``readwrite``, or ``writeonly`` must be specified.
- * ``readonly`` indicates the operand will only be read from.
- * ``readwrite`` indicates the operand will be read from and written to.
- * ``writeonly`` indicates the operand will only be written to.
- * ``no_broadcast`` prevents the operand from being broadcasted.
- * ``contig`` forces the operand data to be contiguous.
- * ``aligned`` forces the operand data to be aligned.
- * ``nbo`` forces the operand data to be in native byte order.
- * ``copy`` allows a temporary read-only copy if required.
- * ``updateifcopy`` allows a temporary read-write copy if required.
- * ``allocate`` causes the array to be allocated if it is None
- in the ``op`` parameter.
- * ``no_subtype`` prevents an ``allocate`` operand from using a subtype.
- * ``arraymask`` indicates that this operand is the mask to use
- for selecting elements when writing to operands with the
- 'writemasked' flag set. The iterator does not enforce this,
- but when writing from a buffer back to the array, it only
- copies those elements indicated by this mask.
- * ``writemasked`` indicates that only elements where the chosen
- ``arraymask`` operand is True will be written to.
- * ``overlap_assume_elementwise`` can be used to mark operands that are
- accessed only in the iterator order, to allow less conservative
- copying when ``copy_if_overlap`` is present.
- op_dtypes : dtype or tuple of dtype(s), optional
- The required data type(s) of the operands. If copying or buffering
- is enabled, the data will be converted to/from their original types.
- order : {'C', 'F', 'A', 'K'}, optional
- Controls the iteration order. 'C' means C order, 'F' means
- Fortran order, 'A' means 'F' order if all the arrays are Fortran
- contiguous, 'C' order otherwise, and 'K' means as close to the
- order the array elements appear in memory as possible. This also
- affects the element memory order of ``allocate`` operands, as they
- are allocated to be compatible with iteration order.
- Default is 'K'.
- casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
- Controls what kind of data casting may occur when making a copy
- or buffering. Setting this to 'unsafe' is not recommended,
- as it can adversely affect accumulations.
- * 'no' means the data types should not be cast at all.
- * 'equiv' means only byte-order changes are allowed.
- * 'safe' means only casts which can preserve values are allowed.
- * 'same_kind' means only safe casts or casts within a kind,
- like float64 to float32, are allowed.
- * 'unsafe' means any data conversions may be done.
- op_axes : list of list of ints, optional
- If provided, is a list of ints or None for each operands.
- The list of axes for an operand is a mapping from the dimensions
- of the iterator to the dimensions of the operand. A value of
- -1 can be placed for entries, causing that dimension to be
- treated as `newaxis`.
- itershape : tuple of ints, optional
- The desired shape of the iterator. This allows ``allocate`` operands
- with a dimension mapped by op_axes not corresponding to a dimension
- of a different operand to get a value not equal to 1 for that
- dimension.
- buffersize : int, optional
- When buffering is enabled, controls the size of the temporary
- buffers. Set to 0 for the default value.
- Attributes
- ----------
- dtypes : tuple of dtype(s)
- The data types of the values provided in `value`. This may be
- different from the operand data types if buffering is enabled.
- Valid only before the iterator is closed.
- finished : bool
- Whether the iteration over the operands is finished or not.
- has_delayed_bufalloc : bool
- If True, the iterator was created with the ``delay_bufalloc`` flag,
- and no reset() function was called on it yet.
- has_index : bool
- If True, the iterator was created with either the ``c_index`` or
- the ``f_index`` flag, and the property `index` can be used to
- retrieve it.
- has_multi_index : bool
- If True, the iterator was created with the ``multi_index`` flag,
- and the property `multi_index` can be used to retrieve it.
- index
- When the ``c_index`` or ``f_index`` flag was used, this property
- provides access to the index. Raises a ValueError if accessed
- and ``has_index`` is False.
- iterationneedsapi : bool
- Whether iteration requires access to the Python API, for example
- if one of the operands is an object array.
- iterindex : int
- An index which matches the order of iteration.
- itersize : int
- Size of the iterator.
- itviews
- Structured view(s) of `operands` in memory, matching the reordered
- and optimized iterator access pattern. Valid only before the iterator
- is closed.
- multi_index
- When the ``multi_index`` flag was used, this property
- provides access to the index. Raises a ValueError if accessed
- accessed and ``has_multi_index`` is False.
- ndim : int
- The dimensions of the iterator.
- nop : int
- The number of iterator operands.
- operands : tuple of operand(s)
- The array(s) to be iterated over. Valid only before the iterator is
- closed.
- shape : tuple of ints
- Shape tuple, the shape of the iterator.
- value
- Value of ``operands`` at current iteration. Normally, this is a
- tuple of array scalars, but if the flag ``external_loop`` is used,
- it is a tuple of one dimensional arrays.
- Notes
- -----
- `nditer` supersedes `flatiter`. The iterator implementation behind
- `nditer` is also exposed by the NumPy C API.
- The Python exposure supplies two iteration interfaces, one which follows
- the Python iterator protocol, and another which mirrors the C-style
- do-while pattern. The native Python approach is better in most cases, but
- if you need the coordinates or index of an iterator, use the C-style pattern.
- Examples
- --------
- Here is how we might write an ``iter_add`` function, using the
- Python iterator protocol:
- >>> 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]
- Here is the same function, but following the C-style pattern:
- >>> 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]
- Here is an example outer product function:
- >>> 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]])
- Here is an example function which operates like a "lambda" 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])
- If operand flags `"writeonly"` or `"readwrite"` are used the
- operands may be views into the original data with the
- `WRITEBACKIFCOPY` flag. In this case `nditer` must be used as a
- context manager or the `nditer.close` method must be called before
- using the result. The temporary data will be written back to the
- original data when the `__exit__` function is called but not before:
- >>> a = np.arange(6, dtype='i4')[::-2]
- >>> with np.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], dtype=int32), array([-1., -2., -3.], dtype=float32))
- It is important to note that once the iterator is exited, dangling
- references (like `x` in the example) may or may not share data with
- the original data `a`. If writeback semantics were active, i.e. if
- `x.base.flags.writebackifcopy` is `True`, then exiting the iterator
- will sever the connection between `x` and `a`, writing to `x` will
- no longer write to `a`. If writeback semantics are not active, then
- `x.data` will still point at some part of `a.data`, and writing to
- one will affect the other.
- Context management and the `close` method appeared in version 1.15.0.
- """)
- # nditer methods
- add_newdoc('numpy.core', 'nditer', ('copy',
- """
- copy()
- Get a copy of the iterator in its current state.
- Examples
- --------
- >>> x = np.arange(10)
- >>> y = x + 1
- >>> it = np.nditer([x, y])
- >>> next(it)
- (array(0), array(1))
- >>> it2 = it.copy()
- >>> next(it2)
- (array(1), array(2))
- """))
- add_newdoc('numpy.core', 'nditer', ('operands',
- """
- operands[`Slice`]
- The array(s) to be iterated over. Valid only before the iterator is closed.
- """))
- add_newdoc('numpy.core', 'nditer', ('debug_print',
- """
- debug_print()
- Print the current state of the `nditer` instance and debug info to stdout.
- """))
- add_newdoc('numpy.core', 'nditer', ('enable_external_loop',
- """
- enable_external_loop()
- When the "external_loop" was not used during construction, but
- is desired, this modifies the iterator to behave as if the flag
- was specified.
- """))
- add_newdoc('numpy.core', 'nditer', ('iternext',
- """
- iternext()
- Check whether iterations are left, and perform a single internal iteration
- without returning the result. Used in the C-style pattern do-while
- pattern. For an example, see `nditer`.
- Returns
- -------
- iternext : bool
- Whether or not there are iterations left.
- """))
- add_newdoc('numpy.core', 'nditer', ('remove_axis',
- """
- remove_axis(i)
- Removes axis `i` from the iterator. Requires that the flag "multi_index"
- be enabled.
- """))
- add_newdoc('numpy.core', 'nditer', ('remove_multi_index',
- """
- remove_multi_index()
- When the "multi_index" flag was specified, this removes it, allowing
- the internal iteration structure to be optimized further.
- """))
- add_newdoc('numpy.core', 'nditer', ('reset',
- """
- reset()
- Reset the iterator to its initial state.
- """))
- add_newdoc('numpy.core', 'nested_iters',
- """
- Create nditers for use in nested loops
- Create a tuple of `nditer` objects which iterate in nested loops over
- different axes of the op argument. The first iterator is used in the
- outermost loop, the last in the innermost loop. Advancing one will change
- the subsequent iterators to point at its new element.
- Parameters
- ----------
- op : ndarray or sequence of array_like
- The array(s) to iterate over.
- axes : list of list of int
- Each item is used as an "op_axes" argument to an nditer
- flags, op_flags, op_dtypes, order, casting, buffersize (optional)
- See `nditer` parameters of the same name
- Returns
- -------
- iters : tuple of nditer
- An nditer for each item in `axes`, outermost first
- See Also
- --------
- nditer
- Examples
- --------
- Basic usage. Note how y is the "flattened" version of
- [a[:, 0, :], a[:, 1, 0], a[:, 2, :]] since we specified
- the first iter's axes as [1]
- >>> a = np.arange(12).reshape(2, 3, 2)
- >>> i, j = np.nested_iters(a, [[1], [0, 2]], flags=["multi_index"])
- >>> for x in i:
- ... print(i.multi_index)
- ... for y in j:
- ... print('', j.multi_index, y)
- (0,)
- (0, 0) 0
- (0, 1) 1
- (1, 0) 6
- (1, 1) 7
- (1,)
- (0, 0) 2
- (0, 1) 3
- (1, 0) 8
- (1, 1) 9
- (2,)
- (0, 0) 4
- (0, 1) 5
- (1, 0) 10
- (1, 1) 11
- """)
- add_newdoc('numpy.core', 'nditer', ('close',
- """
- close()
- Resolve all writeback semantics in writeable operands.
- .. versionadded:: 1.15.0
- See Also
- --------
- :ref:`nditer-context-manager`
- """))
- ###############################################################################
- #
- # broadcast
- #
- ###############################################################################
- add_newdoc('numpy.core', 'broadcast',
- """
- Produce an object that mimics broadcasting.
- Parameters
- ----------
- in1, in2, ... : array_like
- Input parameters.
- Returns
- -------
- b : broadcast object
- Broadcast the input parameters against one another, and
- return an object that encapsulates the result.
- Amongst others, it has ``shape`` and ``nd`` properties, and
- may be used as an iterator.
- See Also
- --------
- broadcast_arrays
- broadcast_to
- Examples
- --------
- Manually adding two vectors, using broadcasting:
- >>> x = np.array([[1], [2], [3]])
- >>> y = np.array([4, 5, 6])
- >>> b = np.broadcast(x, y)
- >>> out = np.empty(b.shape)
- >>> out.flat = [u+v for (u,v) in b]
- >>> out
- array([[5., 6., 7.],
- [6., 7., 8.],
- [7., 8., 9.]])
- Compare against built-in broadcasting:
- >>> x + y
- array([[5, 6, 7],
- [6, 7, 8],
- [7, 8, 9]])
- """)
- # attributes
- add_newdoc('numpy.core', 'broadcast', ('index',
- """
- current index in broadcasted result
- Examples
- --------
- >>> x = np.array([[1], [2], [3]])
- >>> y = np.array([4, 5, 6])
- >>> b = np.broadcast(x, y)
- >>> b.index
- 0
- >>> next(b), next(b), next(b)
- ((1, 4), (1, 5), (1, 6))
- >>> b.index
- 3
- """))
- add_newdoc('numpy.core', 'broadcast', ('iters',
- """
- tuple of iterators along ``self``'s "components."
- Returns a tuple of `numpy.flatiter` objects, one for each "component"
- of ``self``.
- See Also
- --------
- numpy.flatiter
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> y = np.array([[4], [5], [6]])
- >>> b = np.broadcast(x, y)
- >>> row, col = b.iters
- >>> next(row), next(col)
- (1, 4)
- """))
- add_newdoc('numpy.core', 'broadcast', ('ndim',
- """
- Number of dimensions of broadcasted result. Alias for `nd`.
- .. versionadded:: 1.12.0
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> y = np.array([[4], [5], [6]])
- >>> b = np.broadcast(x, y)
- >>> b.ndim
- 2
- """))
- add_newdoc('numpy.core', 'broadcast', ('nd',
- """
- Number of dimensions of broadcasted result. For code intended for NumPy
- 1.12.0 and later the more consistent `ndim` is preferred.
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> y = np.array([[4], [5], [6]])
- >>> b = np.broadcast(x, y)
- >>> b.nd
- 2
- """))
- add_newdoc('numpy.core', 'broadcast', ('numiter',
- """
- Number of iterators possessed by the broadcasted result.
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> y = np.array([[4], [5], [6]])
- >>> b = np.broadcast(x, y)
- >>> b.numiter
- 2
- """))
- add_newdoc('numpy.core', 'broadcast', ('shape',
- """
- Shape of broadcasted result.
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> y = np.array([[4], [5], [6]])
- >>> b = np.broadcast(x, y)
- >>> b.shape
- (3, 3)
- """))
- add_newdoc('numpy.core', 'broadcast', ('size',
- """
- Total size of broadcasted result.
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> y = np.array([[4], [5], [6]])
- >>> b = np.broadcast(x, y)
- >>> b.size
- 9
- """))
- add_newdoc('numpy.core', 'broadcast', ('reset',
- """
- reset()
- Reset the broadcasted result's iterator(s).
- Parameters
- ----------
- None
- Returns
- -------
- None
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> y = np.array([[4], [5], [6]])
- >>> b = np.broadcast(x, y)
- >>> b.index
- 0
- >>> next(b), next(b), next(b)
- ((1, 4), (2, 4), (3, 4))
- >>> b.index
- 3
- >>> b.reset()
- >>> b.index
- 0
- """))
- ###############################################################################
- #
- # numpy functions
- #
- ###############################################################################
- add_newdoc('numpy.core.multiarray', 'array',
- """
- array(object, dtype=None, *, copy=True, order='K', subok=False, ndmin=0)
- Create an array.
- Parameters
- ----------
- object : array_like
- An array, any object exposing the array interface, an object whose
- __array__ method returns an array, or any (nested) sequence.
- dtype : data-type, optional
- The desired data-type for the array. If not given, then the type will
- be determined as the minimum type required to hold the objects in the
- sequence.
- copy : bool, optional
- If true (default), then the object is copied. Otherwise, a copy will
- only be made if __array__ returns a copy, if obj is a nested sequence,
- or if a copy is needed to satisfy any of the other requirements
- (`dtype`, `order`, etc.).
- order : {'K', 'A', 'C', 'F'}, optional
- Specify the memory layout of the array. If object is not an array, the
- newly created array will be in C order (row major) unless 'F' is
- specified, in which case it will be in Fortran order (column major).
- If object is an array the following holds.
- ===== ========= ===================================================
- order no copy copy=True
- ===== ========= ===================================================
- 'K' unchanged F & C order preserved, otherwise most similar order
- 'A' unchanged F order if input is F and not C, otherwise C order
- 'C' C order C order
- 'F' F order F order
- ===== ========= ===================================================
- When ``copy=False`` and a copy is made for other reasons, the result is
- the same as if ``copy=True``, with some exceptions for `A`, see the
- Notes section. The default order is 'K'.
- subok : bool, optional
- If True, then sub-classes will be passed-through, otherwise
- the returned array will be forced to be a base-class array (default).
- ndmin : int, optional
- Specifies the minimum number of dimensions that the resulting
- array should have. Ones will be pre-pended to the shape as
- needed to meet this requirement.
- Returns
- -------
- out : ndarray
- An array object satisfying the specified requirements.
- See Also
- --------
- empty_like : Return an empty array with shape and type of input.
- ones_like : Return an array of ones with shape and type of input.
- zeros_like : Return an array of zeros with shape and type of input.
- full_like : Return a new array with shape of input filled with value.
- empty : Return a new uninitialized array.
- ones : Return a new array setting values to one.
- zeros : Return a new array setting values to zero.
- full : Return a new array of given shape filled with value.
- Notes
- -----
- When order is 'A' and `object` is an array in neither 'C' nor 'F' order,
- and a copy is forced by a change in dtype, then the order of the result is
- not necessarily 'C' as expected. This is likely a bug.
- Examples
- --------
- >>> np.array([1, 2, 3])
- array([1, 2, 3])
- Upcasting:
- >>> np.array([1, 2, 3.0])
- array([ 1., 2., 3.])
- More than one dimension:
- >>> np.array([[1, 2], [3, 4]])
- array([[1, 2],
- [3, 4]])
- Minimum dimensions 2:
- >>> np.array([1, 2, 3], ndmin=2)
- array([[1, 2, 3]])
- Type provided:
- >>> np.array([1, 2, 3], dtype=complex)
- array([ 1.+0.j, 2.+0.j, 3.+0.j])
- Data-type consisting of more than one element:
- >>> x = np.array([(1,2),(3,4)],dtype=[('a','<i4'),('b','<i4')])
- >>> x['a']
- array([1, 3])
- Creating an array from sub-classes:
- >>> np.array(np.mat('1 2; 3 4'))
- array([[1, 2],
- [3, 4]])
- >>> np.array(np.mat('1 2; 3 4'), subok=True)
- matrix([[1, 2],
- [3, 4]])
- """)
- add_newdoc('numpy.core.multiarray', 'empty',
- """
- empty(shape, dtype=float, order='C')
- Return a new array of given shape and type, without initializing entries.
- Parameters
- ----------
- shape : int or tuple of int
- Shape of the empty array, e.g., ``(2, 3)`` or ``2``.
- dtype : data-type, optional
- Desired output data-type for the array, e.g, `numpy.int8`. Default is
- `numpy.float64`.
- order : {'C', 'F'}, optional, default: 'C'
- Whether to store multi-dimensional data in row-major
- (C-style) or column-major (Fortran-style) order in
- memory.
- Returns
- -------
- out : ndarray
- Array of uninitialized (arbitrary) data of the given shape, dtype, and
- order. Object arrays will be initialized to None.
- See Also
- --------
- empty_like : Return an empty array with shape and type of input.
- ones : Return a new array setting values to one.
- zeros : Return a new array setting values to zero.
- full : Return a new array of given shape filled with value.
- Notes
- -----
- `empty`, unlike `zeros`, does not set the array values to zero,
- and may therefore be marginally faster. On the other hand, it requires
- the user to manually set all the values in the array, and should be
- used with caution.
- Examples
- --------
- >>> np.empty([2, 2])
- array([[ -9.74499359e+001, 6.69583040e-309],
- [ 2.13182611e-314, 3.06959433e-309]]) #uninitialized
- >>> np.empty([2, 2], dtype=int)
- array([[-1073741821, -1067949133],
- [ 496041986, 19249760]]) #uninitialized
- """)
- add_newdoc('numpy.core.multiarray', 'scalar',
- """
- scalar(dtype, obj)
- Return a new scalar array of the given type initialized with obj.
- This function is meant mainly for pickle support. `dtype` must be a
- valid data-type descriptor. If `dtype` corresponds to an object
- descriptor, then `obj` can be any object, otherwise `obj` must be a
- string. If `obj` is not given, it will be interpreted as None for object
- type and as zeros for all other types.
- """)
- add_newdoc('numpy.core.multiarray', 'zeros',
- """
- zeros(shape, dtype=float, order='C')
- Return a new array of given shape and type, filled with zeros.
- Parameters
- ----------
- shape : int or tuple of ints
- Shape of the new array, e.g., ``(2, 3)`` or ``2``.
- dtype : data-type, optional
- The desired data-type for the array, e.g., `numpy.int8`. Default is
- `numpy.float64`.
- order : {'C', 'F'}, optional, default: 'C'
- Whether to store multi-dimensional data in row-major
- (C-style) or column-major (Fortran-style) order in
- memory.
- Returns
- -------
- out : ndarray
- Array of zeros with the given shape, dtype, and order.
- See Also
- --------
- zeros_like : Return an array of zeros with shape and type of input.
- empty : Return a new uninitialized array.
- ones : Return a new array setting values to one.
- full : Return a new array of given shape filled with value.
- Examples
- --------
- >>> np.zeros(5)
- array([ 0., 0., 0., 0., 0.])
- >>> np.zeros((5,), dtype=int)
- array([0, 0, 0, 0, 0])
- >>> np.zeros((2, 1))
- array([[ 0.],
- [ 0.]])
- >>> s = (2,2)
- >>> np.zeros(s)
- array([[ 0., 0.],
- [ 0., 0.]])
- >>> np.zeros((2,), dtype=[('x', 'i4'), ('y', 'i4')]) # custom dtype
- array([(0, 0), (0, 0)],
- dtype=[('x', '<i4'), ('y', '<i4')])
- """)
- add_newdoc('numpy.core.multiarray', 'set_typeDict',
- """set_typeDict(dict)
- Set the internal dictionary that can look up an array type using a
- registered code.
- """)
- add_newdoc('numpy.core.multiarray', 'fromstring',
- """
- fromstring(string, dtype=float, count=-1, sep='')
- A new 1-D array initialized from text data in a string.
- Parameters
- ----------
- string : str
- A string containing the data.
- dtype : data-type, optional
- The data type of the array; default: float. For binary input data,
- the data must be in exactly this format. Most builtin numeric types are
- supported and extension types may be supported.
- .. versionadded:: 1.18.0
- Complex dtypes.
- count : int, optional
- Read this number of `dtype` elements from the data. If this is
- negative (the default), the count will be determined from the
- length of the data.
- sep : str, optional
- The string separating numbers in the data; extra whitespace between
- elements is also ignored.
- .. deprecated:: 1.14
- Passing ``sep=''``, the default, is deprecated since it will
- trigger the deprecated binary mode of this function. This mode
- interprets `string` as binary bytes, rather than ASCII text with
- decimal numbers, an operation which is better spelt
- ``frombuffer(string, dtype, count)``. If `string` contains unicode
- text, the binary mode of `fromstring` will first encode it into
- bytes using either utf-8 (python 3) or the default encoding
- (python 2), neither of which produce sane results.
- Returns
- -------
- arr : ndarray
- The constructed array.
- Raises
- ------
- ValueError
- If the string is not the correct size to satisfy the requested
- `dtype` and `count`.
- See Also
- --------
- frombuffer, fromfile, fromiter
- Examples
- --------
- >>> np.fromstring('1 2', dtype=int, sep=' ')
- array([1, 2])
- >>> np.fromstring('1, 2', dtype=int, sep=',')
- array([1, 2])
- """)
- add_newdoc('numpy.core.multiarray', 'compare_chararrays',
- """
- compare_chararrays(a, b, cmp_op, rstrip)
- Performs element-wise comparison of two string arrays using the
- comparison operator specified by `cmp_op`.
- Parameters
- ----------
- a, b : array_like
- Arrays to be compared.
- cmp_op : {"<", "<=", "==", ">=", ">", "!="}
- Type of comparison.
- rstrip : Boolean
- If True, the spaces at the end of Strings are removed before the comparison.
- Returns
- -------
- out : ndarray
- The output array of type Boolean with the same shape as a and b.
- Raises
- ------
- ValueError
- If `cmp_op` is not valid.
- TypeError
- If at least one of `a` or `b` is a non-string array
- Examples
- --------
- >>> a = np.array(["a", "b", "cde"])
- >>> b = np.array(["a", "a", "dec"])
- >>> np.compare_chararrays(a, b, ">", True)
- array([False, True, False])
- """)
- add_newdoc('numpy.core.multiarray', 'fromiter',
- """
- fromiter(iterable, dtype, count=-1)
- Create a new 1-dimensional array from an iterable object.
- Parameters
- ----------
- iterable : iterable object
- An iterable object providing data for the array.
- dtype : data-type
- The data-type of the returned array.
- count : int, optional
- The number of items to read from *iterable*. The default is -1,
- which means all data is read.
- Returns
- -------
- out : ndarray
- The output array.
- Notes
- -----
- Specify `count` to improve performance. It allows ``fromiter`` to
- pre-allocate the output array, instead of resizing it on demand.
- Examples
- --------
- >>> iterable = (x*x for x in range(5))
- >>> np.fromiter(iterable, float)
- array([ 0., 1., 4., 9., 16.])
- """)
- add_newdoc('numpy.core.multiarray', 'fromfile',
- """
- fromfile(file, dtype=float, count=-1, sep='', offset=0)
- Construct an array from data in a text or binary file.
- A highly efficient way of reading binary data with a known data-type,
- as well as parsing simply formatted text files. Data written using the
- `tofile` method can be read using this function.
- Parameters
- ----------
- file : file or str or Path
- Open file object or filename.
- .. versionchanged:: 1.17.0
- `pathlib.Path` objects are now accepted.
- dtype : data-type
- Data type of the returned array.
- For binary files, it is used to determine the size and byte-order
- of the items in the file.
- Most builtin numeric types are supported and extension types may be supported.
- .. versionadded:: 1.18.0
- Complex dtypes.
- count : int
- Number of items to read. ``-1`` means all items (i.e., the complete
- file).
- sep : str
- Separator between items if file is a text file.
- Empty ("") separator means the file should be treated as binary.
- Spaces (" ") in the separator match zero or more whitespace characters.
- A separator consisting only of spaces must match at least one
- whitespace.
- offset : int
- The offset (in bytes) from the file's current position. Defaults to 0.
- Only permitted for binary files.
- .. versionadded:: 1.17.0
- See also
- --------
- load, save
- ndarray.tofile
- loadtxt : More flexible way of loading data from a text file.
- Notes
- -----
- Do not rely on the combination of `tofile` and `fromfile` for
- data storage, as the binary files generated are not platform
- independent. In particular, no byte-order or data-type information is
- saved. Data can be stored in the platform independent ``.npy`` format
- using `save` and `load` instead.
- Examples
- --------
- Construct an ndarray:
- >>> dt = np.dtype([('time', [('min', np.int64), ('sec', np.int64)]),
- ... ('temp', float)])
- >>> x = np.zeros((1,), dtype=dt)
- >>> x['time']['min'] = 10; x['temp'] = 98.25
- >>> x
- array([((10, 0), 98.25)],
- dtype=[('time', [('min', '<i8'), ('sec', '<i8')]), ('temp', '<f8')])
- Save the raw data to disk:
- >>> import tempfile
- >>> fname = tempfile.mkstemp()[1]
- >>> x.tofile(fname)
- Read the raw data from disk:
- >>> np.fromfile(fname, dtype=dt)
- array([((10, 0), 98.25)],
- dtype=[('time', [('min', '<i8'), ('sec', '<i8')]), ('temp', '<f8')])
- The recommended way to store and load data:
- >>> np.save(fname, x)
- >>> np.load(fname + '.npy')
- array([((10, 0), 98.25)],
- dtype=[('time', [('min', '<i8'), ('sec', '<i8')]), ('temp', '<f8')])
- """)
- add_newdoc('numpy.core.multiarray', 'frombuffer',
- """
- frombuffer(buffer, dtype=float, count=-1, offset=0)
- Interpret a buffer as a 1-dimensional array.
- Parameters
- ----------
- buffer : buffer_like
- An object that exposes the buffer interface.
- dtype : data-type, optional
- Data-type of the returned array; default: float.
- count : int, optional
- Number of items to read. ``-1`` means all data in the buffer.
- offset : int, optional
- Start reading the buffer from this offset (in bytes); default: 0.
- Notes
- -----
- If the buffer has data that is not in machine byte-order, this should
- be specified as part of the data-type, e.g.::
- >>> dt = np.dtype(int)
- >>> dt = dt.newbyteorder('>')
- >>> np.frombuffer(buf, dtype=dt) # doctest: +SKIP
- The data of the resulting array will not be byteswapped, but will be
- interpreted correctly.
- Examples
- --------
- >>> s = b'hello world'
- >>> np.frombuffer(s, dtype='S1', count=5, offset=6)
- array([b'w', b'o', b'r', b'l', b'd'], dtype='|S1')
- >>> np.frombuffer(b'\\x01\\x02', dtype=np.uint8)
- array([1, 2], dtype=uint8)
- >>> np.frombuffer(b'\\x01\\x02\\x03\\x04\\x05', dtype=np.uint8, count=3)
- array([1, 2, 3], dtype=uint8)
- """)
- add_newdoc('numpy.core', 'fastCopyAndTranspose',
- """_fastCopyAndTranspose(a)""")
- add_newdoc('numpy.core.multiarray', 'correlate',
- """cross_correlate(a,v, mode=0)""")
- add_newdoc('numpy.core.multiarray', 'arange',
- """
- arange([start,] stop[, step,], dtype=None)
- Return evenly spaced values within a given interval.
- Values are generated within the half-open interval ``[start, stop)``
- (in other words, the interval including `start` but excluding `stop`).
- For integer arguments the function is equivalent to the Python built-in
- `range` function, but returns an ndarray rather than a list.
- When using a non-integer step, such as 0.1, the results will often not
- be consistent. It is better to use `numpy.linspace` for these cases.
- Parameters
- ----------
- start : number, optional
- Start of interval. The interval includes this value. The default
- start value is 0.
- stop : number
- End of interval. The interval does not include this value, except
- in some cases where `step` is not an integer and floating point
- round-off affects the length of `out`.
- step : number, optional
- Spacing between values. For any output `out`, this is the distance
- between two adjacent values, ``out[i+1] - out[i]``. The default
- step size is 1. If `step` is specified as a position argument,
- `start` must also be given.
- dtype : dtype
- The type of the output array. If `dtype` is not given, infer the data
- type from the other input arguments.
- Returns
- -------
- arange : ndarray
- Array of evenly spaced values.
- For floating point arguments, the length of the result is
- ``ceil((stop - start)/step)``. Because of floating point overflow,
- this rule may result in the last element of `out` being greater
- than `stop`.
- See Also
- --------
- numpy.linspace : Evenly spaced numbers with careful handling of endpoints.
- numpy.ogrid: Arrays of evenly spaced numbers in N-dimensions.
- numpy.mgrid: Grid-shaped arrays of evenly spaced numbers in N-dimensions.
- Examples
- --------
- >>> np.arange(3)
- array([0, 1, 2])
- >>> np.arange(3.0)
- array([ 0., 1., 2.])
- >>> np.arange(3,7)
- array([3, 4, 5, 6])
- >>> np.arange(3,7,2)
- array([3, 5])
- """)
- add_newdoc('numpy.core.multiarray', '_get_ndarray_c_version',
- """_get_ndarray_c_version()
- Return the compile time NPY_VERSION (formerly called NDARRAY_VERSION) number.
- """)
- add_newdoc('numpy.core.multiarray', '_reconstruct',
- """_reconstruct(subtype, shape, dtype)
- Construct an empty array. Used by Pickles.
- """)
- add_newdoc('numpy.core.multiarray', 'set_string_function',
- """
- set_string_function(f, repr=1)
- Internal method to set a function to be used when pretty printing arrays.
- """)
- add_newdoc('numpy.core.multiarray', 'set_numeric_ops',
- """
- set_numeric_ops(op1=func1, op2=func2, ...)
- Set numerical operators for array objects.
- .. deprecated:: 1.16
- For the general case, use :c:func:`PyUFunc_ReplaceLoopBySignature`.
- For ndarray subclasses, define the ``__array_ufunc__`` method and
- override the relevant ufunc.
- Parameters
- ----------
- op1, op2, ... : callable
- Each ``op = func`` pair describes an operator to be replaced.
- For example, ``add = lambda x, y: np.add(x, y) % 5`` would replace
- addition by modulus 5 addition.
- Returns
- -------
- saved_ops : list of callables
- A list of all operators, stored before making replacements.
- Notes
- -----
- .. WARNING::
- Use with care! Incorrect usage may lead to memory errors.
- A function replacing an operator cannot make use of that operator.
- For example, when replacing add, you may not use ``+``. Instead,
- directly call ufuncs.
- Examples
- --------
- >>> def add_mod5(x, y):
- ... return np.add(x, y) % 5
- ...
- >>> old_funcs = np.set_numeric_ops(add=add_mod5)
- >>> x = np.arange(12).reshape((3, 4))
- >>> x + x
- array([[0, 2, 4, 1],
- [3, 0, 2, 4],
- [1, 3, 0, 2]])
- >>> ignore = np.set_numeric_ops(**old_funcs) # restore operators
- """)
- add_newdoc('numpy.core.multiarray', 'promote_types',
- """
- promote_types(type1, type2)
- Returns the data type with the smallest size and smallest scalar
- kind to which both ``type1`` and ``type2`` may be safely cast.
- The returned data type is always in native byte order.
- This function is symmetric, but rarely associative.
- Parameters
- ----------
- type1 : dtype or dtype specifier
- First data type.
- type2 : dtype or dtype specifier
- Second data type.
- Returns
- -------
- out : dtype
- The promoted data type.
- Notes
- -----
- .. versionadded:: 1.6.0
- Starting in NumPy 1.9, promote_types function now returns a valid string
- length when given an integer or float dtype as one argument and a string
- dtype as another argument. Previously it always returned the input string
- dtype, even if it wasn't long enough to store the max integer/float value
- converted to a string.
- See Also
- --------
- result_type, dtype, can_cast
- Examples
- --------
- >>> np.promote_types('f4', 'f8')
- dtype('float64')
- >>> np.promote_types('i8', 'f4')
- dtype('float64')
- >>> np.promote_types('>i8', '<c8')
- dtype('complex128')
- >>> np.promote_types('i4', 'S8')
- dtype('S11')
- An example of a non-associative case:
- >>> p = np.promote_types
- >>> p('S', p('i1', 'u1'))
- dtype('S6')
- >>> p(p('S', 'i1'), 'u1')
- dtype('S4')
- """)
- add_newdoc('numpy.core.multiarray', 'c_einsum',
- """
- c_einsum(subscripts, *operands, out=None, dtype=None, order='K',
- casting='safe')
- *This documentation shadows that of the native python implementation of the `einsum` function,
- except all references and examples related to the `optimize` argument (v 0.12.0) have been removed.*
- Evaluates the Einstein summation convention on the operands.
- Using the Einstein summation convention, many common multi-dimensional,
- linear algebraic array operations can be represented in a simple fashion.
- In *implicit* mode `einsum` computes these values.
- In *explicit* mode, `einsum` provides further flexibility to compute
- other array operations that might not be considered classical Einstein
- summation operations, by disabling, or forcing summation over specified
- subscript labels.
- See the notes and examples for clarification.
- Parameters
- ----------
- subscripts : str
- Specifies the subscripts for summation as comma separated list of
- subscript labels. An implicit (classical Einstein summation)
- calculation is performed unless the explicit indicator '->' is
- included as well as subscript labels of the precise output form.
- operands : list of array_like
- These are the arrays for the operation.
- out : ndarray, optional
- If provided, the calculation is done into this array.
- dtype : {data-type, None}, optional
- If provided, forces the calculation to use the data type specified.
- Note that you may have to also give a more liberal `casting`
- parameter to allow the conversions. Default is None.
- order : {'C', 'F', 'A', 'K'}, optional
- Controls the memory layout of the output. 'C' means it should
- be C contiguous. 'F' means it should be Fortran contiguous,
- 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise.
- 'K' means it should be as close to the layout as the inputs as
- is possible, including arbitrarily permuted axes.
- Default is 'K'.
- casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
- Controls what kind of data casting may occur. Setting this to
- 'unsafe' is not recommended, as it can adversely affect accumulations.
- * 'no' means the data types should not be cast at all.
- * 'equiv' means only byte-order changes are allowed.
- * 'safe' means only casts which can preserve values are allowed.
- * 'same_kind' means only safe casts or casts within a kind,
- like float64 to float32, are allowed.
- * 'unsafe' means any data conversions may be done.
- Default is 'safe'.
- optimize : {False, True, 'greedy', 'optimal'}, optional
- Controls if intermediate optimization should occur. No optimization
- will occur if False and True will default to the 'greedy' algorithm.
- Also accepts an explicit contraction list from the ``np.einsum_path``
- function. See ``np.einsum_path`` for more details. Defaults to False.
- Returns
- -------
- output : ndarray
- The calculation based on the Einstein summation convention.
- See Also
- --------
- einsum_path, dot, inner, outer, tensordot, linalg.multi_dot
- Notes
- -----
- .. versionadded:: 1.6.0
- The Einstein summation convention can be used to compute
- many multi-dimensional, linear algebraic array operations. `einsum`
- provides a succinct way of representing these.
- A non-exhaustive list of these operations,
- which can be computed by `einsum`, is shown below along with examples:
- * Trace of an array, :py:func:`numpy.trace`.
- * Return a diagonal, :py:func:`numpy.diag`.
- * Array axis summations, :py:func:`numpy.sum`.
- * Transpositions and permutations, :py:func:`numpy.transpose`.
- * Matrix multiplication and dot product, :py:func:`numpy.matmul` :py:func:`numpy.dot`.
- * Vector inner and outer products, :py:func:`numpy.inner` :py:func:`numpy.outer`.
- * Broadcasting, element-wise and scalar multiplication, :py:func:`numpy.multiply`.
- * Tensor contractions, :py:func:`numpy.tensordot`.
- * Chained array operations, in efficient calculation order, :py:func:`numpy.einsum_path`.
- The subscripts string is a comma-separated list of subscript labels,
- where each label refers to a dimension of the corresponding operand.
- Whenever a label is repeated it is summed, so ``np.einsum('i,i', a, b)``
- is equivalent to :py:func:`np.inner(a,b) <numpy.inner>`. If a label
- appears only once, it is not summed, so ``np.einsum('i', a)`` produces a
- view of ``a`` with no changes. A further example ``np.einsum('ij,jk', a, b)``
- describes traditional matrix multiplication and is equivalent to
- :py:func:`np.matmul(a,b) <numpy.matmul>`. Repeated subscript labels in one
- operand take the diagonal. For example, ``np.einsum('ii', a)`` is equivalent
- to :py:func:`np.trace(a) <numpy.trace>`.
- In *implicit mode*, the chosen subscripts are important
- since the axes of the output are reordered alphabetically. This
- means that ``np.einsum('ij', a)`` doesn't affect a 2D array, while
- ``np.einsum('ji', a)`` takes its transpose. Additionally,
- ``np.einsum('ij,jk', a, b)`` returns a matrix multiplication, while,
- ``np.einsum('ij,jh', a, b)`` returns the transpose of the
- multiplication since subscript 'h' precedes subscript 'i'.
- In *explicit mode* the output can be directly controlled by
- specifying output subscript labels. This requires the
- identifier '->' as well as the list of output subscript labels.
- This feature increases the flexibility of the function since
- summing can be disabled or forced when required. The call
- ``np.einsum('i->', a)`` is like :py:func:`np.sum(a, axis=-1) <numpy.sum>`,
- and ``np.einsum('ii->i', a)`` is like :py:func:`np.diag(a) <numpy.diag>`.
- The difference is that `einsum` does not allow broadcasting by default.
- Additionally ``np.einsum('ij,jh->ih', a, b)`` directly specifies the
- order of the output subscript labels and therefore returns matrix
- multiplication, unlike the example above in implicit mode.
- To enable and control broadcasting, use an ellipsis. Default
- NumPy-style broadcasting is done by adding an ellipsis
- to the left of each term, like ``np.einsum('...ii->...i', a)``.
- To take the trace along the first and last axes,
- you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix
- product with the left-most indices instead of rightmost, one can do
- ``np.einsum('ij...,jk...->ik...', a, b)``.
- When there is only one operand, no axes are summed, and no output
- parameter is provided, a view into the operand is returned instead
- of a new array. Thus, taking the diagonal as ``np.einsum('ii->i', a)``
- produces a view (changed in version 1.10.0).
- `einsum` also provides an alternative way to provide the subscripts
- and operands as ``einsum(op0, sublist0, op1, sublist1, ..., [sublistout])``.
- If the output shape is not provided in this format `einsum` will be
- calculated in implicit mode, otherwise it will be performed explicitly.
- The examples below have corresponding `einsum` calls with the two
- parameter methods.
- .. versionadded:: 1.10.0
- Views returned from einsum are now writeable whenever the input array
- is writeable. For example, ``np.einsum('ijk...->kji...', a)`` will now
- have the same effect as :py:func:`np.swapaxes(a, 0, 2) <numpy.swapaxes>`
- and ``np.einsum('ii->i', a)`` will return a writeable view of the diagonal
- of a 2D array.
- Examples
- --------
- >>> a = np.arange(25).reshape(5,5)
- >>> b = np.arange(5)
- >>> c = np.arange(6).reshape(2,3)
- Trace of a matrix:
- >>> np.einsum('ii', a)
- 60
- >>> np.einsum(a, [0,0])
- 60
- >>> np.trace(a)
- 60
- Extract the diagonal (requires explicit form):
- >>> np.einsum('ii->i', a)
- array([ 0, 6, 12, 18, 24])
- >>> np.einsum(a, [0,0], [0])
- array([ 0, 6, 12, 18, 24])
- >>> np.diag(a)
- array([ 0, 6, 12, 18, 24])
- Sum over an axis (requires explicit form):
- >>> np.einsum('ij->i', a)
- array([ 10, 35, 60, 85, 110])
- >>> np.einsum(a, [0,1], [0])
- array([ 10, 35, 60, 85, 110])
- >>> np.sum(a, axis=1)
- array([ 10, 35, 60, 85, 110])
- For higher dimensional arrays summing a single axis can be done with ellipsis:
- >>> np.einsum('...j->...', a)
- array([ 10, 35, 60, 85, 110])
- >>> np.einsum(a, [Ellipsis,1], [Ellipsis])
- array([ 10, 35, 60, 85, 110])
- Compute a matrix transpose, or reorder any number of axes:
- >>> np.einsum('ji', c)
- array([[0, 3],
- [1, 4],
- [2, 5]])
- >>> np.einsum('ij->ji', c)
- array([[0, 3],
- [1, 4],
- [2, 5]])
- >>> np.einsum(c, [1,0])
- array([[0, 3],
- [1, 4],
- [2, 5]])
- >>> np.transpose(c)
- array([[0, 3],
- [1, 4],
- [2, 5]])
- Vector inner products:
- >>> np.einsum('i,i', b, b)
- 30
- >>> np.einsum(b, [0], b, [0])
- 30
- >>> np.inner(b,b)
- 30
- Matrix vector multiplication:
- >>> np.einsum('ij,j', a, b)
- array([ 30, 80, 130, 180, 230])
- >>> np.einsum(a, [0,1], b, [1])
- array([ 30, 80, 130, 180, 230])
- >>> np.dot(a, b)
- array([ 30, 80, 130, 180, 230])
- >>> np.einsum('...j,j', a, b)
- array([ 30, 80, 130, 180, 230])
- Broadcasting and scalar multiplication:
- >>> np.einsum('..., ...', 3, c)
- array([[ 0, 3, 6],
- [ 9, 12, 15]])
- >>> np.einsum(',ij', 3, c)
- array([[ 0, 3, 6],
- [ 9, 12, 15]])
- >>> np.einsum(3, [Ellipsis], c, [Ellipsis])
- array([[ 0, 3, 6],
- [ 9, 12, 15]])
- >>> np.multiply(3, c)
- array([[ 0, 3, 6],
- [ 9, 12, 15]])
- Vector outer product:
- >>> np.einsum('i,j', np.arange(2)+1, b)
- array([[0, 1, 2, 3, 4],
- [0, 2, 4, 6, 8]])
- >>> np.einsum(np.arange(2)+1, [0], b, [1])
- array([[0, 1, 2, 3, 4],
- [0, 2, 4, 6, 8]])
- >>> np.outer(np.arange(2)+1, b)
- array([[0, 1, 2, 3, 4],
- [0, 2, 4, 6, 8]])
- Tensor contraction:
- >>> a = np.arange(60.).reshape(3,4,5)
- >>> b = np.arange(24.).reshape(4,3,2)
- >>> np.einsum('ijk,jil->kl', a, b)
- array([[ 4400., 4730.],
- [ 4532., 4874.],
- [ 4664., 5018.],
- [ 4796., 5162.],
- [ 4928., 5306.]])
- >>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3])
- array([[ 4400., 4730.],
- [ 4532., 4874.],
- [ 4664., 5018.],
- [ 4796., 5162.],
- [ 4928., 5306.]])
- >>> np.tensordot(a,b, axes=([1,0],[0,1]))
- array([[ 4400., 4730.],
- [ 4532., 4874.],
- [ 4664., 5018.],
- [ 4796., 5162.],
- [ 4928., 5306.]])
- Writeable returned arrays (since version 1.10.0):
- >>> a = np.zeros((3, 3))
- >>> np.einsum('ii->i', a)[:] = 1
- >>> a
- array([[ 1., 0., 0.],
- [ 0., 1., 0.],
- [ 0., 0., 1.]])
- Example of ellipsis use:
- >>> a = np.arange(6).reshape((3,2))
- >>> b = np.arange(12).reshape((4,3))
- >>> np.einsum('ki,jk->ij', a, b)
- array([[10, 28, 46, 64],
- [13, 40, 67, 94]])
- >>> np.einsum('ki,...k->i...', a, b)
- array([[10, 28, 46, 64],
- [13, 40, 67, 94]])
- >>> np.einsum('k...,jk', a, b)
- array([[10, 28, 46, 64],
- [13, 40, 67, 94]])
- """)
- ##############################################################################
- #
- # Documentation for ndarray attributes and methods
- #
- ##############################################################################
- ##############################################################################
- #
- # ndarray object
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'ndarray',
- """
- ndarray(shape, dtype=float, buffer=None, offset=0,
- strides=None, order=None)
- An array object represents a multidimensional, homogeneous array
- of fixed-size items. An associated data-type object describes the
- format of each element in the array (its byte-order, how many bytes it
- occupies in memory, whether it is an integer, a floating point number,
- or something else, etc.)
- Arrays should be constructed using `array`, `zeros` or `empty` (refer
- to the See Also section below). The parameters given here refer to
- a low-level method (`ndarray(...)`) for instantiating an array.
- For more information, refer to the `numpy` module and examine the
- methods and attributes of an array.
- Parameters
- ----------
- (for the __new__ method; see Notes below)
- shape : tuple of ints
- Shape of created array.
- dtype : data-type, optional
- Any object that can be interpreted as a numpy data type.
- buffer : object exposing buffer interface, optional
- Used to fill the array with data.
- offset : int, optional
- Offset of array data in buffer.
- strides : tuple of ints, optional
- Strides of data in memory.
- order : {'C', 'F'}, optional
- Row-major (C-style) or column-major (Fortran-style) order.
- Attributes
- ----------
- T : ndarray
- Transpose of the array.
- data : buffer
- The array's elements, in memory.
- dtype : dtype object
- Describes the format of the elements in the array.
- flags : dict
- Dictionary containing information related to memory use, e.g.,
- 'C_CONTIGUOUS', 'OWNDATA', 'WRITEABLE', etc.
- flat : numpy.flatiter object
- Flattened version of the array as an iterator. The iterator
- allows assignments, e.g., ``x.flat = 3`` (See `ndarray.flat` for
- assignment examples; TODO).
- imag : ndarray
- Imaginary part of the array.
- real : ndarray
- Real part of the array.
- size : int
- Number of elements in the array.
- itemsize : int
- The memory use of each array element in bytes.
- nbytes : int
- The total number of bytes required to store the array data,
- i.e., ``itemsize * size``.
- ndim : int
- The array's number of dimensions.
- shape : tuple of ints
- Shape of the array.
- strides : tuple of ints
- The step-size required to move from one element to the next in
- memory. For example, a contiguous ``(3, 4)`` array of type
- ``int16`` in C-order has strides ``(8, 2)``. This implies that
- to move from element to element in memory requires jumps of 2 bytes.
- To move from row-to-row, one needs to jump 8 bytes at a time
- (``2 * 4``).
- ctypes : ctypes object
- Class containing properties of the array needed for interaction
- with ctypes.
- base : ndarray
- If the array is a view into another array, that array is its `base`
- (unless that array is also a view). The `base` array is where the
- array data is actually stored.
- See Also
- --------
- array : Construct an array.
- zeros : Create an array, each element of which is zero.
- empty : Create an array, but leave its allocated memory unchanged (i.e.,
- it contains "garbage").
- dtype : Create a data-type.
- Notes
- -----
- There are two modes of creating an array using ``__new__``:
- 1. If `buffer` is None, then only `shape`, `dtype`, and `order`
- are used.
- 2. If `buffer` is an object exposing the buffer interface, then
- all keywords are interpreted.
- No ``__init__`` method is needed because the array is fully initialized
- after the ``__new__`` method.
- Examples
- --------
- These examples illustrate the low-level `ndarray` constructor. Refer
- to the `See Also` section above for easier ways of constructing an
- ndarray.
- First mode, `buffer` is None:
- >>> np.ndarray(shape=(2,2), dtype=float, order='F')
- array([[0.0e+000, 0.0e+000], # random
- [ nan, 2.5e-323]])
- Second mode:
- >>> np.ndarray((2,), buffer=np.array([1,2,3]),
- ... offset=np.int_().itemsize,
- ... dtype=int) # offset = 1*itemsize, i.e. skip first element
- array([2, 3])
- """)
- ##############################################################################
- #
- # ndarray attributes
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_interface__',
- """Array protocol: Python side."""))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_finalize__',
- """None."""))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_priority__',
- """Array priority."""))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_struct__',
- """Array protocol: C-struct side."""))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('base',
- """
- Base object if memory is from some other object.
- Examples
- --------
- The base of an array that owns its memory is None:
- >>> x = np.array([1,2,3,4])
- >>> x.base is None
- True
- Slicing creates a view, whose memory is shared with x:
- >>> y = x[2:]
- >>> y.base is x
- True
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('ctypes',
- """
- An object to simplify the interaction of the array with the ctypes
- module.
- This attribute creates an object that makes it easier to use arrays
- when calling shared libraries with the ctypes module. The returned
- object has, among others, data, shape, and strides attributes (see
- Notes below) which themselves return ctypes objects that can be used
- as arguments to a shared library.
- Parameters
- ----------
- None
- Returns
- -------
- c : Python object
- Possessing attributes data, shape, strides, etc.
- See Also
- --------
- numpy.ctypeslib
- Notes
- -----
- Below are the public attributes of this object which were documented
- in "Guide to NumPy" (we have omitted undocumented public attributes,
- as well as documented private attributes):
- .. autoattribute:: numpy.core._internal._ctypes.data
- :noindex:
- .. autoattribute:: numpy.core._internal._ctypes.shape
- :noindex:
- .. autoattribute:: numpy.core._internal._ctypes.strides
- :noindex:
- .. automethod:: numpy.core._internal._ctypes.data_as
- :noindex:
- .. automethod:: numpy.core._internal._ctypes.shape_as
- :noindex:
- .. automethod:: numpy.core._internal._ctypes.strides_as
- :noindex:
- If the ctypes module is not available, then the ctypes attribute
- of array objects still returns something useful, but ctypes objects
- are not returned and errors may be raised instead. In particular,
- the object will still have the ``as_parameter`` attribute which will
- return an integer equal to the data attribute.
- Examples
- --------
- >>> import ctypes
- >>> x = np.array([[0, 1], [2, 3]], dtype=np.int32)
- >>> x
- array([[0, 1],
- [2, 3]], dtype=int32)
- >>> x.ctypes.data
- 31962608 # may vary
- >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32))
- <__main__.LP_c_uint object at 0x7ff2fc1fc200> # may vary
- >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32)).contents
- c_uint(0)
- >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_uint64)).contents
- c_ulong(4294967296)
- >>> x.ctypes.shape
- <numpy.core._internal.c_long_Array_2 object at 0x7ff2fc1fce60> # may vary
- >>> x.ctypes.strides
- <numpy.core._internal.c_long_Array_2 object at 0x7ff2fc1ff320> # may vary
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('data',
- """Python buffer object pointing to the start of the array's data."""))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('dtype',
- """
- Data-type of the array's elements.
- Parameters
- ----------
- None
- Returns
- -------
- d : numpy dtype object
- See Also
- --------
- numpy.dtype
- Examples
- --------
- >>> x
- array([[0, 1],
- [2, 3]])
- >>> x.dtype
- dtype('int32')
- >>> type(x.dtype)
- <type 'numpy.dtype'>
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('imag',
- """
- The imaginary part of the array.
- Examples
- --------
- >>> x = np.sqrt([1+0j, 0+1j])
- >>> x.imag
- array([ 0. , 0.70710678])
- >>> x.imag.dtype
- dtype('float64')
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('itemsize',
- """
- Length of one array element in bytes.
- Examples
- --------
- >>> x = np.array([1,2,3], dtype=np.float64)
- >>> x.itemsize
- 8
- >>> x = np.array([1,2,3], dtype=np.complex128)
- >>> x.itemsize
- 16
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('flags',
- """
- Information about the memory layout of the array.
- Attributes
- ----------
- C_CONTIGUOUS (C)
- The data is in a single, C-style contiguous segment.
- F_CONTIGUOUS (F)
- The data is in a single, Fortran-style contiguous segment.
- OWNDATA (O)
- The array owns the memory it uses or borrows it from another object.
- WRITEABLE (W)
- The data area can be written to. Setting this to False locks
- the data, making it read-only. A view (slice, etc.) inherits WRITEABLE
- from its base array at creation time, but a view of a writeable
- array may be subsequently locked while the base array remains writeable.
- (The opposite is not true, in that a view of a locked array may not
- be made writeable. However, currently, locking a base object does not
- lock any views that already reference it, so under that circumstance it
- is possible to alter the contents of a locked array via a previously
- created writeable view onto it.) Attempting to change a non-writeable
- array raises a RuntimeError exception.
- ALIGNED (A)
- The data and all elements are aligned appropriately for the hardware.
- WRITEBACKIFCOPY (X)
- This array is a copy of some other array. The C-API function
- PyArray_ResolveWritebackIfCopy must be called before deallocating
- to the base array will be updated with the contents of this array.
- UPDATEIFCOPY (U)
- (Deprecated, use WRITEBACKIFCOPY) This array is a copy of some other array.
- When this array is
- deallocated, the base array will be updated with the contents of
- this array.
- FNC
- F_CONTIGUOUS and not C_CONTIGUOUS.
- FORC
- F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
- BEHAVED (B)
- ALIGNED and WRITEABLE.
- CARRAY (CA)
- BEHAVED and C_CONTIGUOUS.
- FARRAY (FA)
- BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.
- Notes
- -----
- The `flags` object can be accessed dictionary-like (as in ``a.flags['WRITEABLE']``),
- or by using lowercased attribute names (as in ``a.flags.writeable``). Short flag
- names are only supported in dictionary access.
- Only the WRITEBACKIFCOPY, UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be
- changed by the user, via direct assignment to the attribute or dictionary
- entry, or by calling `ndarray.setflags`.
- The array flags cannot be set arbitrarily:
- - UPDATEIFCOPY can only be set ``False``.
- - WRITEBACKIFCOPY can only be set ``False``.
- - ALIGNED can only be set ``True`` if the data is truly aligned.
- - WRITEABLE can only be set ``True`` if the array owns its own memory
- or the ultimate owner of the memory exposes a writeable buffer
- interface or is a string.
- Arrays can be both C-style and Fortran-style contiguous simultaneously.
- This is clear for 1-dimensional arrays, but can also be true for higher
- dimensional arrays.
- Even for contiguous arrays a stride for a given dimension
- ``arr.strides[dim]`` may be *arbitrary* if ``arr.shape[dim] == 1``
- or the array has no elements.
- It does *not* generally hold that ``self.strides[-1] == self.itemsize``
- for C-style contiguous arrays or ``self.strides[0] == self.itemsize`` for
- Fortran-style contiguous arrays is true.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('flat',
- """
- A 1-D iterator over the array.
- This is a `numpy.flatiter` instance, which acts similarly to, but is not
- a subclass of, Python's built-in iterator object.
- See Also
- --------
- flatten : Return a copy of the array collapsed into one dimension.
- flatiter
- Examples
- --------
- >>> x = np.arange(1, 7).reshape(2, 3)
- >>> x
- array([[1, 2, 3],
- [4, 5, 6]])
- >>> x.flat[3]
- 4
- >>> x.T
- array([[1, 4],
- [2, 5],
- [3, 6]])
- >>> x.T.flat[3]
- 5
- >>> type(x.flat)
- <class 'numpy.flatiter'>
- An assignment example:
- >>> x.flat = 3; x
- array([[3, 3, 3],
- [3, 3, 3]])
- >>> x.flat[[1,4]] = 1; x
- array([[3, 1, 3],
- [3, 1, 3]])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('nbytes',
- """
- Total bytes consumed by the elements of the array.
- Notes
- -----
- Does not include memory consumed by non-element attributes of the
- array object.
- Examples
- --------
- >>> x = np.zeros((3,5,2), dtype=np.complex128)
- >>> x.nbytes
- 480
- >>> np.prod(x.shape) * x.itemsize
- 480
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('ndim',
- """
- Number of array dimensions.
- Examples
- --------
- >>> x = np.array([1, 2, 3])
- >>> x.ndim
- 1
- >>> y = np.zeros((2, 3, 4))
- >>> y.ndim
- 3
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('real',
- """
- The real part of the array.
- Examples
- --------
- >>> x = np.sqrt([1+0j, 0+1j])
- >>> x.real
- array([ 1. , 0.70710678])
- >>> x.real.dtype
- dtype('float64')
- See Also
- --------
- numpy.real : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('shape',
- """
- Tuple of array dimensions.
- The shape property is usually used to get the current shape of an array,
- but may also be used to reshape the array in-place by assigning a tuple of
- array dimensions to it. As with `numpy.reshape`, one of the new shape
- dimensions can be -1, in which case its value is inferred from the size of
- the array and the remaining dimensions. Reshaping an array in-place will
- fail if a copy is required.
- Examples
- --------
- >>> x = np.array([1, 2, 3, 4])
- >>> x.shape
- (4,)
- >>> y = np.zeros((2, 3, 4))
- >>> y.shape
- (2, 3, 4)
- >>> y.shape = (3, 8)
- >>> y
- array([[ 0., 0., 0., 0., 0., 0., 0., 0.],
- [ 0., 0., 0., 0., 0., 0., 0., 0.],
- [ 0., 0., 0., 0., 0., 0., 0., 0.]])
- >>> y.shape = (3, 6)
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- ValueError: total size of new array must be unchanged
- >>> np.zeros((4,2))[::2].shape = (-1,)
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- AttributeError: Incompatible shape for in-place modification. Use
- `.reshape()` to make a copy with the desired shape.
- See Also
- --------
- numpy.reshape : similar function
- ndarray.reshape : similar method
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('size',
- """
- Number of elements in the array.
- Equal to ``np.prod(a.shape)``, i.e., the product of the array's
- dimensions.
- Notes
- -----
- `a.size` returns a standard arbitrary precision Python integer. This
- may not be the case with other methods of obtaining the same value
- (like the suggested ``np.prod(a.shape)``, which returns an instance
- of ``np.int_``), and may be relevant if the value is used further in
- calculations that may overflow a fixed size integer type.
- Examples
- --------
- >>> x = np.zeros((3, 5, 2), dtype=np.complex128)
- >>> x.size
- 30
- >>> np.prod(x.shape)
- 30
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('strides',
- """
- Tuple of bytes to step in each dimension when traversing an array.
- The byte offset of element ``(i[0], i[1], ..., i[n])`` in an array `a`
- is::
- offset = sum(np.array(i) * a.strides)
- A more detailed explanation of strides can be found in the
- "ndarray.rst" file in the NumPy reference guide.
- Notes
- -----
- Imagine an array of 32-bit integers (each 4 bytes)::
- x = np.array([[0, 1, 2, 3, 4],
- [5, 6, 7, 8, 9]], dtype=np.int32)
- This array is stored in memory as 40 bytes, one after the other
- (known as a contiguous block of memory). The strides of an array tell
- us how many bytes we have to skip in memory to move to the next position
- along a certain axis. For example, we have to skip 4 bytes (1 value) to
- move to the next column, but 20 bytes (5 values) to get to the same
- position in the next row. As such, the strides for the array `x` will be
- ``(20, 4)``.
- See Also
- --------
- numpy.lib.stride_tricks.as_strided
- Examples
- --------
- >>> y = np.reshape(np.arange(2*3*4), (2,3,4))
- >>> y
- array([[[ 0, 1, 2, 3],
- [ 4, 5, 6, 7],
- [ 8, 9, 10, 11]],
- [[12, 13, 14, 15],
- [16, 17, 18, 19],
- [20, 21, 22, 23]]])
- >>> y.strides
- (48, 16, 4)
- >>> y[1,1,1]
- 17
- >>> offset=sum(y.strides * np.array((1,1,1)))
- >>> offset/y.itemsize
- 17
- >>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
- >>> x.strides
- (32, 4, 224, 1344)
- >>> i = np.array([3,5,2,2])
- >>> offset = sum(i * x.strides)
- >>> x[3,5,2,2]
- 813
- >>> offset / x.itemsize
- 813
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('T',
- """
- The transposed array.
- Same as ``self.transpose()``.
- Examples
- --------
- >>> x = np.array([[1.,2.],[3.,4.]])
- >>> x
- array([[ 1., 2.],
- [ 3., 4.]])
- >>> x.T
- array([[ 1., 3.],
- [ 2., 4.]])
- >>> x = np.array([1.,2.,3.,4.])
- >>> x
- array([ 1., 2., 3., 4.])
- >>> x.T
- array([ 1., 2., 3., 4.])
- See Also
- --------
- transpose
- """))
- ##############################################################################
- #
- # ndarray methods
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__array__',
- """ a.__array__([dtype], /) -> reference if type unchanged, copy otherwise.
- Returns either a new reference to self if dtype is not given or a new array
- of provided data type if dtype is different from the current dtype of the
- array.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_prepare__',
- """a.__array_prepare__(obj) -> Object of same type as ndarray object obj.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_wrap__',
- """a.__array_wrap__(obj) -> Object of same type as ndarray object a.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__copy__',
- """a.__copy__()
- Used if :func:`copy.copy` is called on an array. Returns a copy of the array.
- Equivalent to ``a.copy(order='K')``.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__deepcopy__',
- """a.__deepcopy__(memo, /) -> Deep copy of array.
- Used if :func:`copy.deepcopy` is called on an array.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__reduce__',
- """a.__reduce__()
- For pickling.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('__setstate__',
- """a.__setstate__(state, /)
- For unpickling.
- The `state` argument must be a sequence that contains the following
- elements:
- Parameters
- ----------
- version : int
- optional pickle version. If omitted defaults to 0.
- shape : tuple
- dtype : data-type
- isFortran : bool
- rawdata : string or list
- a binary string with the data (or a list if 'a' is an object array)
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('all',
- """
- a.all(axis=None, out=None, keepdims=False)
- Returns True if all elements evaluate to True.
- Refer to `numpy.all` for full documentation.
- See Also
- --------
- numpy.all : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('any',
- """
- a.any(axis=None, out=None, keepdims=False)
- Returns True if any of the elements of `a` evaluate to True.
- Refer to `numpy.any` for full documentation.
- See Also
- --------
- numpy.any : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('argmax',
- """
- a.argmax(axis=None, out=None)
- Return indices of the maximum values along the given axis.
- Refer to `numpy.argmax` for full documentation.
- See Also
- --------
- numpy.argmax : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('argmin',
- """
- a.argmin(axis=None, out=None)
- Return indices of the minimum values along the given axis of `a`.
- Refer to `numpy.argmin` for detailed documentation.
- See Also
- --------
- numpy.argmin : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('argsort',
- """
- a.argsort(axis=-1, kind=None, order=None)
- Returns the indices that would sort this array.
- Refer to `numpy.argsort` for full documentation.
- See Also
- --------
- numpy.argsort : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('argpartition',
- """
- a.argpartition(kth, axis=-1, kind='introselect', order=None)
- Returns the indices that would partition this array.
- Refer to `numpy.argpartition` for full documentation.
- .. versionadded:: 1.8.0
- See Also
- --------
- numpy.argpartition : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('astype',
- """
- a.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)
- Copy of the array, cast to a specified type.
- Parameters
- ----------
- dtype : str or dtype
- Typecode or data-type to which the array is cast.
- order : {'C', 'F', 'A', 'K'}, optional
- Controls the memory layout order of the result.
- 'C' means C order, 'F' means Fortran order, 'A'
- means 'F' order if all the arrays are Fortran contiguous,
- 'C' order otherwise, and 'K' means as close to the
- order the array elements appear in memory as possible.
- Default is 'K'.
- casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
- Controls what kind of data casting may occur. Defaults to 'unsafe'
- for backwards compatibility.
- * 'no' means the data types should not be cast at all.
- * 'equiv' means only byte-order changes are allowed.
- * 'safe' means only casts which can preserve values are allowed.
- * 'same_kind' means only safe casts or casts within a kind,
- like float64 to float32, are allowed.
- * 'unsafe' means any data conversions may be done.
- subok : bool, optional
- If True, then sub-classes will be passed-through (default), otherwise
- the returned array will be forced to be a base-class array.
- copy : bool, optional
- By default, astype always returns a newly allocated array. If this
- is set to false, and the `dtype`, `order`, and `subok`
- requirements are satisfied, the input array is returned instead
- of a copy.
- Returns
- -------
- arr_t : ndarray
- Unless `copy` is False and the other conditions for returning the input
- array are satisfied (see description for `copy` input parameter), `arr_t`
- is a new array of the same shape as the input array, with dtype, order
- given by `dtype`, `order`.
- Notes
- -----
- .. versionchanged:: 1.17.0
- Casting between a simple data type and a structured one is possible only
- for "unsafe" casting. Casting to multiple fields is allowed, but
- casting from multiple fields is not.
- .. versionchanged:: 1.9.0
- Casting from numeric to string types in 'safe' casting mode requires
- that the string dtype length is long enough to store the max
- integer/float value converted.
- Raises
- ------
- ComplexWarning
- When casting from complex to float or int. To avoid this,
- one should use ``a.real.astype(t)``.
- Examples
- --------
- >>> x = np.array([1, 2, 2.5])
- >>> x
- array([1. , 2. , 2.5])
- >>> x.astype(int)
- array([1, 2, 2])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('byteswap',
- """
- a.byteswap(inplace=False)
- Swap the bytes of the array elements
- Toggle between low-endian and big-endian data representation by
- returning a byteswapped array, optionally swapped in-place.
- Arrays of byte-strings are not swapped. The real and imaginary
- parts of a complex number are swapped individually.
- Parameters
- ----------
- inplace : bool, optional
- If ``True``, swap bytes in-place, default is ``False``.
- Returns
- -------
- out : ndarray
- The byteswapped array. If `inplace` is ``True``, this is
- a view to self.
- Examples
- --------
- >>> A = np.array([1, 256, 8755], dtype=np.int16)
- >>> list(map(hex, A))
- ['0x1', '0x100', '0x2233']
- >>> A.byteswap(inplace=True)
- array([ 256, 1, 13090], dtype=int16)
- >>> list(map(hex, A))
- ['0x100', '0x1', '0x3322']
- Arrays of byte-strings are not swapped
- >>> A = np.array([b'ceg', b'fac'])
- >>> A.byteswap()
- array([b'ceg', b'fac'], dtype='|S3')
- ``A.newbyteorder().byteswap()`` produces an array with the same values
- but different representation in memory
- >>> A = np.array([1, 2, 3])
- >>> A.view(np.uint8)
- array([1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0,
- 0, 0], dtype=uint8)
- >>> A.newbyteorder().byteswap(inplace=True)
- array([1, 2, 3])
- >>> A.view(np.uint8)
- array([0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0,
- 0, 3], dtype=uint8)
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('choose',
- """
- a.choose(choices, out=None, mode='raise')
- Use an index array to construct a new array from a set of choices.
- Refer to `numpy.choose` for full documentation.
- See Also
- --------
- numpy.choose : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('clip',
- """
- a.clip(min=None, max=None, out=None, **kwargs)
- Return an array whose values are limited to ``[min, max]``.
- One of max or min must be given.
- Refer to `numpy.clip` for full documentation.
- See Also
- --------
- numpy.clip : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('compress',
- """
- a.compress(condition, axis=None, out=None)
- Return selected slices of this array along given axis.
- Refer to `numpy.compress` for full documentation.
- See Also
- --------
- numpy.compress : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('conj',
- """
- a.conj()
- Complex-conjugate all elements.
- Refer to `numpy.conjugate` for full documentation.
- See Also
- --------
- numpy.conjugate : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('conjugate',
- """
- a.conjugate()
- Return the complex conjugate, element-wise.
- Refer to `numpy.conjugate` for full documentation.
- See Also
- --------
- numpy.conjugate : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('copy',
- """
- a.copy(order='C')
- Return a copy of the array.
- Parameters
- ----------
- order : {'C', 'F', 'A', 'K'}, optional
- Controls the memory layout of the copy. 'C' means C-order,
- 'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
- 'C' otherwise. 'K' means match the layout of `a` as closely
- as possible. (Note that this function and :func:`numpy.copy` are very
- similar, but have different default values for their order=
- arguments.)
- See also
- --------
- numpy.copy
- numpy.copyto
- Examples
- --------
- >>> x = np.array([[1,2,3],[4,5,6]], order='F')
- >>> y = x.copy()
- >>> x.fill(0)
- >>> x
- array([[0, 0, 0],
- [0, 0, 0]])
- >>> y
- array([[1, 2, 3],
- [4, 5, 6]])
- >>> y.flags['C_CONTIGUOUS']
- True
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('cumprod',
- """
- a.cumprod(axis=None, dtype=None, out=None)
- Return the cumulative product of the elements along the given axis.
- Refer to `numpy.cumprod` for full documentation.
- See Also
- --------
- numpy.cumprod : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('cumsum',
- """
- a.cumsum(axis=None, dtype=None, out=None)
- Return the cumulative sum of the elements along the given axis.
- Refer to `numpy.cumsum` for full documentation.
- See Also
- --------
- numpy.cumsum : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal',
- """
- a.diagonal(offset=0, axis1=0, axis2=1)
- Return specified diagonals. In NumPy 1.9 the returned array is a
- read-only view instead of a copy as in previous NumPy versions. In
- a future version the read-only restriction will be removed.
- Refer to :func:`numpy.diagonal` for full documentation.
- See Also
- --------
- numpy.diagonal : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('dot',
- """
- a.dot(b, out=None)
- Dot product of two arrays.
- Refer to `numpy.dot` for full documentation.
- See Also
- --------
- numpy.dot : equivalent function
- Examples
- --------
- >>> a = np.eye(2)
- >>> b = np.ones((2, 2)) * 2
- >>> a.dot(b)
- array([[2., 2.],
- [2., 2.]])
- This array method can be conveniently chained:
- >>> a.dot(b).dot(b)
- array([[8., 8.],
- [8., 8.]])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('dump',
- """a.dump(file)
- Dump a pickle of the array to the specified file.
- The array can be read back with pickle.load or numpy.load.
- Parameters
- ----------
- file : str or Path
- A string naming the dump file.
- .. versionchanged:: 1.17.0
- `pathlib.Path` objects are now accepted.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('dumps',
- """
- a.dumps()
- Returns the pickle of the array as a string.
- pickle.loads or numpy.loads will convert the string back to an array.
- Parameters
- ----------
- None
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('fill',
- """
- a.fill(value)
- Fill the array with a scalar value.
- Parameters
- ----------
- value : scalar
- All elements of `a` will be assigned this value.
- Examples
- --------
- >>> a = np.array([1, 2])
- >>> a.fill(0)
- >>> a
- array([0, 0])
- >>> a = np.empty(2)
- >>> a.fill(1)
- >>> a
- array([1., 1.])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('flatten',
- """
- a.flatten(order='C')
- Return a copy of the array collapsed into one dimension.
- Parameters
- ----------
- order : {'C', 'F', 'A', 'K'}, optional
- 'C' means to flatten in row-major (C-style) order.
- 'F' means to flatten in column-major (Fortran-
- style) order. 'A' means to flatten in column-major
- order if `a` is Fortran *contiguous* in memory,
- row-major order otherwise. 'K' means to flatten
- `a` in the order the elements occur in memory.
- The default is 'C'.
- Returns
- -------
- y : ndarray
- A copy of the input array, flattened to one dimension.
- See Also
- --------
- ravel : Return a flattened array.
- flat : A 1-D flat iterator over the array.
- Examples
- --------
- >>> a = np.array([[1,2], [3,4]])
- >>> a.flatten()
- array([1, 2, 3, 4])
- >>> a.flatten('F')
- array([1, 3, 2, 4])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('getfield',
- """
- a.getfield(dtype, offset=0)
- Returns a field of the given array as a certain type.
- A field is a view of the array data with a given data-type. The values in
- the view are determined by the given type and the offset into the current
- array in bytes. The offset needs to be such that the view dtype fits in the
- array dtype; for example an array of dtype complex128 has 16-byte elements.
- If taking a view with a 32-bit integer (4 bytes), the offset needs to be
- between 0 and 12 bytes.
- Parameters
- ----------
- dtype : str or dtype
- The data type of the view. The dtype size of the view can not be larger
- than that of the array itself.
- offset : int
- Number of bytes to skip before beginning the element view.
- Examples
- --------
- >>> x = np.diag([1.+1.j]*2)
- >>> x[1, 1] = 2 + 4.j
- >>> x
- array([[1.+1.j, 0.+0.j],
- [0.+0.j, 2.+4.j]])
- >>> x.getfield(np.float64)
- array([[1., 0.],
- [0., 2.]])
- By choosing an offset of 8 bytes we can select the complex part of the
- array for our view:
- >>> x.getfield(np.float64, offset=8)
- array([[1., 0.],
- [0., 4.]])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('item',
- """
- a.item(*args)
- Copy an element of an array to a standard Python scalar and return it.
- Parameters
- ----------
- \\*args : Arguments (variable number and type)
- * none: in this case, the method only works for arrays
- with one element (`a.size == 1`), which element is
- copied into a standard Python scalar object and returned.
- * int_type: this argument is interpreted as a flat index into
- the array, specifying which element to copy and return.
- * tuple of int_types: functions as does a single int_type argument,
- except that the argument is interpreted as an nd-index into the
- array.
- Returns
- -------
- z : Standard Python scalar object
- A copy of the specified element of the array as a suitable
- Python scalar
- Notes
- -----
- When the data type of `a` is longdouble or clongdouble, item() returns
- a scalar array object because there is no available Python scalar that
- would not lose information. Void arrays return a buffer object for item(),
- unless fields are defined, in which case a tuple is returned.
- `item` is very similar to a[args], except, instead of an array scalar,
- a standard Python scalar is returned. This can be useful for speeding up
- access to elements of the array and doing arithmetic on elements of the
- array using Python's optimized math.
- Examples
- --------
- >>> np.random.seed(123)
- >>> x = np.random.randint(9, size=(3, 3))
- >>> x
- array([[2, 2, 6],
- [1, 3, 6],
- [1, 0, 1]])
- >>> x.item(3)
- 1
- >>> x.item(7)
- 0
- >>> x.item((0, 1))
- 2
- >>> x.item((2, 2))
- 1
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('itemset',
- """
- a.itemset(*args)
- Insert scalar into an array (scalar is cast to array's dtype, if possible)
- There must be at least 1 argument, and define the last argument
- as *item*. Then, ``a.itemset(*args)`` is equivalent to but faster
- than ``a[args] = item``. The item should be a scalar value and `args`
- must select a single item in the array `a`.
- Parameters
- ----------
- \\*args : Arguments
- If one argument: a scalar, only used in case `a` is of size 1.
- If two arguments: the last argument is the value to be set
- and must be a scalar, the first argument specifies a single array
- element location. It is either an int or a tuple.
- Notes
- -----
- Compared to indexing syntax, `itemset` provides some speed increase
- for placing a scalar into a particular location in an `ndarray`,
- if you must do this. However, generally this is discouraged:
- among other problems, it complicates the appearance of the code.
- Also, when using `itemset` (and `item`) inside a loop, be sure
- to assign the methods to a local variable to avoid the attribute
- look-up at each loop iteration.
- Examples
- --------
- >>> np.random.seed(123)
- >>> x = np.random.randint(9, size=(3, 3))
- >>> x
- array([[2, 2, 6],
- [1, 3, 6],
- [1, 0, 1]])
- >>> x.itemset(4, 0)
- >>> x.itemset((2, 2), 9)
- >>> x
- array([[2, 2, 6],
- [1, 0, 6],
- [1, 0, 9]])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('max',
- """
- a.max(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
- Return the maximum along a given axis.
- Refer to `numpy.amax` for full documentation.
- See Also
- --------
- numpy.amax : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('mean',
- """
- a.mean(axis=None, dtype=None, out=None, keepdims=False)
- Returns the average of the array elements along given axis.
- Refer to `numpy.mean` for full documentation.
- See Also
- --------
- numpy.mean : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('min',
- """
- a.min(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
- Return the minimum along a given axis.
- Refer to `numpy.amin` for full documentation.
- See Also
- --------
- numpy.amin : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('newbyteorder',
- """
- arr.newbyteorder(new_order='S')
- Return the array with the same data viewed with a different byte order.
- Equivalent to::
- arr.view(arr.dtype.newbytorder(new_order))
- Changes are also made in all fields and sub-arrays of the array data
- type.
- Parameters
- ----------
- new_order : string, optional
- Byte order to force; a value from the byte order specifications
- below. `new_order` codes can be any of:
- * 'S' - swap dtype from current to opposite endian
- * {'<', 'L'} - little endian
- * {'>', 'B'} - big endian
- * {'=', 'N'} - native order
- * {'|', 'I'} - ignore (no change to byte order)
- The default value ('S') results in swapping the current
- byte order. The code does a case-insensitive check on the first
- letter of `new_order` for the alternatives above. For example,
- any of 'B' or 'b' or 'biggish' are valid to specify big-endian.
- Returns
- -------
- new_arr : array
- New array object with the dtype reflecting given change to the
- byte order.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('nonzero',
- """
- a.nonzero()
- Return the indices of the elements that are non-zero.
- Refer to `numpy.nonzero` for full documentation.
- See Also
- --------
- numpy.nonzero : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('prod',
- """
- a.prod(axis=None, dtype=None, out=None, keepdims=False, initial=1, where=True)
- Return the product of the array elements over the given axis
- Refer to `numpy.prod` for full documentation.
- See Also
- --------
- numpy.prod : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('ptp',
- """
- a.ptp(axis=None, out=None, keepdims=False)
- Peak to peak (maximum - minimum) value along a given axis.
- Refer to `numpy.ptp` for full documentation.
- See Also
- --------
- numpy.ptp : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('put',
- """
- a.put(indices, values, mode='raise')
- Set ``a.flat[n] = values[n]`` for all `n` in indices.
- Refer to `numpy.put` for full documentation.
- See Also
- --------
- numpy.put : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('ravel',
- """
- a.ravel([order])
- Return a flattened array.
- Refer to `numpy.ravel` for full documentation.
- See Also
- --------
- numpy.ravel : equivalent function
- ndarray.flat : a flat iterator on the array.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('repeat',
- """
- a.repeat(repeats, axis=None)
- Repeat elements of an array.
- Refer to `numpy.repeat` for full documentation.
- See Also
- --------
- numpy.repeat : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('reshape',
- """
- a.reshape(shape, order='C')
- Returns an array containing the same data with a new shape.
- Refer to `numpy.reshape` for full documentation.
- See Also
- --------
- numpy.reshape : equivalent function
- Notes
- -----
- Unlike the free function `numpy.reshape`, this method on `ndarray` allows
- the elements of the shape parameter to be passed in as separate arguments.
- For example, ``a.reshape(10, 11)`` is equivalent to
- ``a.reshape((10, 11))``.
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('resize',
- """
- a.resize(new_shape, refcheck=True)
- Change shape and size of array in-place.
- Parameters
- ----------
- new_shape : tuple of ints, or `n` ints
- Shape of resized array.
- refcheck : bool, optional
- If False, reference count will not be checked. Default is True.
- Returns
- -------
- None
- Raises
- ------
- ValueError
- If `a` does not own its own data or references or views to it exist,
- and the data memory must be changed.
- PyPy only: will always raise if the data memory must be changed, since
- there is no reliable way to determine if references or views to it
- exist.
- SystemError
- If the `order` keyword argument is specified. This behaviour is a
- bug in NumPy.
- See Also
- --------
- resize : Return a new array with the specified shape.
- Notes
- -----
- This reallocates space for the data area if necessary.
- Only contiguous arrays (data elements consecutive in memory) can be
- resized.
- The purpose of the reference count check is to make sure you
- do not use this array as a buffer for another Python object and then
- reallocate the memory. However, reference counts can increase in
- other ways so if you are sure that you have not shared the memory
- for this array with another Python object, then you may safely set
- `refcheck` to False.
- Examples
- --------
- Shrinking an array: array is flattened (in the order that the data are
- stored in memory), resized, and reshaped:
- >>> a = np.array([[0, 1], [2, 3]], order='C')
- >>> a.resize((2, 1))
- >>> a
- array([[0],
- [1]])
- >>> a = np.array([[0, 1], [2, 3]], order='F')
- >>> a.resize((2, 1))
- >>> a
- array([[0],
- [2]])
- Enlarging an array: as above, but missing entries are filled with zeros:
- >>> b = np.array([[0, 1], [2, 3]])
- >>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
- >>> b
- array([[0, 1, 2],
- [3, 0, 0]])
- Referencing an array prevents resizing...
- >>> c = a
- >>> a.resize((1, 1))
- Traceback (most recent call last):
- ...
- ValueError: cannot resize an array that references or is referenced ...
- Unless `refcheck` is False:
- >>> a.resize((1, 1), refcheck=False)
- >>> a
- array([[0]])
- >>> c
- array([[0]])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('round',
- """
- a.round(decimals=0, out=None)
- Return `a` with each element rounded to the given number of decimals.
- Refer to `numpy.around` for full documentation.
- See Also
- --------
- numpy.around : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('searchsorted',
- """
- a.searchsorted(v, side='left', sorter=None)
- Find indices where elements of v should be inserted in a to maintain order.
- For full documentation, see `numpy.searchsorted`
- See Also
- --------
- numpy.searchsorted : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('setfield',
- """
- a.setfield(val, dtype, offset=0)
- Put a value into a specified place in a field defined by a data-type.
- Place `val` into `a`'s field defined by `dtype` and beginning `offset`
- bytes into the field.
- Parameters
- ----------
- val : object
- Value to be placed in field.
- dtype : dtype object
- Data-type of the field in which to place `val`.
- offset : int, optional
- The number of bytes into the field at which to place `val`.
- Returns
- -------
- None
- See Also
- --------
- getfield
- Examples
- --------
- >>> x = np.eye(3)
- >>> x.getfield(np.float64)
- array([[1., 0., 0.],
- [0., 1., 0.],
- [0., 0., 1.]])
- >>> x.setfield(3, np.int32)
- >>> x.getfield(np.int32)
- array([[3, 3, 3],
- [3, 3, 3],
- [3, 3, 3]], dtype=int32)
- >>> x
- array([[1.0e+000, 1.5e-323, 1.5e-323],
- [1.5e-323, 1.0e+000, 1.5e-323],
- [1.5e-323, 1.5e-323, 1.0e+000]])
- >>> x.setfield(np.eye(3), np.int32)
- >>> x
- array([[1., 0., 0.],
- [0., 1., 0.],
- [0., 0., 1.]])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('setflags',
- """
- a.setflags(write=None, align=None, uic=None)
- Set array flags WRITEABLE, ALIGNED, (WRITEBACKIFCOPY and UPDATEIFCOPY),
- respectively.
- These Boolean-valued flags affect how numpy interprets the memory
- area used by `a` (see Notes below). The ALIGNED flag can only
- be set to True if the data is actually aligned according to the type.
- The WRITEBACKIFCOPY and (deprecated) UPDATEIFCOPY flags can never be set
- to True. The flag WRITEABLE can only be set to True if the array owns its
- own memory, or the ultimate owner of the memory exposes a writeable buffer
- interface, or is a string. (The exception for string is made so that
- unpickling can be done without copying memory.)
- Parameters
- ----------
- write : bool, optional
- Describes whether or not `a` can be written to.
- align : bool, optional
- Describes whether or not `a` is aligned properly for its type.
- uic : bool, optional
- Describes whether or not `a` is a copy of another "base" array.
- Notes
- -----
- Array flags provide information about how the memory area used
- for the array is to be interpreted. There are 7 Boolean flags
- in use, only four of which can be changed by the user:
- WRITEBACKIFCOPY, UPDATEIFCOPY, WRITEABLE, and ALIGNED.
- WRITEABLE (W) the data area can be written to;
- ALIGNED (A) the data and strides are aligned appropriately for the hardware
- (as determined by the compiler);
- UPDATEIFCOPY (U) (deprecated), replaced by WRITEBACKIFCOPY;
- WRITEBACKIFCOPY (X) this array is a copy of some other array (referenced
- by .base). When the C-API function PyArray_ResolveWritebackIfCopy is
- called, the base array will be updated with the contents of this array.
- All flags can be accessed using the single (upper case) letter as well
- as the full name.
- Examples
- --------
- >>> y = np.array([[3, 1, 7],
- ... [2, 0, 0],
- ... [8, 5, 9]])
- >>> y
- array([[3, 1, 7],
- [2, 0, 0],
- [8, 5, 9]])
- >>> y.flags
- C_CONTIGUOUS : True
- F_CONTIGUOUS : False
- OWNDATA : True
- WRITEABLE : True
- ALIGNED : True
- WRITEBACKIFCOPY : False
- UPDATEIFCOPY : False
- >>> y.setflags(write=0, align=0)
- >>> y.flags
- C_CONTIGUOUS : True
- F_CONTIGUOUS : False
- OWNDATA : True
- WRITEABLE : False
- ALIGNED : False
- WRITEBACKIFCOPY : False
- UPDATEIFCOPY : False
- >>> y.setflags(uic=1)
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- ValueError: cannot set WRITEBACKIFCOPY flag to True
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('sort',
- """
- a.sort(axis=-1, kind=None, order=None)
- Sort an array in-place. Refer to `numpy.sort` for full documentation.
- Parameters
- ----------
- axis : int, optional
- Axis along which to sort. Default is -1, which means sort along the
- last axis.
- kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
- Sorting algorithm. The default is 'quicksort'. Note that both 'stable'
- and 'mergesort' use timsort under the covers and, in general, the
- actual implementation will vary with datatype. The 'mergesort' option
- is retained for backwards compatibility.
- .. versionchanged:: 1.15.0.
- The 'stable' option was added.
- order : str or list of str, optional
- When `a` is an array with fields defined, this argument specifies
- which fields to compare first, second, etc. A single field can
- be specified as a string, and not all fields need be specified,
- but unspecified fields will still be used, in the order in which
- they come up in the dtype, to break ties.
- See Also
- --------
- numpy.sort : Return a sorted copy of an array.
- numpy.argsort : Indirect sort.
- numpy.lexsort : Indirect stable sort on multiple keys.
- numpy.searchsorted : Find elements in sorted array.
- numpy.partition: Partial sort.
- Notes
- -----
- See `numpy.sort` for notes on the different sorting algorithms.
- Examples
- --------
- >>> a = np.array([[1,4], [3,1]])
- >>> a.sort(axis=1)
- >>> a
- array([[1, 4],
- [1, 3]])
- >>> a.sort(axis=0)
- >>> a
- array([[1, 3],
- [1, 4]])
- Use the `order` keyword to specify a field to use when sorting a
- structured array:
- >>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
- >>> a.sort(order='y')
- >>> a
- array([(b'c', 1), (b'a', 2)],
- dtype=[('x', 'S1'), ('y', '<i8')])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('partition',
- """
- a.partition(kth, axis=-1, kind='introselect', order=None)
- Rearranges the elements in the array in such a way that the value of the
- element in kth position is in the position it would be in a sorted array.
- All elements smaller than the kth element are moved before this element and
- all equal or greater are moved behind it. The ordering of the elements in
- the two partitions is undefined.
- .. versionadded:: 1.8.0
- Parameters
- ----------
- kth : int or sequence of ints
- Element index to partition by. The kth element value will be in its
- final sorted position and all smaller elements will be moved before it
- and all equal or greater elements behind it.
- The order of all elements in the partitions is undefined.
- If provided with a sequence of kth it will partition all elements
- indexed by kth of them into their sorted position at once.
- axis : int, optional
- Axis along which to sort. Default is -1, which means sort along the
- last axis.
- kind : {'introselect'}, optional
- Selection algorithm. Default is 'introselect'.
- order : str or list of str, optional
- When `a` is an array with fields defined, this argument specifies
- which fields to compare first, second, etc. A single field can
- be specified as a string, and not all fields need to be specified,
- but unspecified fields will still be used, in the order in which
- they come up in the dtype, to break ties.
- See Also
- --------
- numpy.partition : Return a parititioned copy of an array.
- argpartition : Indirect partition.
- sort : Full sort.
- Notes
- -----
- See ``np.partition`` for notes on the different algorithms.
- Examples
- --------
- >>> a = np.array([3, 4, 2, 1])
- >>> a.partition(3)
- >>> a
- array([2, 1, 3, 4])
- >>> a.partition((1, 3))
- >>> a
- array([1, 2, 3, 4])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('squeeze',
- """
- a.squeeze(axis=None)
- Remove single-dimensional entries from the shape of `a`.
- Refer to `numpy.squeeze` for full documentation.
- See Also
- --------
- numpy.squeeze : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
- """
- a.std(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
- Returns the standard deviation of the array elements along given axis.
- Refer to `numpy.std` for full documentation.
- See Also
- --------
- numpy.std : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('sum',
- """
- a.sum(axis=None, dtype=None, out=None, keepdims=False, initial=0, where=True)
- Return the sum of the array elements over the given axis.
- Refer to `numpy.sum` for full documentation.
- See Also
- --------
- numpy.sum : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('swapaxes',
- """
- a.swapaxes(axis1, axis2)
- Return a view of the array with `axis1` and `axis2` interchanged.
- Refer to `numpy.swapaxes` for full documentation.
- See Also
- --------
- numpy.swapaxes : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('take',
- """
- a.take(indices, axis=None, out=None, mode='raise')
- Return an array formed from the elements of `a` at the given indices.
- Refer to `numpy.take` for full documentation.
- See Also
- --------
- numpy.take : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('tofile',
- """
- a.tofile(fid, sep="", format="%s")
- Write array to a file as text or binary (default).
- Data is always written in 'C' order, independent of the order of `a`.
- The data produced by this method can be recovered using the function
- fromfile().
- Parameters
- ----------
- fid : file or str or Path
- An open file object, or a string containing a filename.
- .. versionchanged:: 1.17.0
- `pathlib.Path` objects are now accepted.
- sep : str
- Separator between array items for text output.
- If "" (empty), a binary file is written, equivalent to
- ``file.write(a.tobytes())``.
- format : str
- Format string for text file output.
- Each entry in the array is formatted to text by first converting
- it to the closest Python type, and then using "format" % item.
- Notes
- -----
- This is a convenience function for quick storage of array data.
- Information on endianness and precision is lost, so this method is not a
- good choice for files intended to archive data or transport data between
- machines with different endianness. Some of these problems can be overcome
- by outputting the data as text files, at the expense of speed and file
- size.
- When fid is a file object, array contents are directly written to the
- file, bypassing the file object's ``write`` method. As a result, tofile
- cannot be used with files objects supporting compression (e.g., GzipFile)
- or file-like objects that do not support ``fileno()`` (e.g., BytesIO).
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('tolist',
- """
- a.tolist()
- Return the array as an ``a.ndim``-levels deep nested list of Python scalars.
- Return a copy of the array data as a (nested) Python list.
- Data items are converted to the nearest compatible builtin Python type, via
- the `~numpy.ndarray.item` function.
- If ``a.ndim`` is 0, then since the depth of the nested list is 0, it will
- not be a list at all, but a simple Python scalar.
- Parameters
- ----------
- none
- Returns
- -------
- y : object, or list of object, or list of list of object, or ...
- The possibly nested list of array elements.
- Notes
- -----
- The array may be recreated via ``a = np.array(a.tolist())``, although this
- may sometimes lose precision.
- Examples
- --------
- For a 1D array, ``a.tolist()`` is almost the same as ``list(a)``,
- except that ``tolist`` changes numpy scalars to Python scalars:
- >>> a = np.uint32([1, 2])
- >>> a_list = list(a)
- >>> a_list
- [1, 2]
- >>> type(a_list[0])
- <class 'numpy.uint32'>
- >>> a_tolist = a.tolist()
- >>> a_tolist
- [1, 2]
- >>> type(a_tolist[0])
- <class 'int'>
- Additionally, for a 2D array, ``tolist`` applies recursively:
- >>> a = np.array([[1, 2], [3, 4]])
- >>> list(a)
- [array([1, 2]), array([3, 4])]
- >>> a.tolist()
- [[1, 2], [3, 4]]
- The base case for this recursion is a 0D array:
- >>> a = np.array(1)
- >>> list(a)
- Traceback (most recent call last):
- ...
- TypeError: iteration over a 0-d array
- >>> a.tolist()
- 1
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('tobytes', """
- a.tobytes(order='C')
- Construct Python bytes containing the raw data bytes in the array.
- Constructs Python bytes showing a copy of the raw contents of
- data memory. The bytes object can be produced in either 'C' or 'Fortran',
- or 'Any' order (the default is 'C'-order). 'Any' order means C-order
- unless the F_CONTIGUOUS flag in the array is set, in which case it
- means 'Fortran' order.
- .. versionadded:: 1.9.0
- Parameters
- ----------
- order : {'C', 'F', None}, optional
- Order of the data for multidimensional arrays:
- C, Fortran, or the same as for the original array.
- Returns
- -------
- s : bytes
- Python bytes exhibiting a copy of `a`'s raw data.
- Examples
- --------
- >>> x = np.array([[0, 1], [2, 3]], dtype='<u2')
- >>> x.tobytes()
- b'\\x00\\x00\\x01\\x00\\x02\\x00\\x03\\x00'
- >>> x.tobytes('C') == x.tobytes()
- True
- >>> x.tobytes('F')
- b'\\x00\\x00\\x02\\x00\\x01\\x00\\x03\\x00'
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring', r"""
- a.tostring(order='C')
- A compatibility alias for `tobytes`, with exactly the same behavior.
- Despite its name, it returns `bytes` not `str`\ s.
- .. deprecated:: 1.19.0
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('trace',
- """
- a.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)
- Return the sum along diagonals of the array.
- Refer to `numpy.trace` for full documentation.
- See Also
- --------
- numpy.trace : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose',
- """
- a.transpose(*axes)
- Returns a view of the array with axes transposed.
- For a 1-D array this has no effect, as a transposed vector is simply the
- same vector. To convert a 1-D array into a 2D column vector, an additional
- dimension must be added. `np.atleast2d(a).T` achieves this, as does
- `a[:, np.newaxis]`.
- For a 2-D array, this is a standard matrix transpose.
- For an n-D array, if axes are given, their order indicates how the
- axes are permuted (see Examples). If axes are not provided and
- ``a.shape = (i[0], i[1], ... i[n-2], i[n-1])``, then
- ``a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0])``.
- Parameters
- ----------
- axes : None, tuple of ints, or `n` ints
- * None or no argument: reverses the order of the axes.
- * tuple of ints: `i` in the `j`-th place in the tuple means `a`'s
- `i`-th axis becomes `a.transpose()`'s `j`-th axis.
- * `n` ints: same as an n-tuple of the same ints (this form is
- intended simply as a "convenience" alternative to the tuple form)
- Returns
- -------
- out : ndarray
- View of `a`, with axes suitably permuted.
- See Also
- --------
- ndarray.T : Array property returning the array transposed.
- ndarray.reshape : Give a new shape to an array without changing its data.
- Examples
- --------
- >>> a = np.array([[1, 2], [3, 4]])
- >>> a
- array([[1, 2],
- [3, 4]])
- >>> a.transpose()
- array([[1, 3],
- [2, 4]])
- >>> a.transpose((1, 0))
- array([[1, 3],
- [2, 4]])
- >>> a.transpose(1, 0)
- array([[1, 3],
- [2, 4]])
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('var',
- """
- a.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False)
- Returns the variance of the array elements, along given axis.
- Refer to `numpy.var` for full documentation.
- See Also
- --------
- numpy.var : equivalent function
- """))
- add_newdoc('numpy.core.multiarray', 'ndarray', ('view',
- """
- a.view([dtype][, type])
- New view of array with the same data.
- .. note::
- Passing None for ``dtype`` is different from omitting the parameter,
- since the former invokes ``dtype(None)`` which is an alias for
- ``dtype('float_')``.
- Parameters
- ----------
- dtype : data-type or ndarray sub-class, optional
- Data-type descriptor of the returned view, e.g., float32 or int16.
- Omitting it results in the view having the same data-type as `a`.
- This argument can also be specified as an ndarray sub-class, which
- then specifies the type of the returned object (this is equivalent to
- setting the ``type`` parameter).
- type : Python type, optional
- Type of the returned view, e.g., ndarray or matrix. Again, omission
- of the parameter results in type preservation.
- Notes
- -----
- ``a.view()`` is used two different ways:
- ``a.view(some_dtype)`` or ``a.view(dtype=some_dtype)`` constructs a view
- of the array's memory with a different data-type. This can cause a
- reinterpretation of the bytes of memory.
- ``a.view(ndarray_subclass)`` or ``a.view(type=ndarray_subclass)`` just
- returns an instance of `ndarray_subclass` that looks at the same array
- (same shape, dtype, etc.) This does not cause a reinterpretation of the
- memory.
- For ``a.view(some_dtype)``, if ``some_dtype`` has a different number of
- bytes per entry than the previous dtype (for example, converting a
- regular array to a structured array), then the behavior of the view
- cannot be predicted just from the superficial appearance of ``a`` (shown
- by ``print(a)``). It also depends on exactly how ``a`` is stored in
- memory. Therefore if ``a`` is C-ordered versus fortran-ordered, versus
- defined as a slice or transpose, etc., the view may give different
- results.
- Examples
- --------
- >>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])
- Viewing array data using a different type and dtype:
- >>> y = x.view(dtype=np.int16, type=np.matrix)
- >>> y
- matrix([[513]], dtype=int16)
- >>> print(type(y))
- <class 'numpy.matrix'>
- Creating a view on a structured array so it can be used in calculations
- >>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
- >>> xv = x.view(dtype=np.int8).reshape(-1,2)
- >>> xv
- array([[1, 2],
- [3, 4]], dtype=int8)
- >>> xv.mean(0)
- array([2., 3.])
- Making changes to the view changes the underlying array
- >>> xv[0,1] = 20
- >>> x
- array([(1, 20), (3, 4)], dtype=[('a', 'i1'), ('b', 'i1')])
- Using a view to convert an array to a recarray:
- >>> z = x.view(np.recarray)
- >>> z.a
- array([1, 3], dtype=int8)
- Views share data:
- >>> x[0] = (9, 10)
- >>> z[0]
- (9, 10)
- Views that change the dtype size (bytes per entry) should normally be
- avoided on arrays defined by slices, transposes, fortran-ordering, etc.:
- >>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
- >>> y = x[:, 0:2]
- >>> y
- array([[1, 2],
- [4, 5]], dtype=int16)
- >>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
- Traceback (most recent call last):
- ...
- ValueError: To change to a dtype of a different size, the array must be C-contiguous
- >>> z = y.copy()
- >>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
- array([[(1, 2)],
- [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])
- """))
- ##############################################################################
- #
- # umath functions
- #
- ##############################################################################
- add_newdoc('numpy.core.umath', 'frompyfunc',
- """
- frompyfunc(func, nin, nout, *[, identity])
- Takes an arbitrary Python function and returns a NumPy ufunc.
- Can be used, for example, to add broadcasting to a built-in Python
- function (see Examples section).
- Parameters
- ----------
- func : Python function object
- An arbitrary Python function.
- nin : int
- The number of input arguments.
- nout : int
- The number of objects returned by `func`.
- identity : object, optional
- The value to use for the `~numpy.ufunc.identity` attribute of the resulting
- object. If specified, this is equivalent to setting the underlying
- C ``identity`` field to ``PyUFunc_IdentityValue``.
- If omitted, the identity is set to ``PyUFunc_None``. Note that this is
- _not_ equivalent to setting the identity to ``None``, which implies the
- operation is reorderable.
- Returns
- -------
- out : ufunc
- Returns a NumPy universal function (``ufunc``) object.
- See Also
- --------
- vectorize : Evaluates pyfunc over input arrays using broadcasting rules of numpy.
- Notes
- -----
- The returned ufunc always returns PyObject arrays.
- Examples
- --------
- Use frompyfunc to add broadcasting to the Python function ``oct``:
- >>> oct_array = np.frompyfunc(oct, 1, 1)
- >>> oct_array(np.array((10, 30, 100)))
- array(['0o12', '0o36', '0o144'], dtype=object)
- >>> np.array((oct(10), oct(30), oct(100))) # for comparison
- array(['0o12', '0o36', '0o144'], dtype='<U5')
- """)
- add_newdoc('numpy.core.umath', 'geterrobj',
- """
- geterrobj()
- Return the current object that defines floating-point error handling.
- The error object contains all information that defines the error handling
- behavior in NumPy. `geterrobj` is used internally by the other
- functions that get and set error handling behavior (`geterr`, `seterr`,
- `geterrcall`, `seterrcall`).
- Returns
- -------
- errobj : list
- The error object, a list containing three elements:
- [internal numpy buffer size, error mask, error callback function].
- The error mask is a single integer that holds the treatment information
- on all four floating point errors. The information for each error type
- is contained in three bits of the integer. If we print it in base 8, we
- can see what treatment is set for "invalid", "under", "over", and
- "divide" (in that order). The printed string can be interpreted with
- * 0 : 'ignore'
- * 1 : 'warn'
- * 2 : 'raise'
- * 3 : 'call'
- * 4 : 'print'
- * 5 : 'log'
- See Also
- --------
- seterrobj, seterr, geterr, seterrcall, geterrcall
- getbufsize, setbufsize
- Notes
- -----
- For complete documentation of the types of floating-point exceptions and
- treatment options, see `seterr`.
- Examples
- --------
- >>> np.geterrobj() # first get the defaults
- [8192, 521, None]
- >>> def err_handler(type, flag):
- ... print("Floating point error (%s), with flag %s" % (type, flag))
- ...
- >>> old_bufsize = np.setbufsize(20000)
- >>> old_err = np.seterr(divide='raise')
- >>> old_handler = np.seterrcall(err_handler)
- >>> np.geterrobj()
- [8192, 521, <function err_handler at 0x91dcaac>]
- >>> old_err = np.seterr(all='ignore')
- >>> np.base_repr(np.geterrobj()[1], 8)
- '0'
- >>> old_err = np.seterr(divide='warn', over='log', under='call',
- ... invalid='print')
- >>> np.base_repr(np.geterrobj()[1], 8)
- '4351'
- """)
- add_newdoc('numpy.core.umath', 'seterrobj',
- """
- seterrobj(errobj)
- Set the object that defines floating-point error handling.
- The error object contains all information that defines the error handling
- behavior in NumPy. `seterrobj` is used internally by the other
- functions that set error handling behavior (`seterr`, `seterrcall`).
- Parameters
- ----------
- errobj : list
- The error object, a list containing three elements:
- [internal numpy buffer size, error mask, error callback function].
- The error mask is a single integer that holds the treatment information
- on all four floating point errors. The information for each error type
- is contained in three bits of the integer. If we print it in base 8, we
- can see what treatment is set for "invalid", "under", "over", and
- "divide" (in that order). The printed string can be interpreted with
- * 0 : 'ignore'
- * 1 : 'warn'
- * 2 : 'raise'
- * 3 : 'call'
- * 4 : 'print'
- * 5 : 'log'
- See Also
- --------
- geterrobj, seterr, geterr, seterrcall, geterrcall
- getbufsize, setbufsize
- Notes
- -----
- For complete documentation of the types of floating-point exceptions and
- treatment options, see `seterr`.
- Examples
- --------
- >>> old_errobj = np.geterrobj() # first get the defaults
- >>> old_errobj
- [8192, 521, None]
- >>> def err_handler(type, flag):
- ... print("Floating point error (%s), with flag %s" % (type, flag))
- ...
- >>> new_errobj = [20000, 12, err_handler]
- >>> np.seterrobj(new_errobj)
- >>> np.base_repr(12, 8) # int for divide=4 ('print') and over=1 ('warn')
- '14'
- >>> np.geterr()
- {'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'}
- >>> np.geterrcall() is err_handler
- True
- """)
- ##############################################################################
- #
- # compiled_base functions
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'add_docstring',
- """
- add_docstring(obj, docstring)
- Add a docstring to a built-in obj if possible.
- If the obj already has a docstring raise a RuntimeError
- If this routine does not know how to add a docstring to the object
- raise a TypeError
- """)
- add_newdoc('numpy.core.umath', '_add_newdoc_ufunc',
- """
- add_ufunc_docstring(ufunc, new_docstring)
- Replace the docstring for a ufunc with new_docstring.
- This method will only work if the current docstring for
- the ufunc is NULL. (At the C level, i.e. when ufunc->doc is NULL.)
- Parameters
- ----------
- ufunc : numpy.ufunc
- A ufunc whose current doc is NULL.
- new_docstring : string
- The new docstring for the ufunc.
- Notes
- -----
- This method allocates memory for new_docstring on
- the heap. Technically this creates a mempory leak, since this
- memory will not be reclaimed until the end of the program
- even if the ufunc itself is removed. However this will only
- be a problem if the user is repeatedly creating ufuncs with
- no documentation, adding documentation via add_newdoc_ufunc,
- and then throwing away the ufunc.
- """)
- add_newdoc('numpy.core.multiarray', '_set_madvise_hugepage',
- """
- _set_madvise_hugepage(enabled: bool) -> bool
- Set or unset use of ``madvise (2)`` MADV_HUGEPAGE support when
- allocating the array data. Returns the previously set value.
- See `global_state` for more information.
- """)
- add_newdoc('numpy.core._multiarray_tests', 'format_float_OSprintf_g',
- """
- format_float_OSprintf_g(val, precision)
- Print a floating point scalar using the system's printf function,
- equivalent to:
- printf("%.*g", precision, val);
- for half/float/double, or replacing 'g' by 'Lg' for longdouble. This
- method is designed to help cross-validate the format_float_* methods.
- Parameters
- ----------
- val : python float or numpy floating scalar
- Value to format.
- precision : non-negative integer, optional
- Precision given to printf.
- Returns
- -------
- rep : string
- The string representation of the floating point value
- See Also
- --------
- format_float_scientific
- format_float_positional
- """)
- ##############################################################################
- #
- # Documentation for ufunc attributes and methods
- #
- ##############################################################################
- ##############################################################################
- #
- # ufunc object
- #
- ##############################################################################
- add_newdoc('numpy.core', 'ufunc',
- """
- Functions that operate element by element on whole arrays.
- To see the documentation for a specific ufunc, use `info`. For
- example, ``np.info(np.sin)``. Because ufuncs are written in C
- (for speed) and linked into Python with NumPy's ufunc facility,
- Python's help() function finds this page whenever help() is called
- on a ufunc.
- A detailed explanation of ufuncs can be found in the docs for :ref:`ufuncs`.
- Calling ufuncs:
- ===============
- op(*x[, out], where=True, **kwargs)
- Apply `op` to the arguments `*x` elementwise, broadcasting the arguments.
- The broadcasting rules are:
- * Dimensions of length 1 may be prepended to either array.
- * Arrays may be repeated along dimensions of length 1.
- Parameters
- ----------
- *x : array_like
- Input arrays.
- out : ndarray, None, or tuple of ndarray and None, optional
- Alternate array object(s) in which to put the result; if provided, it
- must have a shape that the inputs broadcast to. A tuple of arrays
- (possible only as a keyword argument) must have length equal to the
- number of outputs; use None for uninitialized outputs to be
- allocated by the ufunc.
- where : array_like, optional
- This condition is broadcast over the input. At locations where the
- condition is True, the `out` array will be set to the ufunc result.
- Elsewhere, the `out` array will retain its original value.
- Note that if an uninitialized `out` array is created via the default
- ``out=None``, locations within it where the condition is False will
- remain uninitialized.
- **kwargs
- For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.
- Returns
- -------
- r : ndarray or tuple of ndarray
- `r` will have the shape that the arrays in `x` broadcast to; if `out` is
- provided, it will be returned. If not, `r` will be allocated and
- may contain uninitialized values. If the function has more than one
- output, then the result will be a tuple of arrays.
- """)
- ##############################################################################
- #
- # ufunc attributes
- #
- ##############################################################################
- add_newdoc('numpy.core', 'ufunc', ('identity',
- """
- The identity value.
- Data attribute containing the identity element for the ufunc, if it has one.
- If it does not, the attribute value is None.
- Examples
- --------
- >>> np.add.identity
- 0
- >>> np.multiply.identity
- 1
- >>> np.power.identity
- 1
- >>> print(np.exp.identity)
- None
- """))
- add_newdoc('numpy.core', 'ufunc', ('nargs',
- """
- The number of arguments.
- Data attribute containing the number of arguments the ufunc takes, including
- optional ones.
- Notes
- -----
- Typically this value will be one more than what you might expect because all
- ufuncs take the optional "out" argument.
- Examples
- --------
- >>> np.add.nargs
- 3
- >>> np.multiply.nargs
- 3
- >>> np.power.nargs
- 3
- >>> np.exp.nargs
- 2
- """))
- add_newdoc('numpy.core', 'ufunc', ('nin',
- """
- The number of inputs.
- Data attribute containing the number of arguments the ufunc treats as input.
- Examples
- --------
- >>> np.add.nin
- 2
- >>> np.multiply.nin
- 2
- >>> np.power.nin
- 2
- >>> np.exp.nin
- 1
- """))
- add_newdoc('numpy.core', 'ufunc', ('nout',
- """
- The number of outputs.
- Data attribute containing the number of arguments the ufunc treats as output.
- Notes
- -----
- Since all ufuncs can take output arguments, this will always be (at least) 1.
- Examples
- --------
- >>> np.add.nout
- 1
- >>> np.multiply.nout
- 1
- >>> np.power.nout
- 1
- >>> np.exp.nout
- 1
- """))
- add_newdoc('numpy.core', 'ufunc', ('ntypes',
- """
- The number of types.
- The number of numerical NumPy types - of which there are 18 total - on which
- the ufunc can operate.
- See Also
- --------
- numpy.ufunc.types
- Examples
- --------
- >>> np.add.ntypes
- 18
- >>> np.multiply.ntypes
- 18
- >>> np.power.ntypes
- 17
- >>> np.exp.ntypes
- 7
- >>> np.remainder.ntypes
- 14
- """))
- add_newdoc('numpy.core', 'ufunc', ('types',
- """
- Returns a list with types grouped input->output.
- Data attribute listing the data-type "Domain-Range" groupings the ufunc can
- deliver. The data-types are given using the character codes.
- See Also
- --------
- numpy.ufunc.ntypes
- Examples
- --------
- >>> np.add.types
- ['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l',
- 'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D',
- 'GG->G', 'OO->O']
- >>> np.multiply.types
- ['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l',
- 'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D',
- 'GG->G', 'OO->O']
- >>> np.power.types
- ['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L',
- 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D', 'GG->G',
- 'OO->O']
- >>> np.exp.types
- ['f->f', 'd->d', 'g->g', 'F->F', 'D->D', 'G->G', 'O->O']
- >>> np.remainder.types
- ['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L',
- 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'OO->O']
- """))
- add_newdoc('numpy.core', 'ufunc', ('signature',
- """
- Definition of the core elements a generalized ufunc operates on.
- The signature determines how the dimensions of each input/output array
- are split into core and loop dimensions:
- 1. Each dimension in the signature is matched to a dimension of the
- corresponding passed-in array, starting from the end of the shape tuple.
- 2. Core dimensions assigned to the same label in the signature must have
- exactly matching sizes, no broadcasting is performed.
- 3. The core dimensions are removed from all inputs and the remaining
- dimensions are broadcast together, defining the loop dimensions.
- Notes
- -----
- Generalized ufuncs are used internally in many linalg functions, and in
- the testing suite; the examples below are taken from these.
- For ufuncs that operate on scalars, the signature is None, which is
- equivalent to '()' for every argument.
- Examples
- --------
- >>> np.core.umath_tests.matrix_multiply.signature
- '(m,n),(n,p)->(m,p)'
- >>> np.linalg._umath_linalg.det.signature
- '(m,m)->()'
- >>> np.add.signature is None
- True # equivalent to '(),()->()'
- """))
- ##############################################################################
- #
- # ufunc methods
- #
- ##############################################################################
- add_newdoc('numpy.core', 'ufunc', ('reduce',
- """
- reduce(a, axis=0, dtype=None, out=None, keepdims=False, initial=<no value>, where=True)
- Reduces `a`'s dimension by one, by applying ufunc along one axis.
- Let :math:`a.shape = (N_0, ..., N_i, ..., N_{M-1})`. Then
- :math:`ufunc.reduce(a, axis=i)[k_0, ..,k_{i-1}, k_{i+1}, .., k_{M-1}]` =
- the result of iterating `j` over :math:`range(N_i)`, cumulatively applying
- ufunc to each :math:`a[k_0, ..,k_{i-1}, j, k_{i+1}, .., k_{M-1}]`.
- For a one-dimensional array, reduce produces results equivalent to:
- ::
- r = op.identity # op = ufunc
- for i in range(len(A)):
- r = op(r, A[i])
- return r
- For example, add.reduce() is equivalent to sum().
- Parameters
- ----------
- a : array_like
- The array to act on.
- axis : None or int or tuple of ints, optional
- Axis or axes along which a reduction is performed.
- The default (`axis` = 0) is perform a reduction over the first
- dimension of the input array. `axis` may be negative, in
- which case it counts from the last to the first axis.
- .. versionadded:: 1.7.0
- If this is None, a reduction is performed over all the axes.
- If this is a tuple of ints, a reduction is performed on multiple
- axes, instead of a single axis or all the axes as before.
- For operations which are either not commutative or not associative,
- doing a reduction over multiple axes is not well-defined. The
- ufuncs do not currently raise an exception in this case, but will
- likely do so in the future.
- dtype : data-type code, optional
- The type used to represent the intermediate results. Defaults
- to the data-type of the output array if this is provided, or
- the data-type of the input array if no output array is provided.
- out : ndarray, None, or tuple of ndarray and None, optional
- A location into which the result is stored. If not provided or None,
- a freshly-allocated array is returned. For consistency with
- ``ufunc.__call__``, if given as a keyword, this may be wrapped in a
- 1-element tuple.
- .. versionchanged:: 1.13.0
- Tuples are allowed for keyword argument.
- keepdims : bool, optional
- If this is set to True, the axes which are reduced are left
- in the result as dimensions with size one. With this option,
- the result will broadcast correctly against the original `arr`.
- .. versionadded:: 1.7.0
- initial : scalar, optional
- The value with which to start the reduction.
- If the ufunc has no identity or the dtype is object, this defaults
- to None - otherwise it defaults to ufunc.identity.
- If ``None`` is given, the first element of the reduction is used,
- and an error is thrown if the reduction is empty.
- .. versionadded:: 1.15.0
- where : array_like of bool, optional
- A boolean array which is broadcasted to match the dimensions
- of `a`, and selects elements to include in the reduction. Note
- that for ufuncs like ``minimum`` that do not have an identity
- defined, one has to pass in also ``initial``.
- .. versionadded:: 1.17.0
- Returns
- -------
- r : ndarray
- The reduced array. If `out` was supplied, `r` is a reference to it.
- Examples
- --------
- >>> np.multiply.reduce([2,3,5])
- 30
- A multi-dimensional array example:
- >>> X = np.arange(8).reshape((2,2,2))
- >>> X
- array([[[0, 1],
- [2, 3]],
- [[4, 5],
- [6, 7]]])
- >>> np.add.reduce(X, 0)
- array([[ 4, 6],
- [ 8, 10]])
- >>> np.add.reduce(X) # confirm: default axis value is 0
- array([[ 4, 6],
- [ 8, 10]])
- >>> np.add.reduce(X, 1)
- array([[ 2, 4],
- [10, 12]])
- >>> np.add.reduce(X, 2)
- array([[ 1, 5],
- [ 9, 13]])
- You can use the ``initial`` keyword argument to initialize the reduction
- with a different value, and ``where`` to select specific elements to include:
- >>> np.add.reduce([10], initial=5)
- 15
- >>> np.add.reduce(np.ones((2, 2, 2)), axis=(0, 2), initial=10)
- array([14., 14.])
- >>> a = np.array([10., np.nan, 10])
- >>> np.add.reduce(a, where=~np.isnan(a))
- 20.0
- Allows reductions of empty arrays where they would normally fail, i.e.
- for ufuncs without an identity.
- >>> np.minimum.reduce([], initial=np.inf)
- inf
- >>> np.minimum.reduce([[1., 2.], [3., 4.]], initial=10., where=[True, False])
- array([ 1., 10.])
- >>> np.minimum.reduce([])
- Traceback (most recent call last):
- ...
- ValueError: zero-size array to reduction operation minimum which has no identity
- """))
- add_newdoc('numpy.core', 'ufunc', ('accumulate',
- """
- accumulate(array, axis=0, dtype=None, out=None)
- Accumulate the result of applying the operator to all elements.
- For a one-dimensional array, accumulate produces results equivalent to::
- r = np.empty(len(A))
- t = op.identity # op = the ufunc being applied to A's elements
- for i in range(len(A)):
- t = op(t, A[i])
- r[i] = t
- return r
- For example, add.accumulate() is equivalent to np.cumsum().
- For a multi-dimensional array, accumulate is applied along only one
- axis (axis zero by default; see Examples below) so repeated use is
- necessary if one wants to accumulate over multiple axes.
- Parameters
- ----------
- array : array_like
- The array to act on.
- axis : int, optional
- The axis along which to apply the accumulation; default is zero.
- dtype : data-type code, optional
- The data-type used to represent the intermediate results. Defaults
- to the data-type of the output array if such is provided, or the
- the data-type of the input array if no output array is provided.
- out : ndarray, None, or tuple of ndarray and None, optional
- A location into which the result is stored. If not provided or None,
- a freshly-allocated array is returned. For consistency with
- ``ufunc.__call__``, if given as a keyword, this may be wrapped in a
- 1-element tuple.
- .. versionchanged:: 1.13.0
- Tuples are allowed for keyword argument.
- Returns
- -------
- r : ndarray
- The accumulated values. If `out` was supplied, `r` is a reference to
- `out`.
- Examples
- --------
- 1-D array examples:
- >>> np.add.accumulate([2, 3, 5])
- array([ 2, 5, 10])
- >>> np.multiply.accumulate([2, 3, 5])
- array([ 2, 6, 30])
- 2-D array examples:
- >>> I = np.eye(2)
- >>> I
- array([[1., 0.],
- [0., 1.]])
- Accumulate along axis 0 (rows), down columns:
- >>> np.add.accumulate(I, 0)
- array([[1., 0.],
- [1., 1.]])
- >>> np.add.accumulate(I) # no axis specified = axis zero
- array([[1., 0.],
- [1., 1.]])
- Accumulate along axis 1 (columns), through rows:
- >>> np.add.accumulate(I, 1)
- array([[1., 1.],
- [0., 1.]])
- """))
- add_newdoc('numpy.core', 'ufunc', ('reduceat',
- """
- reduceat(a, indices, axis=0, dtype=None, out=None)
- Performs a (local) reduce with specified slices over a single axis.
- For i in ``range(len(indices))``, `reduceat` computes
- ``ufunc.reduce(a[indices[i]:indices[i+1]])``, which becomes the i-th
- generalized "row" parallel to `axis` in the final result (i.e., in a
- 2-D array, for example, if `axis = 0`, it becomes the i-th row, but if
- `axis = 1`, it becomes the i-th column). There are three exceptions to this:
- * when ``i = len(indices) - 1`` (so for the last index),
- ``indices[i+1] = a.shape[axis]``.
- * if ``indices[i] >= indices[i + 1]``, the i-th generalized "row" is
- simply ``a[indices[i]]``.
- * if ``indices[i] >= len(a)`` or ``indices[i] < 0``, an error is raised.
- The shape of the output depends on the size of `indices`, and may be
- larger than `a` (this happens if ``len(indices) > a.shape[axis]``).
- Parameters
- ----------
- a : array_like
- The array to act on.
- indices : array_like
- Paired indices, comma separated (not colon), specifying slices to
- reduce.
- axis : int, optional
- The axis along which to apply the reduceat.
- dtype : data-type code, optional
- The type used to represent the intermediate results. Defaults
- to the data type of the output array if this is provided, or
- the data type of the input array if no output array is provided.
- out : ndarray, None, or tuple of ndarray and None, optional
- A location into which the result is stored. If not provided or None,
- a freshly-allocated array is returned. For consistency with
- ``ufunc.__call__``, if given as a keyword, this may be wrapped in a
- 1-element tuple.
- .. versionchanged:: 1.13.0
- Tuples are allowed for keyword argument.
- Returns
- -------
- r : ndarray
- The reduced values. If `out` was supplied, `r` is a reference to
- `out`.
- Notes
- -----
- A descriptive example:
- If `a` is 1-D, the function `ufunc.accumulate(a)` is the same as
- ``ufunc.reduceat(a, indices)[::2]`` where `indices` is
- ``range(len(array) - 1)`` with a zero placed
- in every other element:
- ``indices = zeros(2 * len(a) - 1)``, ``indices[1::2] = range(1, len(a))``.
- Don't be fooled by this attribute's name: `reduceat(a)` is not
- necessarily smaller than `a`.
- Examples
- --------
- To take the running sum of four successive values:
- >>> np.add.reduceat(np.arange(8),[0,4, 1,5, 2,6, 3,7])[::2]
- array([ 6, 10, 14, 18])
- A 2-D example:
- >>> x = np.linspace(0, 15, 16).reshape(4,4)
- >>> x
- array([[ 0., 1., 2., 3.],
- [ 4., 5., 6., 7.],
- [ 8., 9., 10., 11.],
- [12., 13., 14., 15.]])
- ::
- # reduce such that the result has the following five rows:
- # [row1 + row2 + row3]
- # [row4]
- # [row2]
- # [row3]
- # [row1 + row2 + row3 + row4]
- >>> np.add.reduceat(x, [0, 3, 1, 2, 0])
- array([[12., 15., 18., 21.],
- [12., 13., 14., 15.],
- [ 4., 5., 6., 7.],
- [ 8., 9., 10., 11.],
- [24., 28., 32., 36.]])
- ::
- # reduce such that result has the following two columns:
- # [col1 * col2 * col3, col4]
- >>> np.multiply.reduceat(x, [0, 3], 1)
- array([[ 0., 3.],
- [ 120., 7.],
- [ 720., 11.],
- [2184., 15.]])
- """))
- add_newdoc('numpy.core', 'ufunc', ('outer',
- r"""
- outer(A, B, **kwargs)
- Apply the ufunc `op` to all pairs (a, b) with a in `A` and b in `B`.
- Let ``M = A.ndim``, ``N = B.ndim``. Then the result, `C`, of
- ``op.outer(A, B)`` is an array of dimension M + N such that:
- .. math:: C[i_0, ..., i_{M-1}, j_0, ..., j_{N-1}] =
- op(A[i_0, ..., i_{M-1}], B[j_0, ..., j_{N-1}])
- For `A` and `B` one-dimensional, this is equivalent to::
- r = empty(len(A),len(B))
- for i in range(len(A)):
- for j in range(len(B)):
- r[i,j] = op(A[i], B[j]) # op = ufunc in question
- Parameters
- ----------
- A : array_like
- First array
- B : array_like
- Second array
- kwargs : any
- Arguments to pass on to the ufunc. Typically `dtype` or `out`.
- Returns
- -------
- r : ndarray
- Output array
- See Also
- --------
- numpy.outer : A less powerful version of ``np.multiply.outer``
- that `ravel`\ s all inputs to 1D. This exists
- primarily for compatibility with old code.
- tensordot : ``np.tensordot(a, b, axes=((), ()))`` and
- ``np.multiply.outer(a, b)`` behave same for all
- dimensions of a and b.
- Examples
- --------
- >>> np.multiply.outer([1, 2, 3], [4, 5, 6])
- array([[ 4, 5, 6],
- [ 8, 10, 12],
- [12, 15, 18]])
- A multi-dimensional example:
- >>> A = np.array([[1, 2, 3], [4, 5, 6]])
- >>> A.shape
- (2, 3)
- >>> B = np.array([[1, 2, 3, 4]])
- >>> B.shape
- (1, 4)
- >>> C = np.multiply.outer(A, B)
- >>> C.shape; C
- (2, 3, 1, 4)
- array([[[[ 1, 2, 3, 4]],
- [[ 2, 4, 6, 8]],
- [[ 3, 6, 9, 12]]],
- [[[ 4, 8, 12, 16]],
- [[ 5, 10, 15, 20]],
- [[ 6, 12, 18, 24]]]])
- """))
- add_newdoc('numpy.core', 'ufunc', ('at',
- """
- at(a, indices, b=None)
- Performs unbuffered in place operation on operand 'a' for elements
- specified by 'indices'. For addition ufunc, this method is equivalent to
- ``a[indices] += b``, except that results are accumulated for elements that
- are indexed more than once. For example, ``a[[0,0]] += 1`` will only
- increment the first element once because of buffering, whereas
- ``add.at(a, [0,0], 1)`` will increment the first element twice.
- .. versionadded:: 1.8.0
- Parameters
- ----------
- a : array_like
- The array to perform in place operation on.
- indices : array_like or tuple
- Array like index object or slice object for indexing into first
- operand. If first operand has multiple dimensions, indices can be a
- tuple of array like index objects or slice objects.
- b : array_like
- Second operand for ufuncs requiring two operands. Operand must be
- broadcastable over first operand after indexing or slicing.
- Examples
- --------
- Set items 0 and 1 to their negative values:
- >>> a = np.array([1, 2, 3, 4])
- >>> np.negative.at(a, [0, 1])
- >>> a
- array([-1, -2, 3, 4])
- Increment items 0 and 1, and increment item 2 twice:
- >>> a = np.array([1, 2, 3, 4])
- >>> np.add.at(a, [0, 1, 2, 2], 1)
- >>> a
- array([2, 3, 5, 4])
- Add items 0 and 1 in first array to second array,
- and store results in first array:
- >>> a = np.array([1, 2, 3, 4])
- >>> b = np.array([1, 2])
- >>> np.add.at(a, [0, 1], b)
- >>> a
- array([2, 4, 3, 4])
- """))
- ##############################################################################
- #
- # Documentation for dtype attributes and methods
- #
- ##############################################################################
- ##############################################################################
- #
- # dtype object
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'dtype',
- """
- dtype(obj, align=False, copy=False)
- Create a data type object.
- A numpy array is homogeneous, and contains elements described by a
- dtype object. A dtype object can be constructed from different
- combinations of fundamental numeric types.
- Parameters
- ----------
- obj
- Object to be converted to a data type object.
- align : bool, optional
- Add padding to the fields to match what a C compiler would output
- for a similar C-struct. Can be ``True`` only if `obj` is a dictionary
- or a comma-separated string. If a struct dtype is being created,
- this also sets a sticky alignment flag ``isalignedstruct``.
- copy : bool, optional
- Make a new copy of the data-type object. If ``False``, the result
- may just be a reference to a built-in data-type object.
- See also
- --------
- result_type
- Examples
- --------
- Using array-scalar type:
- >>> np.dtype(np.int16)
- dtype('int16')
- Structured type, one field name 'f1', containing int16:
- >>> np.dtype([('f1', np.int16)])
- dtype([('f1', '<i2')])
- Structured type, one field named 'f1', in itself containing a structured
- type with one field:
- >>> np.dtype([('f1', [('f1', np.int16)])])
- dtype([('f1', [('f1', '<i2')])])
- Structured type, two fields: the first field contains an unsigned int, the
- second an int32:
- >>> np.dtype([('f1', np.uint64), ('f2', np.int32)])
- dtype([('f1', '<u8'), ('f2', '<i4')])
- Using array-protocol type strings:
- >>> np.dtype([('a','f8'),('b','S10')])
- dtype([('a', '<f8'), ('b', 'S10')])
- Using comma-separated field formats. The shape is (2,3):
- >>> np.dtype("i4, (2,3)f8")
- dtype([('f0', '<i4'), ('f1', '<f8', (2, 3))])
- Using tuples. ``int`` is a fixed type, 3 the field's shape. ``void``
- is a flexible type, here of size 10:
- >>> np.dtype([('hello',(np.int64,3)),('world',np.void,10)])
- dtype([('hello', '<i8', (3,)), ('world', 'V10')])
- Subdivide ``int16`` into 2 ``int8``'s, called x and y. 0 and 1 are
- the offsets in bytes:
- >>> np.dtype((np.int16, {'x':(np.int8,0), 'y':(np.int8,1)}))
- dtype((numpy.int16, [('x', 'i1'), ('y', 'i1')]))
- Using dictionaries. Two fields named 'gender' and 'age':
- >>> np.dtype({'names':['gender','age'], 'formats':['S1',np.uint8]})
- dtype([('gender', 'S1'), ('age', 'u1')])
- Offsets in bytes, here 0 and 25:
- >>> np.dtype({'surname':('S25',0),'age':(np.uint8,25)})
- dtype([('surname', 'S25'), ('age', 'u1')])
- """)
- ##############################################################################
- #
- # dtype attributes
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'dtype', ('alignment',
- """
- The required alignment (bytes) of this data-type according to the compiler.
- More information is available in the C-API section of the manual.
- Examples
- --------
- >>> x = np.dtype('i4')
- >>> x.alignment
- 4
- >>> x = np.dtype(float)
- >>> x.alignment
- 8
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('byteorder',
- """
- A character indicating the byte-order of this data-type object.
- One of:
- === ==============
- '=' native
- '<' little-endian
- '>' big-endian
- '|' not applicable
- === ==============
- All built-in data-type objects have byteorder either '=' or '|'.
- Examples
- --------
- >>> dt = np.dtype('i2')
- >>> dt.byteorder
- '='
- >>> # endian is not relevant for 8 bit numbers
- >>> np.dtype('i1').byteorder
- '|'
- >>> # or ASCII strings
- >>> np.dtype('S2').byteorder
- '|'
- >>> # Even if specific code is given, and it is native
- >>> # '=' is the byteorder
- >>> import sys
- >>> sys_is_le = sys.byteorder == 'little'
- >>> native_code = sys_is_le and '<' or '>'
- >>> swapped_code = sys_is_le and '>' or '<'
- >>> dt = np.dtype(native_code + 'i2')
- >>> dt.byteorder
- '='
- >>> # Swapped code shows up as itself
- >>> dt = np.dtype(swapped_code + 'i2')
- >>> dt.byteorder == swapped_code
- True
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('char',
- """A unique character code for each of the 21 different built-in types.
- Examples
- --------
- >>> x = np.dtype(float)
- >>> x.char
- 'd'
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('descr',
- """
- `__array_interface__` description of the data-type.
- The format is that required by the 'descr' key in the
- `__array_interface__` attribute.
- Warning: This attribute exists specifically for `__array_interface__`,
- and passing it directly to `np.dtype` will not accurately reconstruct
- some dtypes (e.g., scalar and subarray dtypes).
- Examples
- --------
- >>> x = np.dtype(float)
- >>> x.descr
- [('', '<f8')]
- >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
- >>> dt.descr
- [('name', '<U16'), ('grades', '<f8', (2,))]
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('fields',
- """
- Dictionary of named fields defined for this data type, or ``None``.
- The dictionary is indexed by keys that are the names of the fields.
- Each entry in the dictionary is a tuple fully describing the field::
- (dtype, offset[, title])
- Offset is limited to C int, which is signed and usually 32 bits.
- If present, the optional title can be any object (if it is a string
- or unicode then it will also be a key in the fields dictionary,
- otherwise it's meta-data). Notice also that the first two elements
- of the tuple can be passed directly as arguments to the ``ndarray.getfield``
- and ``ndarray.setfield`` methods.
- See Also
- --------
- ndarray.getfield, ndarray.setfield
- Examples
- --------
- >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
- >>> print(dt.fields)
- {'grades': (dtype(('float64',(2,))), 16), 'name': (dtype('|S16'), 0)}
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('flags',
- """
- Bit-flags describing how this data type is to be interpreted.
- Bit-masks are in `numpy.core.multiarray` as the constants
- `ITEM_HASOBJECT`, `LIST_PICKLE`, `ITEM_IS_POINTER`, `NEEDS_INIT`,
- `NEEDS_PYAPI`, `USE_GETITEM`, `USE_SETITEM`. A full explanation
- of these flags is in C-API documentation; they are largely useful
- for user-defined data-types.
- The following example demonstrates that operations on this particular
- dtype requires Python C-API.
- Examples
- --------
- >>> x = np.dtype([('a', np.int32, 8), ('b', np.float64, 6)])
- >>> x.flags
- 16
- >>> np.core.multiarray.NEEDS_PYAPI
- 16
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('hasobject',
- """
- Boolean indicating whether this dtype contains any reference-counted
- objects in any fields or sub-dtypes.
- Recall that what is actually in the ndarray memory representing
- the Python object is the memory address of that object (a pointer).
- Special handling may be required, and this attribute is useful for
- distinguishing data types that may contain arbitrary Python objects
- and data-types that won't.
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('isbuiltin',
- """
- Integer indicating how this dtype relates to the built-in dtypes.
- Read-only.
- = ========================================================================
- 0 if this is a structured array type, with fields
- 1 if this is a dtype compiled into numpy (such as ints, floats etc)
- 2 if the dtype is for a user-defined numpy type
- A user-defined type uses the numpy C-API machinery to extend
- numpy to handle a new array type. See
- :ref:`user.user-defined-data-types` in the NumPy manual.
- = ========================================================================
- Examples
- --------
- >>> dt = np.dtype('i2')
- >>> dt.isbuiltin
- 1
- >>> dt = np.dtype('f8')
- >>> dt.isbuiltin
- 1
- >>> dt = np.dtype([('field1', 'f8')])
- >>> dt.isbuiltin
- 0
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('isnative',
- """
- Boolean indicating whether the byte order of this dtype is native
- to the platform.
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('isalignedstruct',
- """
- Boolean indicating whether the dtype is a struct which maintains
- field alignment. This flag is sticky, so when combining multiple
- structs together, it is preserved and produces new dtypes which
- are also aligned.
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('itemsize',
- """
- The element size of this data-type object.
- For 18 of the 21 types this number is fixed by the data-type.
- For the flexible data-types, this number can be anything.
- Examples
- --------
- >>> arr = np.array([[1, 2], [3, 4]])
- >>> arr.dtype
- dtype('int64')
- >>> arr.itemsize
- 8
- >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
- >>> dt.itemsize
- 80
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('kind',
- """
- A character code (one of 'biufcmMOSUV') identifying the general kind of data.
- = ======================
- b boolean
- i signed integer
- u unsigned integer
- f floating-point
- c complex floating-point
- m timedelta
- M datetime
- O object
- S (byte-)string
- U Unicode
- V void
- = ======================
- Examples
- --------
- >>> dt = np.dtype('i4')
- >>> dt.kind
- 'i'
- >>> dt = np.dtype('f8')
- >>> dt.kind
- 'f'
- >>> dt = np.dtype([('field1', 'f8')])
- >>> dt.kind
- 'V'
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('name',
- """
- A bit-width name for this data-type.
- Un-sized flexible data-type objects do not have this attribute.
- Examples
- --------
- >>> x = np.dtype(float)
- >>> x.name
- 'float64'
- >>> x = np.dtype([('a', np.int32, 8), ('b', np.float64, 6)])
- >>> x.name
- 'void640'
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('names',
- """
- Ordered list of field names, or ``None`` if there are no fields.
- The names are ordered according to increasing byte offset. This can be
- used, for example, to walk through all of the named fields in offset order.
- Examples
- --------
- >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
- >>> dt.names
- ('name', 'grades')
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('num',
- """
- A unique number for each of the 21 different built-in types.
- These are roughly ordered from least-to-most precision.
- Examples
- --------
- >>> dt = np.dtype(str)
- >>> dt.num
- 19
- >>> dt = np.dtype(float)
- >>> dt.num
- 12
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('shape',
- """
- Shape tuple of the sub-array if this data type describes a sub-array,
- and ``()`` otherwise.
- Examples
- --------
- >>> dt = np.dtype(('i4', 4))
- >>> dt.shape
- (4,)
- >>> dt = np.dtype(('i4', (2, 3)))
- >>> dt.shape
- (2, 3)
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('ndim',
- """
- Number of dimensions of the sub-array if this data type describes a
- sub-array, and ``0`` otherwise.
- .. versionadded:: 1.13.0
- Examples
- --------
- >>> x = np.dtype(float)
- >>> x.ndim
- 0
- >>> x = np.dtype((float, 8))
- >>> x.ndim
- 1
- >>> x = np.dtype(('i4', (3, 4)))
- >>> x.ndim
- 2
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('str',
- """The array-protocol typestring of this data-type object."""))
- add_newdoc('numpy.core.multiarray', 'dtype', ('subdtype',
- """
- Tuple ``(item_dtype, shape)`` if this `dtype` describes a sub-array, and
- None otherwise.
- The *shape* is the fixed shape of the sub-array described by this
- data type, and *item_dtype* the data type of the array.
- If a field whose dtype object has this attribute is retrieved,
- then the extra dimensions implied by *shape* are tacked on to
- the end of the retrieved array.
- See Also
- --------
- dtype.base
- Examples
- --------
- >>> x = numpy.dtype('8f')
- >>> x.subdtype
- (dtype('float32'), (8,))
- >>> x = numpy.dtype('i2')
- >>> x.subdtype
- >>>
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('base',
- """
- Returns dtype for the base element of the subarrays,
- regardless of their dimension or shape.
- See Also
- --------
- dtype.subdtype
- Examples
- --------
- >>> x = numpy.dtype('8f')
- >>> x.base
- dtype('float32')
- >>> x = numpy.dtype('i2')
- >>> x.base
- dtype('int16')
- """))
- add_newdoc('numpy.core.multiarray', 'dtype', ('type',
- """The type object used to instantiate a scalar of this data-type."""))
- ##############################################################################
- #
- # dtype methods
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'dtype', ('newbyteorder',
- """
- newbyteorder(new_order='S')
- Return a new dtype with a different byte order.
- Changes are also made in all fields and sub-arrays of the data type.
- Parameters
- ----------
- new_order : string, optional
- Byte order to force; a value from the byte order specifications
- below. The default value ('S') results in swapping the current
- byte order. `new_order` codes can be any of:
- * 'S' - swap dtype from current to opposite endian
- * {'<', 'L'} - little endian
- * {'>', 'B'} - big endian
- * {'=', 'N'} - native order
- * {'|', 'I'} - ignore (no change to byte order)
- The code does a case-insensitive check on the first letter of
- `new_order` for these alternatives. For example, any of '>'
- or 'B' or 'b' or 'brian' are valid to specify big-endian.
- Returns
- -------
- new_dtype : dtype
- New dtype object with the given change to the byte order.
- Notes
- -----
- Changes are also made in all fields and sub-arrays of the data type.
- Examples
- --------
- >>> import sys
- >>> sys_is_le = sys.byteorder == 'little'
- >>> native_code = sys_is_le and '<' or '>'
- >>> swapped_code = sys_is_le and '>' or '<'
- >>> native_dt = np.dtype(native_code+'i2')
- >>> swapped_dt = np.dtype(swapped_code+'i2')
- >>> native_dt.newbyteorder('S') == swapped_dt
- True
- >>> native_dt.newbyteorder() == swapped_dt
- True
- >>> native_dt == swapped_dt.newbyteorder('S')
- True
- >>> native_dt == swapped_dt.newbyteorder('=')
- True
- >>> native_dt == swapped_dt.newbyteorder('N')
- True
- >>> native_dt == native_dt.newbyteorder('|')
- True
- >>> np.dtype('<i2') == native_dt.newbyteorder('<')
- True
- >>> np.dtype('<i2') == native_dt.newbyteorder('L')
- True
- >>> np.dtype('>i2') == native_dt.newbyteorder('>')
- True
- >>> np.dtype('>i2') == native_dt.newbyteorder('B')
- True
- """))
- ##############################################################################
- #
- # Datetime-related Methods
- #
- ##############################################################################
- add_newdoc('numpy.core.multiarray', 'busdaycalendar',
- """
- busdaycalendar(weekmask='1111100', holidays=None)
- A business day calendar object that efficiently stores information
- defining valid days for the busday family of functions.
- The default valid days are Monday through Friday ("business days").
- A busdaycalendar object can be specified with any set of weekly
- valid days, plus an optional "holiday" dates that always will be invalid.
- Once a busdaycalendar object is created, the weekmask and holidays
- cannot be modified.
- .. versionadded:: 1.7.0
- Parameters
- ----------
- weekmask : str or array_like of bool, optional
- A seven-element array indicating which of Monday through Sunday are
- valid days. May be specified as a length-seven list or array, like
- [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
- like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
- weekdays, optionally separated by white space. Valid abbreviations
- are: Mon Tue Wed Thu Fri Sat Sun
- holidays : array_like of datetime64[D], optional
- An array of dates to consider as invalid dates, no matter which
- weekday they fall upon. Holiday dates may be specified in any
- order, and NaT (not-a-time) dates are ignored. This list is
- saved in a normalized form that is suited for fast calculations
- of valid days.
- Returns
- -------
- out : busdaycalendar
- A business day calendar object containing the specified
- weekmask and holidays values.
- See Also
- --------
- is_busday : Returns a boolean array indicating valid days.
- busday_offset : Applies an offset counted in valid days.
- busday_count : Counts how many valid days are in a half-open date range.
- Attributes
- ----------
- Note: once a busdaycalendar object is created, you cannot modify the
- weekmask or holidays. The attributes return copies of internal data.
- weekmask : (copy) seven-element array of bool
- holidays : (copy) sorted array of datetime64[D]
- Examples
- --------
- >>> # Some important days in July
- ... bdd = np.busdaycalendar(
- ... holidays=['2011-07-01', '2011-07-04', '2011-07-17'])
- >>> # Default is Monday to Friday weekdays
- ... bdd.weekmask
- array([ True, True, True, True, True, False, False])
- >>> # Any holidays already on the weekend are removed
- ... bdd.holidays
- array(['2011-07-01', '2011-07-04'], dtype='datetime64[D]')
- """)
- add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('weekmask',
- """A copy of the seven-element boolean mask indicating valid days."""))
- add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('holidays',
- """A copy of the holiday array indicating additional invalid days."""))
- add_newdoc('numpy.core.multiarray', 'normalize_axis_index',
- """
- normalize_axis_index(axis, ndim, msg_prefix=None)
- Normalizes an axis index, `axis`, such that is a valid positive index into
- the shape of array with `ndim` dimensions. Raises an AxisError with an
- appropriate message if this is not possible.
- Used internally by all axis-checking logic.
- .. versionadded:: 1.13.0
- Parameters
- ----------
- axis : int
- The un-normalized index of the axis. Can be negative
- ndim : int
- The number of dimensions of the array that `axis` should be normalized
- against
- msg_prefix : str
- A prefix to put before the message, typically the name of the argument
- Returns
- -------
- normalized_axis : int
- The normalized axis index, such that `0 <= normalized_axis < ndim`
- Raises
- ------
- AxisError
- If the axis index is invalid, when `-ndim <= axis < ndim` is false.
- Examples
- --------
- >>> normalize_axis_index(0, ndim=3)
- 0
- >>> normalize_axis_index(1, ndim=3)
- 1
- >>> normalize_axis_index(-1, ndim=3)
- 2
- >>> normalize_axis_index(3, ndim=3)
- Traceback (most recent call last):
- ...
- AxisError: axis 3 is out of bounds for array of dimension 3
- >>> normalize_axis_index(-4, ndim=3, msg_prefix='axes_arg')
- Traceback (most recent call last):
- ...
- AxisError: axes_arg: axis -4 is out of bounds for array of dimension 3
- """)
- add_newdoc('numpy.core.multiarray', 'datetime_data',
- """
- datetime_data(dtype, /)
- Get information about the step size of a date or time type.
- The returned tuple can be passed as the second argument of `numpy.datetime64` and
- `numpy.timedelta64`.
- Parameters
- ----------
- dtype : dtype
- The dtype object, which must be a `datetime64` or `timedelta64` type.
- Returns
- -------
- unit : str
- The :ref:`datetime unit <arrays.dtypes.dateunits>` on which this dtype
- is based.
- count : int
- The number of base units in a step.
- Examples
- --------
- >>> dt_25s = np.dtype('timedelta64[25s]')
- >>> np.datetime_data(dt_25s)
- ('s', 25)
- >>> np.array(10, dt_25s).astype('timedelta64[s]')
- array(250, dtype='timedelta64[s]')
- The result can be used to construct a datetime that uses the same units
- as a timedelta
- >>> np.datetime64('2010', np.datetime_data(dt_25s))
- numpy.datetime64('2010-01-01T00:00:00','25s')
- """)
- ##############################################################################
- #
- # Documentation for `generic` attributes and methods
- #
- ##############################################################################
- add_newdoc('numpy.core.numerictypes', 'generic',
- """
- Base class for numpy scalar types.
- Class from which most (all?) numpy scalar types are derived. For
- consistency, exposes the same API as `ndarray`, despite many
- consequent attributes being either "get-only," or completely irrelevant.
- This is the class from which it is strongly suggested users should derive
- custom scalar types.
- """)
- # Attributes
- add_newdoc('numpy.core.numerictypes', 'generic', ('T',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class so as to
- provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('base',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class so as to
- a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('data',
- """Pointer to start of data."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('dtype',
- """Get array data-descriptor."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('flags',
- """The integer value of flags."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('flat',
- """A 1-D view of the scalar."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('imag',
- """The imaginary part of the scalar."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('itemsize',
- """The length of one element in bytes."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('nbytes',
- """The length of the scalar in bytes."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('ndim',
- """The number of array dimensions."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('real',
- """The real part of the scalar."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('shape',
- """Tuple of array dimensions."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('size',
- """The number of elements in the gentype."""))
- add_newdoc('numpy.core.numerictypes', 'generic', ('strides',
- """Tuple of bytes steps in each dimension."""))
- # Methods
- add_newdoc('numpy.core.numerictypes', 'generic', ('all',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('any',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('argmax',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('argmin',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('argsort',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('astype',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('byteswap',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class so as to
- provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('choose',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('clip',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('compress',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('conjugate',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('copy',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('cumprod',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('cumsum',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('diagonal',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('dump',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('dumps',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('fill',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('flatten',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('getfield',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('item',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('itemset',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('max',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('mean',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('min',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('newbyteorder',
- """
- newbyteorder(new_order='S')
- Return a new `dtype` with a different byte order.
- Changes are also made in all fields and sub-arrays of the data type.
- The `new_order` code can be any from the following:
- * 'S' - swap dtype from current to opposite endian
- * {'<', 'L'} - little endian
- * {'>', 'B'} - big endian
- * {'=', 'N'} - native order
- * {'|', 'I'} - ignore (no change to byte order)
- Parameters
- ----------
- new_order : str, optional
- Byte order to force; a value from the byte order specifications
- above. The default value ('S') results in swapping the current
- byte order. The code does a case-insensitive check on the first
- letter of `new_order` for the alternatives above. For example,
- any of 'B' or 'b' or 'biggish' are valid to specify big-endian.
- Returns
- -------
- new_dtype : dtype
- New `dtype` object with the given change to the byte order.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('nonzero',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('prod',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('ptp',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('put',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('ravel',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('repeat',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('reshape',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('resize',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('round',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('searchsorted',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('setfield',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('setflags',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class so as to
- provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('sort',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('squeeze',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('std',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('sum',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('swapaxes',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('take',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('tofile',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('tolist',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('tostring',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('trace',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('transpose',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('var',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- add_newdoc('numpy.core.numerictypes', 'generic', ('view',
- """
- Not implemented (virtual attribute)
- Class generic exists solely to derive numpy scalars from, and possesses,
- albeit unimplemented, all the attributes of the ndarray class
- so as to provide a uniform API.
- See also the corresponding attribute of the derived class of interest.
- """))
- ##############################################################################
- #
- # Documentation for scalar type abstract base classes in type hierarchy
- #
- ##############################################################################
- add_newdoc('numpy.core.numerictypes', 'number',
- """
- Abstract base class of all numeric scalar types.
- """)
- add_newdoc('numpy.core.numerictypes', 'integer',
- """
- Abstract base class of all integer scalar types.
- """)
- add_newdoc('numpy.core.numerictypes', 'signedinteger',
- """
- Abstract base class of all signed integer scalar types.
- """)
- add_newdoc('numpy.core.numerictypes', 'unsignedinteger',
- """
- Abstract base class of all unsigned integer scalar types.
- """)
- add_newdoc('numpy.core.numerictypes', 'inexact',
- """
- Abstract base class of all numeric scalar types with a (potentially)
- inexact representation of the values in its range, such as
- floating-point numbers.
- """)
- add_newdoc('numpy.core.numerictypes', 'floating',
- """
- Abstract base class of all floating-point scalar types.
- """)
- add_newdoc('numpy.core.numerictypes', 'complexfloating',
- """
- Abstract base class of all complex number scalar types that are made up of
- floating-point numbers.
- """)
- add_newdoc('numpy.core.numerictypes', 'flexible',
- """
- Abstract base class of all scalar types without predefined length.
- The actual size of these types depends on the specific `np.dtype`
- instantiation.
- """)
- add_newdoc('numpy.core.numerictypes', 'character',
- """
- Abstract base class of all character string scalar types.
- """)
- ##############################################################################
- #
- # Documentation for concrete scalar classes
- #
- ##############################################################################
- def numeric_type_aliases(aliases):
- def type_aliases_gen():
- for alias, doc in aliases:
- try:
- alias_type = getattr(_numerictypes, alias)
- except AttributeError:
- # The set of aliases that actually exist varies between platforms
- pass
- else:
- yield (alias_type, alias, doc)
- return list(type_aliases_gen())
- possible_aliases = numeric_type_aliases([
- ('int8', '8-bit signed integer (-128 to 127)'),
- ('int16', '16-bit signed integer (-32768 to 32767)'),
- ('int32', '32-bit signed integer (-2147483648 to 2147483647)'),
- ('int64', '64-bit signed integer (-9223372036854775808 to 9223372036854775807)'),
- ('intp', 'Signed integer large enough to fit pointer, compatible with C ``intptr_t``'),
- ('uint8', '8-bit unsigned integer (0 to 255)'),
- ('uint16', '16-bit unsigned integer (0 to 65535)'),
- ('uint32', '32-bit unsigned integer (0 to 4294967295)'),
- ('uint64', '64-bit unsigned integer (0 to 18446744073709551615)'),
- ('uintp', 'Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``'),
- ('float16', '16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa'),
- ('float32', '32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits mantissa'),
- ('float64', '64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa'),
- ('float96', '96-bit extended-precision floating-point number type'),
- ('float128', '128-bit extended-precision floating-point number type'),
- ('complex64', 'Complex number type composed of 2 32-bit-precision floating-point numbers'),
- ('complex128', 'Complex number type composed of 2 64-bit-precision floating-point numbers'),
- ('complex192', 'Complex number type composed of 2 96-bit extended-precision floating-point numbers'),
- ('complex256', 'Complex number type composed of 2 128-bit extended-precision floating-point numbers'),
- ])
- def add_newdoc_for_scalar_type(obj, fixed_aliases, doc):
- o = getattr(_numerictypes, obj)
- character_code = dtype(o).char
- canonical_name_doc = "" if obj == o.__name__ else "Canonical name: ``np.{}``.\n ".format(obj)
- alias_doc = ''.join("Alias: ``np.{}``.\n ".format(alias) for alias in fixed_aliases)
- alias_doc += ''.join("Alias *on this platform*: ``np.{}``: {}.\n ".format(alias, doc)
- for (alias_type, alias, doc) in possible_aliases if alias_type is o)
- docstring = """
- {doc}
- Character code: ``'{character_code}'``.
- {canonical_name_doc}{alias_doc}
- """.format(doc=doc.strip(), character_code=character_code,
- canonical_name_doc=canonical_name_doc, alias_doc=alias_doc)
- add_newdoc('numpy.core.numerictypes', obj, docstring)
- add_newdoc_for_scalar_type('bool_', ['bool8'],
- """
- Boolean type (True or False), stored as a byte.
- """)
- add_newdoc_for_scalar_type('byte', [],
- """
- Signed integer type, compatible with C ``char``.
- """)
- add_newdoc_for_scalar_type('short', [],
- """
- Signed integer type, compatible with C ``short``.
- """)
- add_newdoc_for_scalar_type('intc', [],
- """
- Signed integer type, compatible with C ``int``.
- """)
- add_newdoc_for_scalar_type('int_', [],
- """
- Signed integer type, compatible with Python `int` anc C ``long``.
- """)
- add_newdoc_for_scalar_type('longlong', [],
- """
- Signed integer type, compatible with C ``long long``.
- """)
- add_newdoc_for_scalar_type('ubyte', [],
- """
- Unsigned integer type, compatible with C ``unsigned char``.
- """)
- add_newdoc_for_scalar_type('ushort', [],
- """
- Unsigned integer type, compatible with C ``unsigned short``.
- """)
- add_newdoc_for_scalar_type('uintc', [],
- """
- Unsigned integer type, compatible with C ``unsigned int``.
- """)
- add_newdoc_for_scalar_type('uint', [],
- """
- Unsigned integer type, compatible with C ``unsigned long``.
- """)
- add_newdoc_for_scalar_type('ulonglong', [],
- """
- Signed integer type, compatible with C ``unsigned long long``.
- """)
- add_newdoc_for_scalar_type('half', [],
- """
- Half-precision floating-point number type.
- """)
- add_newdoc_for_scalar_type('single', [],
- """
- Single-precision floating-point number type, compatible with C ``float``.
- """)
- add_newdoc_for_scalar_type('double', ['float_'],
- """
- Double-precision floating-point number type, compatible with Python `float`
- and C ``double``.
- """)
- add_newdoc_for_scalar_type('longdouble', ['longfloat'],
- """
- Extended-precision floating-point number type, compatible with C
- ``long double`` but not necessarily with IEEE 754 quadruple-precision.
- """)
- add_newdoc_for_scalar_type('csingle', ['singlecomplex'],
- """
- Complex number type composed of two single-precision floating-point
- numbers.
- """)
- add_newdoc_for_scalar_type('cdouble', ['cfloat', 'complex_'],
- """
- Complex number type composed of two double-precision floating-point
- numbers, compatible with Python `complex`.
- """)
- add_newdoc_for_scalar_type('clongdouble', ['clongfloat', 'longcomplex'],
- """
- Complex number type composed of two extended-precision floating-point
- numbers.
- """)
- add_newdoc_for_scalar_type('object_', [],
- """
- Any Python object.
- """)
- # TODO: work out how to put this on the base class, np.floating
- for float_name in ('half', 'single', 'double', 'longdouble'):
- add_newdoc('numpy.core.numerictypes', float_name, ('as_integer_ratio',
- """
- {ftype}.as_integer_ratio() -> (int, int)
- Return a pair of integers, whose ratio is exactly equal to the original
- floating point number, and with a positive denominator.
- Raise OverflowError on infinities and a ValueError on NaNs.
- >>> np.{ftype}(10.0).as_integer_ratio()
- (10, 1)
- >>> np.{ftype}(0.0).as_integer_ratio()
- (0, 1)
- >>> np.{ftype}(-.25).as_integer_ratio()
- (-1, 4)
- """.format(ftype=float_name)))
|