Repository: cnuernber/libpython-clj Branch: master Commit: 97dff5cdf75c Files: 101 Total size: 1.6 MB Directory structure: gitextract_0j37h__8/ ├── .github/ │ ├── FUNDING.yml │ └── workflows/ │ └── test.yml ├── .gitignore ├── .gitmodules ├── .travis.yml ├── CHANGELOG.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── codegen-test/ │ ├── README.md │ ├── deps.edn │ ├── scripts/ │ │ ├── compile │ │ └── run │ └── src/ │ ├── code/ │ │ ├── codegen.clj │ │ └── main.clj │ └── python/ │ └── numpy.clj ├── deps.edn ├── dockerfiles/ │ ├── CondaDockerfile │ ├── Py38Dockerfile │ └── Py39Dockerfile ├── docs/ │ ├── Usage.html │ ├── css/ │ │ └── default.css │ ├── embedded.html │ ├── environments.html │ ├── highlight/ │ │ └── solarized-light.css │ ├── index.html │ ├── js/ │ │ └── page_effects.js │ ├── libpython-clj.python.html │ ├── libpython-clj.python.np-array.html │ ├── libpython-clj.require.html │ ├── libpython-clj2.codegen.html │ ├── libpython-clj2.embedded.html │ ├── libpython-clj2.java-api.html │ ├── libpython-clj2.python.class.html │ ├── libpython-clj2.python.html │ ├── libpython-clj2.python.np-array.html │ ├── libpython-clj2.require.html │ ├── new-to-clojure.html │ ├── scopes-and-gc.html │ └── slicing.html ├── questions/ │ ├── 32bit.txt │ ├── 64bit.txt │ ├── compile32.sh │ ├── compile64.sh │ ├── ssizet_size.cpp │ └── typeobject.cpp ├── resources/ │ └── clj-kondo.exports/ │ └── clj-python/ │ └── libpython-clj/ │ ├── config.edn │ └── hooks/ │ └── libpython_clj/ │ ├── jna/ │ │ └── base/ │ │ └── def_pylib_fn.clj │ └── require/ │ └── import_python.clj ├── scripts/ │ ├── build-conda-docker │ ├── build-py38-docker │ ├── build-py39-docker │ ├── conda-repl │ ├── deploy │ ├── install │ ├── py38-repl │ ├── run-conda-docker │ ├── run-py38-docker │ ├── run-py39-docker │ └── run-tests ├── src/ │ └── libpython_clj2/ │ ├── codegen.clj │ ├── embedded.clj │ ├── java_api.clj │ ├── metadata.clj │ ├── python/ │ │ ├── base.clj │ │ ├── bridge_as_jvm.clj │ │ ├── bridge_as_python.clj │ │ ├── class.clj │ │ ├── copy.clj │ │ ├── dechunk_map.clj │ │ ├── ffi.clj │ │ ├── fn.clj │ │ ├── gc.clj │ │ ├── info.clj │ │ ├── io_redirect.clj │ │ ├── jvm_handle.clj │ │ ├── np_array.clj │ │ ├── protocols.clj │ │ ├── windows.clj │ │ └── with.clj │ ├── python.clj │ ├── require.clj │ └── sugar.clj ├── test/ │ └── libpython_clj2/ │ ├── classes_test.clj │ ├── codegen_test.clj │ ├── ffi_test.clj │ ├── fncall_test.clj │ ├── iter_gen_seq_test.clj │ ├── java_api_test.clj │ ├── numpy_test.clj │ ├── python_test.clj │ ├── require_python_test.clj │ ├── stress_test.clj │ └── sugar_test.clj ├── testcode/ │ └── __init__.py └── topics/ ├── Usage.md ├── embedded.md ├── environments.md ├── new-to-clojure.md ├── scopes-and-gc.md └── slicing.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/FUNDING.yml ================================================ github: cnuernber ================================================ FILE: .github/workflows/test.yml ================================================ name: test on: push: branches: - master paths-ignore: - '**/README.md' - '**/CHANGELOG.md' pull_request: jobs: unit-test: runs-on: ${{matrix.os}} strategy: fail-fast: false matrix: os: [macos-latest, ubuntu-latest, windows-latest] jdk: [19, 21, 25] python-version: ["3.9", "3.11","3.12","3.13","3.14"] steps: - uses: actions/checkout@v3 - name: Set up JDK ${{ matrix.jdk }} uses: actions/setup-java@v4 with: java-version: ${{ matrix.jdk }} distribution: temurin - name: Install Clojure uses: DeLaGuardo/setup-clojure@11.0 with: cli: 1.11.1.1347 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v6 with: python-version: ${{ matrix.python-version }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install numpy --no-cache-dir - name: Run tests (jdk<17) if: ${{ matrix.jdk < 17 }} run: | clojure -M:test - name: Run tests (jdk>=17) if: ${{ matrix.jdk >= 17 }} run: | clojure -M:jdk-${{matrix.jdk}}:test ================================================ FILE: .gitignore ================================================ target /classes /checkouts profiles.clj pom.xml pom.xml.asc *.jar *.class /.lein-* .nrepl-port .hgignore .hg/ __pycache__ .cpcache/ cpython a.out *.pom *.pom.asc /.idea *.iml .lsp .clj-kondo pregen-ffi-test ================================================ FILE: .gitmodules ================================================ ================================================ FILE: .travis.yml ================================================ language: clojure dist: bionic lein: 2.9.1 sudo: required before_install: - sudo apt-get -y install python3 python3-pip - sudo python3 -mpip install setuptools - sudo python3 -mpip install numpy - curl -O https://download.clojure.org/install/linux-install-1.10.2.796.sh - chmod +x linux-install-1.10.2.796.sh - sudo ./linux-install-1.10.2.796.sh - clojure -Sdescribe addons: apt: update: true install: clojure -Sdescribe script: clojure -M:test cache: directories: - "$HOME/.m2" ================================================ FILE: CHANGELOG.md ================================================ # Time for a ChangeLog! ## 2.026 * Faster string conversion from c->jvm for large strings. * Fix for https://github.com/techascent/tech.ml.dataset/issues/437 ## 2.025 * [Stop using nio-buffer conversion for ->string](https://github.com/clj-python/libpython-clj/blob/master/src/libpython_clj2/python/ffi.clj#L795) * [PR - Handle conversion of more types in ->jvm](https://github.com/clj-python/libpython-clj/pull/251) * Fix issue with locating python dll on MS-Windows [#246](https://github.com/clj-python/libpython-clj/issues/246). ## 2.024 * large dtype-next/hamf upgrade. * fix for call-attr (it was broken when using keywords). ## 2.023 * pre/post hooks for python initialization ## 2.022 * Support for JDK-19. Still uses JNA as the FFI provider but libpython-clj now works out of the box when using JDK-19. ## 2.021 * Add support for a `python.edn` file, see `libpython-clj2.python/initialize!` documentation ## 2.020 * Better support for running with `-Dlibpython_clj.manual_gil=true` - `with-manual-gil`. Addresses [issue 221](https://github.com/clj-python/libpython-clj/issues/221). ## 2.019 * Upgrade to clojure 1.11 as development version. * Upgrade dtype-next to get rid of 1.11 warnings (and for unary min,max). * Upgrade jna to latest version for greater x-platform support. ## 2.017 * Tested AOT and codegen of numpy namespace to ensure it is loadable and works as expected. * This fixed an issue with the codegen system. ## 2.016 * Upgrade dtype-next to latest version. This version of dtype-next comes with it's own java-api so you can integrate deeper into the zero-copy pathways. ## 2.015 * java API has stabilized. * [GILLocker](https://clj-python.github.io/libpython-clj/libpython-clj2.java-api.html#var--GILLocker) - an auto-closeable pathway so you case use Java's try-with-resources or Clojure's with-open. ## 2.013 * Lots of changes and releases ironing out a java api with a user. This is close but not completely there yet so expect the java api to change a bit more. * [make-fastcallable](https://clj-python.github.io/libpython-clj/libpython-clj2.python.html#var-make-fastcallable) ## 2.000 * You can now create instance functions that accept both positional and keyword arguments - libpython-clj2.python/make-kw-instance-fn. See test at test/libpython-clj2.python.classes-test. * latest dtype-next - see documentation for tech.v3.datatype/set-value!. * Fix for using ffi on arm64 platforms. ## 2.00-beta-22 * Fix to PR-166 - strings in docs weren't properly escaped. ## 2.00-beta-20 * [Issue 167] - `py.` fails in a go-loop. * [PR 166](https://github.com/clj-python/libpython-clj/pull/166) - Fix codegen for special double values such as Nan and infinity. * [PR 165](https://github.com/clj-python/libpython-clj/pull/165) - remove codegen builtins and numpy due to codegen pathway not being stable and potential version conflicts between e.g. numpy versions. ## 2.00-beta-19 * [issue 126](https://github.com/clj-python/libpython-clj/issues/126) - Python maps sometimes fail to destructure. ## 2.00-beta-18 * Additional fix for 162 to allow booleans to be considered primitives and be output inline. * Experimental fix for [issue 164](https://github.com/clj-python/libpython-clj/issues/164) - Unsigned int64 fails with `OverflowError: int too big to convert`. ## 2.00-beta-17 * Almost fix fo [issue 163](https://github.com/clj-python/libpython-clj/issues/163) - codegen fails with JVM primitives. ## 2.00-beta-16 * Fix for [issue 162](https://github.com/clj-python/libpython-clj/issues/162) - many things failing when using JDK-16. Note there is now a :jdk-16 alias in deps.edn that shows how to use libpython-clj with JDK-16. ## 2.00-beta-15 * Fix for [issue 160](https://github.com/clj-python/libpython-clj/issues/160) - ->python has to realize lazy seqs. * Remove camel-snake-kebab as direct dependency; it comes in via dtype-next. ## 2.00-beta-13 * Update to dtype-next to support graal native static ffi and library generation. * Update to dtype-next to have correct definitions of ptr-t, offset-t, and size-t types. ## 2.00-beta-12 * Small refinements around embedding and documentation. ## 2.00-beta-11 * Major improvements to get libpython-clj v2 to work as robustly as v1 did across several operating systems. * First release that includes embedded functionality (!!). See the embedded topic for more details. ## 2.00-beta-8 * Add back in dynamically searching for libraries based on `java.library.path`. ## 2.00-beta-7 * Upgrade to dtype-next to ensure that JNA is the preferred FFI framework. * Re-introduce java.library.path shenanigans in order to support pyenv type systems. ## 2.00-beta-6 * Revert initialize! back to v1 optional argument style. ## 2.00-beta-5 * Fix codox document generation issue. * Added a document on environments. ## 2.00-beta-4 * [static namespace generation](https://clj-python.github.io/libpython-clj/libpython-clj2.codegen.html#var-write-namespace.21) - Generate AOT-safe clojure code that will dynamically find the symbol and cache it upon first call. ## 2.00-beta-3 * Fixes to allow Conda to work - [cnuernber/facial-rec](https://github.com/cnuernber/facial-rec) lives again!! ## 2.00-beta-2 * Fix for [numpy.all returns false](https://github.com/clj-python/libpython-clj/issues/148) ## 2.00-beta-1 * Major upgrade of tech system - moved to dtype-next. This release is only compatible with tech.ml.dataset versions 5.+. There are many changes but there should be very few user visible ones. Please see [cnuernber/dtype-next](https://cnuernber.github.io/dtype-next/) for more information. This brings a total refactor removing about 1/2 the code, 32bit support and and JDK-16 support. ## 1.45 * tech.datatype - 5.0 release ## 1.43 * `tech.datatype` - latest version to work with `tech.ml.dataset`. ## 1.42 * `tech.datatype` - latest version to work with `tech.ml.dataset`. ## 1.41 * `tech.datatype` - latest version to work with `tech.ml.dataset`. ## 1.40 * `tech.datatype` fixed bug in argsort. ## 1.39 * `tech.datatype` upgrade to version that supports datetime types. ## 1.38-SNAPSHOT * `tech.datatype` is upgrade to 5.0 (!!). ## 1.37 * Update to tech.datatype 4.88 - much faster group-by, lots of small improvements. ## 1.37 * Fix for metadata generation of sys module that was failing. This needs a deeper fix. * Race condition and stability fix. * `deps.edn` now supported in parallel with `project.clj` ## 1.36 * clojure.core.async upgrade ## 1.35 * [Examples are now done by gigasquid](https://github.com/gigasquid/libpython-clj-examples) * [datafy/nav](https://clojure.github.io/clojure/branch-master/clojure.datafy-api.html) are now extensible for custom Python objects. Extend `libpython-clj.require/pydafy` and `libpython-clj.require/pynav` respectively with the symbol of class you want to extend. See respective docstrings for details. * bugfix -- python.str now loaded by `import-python` ## 1.34 * Skipped due to build system issues. ## 1.33 * Better [windows anaconda support](https://github.com/cnuernber/libpython-clj/pull/67) thanks to [orolle](https://github.com/orolle). * Moved to PyGILState* functions for GIL management. This mainly due to [FongHou](https://github.com/cnuernber/libpython-clj/commits?author=FongHou) in PRs [here](https://github.com/cnuernber/libpython-clj/pull/64) and [here](https://github.com/cnuernber/libpython-clj/pull/65). * **BREAKING CHANGE** `require-python` now respects prefix lists -- unfortunately, the previous syntax was incorrect. ```clojure ;; WRONG (syntax version < 1.33) (require-python '(os math)) ``` would be equivalent to ```clojure ;; (do (require-python 'os) (require-python 'math)) ``` the correct syntax for this SHOULD have been ```clojure (require-python 'os 'math) ``` 1.33 fixes this mistake, and provides support for prefix lists, for example: ```clojure (require-python '[builtins :as python] '(builtins [list :as python.list] [dict :as python.dict] [tuple :as python.tuple] [set :as python.set] [frozenset :as python.frozenset])) ``` (**Note**: this is done for you by the function `libpython-clj.require/import-python`) This fix brought to you by [jjtolton](https://github.com/jjtolton). ## 1.32 * DecRef now happens cooperatively in python thread. We used to use separate threads in order to do decrement the refcount on objects that aren't reachable any more. Now it happens at the end of the `with-gil` macro and thus it is possible to have all python access confined to a single thread if this is desired for stability. It is also quite a bit faster as the GIL is captured once and all decrefs happen after that. * Major performance and stability enhancements. 1. Doubled down on single-interpreter design. This simplified some important aspects and led to a bit of perf gain. 2. Implemented JNA [DirectMapping](https://github.com/java-native-access/jna/blob/master/www/DirectMapping.md) for quite a few hotspots found via profiling some simple examples. Lots of people helped out with this (John Collins, Tom Poole (joinr)). * Python executables can now be specified directly using the syntax ```clojure (py/initialize! :python-executable ) ``` where **executable** can be a system installation of Python such as `"python3"`, `"python3.7"`; it can also be a fully qualified path such as `"/usr/bin/python3.7"`; or any Python executable along your discoverable system path. * Python virtual environments can now be used instead of system installations! This has been tested on Linux/Ubuntu variants with virtual environments installed with ```bash virtualenv -p $(which ) env ``` and then invoked using ```clojure (py/initialize! :python-executable "/abs/path/to/env/bin/python") ``` Tested on Python 3.6.8 and Python 3.7. **WARNING**: This is suitable for casual hacking and exploratory development -- however, at this time, we still strongly recommend using Docker and a system installation of Python in production environments. * **breaking change** (and remediation): `require-python` no longer automatically binds the Python module to the Clojure the namespace symbol. If you wish to bind the module to the namespace symbol, you need to use the `:bind-ns` flag. Example: ```clojure (require-python 'requests) ;;=> nil requests ;;=> throws Exception (require-python '[requests :bind-ns]) ;;=> nil (py.. requests (get "https://www.google.com) -content (decode "latin-1)) ;; works ``` * Python method helper syntax for programmatic passing of maps to satisfy `*args`, `**kwargs` situations on the `py.` family of macros. Two new macros have been introduced to address this ```clojure (py* obj method args) (py* obj method args kwargs) (py** obj method kwargs) (py** obj method arg1 arg2 arg3 ... argN kwargs) ``` and the `py..` syntax has been extended to accomodate these conventions as well. ```clojure (py.. obj (*method args)) (py.. obj (*method args kwargs)) (py.. obj (**method kwargs)) (py.. obj (**method arg1 arg2 arg3 ... argN kwargs)) ``` ### Bugs Fixed: * [attribute calls with argument given in map](https://github.com/cnuernber/libpython-clj/issues/46) * [allow specification of python executable](https://github.com/cnuernber/libpython-clj/issues/52) * [difference in calling conventions leads to strange behavior in pandas](https://github.com/cnuernber/libpython-clj/issues/50) with [screencast of fix](https://drive.google.com/file/d/1PTXzWqNaRAiIDDZWqkeffIK2KESRWSRh/view?usp=sharing) * [Allow single threaded use of Python](https://github.com/cnuernber/libpython-clj/issues/48) * [Simplify interpreter design for only one interpreter](https://github.com/cnuernber/libpython-clj/issues/47) ## 1.31 * Python objects are now datafy-able and nav-igable. `require-python` is now rebuilt using datafy. * `py.`, `py.-`, and `py..` added to the `libpython-clj` APIs to allow method/attribute access more consistent with idiomatic Clojure forms. ## 1.30 This release is a big one. With finalizing `require-python` we have a clear way to use Python in daily use and make it look good in normal Clojure usage. There is a demo of [facial recognition](https://github.com/cnuernber/facial-rec) using some of the best open systems for doing this; this demo would absolutely not be possible without this library due to the extensive use of numpy and cython to implement the face detection. We can now interact with even very complex Python systems with roughly the same performance as a pure Python system. #### Finalized `require-python` Lots of work put in to make the `require-python` pathway work with classes and some serious refactoring overall. #### Better Numpy Support * Most of the datatype libraries math operators supported by numpy objects (+,-,etc). * Numpy objects can be used in datatype library functions (like `copy`, `make-container`) and work in optimized ways. ```clojure libpython-clj.python.numpy-test> (def test-ary (py/$a np-mod array (->> (range 9) (partition 3) (mapv vec)))) #'libpython-clj.python.numpy-test/test-ary libpython-clj.python.numpy-test> test-ary [[0 1 2] [3 4 5] [6 7 8]] libpython-clj.python.numpy-test> (dfn/+ test-ary 2) [[ 2 3 4] [ 5 6 7] [ 8 9 10]] libpython-clj.python.numpy-test> (dfn/> test-ary 4) [[False False False] [False False True] [ True True True]] ``` #### Bugs Fixed * Support for java character <-> py string * Fixed potential crash related to use of delay mechanism and stack based gc. * Added logging to complain loudly if refcounts appear to be bad. ## 1.29 * Found/fixed issue with `->jvm` and large Python dictionaries. ## 1.28 * `(range 5)` - Clojure ranges <-> Python ranges when possible. * bridged types derive from `collections.abc.*` so that they pass instance checks in libraries that are checking for generic types. * Really interesting unit test for [generators, ranges and sequences](test/libpython_clj/iter_gen_seq_test.clj). ## 1.27 * Fixed bug where `(as-python {:is_train false})` results in a dictionary with a none value instead of a false value. This was found through hours of debugging why mxnet's forward function call was returning different values in Clojure than in Python. ## 1.26 * [python startup work](https://github.com/cnuernber/libpython-clj/commit/16da3d885f29bde59ea219c9438b9d3654387971) * [python generators & clojure transducers](https://github.com/cnuernber/libpython-clj/pull/27) * [requre-python reload fix](https://github.com/cnuernber/libpython-clj/pull/24) * Bugfix with `require-python` :reload semantics. ## 1.25 Fixed (with tests) major issue with `require-python`. ## 1.24 Clojure's range is now respected in two different ways: * `(range)` - bridges to a Python iterable * `(range 5)` - copies to a Python list ## 1.23 Equals, hashcode, nice default `.toString` of Python types: ```clojure user> (require '[libpython-clj.python :as py]) nil user> (def test-tuple (py/->py-tuple [1 2])) #'user/test-tuple user> (require '[libpython-clj.require :refer [require-python]]) nil user> (require-python '[builtins :as bt]) nil user> (bt/type test-tuple) builtins.tuple user> test-tuple (1, 2) user> (def new-tuple (py/->py-tuple [3 4])) #'user/new-tuple user> (= test-tuple new-tuple) false user> (= test-tuple (py/->py-tuple [1 2])) true user> (.hashCode test-tuple) 2130570162 user> (.hashCode (py/->py-tuple [1 2])) 2130570162 user> (require-python '[numpy :as np]) nil user> (def np-ary (np/array [1 2 3])) #'user/np-ary user> np-ary [1 2 3] user> (bt/type np-ary) numpy.ndarray user> (py/python-type *1) :type ``` ## 1.22 Working to make more Python environments work out of the box. Currently have a testcase for conda working in a clean install of a docker container. There is now a new method: `libpython-clj.python.interpreter/detect-startup-info` that attempts call `python3-config --prefix` and `python3 --version` in order to automagically configure the Python library. ## 1.21 Bugfix release. Passing infinite sequences to Python functions was causing a hang as libpython-clj attempted to copy the sequence. The current calling convention does a shallow copy of things that are list-like or map-like, while bridging things that are iterable or don't fall into the above categories. This exposed a bug that caused reference counting to be subtly wrong when Python iterated through a bridged object. And that was my life for a day. ## 1.20 With too many huge things we had to skip a few versions! #### require-python `require-python` works like require but it works on Python modules. `require-python` dynamically loads the module and exports it's symbols into a Clojure namespace. There are many options available for this pathway. This implements a big step towards embedding Python in Clojure in a simple, clear, and easy to use way. One important thing to consider is the require has a `:reload:` option to allow you to actively develop a Python module and test it via Clojure. This excellent work was in large part done by [James Tolton](https://github.com/jjtolton). * [require-python-test](test/libpython_clj/require_python_test.clj) #### Clojure-defined Python classes You can now extend a tuple of Python classes (or implement a new one). This system allows, among many things, us to use frameworks that use derivation as part of their public API. Please see [classes-test](test/libpython_clj/classes_test.clj) for a documented example of a simple pathway through the new API. Note that if you use vanilla `->py-fn` functions as part of the class definition you won't get access to the `self` object. #### Bugfixes A general stability bugfix was made that was involved in the interoperation of Clojure functions within Python. Clojure functions weren't currently adding a refcount to their return values. ## 1.16 Fixed a bug where the system would load multiple Python libraries, not stopping after the first valid library loaded. There are two ways to control the system's Python library loading mechanism: 1. Pass in a library name in `initialize!` 2. `alter-var-root` the list of libraries in `libpython-clj.jna.base` before calling `initialize!`. ## 1.15 Moar syntax sugar -- ```clojure user> (py/$. numpy linspace) user> (py/$.. numpy random shuffle) ``` ## 1.14 libpython-clj now searches for several shared libraries instead of being hardcoded to just one of them. Because of this, there is now: ```clojure libpython-clj.jna.base/*python-library-names* ``` This is a sequence of library names that will be tried in order. You can also pass in the desired library name as part of the `initialize!` call and only this name will be tried. ================================================ FILE: CONTRIBUTING.md ================================================ # Contributing Contributions are welcome and come in many forms. Let's be polite, professional, and keep this a place we want to be. ## Issues Issues are best if they come with a test. The exact version of python you are running and your operating system, clojure version, java version, etc. if relevant will save everyone time who reviews your issue. Consider some form of: 1. What I did 1. What I expected to happen 1. What actually happened ## Failing Tests A public branch with failing tests of things that you would like to work is also a great idea. Or just more tests. Things like: >> are java lists and maps actually substitutable for python lists and dicts in python code and vice versa are most likely ripe areas for tests and will greatly help with expectations and code portability. ## PR's Shorter the PR, the less back and forth there will be and the more likely to be accepted. ## Documentation Documentation is key but needs to be accurate and brief. Incorrect documentation is worse than no documentation. ================================================ FILE: LICENSE ================================================ Eclipse Public License - v 2.0 THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. 1. DEFINITIONS "Contribution" means: a) in the case of the initial Contributor, the initial content Distributed under this Agreement, and b) in the case of each subsequent Contributor: i) changes to the Program, and ii) additions to the Program; where such changes and/or additions to the Program originate from and are Distributed by that particular Contributor. A Contribution "originates" from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include changes or additions to the Program that are not Modified Works. "Contributor" means any person or entity that Distributes the Program. "Licensed Patents" mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program. "Program" means the Contributions Distributed in accordance with this Agreement. "Recipient" means anyone who receives the Program under this Agreement or any Secondary License (as applicable), including Contributors. "Derivative Works" shall mean any work, whether in Source Code or other form, that is based on (or derived from) the Program and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. "Modified Works" shall mean any work in Source Code or other form that results from an addition to, deletion from, or modification of the contents of the Program, including, for purposes of clarity any new file in Source Code form that contains any contents of the Program. Modified Works shall not include works that contain only declarations, interfaces, types, classes, structures, or files of the Program solely in each case in order to link to, bind by name, or subclass the Program or Modified Works thereof. "Distribute" means the acts of a) distributing or b) making available in any manner that enables the transfer of a copy. "Source Code" means the form of a Program preferred for making modifications, including but not limited to software source code, documentation source, and configuration files. "Secondary License" means either the GNU General Public License, Version 2.0, or any later versions of that license, including any exceptions or additional permissions as identified by the initial Contributor. 2. GRANT OF RIGHTS a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, Distribute and sublicense the Contribution of such Contributor, if any, and such Derivative Works. b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in Source Code or other form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder. c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to Distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program. d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement. e) Notwithstanding the terms of any Secondary License, no Contributor makes additional grants to any Recipient (other than those set forth in this Agreement) as a result of such Recipient's receipt of the Program under the terms of a Secondary License (if permitted under the terms of Section 3). 3. REQUIREMENTS 3.1 If a Contributor Distributes the Program in any form, then: a) the Program must also be made available as Source Code, in accordance with section 3.2, and the Contributor must accompany the Program with a statement that the Source Code for the Program is available under this Agreement, and informs Recipients how to obtain it in a reasonable manner on or through a medium customarily used for software exchange; and b) the Contributor may Distribute the Program under a license different than this Agreement, provided that such license: i) effectively disclaims on behalf of all other Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose; ii) effectively excludes on behalf of all other Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; iii) does not attempt to limit or alter the recipients' rights in the Source Code under section 3.2; and iv) requires any subsequent distribution of the Program by any party to be under a license that satisfies the requirements of this section 3. 3.2 When the Program is Distributed as Source Code: a) it must be made available under this Agreement, or if the Program (i) is combined with other material in a separate file or files made available under a Secondary License, and (ii) the initial Contributor attached to the Source Code the notice described in Exhibit A of this Agreement, then the Program may be made available under the terms of such Secondary Licenses, and b) a copy of this Agreement must be included with each copy of the Program. 3.3 Contributors may not remove or alter any copyright, patent, trademark, attribution notices, disclaimers of warranty, or limitations of liability ("notices") contained within the Program from any copy of the Program which they Distribute, provided that Contributors may add their own appropriate notices. 4. COMMERCIAL DISTRIBUTION Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense. For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages. 5. NO WARRANTY EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations. 6. DISCLAIMER OF LIABILITY EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 7. GENERAL If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed. All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive. Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be Distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to Distribute the Program (including its Contributions) under the new version. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. Nothing in this Agreement is intended to be enforceable by any entity that is not a Contributor or Recipient. No third-party beneficiary rights are created under this Agreement. Exhibit A - Form of Secondary Licenses Notice "This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), version(s), and exceptions or additional permissions here}." Simply including a copy of this Agreement, including this Exhibit A is not sufficient to license the Source Code under Secondary Licenses. If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice. You may add additional accurate notices of copyright ownership. ================================================ FILE: README.md ================================================ # Deep Clojure/Python Integration ### Version Info [![Clojars Project](https://img.shields.io/clojars/v/clj-python/libpython-clj.svg)](https://clojars.org/clj-python/libpython-clj) [![travis integration](https://travis-ci.com/clj-python/libpython-clj.svg?branch=master)](https://travis-ci.com/clj-python/libpython-clj) ## New Versions Are HOT! Huge New Features! You Can't Afford To Miss Out! * [API Documentation](https://clj-python.github.io/libpython-clj/) * [Java API](https://clj-python.github.io/libpython-clj/libpython-clj2.java-api.html) - you can use libpython-clj from java - no Clojure required. The class is included with the jar so just put the jar on the classpath and then `import libpython_clj2.java_api;` will work. Be sure to carefully read the namespace doc as, due to performance considerations, not all methods are protected via automatic GIL management. Note this integration includes support for extremely efficient data copies to numpy objects and callbacks from python to java. * [make-fastcallable](https://clj-python.github.io/libpython-clj/libpython-clj2.python.html#var-make-fastcallable) so if you calling a small function repeatedly you can now call it about twice as fast. A better optimization is to call a function once with numpy array arguments but unfortunately not all use cases are amenable to this pathway. So we did what we can. * JDK-17 and Mac M-1 support. To use libpython-clj2 with jdk-17 you need to enable the foreign module - see [deps.edn](https://github.com/clj-python/libpython-clj/blob/6e7368b44aaabddf565a5bbf3a240e60bf3dcbf8/deps.edn#L10) for a working alias. * You can now [Embed Clojure in Python](https://clj-python.github.io/libpython-clj/embedded.html) - you can launch a Clojure REPL from a Python host process. * **32 bit support**!! * 20-30% better performance. * Please avoid deprecated versions such as `[cnuernber/libpython-clj "1.36"]` (***note name change***). * This library, which has received the efforts of many excellent people, is built mainly upon [cnuernber/dtype-next](https://github.com/cnuernber/dtype-next/) and the [JNA library](https://github.com/java-native-access/jna). * [Static code generation](https://clj-python.github.io/libpython-clj/libpython-clj2.codegen.html#var-write-namespace.21) - generate clojure namespaces wrapping python modules that are safe to use with AOT and load much faster than analogous `require-python` calls. These namespace will not automatically initialize the python subsystem -- initialize! must be called first (or a nice exception is throw). ## libpython-clj features * Bridge between JVM objects and Python objects easily; use Python in your Java and use some Java in your Python. * Python objects are linked to the JVM GC such that when they are no longer reachable from the JVM their references are released. Scope based resource contexts are [also available](topics/scopes-and-gc.md). * Finding the python libraries is done dynamically allowing one system to run on multiple versions of python. * REPL oriented design means fast, smooth, iterative development. * Carin Meier has written excellent posts on [plotting](http://gigasquidsoftware.com/blog/2020/01/18/parens-for-pyplot/) and [advanced text generation](http://gigasquidsoftware.com/blog/2020/01/10/hugging-face-gpt-with-clojure/). She also has some great [examples](https://github.com/gigasquid/libpython-clj-examples). ## Vision We aim to integrate Python into Clojure at a deep level. This means that we want to be able to load/use python modules almost as if they were Clojure namespaces. We also want to be able to use Clojure to extend Python objects. I gave a [talk at Clojure Conj 2019](https://www.youtube.com/watch?v=vQPW16_jixs) that outlines more of what is going on. This code is a concrete example that generates an [embedding for faces](https://github.com/cnuernber/facial-rec): ```clojure (ns facial-rec.face-feature (:require [libpython-clj2.require :refer [require-python]] [libpython-clj2.python :refer [py. py.. py.-] :as py] [tech.v3.datatype :as dtype])) (require-python 'mxnet '(mxnet ndarray module io model)) (require-python 'cv2) (require-python '[numpy :as np]) (defn load-model [& {:keys [model-path checkpoint] :or {model-path "models/recognition/model" checkpoint 0}}] (let [[sym arg-params aux-params] (mxnet.model/load_checkpoint model-path checkpoint) all-layers (py. sym get_internals) target-layer (py/get-item all-layers "fc1_output") model (mxnet.module/Module :symbol target-layer :context (mxnet/cpu) :label_names nil)] (py. model bind :data_shapes [["data" [1 3 112 112]]]) (py. model set_params arg-params aux-params) model)) (defonce model (load-model)) (defn face->feature [img-path] (py/with-gil-stack-rc-context (if-let [new-img (cv2/imread img-path)] (let [new-img (cv2/cvtColor new-img cv2/COLOR_BGR2RGB) new-img (np/transpose new-img [2 0 1]) input-blob (np/expand_dims new-img :axis 0) data (mxnet.ndarray/array input-blob) batch (mxnet.io/DataBatch :data [data])] (py. model forward batch :is_train false) (-> (py. model get_outputs) first (py. asnumpy) (#(dtype/make-container :java-array :float32 %)))) (throw (Exception. (format "Failed to load img: %s" img-path)))))) ``` ## Usage #### Config namespace ```clojure (ns my-py-clj.config (:require [libpython-clj2.python :as py])) ;; When you use conda, it should look like this. (py/initialize! :python-executable "/opt/anaconda3/envs/my_env/bin/python3.7" :library-path "/opt/anaconda3/envs/my_env/lib/libpython3.7m.dylib") ``` #### Update project.clj ```clojure {... ;; This namespace going to run when the REPL is up. :repl-options {:init-ns my-py-clj.config} ...} ``` ```clojure user> (require '[libpython-clj2.require :refer [require-python]]) ...logging info.... nil user> (require-python '[numpy :as np]) nil user> (def test-ary (np/array [[1 2][3 4]])) #'user/test-ary user> test-ary [[1 2] [3 4]] ``` We have a [document](topics/Usage.md) on all the features but beginning usage is pretty simple. Import your modules, use the things from Clojure. We have put effort into making sure things like sequences and ranges transfer between the two languages. #### Environments One very complimentary aspect of Python with respect to Clojure is its integration with cutting edge native libraries. Our support isn't perfect so some understanding of the mechanism is important to diagnose errors and issues. Current, we launch the python3 executable and print out various different bits of configuration as json. We parse the json and use the output to attempt to find the `libpython3.Xm.so` shared library so for example if we are loading python 3.6 we look for `libpython3.6m.so` on Linux or `libpython3.6m.dylib` on the Mac. If we are unable to find a dynamic library such as `libpythonx.y.so` or `libpythonx.z.dylib`, it may be because Python is statically linked and the library is not present at all. This is dependent on the operating system and installation, and it is not always possible to detect it. In this case, we will receive an error message saying "Failed to find a valid python library!". To fix this, you may need to install additional OS packages or manually set the precise library location during `py/initialize!`. This pathway has allowed us support Conda albeit with some work. For examples using Conda, check out the facial rec repository a)bove or look into how we [build](scripts/build-conda-docker) our test [docker containers](dockerfiles/CondaDockerfile). #### devcontainer The scicloj community is maintaining a `devcontainer` [template](https://github.com/scicloj/devcontainer-templates/tree/main/src/scicloj) on which `libpython-clj` is know to work out of the box. This can be used as a starting point for projects using `libpython-clj` or as reference for debuging issues. ## Community We like to talk about libpython-clj on [Zulip](https://clojurians.zulipchat.com/#streams/215609/libpython-clj-dev) as the conversations are persistent and searchable. ## Further Information * Clojure Conj 2019 [video](https://www.youtube.com/watch?v=vQPW16_jixs) and [slides](https://docs.google.com/presentation/d/1uegYhpS6P2AtEfhpg6PlgBmTSIPqCXvFTWcGYG_Qk2o/edit?usp=sharing). * [development discussion forum](https://clojurians.zulipchat.com/#narrow/stream/215609-libpython-clj-dev) * [design documentation](topics/design.md) * [scope and garbage collection docs](topics/scopes-and-gc.md) * [examples](https://github.com/gigasquid/libpython-clj-examples) * [docker setup](https://github.com/scicloj/docker-hub) * [pandas bindings (!!)](https://github.com/alanmarazzi/panthera) * [nextjournal notebooks](https://nextjournal.com/kommen) * [scicloj video](https://www.youtube.com/watch?v=ajDiGS73i2o) * [Clojure/Python interop technical blog post](http://techascent.com/blog/functions-across-languages.html) * [persistent datastructures in python](https://github.com/tobgu/pyrsistent) ## New To Clojure New to Clojure or the JVM? Try remixing the nextjournal entry and playing around there. For more resources on learning and getting more comfortable with Clojure, we have an [introductory document](topics/new-to-clojure.md). ## Resources * [libpython C api](https://docs.python.org/3.7/c-api/index.html#c-api-index) * [create numpy from C ptr](https://stackoverflow.com/questions/23930671/how-to-create-n-dim-numpy-array-from-a-pointer) * [create C ptr from numpy](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.ctypes.html) To install jar to local .m2 : ```bash $ clj -X:depstar ``` After building and process `pom.xml` file you can run: ```bash $ clj -X:install ``` ### Deploy to clojars ```bash $ clj -X:deploy ``` > This command will sign jar before deploy, using your gpg key. ## License Copyright © 2019 Chris Nuernberger This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0. ================================================ FILE: codegen-test/README.md ================================================ # Codegen Sample A quick sample testing intended codegen usage. ## Usage We first generate the numpy namespace with a compile step. ```console scripts/compile ``` Next we run the compiled code from an AOT'd main. ```console scripts/run ``` ================================================ FILE: codegen-test/deps.edn ================================================ {:paths ["src"] :deps {clj-python/libpython-clj {:mvn/version "2.017"}}} ================================================ FILE: codegen-test/scripts/compile ================================================ #!/bin/bash clj -e "(require '[code.codegen :as cg])(cg/codegen)(println \"compilation successful\")\ (shutdown-agents)" ================================================ FILE: codegen-test/scripts/run ================================================ #!/bin/bash clj -e "(compile 'code.main)" java -cp "$(clj -Spath):classes" code.main ================================================ FILE: codegen-test/src/code/codegen.clj ================================================ (ns code.codegen (:require [libpython-clj2.python :as py] [libpython-clj2.codegen :as cgen])) (defn codegen [] (py/initialize!) (cgen/write-namespace! "numpy")) ================================================ FILE: codegen-test/src/code/main.clj ================================================ (ns code.main (:require [python.numpy :as np] [libpython-clj2.python :as py]) (:gen-class)) (defn setup! [] (py/initialize!)) (defn lspace [] (np/linspace 2 3)) (defn -main [] (setup!) (println (lspace)) (shutdown-agents)) ================================================ FILE: codegen-test/src/python/numpy.clj ================================================ (ns python.numpy "No documentation provided" (:require [libpython-clj2.python :as py] [libpython-clj2.python.jvm-handle :refer [py-global-delay]] [libpython-clj2.python.bridge-as-jvm :as as-jvm]) (:refer-clojure :exclude [+ - * / float double int long mod byte test char short take partition require max min identity empty mod repeat str load cast type sort conj map range list next hash eval bytes filter compile print set format compare reduce merge])) (defonce ^:private src-obj* (py-global-delay (py/path->py-obj "numpy"))) (def ^{:doc " result_type(*arrays_and_dtypes) Returns the type that results from applying the NumPy type promotion rules to the arguments. Type promotion in NumPy works similarly to the rules in languages like C++, with some slight differences. When both scalars and arrays are used, the array's type takes precedence and the actual value of the scalar is taken into account. For example, calculating 3*a, where a is an array of 32-bit floats, intuitively should result in a 32-bit float output. If the 3 is a 32-bit integer, the NumPy rules indicate it can't convert losslessly into a 32-bit float, so a 64-bit float should be the result type. By examining the value of the constant, '3', we see that it fits in an 8-bit integer, which can be cast losslessly into the 32-bit float. Parameters ---------- arrays_and_dtypes : list of arrays and dtypes The operands of some operation whose result type is needed. Returns ------- out : dtype The result type. See also -------- dtype, promote_types, min_scalar_type, can_cast Notes ----- .. versionadded:: 1.6.0 The specific algorithm used is as follows. Categories are determined by first checking which of boolean, integer (int/uint), or floating point (float/complex) the maximum kind of all the arrays and the scalars are. If there are only scalars or the maximum category of the scalars is higher than the maximum category of the arrays, the data types are combined with :func:`promote_types` to produce the return value. Otherwise, `min_scalar_type` is called on each array, and the resulting data types are all combined with :func:`promote_types` to produce the return value. The set of int values is not a subset of the uint values for types with the same number of bits, something not reflected in :func:`min_scalar_type`, but handled as a special case in `result_type`. Examples -------- >>> np.result_type(3, np.arange(7, dtype='i1')) dtype('int8') >>> np.result_type('i4', 'c8') dtype('complex128') >>> np.result_type(3.0, -2) dtype('float64') " :arglists '[[& [args {:as kwargs}]]]} result_type (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "result_type")))) (def ^{:doc " ravel_multi_index(multi_index, dims, mode='raise', order='C') Converts a tuple of index arrays into an array of flat indices, applying boundary modes to the multi-index. Parameters ---------- multi_index : tuple of array_like A tuple of integer arrays, one array for each dimension. dims : tuple of ints The shape of array into which the indices from ``multi_index`` apply. mode : {'raise', 'wrap', 'clip'}, optional Specifies how out-of-bounds indices are handled. Can specify either one mode or a tuple of modes, one mode per index. * 'raise' -- raise an error (default) * 'wrap' -- wrap around * 'clip' -- clip to the range In 'clip' mode, a negative index which would normally wrap will clip to 0 instead. order : {'C', 'F'}, optional Determines whether the multi-index should be viewed as indexing in row-major (C-style) or column-major (Fortran-style) order. Returns ------- raveled_indices : ndarray An array of indices into the flattened version of an array of dimensions ``dims``. See Also -------- unravel_index Notes ----- .. versionadded:: 1.6.0 Examples -------- >>> arr = np.array([[3,6,6],[4,5,1]]) >>> np.ravel_multi_index(arr, (7,6)) array([22, 41, 37]) >>> np.ravel_multi_index(arr, (7,6), order='F') array([31, 41, 13]) >>> np.ravel_multi_index(arr, (4,6), mode='clip') array([22, 23, 19]) >>> np.ravel_multi_index(arr, (4,4), mode=('clip','wrap')) array([12, 13, 13]) >>> np.ravel_multi_index((3,1,4,1), (6,7,8,9)) 1621 " :arglists '[[& [args {:as kwargs}]]]} ravel_multi_index (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ravel_multi_index")))) (def ^{:doc " vdot(a, b) Return the dot product of two vectors. The vdot(`a`, `b`) function handles complex numbers differently than dot(`a`, `b`). If the first argument is complex the complex conjugate of the first argument is used for the calculation of the dot product. Note that `vdot` handles multidimensional arrays differently than `dot`: it does *not* perform a matrix product, but flattens input arguments to 1-D vectors first. Consequently, it should only be used for vectors. Parameters ---------- a : array_like If `a` is complex the complex conjugate is taken before calculation of the dot product. b : array_like Second argument to the dot product. Returns ------- output : ndarray Dot product of `a` and `b`. Can be an int, float, or complex depending on the types of `a` and `b`. See Also -------- dot : Return the dot product without using the complex conjugate of the first argument. Examples -------- >>> a = np.array([1+2j,3+4j]) >>> b = np.array([5+6j,7+8j]) >>> np.vdot(a, b) (70-8j) >>> np.vdot(b, a) (70+8j) Note that higher-dimensional arrays are flattened! >>> a = np.array([[1, 4], [5, 6]]) >>> b = np.array([[4, 1], [2, 2]]) >>> np.vdot(a, b) 30 >>> np.vdot(b, a) 30 >>> 1*4 + 4*1 + 5*2 + 6*2 30 " :arglists '[[& [args {:as kwargs}]]]} vdot (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "vdot")))) (def ^{:doc "Signed integer type, compatible with C ``short``. :Character code: ``'h'`` :Canonical name: `numpy.short` :Alias on this platform: `numpy.int16`: 16-bit signed integer (``-32_768`` to ``32_767``)." :arglists '[[self & [args {:as kwargs}]]]} int16 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "int16")))) (def ^{:doc ""} NaN ##NaN) (def ^{:doc " Diagnosing machine parameters. Attributes ---------- ibeta : int Radix in which numbers are represented. it : int Number of base-`ibeta` digits in the floating point mantissa M. machep : int Exponent of the smallest (most negative) power of `ibeta` that, added to 1.0, gives something different from 1.0 eps : float Floating-point number ``beta**machep`` (floating point precision) negep : int Exponent of the smallest power of `ibeta` that, subtracted from 1.0, gives something different from 1.0. epsneg : float Floating-point number ``beta**negep``. iexp : int Number of bits in the exponent (including its sign and bias). minexp : int Smallest (most negative) power of `ibeta` consistent with there being no leading zeros in the mantissa. xmin : float Floating-point number ``beta**minexp`` (the smallest [in magnitude] positive floating point number with full precision). maxexp : int Smallest (positive) power of `ibeta` that causes overflow. xmax : float ``(1-epsneg) * beta**maxexp`` (the largest [in magnitude] usable floating value). irnd : int In ``range(6)``, information on what kind of rounding is done in addition, and on how underflow is handled. ngrd : int Number of 'guard digits' used when truncating the product of two mantissas to fit the representation. epsilon : float Same as `eps`. tiny : float Same as `xmin`. huge : float Same as `xmax`. precision : float ``- int(-log10(eps))`` resolution : float ``- 10**(-precision)`` Parameters ---------- float_conv : function, optional Function that converts an integer or integer array to a float or float array. Default is `float`. int_conv : function, optional Function that converts a float or float array to an integer or integer array. Default is `int`. float_to_float : function, optional Function that converts a float array to float. Default is `float`. Note that this does not seem to do anything useful in the current implementation. float_to_str : function, optional Function that converts a single float to a string. Default is ``lambda v:'%24.16e' %v``. title : str, optional Title that is printed in the string representation of `MachAr`. See Also -------- finfo : Machine limits for floating point types. iinfo : Machine limits for integer types. References ---------- .. [1] Press, Teukolsky, Vetterling and Flannery, \"Numerical Recipes in C++,\" 2nd ed, Cambridge University Press, 2002, p. 31. " :arglists '[[self & [{float_conv :float_conv, int_conv :int_conv, float_to_float :float_to_float, float_to_str :float_to_str, title :title}]] [self & [{float_conv :float_conv, int_conv :int_conv, float_to_float :float_to_float, float_to_str :float_to_str}]] [self & [{float_conv :float_conv, int_conv :int_conv, float_to_float :float_to_float}]] [self & [{float_conv :float_conv, int_conv :int_conv}]] [self & [{float_conv :float_conv}]] [self]]} MachAr (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "MachAr")))) (def ^{:doc " Kronecker product of two arrays. Computes the Kronecker product, a composite array made of blocks of the second array scaled by the first. Parameters ---------- a, b : array_like Returns ------- out : ndarray See Also -------- outer : The outer product Notes ----- The function assumes that the number of dimensions of `a` and `b` are the same, if necessary prepending the smallest with ones. If `a.shape = (r0,r1,..,rN)` and `b.shape = (s0,s1,...,sN)`, the Kronecker product has shape `(r0*s0, r1*s1, ..., rN*SN)`. The elements are products of elements from `a` and `b`, organized explicitly by:: kron(a,b)[k0,k1,...,kN] = a[i0,i1,...,iN] * b[j0,j1,...,jN] where:: kt = it * st + jt, t = 0,...,N In the common 2-D case (N=1), the block structure can be visualized:: [[ a[0,0]*b, a[0,1]*b, ... , a[0,-1]*b ], [ ... ... ], [ a[-1,0]*b, a[-1,1]*b, ... , a[-1,-1]*b ]] Examples -------- >>> np.kron([1,10,100], [5,6,7]) array([ 5, 6, 7, ..., 500, 600, 700]) >>> np.kron([5,6,7], [1,10,100]) array([ 5, 50, 500, ..., 7, 70, 700]) >>> np.kron(np.eye(2), np.ones((2,2))) array([[1., 1., 0., 0.], [1., 1., 0., 0.], [0., 0., 1., 1.], [0., 0., 1., 1.]]) >>> a = np.arange(100).reshape((2,5,2,5)) >>> b = np.arange(24).reshape((2,3,4)) >>> c = np.kron(a,b) >>> c.shape (2, 10, 6, 20) >>> I = (1,3,0,2) >>> J = (0,2,1) >>> J1 = (0,) + J # extend to ndim=4 >>> S1 = (1,) + b.shape >>> K = tuple(np.array(I) * np.array(S1) + np.array(J1)) >>> c[K] == a[I]*b[J] True " :arglists '[[& [args {:as kwargs}]]]} kron (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "kron")))) (def ^{:doc "Abstract base class of all scalar types without predefined length. The actual size of these types depends on the specific `np.dtype` instantiation." :arglists '[[self & [args {:as kwargs}]]]} flexible (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "flexible")))) (def ^{:doc " Load ASCII data stored in a comma-separated file. The returned array is a record array (if ``usemask=False``, see `recarray`) or a masked record array (if ``usemask=True``, see `ma.mrecords.MaskedRecords`). Parameters ---------- fname, kwargs : For a description of input parameters, see `genfromtxt`. See Also -------- numpy.genfromtxt : generic function to load ASCII data. Notes ----- By default, `dtype` is None, which means that the data-type of the output array will be determined from the data. " :arglists '[[fname & [{:as kwargs}]]]} recfromcsv (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "recfromcsv")))) (def ^{:doc "Abstract base class of all numeric scalar types with a (potentially) inexact representation of the values in its range, such as floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} inexact (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "inexact")))) (def ^{:doc "floor(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the floor of the input, element-wise. The floor of the scalar `x` is the largest integer `i`, such that `i <= x`. It is often denoted as :math:`\\lfloor x \\rfloor`. Parameters ---------- x : array_like Input data. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The floor of each element in `x`. This is a scalar if `x` is a scalar. See Also -------- ceil, trunc, rint Notes ----- Some spreadsheet programs calculate the \"floor-towards-zero\", in other words ``floor(-2.5) == -2``. NumPy instead uses the definition of `floor` where `floor(-2.5) == -3`. Examples -------- >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.floor(a) array([-2., -2., -1., 0., 1., 1., 2.])" :arglists '[[self & [args {:as kwargs}]]]} floor (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "floor")))) (def ^{:doc ""} tracemalloc_domain 389047) (def ^{:doc " Return selected slices of an array along given axis. When working along a given axis, a slice along that axis is returned in `output` for each index where `condition` evaluates to True. When working on a 1-D array, `compress` is equivalent to `extract`. Parameters ---------- condition : 1-D array of bools Array that selects which entries to return. If len(condition) is less than the size of `a` along the given axis, then output is truncated to the length of the condition array. a : array_like Array from which to extract a part. axis : int, optional Axis along which to take slices. If None (default), work on the flattened array. out : ndarray, optional Output array. Its type is preserved and it must be of the right shape to hold the output. Returns ------- compressed_array : ndarray A copy of `a` without the slices along axis for which `condition` is false. See Also -------- take, choose, diag, diagonal, select ndarray.compress : Equivalent method in ndarray extract: Equivalent method when working on 1-D arrays :ref:`ufuncs-output-type` Examples -------- >>> a = np.array([[1, 2], [3, 4], [5, 6]]) >>> a array([[1, 2], [3, 4], [5, 6]]) >>> np.compress([0, 1], a, axis=0) array([[3, 4]]) >>> np.compress([False, True, True], a, axis=0) array([[3, 4], [5, 6]]) >>> np.compress([False, True], a, axis=1) array([[2], [4], [6]]) Working on the flattened array does not return slices along an axis but selects elements. >>> np.compress([False, True], a) array([2]) " :arglists '[[& [args {:as kwargs}]]]} compress (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "compress")))) (def ^{:doc "Extended-precision floating-point number type, compatible with C ``long double`` but not necessarily with IEEE 754 quadruple-precision. :Character code: ``'g'`` :Canonical name: `numpy.longdouble` :Alias: `numpy.longfloat` :Alias on this platform: `numpy.float128`: 128-bit extended-precision floating-point number type." :arglists '[[self & [args {:as kwargs}]]]} longfloat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "longfloat")))) (def ^{:doc "log1p(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the natural logarithm of one plus the input array, element-wise. Calculates ``log(1 + x)``. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray Natural logarithm of `1 + x`, element-wise. This is a scalar if `x` is a scalar. See Also -------- expm1 : ``exp(x) - 1``, the inverse of `log1p`. Notes ----- For real-valued input, `log1p` is accurate also for `x` so small that `1 + x == 1` in floating-point accuracy. Logarithm is a multivalued function: for each `x` there is an infinite number of `z` such that `exp(z) = 1 + x`. The convention is to return the `z` whose imaginary part lies in `[-pi, pi]`. For real-valued input data types, `log1p` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `log1p` is a complex analytical function that has a branch cut `[-inf, -1]` and is continuous from above on it. `log1p` handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard. References ---------- .. [1] M. Abramowitz and I.A. Stegun, \"Handbook of Mathematical Functions\", 10th printing, 1964, pp. 67. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, \"Logarithm\". https://en.wikipedia.org/wiki/Logarithm Examples -------- >>> np.log1p(1e-99) 1e-99 >>> np.log(1 + 1e-99) 0.0" :arglists '[[self & [args {:as kwargs}]]]} log1p (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "log1p")))) (def ^{:doc "arctan2(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Element-wise arc tangent of ``x1/x2`` choosing the quadrant correctly. The quadrant (i.e., branch) is chosen so that ``arctan2(x1, x2)`` is the signed angle in radians between the ray ending at the origin and passing through the point (1,0), and the ray ending at the origin and passing through the point (`x2`, `x1`). (Note the role reversal: the \"`y`-coordinate\" is the first function parameter, the \"`x`-coordinate\" is the second.) By IEEE convention, this function is defined for `x2` = +/-0 and for either or both of `x1` and `x2` = +/-inf (see Notes for specific values). This function is not defined for complex-valued arguments; for the so-called argument of complex values, use `angle`. Parameters ---------- x1 : array_like, real-valued `y`-coordinates. x2 : array_like, real-valued `x`-coordinates. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- angle : ndarray Array of angles in radians, in the range ``[-pi, pi]``. This is a scalar if both `x1` and `x2` are scalars. See Also -------- arctan, tan, angle Notes ----- *arctan2* is identical to the `atan2` function of the underlying C library. The following special values are defined in the C standard: [1]_ ====== ====== ================ `x1` `x2` `arctan2(x1,x2)` ====== ====== ================ +/- 0 +0 +/- 0 +/- 0 -0 +/- pi > 0 +/-inf +0 / +pi < 0 +/-inf -0 / -pi +/-inf +inf +/- (pi/4) +/-inf -inf +/- (3*pi/4) ====== ====== ================ Note that +0 and -0 are distinct floating point numbers, as are +inf and -inf. References ---------- .. [1] ISO/IEC standard 9899:1999, \"Programming language C.\" Examples -------- Consider four points in different quadrants: >>> x = np.array([-1, +1, +1, -1]) >>> y = np.array([-1, -1, +1, +1]) >>> np.arctan2(y, x) * 180 / np.pi array([-135., -45., 45., 135.]) Note the order of the parameters. `arctan2` is defined also when `x2` = 0 and at several other special points, obtaining values in the range ``[-pi, pi]``: >>> np.arctan2([1., -1.], [0., 0.]) array([ 1.57079633, -1.57079633]) >>> np.arctan2([0., 0., np.inf], [+0., -0., np.inf]) array([ 0. , 3.14159265, 0.78539816])" :arglists '[[self & [args {:as kwargs}]]]} arctan2 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arctan2")))) (def ^{:doc "ceil(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the ceiling of the input, element-wise. The ceil of the scalar `x` is the smallest integer `i`, such that `i >= x`. It is often denoted as :math:`\\lceil x \\rceil`. Parameters ---------- x : array_like Input data. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The ceiling of each element in `x`, with `float` dtype. This is a scalar if `x` is a scalar. See Also -------- floor, trunc, rint Examples -------- >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.ceil(a) array([-1., -1., -0., 1., 2., 2., 2.])" :arglists '[[self & [args {:as kwargs}]]]} ceil (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ceil")))) (def ^{:doc " Return an array (ndim >= 1) laid out in Fortran order in memory. Parameters ---------- a : array_like Input array. dtype : str or dtype object, optional By default, the data-type is inferred from the input data. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray The input `a` in Fortran, or column-major, order. See Also -------- ascontiguousarray : Convert input to a contiguous (C order) array. asanyarray : Convert input to an ndarray with either row or column-major memory order. require : Return an ndarray that satisfies requirements. ndarray.flags : Information about the memory layout of the array. Examples -------- >>> x = np.arange(6).reshape(2,3) >>> y = np.asfortranarray(x) >>> x.flags['F_CONTIGUOUS'] False >>> y.flags['F_CONTIGUOUS'] True Note: This function returns an array with at least one-dimension (1-d) so it will not preserve 0-d arrays. " :arglists '[[a & [{dtype :dtype, like :like}]] [a & [{like :like}]]]} asfortranarray (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "asfortranarray")))) (def ^{:doc "logical_and(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the truth value of x1 AND x2 element-wise. Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or bool Boolean result of the logical AND operation applied to the elements of `x1` and `x2`; the shape is determined by broadcasting. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logical_or, logical_not, logical_xor bitwise_and Examples -------- >>> np.logical_and(True, False) False >>> np.logical_and([True, False], [False, False]) array([False, False]) >>> x = np.arange(5) >>> np.logical_and(x>1, x<4) array([False, False, True, True, False]) The ``&`` operator can be used as a shorthand for ``np.logical_and`` on boolean ndarrays. >>> a = np.array([True, False]) >>> b = np.array([False, False]) >>> a & b array([False, False])" :arglists '[[self & [args {:as kwargs}]]]} logical_and (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "logical_and")))) (def ^{:doc " Return indices that are non-zero in the flattened version of a. This is equivalent to np.nonzero(np.ravel(a))[0]. Parameters ---------- a : array_like Input data. Returns ------- res : ndarray Output array, containing the indices of the elements of `a.ravel()` that are non-zero. See Also -------- nonzero : Return the indices of the non-zero elements of the input array. ravel : Return a 1-D array containing the elements of the input array. Examples -------- >>> x = np.arange(-2, 3) >>> x array([-2, -1, 0, 1, 2]) >>> np.flatnonzero(x) array([0, 1, 3, 4]) Use the indices of the non-zero elements as an index array to extract these elements: >>> x.ravel()[np.flatnonzero(x)] array([-2, -1, 1, 2]) " :arglists '[[& [args {:as kwargs}]]]} flatnonzero (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "flatnonzero")))) (def ^{:doc " Returns True if the type of `element` is a scalar type. Parameters ---------- element : any Input argument, can be of any type and shape. Returns ------- val : bool True if `element` is a scalar type, False if it is not. See Also -------- ndim : Get the number of dimensions of an array Notes ----- If you need a stricter way to identify a *numerical* scalar, use ``isinstance(x, numbers.Number)``, as that returns ``False`` for most non-numerical elements such as strings. In most cases ``np.ndim(x) == 0`` should be used instead of this function, as that will also return true for 0d arrays. This is how numpy overloads functions in the style of the ``dx`` arguments to `gradient` and the ``bins`` argument to `histogram`. Some key differences: +--------------------------------------+---------------+-------------------+ | x |``isscalar(x)``|``np.ndim(x) == 0``| +======================================+===============+===================+ | PEP 3141 numeric objects (including | ``True`` | ``True`` | | builtins) | | | +--------------------------------------+---------------+-------------------+ | builtin string and buffer objects | ``True`` | ``True`` | +--------------------------------------+---------------+-------------------+ | other builtin objects, like | ``False`` | ``True`` | | `pathlib.Path`, `Exception`, | | | | the result of `re.compile` | | | +--------------------------------------+---------------+-------------------+ | third-party objects like | ``False`` | ``True`` | | `matplotlib.figure.Figure` | | | +--------------------------------------+---------------+-------------------+ | zero-dimensional numpy arrays | ``False`` | ``True`` | +--------------------------------------+---------------+-------------------+ | other numpy arrays | ``False`` | ``False`` | +--------------------------------------+---------------+-------------------+ | `list`, `tuple`, and other sequence | ``False`` | ``False`` | | objects | | | +--------------------------------------+---------------+-------------------+ Examples -------- >>> np.isscalar(3.1) True >>> np.isscalar(np.array(3.1)) False >>> np.isscalar([3.1]) False >>> np.isscalar(False) True >>> np.isscalar('numpy') True NumPy supports PEP 3141 numbers: >>> from fractions import Fraction >>> np.isscalar(Fraction(5, 17)) True >>> from numbers import Number >>> np.isscalar(Number()) True " :arglists '[[element]]} isscalar (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isscalar")))) (def ^{:doc " Return a scalar type which is common to the input arrays. The return type will always be an inexact (i.e. floating point) scalar type, even if all the arrays are integer arrays. If one of the inputs is an integer array, the minimum precision type that is returned is a 64-bit floating point dtype. All input arrays except int64 and uint64 can be safely cast to the returned dtype without loss of information. Parameters ---------- array1, array2, ... : ndarrays Input arrays. Returns ------- out : data type code Data type code. See Also -------- dtype, mintypecode Examples -------- >>> np.common_type(np.arange(2, dtype=np.float32)) >>> np.common_type(np.arange(2, dtype=np.float32), np.arange(2)) >>> np.common_type(np.arange(4), np.array([45, 6.j]), np.array([45.0])) " :arglists '[[& [args {:as kwargs}]]]} common_type (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "common_type")))) (def ^{:doc "Complex number type composed of two extended-precision floating-point numbers. :Character code: ``'G'`` :Canonical name: `numpy.clongdouble` :Alias: `numpy.clongfloat` :Alias: `numpy.longcomplex` :Alias on this platform: `numpy.complex256`: Complex number type composed of 2 128-bit extended-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} clongdouble (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "clongdouble")))) (def ^{:doc " Extract a diagonal or construct a diagonal array. See the more detailed documentation for ``numpy.diagonal`` if you use this function to extract a diagonal and wish to write to the resulting array; whether it returns a copy or a view depends on what version of numpy you are using. Parameters ---------- v : array_like If `v` is a 2-D array, return a copy of its `k`-th diagonal. If `v` is a 1-D array, return a 2-D array with `v` on the `k`-th diagonal. k : int, optional Diagonal in question. The default is 0. Use `k>0` for diagonals above the main diagonal, and `k<0` for diagonals below the main diagonal. Returns ------- out : ndarray The extracted diagonal or constructed diagonal array. See Also -------- diagonal : Return specified diagonals. diagflat : Create a 2-D array with the flattened input as a diagonal. trace : Sum along diagonals. triu : Upper triangle of an array. tril : Lower triangle of an array. Examples -------- >>> x = np.arange(9).reshape((3,3)) >>> x array([[0, 1, 2], [3, 4, 5], [6, 7, 8]]) >>> np.diag(x) array([0, 4, 8]) >>> np.diag(x, k=1) array([1, 5]) >>> np.diag(x, k=-1) array([3, 7]) >>> np.diag(np.diag(x)) array([[0, 0, 0], [0, 4, 0], [0, 0, 8]]) " :arglists '[[& [args {:as kwargs}]]]} diag (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "diag")))) (def ^{:doc " Return the maximum of an array or maximum along an axis, ignoring any NaNs. When all-NaN slices are encountered a ``RuntimeWarning`` is raised and NaN is returned for that slice. Parameters ---------- a : array_like Array containing numbers whose maximum is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the maximum is computed. The default is to compute the maximum of the flattened array. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. .. versionadded:: 1.8.0 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 `a`. If the value is anything but the default, then `keepdims` will be passed through to the `max` method of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. .. versionadded:: 1.8.0 Returns ------- nanmax : ndarray An array with the same shape as `a`, with the specified axis removed. If `a` is a 0-d array, or if axis is None, an ndarray scalar is returned. The same dtype as `a` is returned. See Also -------- nanmin : The minimum value of an array along a given axis, ignoring any NaNs. amax : The maximum value of an array along a given axis, propagating any NaNs. fmax : Element-wise maximum of two arrays, ignoring any NaNs. maximum : Element-wise maximum of two arrays, propagating any NaNs. isnan : Shows which elements are Not a Number (NaN). isfinite: Shows which elements are neither NaN nor infinity. amin, fmin, minimum Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Positive infinity is treated as a very large number and negative infinity is treated as a very small (i.e. negative) number. If the input has a integer type the function is equivalent to np.max. Examples -------- >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nanmax(a) 3.0 >>> np.nanmax(a, axis=0) array([3., 2.]) >>> np.nanmax(a, axis=1) array([2., 3.]) When positive infinity and negative infinity are present: >>> np.nanmax([1, 2, np.nan, np.NINF]) 2.0 >>> np.nanmax([1, 2, np.nan, np.inf]) inf " :arglists '[[& [args {:as kwargs}]]]} nanmax (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanmax")))) (def ^{:doc "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." :arglists '[[self & [args {:as kwargs}]]]} generic (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "generic")))) (def ^{:doc " Return the indices of the bins to which each value in input array belongs. ========= ============= ============================ `right` order of bins returned index `i` satisfies ========= ============= ============================ ``False`` increasing ``bins[i-1] <= x < bins[i]`` ``True`` increasing ``bins[i-1] < x <= bins[i]`` ``False`` decreasing ``bins[i-1] > x >= bins[i]`` ``True`` decreasing ``bins[i-1] >= x > bins[i]`` ========= ============= ============================ If values in `x` are beyond the bounds of `bins`, 0 or ``len(bins)`` is returned as appropriate. Parameters ---------- x : array_like Input array to be binned. Prior to NumPy 1.10.0, this array had to be 1-dimensional, but can now have any shape. bins : array_like Array of bins. It has to be 1-dimensional and monotonic. right : bool, optional Indicating whether the intervals include the right or the left bin edge. Default behavior is (right==False) indicating that the interval does not include the right edge. The left bin end is open in this case, i.e., bins[i-1] <= x < bins[i] is the default behavior for monotonically increasing bins. Returns ------- indices : ndarray of ints Output array of indices, of same shape as `x`. Raises ------ ValueError If `bins` is not monotonic. TypeError If the type of the input is complex. See Also -------- bincount, histogram, unique, searchsorted Notes ----- If values in `x` are such that they fall outside the bin range, attempting to index `bins` with the indices that `digitize` returns will result in an IndexError. .. versionadded:: 1.10.0 `np.digitize` is implemented in terms of `np.searchsorted`. This means that a binary search is used to bin the values, which scales much better for larger number of bins than the previous linear search. It also removes the requirement for the input array to be 1-dimensional. For monotonically _increasing_ `bins`, the following are equivalent:: np.digitize(x, bins, right=True) np.searchsorted(bins, x, side='left') Note that as the order of the arguments are reversed, the side must be too. The `searchsorted` call is marginally faster, as it does not do any monotonicity checks. Perhaps more importantly, it supports all dtypes. Examples -------- >>> x = np.array([0.2, 6.4, 3.0, 1.6]) >>> bins = np.array([0.0, 1.0, 2.5, 4.0, 10.0]) >>> inds = np.digitize(x, bins) >>> inds array([1, 4, 3, 2]) >>> for n in range(x.size): ... print(bins[inds[n]-1], \"<=\", x[n], \"<\", bins[inds[n]]) ... 0.0 <= 0.2 < 1.0 4.0 <= 6.4 < 10.0 2.5 <= 3.0 < 4.0 1.0 <= 1.6 < 2.5 >>> x = np.array([1.2, 10.0, 12.4, 15.5, 20.]) >>> bins = np.array([0, 5, 10, 15, 20]) >>> np.digitize(x,bins,right=True) array([1, 2, 3, 4, 4]) >>> np.digitize(x,bins,right=False) array([1, 3, 3, 4, 5]) " :arglists '[[& [args {:as kwargs}]]]} digitize (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "digitize")))) (def ^{:doc " Split an array into multiple sub-arrays. Please refer to the ``split`` documentation. The only difference between these functions is that ``array_split`` allows `indices_or_sections` to be an integer that does *not* equally divide the axis. For an array of length l that should be split into n sections, it returns l % n sub-arrays of size l//n + 1 and the rest of size l//n. See Also -------- split : Split array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(8.0) >>> np.array_split(x, 3) [array([0., 1., 2.]), array([3., 4., 5.]), array([6., 7.])] >>> x = np.arange(9) >>> np.array_split(x, 4) [array([0, 1, 2]), array([3, 4]), array([5, 6]), array([7, 8])] " :arglists '[[& [args {:as kwargs}]]]} array_split (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "array_split")))) (def ^{:doc " ======================== Random Number Generation ======================== Use ``default_rng()`` to create a `Generator` and call its methods. =============== ========================================================= Generator --------------- --------------------------------------------------------- Generator Class implementing all of the random number distributions default_rng Default constructor for ``Generator`` =============== ========================================================= ============================================= === BitGenerator Streams that work with Generator --------------------------------------------- --- MT19937 PCG64 Philox SFC64 ============================================= === ============================================= === Getting entropy to initialize a BitGenerator --------------------------------------------- --- SeedSequence ============================================= === Legacy ------ For backwards compatibility with previous versions of numpy before 1.17, the various aliases to the global `RandomState` methods are left alone and do not use the new `Generator` API. ==================== ========================================================= Utility functions -------------------- --------------------------------------------------------- random Uniformly distributed floats over ``[0, 1)`` bytes Uniformly distributed random bytes. permutation Randomly permute a sequence / generate a random sequence. shuffle Randomly permute a sequence in place. choice Random sample from 1-D array. ==================== ========================================================= ==================== ========================================================= Compatibility functions - removed in the new API -------------------- --------------------------------------------------------- rand Uniformly distributed values. randn Normally distributed values. ranf Uniformly distributed floating point numbers. random_integers Uniformly distributed integers in a given range. (deprecated, use ``integers(..., closed=True)`` instead) random_sample Alias for `random_sample` randint Uniformly distributed integers in a given range seed Seed the legacy random number generator. ==================== ========================================================= ==================== ========================================================= Univariate distributions -------------------- --------------------------------------------------------- beta Beta distribution over ``[0, 1]``. binomial Binomial distribution. chisquare :math:`\\chi^2` distribution. exponential Exponential distribution. f F (Fisher-Snedecor) distribution. gamma Gamma distribution. geometric Geometric distribution. gumbel Gumbel distribution. hypergeometric Hypergeometric distribution. laplace Laplace distribution. logistic Logistic distribution. lognormal Log-normal distribution. logseries Logarithmic series distribution. negative_binomial Negative binomial distribution. noncentral_chisquare Non-central chi-square distribution. noncentral_f Non-central F distribution. normal Normal / Gaussian distribution. pareto Pareto distribution. poisson Poisson distribution. power Power distribution. rayleigh Rayleigh distribution. triangular Triangular distribution. uniform Uniform distribution. vonmises Von Mises circular distribution. wald Wald (inverse Gaussian) distribution. weibull Weibull distribution. zipf Zipf's distribution over ranked data. ==================== ========================================================= ==================== ========================================================== Multivariate distributions -------------------- ---------------------------------------------------------- dirichlet Multivariate generalization of Beta distribution. multinomial Multivariate generalization of the binomial distribution. multivariate_normal Multivariate generalization of the normal distribution. ==================== ========================================================== ==================== ========================================================= Standard distributions -------------------- --------------------------------------------------------- standard_cauchy Standard Cauchy-Lorentz distribution. standard_exponential Standard exponential distribution. standard_gamma Standard Gamma distribution. standard_normal Standard normal distribution. standard_t Standard Student's t-distribution. ==================== ========================================================= ==================== ========================================================= Internal functions -------------------- --------------------------------------------------------- get_state Get tuple representing internal state of generator. set_state Set state of generator. ==================== ========================================================= "} random (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "random")))) (def ^{:doc " Return the directory that contains the NumPy \\*.h header files. Extension modules that need to compile against NumPy should use this function to locate the appropriate include directory. Notes ----- When using ``distutils``, for example in ``setup.py``. :: import numpy as np ... Extension('extension_name', ... include_dirs=[np.get_include()]) ... " :arglists '[[]]} get_include (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "get_include")))) (def ^{:doc ""} MAY_SHARE_BOUNDS 0) (def ^{:doc ""} UFUNC_BUFSIZE_DEFAULT 8192) (def ^{:doc ""} __config__ (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "__config__")))) (def ^{:doc " Return the length of the first dimension of the input array. .. deprecated:: 1.18 `numpy.alen` is deprecated, use `len` instead. Parameters ---------- a : array_like Input array. Returns ------- alen : int Length of the first dimension of `a`. See Also -------- shape, size Examples -------- >>> a = np.zeros((7,4,5)) >>> a.shape[0] 7 >>> np.alen(a) 7 " :arglists '[[& [args {:as kwargs}]]]} alen (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "alen")))) (def ^{:doc " Save an array to a binary file in NumPy ``.npy`` format. Parameters ---------- file : file, str, or pathlib.Path File or filename to which the data is saved. If file is a file-object, then the filename is unchanged. If file is a string or Path, a ``.npy`` extension will be appended to the filename if it does not already have one. arr : array_like Array data to be saved. allow_pickle : bool, optional Allow saving object arrays using Python pickles. Reasons for disallowing pickles include security (loading pickled data can execute arbitrary code) and portability (pickled objects may not be loadable on different Python installations, for example if the stored objects require libraries that are not available, and not all pickled data is compatible between Python 2 and Python 3). Default: True fix_imports : bool, optional Only useful in forcing objects in object arrays on Python 3 to be pickled in a Python 2 compatible way. If `fix_imports` is True, pickle will try to map the new Python 3 names to the old module names used in Python 2, so that the pickle data stream is readable with Python 2. See Also -------- savez : Save several arrays into a ``.npz`` archive savetxt, load Notes ----- For a description of the ``.npy`` format, see :py:mod:`numpy.lib.format`. Any data saved to the file is appended to the end of the file. Examples -------- >>> from tempfile import TemporaryFile >>> outfile = TemporaryFile() >>> x = np.arange(10) >>> np.save(outfile, x) >>> _ = outfile.seek(0) # Only needed here to simulate closing & reopening file >>> np.load(outfile) array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> with open('test.npy', 'wb') as f: ... np.save(f, np.array([1, 2])) ... np.save(f, np.array([1, 3])) >>> with open('test.npy', 'rb') as f: ... a = np.load(f) ... b = np.load(f) >>> print(a, b) # [1 2] [1 3] " :arglists '[[& [args {:as kwargs}]]]} save (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "save")))) (def ^{:doc "cosh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Hyperbolic cosine, element-wise. Equivalent to ``1/2 * (np.exp(x) + np.exp(-x))`` and ``np.cos(1j*x)``. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array of same shape as `x`. This is a scalar if `x` is a scalar. Examples -------- >>> np.cosh(0) 1.0 The hyperbolic cosine describes the shape of a hanging cable: >>> import matplotlib.pyplot as plt >>> x = np.linspace(-4, 4, 1000) >>> plt.plot(x, np.cosh(x)) >>> plt.show()" :arglists '[[self & [args {:as kwargs}]]]} cosh (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cosh")))) (def ^{:doc " Construct an open mesh from multiple sequences. This function takes N 1-D sequences and returns N outputs with N dimensions each, such that the shape is 1 in all but one dimension and the dimension with the non-unit shape value cycles through all N dimensions. Using `ix_` one can quickly construct index arrays that will index the cross product. ``a[np.ix_([1,3],[2,5])]`` returns the array ``[[a[1,2] a[1,5]], [a[3,2] a[3,5]]]``. Parameters ---------- args : 1-D sequences Each sequence should be of integer or boolean type. Boolean sequences will be interpreted as boolean masks for the corresponding dimension (equivalent to passing in ``np.nonzero(boolean_sequence)``). Returns ------- out : tuple of ndarrays N arrays with N dimensions each, with N the number of input sequences. Together these arrays form an open mesh. See Also -------- ogrid, mgrid, meshgrid Examples -------- >>> a = np.arange(10).reshape(2, 5) >>> a array([[0, 1, 2, 3, 4], [5, 6, 7, 8, 9]]) >>> ixgrid = np.ix_([0, 1], [2, 4]) >>> ixgrid (array([[0], [1]]), array([[2, 4]])) >>> ixgrid[0].shape, ixgrid[1].shape ((2, 1), (1, 2)) >>> a[ixgrid] array([[2, 4], [7, 9]]) >>> ixgrid = np.ix_([True, True], [2, 4]) >>> a[ixgrid] array([[2, 4], [7, 9]]) >>> ixgrid = np.ix_([True, True], [False, False, True, False, True]) >>> a[ixgrid] array([[2, 4], [7, 9]]) " :arglists '[[& [args {:as kwargs}]]]} ix_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ix_")))) (def ^{:doc ""} NINF ##-Inf) (def ^{:doc "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 `. 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." :arglists '[[self & [args {:as kwargs}]]]} ufunc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ufunc")))) (def ^{:doc "" :arglists '[[self & [args {:as kwargs}]]]} TooHardError (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "TooHardError")))) (def ^{:doc " Return the string representation of a scalar dtype. Parameters ---------- sctype : scalar dtype or object If a scalar dtype, the corresponding string character is returned. If an object, `sctype2char` tries to infer its scalar type and then return the corresponding string character. Returns ------- typechar : str The string character corresponding to the scalar type. Raises ------ ValueError If `sctype` is an object for which the type can not be inferred. See Also -------- obj2sctype, issctype, issubsctype, mintypecode Examples -------- >>> for sctype in [np.int32, np.double, np.complex_, np.string_, np.ndarray]: ... print(np.sctype2char(sctype)) l # may vary d D S O >>> x = np.array([1., 2-1.j]) >>> np.sctype2char(x) 'D' >>> np.sctype2char(list) 'O' " :arglists '[[sctype]]} sctype2char (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sctype2char")))) (def ^{:doc " Find the unique elements of an array. Returns the sorted unique elements of an array. There are three optional outputs in addition to the unique elements: * the indices of the input array that give the unique values * the indices of the unique array that reconstruct the input array * the number of times each unique value comes up in the input array Parameters ---------- ar : array_like Input array. Unless `axis` is specified, this will be flattened if it is not already 1-D. return_index : bool, optional If True, also return the indices of `ar` (along the specified axis, if provided, or in the flattened array) that result in the unique array. return_inverse : bool, optional If True, also return the indices of the unique array (for the specified axis, if provided) that can be used to reconstruct `ar`. return_counts : bool, optional If True, also return the number of times each unique item appears in `ar`. .. versionadded:: 1.9.0 axis : int or None, optional The axis to operate on. If None, `ar` will be flattened. If an integer, the subarrays indexed by the given axis will be flattened and treated as the elements of a 1-D array with the dimension of the given axis, see the notes for more details. Object arrays or structured arrays that contain objects are not supported if the `axis` kwarg is used. The default is None. .. versionadded:: 1.13.0 Returns ------- unique : ndarray The sorted unique values. unique_indices : ndarray, optional The indices of the first occurrences of the unique values in the original array. Only provided if `return_index` is True. unique_inverse : ndarray, optional The indices to reconstruct the original array from the unique array. Only provided if `return_inverse` is True. unique_counts : ndarray, optional The number of times each of the unique values comes up in the original array. Only provided if `return_counts` is True. .. versionadded:: 1.9.0 See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. repeat : Repeat elements of an array. Notes ----- When an axis is specified the subarrays indexed by the axis are sorted. This is done by making the specified axis the first dimension of the array (move the axis to the first dimension to keep the order of the other axes) and then flattening the subarrays in C order. The flattened subarrays are then viewed as a structured type with each element given a label, with the effect that we end up with a 1-D array of structured types that can be treated in the same way as any other 1-D array. The result is that the flattened subarrays are sorted in lexicographic order starting with the first element. Examples -------- >>> np.unique([1, 1, 2, 2, 3, 3]) array([1, 2, 3]) >>> a = np.array([[1, 1], [2, 3]]) >>> np.unique(a) array([1, 2, 3]) Return the unique rows of a 2D array >>> a = np.array([[1, 0, 0], [1, 0, 0], [2, 3, 4]]) >>> np.unique(a, axis=0) array([[1, 0, 0], [2, 3, 4]]) Return the indices of the original array that give the unique values: >>> a = np.array(['a', 'b', 'b', 'c', 'a']) >>> u, indices = np.unique(a, return_index=True) >>> u array(['a', 'b', 'c'], dtype='>> indices array([0, 1, 3]) >>> a[indices] array(['a', 'b', 'c'], dtype='>> a = np.array([1, 2, 6, 4, 2, 3, 2]) >>> u, indices = np.unique(a, return_inverse=True) >>> u array([1, 2, 3, 4, 6]) >>> indices array([0, 1, 4, 3, 1, 2, 1]) >>> u[indices] array([1, 2, 6, 4, 2, 3, 2]) Reconstruct the input values from the unique values and counts: >>> a = np.array([1, 2, 6, 4, 2, 3, 2]) >>> values, counts = np.unique(a, return_counts=True) >>> values array([1, 2, 3, 4, 6]) >>> counts array([1, 3, 1, 1, 1]) >>> np.repeat(values, counts) array([1, 2, 2, 2, 3, 4, 6]) # original order not preserved " :arglists '[[& [args {:as kwargs}]]]} unique (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "unique")))) (def ^{:doc " Return the minimum of an array or minimum along an axis. Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional Axis or axes along which to operate. By default, flattened input is used. .. versionadded:: 1.7.0 If this is a tuple of ints, the minimum is selected over multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See :ref:`ufuncs-output-type` for more details. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `amin` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. initial : scalar, optional The maximum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.15.0 where : array_like of bool, optional Elements to compare for the minimum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.17.0 Returns ------- amin : ndarray or scalar Minimum of `a`. If `axis` is None, the result is a scalar value. If `axis` is given, the result is an array of dimension ``a.ndim - 1``. See Also -------- amax : The maximum value of an array along a given axis, propagating any NaNs. nanmin : The minimum value of an array along a given axis, ignoring any NaNs. minimum : Element-wise minimum of two arrays, propagating any NaNs. fmin : Element-wise minimum of two arrays, ignoring any NaNs. argmin : Return the indices of the minimum values. nanmax, maximum, fmax Notes ----- NaN values are propagated, that is if at least one item is NaN, the corresponding min value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmin. Don't use `amin` for element-wise comparison of 2 arrays; when ``a.shape[0]`` is 2, ``minimum(a[0], a[1])`` is faster than ``amin(a, axis=0)``. Examples -------- >>> a = np.arange(4).reshape((2,2)) >>> a array([[0, 1], [2, 3]]) >>> np.amin(a) # Minimum of the flattened array 0 >>> np.amin(a, axis=0) # Minima along the first axis array([0, 1]) >>> np.amin(a, axis=1) # Minima along the second axis array([0, 2]) >>> np.amin(a, where=[False, True], initial=10, axis=0) array([10, 1]) >>> b = np.arange(5, dtype=float) >>> b[2] = np.NaN >>> np.amin(b) nan >>> np.amin(b, where=~np.isnan(b), initial=10) 0.0 >>> np.nanmin(b) 0.0 >>> np.min([[-50], [10]], axis=-1, initial=0) array([-50, 0]) Notice that the initial value is used as one of the elements for which the minimum is determined, unlike for the default argument Python's max function, which is only used for empty iterables. Notice that this isn't the same as Python's ``default`` argument. >>> np.min([6], initial=5) 5 >>> min([6], default=5) 6 " :arglists '[[& [args {:as kwargs}]]]} min (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "min")))) (def ^{:doc " Compute the bi-dimensional histogram of two data samples. Parameters ---------- x : array_like, shape (N,) An array containing the x coordinates of the points to be histogrammed. y : array_like, shape (N,) An array containing the y coordinates of the points to be histogrammed. bins : int or array_like or [int, int] or [array, array], optional The bin specification: * If int, the number of bins for the two dimensions (nx=ny=bins). * If array_like, the bin edges for the two dimensions (x_edges=y_edges=bins). * If [int, int], the number of bins in each dimension (nx, ny = bins). * If [array, array], the bin edges in each dimension (x_edges, y_edges = bins). * A combination [int, array] or [array, int], where int is the number of bins and array is the bin edges. range : array_like, shape(2,2), optional The leftmost and rightmost edges of the bins along each dimension (if not specified explicitly in the `bins` parameters): ``[[xmin, xmax], [ymin, ymax]]``. All values outside of this range will be considered outliers and not tallied in the histogram. density : bool, optional If False, the default, returns the number of samples in each bin. If True, returns the probability *density* function at the bin, ``bin_count / sample_count / bin_area``. normed : bool, optional An alias for the density argument that behaves identically. To avoid confusion with the broken normed argument to `histogram`, `density` should be preferred. weights : array_like, shape(N,), optional An array of values ``w_i`` weighing each sample ``(x_i, y_i)``. Weights are normalized to 1 if `normed` is True. If `normed` is False, the values of the returned histogram are equal to the sum of the weights belonging to the samples falling into each bin. Returns ------- H : ndarray, shape(nx, ny) The bi-dimensional histogram of samples `x` and `y`. Values in `x` are histogrammed along the first dimension and values in `y` are histogrammed along the second dimension. xedges : ndarray, shape(nx+1,) The bin edges along the first dimension. yedges : ndarray, shape(ny+1,) The bin edges along the second dimension. See Also -------- histogram : 1D histogram histogramdd : Multidimensional histogram Notes ----- When `normed` is True, then the returned histogram is the sample density, defined such that the sum over bins of the product ``bin_value * bin_area`` is 1. Please note that the histogram does not follow the Cartesian convention where `x` values are on the abscissa and `y` values on the ordinate axis. Rather, `x` is histogrammed along the first dimension of the array (vertical), and `y` along the second dimension of the array (horizontal). This ensures compatibility with `histogramdd`. Examples -------- >>> from matplotlib.image import NonUniformImage >>> import matplotlib.pyplot as plt Construct a 2-D histogram with variable bin width. First define the bin edges: >>> xedges = [0, 1, 3, 5] >>> yedges = [0, 2, 3, 4, 6] Next we create a histogram H with random bin content: >>> x = np.random.normal(2, 1, 100) >>> y = np.random.normal(1, 1, 100) >>> H, xedges, yedges = np.histogram2d(x, y, bins=(xedges, yedges)) >>> H = H.T # Let each row list bins with common y range. :func:`imshow ` can only display square bins: >>> fig = plt.figure(figsize=(7, 3)) >>> ax = fig.add_subplot(131, title='imshow: square bins') >>> plt.imshow(H, interpolation='nearest', origin='lower', ... extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]]) :func:`pcolormesh ` can display actual edges: >>> ax = fig.add_subplot(132, title='pcolormesh: actual edges', ... aspect='equal') >>> X, Y = np.meshgrid(xedges, yedges) >>> ax.pcolormesh(X, Y, H) :class:`NonUniformImage ` can be used to display actual bin edges with interpolation: >>> ax = fig.add_subplot(133, title='NonUniformImage: interpolated', ... aspect='equal', xlim=xedges[[0, -1]], ylim=yedges[[0, -1]]) >>> im = NonUniformImage(ax, interpolation='bilinear') >>> xcenters = (xedges[:-1] + xedges[1:]) / 2 >>> ycenters = (yedges[:-1] + yedges[1:]) / 2 >>> im.set_data(xcenters, ycenters, H) >>> ax.images.append(im) >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} histogram2d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "histogram2d")))) (def ^{:doc " Return a string representation of the data in an array. The data in the array is returned as a single string. This function is similar to `array_repr`, the difference being that `array_repr` also returns information on the kind of array and its data type. Parameters ---------- a : ndarray Input array. max_line_width : int, optional Inserts newlines if text is longer than `max_line_width`. Defaults to ``numpy.get_printoptions()['linewidth']``. precision : int, optional Floating point precision. Defaults to ``numpy.get_printoptions()['precision']``. suppress_small : bool, optional Represent numbers \"very close\" to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to ``numpy.get_printoptions()['suppress']``. See Also -------- array2string, array_repr, set_printoptions Examples -------- >>> np.array_str(np.arange(3)) '[0 1 2]' " :arglists '[[& [args {:as kwargs}]]]} array_str (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "array_str")))) (def ^{:doc ""} SHIFT_INVALID 9) (def ^{:doc "zeros(shape, dtype=float, order='C', *, like=None) 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 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', ' new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)"} sctypes (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* "sctypes")))) (def ^{:doc "invert(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute bit-wise inversion, or bit-wise NOT, element-wise. Computes the bit-wise NOT of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``~``. For signed integer inputs, the two's complement is returned. In a two's-complement system negative numbers are represented by the two's complement of the absolute value. This is the most common method of representing signed integers on computers [1]_. A N-bit two's-complement system can represent every integer in the range :math:`-2^{N-1}` to :math:`+2^{N-1}-1`. Parameters ---------- x : array_like Only integer and boolean types are handled. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Result. This is a scalar if `x` is a scalar. See Also -------- bitwise_and, bitwise_or, bitwise_xor logical_not binary_repr : Return the binary representation of the input number as a string. Notes ----- `bitwise_not` is an alias for `invert`: >>> np.bitwise_not is np.invert True References ---------- .. [1] Wikipedia, \"Two's complement\", https://en.wikipedia.org/wiki/Two's_complement Examples -------- We've seen that 13 is represented by ``00001101``. The invert or bit-wise NOT of 13 is then: >>> x = np.invert(np.array(13, dtype=np.uint8)) >>> x 242 >>> np.binary_repr(x, width=8) '11110010' The result depends on the bit-width: >>> x = np.invert(np.array(13, dtype=np.uint16)) >>> x 65522 >>> np.binary_repr(x, width=16) '1111111111110010' When using signed integer types the result is the two's complement of the result for the unsigned type: >>> np.invert(np.array([13], dtype=np.int8)) array([-14], dtype=int8) >>> np.binary_repr(-14, width=8) '11110010' Booleans are accepted as well: >>> np.invert(np.array([True, False])) array([False, True]) The ``~`` operator can be used as a shorthand for ``np.invert`` on ndarrays. >>> x1 = np.array([True, False]) >>> ~x1 array([False, True])" :arglists '[[self & [args {:as kwargs}]]]} invert (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "invert")))) (def ^{:doc "floor_divide(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the largest integer smaller or equal to the division of the inputs. It is equivalent to the Python ``//`` operator and pairs with the Python ``%`` (`remainder`), function so that ``a = a % b + b * (a // b)`` up to roundoff. Parameters ---------- x1 : array_like Numerator. x2 : array_like Denominator. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray y = floor(`x1`/`x2`) This is a scalar if both `x1` and `x2` are scalars. See Also -------- remainder : Remainder complementary to floor_divide. divmod : Simultaneous floor division and remainder. divide : Standard division. floor : Round a number to the nearest integer toward minus infinity. ceil : Round a number to the nearest integer toward infinity. Examples -------- >>> np.floor_divide(7,3) 2 >>> np.floor_divide([1., 2., 3., 4.], 2.5) array([ 0., 0., 1., 1.]) The ``//`` operator can be used as a shorthand for ``np.floor_divide`` on ndarrays. >>> x1 = np.array([1., 2., 3., 4.]) >>> x1 // 2.5 array([0., 0., 1., 1.])" :arglists '[[self & [args {:as kwargs}]]]} floor_divide (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "floor_divide")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned long``. :Character code: ``'L'`` :Canonical name: `numpy.uint` :Alias on this platform: `numpy.uint64`: 64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``). :Alias on this platform: `numpy.uintp`: Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``." :arglists '[[self & [args {:as kwargs}]]]} uint0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uint0")))) (def ^{:doc " ============================ ``ctypes`` Utility Functions ============================ See Also --------- load_library : Load a C library. ndpointer : Array restype/argtype with verification. as_ctypes : Create a ctypes array from an ndarray. as_array : Create an ndarray from a ctypes array. References ---------- .. [1] \"SciPy Cookbook: ctypes\", https://scipy-cookbook.readthedocs.io/items/Ctypes.html Examples -------- Load the C library: >>> _lib = np.ctypeslib.load_library('libmystuff', '.') #doctest: +SKIP Our result type, an ndarray that must be of type double, be 1-dimensional and is C-contiguous in memory: >>> array_1d_double = np.ctypeslib.ndpointer( ... dtype=np.double, ... ndim=1, flags='CONTIGUOUS') #doctest: +SKIP Our C-function typically takes an array and updates its values in-place. For example:: void foo_func(double* x, int length) { int i; for (i = 0; i < length; i++) { x[i] = i*i; } } We wrap it using: >>> _lib.foo_func.restype = None #doctest: +SKIP >>> _lib.foo_func.argtypes = [array_1d_double, c_int] #doctest: +SKIP Then, we're ready to call ``foo_func``: >>> out = np.empty(15, dtype=np.double) >>> _lib.foo_func(out, len(out)) #doctest: +SKIP "} ctypeslib (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "ctypeslib")))) (def ^{:doc "Boolean type (True or False), stored as a byte. .. warning:: The :class:`bool_` type is not a subclass of the :class:`int_` type (the :class:`bool_` is not even a number type). This is different than Python's default implementation of :class:`bool` as a sub-class of :class:`int`. :Character code: ``'?'`` :Alias: `numpy.bool8`" :arglists '[[self & [args {:as kwargs}]]]} bool_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bool_")))) (def ^{:doc "Either an opaque sequence of bytes, or a structure. >>> np.void(b'abcd') void(b'\\x61\\x62\\x63\\x64') Structured `void` scalars can only be constructed via extraction from :ref:`structured_arrays`: >>> arr = np.array((1, 2), dtype=[('x', np.int8), ('y', np.int8)]) >>> arr[()] (1, 2) # looks like a tuple, but is `np.void` :Character code: ``'V'``" :arglists '[[self & [args {:as kwargs}]]]} void0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "void0")))) (def ^{:doc "A byte string. When used in arrays, this type strips trailing null bytes. :Character code: ``'S'`` :Alias: `numpy.string_`" :arglists '[[self & [args {:as kwargs}]]]} bytes_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bytes_")))) (def ^{:doc " Set how floating-point errors are handled. Note that operations on integer scalar types (such as `int16`) are handled like floating point, and are affected by these settings. Parameters ---------- all : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional Set treatment for all types of floating-point errors at once: - ignore: Take no action when the exception occurs. - warn: Print a `RuntimeWarning` (via the Python `warnings` module). - raise: Raise a `FloatingPointError`. - call: Call a function specified using the `seterrcall` function. - print: Print a warning directly to ``stdout``. - log: Record error in a Log object specified by `seterrcall`. The default is not to change the current behavior. divide : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional Treatment for division by zero. over : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional Treatment for floating-point overflow. under : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional Treatment for floating-point underflow. invalid : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional Treatment for invalid floating-point operation. Returns ------- old_settings : dict Dictionary containing the old settings. See also -------- seterrcall : Set a callback function for the 'call' mode. geterr, geterrcall, errstate Notes ----- The floating-point exceptions are defined in the IEEE 754 standard [1]_: - Division by zero: infinite result obtained from finite numbers. - Overflow: result too large to be expressed. - Underflow: result so close to zero that some precision was lost. - Invalid operation: result is not an expressible number, typically indicates that a NaN was produced. .. [1] https://en.wikipedia.org/wiki/IEEE_754 Examples -------- >>> old_settings = np.seterr(all='ignore') #seterr to known value >>> np.seterr(over='raise') {'divide': 'ignore', 'over': 'ignore', 'under': 'ignore', 'invalid': 'ignore'} >>> np.seterr(**old_settings) # reset to default {'divide': 'ignore', 'over': 'raise', 'under': 'ignore', 'invalid': 'ignore'} >>> np.int16(32000) * np.int16(3) 30464 >>> old_settings = np.seterr(all='warn', over='raise') >>> np.int16(32000) * np.int16(3) Traceback (most recent call last): File \"\", line 1, in FloatingPointError: overflow encountered in short_scalars >>> from collections import OrderedDict >>> old_settings = np.seterr(all='print') >>> OrderedDict(np.geterr()) OrderedDict([('divide', 'print'), ('over', 'print'), ('under', 'print'), ('invalid', 'print')]) >>> np.int16(32000) * np.int16(3) 30464 " :arglists '[[& [{all :all, divide :divide, over :over, under :under, invalid :invalid}]] [& [{all :all, divide :divide, over :over, under :under}]] [& [{all :all, divide :divide, over :over}]] [& [{all :all, divide :divide}]] [& [{all :all}]] []]} seterr (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "seterr")))) (def ^{:doc ""} ERR_CALL 3) (def ^{:doc "isinf(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Test element-wise for positive or negative infinity. Returns a boolean array of the same shape as `x`, True where ``x == +/-inf``, otherwise False. Parameters ---------- x : array_like Input values out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : bool (scalar) or boolean ndarray True where ``x`` is positive or negative infinity, false otherwise. This is a scalar if `x` is a scalar. See Also -------- isneginf, isposinf, isnan, isfinite Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). Errors result if the second argument is supplied when the first argument is a scalar, or if the first and second arguments have different shapes. Examples -------- >>> np.isinf(np.inf) True >>> np.isinf(np.nan) False >>> np.isinf(np.NINF) True >>> np.isinf([np.inf, -np.inf, 1.0, np.nan]) array([ True, True, False, False]) >>> x = np.array([-np.inf, 0., np.inf]) >>> y = np.array([2, 2, 2]) >>> np.isinf(x, y) array([1, 0, 1]) >>> y array([1, 0, 1])" :arglists '[[self & [args {:as kwargs}]]]} isinf (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isinf")))) (def ^{:doc "Built-in immutable sequence. If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items. If the argument is a tuple, the return value is the same object."} kernel_version (as-jvm/generic-python-as-list (py-global-delay (py/get-attr @src-obj* "kernel_version")))) (def ^{:doc "spacing(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the distance between x and the nearest adjacent number. Parameters ---------- x : array_like Values to find the spacing of. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar The spacing of values of `x`. This is a scalar if `x` is a scalar. Notes ----- It can be considered as a generalization of EPS: ``spacing(np.float64(1)) == np.finfo(np.float64).eps``, and there should not be any representable number between ``x + spacing(x)`` and x for any finite x. Spacing of +- inf and NaN is NaN. Examples -------- >>> np.spacing(1) == np.finfo(np.float64).eps True" :arglists '[[self & [args {:as kwargs}]]]} spacing (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "spacing")))) (def ^{:doc "Double-precision floating-point number type, compatible with Python `float` and C ``double``. :Character code: ``'d'`` :Canonical name: `numpy.double` :Alias: `numpy.float_` :Alias on this platform: `numpy.float64`: 64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa." :arglists '[[self & [args {:as kwargs}]]]} float_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "float_")))) (def ^{:doc " Issued by `polyfit` when the Vandermonde matrix is rank deficient. For more information, a way to suppress the warning, and an example of `RankWarning` being issued, see `polyfit`. " :arglists '[[self & [args {:as kwargs}]]]} RankWarning (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "RankWarning")))) (def ^{:doc " Evaluate a polynomial at specific values. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. If `p` is of length N, this function returns the value: ``p[0]*x**(N-1) + p[1]*x**(N-2) + ... + p[N-2]*x + p[N-1]`` If `x` is a sequence, then `p(x)` is returned for each element of `x`. If `x` is another polynomial then the composite polynomial `p(x(t))` is returned. Parameters ---------- p : array_like or poly1d object 1D array of polynomial coefficients (including coefficients equal to zero) from highest degree to the constant term, or an instance of poly1d. x : array_like or poly1d object A number, an array of numbers, or an instance of poly1d, at which to evaluate `p`. Returns ------- values : ndarray or poly1d If `x` is a poly1d instance, the result is the composition of the two polynomials, i.e., `x` is \"substituted\" in `p` and the simplified result is returned. In addition, the type of `x` - array_like or poly1d - governs the type of the output: `x` array_like => `values` array_like, `x` a poly1d object => `values` is also. See Also -------- poly1d: A polynomial class. Notes ----- Horner's scheme [1]_ is used to evaluate the polynomial. Even so, for polynomials of high degree the values may be inaccurate due to rounding errors. Use carefully. If `x` is a subtype of `ndarray` the return value will be of the same type. References ---------- .. [1] I. N. Bronshtein, K. A. Semendyayev, and K. A. Hirsch (Eng. trans. Ed.), *Handbook of Mathematics*, New York, Van Nostrand Reinhold Co., 1985, pg. 720. Examples -------- >>> np.polyval([3,0,1], 5) # 3 * 5**2 + 0 * 5**1 + 1 76 >>> np.polyval([3,0,1], np.poly1d(5)) poly1d([76]) >>> np.polyval(np.poly1d([3,0,1]), 5) 76 >>> np.polyval(np.poly1d([3,0,1]), np.poly1d(5)) poly1d([76]) " :arglists '[[& [args {:as kwargs}]]]} polyval (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polyval")))) (def ^{:doc " Translates slice objects to concatenation along the first axis. This is a simple way to build up arrays quickly. There are two use cases. 1. If the index expression contains comma separated arrays, then stack them along their first axis. 2. If the index expression contains slice notation or scalars then create a 1-D array with a range indicated by the slice notation. If slice notation is used, the syntax ``start:stop:step`` is equivalent to ``np.arange(start, stop, step)`` inside of the brackets. However, if ``step`` is an imaginary number (i.e. 100j) then its integer portion is interpreted as a number-of-points desired and the start and stop are inclusive. In other words ``start:stop:stepj`` is interpreted as ``np.linspace(start, stop, step, endpoint=1)`` inside of the brackets. After expansion of slice notation, all comma separated sequences are concatenated together. Optional character strings placed as the first element of the index expression can be used to change the output. The strings 'r' or 'c' result in matrix output. If the result is 1-D and 'r' is specified a 1 x N (row) matrix is produced. If the result is 1-D and 'c' is specified, then a N x 1 (column) matrix is produced. If the result is 2-D then both provide the same matrix result. A string integer specifies which axis to stack multiple comma separated arrays along. A string of two comma-separated integers allows indication of the minimum number of dimensions to force each entry into as the second integer (the axis to concatenate along is still the first integer). A string with three comma-separated integers allows specification of the axis to concatenate along, the minimum number of dimensions to force the entries to, and which axis should contain the start of the arrays which are less than the specified number of dimensions. In other words the third integer allows you to specify where the 1's should be placed in the shape of the arrays that have their shapes upgraded. By default, they are placed in the front of the shape tuple. The third argument allows you to specify where the start of the array should be instead. Thus, a third argument of '0' would place the 1's at the end of the array shape. Negative integers specify where in the new shape tuple the last dimension of upgraded arrays should be placed, so the default is '-1'. Parameters ---------- Not a function, so takes no parameters Returns ------- A concatenated ndarray or matrix. See Also -------- concatenate : Join a sequence of arrays along an existing axis. c_ : Translates slice objects to concatenation along the second axis. Examples -------- >>> np.r_[np.array([1,2,3]), 0, 0, np.array([4,5,6])] array([1, 2, 3, ..., 4, 5, 6]) >>> np.r_[-1:1:6j, [0]*3, 5, 6] array([-1. , -0.6, -0.2, 0.2, 0.6, 1. , 0. , 0. , 0. , 5. , 6. ]) String integers specify the axis to concatenate along or the minimum number of dimensions to force entries into. >>> a = np.array([[0, 1, 2], [3, 4, 5]]) >>> np.r_['-1', a, a] # concatenate along last axis array([[0, 1, 2, 0, 1, 2], [3, 4, 5, 3, 4, 5]]) >>> np.r_['0,2', [1,2,3], [4,5,6]] # concatenate along first axis, dim>=2 array([[1, 2, 3], [4, 5, 6]]) >>> np.r_['0,2,0', [1,2,3], [4,5,6]] array([[1], [2], [3], [4], [5], [6]]) >>> np.r_['1,2,0', [1,2,3], [4,5,6]] array([[1, 4], [2, 5], [3, 6]]) Using 'r' or 'c' as a first string argument creates a matrix. >>> np.r_['r',[1,2,3], [4,5,6]] matrix([[1, 2, 3, 4, 5, 6]]) "} r_ (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "r_")))) (def ^{:doc " An N-dimensional iterator object to index arrays. Given the shape of an array, an `ndindex` instance iterates over the N-dimensional index of the array. At each iteration a tuple of indices is returned, the last dimension is iterated over first. Parameters ---------- shape : ints, or a single tuple of ints The size of each dimension of the array can be passed as individual parameters or as the elements of a tuple. See Also -------- ndenumerate, flatiter Examples -------- # dimensions as individual arguments >>> for index in np.ndindex(3, 2, 1): ... print(index) (0, 0, 0) (0, 1, 0) (1, 0, 0) (1, 1, 0) (2, 0, 0) (2, 1, 0) # same dimensions - but in a tuple (3, 2, 1) >>> for index in np.ndindex((3, 2, 1)): ... print(index) (0, 0, 0) (0, 1, 0) (1, 0, 0) (1, 1, 0) (2, 0, 0) (2, 1, 0) " :arglists '[[self & [shape]]]} ndindex (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ndindex")))) (def ^{:doc ""} infty ##Inf) (def ^{:doc " Issues a DeprecationWarning, adds warning to `old_name`'s docstring, rebinds ``old_name.__name__`` and returns the new function object. This function may also be used as a decorator. Parameters ---------- func : function The function to be deprecated. old_name : str, optional The name of the function to be deprecated. Default is None, in which case the name of `func` is used. new_name : str, optional The new name for the function. Default is None, in which case the deprecation message is that `old_name` is deprecated. If given, the deprecation message is that `old_name` is deprecated and `new_name` should be used instead. message : str, optional Additional explanation of the deprecation. Displayed in the docstring after the warning. Returns ------- old_func : function The deprecated function. Examples -------- Note that ``olduint`` returns a value after printing Deprecation Warning: >>> olduint = np.deprecate(np.uint) DeprecationWarning: `uint64` is deprecated! # may vary >>> olduint(6) 6 " :arglists '[[& [args {:as kwargs}]]]} deprecate (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "deprecate")))) (def ^{:doc " Set printing options. These options determine the way floating point numbers, arrays and other NumPy objects are displayed. Parameters ---------- precision : int or None, optional Number of digits of precision for floating point output (default 8). May be None if `floatmode` is not `fixed`, to print as many digits as necessary to uniquely specify the value. threshold : int, optional Total number of array elements which trigger summarization rather than full repr (default 1000). To always use the full repr without summarization, pass `sys.maxsize`. edgeitems : int, optional Number of array items in summary at beginning and end of each dimension (default 3). linewidth : int, optional The number of characters per line for the purpose of inserting line breaks (default 75). suppress : bool, optional If True, always print floating point numbers using fixed point notation, in which case numbers equal to zero in the current precision will print as zero. If False, then scientific notation is used when absolute value of the smallest number is < 1e-4 or the ratio of the maximum absolute value to the minimum is > 1e3. The default is False. nanstr : str, optional String representation of floating point not-a-number (default nan). infstr : str, optional String representation of floating point infinity (default inf). sign : string, either '-', '+', or ' ', optional Controls printing of the sign of floating-point types. If '+', always print the sign of positive values. If ' ', always prints a space (whitespace character) in the sign position of positive values. If '-', omit the sign character of positive values. (default '-') formatter : dict of callables, optional If not None, the keys should indicate the type(s) that the respective formatting function applies to. Callables should return a string. Types that are not specified (by their corresponding keys) are handled by the default formatters. Individual types for which a formatter can be set are: - 'bool' - 'int' - 'timedelta' : a `numpy.timedelta64` - 'datetime' : a `numpy.datetime64` - 'float' - 'longfloat' : 128-bit floats - 'complexfloat' - 'longcomplexfloat' : composed of two 128-bit floats - 'numpystr' : types `numpy.string_` and `numpy.unicode_` - 'object' : `np.object_` arrays - 'str' : all other strings Other keys that can be used to set a group of types at once are: - 'all' : sets all types - 'int_kind' : sets 'int' - 'float_kind' : sets 'float' and 'longfloat' - 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat' - 'str_kind' : sets 'str' and 'numpystr' floatmode : str, optional Controls the interpretation of the `precision` option for floating-point types. Can take the following values (default maxprec_equal): * 'fixed': Always print exactly `precision` fractional digits, even if this would print more or fewer digits than necessary to specify the value uniquely. * 'unique': Print the minimum number of fractional digits necessary to represent each value uniquely. Different elements may have a different number of digits. The value of the `precision` option is ignored. * 'maxprec': Print at most `precision` fractional digits, but if an element can be uniquely represented with fewer digits only print it with that many. * 'maxprec_equal': Print at most `precision` fractional digits, but if every element in the array can be uniquely represented with an equal number of fewer digits, use that many digits for all elements. legacy : string or `False`, optional If set to the string `'1.13'` enables 1.13 legacy printing mode. This approximates numpy 1.13 print output by including a space in the sign position of floats and different behavior for 0d arrays. If set to `False`, disables legacy mode. Unrecognized strings will be ignored with a warning for forward compatibility. .. versionadded:: 1.14.0 See Also -------- get_printoptions, printoptions, set_string_function, array2string Notes ----- `formatter` is always reset with a call to `set_printoptions`. Use `printoptions` as a context manager to set the values temporarily. Examples -------- Floating point precision can be set: >>> np.set_printoptions(precision=4) >>> np.array([1.123456789]) [1.1235] Long arrays can be summarised: >>> np.set_printoptions(threshold=5) >>> np.arange(10) array([0, 1, 2, ..., 7, 8, 9]) Small results can be suppressed: >>> eps = np.finfo(float).eps >>> x = np.arange(4.) >>> x**2 - (x + eps)**2 array([-4.9304e-32, -4.4409e-16, 0.0000e+00, 0.0000e+00]) >>> np.set_printoptions(suppress=True) >>> x**2 - (x + eps)**2 array([-0., -0., 0., 0.]) A custom formatter can be used to display array elements as desired: >>> np.set_printoptions(formatter={'all':lambda x: 'int: '+str(-x)}) >>> x = np.arange(3) >>> x array([int: 0, int: -1, int: -2]) >>> np.set_printoptions() # formatter gets reset >>> x array([0, 1, 2]) To put back the default options, you can use: >>> np.set_printoptions(edgeitems=3, infstr='inf', ... linewidth=75, nanstr='nan', precision=8, ... suppress=False, threshold=1000, formatter=None) Also to temporarily override options, use `printoptions` as a context manager: >>> with np.printoptions(precision=2, suppress=True, threshold=5): ... np.linspace(0, 10, 10) array([ 0. , 1.11, 2.22, ..., 7.78, 8.89, 10. ]) " :arglists '[[& [{legacy :legacy, infstr :infstr, linewidth :linewidth, suppress :suppress, sign :sign, formatter :formatter, precision :precision, floatmode :floatmode, edgeitems :edgeitems, threshold :threshold, nanstr :nanstr}]] [& [{legacy :legacy, infstr :infstr, linewidth :linewidth, suppress :suppress, sign :sign, formatter :formatter, precision :precision, edgeitems :edgeitems, threshold :threshold, nanstr :nanstr}]] [& [{legacy :legacy, infstr :infstr, linewidth :linewidth, suppress :suppress, formatter :formatter, precision :precision, edgeitems :edgeitems, threshold :threshold, nanstr :nanstr}]] [& [{precision :precision, threshold :threshold, edgeitems :edgeitems, linewidth :linewidth, suppress :suppress, nanstr :nanstr, infstr :infstr, legacy :legacy}]] [& [{precision :precision, threshold :threshold, edgeitems :edgeitems, linewidth :linewidth, suppress :suppress, nanstr :nanstr, legacy :legacy}]] [& [{precision :precision, threshold :threshold, edgeitems :edgeitems, linewidth :linewidth, suppress :suppress, legacy :legacy}]] [& [{precision :precision, threshold :threshold, edgeitems :edgeitems, linewidth :linewidth, legacy :legacy}]] [& [{precision :precision, threshold :threshold, edgeitems :edgeitems, legacy :legacy}]] [& [{precision :precision, threshold :threshold, legacy :legacy}]] [& [{precision :precision, legacy :legacy}]] [& [{legacy :legacy}]]]} set_printoptions (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "set_printoptions")))) (def ^{:doc " Pad an array. Parameters ---------- array : array_like of rank N The array to pad. pad_width : {sequence, array_like, int} Number of values padded to the edges of each axis. ((before_1, after_1), ... (before_N, after_N)) unique pad widths for each axis. ((before, after),) yields same before and after pad for each axis. (pad,) or int is a shortcut for before = after = pad width for all axes. mode : str or function, optional One of the following string values or a user supplied function. 'constant' (default) Pads with a constant value. 'edge' Pads with the edge values of array. 'linear_ramp' Pads with the linear ramp between end_value and the array edge value. 'maximum' Pads with the maximum value of all or part of the vector along each axis. 'mean' Pads with the mean value of all or part of the vector along each axis. 'median' Pads with the median value of all or part of the vector along each axis. 'minimum' Pads with the minimum value of all or part of the vector along each axis. 'reflect' Pads with the reflection of the vector mirrored on the first and last values of the vector along each axis. 'symmetric' Pads with the reflection of the vector mirrored along the edge of the array. 'wrap' Pads with the wrap of the vector along the axis. The first values are used to pad the end and the end values are used to pad the beginning. 'empty' Pads with undefined values. .. versionadded:: 1.17 Padding function, see Notes. stat_length : sequence or int, optional Used in 'maximum', 'mean', 'median', and 'minimum'. Number of values at edge of each axis used to calculate the statistic value. ((before_1, after_1), ... (before_N, after_N)) unique statistic lengths for each axis. ((before, after),) yields same before and after statistic lengths for each axis. (stat_length,) or int is a shortcut for before = after = statistic length for all axes. Default is ``None``, to use the entire axis. constant_values : sequence or scalar, optional Used in 'constant'. The values to set the padded values for each axis. ``((before_1, after_1), ... (before_N, after_N))`` unique pad constants for each axis. ``((before, after),)`` yields same before and after constants for each axis. ``(constant,)`` or ``constant`` is a shortcut for ``before = after = constant`` for all axes. Default is 0. end_values : sequence or scalar, optional Used in 'linear_ramp'. The values used for the ending value of the linear_ramp and that will form the edge of the padded array. ``((before_1, after_1), ... (before_N, after_N))`` unique end values for each axis. ``((before, after),)`` yields same before and after end values for each axis. ``(constant,)`` or ``constant`` is a shortcut for ``before = after = constant`` for all axes. Default is 0. reflect_type : {'even', 'odd'}, optional Used in 'reflect', and 'symmetric'. The 'even' style is the default with an unaltered reflection around the edge value. For the 'odd' style, the extended part of the array is created by subtracting the reflected values from two times the edge value. Returns ------- pad : ndarray Padded array of rank equal to `array` with shape increased according to `pad_width`. Notes ----- .. versionadded:: 1.7.0 For an array with rank greater than 1, some of the padding of later axes is calculated from padding of previous axes. This is easiest to think about with a rank 2 array where the corners of the padded array are calculated by using padded values from the first axis. The padding function, if used, should modify a rank 1 array in-place. It has the following signature:: padding_func(vector, iaxis_pad_width, iaxis, kwargs) where vector : ndarray A rank 1 array already padded with zeros. Padded values are vector[:iaxis_pad_width[0]] and vector[-iaxis_pad_width[1]:]. iaxis_pad_width : tuple A 2-tuple of ints, iaxis_pad_width[0] represents the number of values padded at the beginning of vector where iaxis_pad_width[1] represents the number of values padded at the end of vector. iaxis : int The axis currently being calculated. kwargs : dict Any keyword arguments the function requires. Examples -------- >>> a = [1, 2, 3, 4, 5] >>> np.pad(a, (2, 3), 'constant', constant_values=(4, 6)) array([4, 4, 1, ..., 6, 6, 6]) >>> np.pad(a, (2, 3), 'edge') array([1, 1, 1, ..., 5, 5, 5]) >>> np.pad(a, (2, 3), 'linear_ramp', end_values=(5, -4)) array([ 5, 3, 1, 2, 3, 4, 5, 2, -1, -4]) >>> np.pad(a, (2,), 'maximum') array([5, 5, 1, 2, 3, 4, 5, 5, 5]) >>> np.pad(a, (2,), 'mean') array([3, 3, 1, 2, 3, 4, 5, 3, 3]) >>> np.pad(a, (2,), 'median') array([3, 3, 1, 2, 3, 4, 5, 3, 3]) >>> a = [[1, 2], [3, 4]] >>> np.pad(a, ((3, 2), (2, 3)), 'minimum') array([[1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1], [3, 3, 3, 4, 3, 3, 3], [1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1]]) >>> a = [1, 2, 3, 4, 5] >>> np.pad(a, (2, 3), 'reflect') array([3, 2, 1, 2, 3, 4, 5, 4, 3, 2]) >>> np.pad(a, (2, 3), 'reflect', reflect_type='odd') array([-1, 0, 1, 2, 3, 4, 5, 6, 7, 8]) >>> np.pad(a, (2, 3), 'symmetric') array([2, 1, 1, 2, 3, 4, 5, 5, 4, 3]) >>> np.pad(a, (2, 3), 'symmetric', reflect_type='odd') array([0, 1, 1, 2, 3, 4, 5, 5, 6, 7]) >>> np.pad(a, (2, 3), 'wrap') array([4, 5, 1, 2, 3, 4, 5, 1, 2, 3]) >>> def pad_with(vector, pad_width, iaxis, kwargs): ... pad_value = kwargs.get('padder', 10) ... vector[:pad_width[0]] = pad_value ... vector[-pad_width[1]:] = pad_value >>> a = np.arange(6) >>> a = a.reshape((2, 3)) >>> np.pad(a, 2, pad_with) array([[10, 10, 10, 10, 10, 10, 10], [10, 10, 10, 10, 10, 10, 10], [10, 10, 0, 1, 2, 10, 10], [10, 10, 3, 4, 5, 10, 10], [10, 10, 10, 10, 10, 10, 10], [10, 10, 10, 10, 10, 10, 10]]) >>> np.pad(a, 2, pad_with, padder=100) array([[100, 100, 100, 100, 100, 100, 100], [100, 100, 100, 100, 100, 100, 100], [100, 100, 0, 1, 2, 100, 100], [100, 100, 3, 4, 5, 100, 100], [100, 100, 100, 100, 100, 100, 100], [100, 100, 100, 100, 100, 100, 100]]) " :arglists '[[& [args {:as kwargs}]]]} pad (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "pad")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned long``. :Character code: ``'L'`` :Canonical name: `numpy.uint` :Alias on this platform: `numpy.uint64`: 64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``). :Alias on this platform: `numpy.uintp`: Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``." :arglists '[[self & [args {:as kwargs}]]]} Uint64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "Uint64")))) (def ^{:doc " Print the NumPy arrays in the given dictionary. If there is no dictionary passed in or `vardict` is None then returns NumPy arrays in the globals() dictionary (all NumPy arrays in the namespace). Parameters ---------- vardict : dict, optional A dictionary possibly containing ndarrays. Default is globals(). Returns ------- out : None Returns 'None'. Notes ----- Prints out the name, shape, bytes and type of all of the ndarrays present in `vardict`. Examples -------- >>> a = np.arange(10) >>> b = np.ones(20) >>> np.who() Name Shape Bytes Type =========================================================== a 10 80 int64 b 20 160 float64 Upper bound on total bytes = 240 >>> d = {'x': np.arange(2.0), 'y': np.arange(3.0), 'txt': 'Some str', ... 'idx':5} >>> np.who(d) Name Shape Bytes Type =========================================================== x 2 16 float64 y 3 24 float64 Upper bound on total bytes = 40 " :arglists '[[& [{vardict :vardict}]] []]} who (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "who")))) (def ^{:doc " Function to calculate only the edges of the bins used by the `histogram` function. Parameters ---------- a : array_like Input data. The histogram is computed over the flattened array. bins : int or sequence of scalars or str, optional If `bins` is an int, it defines the number of equal-width bins in the given range (10, by default). If `bins` is a sequence, it defines the bin edges, including the rightmost edge, allowing for non-uniform bin widths. If `bins` is a string from the list below, `histogram_bin_edges` will use the method chosen to calculate the optimal bin width and consequently the number of bins (see `Notes` for more detail on the estimators) from the data that falls within the requested range. While the bin width will be optimal for the actual data in the range, the number of bins will be computed to fill the entire range, including the empty portions. For visualisation, using the 'auto' option is suggested. Weighted data is not supported for automated bin size selection. 'auto' Maximum of the 'sturges' and 'fd' estimators. Provides good all around performance. 'fd' (Freedman Diaconis Estimator) Robust (resilient to outliers) estimator that takes into account data variability and data size. 'doane' An improved version of Sturges' estimator that works better with non-normal datasets. 'scott' Less robust estimator that that takes into account data variability and data size. 'stone' Estimator based on leave-one-out cross-validation estimate of the integrated squared error. Can be regarded as a generalization of Scott's rule. 'rice' Estimator does not take variability into account, only data size. Commonly overestimates number of bins required. 'sturges' R's default method, only accounts for data size. Only optimal for gaussian data and underestimates number of bins for large non-gaussian datasets. 'sqrt' Square root (of data size) estimator, used by Excel and other programs for its speed and simplicity. range : (float, float), optional The lower and upper range of the bins. If not provided, range is simply ``(a.min(), a.max())``. Values outside the range are ignored. The first element of the range must be less than or equal to the second. `range` affects the automatic bin computation as well. While bin width is computed to be optimal based on the actual data within `range`, the bin count will fill the entire range including portions containing no data. weights : array_like, optional An array of weights, of the same shape as `a`. Each value in `a` only contributes its associated weight towards the bin count (instead of 1). This is currently not used by any of the bin estimators, but may be in the future. Returns ------- bin_edges : array of dtype float The edges to pass into `histogram` See Also -------- histogram Notes ----- The methods to estimate the optimal number of bins are well founded in literature, and are inspired by the choices R provides for histogram visualisation. Note that having the number of bins proportional to :math:`n^{1/3}` is asymptotically optimal, which is why it appears in most estimators. These are simply plug-in methods that give good starting points for number of bins. In the equations below, :math:`h` is the binwidth and :math:`n_h` is the number of bins. All estimators that compute bin counts are recast to bin width using the `ptp` of the data. The final bin count is obtained from ``np.round(np.ceil(range / h))``. 'auto' (maximum of the 'sturges' and 'fd' estimators) A compromise to get a good value. For small datasets the Sturges value will usually be chosen, while larger datasets will usually default to FD. Avoids the overly conservative behaviour of FD and Sturges for small and large datasets respectively. Switchover point is usually :math:`a.size \\approx 1000`. 'fd' (Freedman Diaconis Estimator) .. math:: h = 2 \\frac{IQR}{n^{1/3}} The binwidth is proportional to the interquartile range (IQR) and inversely proportional to cube root of a.size. Can be too conservative for small datasets, but is quite good for large datasets. The IQR is very robust to outliers. 'scott' .. math:: h = \\sigma \\sqrt[3]{\\frac{24 * \\sqrt{\\pi}}{n}} The binwidth is proportional to the standard deviation of the data and inversely proportional to cube root of ``x.size``. Can be too conservative for small datasets, but is quite good for large datasets. The standard deviation is not very robust to outliers. Values are very similar to the Freedman-Diaconis estimator in the absence of outliers. 'rice' .. math:: n_h = 2n^{1/3} The number of bins is only proportional to cube root of ``a.size``. It tends to overestimate the number of bins and it does not take into account data variability. 'sturges' .. math:: n_h = \\log _{2}n+1 The number of bins is the base 2 log of ``a.size``. This estimator assumes normality of data and is too conservative for larger, non-normal datasets. This is the default method in R's ``hist`` method. 'doane' .. math:: n_h = 1 + \\log_{2}(n) + \\log_{2}(1 + \\frac{|g_1|}{\\sigma_{g_1}}) g_1 = mean[(\\frac{x - \\mu}{\\sigma})^3] \\sigma_{g_1} = \\sqrt{\\frac{6(n - 2)}{(n + 1)(n + 3)}} An improved version of Sturges' formula that produces better estimates for non-normal datasets. This estimator attempts to account for the skew of the data. 'sqrt' .. math:: n_h = \\sqrt n The simplest and fastest estimator. Only takes into account the data size. Examples -------- >>> arr = np.array([0, 0, 0, 1, 2, 3, 3, 4, 5]) >>> np.histogram_bin_edges(arr, bins='auto', range=(0, 1)) array([0. , 0.25, 0.5 , 0.75, 1. ]) >>> np.histogram_bin_edges(arr, bins=2) array([0. , 2.5, 5. ]) For consistency with histogram, an array of pre-computed bins is passed through unmodified: >>> np.histogram_bin_edges(arr, [1, 2]) array([1, 2]) This function allows one set of bins to be computed, and reused across multiple histograms: >>> shared_bins = np.histogram_bin_edges(arr, bins='auto') >>> shared_bins array([0., 1., 2., 3., 4., 5.]) >>> group_id = np.array([0, 1, 1, 0, 1, 1, 0, 1, 1]) >>> hist_0, _ = np.histogram(arr[group_id == 0], bins=shared_bins) >>> hist_1, _ = np.histogram(arr[group_id == 1], bins=shared_bins) >>> hist_0; hist_1 array([1, 1, 0, 1, 0]) array([2, 0, 1, 1, 2]) Which gives more easily comparable results than using separate bins for each histogram: >>> hist_0, bins_0 = np.histogram(arr[group_id == 0], bins='auto') >>> hist_1, bins_1 = np.histogram(arr[group_id == 1], bins='auto') >>> hist_0; hist_1 array([1, 1, 1]) array([2, 1, 1, 2]) >>> bins_0; bins_1 array([0., 1., 2., 3.]) array([0. , 1.25, 2.5 , 3.75, 5. ]) " :arglists '[[& [args {:as kwargs}]]]} histogram_bin_edges (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "histogram_bin_edges")))) (def ^{:doc " Compute the standard deviation along the specified axis. Returns the standard deviation, a measure of the spread of a distribution, of the array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis. Parameters ---------- a : array_like Calculate the standard deviation of these values. axis : None or int or tuple of ints, optional Axis or axes along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array. .. versionadded:: 1.7.0 If this is a tuple of ints, a standard deviation is performed over multiple axes, instead of a single axis or all the axes as before. dtype : dtype, optional Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary. ddof : int, optional Means Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. By default `ddof` is zero. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `std` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. where : array_like of bool, optional Elements to include in the standard deviation. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.20.0 Returns ------- standard_deviation : ndarray, see dtype parameter above. If `out` is None, return a new array containing the standard deviation, otherwise return a reference to the output array. See Also -------- var, mean, nanmean, nanstd, nanvar :ref:`ufuncs-output-type` Notes ----- The standard deviation is the square root of the average of the squared deviations from the mean, i.e., ``std = sqrt(mean(x))``, where ``x = abs(a - a.mean())**2``. The average squared deviation is typically calculated as ``x.sum() / N``, where ``N = len(x)``. If, however, `ddof` is specified, the divisor ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1`` provides an unbiased estimator of the variance of the infinite population. ``ddof=0`` provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ``ddof=1``, it will not be an unbiased estimate of the standard deviation per se. Note that, for complex numbers, `std` takes the absolute value before squaring, so that the result is always real and nonnegative. For floating-point input, the *std* is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the `dtype` keyword can alleviate this issue. Examples -------- >>> a = np.array([[1, 2], [3, 4]]) >>> np.std(a) 1.1180339887498949 # may vary >>> np.std(a, axis=0) array([1., 1.]) >>> np.std(a, axis=1) array([0.5, 0.5]) In single precision, std() can be inaccurate: >>> a = np.zeros((2, 512*512), dtype=np.float32) >>> a[0, :] = 1.0 >>> a[1, :] = 0.1 >>> np.std(a) 0.45000005 Computing the standard deviation in float64 is more accurate: >>> np.std(a, dtype=np.float64) 0.44999999925494177 # may vary Specifying a where argument: >>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]]) >>> np.std(a) 2.614064523559687 # may vary >>> np.std(a, where=[[True], [True], [False]]) 2.0 " :arglists '[[& [args {:as kwargs}]]]} std (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "std")))) (def ^{:doc " Test element-wise for negative infinity, return result as bool array. Parameters ---------- x : array_like The input array. out : array_like, optional A location into which the result is stored. If provided, it must have a shape that the input broadcasts to. If not provided or None, a freshly-allocated boolean array is returned. Returns ------- out : ndarray A boolean array with the same dimensions as the input. If second argument is not supplied then a numpy boolean array is returned with values True where the corresponding element of the input is negative infinity and values False where the element of the input is not negative infinity. If a second argument is supplied the result is stored there. If the type of that array is a numeric type the result is represented as zeros and ones, if the type is boolean then as False and True. The return value `out` is then a reference to that array. See Also -------- isinf, isposinf, isnan, isfinite Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). Errors result if the second argument is also supplied when x is a scalar input, if first and second arguments have different shapes, or if the first argument has complex values. Examples -------- >>> np.isneginf(np.NINF) True >>> np.isneginf(np.inf) False >>> np.isneginf(np.PINF) False >>> np.isneginf([-np.inf, 0., np.inf]) array([ True, False, False]) >>> x = np.array([-np.inf, 0., np.inf]) >>> y = np.array([2, 2, 2]) >>> np.isneginf(x, y) array([1, 0, 0]) >>> y array([1, 0, 0]) " :arglists '[[& [args {:as kwargs}]]]} isneginf (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isneginf")))) (def ^{:doc " Round to nearest integer towards zero. Round an array of floats element-wise to nearest integer towards zero. The rounded values are returned as floats. Parameters ---------- x : array_like An array of floats to be rounded out : ndarray, optional A location into which the result is stored. If provided, it must have a shape that the input broadcasts to. If not provided or None, a freshly-allocated array is returned. Returns ------- out : ndarray of floats A float array with the same dimensions as the input. If second argument is not supplied then a float array is returned with the rounded values. If a second argument is supplied the result is stored there. The return value `out` is then a reference to that array. See Also -------- trunc, floor, ceil around : Round to given number of decimals Examples -------- >>> np.fix(3.14) 3.0 >>> np.fix(3) 3.0 >>> np.fix([2.1, 2.9, -2.1, -2.9]) array([ 2., 2., -2., -2.]) " :arglists '[[& [args {:as kwargs}]]]} fix (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fix")))) (def ^{:doc " Return a new array of given shape and type, filled with ones. Parameters ---------- shape : int or sequence 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray Array of ones with the given shape, dtype, and order. See Also -------- ones_like : Return an array of ones with shape and type of input. empty : Return a new uninitialized array. zeros : Return a new array setting values to zero. full : Return a new array of given shape filled with value. Examples -------- >>> np.ones(5) array([1., 1., 1., 1., 1.]) >>> np.ones((5,), dtype=int) array([1, 1, 1, 1, 1]) >>> np.ones((2, 1)) array([[1.], [1.]]) >>> s = (2,2) >>> np.ones(s) array([[1., 1.], [1., 1.]]) " :arglists '[[shape & [{dtype :dtype, order :order, like :like}]] [shape & [{dtype :dtype, like :like}]] [shape & [{like :like}]]]} ones (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ones")))) (def ^{:doc " Remove axes of length one from `a`. Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional .. versionadded:: 1.7.0 Selects a subset of the entries of length one in the shape. If an axis is selected with shape entry greater than one, an error is raised. Returns ------- squeezed : ndarray The input array, but with all or a subset of the dimensions of length 1 removed. This is always `a` itself or a view into `a`. Note that if all axes are squeezed, the result is a 0d array and not a scalar. Raises ------ ValueError If `axis` is not None, and an axis being squeezed is not of length 1 See Also -------- expand_dims : The inverse operation, adding entries of length one reshape : Insert, remove, and combine dimensions, and resize existing ones Examples -------- >>> x = np.array([[[0], [1], [2]]]) >>> x.shape (1, 3, 1) >>> np.squeeze(x).shape (3,) >>> np.squeeze(x, axis=0).shape (3, 1) >>> np.squeeze(x, axis=1).shape Traceback (most recent call last): ... ValueError: cannot select an axis to squeeze out which has size not equal to one >>> np.squeeze(x, axis=2).shape (1, 3) >>> x = np.array([[1234]]) >>> x.shape (1, 1) >>> np.squeeze(x) array(1234) # 0d array >>> np.squeeze(x).shape () >>> np.squeeze(x)[()] 1234 " :arglists '[[& [args {:as kwargs}]]]} squeeze (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "squeeze")))) (def ^{:doc " Class to convert formats, names, titles description to a dtype. After constructing the format_parser object, the dtype attribute is the converted data-type: ``dtype = format_parser(formats, names, titles).dtype`` Attributes ---------- dtype : dtype The converted data-type. Parameters ---------- formats : str or list of str The format description, either specified as a string with comma-separated format descriptions in the form ``'f8, i4, a5'``, or a list of format description strings in the form ``['f8', 'i4', 'a5']``. names : str or list/tuple of str The field names, either specified as a comma-separated string in the form ``'col1, col2, col3'``, or as a list or tuple of strings in the form ``['col1', 'col2', 'col3']``. An empty list can be used, in that case default field names ('f0', 'f1', ...) are used. titles : sequence Sequence of title strings. An empty list can be used to leave titles out. aligned : bool, optional If True, align the fields by padding as the C-compiler would. Default is False. byteorder : str, optional If specified, all the fields will be changed to the provided byte-order. Otherwise, the default byte-order is used. For all available string specifiers, see `dtype.newbyteorder`. See Also -------- dtype, typename, sctype2char Examples -------- >>> np.format_parser(['>> np.format_parser(['f8', 'i4', 'a5'], ['col1', 'col2', 'col3'], ... []).dtype dtype([('col1', '>> np.format_parser(['>> f = np.array([1, 2, 4, 7, 11, 16], dtype=float) >>> np.gradient(f) array([1. , 1.5, 2.5, 3.5, 4.5, 5. ]) >>> np.gradient(f, 2) array([0.5 , 0.75, 1.25, 1.75, 2.25, 2.5 ]) Spacing can be also specified with an array that represents the coordinates of the values F along the dimensions. For instance a uniform spacing: >>> x = np.arange(f.size) >>> np.gradient(f, x) array([1. , 1.5, 2.5, 3.5, 4.5, 5. ]) Or a non uniform one: >>> x = np.array([0., 1., 1.5, 3.5, 4., 6.], dtype=float) >>> np.gradient(f, x) array([1. , 3. , 3.5, 6.7, 6.9, 2.5]) For two dimensional arrays, the return will be two arrays ordered by axis. In this example the first array stands for the gradient in rows and the second one in columns direction: >>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float)) [array([[ 2., 2., -1.], [ 2., 2., -1.]]), array([[1. , 2.5, 4. ], [1. , 1. , 1. ]])] In this example the spacing is also specified: uniform for axis=0 and non uniform for axis=1 >>> dx = 2. >>> y = [1., 1.5, 3.5] >>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float), dx, y) [array([[ 1. , 1. , -0.5], [ 1. , 1. , -0.5]]), array([[2. , 2. , 2. ], [2. , 1.7, 0.5]])] It is possible to specify how boundaries are treated using `edge_order` >>> x = np.array([0, 1, 2, 3, 4]) >>> f = x**2 >>> np.gradient(f, edge_order=1) array([1., 2., 4., 6., 7.]) >>> np.gradient(f, edge_order=2) array([0., 2., 4., 6., 8.]) The `axis` keyword can be used to specify a subset of axes of which the gradient is calculated >>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float), axis=0) array([[ 2., 2., -1.], [ 2., 2., -1.]]) Notes ----- Assuming that :math:`f\\in C^{3}` (i.e., :math:`f` has at least 3 continuous derivatives) and let :math:`h_{*}` be a non-homogeneous stepsize, we minimize the \"consistency error\" :math:`\\eta_{i}` between the true gradient and its estimate from a linear combination of the neighboring grid-points: .. math:: \\eta_{i} = f_{i}^{\\left(1\\right)} - \\left[ \\alpha f\\left(x_{i}\\right) + \\beta f\\left(x_{i} + h_{d}\\right) + \\gamma f\\left(x_{i}-h_{s}\\right) \\right] By substituting :math:`f(x_{i} + h_{d})` and :math:`f(x_{i} - h_{s})` with their Taylor series expansion, this translates into solving the following the linear system: .. math:: \\left\\{ \\begin{array}{r} \\alpha+\\beta+\\gamma=0 \\\\ \\beta h_{d}-\\gamma h_{s}=1 \\\\ \\beta h_{d}^{2}+\\gamma h_{s}^{2}=0 \\end{array} \\right. The resulting approximation of :math:`f_{i}^{(1)}` is the following: .. math:: \\hat f_{i}^{(1)} = \\frac{ h_{s}^{2}f\\left(x_{i} + h_{d}\\right) + \\left(h_{d}^{2} - h_{s}^{2}\\right)f\\left(x_{i}\\right) - h_{d}^{2}f\\left(x_{i}-h_{s}\\right)} { h_{s}h_{d}\\left(h_{d} + h_{s}\\right)} + \\mathcal{O}\\left(\\frac{h_{d}h_{s}^{2} + h_{s}h_{d}^{2}}{h_{d} + h_{s}}\\right) It is worth noting that if :math:`h_{s}=h_{d}` (i.e., data are evenly spaced) we find the standard second order approximation: .. math:: \\hat f_{i}^{(1)}= \\frac{f\\left(x_{i+1}\\right) - f\\left(x_{i-1}\\right)}{2h} + \\mathcal{O}\\left(h^{2}\\right) With a similar procedure the forward/backward approximations used for boundaries can be derived. References ---------- .. [1] Quarteroni A., Sacco R., Saleri F. (2007) Numerical Mathematics (Texts in Applied Mathematics). New York: Springer. .. [2] Durran D. R. (1999) Numerical Methods for Wave Equations in Geophysical Fluid Dynamics. New York: Springer. .. [3] Fornberg B. (1988) Generation of Finite Difference Formulas on Arbitrarily Spaced Grids, Mathematics of Computation 51, no. 184 : 699-706. `PDF `_. " :arglists '[[& [args {:as kwargs}]]]} gradient (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "gradient")))) (def ^{:doc " Return the scalar dtype or NumPy equivalent of Python type of an object. Parameters ---------- rep : any The object of which the type is returned. default : any, optional If given, this is returned for objects whose types can not be determined. If not given, None is returned for those objects. Returns ------- dtype : dtype or Python type The data type of `rep`. See Also -------- sctype2char, issctype, issubsctype, issubdtype, maximum_sctype Examples -------- >>> np.obj2sctype(np.int32) >>> np.obj2sctype(np.array([1., 2.])) >>> np.obj2sctype(np.array([1.j])) >>> np.obj2sctype(dict) >>> np.obj2sctype('string') >>> np.obj2sctype(1, default=list) " :arglists '[[rep & [{default :default}]] [rep]]} obj2sctype (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "obj2sctype")))) (def ^{:doc " Base object for a dictionary for look-up with any alias for an array dtype. Instances of `_typedict` can not be used as dictionaries directly, first they have to be populated. "} cast (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "cast")))) (def ^{:doc " Determine common type following standard coercion rules. Parameters ---------- array_types : sequence A list of dtypes or dtype convertible objects representing arrays. scalar_types : sequence A list of dtypes or dtype convertible objects representing scalars. Returns ------- datatype : dtype The common data type, which is the maximum of `array_types` ignoring `scalar_types`, unless the maximum of `scalar_types` is of a different kind (`dtype.kind`). If the kind is not understood, then None is returned. See Also -------- dtype, common_type, can_cast, mintypecode Examples -------- >>> np.find_common_type([], [np.int64, np.float32, complex]) dtype('complex128') >>> np.find_common_type([np.int64, np.float32], []) dtype('float64') The standard casting rules ensure that a scalar cannot up-cast an array unless the scalar is of a fundamentally different kind of data (i.e. under a different hierarchy in the data type hierarchy) then the array: >>> np.find_common_type([np.float32], [np.int64, np.float64]) dtype('float32') Complex is of a different type, so it up-casts the float in the `array_types` argument: >>> np.find_common_type([np.float32], [complex]) dtype('complex128') Type specifier strings are convertible to dtypes and can therefore be used instead of dtypes: >>> np.find_common_type(['f4', 'f4', 'i4'], ['c8']) dtype('complex128') " :arglists '[[array_types scalar_types]]} find_common_type (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "find_common_type")))) (def ^{:doc "Signed integer type, compatible with Python `int` and C ``long``. :Character code: ``'l'`` :Canonical name: `numpy.int_` :Alias on this platform: `numpy.int64`: 64-bit signed integer (``-9_223_372_036_854_775_808`` to ``9_223_372_036_854_775_807``). :Alias on this platform: `numpy.intp`: Signed integer large enough to fit pointer, compatible with C ``intptr_t``." :arglists '[[self & [args {:as kwargs}]]]} intp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "intp")))) (def ^{:doc " Find the coefficients of a polynomial with the given sequence of roots. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. Returns the coefficients of the polynomial whose leading coefficient is one for the given sequence of zeros (multiple roots must be included in the sequence as many times as their multiplicity; see Examples). A square matrix (or array, which will be treated as a matrix) can also be given, in which case the coefficients of the characteristic polynomial of the matrix are returned. Parameters ---------- seq_of_zeros : array_like, shape (N,) or (N, N) A sequence of polynomial roots, or a square array or matrix object. Returns ------- c : ndarray 1D array of polynomial coefficients from highest to lowest degree: ``c[0] * x**(N) + c[1] * x**(N-1) + ... + c[N-1] * x + c[N]`` where c[0] always equals 1. Raises ------ ValueError If input is the wrong shape (the input must be a 1-D or square 2-D array). See Also -------- polyval : Compute polynomial values. roots : Return the roots of a polynomial. polyfit : Least squares polynomial fit. poly1d : A one-dimensional polynomial class. Notes ----- Specifying the roots of a polynomial still leaves one degree of freedom, typically represented by an undetermined leading coefficient. [1]_ In the case of this function, that coefficient - the first one in the returned array - is always taken as one. (If for some reason you have one other point, the only automatic way presently to leverage that information is to use ``polyfit``.) The characteristic polynomial, :math:`p_a(t)`, of an `n`-by-`n` matrix **A** is given by :math:`p_a(t) = \\mathrm{det}(t\\, \\mathbf{I} - \\mathbf{A})`, where **I** is the `n`-by-`n` identity matrix. [2]_ References ---------- .. [1] M. Sullivan and M. Sullivan, III, \"Algebra and Trignometry, Enhanced With Graphing Utilities,\" Prentice-Hall, pg. 318, 1996. .. [2] G. Strang, \"Linear Algebra and Its Applications, 2nd Edition,\" Academic Press, pg. 182, 1980. Examples -------- Given a sequence of a polynomial's zeros: >>> np.poly((0, 0, 0)) # Multiple root example array([1., 0., 0., 0.]) The line above represents z**3 + 0*z**2 + 0*z + 0. >>> np.poly((-1./2, 0, 1./2)) array([ 1. , 0. , -0.25, 0. ]) The line above represents z**3 - z/4 >>> np.poly((np.random.random(1)[0], 0, np.random.random(1)[0])) array([ 1. , -0.77086955, 0.08618131, 0. ]) # random Given a square array object: >>> P = np.array([[0, 1./3], [-1./2, 0]]) >>> np.poly(P) array([1. , 0. , 0.16666667]) Note how in all cases the leading coefficient is always 1. " :arglists '[[& [args {:as kwargs}]]]} poly (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "poly")))) (def ^{:doc "dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)"} __deprecated_attrs__ (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* "__deprecated_attrs__")))) (def ^{:doc " Return the scalar type of highest precision of the same kind as the input. Parameters ---------- t : dtype or dtype specifier The input data type. This can be a `dtype` object or an object that is convertible to a `dtype`. Returns ------- out : dtype The highest precision data type of the same kind (`dtype.kind`) as `t`. See Also -------- obj2sctype, mintypecode, sctype2char dtype Examples -------- >>> np.maximum_sctype(int) >>> np.maximum_sctype(np.uint8) >>> np.maximum_sctype(complex) # may vary >>> np.maximum_sctype(str) >>> np.maximum_sctype('i2') >>> np.maximum_sctype('f4') # may vary " :arglists '[[t]]} maximum_sctype (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "maximum_sctype")))) (def ^{:doc " Build a matrix object from a string, nested sequence, or array. Parameters ---------- obj : str or array_like Input data. If a string, variables in the current scope may be referenced by name. ldict : dict, optional A dictionary that replaces local operands in current frame. Ignored if `obj` is not a string or `gdict` is None. gdict : dict, optional A dictionary that replaces global operands in current frame. Ignored if `obj` is not a string. Returns ------- out : matrix Returns a matrix object, which is a specialized 2-D array. See Also -------- block : A generalization of this function for N-d arrays, that returns normal ndarrays. Examples -------- >>> A = np.mat('1 1; 1 1') >>> B = np.mat('2 2; 2 2') >>> C = np.mat('3 4; 5 6') >>> D = np.mat('7 8; 9 0') All the following expressions construct the same block matrix: >>> np.bmat([[A, B], [C, D]]) matrix([[1, 1, 2, 2], [1, 1, 2, 2], [3, 4, 7, 8], [5, 6, 9, 0]]) >>> np.bmat(np.r_[np.c_[A, B], np.c_[C, D]]) matrix([[1, 1, 2, 2], [1, 1, 2, 2], [3, 4, 7, 8], [5, 6, 9, 0]]) >>> np.bmat('A,B; C,D') matrix([[1, 1, 2, 2], [1, 1, 2, 2], [3, 4, 7, 8], [5, 6, 9, 0]]) " :arglists '[[obj & [{ldict :ldict, gdict :gdict}]] [obj & [{ldict :ldict}]] [obj]]} bmat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bmat")))) (def ^{:doc " Put values into the destination array by matching 1d index and data slices. This iterates over matching 1d slices oriented along the specified axis in the index and data arrays, and uses the former to place values into the latter. These slices can be different lengths. Functions returning an index along an axis, like `argsort` and `argpartition`, produce suitable indices for this function. .. versionadded:: 1.15.0 Parameters ---------- arr: ndarray (Ni..., M, Nk...) Destination array. indices: ndarray (Ni..., J, Nk...) Indices to change along each 1d slice of `arr`. This must match the dimension of arr, but dimensions in Ni and Nj may be 1 to broadcast against `arr`. values: array_like (Ni..., J, Nk...) values to insert at those indices. Its shape and dimension are broadcast to match that of `indices`. axis: int The axis to take 1d slices along. If axis is None, the destination array is treated as if a flattened 1d view had been created of it. Notes ----- This is equivalent to (but faster than) the following use of `ndindex` and `s_`, which sets each of ``ii`` and ``kk`` to a tuple of indices:: Ni, M, Nk = a.shape[:axis], a.shape[axis], a.shape[axis+1:] J = indices.shape[axis] # Need not equal M for ii in ndindex(Ni): for kk in ndindex(Nk): a_1d = a [ii + s_[:,] + kk] indices_1d = indices[ii + s_[:,] + kk] values_1d = values [ii + s_[:,] + kk] for j in range(J): a_1d[indices_1d[j]] = values_1d[j] Equivalently, eliminating the inner loop, the last two lines would be:: a_1d[indices_1d] = values_1d See Also -------- take_along_axis : Take values from the input array by matching 1d index and data slices Examples -------- For this sample array >>> a = np.array([[10, 30, 20], [60, 40, 50]]) We can replace the maximum values with: >>> ai = np.expand_dims(np.argmax(a, axis=1), axis=1) >>> ai array([[1], [0]]) >>> np.put_along_axis(a, ai, 99, axis=1) >>> a array([[10, 99, 20], [99, 40, 50]]) " :arglists '[[& [args {:as kwargs}]]]} put_along_axis (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "put_along_axis")))) (def ^{:doc "logical_or(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the truth value of x1 OR x2 element-wise. Parameters ---------- x1, x2 : array_like Logical OR is applied to the elements of `x1` and `x2`. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or bool Boolean result of the logical OR operation applied to the elements of `x1` and `x2`; the shape is determined by broadcasting. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logical_and, logical_not, logical_xor bitwise_or Examples -------- >>> np.logical_or(True, False) True >>> np.logical_or([True, False], [False, False]) array([ True, False]) >>> x = np.arange(5) >>> np.logical_or(x < 1, x > 3) array([ True, False, False, False, True]) The ``|`` operator can be used as a shorthand for ``np.logical_or`` on boolean ndarrays. >>> a = np.array([True, False]) >>> b = np.array([False, False]) >>> a | b array([ True, False])" :arglists '[[self & [args {:as kwargs}]]]} logical_or (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "logical_or")))) (def ^{:doc "Either an opaque sequence of bytes, or a structure. >>> np.void(b'abcd') void(b'\\x61\\x62\\x63\\x64') Structured `void` scalars can only be constructed via extraction from :ref:`structured_arrays`: >>> arr = np.array((1, 2), dtype=[('x', np.int8), ('y', np.int8)]) >>> arr[()] (1, 2) # looks like a tuple, but is `np.void` :Character code: ``'V'``" :arglists '[[self & [args {:as kwargs}]]]} void (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "void")))) (def ^{:doc ""} e 2.718281828459045) (def ^{:doc "positive(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Numerical positive, element-wise. .. versionadded:: 1.13.0 Parameters ---------- x : array_like or scalar Input array. Returns ------- y : ndarray or scalar Returned array or scalar: `y = +x`. This is a scalar if `x` is a scalar. Notes ----- Equivalent to `x.copy()`, but only defined for types that support arithmetic. Examples -------- >>> x1 = np.array(([1., -1.])) >>> np.positive(x1) array([ 1., -1.]) The unary ``+`` operator can be used as a shorthand for ``np.positive`` on ndarrays. >>> x1 = np.array(([1., -1.])) >>> +x1 array([ 1., -1.])" :arglists '[[self & [args {:as kwargs}]]]} positive (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "positive")))) (def ^{:doc ""} inf ##Inf) (def ^{:doc "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 `. 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." :arglists '[[self & [args {:as kwargs}]]]} nditer (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nditer")))) (def ^{:doc " Return the sum of array elements over a given axis treating Not a Numbers (NaNs) as zero. In NumPy versions <= 1.9.0 Nan is returned for slices that are all-NaN or empty. In later versions zero is returned. Parameters ---------- a : array_like Array containing numbers whose sum is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the sum is computed. The default is to compute the sum of the flattened array. dtype : data-type, optional The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of `a` is used. An exception is when `a` has an integer type with less precision than the platform (u)intp. In that case, the default will be either (u)int32 or (u)int64 depending on whether the platform is 32 or 64 bits. For inexact inputs, dtype must be inexact. .. versionadded:: 1.8.0 out : ndarray, optional Alternate output array in which to place the result. The default is ``None``. If provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. The casting of NaN to integer can yield unexpected results. .. versionadded:: 1.8.0 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 `a`. If the value is anything but the default, then `keepdims` will be passed through to the `mean` or `sum` methods of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. .. versionadded:: 1.8.0 Returns ------- nansum : ndarray. A new array holding the result is returned unless `out` is specified, in which it is returned. The result has the same size as `a`, and the same shape as `a` if `axis` is not None or `a` is a 1-d array. See Also -------- numpy.sum : Sum across array propagating NaNs. isnan : Show which elements are NaN. isfinite: Show which elements are not NaN or +/-inf. Notes ----- If both positive and negative infinity are present, the sum will be Not A Number (NaN). Examples -------- >>> np.nansum(1) 1 >>> np.nansum([1]) 1 >>> np.nansum([1, np.nan]) 1.0 >>> a = np.array([[1, 1], [1, np.nan]]) >>> np.nansum(a) 3.0 >>> np.nansum(a, axis=0) array([2., 1.]) >>> np.nansum([1, np.nan, np.inf]) inf >>> np.nansum([1, np.nan, np.NINF]) -inf >>> from numpy.testing import suppress_warnings >>> with suppress_warnings() as sup: ... sup.filter(RuntimeWarning) ... np.nansum([1, np.nan, np.inf, -np.inf]) # both +/- infinity present nan " :arglists '[[& [args {:as kwargs}]]]} nansum (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nansum")))) (def ^{:doc " Return the product of array elements over a given axis treating Not a Numbers (NaNs) as ones. One is returned for slices that are all-NaN or empty. .. versionadded:: 1.10.0 Parameters ---------- a : array_like Array containing numbers whose product is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the product is computed. The default is to compute the product of the flattened array. dtype : data-type, optional The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of `a` is used. An exception is when `a` has an integer type with less precision than the platform (u)intp. In that case, the default will be either (u)int32 or (u)int64 depending on whether the platform is 32 or 64 bits. For inexact inputs, dtype must be inexact. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``. If provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. The casting of NaN to integer can yield unexpected results. keepdims : bool, optional If 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`. Returns ------- nanprod : ndarray A new array holding the result is returned unless `out` is specified, in which case it is returned. See Also -------- numpy.prod : Product across array propagating NaNs. isnan : Show which elements are NaN. Examples -------- >>> np.nanprod(1) 1 >>> np.nanprod([1]) 1 >>> np.nanprod([1, np.nan]) 1.0 >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nanprod(a) 6.0 >>> np.nanprod(a, axis=0) array([3., 2.]) " :arglists '[[& [args {:as kwargs}]]]} nanprod (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanprod")))) (def ^{:doc " Find the set exclusive-or of two arrays. Return the sorted, unique values that are in only one (not both) of the input arrays. Parameters ---------- ar1, ar2 : array_like Input arrays. assume_unique : bool If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. Returns ------- setxor1d : ndarray Sorted 1D array of unique values that are in only one of the input arrays. Examples -------- >>> a = np.array([1, 2, 3, 2, 4]) >>> b = np.array([2, 3, 5, 7, 5]) >>> np.setxor1d(a,b) array([1, 4, 5, 7]) " :arglists '[[& [args {:as kwargs}]]]} setxor1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "setxor1d")))) (def ^{:doc " Return an array copy of the given object. Parameters ---------- a : array_like Input data. 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 :meth:`ndarray.copy` are very similar, but have different default values for their order= arguments.) 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 (defaults to False). .. versionadded:: 1.19.0 Returns ------- arr : ndarray Array interpretation of `a`. See Also -------- ndarray.copy : Preferred method for creating an array copy Notes ----- This is equivalent to: >>> np.array(a, copy=True) #doctest: +SKIP Examples -------- Create an array x, with a reference y and a copy z: >>> x = np.array([1, 2, 3]) >>> y = x >>> z = np.copy(x) Note that, when we modify x, y changes, but not z: >>> x[0] = 10 >>> x[0] == y[0] True >>> x[0] == z[0] False Note that np.copy is a shallow copy and will not copy object elements within arrays. This is mainly important for arrays containing Python objects. The new array will contain the same object which may lead to surprises if that object can be modified (is mutable): >>> a = np.array([1, 'm', [2, 3, 4]], dtype=object) >>> b = np.copy(a) >>> b[2][0] = 10 >>> a array([1, 'm', list([10, 3, 4])], dtype=object) To ensure all elements within an ``object`` array are copied, use `copy.deepcopy`: >>> import copy >>> a = np.array([1, 'm', [2, 3, 4]], dtype=object) >>> c = copy.deepcopy(a) >>> c[2][0] = 10 >>> c array([1, 'm', list([10, 3, 4])], dtype=object) >>> a array([1, 'm', list([2, 3, 4])], dtype=object) " :arglists '[[& [args {:as kwargs}]]]} copy (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "copy")))) (def ^{:doc " Test whether each element of a 1-D array is also present in a second array. Returns a boolean array the same length as `ar1` that is True where an element of `ar1` is in `ar2` and False otherwise. We recommend using :func:`isin` instead of `in1d` for new code. Parameters ---------- ar1 : (M,) array_like Input array. ar2 : array_like The values against which to test each value of `ar1`. assume_unique : bool, optional If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. invert : bool, optional If True, the values in the returned array are inverted (that is, False where an element of `ar1` is in `ar2` and True otherwise). Default is False. ``np.in1d(a, b, invert=True)`` is equivalent to (but is faster than) ``np.invert(in1d(a, b))``. .. versionadded:: 1.8.0 Returns ------- in1d : (M,) ndarray, bool The values `ar1[in1d]` are in `ar2`. See Also -------- isin : Version of this function that preserves the shape of ar1. numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Notes ----- `in1d` can be considered as an element-wise function version of the python keyword `in`, for 1-D sequences. ``in1d(a, b)`` is roughly equivalent to ``np.array([item in b for item in a])``. However, this idea fails if `ar2` is a set, or similar (non-sequence) container: As ``ar2`` is converted to an array, in those cases ``asarray(ar2)`` is an object array rather than the expected array of contained values. .. versionadded:: 1.4.0 Examples -------- >>> test = np.array([0, 1, 2, 5, 0]) >>> states = [0, 2] >>> mask = np.in1d(test, states) >>> mask array([ True, False, True, False, True]) >>> test[mask] array([0, 2, 0]) >>> mask = np.in1d(test, states, invert=True) >>> mask array([False, True, False, True, False]) >>> test[mask] array([1, 5]) " :arglists '[[& [args {:as kwargs}]]]} in1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "in1d")))) (def ^{:doc "Complex number type composed of two double-precision floating-point numbers, compatible with Python `complex`. :Character code: ``'D'`` :Canonical name: `numpy.cdouble` :Alias: `numpy.cfloat` :Alias: `numpy.complex_` :Alias on this platform: `numpy.complex128`: Complex number type composed of 2 64-bit-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} complex_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "complex_")))) (def ^{:doc " Translates slice objects to concatenation along the second axis. This is short-hand for ``np.r_['-1,2,0', index expression]``, which is useful because of its common occurrence. In particular, arrays will be stacked along their last axis after being upgraded to at least 2-D with 1's post-pended to the shape (column vectors made out of 1-D arrays). See Also -------- column_stack : Stack 1-D arrays as columns into a 2-D array. r_ : For more detailed documentation. Examples -------- >>> np.c_[np.array([1,2,3]), np.array([4,5,6])] array([[1, 4], [2, 5], [3, 6]]) >>> np.c_[np.array([[1,2,3]]), 0, 0, np.array([[4,5,6]])] array([[1, 2, 3, ..., 4, 5, 6]]) "} c_ (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "c_")))) (def ^{:doc " `nd_grid` instance which returns a dense multi-dimensional \"meshgrid\". An instance of `numpy.lib.index_tricks.nd_grid` which returns an dense (or fleshed out) mesh-grid when indexed, so that each returned argument has the same shape. The dimensions and number of the output arrays are equal to the number of indexing dimensions. If the step length is not a complex number, then the stop is not inclusive. However, if the step length is a **complex number** (e.g. 5j), then the integer part of its magnitude is interpreted as specifying the number of points to create between the start and stop values, where the stop value **is inclusive**. Returns ------- mesh-grid `ndarrays` all of the same dimensions See Also -------- numpy.lib.index_tricks.nd_grid : class of `ogrid` and `mgrid` objects ogrid : like mgrid but returns open (not fleshed out) mesh grids r_ : array concatenator Examples -------- >>> np.mgrid[0:5,0:5] array([[[0, 0, 0, 0, 0], [1, 1, 1, 1, 1], [2, 2, 2, 2, 2], [3, 3, 3, 3, 3], [4, 4, 4, 4, 4]], [[0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]]) >>> np.mgrid[-1:1:5j] array([-1. , -0.5, 0. , 0.5, 1. ]) "} mgrid (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "mgrid")))) (def ^{:doc " Integrate along the given axis using the composite trapezoidal rule. Integrate `y` (`x`) along given axis. Parameters ---------- y : array_like Input array to integrate. x : array_like, optional The sample points corresponding to the `y` values. If `x` is None, the sample points are assumed to be evenly spaced `dx` apart. The default is None. dx : scalar, optional The spacing between sample points when `x` is None. The default is 1. axis : int, optional The axis along which to integrate. Returns ------- trapz : float Definite integral as approximated by trapezoidal rule. See Also -------- sum, cumsum Notes ----- Image [2]_ illustrates trapezoidal rule -- y-axis locations of points will be taken from `y` array, by default x-axis distances between points will be 1.0, alternatively they can be provided with `x` array or with `dx` scalar. Return value will be equal to combined area under the red lines. References ---------- .. [1] Wikipedia page: https://en.wikipedia.org/wiki/Trapezoidal_rule .. [2] Illustration image: https://en.wikipedia.org/wiki/File:Composite_trapezoidal_rule_illustration.png Examples -------- >>> np.trapz([1,2,3]) 4.0 >>> np.trapz([1,2,3], x=[4,6,8]) 8.0 >>> np.trapz([1,2,3], dx=2) 8.0 >>> a = np.arange(6).reshape(2, 3) >>> a array([[0, 1, 2], [3, 4, 5]]) >>> np.trapz(a, axis=0) array([1.5, 2.5, 3.5]) >>> np.trapz(a, axis=1) array([2., 8.]) " :arglists '[[& [args {:as kwargs}]]]} trapz (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "trapz")))) (def ^{:doc "Double-precision floating-point number type, compatible with Python `float` and C ``double``. :Character code: ``'d'`` :Canonical name: `numpy.double` :Alias: `numpy.float_` :Alias on this platform: `numpy.float64`: 64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa." :arglists '[[self & [args {:as kwargs}]]]} float64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "float64")))) (def ^{:doc " Compute the multidimensional histogram of some data. Parameters ---------- sample : (N, D) array, or (D, N) array_like The data to be histogrammed. Note the unusual interpretation of sample when an array_like: * When an array, each row is a coordinate in a D-dimensional space - such as ``histogramdd(np.array([p1, p2, p3]))``. * When an array_like, each element is the list of values for single coordinate - such as ``histogramdd((X, Y, Z))``. The first form should be preferred. bins : sequence or int, optional The bin specification: * A sequence of arrays describing the monotonically increasing bin edges along each dimension. * The number of bins for each dimension (nx, ny, ... =bins) * The number of bins for all dimensions (nx=ny=...=bins). range : sequence, optional A sequence of length D, each an optional (lower, upper) tuple giving the outer bin edges to be used if the edges are not given explicitly in `bins`. An entry of None in the sequence results in the minimum and maximum values being used for the corresponding dimension. The default, None, is equivalent to passing a tuple of D None values. density : bool, optional If False, the default, returns the number of samples in each bin. If True, returns the probability *density* function at the bin, ``bin_count / sample_count / bin_volume``. normed : bool, optional An alias for the density argument that behaves identically. To avoid confusion with the broken normed argument to `histogram`, `density` should be preferred. weights : (N,) array_like, optional An array of values `w_i` weighing each sample `(x_i, y_i, z_i, ...)`. Weights are normalized to 1 if normed is True. If normed is False, the values of the returned histogram are equal to the sum of the weights belonging to the samples falling into each bin. Returns ------- H : ndarray The multidimensional histogram of sample x. See normed and weights for the different possible semantics. edges : list A list of D arrays describing the bin edges for each dimension. See Also -------- histogram: 1-D histogram histogram2d: 2-D histogram Examples -------- >>> r = np.random.randn(100,3) >>> H, edges = np.histogramdd(r, bins = (5, 8, 4)) >>> H.shape, edges[0].size, edges[1].size, edges[2].size ((5, 8, 4), 6, 9, 5) " :arglists '[[& [args {:as kwargs}]]]} histogramdd (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "histogramdd")))) (def ^{:doc " Compute the weighted average along the specified axis. Parameters ---------- a : array_like Array containing data to be averaged. If `a` is not an array, a conversion is attempted. axis : None or int or tuple of ints, optional Axis or axes along which to average `a`. The default, axis=None, will average over all of the elements of the input array. If axis is negative it counts from the last to the first axis. .. versionadded:: 1.7.0 If axis is a tuple of ints, averaging is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. weights : array_like, optional An array of weights associated with the values in `a`. Each value in `a` contributes to the average according to its associated weight. The weights array can either be 1-D (in which case its length must be the size of `a` along the given axis) or of the same shape as `a`. If `weights=None`, then all data in `a` are assumed to have a weight equal to one. The 1-D calculation is:: avg = sum(a * weights) / sum(weights) The only constraint on `weights` is that `sum(weights)` must not be 0. returned : bool, optional Default is `False`. If `True`, the tuple (`average`, `sum_of_weights`) is returned, otherwise only the average is returned. If `weights=None`, `sum_of_weights` is equivalent to the number of elements over which the average is taken. Returns ------- retval, [sum_of_weights] : array_type or double Return the average along the specified axis. When `returned` is `True`, return a tuple with the average as the first element and the sum of the weights as the second element. `sum_of_weights` is of the same type as `retval`. The result dtype follows a genereal pattern. If `weights` is None, the result dtype will be that of `a` , or ``float64`` if `a` is integral. Otherwise, if `weights` is not None and `a` is non- integral, the result type will be the type of lowest precision capable of representing values of both `a` and `weights`. If `a` happens to be integral, the previous rules still applies but the result dtype will at least be ``float64``. Raises ------ ZeroDivisionError When all weights along axis are zero. See `numpy.ma.average` for a version robust to this type of error. TypeError When the length of 1D `weights` is not the same as the shape of `a` along axis. See Also -------- mean ma.average : average for masked arrays -- useful if your data contains \"missing\" values numpy.result_type : Returns the type that results from applying the numpy type promotion rules to the arguments. Examples -------- >>> data = np.arange(1, 5) >>> data array([1, 2, 3, 4]) >>> np.average(data) 2.5 >>> np.average(np.arange(1, 11), weights=np.arange(10, 0, -1)) 4.0 >>> data = np.arange(6).reshape((3,2)) >>> data array([[0, 1], [2, 3], [4, 5]]) >>> np.average(data, axis=1, weights=[1./4, 3./4]) array([0.75, 2.75, 4.75]) >>> np.average(data, weights=[1./4, 3./4]) Traceback (most recent call last): ... TypeError: Axis must be specified when shapes of a and weights differ. >>> a = np.ones(5, dtype=np.float128) >>> w = np.ones(5, dtype=np.complex64) >>> avg = np.average(a, weights=w) >>> print(avg.dtype) complex256 " :arglists '[[& [args {:as kwargs}]]]} average (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "average")))) (def ^{:doc " Check for a complex type or an array of complex numbers. The type of the input is checked, not the value. Even if the input has an imaginary part equal to zero, `iscomplexobj` evaluates to True. Parameters ---------- x : any The input can be of any type and shape. Returns ------- iscomplexobj : bool The return value, True if `x` is of a complex type or has at least one complex element. See Also -------- isrealobj, iscomplex Examples -------- >>> np.iscomplexobj(1) False >>> np.iscomplexobj(1+0j) True >>> np.iscomplexobj([3, 1+0j, True]) True " :arglists '[[& [args {:as kwargs}]]]} iscomplexobj (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "iscomplexobj")))) (def ^{:doc "logaddexp(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Logarithm of the sum of exponentiations of the inputs. Calculates ``log(exp(x1) + exp(x2))``. This function is useful in statistics where the calculated probabilities of events may be so small as to exceed the range of normal floating point numbers. In such cases the logarithm of the calculated probability is stored. This function allows adding probabilities stored in such a fashion. Parameters ---------- x1, x2 : array_like Input values. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- result : ndarray Logarithm of ``exp(x1) + exp(x2)``. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logaddexp2: Logarithm of the sum of exponentiations of inputs in base 2. Notes ----- .. versionadded:: 1.3.0 Examples -------- >>> prob1 = np.log(1e-50) >>> prob2 = np.log(2.5e-50) >>> prob12 = np.logaddexp(prob1, prob2) >>> prob12 -113.87649168120691 >>> np.exp(prob12) 3.5000000000000057e-50" :arglists '[[self & [args {:as kwargs}]]]} logaddexp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "logaddexp")))) (def ^{:doc "multiply(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Multiply arguments element-wise. Parameters ---------- x1, x2 : array_like Input arrays to be multiplied. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The product of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars. Notes ----- Equivalent to `x1` * `x2` in terms of array broadcasting. Examples -------- >>> np.multiply(2.0, 4.0) 8.0 >>> x1 = np.arange(9.0).reshape((3, 3)) >>> x2 = np.arange(3.0) >>> np.multiply(x1, x2) array([[ 0., 1., 4.], [ 0., 4., 10.], [ 0., 7., 16.]]) The ``*`` operator can be used as a shorthand for ``np.multiply`` on ndarrays. >>> x1 = np.arange(9.0).reshape((3, 3)) >>> x2 = np.arange(3.0) >>> x1 * x2 array([[ 0., 1., 4.], [ 0., 4., 10.], [ 0., 7., 16.]])" :arglists '[[self & [args {:as kwargs}]]]} multiply (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "multiply")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned long``. :Character code: ``'L'`` :Canonical name: `numpy.uint` :Alias on this platform: `numpy.uint64`: 64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``). :Alias on this platform: `numpy.uintp`: Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``." :arglists '[[self & [args {:as kwargs}]]]} uint (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uint")))) (def ^{:doc " Compute the qth percentile of the data along the specified axis, while ignoring nan values. Returns the qth percentile(s) of the array elements. .. versionadded:: 1.9.0 Parameters ---------- a : array_like Input array or object that can be converted to an array, containing nan values to be ignored. q : array_like of float Percentile or sequence of percentiles to compute, which must be between 0 and 100 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the percentiles are computed. The default is to compute the percentile(s) along a flattened version of the array. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} This optional parameter specifies the interpolation method to use when the desired percentile lies between two data points ``i < j``: * 'linear': ``i + (j - i) * fraction``, where ``fraction`` is the fractional part of the index surrounded by ``i`` and ``j``. * 'lower': ``i``. * 'higher': ``j``. * 'nearest': ``i`` or ``j``, whichever is nearest. * 'midpoint': ``(i + j) / 2``. 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 array `a`. If this is anything but the default value it will be passed through (in the special case of an empty array) to the `mean` function of the underlying array. If the array is a sub-class and `mean` does not have the kwarg `keepdims` this will raise a RuntimeError. Returns ------- percentile : scalar or ndarray If `q` is a single percentile and `axis=None`, then the result is a scalar. If multiple percentiles are given, first axis of the result corresponds to the percentiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- nanmean nanmedian : equivalent to ``nanpercentile(..., 50)`` percentile, median, mean nanquantile : equivalent to nanpercentile, but with q in the range [0, 1]. Notes ----- Given a vector ``V`` of length ``N``, the ``q``-th percentile of ``V`` is the value ``q/100`` of the way from the minimum to the maximum in a sorted copy of ``V``. The values and distances of the two nearest neighbors as well as the `interpolation` parameter will determine the percentile if the normalized ranking does not match the location of ``q`` exactly. This function is the same as the median if ``q=50``, the same as the minimum if ``q=0`` and the same as the maximum if ``q=100``. Examples -------- >>> a = np.array([[10., 7., 4.], [3., 2., 1.]]) >>> a[0][1] = np.nan >>> a array([[10., nan, 4.], [ 3., 2., 1.]]) >>> np.percentile(a, 50) nan >>> np.nanpercentile(a, 50) 3.0 >>> np.nanpercentile(a, 50, axis=0) array([6.5, 2. , 2.5]) >>> np.nanpercentile(a, 50, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.nanpercentile(a, 50, axis=0) >>> out = np.zeros_like(m) >>> np.nanpercentile(a, 50, axis=0, out=out) array([6.5, 2. , 2.5]) >>> m array([6.5, 2. , 2.5]) >>> b = a.copy() >>> np.nanpercentile(b, 50, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) " :arglists '[[& [args {:as kwargs}]]]} nanpercentile (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanpercentile")))) (def ^{:doc "Signed integer type, compatible with C ``int``. :Character code: ``'i'`` :Canonical name: `numpy.intc` :Alias on this platform: `numpy.int32`: 32-bit signed integer (``-2_147_483_648`` to ``2_147_483_647``)." :arglists '[[self & [args {:as kwargs}]]]} intc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "intc")))) (def ^{:doc "Signed integer type, compatible with C ``int``. :Character code: ``'i'`` :Canonical name: `numpy.intc` :Alias on this platform: `numpy.int32`: 32-bit signed integer (``-2_147_483_648`` to ``2_147_483_647``)." :arglists '[[self & [args {:as kwargs}]]]} int32 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "int32")))) (def ^{:doc " Change elements of an array based on conditional and input values. Similar to ``np.copyto(arr, vals, where=mask)``, the difference is that `place` uses the first N elements of `vals`, where N is the number of True values in `mask`, while `copyto` uses the elements where `mask` is True. Note that `extract` does the exact opposite of `place`. Parameters ---------- arr : ndarray Array to put data into. mask : array_like Boolean mask array. Must have the same size as `a`. vals : 1-D sequence Values to put into `a`. Only the first N elements are used, where N is the number of True values in `mask`. If `vals` is smaller than N, it will be repeated, and if elements of `a` are to be masked, this sequence must be non-empty. See Also -------- copyto, put, take, extract Examples -------- >>> arr = np.arange(6).reshape(2, 3) >>> np.place(arr, arr>2, [44, 55]) >>> arr array([[ 0, 1, 2], [44, 55, 44]]) " :arglists '[[& [args {:as kwargs}]]]} place (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "place")))) (def ^{:doc " Return the shape of an array. Parameters ---------- a : array_like Input array. Returns ------- shape : tuple of ints The elements of the shape tuple give the lengths of the corresponding array dimensions. See Also -------- len ndarray.shape : Equivalent array method. Examples -------- >>> np.shape(np.eye(3)) (3, 3) >>> np.shape([[1, 2]]) (1, 2) >>> np.shape([0]) (1,) >>> np.shape(0) () >>> a = np.array([(1, 2), (3, 4)], dtype=[('x', 'i4'), ('y', 'i4')]) >>> np.shape(a) (2,) >>> a.shape (2,) " :arglists '[[& [args {:as kwargs}]]]} shape (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "shape")))) (def ^{:doc "Sub-package containing the matrix class and related functions. "} matrixlib (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "matrixlib")))) (def ^{:doc "lcm(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Returns the lowest common multiple of ``|x1|`` and ``|x2|`` Parameters ---------- x1, x2 : array_like, int Arrays of values. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). Returns ------- y : ndarray or scalar The lowest common multiple of the absolute value of the inputs This is a scalar if both `x1` and `x2` are scalars. See Also -------- gcd : The greatest common divisor Examples -------- >>> np.lcm(12, 20) 60 >>> np.lcm.reduce([3, 12, 20]) 60 >>> np.lcm.reduce([40, 12, 20]) 120 >>> np.lcm(np.arange(6), 20) array([ 0, 20, 20, 60, 20, 20])" :arglists '[[self & [args {:as kwargs}]]]} lcm (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "lcm")))) (def ^{:doc "copysign(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Change the sign of x1 to that of x2, element-wise. If `x2` is a scalar, its sign will be copied to all elements of `x1`. Parameters ---------- x1 : array_like Values to change the sign of. x2 : array_like The sign of `x2` is copied to `x1`. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar The values of `x1` with the sign of `x2`. This is a scalar if both `x1` and `x2` are scalars. Examples -------- >>> np.copysign(1.3, -1) -1.3 >>> 1/np.copysign(0, 1) inf >>> 1/np.copysign(0, -1) -inf >>> np.copysign([-1, 0, 1], -1.1) array([-1., -0., -1.]) >>> np.copysign([-1, 0, 1], np.arange(3)-1) array([-1., 0., 1.])" :arglists '[[self & [args {:as kwargs}]]]} copysign (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "copysign")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned short``. :Character code: ``'H'`` :Canonical name: `numpy.ushort` :Alias on this platform: `numpy.uint16`: 16-bit unsigned integer (``0`` to ``65_535``)." :arglists '[[self & [args {:as kwargs}]]]} uint16 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uint16")))) (def ^{:doc " Return a new array with sub-arrays along an axis deleted. For a one dimensional array, this returns those entries not returned by `arr[obj]`. Parameters ---------- arr : array_like Input array. obj : slice, int or array of ints Indicate indices of sub-arrays to remove along the specified axis. .. versionchanged:: 1.19.0 Boolean indices are now treated as a mask of elements to remove, rather than being cast to the integers 0 and 1. axis : int, optional The axis along which to delete the subarray defined by `obj`. If `axis` is None, `obj` is applied to the flattened array. Returns ------- out : ndarray A copy of `arr` with the elements specified by `obj` removed. Note that `delete` does not occur in-place. If `axis` is None, `out` is a flattened array. See Also -------- insert : Insert elements into an array. append : Append elements at the end of an array. Notes ----- Often it is preferable to use a boolean mask. For example: >>> arr = np.arange(12) + 1 >>> mask = np.ones(len(arr), dtype=bool) >>> mask[[0,2,4]] = False >>> result = arr[mask,...] Is equivalent to `np.delete(arr, [0,2,4], axis=0)`, but allows further use of `mask`. Examples -------- >>> arr = np.array([[1,2,3,4], [5,6,7,8], [9,10,11,12]]) >>> arr array([[ 1, 2, 3, 4], [ 5, 6, 7, 8], [ 9, 10, 11, 12]]) >>> np.delete(arr, 1, 0) array([[ 1, 2, 3, 4], [ 9, 10, 11, 12]]) >>> np.delete(arr, np.s_[::2], 1) array([[ 2, 4], [ 6, 8], [10, 12]]) >>> np.delete(arr, [1,3,5], None) array([ 1, 3, 5, 7, 8, 9, 10, 11, 12]) " :arglists '[[& [args {:as kwargs}]]]} delete (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "delete")))) (def ^{:doc " is_busday(dates, weekmask='1111100', holidays=None, busdaycal=None, out=None) Calculates which of the given dates are valid days, and which are not. .. versionadded:: 1.7.0 Parameters ---------- dates : array_like of datetime64[D] The array of dates to process. 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. They 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. busdaycal : busdaycalendar, optional A `busdaycalendar` object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided. out : array of bool, optional If provided, this array is filled with the result. Returns ------- out : array of bool An array with the same shape as ``dates``, containing True for each valid day, and False for each invalid day. See Also -------- busdaycalendar: An object that specifies a custom set of 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. Examples -------- >>> # The weekdays are Friday, Saturday, and Monday ... np.is_busday(['2011-07-01', '2011-07-02', '2011-07-18'], ... holidays=['2011-07-01', '2011-07-04', '2011-07-17']) array([False, False, True]) " :arglists '[[& [args {:as kwargs}]]]} is_busday (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "is_busday")))) (def ^{:doc " Save several arrays into a single file in compressed ``.npz`` format. If keyword arguments are given, then filenames are taken from the keywords. If arguments are passed in with no keywords, then stored filenames are arr_0, arr_1, etc. Parameters ---------- file : str or file Either the filename (string) or an open file (file-like object) where the data will be saved. If file is a string or a Path, the ``.npz`` extension will be appended to the filename if it is not already there. args : Arguments, optional Arrays to save to the file. Since it is not possible for Python to know the names of the arrays outside `savez`, the arrays will be saved with names \"arr_0\", \"arr_1\", and so on. These arguments can be any expression. kwds : Keyword arguments, optional Arrays to save to the file. Arrays will be saved in the file with the keyword names. Returns ------- None See Also -------- numpy.save : Save a single array to a binary file in NumPy format. numpy.savetxt : Save an array to a file as plain text. numpy.savez : Save several arrays into an uncompressed ``.npz`` file format numpy.load : Load the files created by savez_compressed. Notes ----- The ``.npz`` file format is a zipped archive of files named after the variables they contain. The archive is compressed with ``zipfile.ZIP_DEFLATED`` and each file in the archive contains one variable in ``.npy`` format. For a description of the ``.npy`` format, see :py:mod:`numpy.lib.format`. When opening the saved ``.npz`` file with `load` a `NpzFile` object is returned. This is a dictionary-like object which can be queried for its list of arrays (with the ``.files`` attribute), and for the arrays themselves. Examples -------- >>> test_array = np.random.rand(3, 2) >>> test_vector = np.random.rand(4) >>> np.savez_compressed('/tmp/123', a=test_array, b=test_vector) >>> loaded = np.load('/tmp/123.npz') >>> print(np.array_equal(test_array, loaded['a'])) True >>> print(np.array_equal(test_vector, loaded['b'])) True " :arglists '[[& [args {:as kwargs}]]]} savez_compressed (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "savez_compressed")))) (def ^{:doc " The differences between consecutive elements of an array. Parameters ---------- ary : array_like If necessary, will be flattened before the differences are taken. to_end : array_like, optional Number(s) to append at the end of the returned differences. to_begin : array_like, optional Number(s) to prepend at the beginning of the returned differences. Returns ------- ediff1d : ndarray The differences. Loosely, this is ``ary.flat[1:] - ary.flat[:-1]``. See Also -------- diff, gradient Notes ----- When applied to masked arrays, this function drops the mask information if the `to_begin` and/or `to_end` parameters are used. Examples -------- >>> x = np.array([1, 2, 4, 7, 0]) >>> np.ediff1d(x) array([ 1, 2, 3, -7]) >>> np.ediff1d(x, to_begin=-99, to_end=np.array([88, 99])) array([-99, 1, 2, ..., -7, 88, 99]) The returned array is always 1D. >>> y = [[1, 2, 4], [1, 6, 24]] >>> np.ediff1d(y) array([ 1, 2, -3, 5, 18]) " :arglists '[[& [args {:as kwargs}]]]} ediff1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ediff1d")))) (def ^{:doc "fromfile(file, dtype=float, count=-1, sep='', offset=0, *, like=None) 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 like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.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', '>> 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', '>> np.save(fname, x) >>> np.load(fname + '.npy') array([((10, 0), 98.25)], dtype=[('time', [('min', '>> a = np.arange(5) >>> np.put(a, [0, 2], [-44, -55]) >>> a array([-44, 1, -55, 3, 4]) >>> a = np.arange(5) >>> np.put(a, 22, -5, mode='clip') >>> a array([ 0, 1, 2, 3, -5]) " :arglists '[[& [args {:as kwargs}]]]} put (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "put")))) (def ^{:doc "not_equal(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return (x1 != x2) element-wise. Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array, element-wise comparison of `x1` and `x2`. Typically of type bool, unless ``dtype=object`` is passed. This is a scalar if both `x1` and `x2` are scalars. See Also -------- equal, greater, greater_equal, less, less_equal Examples -------- >>> np.not_equal([1.,2.], [1., 3.]) array([False, True]) >>> np.not_equal([1, 2], [[1, 3],[1, 4]]) array([[False, True], [False, True]]) The ``!=`` operator can be used as a shorthand for ``np.not_equal`` on ndarrays. >>> a = np.array([1., 2.]) >>> b = np.array([1., 3.]) >>> a != b array([False, True])" :arglists '[[self & [args {:as kwargs}]]]} not_equal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "not_equal")))) (def ^{:doc " Return Pearson product-moment correlation coefficients. Please refer to the documentation for `cov` for more detail. The relationship between the correlation coefficient matrix, `R`, and the covariance matrix, `C`, is .. math:: R_{ij} = \\frac{ C_{ij} } { \\sqrt{ C_{ii} * C_{jj} } } The values of `R` are between -1 and 1, inclusive. Parameters ---------- x : array_like A 1-D or 2-D array containing multiple variables and observations. Each row of `x` represents a variable, and each column a single observation of all those variables. Also see `rowvar` below. y : array_like, optional An additional set of variables and observations. `y` has the same shape as `x`. rowvar : bool, optional If `rowvar` is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations. bias : _NoValue, optional Has no effect, do not use. .. deprecated:: 1.10.0 ddof : _NoValue, optional Has no effect, do not use. .. deprecated:: 1.10.0 dtype : data-type, optional Data-type of the result. By default, the return data-type will have at least `numpy.float64` precision. .. versionadded:: 1.20 Returns ------- R : ndarray The correlation coefficient matrix of the variables. See Also -------- cov : Covariance matrix Notes ----- Due to floating point rounding the resulting array may not be Hermitian, the diagonal elements may not be 1, and the elements may not satisfy the inequality abs(a) <= 1. The real and imaginary parts are clipped to the interval [-1, 1] in an attempt to improve on that situation but is not much help in the complex case. This function accepts but discards arguments `bias` and `ddof`. This is for backwards compatibility with previous versions of this function. These arguments had no effect on the return values of the function and can be safely ignored in this and previous versions of numpy. Examples -------- In this example we generate two random arrays, ``xarr`` and ``yarr``, and compute the row-wise and column-wise Pearson correlation coefficients, ``R``. Since ``rowvar`` is true by default, we first find the row-wise Pearson correlation coefficients between the variables of ``xarr``. >>> import numpy as np >>> rng = np.random.default_rng(seed=42) >>> xarr = rng.random((3, 3)) >>> xarr array([[0.77395605, 0.43887844, 0.85859792], [0.69736803, 0.09417735, 0.97562235], [0.7611397 , 0.78606431, 0.12811363]]) >>> R1 = np.corrcoef(xarr) >>> R1 array([[ 1. , 0.99256089, -0.68080986], [ 0.99256089, 1. , -0.76492172], [-0.68080986, -0.76492172, 1. ]]) If we add another set of variables and observations ``yarr``, we can compute the row-wise Pearson correlation coefficients between the variables in ``xarr`` and ``yarr``. >>> yarr = rng.random((3, 3)) >>> yarr array([[0.45038594, 0.37079802, 0.92676499], [0.64386512, 0.82276161, 0.4434142 ], [0.22723872, 0.55458479, 0.06381726]]) >>> R2 = np.corrcoef(xarr, yarr) >>> R2 array([[ 1. , 0.99256089, -0.68080986, 0.75008178, -0.934284 , -0.99004057], [ 0.99256089, 1. , -0.76492172, 0.82502011, -0.97074098, -0.99981569], [-0.68080986, -0.76492172, 1. , -0.99507202, 0.89721355, 0.77714685], [ 0.75008178, 0.82502011, -0.99507202, 1. , -0.93657855, -0.83571711], [-0.934284 , -0.97074098, 0.89721355, -0.93657855, 1. , 0.97517215], [-0.99004057, -0.99981569, 0.77714685, -0.83571711, 0.97517215, 1. ]]) Finally if we use the option ``rowvar=False``, the columns are now being treated as the variables and we will find the column-wise Pearson correlation coefficients between variables in ``xarr`` and ``yarr``. >>> R3 = np.corrcoef(xarr, yarr, rowvar=False) >>> R3 array([[ 1. , 0.77598074, -0.47458546, -0.75078643, -0.9665554 , 0.22423734], [ 0.77598074, 1. , -0.92346708, -0.99923895, -0.58826587, -0.44069024], [-0.47458546, -0.92346708, 1. , 0.93773029, 0.23297648, 0.75137473], [-0.75078643, -0.99923895, 0.93773029, 1. , 0.55627469, 0.47536961], [-0.9665554 , -0.58826587, 0.23297648, 0.55627469, 1. , -0.46666491], [ 0.22423734, -0.44069024, 0.75137473, 0.47536961, -0.46666491, 1. ]]) " :arglists '[[& [args {:as kwargs}]]]} corrcoef (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "corrcoef")))) (def ^{:doc " Return a copy of an array sorted along the first axis. Parameters ---------- a : array_like Array to be sorted. Returns ------- sorted_array : ndarray Array of the same type and shape as `a`. See Also -------- sort Notes ----- ``np.msort(a)`` is equivalent to ``np.sort(a, axis=0)``. " :arglists '[[& [args {:as kwargs}]]]} msort (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "msort")))) (def ^{:doc "Complex number type composed of two single-precision floating-point numbers. :Character code: ``'F'`` :Canonical name: `numpy.csingle` :Alias: `numpy.singlecomplex` :Alias on this platform: `numpy.complex64`: Complex number type composed of 2 32-bit-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} csingle (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "csingle")))) (def ^{:doc "bitwise_or(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the bit-wise OR of two arrays element-wise. Computes the bit-wise OR of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``|``. Parameters ---------- x1, x2 : array_like Only integer and boolean types are handled. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Result. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logical_or bitwise_and bitwise_xor binary_repr : Return the binary representation of the input number as a string. Examples -------- The number 13 has the binaray representation ``00001101``. Likewise, 16 is represented by ``00010000``. The bit-wise OR of 13 and 16 is then ``000111011``, or 29: >>> np.bitwise_or(13, 16) 29 >>> np.binary_repr(29) '11101' >>> np.bitwise_or(32, 2) 34 >>> np.bitwise_or([33, 4], 1) array([33, 5]) >>> np.bitwise_or([33, 4], [1, 2]) array([33, 6]) >>> np.bitwise_or(np.array([2, 5, 255]), np.array([4, 4, 4])) array([ 6, 5, 255]) >>> np.array([2, 5, 255]) | np.array([4, 4, 4]) array([ 6, 5, 255]) >>> np.bitwise_or(np.array([2, 5, 255, 2147483647], dtype=np.int32), ... np.array([4, 4, 4, 2147483647], dtype=np.int32)) array([ 6, 5, 255, 2147483647]) >>> np.bitwise_or([True, True], [False, True]) array([ True, True]) The ``|`` operator can be used as a shorthand for ``np.bitwise_or`` on ndarrays. >>> x1 = np.array([2, 5, 255]) >>> x2 = np.array([4, 4, 4]) >>> x1 | x2 array([ 6, 5, 255])" :arglists '[[self & [args {:as kwargs}]]]} bitwise_or (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bitwise_or")))) (def ^{:doc "rad2deg(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Convert angles from radians to degrees. Parameters ---------- x : array_like Angle in radians. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The corresponding angle in degrees. This is a scalar if `x` is a scalar. See Also -------- deg2rad : Convert angles from degrees to radians. unwrap : Remove large jumps in angle by wrapping. Notes ----- .. versionadded:: 1.3.0 rad2deg(x) is ``180 * x / pi``. Examples -------- >>> np.rad2deg(np.pi/2) 90.0" :arglists '[[self & [args {:as kwargs}]]]} rad2deg (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "rad2deg")))) (def ^{:doc "" :arglists '[[msg]]} deprecate_with_doc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "deprecate_with_doc")))) (def ^{:doc " If input is complex with all imaginary parts close to zero, return real parts. \"Close to zero\" is defined as `tol` * (machine epsilon of the type for `a`). Parameters ---------- a : array_like Input array. tol : float Tolerance in machine epsilons for the complex part of the elements in the array. Returns ------- out : ndarray If `a` is real, the type of `a` is used for the output. If `a` has complex elements, the returned type is float. See Also -------- real, imag, angle Notes ----- Machine epsilon varies from machine to machine and between data types but Python floats on most platforms have a machine epsilon equal to 2.2204460492503131e-16. You can use 'np.finfo(float).eps' to print out the machine epsilon for floats. Examples -------- >>> np.finfo(float).eps 2.2204460492503131e-16 # may vary >>> np.real_if_close([2.1 + 4e-14j, 5.2 + 3e-15j], tol=1000) array([2.1, 5.2]) >>> np.real_if_close([2.1 + 4e-13j, 5.2 + 3e-15j], tol=1000) array([2.1+4.e-13j, 5.2 + 3e-15j]) " :arglists '[[& [args {:as kwargs}]]]} real_if_close (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "real_if_close")))) (def ^{:doc " Construct an array from a text file, using regular expression parsing. The returned array is always a structured array, and is constructed from all matches of the regular expression in the file. Groups in the regular expression are converted to fields of the structured array. Parameters ---------- file : str or file Filename or file object to read. regexp : str or regexp Regular expression used to parse the file. Groups in the regular expression correspond to fields in the dtype. dtype : dtype or list of dtypes Dtype for the structured array. encoding : str, optional Encoding used to decode the inputfile. Does not apply to input streams. .. versionadded:: 1.14.0 Returns ------- output : ndarray The output array, containing the part of the content of `file` that was matched by `regexp`. `output` is always a structured array. Raises ------ TypeError When `dtype` is not a valid dtype for a structured array. See Also -------- fromstring, loadtxt Notes ----- Dtypes for structured arrays can be specified in several forms, but all forms specify at least the data type and field name. For details see `basics.rec`. Examples -------- >>> f = open('test.dat', 'w') >>> _ = f.write(\"1312 foo\\n1534 bar\\n444 qux\") >>> f.close() >>> regexp = r\"(\\d+)\\s+(...)\" # match [digits, whitespace, anything] >>> output = np.fromregex('test.dat', regexp, ... [('num', np.int64), ('key', 'S3')]) >>> output array([(1312, b'foo'), (1534, b'bar'), ( 444, b'qux')], dtype=[('num', '>> output['num'] array([1312, 1534, 444]) " :arglists '[[file regexp dtype & [{encoding :encoding}]] [file regexp dtype]]} fromregex (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fromregex")))) (def ^{:doc ""} FLOATING_POINT_SUPPORT 1) (def ^{:doc " Clip (limit) the values in an array. Given an interval, values outside the interval are clipped to the interval edges. For example, if an interval of ``[0, 1]`` is specified, values smaller than 0 become 0, and values larger than 1 become 1. Equivalent to but faster than ``np.minimum(a_max, np.maximum(a, a_min))``. No check is performed to ensure ``a_min < a_max``. Parameters ---------- a : array_like Array containing elements to clip. a_min, a_max : array_like or None Minimum and maximum value. If ``None``, clipping is not performed on the corresponding edge. Only one of `a_min` and `a_max` may be ``None``. Both are broadcast against `a`. out : ndarray, optional The results will be placed in this array. It may be the input array for in-place clipping. `out` must be of the right shape to hold the output. Its type is preserved. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs `. .. versionadded:: 1.17.0 Returns ------- clipped_array : ndarray An array with the elements of `a`, but where values < `a_min` are replaced with `a_min`, and those > `a_max` with `a_max`. See Also -------- :ref:`ufuncs-output-type` Examples -------- >>> a = np.arange(10) >>> np.clip(a, 1, 8) array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8]) >>> a array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> np.clip(a, 3, 6, out=a) array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6]) >>> a = np.arange(10) >>> a array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> np.clip(a, [3, 4, 1, 1, 1, 4, 4, 4, 4, 4], 8) array([3, 4, 2, 3, 4, 5, 6, 7, 8, 8]) " :arglists '[[& [args {:as kwargs}]]]} clip (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "clip")))) (def ^{:doc "Extended-precision floating-point number type, compatible with C ``long double`` but not necessarily with IEEE 754 quadruple-precision. :Character code: ``'g'`` :Canonical name: `numpy.longdouble` :Alias: `numpy.longfloat` :Alias on this platform: `numpy.float128`: 128-bit extended-precision floating-point number type." :arglists '[[self & [args {:as kwargs}]]]} longdouble (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "longdouble")))) (def ^{:doc "A data-type scalar that allows field access as attribute lookup. " :arglists '[[self & [args {:as kwargs}]]]} record (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "record")))) (def ^{:doc " Returns the indices of the maximum values along an axis. Parameters ---------- a : array_like Input array. axis : int, optional By default, the index is into the flattened array, otherwise along the specified axis. out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. Returns ------- index_array : ndarray of ints Array of indices into the array. It has the same shape as `a.shape` with the dimension along `axis` removed. See Also -------- ndarray.argmax, argmin amax : The maximum value along a given axis. unravel_index : Convert a flat index into an index tuple. take_along_axis : Apply ``np.expand_dims(index_array, axis)`` from argmax to an array as if by calling max. Notes ----- In case of multiple occurrences of the maximum values, the indices corresponding to the first occurrence are returned. Examples -------- >>> a = np.arange(6).reshape(2,3) + 10 >>> a array([[10, 11, 12], [13, 14, 15]]) >>> np.argmax(a) 5 >>> np.argmax(a, axis=0) array([1, 1, 1]) >>> np.argmax(a, axis=1) array([2, 2]) Indexes of the maximal elements of a N-dimensional array: >>> ind = np.unravel_index(np.argmax(a, axis=None), a.shape) >>> ind (1, 2) >>> a[ind] 15 >>> b = np.arange(6) >>> b[1] = 5 >>> b array([0, 5, 2, 3, 4, 5]) >>> np.argmax(b) # Only the first occurrence is returned. 1 >>> x = np.array([[4,2,3], [1,0,3]]) >>> index_array = np.argmax(x, axis=-1) >>> # Same as np.max(x, axis=-1, keepdims=True) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1) array([[4], [3]]) >>> # Same as np.max(x, axis=-1) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1) array([4, 3]) " :arglists '[[& [args {:as kwargs}]]]} argmax (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "argmax")))) (def ^{:doc "frexp(x[, out1, out2], / [, out=(None, None)], *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Decompose the elements of x into mantissa and twos exponent. Returns (`mantissa`, `exponent`), where `x = mantissa * 2**exponent``. The mantissa is lies in the open interval(-1, 1), while the twos exponent is a signed integer. Parameters ---------- x : array_like Array of numbers to be decomposed. out1 : ndarray, optional Output array for the mantissa. Must have the same shape as `x`. out2 : ndarray, optional Output array for the exponent. Must have the same shape as `x`. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- mantissa : ndarray Floating values between -1 and 1. This is a scalar if `x` is a scalar. exponent : ndarray Integer exponents of 2. This is a scalar if `x` is a scalar. See Also -------- ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`. Notes ----- Complex dtypes are not supported, they will raise a TypeError. Examples -------- >>> x = np.arange(9) >>> y1, y2 = np.frexp(x) >>> y1 array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875, 0.5 ]) >>> y2 array([0, 1, 2, 2, 3, 3, 3, 3, 4]) >>> y1 * 2**y2 array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.])" :arglists '[[self & [args {:as kwargs}]]]} frexp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "frexp")))) (def ^{:doc " Interpret the input as a matrix. Unlike `matrix`, `asmatrix` does not make a copy if the input is already a matrix or an ndarray. Equivalent to ``matrix(data, copy=False)``. Parameters ---------- data : array_like Input data. dtype : data-type Data-type of the output matrix. Returns ------- mat : matrix `data` interpreted as a matrix. Examples -------- >>> x = np.array([[1, 2], [3, 4]]) >>> m = np.asmatrix(x) >>> x[0,0] = 5 >>> m matrix([[5, 2], [3, 4]]) " :arglists '[[data & [{dtype :dtype}]] [data]]} asmatrix (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "asmatrix")))) (def ^{:doc "matmul(x1, x2, /, out=None, *, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Matrix product of two arrays. Parameters ---------- x1, x2 : array_like Input arrays, scalars not allowed. out : ndarray, optional A location into which the result is stored. If provided, it must have a shape that matches the signature `(n,k),(k,m)->(n,m)`. If not provided or None, a freshly-allocated array is returned. **kwargs For other keyword-only arguments, see the :ref:`ufunc docs `. .. versionadded:: 1.16 Now handles ufunc kwargs Returns ------- y : ndarray The matrix product of the inputs. This is a scalar only when both x1, x2 are 1-d vectors. Raises ------ ValueError If the last dimension of `x1` is not the same size as the second-to-last dimension of `x2`. If a scalar value is passed in. See Also -------- vdot : Complex-conjugating dot product. tensordot : Sum products over arbitrary axes. einsum : Einstein summation convention. dot : alternative matrix product with different broadcasting rules. Notes ----- The behavior depends on the arguments in the following way. - If both arguments are 2-D they are multiplied like conventional matrices. - If either argument is N-D, N > 2, it is treated as a stack of matrices residing in the last two indexes and broadcast accordingly. - If the first argument is 1-D, it is promoted to a matrix by prepending a 1 to its dimensions. After matrix multiplication the prepended 1 is removed. - If the second argument is 1-D, it is promoted to a matrix by appending a 1 to its dimensions. After matrix multiplication the appended 1 is removed. ``matmul`` differs from ``dot`` in two important ways: - Multiplication by scalars is not allowed, use ``*`` instead. - Stacks of matrices are broadcast together as if the matrices were elements, respecting the signature ``(n,k),(k,m)->(n,m)``: >>> a = np.ones([9, 5, 7, 4]) >>> c = np.ones([9, 5, 4, 3]) >>> np.dot(a, c).shape (9, 5, 7, 9, 5, 3) >>> np.matmul(a, c).shape (9, 5, 7, 3) >>> # n is 7, k is 4, m is 3 The matmul function implements the semantics of the `@` operator introduced in Python 3.5 following PEP465. Examples -------- For 2-D arrays it is the matrix product: >>> a = np.array([[1, 0], ... [0, 1]]) >>> b = np.array([[4, 1], ... [2, 2]]) >>> np.matmul(a, b) array([[4, 1], [2, 2]]) For 2-D mixed with 1-D, the result is the usual. >>> a = np.array([[1, 0], ... [0, 1]]) >>> b = np.array([1, 2]) >>> np.matmul(a, b) array([1, 2]) >>> np.matmul(b, a) array([1, 2]) Broadcasting is conventional for stacks of arrays >>> a = np.arange(2 * 2 * 4).reshape((2, 2, 4)) >>> b = np.arange(2 * 2 * 4).reshape((2, 4, 2)) >>> np.matmul(a,b).shape (2, 2, 2) >>> np.matmul(a, b)[0, 1, 1] 98 >>> sum(a[0, 1, :] * b[0 , :, 1]) 98 Vector, vector returns the scalar inner product, but neither argument is complex-conjugated: >>> np.matmul([2j, 3j], [2j, 3j]) (-13+0j) Scalar multiplication raises an error. >>> np.matmul([1,2], 3) Traceback (most recent call last): ... ValueError: matmul: Input operand 1 does not have enough dimensions ... The ``@`` operator can be used as a shorthand for ``np.matmul`` on ndarrays. >>> x1 = np.array([2j, 3j]) >>> x2 = np.array([2j, 3j]) >>> x1 @ x2 (-13+0j) .. versionadded:: 1.10.0" :arglists '[[self & [args {:as kwargs}]]]} matmul (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "matmul")))) (def ^{:doc " Wrapper functions to more user-friendly calling of certain math functions whose output data-type is different than the input data-type in certain domains of the input. For example, for functions like `log` with branch cuts, the versions in this module provide the mathematically valid answers in the complex plane:: >>> import math >>> from numpy.lib import scimath >>> scimath.log(-math.exp(1)) == (1+1j*math.pi) True Similarly, `sqrt`, other base logarithms, `power` and trig functions are correctly handled. See their respective docstrings for specific examples. Functions --------- .. autosummary:: :toctree: generated/ sqrt log log2 logn log10 power arccos arcsin arctanh "} emath (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "emath")))) (def ^{:doc " Compute the arithmetic mean along the specified axis. Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. `float64` intermediate and return values are used for integer inputs. Parameters ---------- a : array_like Array containing numbers whose mean is desired. If `a` is not an array, a conversion is attempted. axis : None or int or tuple of ints, optional Axis or axes along which the means are computed. The default is to compute the mean of the flattened array. .. versionadded:: 1.7.0 If this is a tuple of ints, a mean is performed over multiple axes, instead of a single axis or all the axes as before. dtype : data-type, optional Type to use in computing the mean. For integer inputs, the default is `float64`; for floating point inputs, it is the same as the input dtype. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `mean` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. where : array_like of bool, optional Elements to include in the mean. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.20.0 Returns ------- m : ndarray, see dtype parameter above If `out=None`, returns a new array containing the mean values, otherwise a reference to the output array is returned. See Also -------- average : Weighted average std, var, nanmean, nanstd, nanvar Notes ----- The arithmetic mean is the sum of the elements along the axis divided by the number of elements. Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for `float32` (see example below). Specifying a higher-precision accumulator using the `dtype` keyword can alleviate this issue. By default, `float16` results are computed using `float32` intermediates for extra precision. Examples -------- >>> a = np.array([[1, 2], [3, 4]]) >>> np.mean(a) 2.5 >>> np.mean(a, axis=0) array([2., 3.]) >>> np.mean(a, axis=1) array([1.5, 3.5]) In single precision, `mean` can be inaccurate: >>> a = np.zeros((2, 512*512), dtype=np.float32) >>> a[0, :] = 1.0 >>> a[1, :] = 0.1 >>> np.mean(a) 0.54999924 Computing the mean in float64 is more accurate: >>> np.mean(a, dtype=np.float64) 0.55000000074505806 # may vary Specifying a where argument: >>> a = np.array([[5, 9, 13], [14, 10, 12], [11, 15, 19]]) >>> np.mean(a) 12.0 >>> np.mean(a, where=[[True], [False], [False]]) 9.0 " :arglists '[[& [args {:as kwargs}]]]} mean (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "mean")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned int``. :Character code: ``'I'`` :Canonical name: `numpy.uintc` :Alias on this platform: `numpy.uint32`: 32-bit unsigned integer (``0`` to ``4_294_967_295``)." :arglists '[[self & [args {:as kwargs}]]]} uint32 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uint32")))) (def ^{:doc " Check if all elements of input array are true. See Also -------- numpy.all : Equivalent function; see for details. " :arglists '[[& [args {:as kwargs}]]]} alltrue (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "alltrue")))) (def ^{:doc "Find the wrapper for the array with the highest priority. In case of ties, leftmost wins. If no wrapper is found, return None " :arglists '[[& [args]]]} get_array_wrap (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "get_array_wrap")))) (def ^{:doc " Load data from a text file. Each row in the text file must have the same number of values. Parameters ---------- fname : file, str, or pathlib.Path File, filename, or generator to read. If the filename extension is ``.gz`` or ``.bz2``, the file is first decompressed. Note that generators should return byte strings. dtype : data-type, optional Data-type of the resulting array; default: float. If this is a structured data-type, the resulting array will be 1-dimensional, and each row will be interpreted as an element of the array. In this case, the number of columns used must match the number of fields in the data-type. comments : str or sequence of str, optional The characters or list of characters used to indicate the start of a comment. None implies no comments. For backwards compatibility, byte strings will be decoded as 'latin1'. The default is '#'. delimiter : str, optional The string used to separate values. For backwards compatibility, byte strings will be decoded as 'latin1'. The default is whitespace. converters : dict, optional A dictionary mapping column number to a function that will parse the column string into the desired value. E.g., if column 0 is a date string: ``converters = {0: datestr2num}``. Converters can also be used to provide a default value for missing data (but see also `genfromtxt`): ``converters = {3: lambda s: float(s.strip() or 0)}``. Default: None. skiprows : int, optional Skip the first `skiprows` lines, including comments; default: 0. usecols : int or sequence, optional Which columns to read, with 0 being the first. For example, ``usecols = (1,4,5)`` will extract the 2nd, 5th and 6th columns. The default, None, results in all columns being read. .. versionchanged:: 1.11.0 When a single column has to be read it is possible to use an integer instead of a tuple. E.g ``usecols = 3`` reads the fourth column the same way as ``usecols = (3,)`` would. unpack : bool, optional If True, the returned array is transposed, so that arguments may be unpacked using ``x, y, z = loadtxt(...)``. When used with a structured data-type, arrays are returned for each field. Default is False. ndmin : int, optional The returned array will have at least `ndmin` dimensions. Otherwise mono-dimensional axes will be squeezed. Legal values: 0 (default), 1 or 2. .. versionadded:: 1.6.0 encoding : str, optional Encoding used to decode the inputfile. Does not apply to input streams. The special value 'bytes' enables backward compatibility workarounds that ensures you receive byte arrays as results if possible and passes 'latin1' encoded strings to converters. Override this value to receive unicode arrays and pass strings as input to converters. If set to None the system default is used. The default value is 'bytes'. .. versionadded:: 1.14.0 max_rows : int, optional Read `max_rows` lines of content after `skiprows` lines. The default is to read all the lines. .. versionadded:: 1.16.0 like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray Data read from the text file. See Also -------- load, fromstring, fromregex genfromtxt : Load data with missing values handled as specified. scipy.io.loadmat : reads MATLAB data files Notes ----- This function aims to be a fast reader for simply formatted files. The `genfromtxt` function provides more sophisticated handling of, e.g., lines with missing values. .. versionadded:: 1.10.0 The strings produced by the Python float.hex method can be used as input for floats. Examples -------- >>> from io import StringIO # StringIO behaves like a file object >>> c = StringIO(\"0 1\\n2 3\") >>> np.loadtxt(c) array([[0., 1.], [2., 3.]]) >>> d = StringIO(\"M 21 72\\nF 35 58\") >>> np.loadtxt(d, dtype={'names': ('gender', 'age', 'weight'), ... 'formats': ('S1', 'i4', 'f4')}) array([(b'M', 21, 72.), (b'F', 35, 58.)], dtype=[('gender', 'S1'), ('age', '>> c = StringIO(\"1,0,2\\n3,0,4\") >>> x, y = np.loadtxt(c, delimiter=',', usecols=(0, 2), unpack=True) >>> x array([1., 3.]) >>> y array([2., 4.]) This example shows how `converters` can be used to convert a field with a trailing minus sign into a negative number. >>> s = StringIO('10.01 31.25-\\n19.22 64.31\\n17.57- 63.94') >>> def conv(fld): ... return -float(fld[:-1]) if fld.endswith(b'-') else float(fld) ... >>> np.loadtxt(s, converters={0: conv, 1: conv}) array([[ 10.01, -31.25], [ 19.22, 64.31], [-17.57, 63.94]]) " :arglists '[[fname & [{max_rows :max_rows, encoding :encoding, ndmin :ndmin, like :like, dtype :dtype, comments :comments, unpack :unpack, converters :converters, delimiter :delimiter, skiprows :skiprows, usecols :usecols}]] [fname & [{encoding :encoding, ndmin :ndmin, like :like, dtype :dtype, comments :comments, unpack :unpack, converters :converters, delimiter :delimiter, skiprows :skiprows, usecols :usecols}]] [fname & [{ndmin :ndmin, like :like, dtype :dtype, comments :comments, unpack :unpack, converters :converters, delimiter :delimiter, skiprows :skiprows, usecols :usecols}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, converters :converters, skiprows :skiprows, usecols :usecols, unpack :unpack, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, converters :converters, skiprows :skiprows, usecols :usecols, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, converters :converters, skiprows :skiprows, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, converters :converters, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, like :like}]] [fname & [{dtype :dtype, comments :comments, like :like}]] [fname & [{dtype :dtype, like :like}]] [fname & [{like :like}]]]} loadtxt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "loadtxt")))) (def ^{:doc " Compute the variance along the specified axis. Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis. Parameters ---------- a : array_like Array containing numbers whose variance is desired. If `a` is not an array, a conversion is attempted. axis : None or int or tuple of ints, optional Axis or axes along which the variance is computed. The default is to compute the variance of the flattened array. .. versionadded:: 1.7.0 If this is a tuple of ints, a variance is performed over multiple axes, instead of a single axis or all the axes as before. dtype : data-type, optional Type to use in computing the variance. For arrays of integer type the default is `float64`; for arrays of float types it is the same as the array type. out : ndarray, optional Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary. ddof : int, optional \"Delta Degrees of Freedom\": the divisor used in the calculation is ``N - ddof``, where ``N`` represents the number of elements. By default `ddof` is zero. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `var` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. where : array_like of bool, optional Elements to include in the variance. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.20.0 Returns ------- variance : ndarray, see dtype parameter above If ``out=None``, returns a new array containing the variance; otherwise, a reference to the output array is returned. See Also -------- std, mean, nanmean, nanstd, nanvar :ref:`ufuncs-output-type` Notes ----- The variance is the average of the squared deviations from the mean, i.e., ``var = mean(x)``, where ``x = abs(a - a.mean())**2``. The mean is typically calculated as ``x.sum() / N``, where ``N = len(x)``. If, however, `ddof` is specified, the divisor ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1`` provides an unbiased estimator of the variance of a hypothetical infinite population. ``ddof=0`` provides a maximum likelihood estimate of the variance for normally distributed variables. Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative. For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for `float32` (see example below). Specifying a higher-accuracy accumulator using the ``dtype`` keyword can alleviate this issue. Examples -------- >>> a = np.array([[1, 2], [3, 4]]) >>> np.var(a) 1.25 >>> np.var(a, axis=0) array([1., 1.]) >>> np.var(a, axis=1) array([0.25, 0.25]) In single precision, var() can be inaccurate: >>> a = np.zeros((2, 512*512), dtype=np.float32) >>> a[0, :] = 1.0 >>> a[1, :] = 0.1 >>> np.var(a) 0.20250003 Computing the variance in float64 is more accurate: >>> np.var(a, dtype=np.float64) 0.20249999932944759 # may vary >>> ((1-0.55)**2 + (0.1-0.55)**2)/2 0.2025 Specifying a where argument: >>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]]) >>> np.var(a) 6.833333333333333 # may vary >>> np.var(a, where=[[True], [True], [False]]) 4.0 " :arglists '[[& [args {:as kwargs}]]]} var (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "var")))) (def ^{:doc " Take values from the input array by matching 1d index and data slices. This iterates over matching 1d slices oriented along the specified axis in the index and data arrays, and uses the former to look up values in the latter. These slices can be different lengths. Functions returning an index along an axis, like `argsort` and `argpartition`, produce suitable indices for this function. .. versionadded:: 1.15.0 Parameters ---------- arr: ndarray (Ni..., M, Nk...) Source array indices: ndarray (Ni..., J, Nk...) Indices to take along each 1d slice of `arr`. This must match the dimension of arr, but dimensions Ni and Nj only need to broadcast against `arr`. axis: int The axis to take 1d slices along. If axis is None, the input array is treated as if it had first been flattened to 1d, for consistency with `sort` and `argsort`. Returns ------- out: ndarray (Ni..., J, Nk...) The indexed result. Notes ----- This is equivalent to (but faster than) the following use of `ndindex` and `s_`, which sets each of ``ii`` and ``kk`` to a tuple of indices:: Ni, M, Nk = a.shape[:axis], a.shape[axis], a.shape[axis+1:] J = indices.shape[axis] # Need not equal M out = np.empty(Ni + (J,) + Nk) for ii in ndindex(Ni): for kk in ndindex(Nk): a_1d = a [ii + s_[:,] + kk] indices_1d = indices[ii + s_[:,] + kk] out_1d = out [ii + s_[:,] + kk] for j in range(J): out_1d[j] = a_1d[indices_1d[j]] Equivalently, eliminating the inner loop, the last two lines would be:: out_1d[:] = a_1d[indices_1d] See Also -------- take : Take along an axis, using the same indices for every 1d slice put_along_axis : Put values into the destination array by matching 1d index and data slices Examples -------- For this sample array >>> a = np.array([[10, 30, 20], [60, 40, 50]]) We can sort either by using sort directly, or argsort and this function >>> np.sort(a, axis=1) array([[10, 20, 30], [40, 50, 60]]) >>> ai = np.argsort(a, axis=1); ai array([[0, 2, 1], [1, 2, 0]]) >>> np.take_along_axis(a, ai, axis=1) array([[10, 20, 30], [40, 50, 60]]) The same works for max and min, if you expand the dimensions: >>> np.expand_dims(np.max(a, axis=1), axis=1) array([[30], [60]]) >>> ai = np.expand_dims(np.argmax(a, axis=1), axis=1) >>> ai array([[1], [0]]) >>> np.take_along_axis(a, ai, axis=1) array([[30], [60]]) If we want to get the max and min at the same time, we can stack the indices first >>> ai_min = np.expand_dims(np.argmin(a, axis=1), axis=1) >>> ai_max = np.expand_dims(np.argmax(a, axis=1), axis=1) >>> ai = np.concatenate([ai_min, ai_max], axis=1) >>> ai array([[0, 1], [1, 0]]) >>> np.take_along_axis(a, ai, axis=1) array([[10, 30], [40, 60]]) " :arglists '[[& [args {:as kwargs}]]]} take_along_axis (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "take_along_axis")))) (def ^{:doc " Return the product of array elements over a given axis. Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional Axis or axes along which a product is performed. The default, axis=None, will calculate the product of all the elements in the input array. If axis is negative it counts from the last to the first axis. .. versionadded:: 1.7.0 If axis is a tuple of ints, a product is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. dtype : dtype, optional The type of the returned array, as well as of the accumulator in which the elements are multiplied. The dtype of `a` is used by default unless `a` has an integer dtype of less precision than the default platform integer. In that case, if `a` is signed then the platform integer is used while if `a` is unsigned then an unsigned integer of the same precision as the platform integer is used. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output, but the type of the output values will be cast if necessary. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `prod` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. initial : scalar, optional The starting value for this product. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.15.0 where : array_like of bool, optional Elements to include in the product. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.17.0 Returns ------- product_along_axis : ndarray, see `dtype` parameter above. An array shaped as `a` but with the specified axis removed. Returns a reference to `out` if specified. See Also -------- ndarray.prod : equivalent method :ref:`ufuncs-output-type` Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow. That means that, on a 32-bit platform: >>> x = np.array([536870910, 536870910, 536870910, 536870910]) >>> np.prod(x) 16 # may vary The product of an empty array is the neutral element 1: >>> np.prod([]) 1.0 Examples -------- By default, calculate the product of all elements: >>> np.prod([1.,2.]) 2.0 Even when the input array is two-dimensional: >>> np.prod([[1.,2.],[3.,4.]]) 24.0 But we can also specify the axis over which to multiply: >>> np.prod([[1.,2.],[3.,4.]], axis=1) array([ 2., 12.]) Or select specific elements to include: >>> np.prod([1., np.nan, 3.], where=[True, False, True]) 3.0 If the type of `x` is unsigned, then the output type is the unsigned platform integer: >>> x = np.array([1, 2, 3], dtype=np.uint8) >>> np.prod(x).dtype == np.uint True If `x` is of a signed integer type, then the output type is the default platform integer: >>> x = np.array([1, 2, 3], dtype=np.int8) >>> np.prod(x).dtype == int True You can also start the product with a value other than one: >>> np.prod([1, 2], initial=5) 10 " :arglists '[[& [args {:as kwargs}]]]} prod (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "prod")))) (def ^{:doc " Load arrays or pickled objects from ``.npy``, ``.npz`` or pickled files. .. warning:: Loading files that contain object arrays uses the ``pickle`` module, which is not secure against erroneous or maliciously constructed data. Consider passing ``allow_pickle=False`` to load data that is known not to contain object arrays for the safer handling of untrusted sources. Parameters ---------- file : file-like object, string, or pathlib.Path The file to read. File-like objects must support the ``seek()`` and ``read()`` methods. Pickled files require that the file-like object support the ``readline()`` method as well. mmap_mode : {None, 'r+', 'r', 'w+', 'c'}, optional If not None, then memory-map the file, using the given mode (see `numpy.memmap` for a detailed description of the modes). A memory-mapped array is kept on disk. However, it can be accessed and sliced like any ndarray. Memory mapping is especially useful for accessing small fragments of large files without reading the entire file into memory. allow_pickle : bool, optional Allow loading pickled object arrays stored in npy files. Reasons for disallowing pickles include security, as loading pickled data can execute arbitrary code. If pickles are disallowed, loading object arrays will fail. Default: False .. versionchanged:: 1.16.3 Made default False in response to CVE-2019-6446. fix_imports : bool, optional Only useful when loading Python 2 generated pickled files on Python 3, which includes npy/npz files containing object arrays. If `fix_imports` is True, pickle will try to map the old Python 2 names to the new names used in Python 3. encoding : str, optional What encoding to use when reading Python 2 strings. Only useful when loading Python 2 generated pickled files in Python 3, which includes npy/npz files containing object arrays. Values other than 'latin1', 'ASCII', and 'bytes' are not allowed, as they can corrupt numerical data. Default: 'ASCII' Returns ------- result : array, tuple, dict, etc. Data stored in the file. For ``.npz`` files, the returned instance of NpzFile class must be closed to avoid leaking file descriptors. Raises ------ IOError If the input file does not exist or cannot be read. ValueError The file contains an object array, but allow_pickle=False given. See Also -------- save, savez, savez_compressed, loadtxt memmap : Create a memory-map to an array stored in a file on disk. lib.format.open_memmap : Create or load a memory-mapped ``.npy`` file. Notes ----- - If the file contains pickle data, then whatever object is stored in the pickle is returned. - If the file is a ``.npy`` file, then a single array is returned. - If the file is a ``.npz`` file, then a dictionary-like object is returned, containing ``{filename: array}`` key-value pairs, one for each file in the archive. - If the file is a ``.npz`` file, the returned value supports the context manager protocol in a similar fashion to the open function:: with load('foo.npz') as data: a = data['a'] The underlying file descriptor is closed when exiting the 'with' block. Examples -------- Store data to disk, and load it again: >>> np.save('/tmp/123', np.array([[1, 2, 3], [4, 5, 6]])) >>> np.load('/tmp/123.npy') array([[1, 2, 3], [4, 5, 6]]) Store compressed data to disk, and load it again: >>> a=np.array([[1, 2, 3], [4, 5, 6]]) >>> b=np.array([1, 2]) >>> np.savez('/tmp/123.npz', a=a, b=b) >>> data = np.load('/tmp/123.npz') >>> data['a'] array([[1, 2, 3], [4, 5, 6]]) >>> data['b'] array([1, 2]) >>> data.close() Mem-map the stored array, and then access the second row directly from disk: >>> X = np.load('/tmp/123.npy', mmap_mode='r') >>> X[1, :] memmap([4, 5, 6]) " :arglists '[[file & [{mmap_mode :mmap_mode, allow_pickle :allow_pickle, fix_imports :fix_imports, encoding :encoding}]] [file & [{mmap_mode :mmap_mode, allow_pickle :allow_pickle, fix_imports :fix_imports}]] [file & [{mmap_mode :mmap_mode, allow_pickle :allow_pickle}]] [file & [{mmap_mode :mmap_mode}]] [file]]} load (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "load")))) (def ^{:doc " Sum of array elements over a given axis. Parameters ---------- a : array_like Elements to sum. axis : None or int or tuple of ints, optional Axis or axes along which a sum is performed. The default, axis=None, will sum all of the elements of the input array. If axis is negative it counts from the last to the first axis. .. versionadded:: 1.7.0 If axis is a tuple of ints, a sum is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. dtype : dtype, optional The type of the returned array and of the accumulator in which the elements are summed. The dtype of `a` is used by default unless `a` has an integer dtype of less precision than the default platform integer. In that case, if `a` is signed then the platform integer is used while if `a` is unsigned then an unsigned integer of the same precision as the platform integer is used. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output, but the type of the output values will be cast if necessary. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `sum` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. initial : scalar, optional Starting value for the sum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.15.0 where : array_like of bool, optional Elements to include in the sum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.17.0 Returns ------- sum_along_axis : ndarray An array with the same shape as `a`, with the specified axis removed. If `a` is a 0-d array, or if `axis` is None, a scalar is returned. If an output array is specified, a reference to `out` is returned. See Also -------- ndarray.sum : Equivalent method. add.reduce : Equivalent functionality of `add`. cumsum : Cumulative sum of array elements. trapz : Integration of array values using the composite trapezoidal rule. mean, average Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow. The sum of an empty array is the neutral element 0: >>> np.sum([]) 0.0 For floating point numbers the numerical precision of sum (and ``np.add.reduce``) is in general limited by directly adding each number individually to the result causing rounding errors in every step. However, often numpy will use a numerically better approach (partial pairwise summation) leading to improved precision in many use-cases. This improved precision is always provided when no ``axis`` is given. When ``axis`` is given, it will depend on which axis is summed. Technically, to provide the best speed possible, the improved precision is only used when the summation is along the fast axis in memory. Note that the exact precision may vary depending on other parameters. In contrast to NumPy, Python's ``math.fsum`` function uses a slower but more precise approach to summation. Especially when summing a large number of lower precision floating point numbers, such as ``float32``, numerical errors can become significant. In such cases it can be advisable to use `dtype=\"float64\"` to use a higher precision for the output. Examples -------- >>> np.sum([0.5, 1.5]) 2.0 >>> np.sum([0.5, 0.7, 0.2, 1.5], dtype=np.int32) 1 >>> np.sum([[0, 1], [0, 5]]) 6 >>> np.sum([[0, 1], [0, 5]], axis=0) array([0, 6]) >>> np.sum([[0, 1], [0, 5]], axis=1) array([1, 5]) >>> np.sum([[0, 1], [np.nan, 5]], where=[False, True], axis=1) array([1., 5.]) If the accumulator is too small, overflow occurs: >>> np.ones(128, dtype=np.int8).sum(dtype=np.int8) -128 You can also start the sum with a value other than zero: >>> np.sum([10], initial=5) 15 " :arglists '[[& [args {:as kwargs}]]]} sum (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sum")))) (def ^{:doc "Signed integer type, compatible with Python `int` and C ``long``. :Character code: ``'l'`` :Canonical name: `numpy.int_` :Alias on this platform: `numpy.int64`: 64-bit signed integer (``-9_223_372_036_854_775_808`` to ``9_223_372_036_854_775_807``). :Alias on this platform: `numpy.intp`: Signed integer large enough to fit pointer, compatible with C ``intptr_t``." :arglists '[[self & [args {:as kwargs}]]]} int64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "int64")))) (def ^{:doc " Determine if a class is a subclass of a second class. `issubclass_` is equivalent to the Python built-in ``issubclass``, except that it returns False instead of raising a TypeError if one of the arguments is not a class. Parameters ---------- arg1 : class Input class. True is returned if `arg1` is a subclass of `arg2`. arg2 : class or tuple of classes. Input class. If a tuple of classes, True is returned if `arg1` is a subclass of any of the tuple elements. Returns ------- out : bool Whether `arg1` is a subclass of `arg2` or not. See Also -------- issubsctype, issubdtype, issctype Examples -------- >>> np.issubclass_(np.int32, int) False >>> np.issubclass_(np.int32, float) False >>> np.issubclass_(np.float64, float) True " :arglists '[[arg1 arg2]]} issubclass_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "issubclass_")))) (def ^{:doc "A datetime stored as a 64-bit integer, counting from ``1970-01-01T00:00:00``. >>> np.datetime64(10, 'Y') numpy.datetime64('1980') >>> np.datetime64(10, 'D') numpy.datetime64('1970-01-11') See :ref:`arrays.datetime` for more information. :Character code: ``'M'``" :arglists '[[self & [args {:as kwargs}]]]} Datetime64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "Datetime64")))) (def ^{:doc "OS routines for NT or Posix depending on what system we're on. This exports: - all functions from posix or nt, e.g. unlink, stat, etc. - os.path is either posixpath or ntpath - os.name is either 'posix' or 'nt' - os.curdir is a string representing the current directory (always '.') - os.pardir is a string representing the parent directory (always '..') - os.sep is the (or a most common) pathname separator ('/' or '\\\\') - os.extsep is the extension separator (always '.') - os.altsep is the alternate pathname separator (None or '/') - os.pathsep is the component separator used in $PATH etc - os.linesep is the line separator in text files ('\\r' or '\\n' or '\\r\\n') - os.defpath is the default search path for executables - os.devnull is the file path of the null device ('/dev/null', etc.) Programs that import and use 'os' stand a better chance of being portable between different platforms. Of course, they must then only use functions that are defined by all platforms (e.g., unlink and opendir), and leave all pathname manipulation to os.path (e.g., split and join). "} os (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "os")))) (def ^{:doc "Complex number type composed of two extended-precision floating-point numbers. :Character code: ``'G'`` :Canonical name: `numpy.clongdouble` :Alias: `numpy.clongfloat` :Alias: `numpy.longcomplex` :Alias on this platform: `numpy.complex256`: Complex number type composed of 2 128-bit extended-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} longcomplex (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "longcomplex")))) (def ^{:doc " dot(a, b, out=None) Dot product of two arrays. Specifically, - If both `a` and `b` are 1-D arrays, it is inner product of vectors (without complex conjugation). - If both `a` and `b` are 2-D arrays, it is matrix multiplication, but using :func:`matmul` or ``a @ b`` is preferred. - If either `a` or `b` is 0-D (scalar), it is equivalent to :func:`multiply` and using ``numpy.multiply(a, b)`` or ``a * b`` is preferred. - If `a` is an N-D array and `b` is a 1-D array, it is a sum product over the last axis of `a` and `b`. - If `a` is an N-D array and `b` is an M-D array (where ``M>=2``), it is a sum product over the last axis of `a` and the second-to-last axis of `b`:: dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m]) Parameters ---------- a : array_like First argument. b : array_like Second argument. out : ndarray, optional Output argument. This must have the exact kind that would be returned if it was not used. In particular, it must have the right type, must be C-contiguous, and its dtype must be the dtype that would be returned for `dot(a,b)`. This is a performance feature. Therefore, if these conditions are not met, an exception is raised, instead of attempting to be flexible. Returns ------- output : ndarray Returns the dot product of `a` and `b`. If `a` and `b` are both scalars or both 1-D arrays then a scalar is returned; otherwise an array is returned. If `out` is given, then it is returned. Raises ------ ValueError If the last dimension of `a` is not the same size as the second-to-last dimension of `b`. See Also -------- vdot : Complex-conjugating dot product. tensordot : Sum products over arbitrary axes. einsum : Einstein summation convention. matmul : '@' operator as method with out parameter. linalg.multi_dot : Chained dot product. Examples -------- >>> np.dot(3, 4) 12 Neither argument is complex-conjugated: >>> np.dot([2j, 3j], [2j, 3j]) (-13+0j) For 2-D arrays it is the matrix product: >>> a = [[1, 0], [0, 1]] >>> b = [[4, 1], [2, 2]] >>> np.dot(a, b) array([[4, 1], [2, 2]]) >>> a = np.arange(3*4*5*6).reshape((3,4,5,6)) >>> b = np.arange(3*4*5*6)[::-1].reshape((5,4,6,3)) >>> np.dot(a, b)[2,3,2,1,2,2] 499128 >>> sum(a[2,3,2,:] * b[1,2,:,2]) 499128 " :arglists '[[& [args {:as kwargs}]]]} dot (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "dot")))) (def ^{:doc " Return the sum along diagonals of the array. If `a` is 2-D, the sum along its diagonal with the given offset is returned, i.e., the sum of elements ``a[i,i+offset]`` for all i. If `a` has more than two dimensions, then the axes specified by axis1 and axis2 are used to determine the 2-D sub-arrays whose traces are returned. The shape of the resulting array is the same as that of `a` with `axis1` and `axis2` removed. Parameters ---------- a : array_like Input array, from which the diagonals are taken. offset : int, optional Offset of the diagonal from the main diagonal. Can be both positive and negative. Defaults to 0. axis1, axis2 : int, optional Axes to be used as the first and second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults are the first two axes of `a`. dtype : dtype, optional Determines the data-type of the returned array and of the accumulator where the elements are summed. If dtype has the value None and `a` is of integer type of precision less than the default integer precision, then the default integer precision is used. Otherwise, the precision is the same as that of `a`. out : ndarray, optional Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. Returns ------- sum_along_diagonals : ndarray If `a` is 2-D, the sum along the diagonal is returned. If `a` has larger dimensions, then an array of sums along diagonals is returned. See Also -------- diag, diagonal, diagflat Examples -------- >>> np.trace(np.eye(3)) 3.0 >>> a = np.arange(8).reshape((2,2,2)) >>> np.trace(a) array([6, 8]) >>> a = np.arange(24).reshape((2,2,2,3)) >>> np.trace(a).shape (2, 3) " :arglists '[[& [args {:as kwargs}]]]} trace (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "trace")))) (def ^{:doc ""} BUFSIZE 8192) (def ^{:doc " Return the indices of the minimum values in the specified axis ignoring NaNs. For all-NaN slices ``ValueError`` is raised. Warning: the results cannot be trusted if a slice contains only NaNs and Infs. Parameters ---------- a : array_like Input data. axis : int, optional Axis along which to operate. By default flattened input is used. Returns ------- index_array : ndarray An array of indices or a single index value. See Also -------- argmin, nanargmax Examples -------- >>> a = np.array([[np.nan, 4], [2, 3]]) >>> np.argmin(a) 0 >>> np.nanargmin(a) 2 >>> np.nanargmin(a, axis=0) array([1, 1]) >>> np.nanargmin(a, axis=1) array([1, 0]) " :arglists '[[& [args {:as kwargs}]]]} nanargmin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanargmin")))) (def ^{:doc "cbrt(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the cube-root of an array, element-wise. .. versionadded:: 1.10.0 Parameters ---------- x : array_like The values whose cube-roots are required. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray An array of the same shape as `x`, containing the cube cube-root of each element in `x`. If `out` was provided, `y` is a reference to it. This is a scalar if `x` is a scalar. Examples -------- >>> np.cbrt([1,8,27]) array([ 1., 2., 3.])" :arglists '[[self & [args {:as kwargs}]]]} cbrt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cbrt")))) (def ^{:doc " min_scalar_type(a) For scalar ``a``, returns the data type with the smallest size and smallest scalar kind which can hold its value. For non-scalar array ``a``, returns the vector's dtype unmodified. Floating point values are not demoted to integers, and complex values are not demoted to floats. Parameters ---------- a : scalar or array_like The value whose minimal data type is to be found. Returns ------- out : dtype The minimal data type. Notes ----- .. versionadded:: 1.6.0 See Also -------- result_type, promote_types, dtype, can_cast Examples -------- >>> np.min_scalar_type(10) dtype('uint8') >>> np.min_scalar_type(-260) dtype('int16') >>> np.min_scalar_type(3.1) dtype('float16') >>> np.min_scalar_type(1e50) dtype('float64') >>> np.min_scalar_type(np.arange(4,dtype='f8')) dtype('float64') " :arglists '[[& [args {:as kwargs}]]]} min_scalar_type (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "min_scalar_type")))) (def ^{:doc " Return the cross product of two (arrays of) vectors. The cross product of `a` and `b` in :math:`R^3` is a vector perpendicular to both `a` and `b`. If `a` and `b` are arrays of vectors, the vectors are defined by the last axis of `a` and `b` by default, and these axes can have dimensions 2 or 3. Where the dimension of either `a` or `b` is 2, the third component of the input vector is assumed to be zero and the cross product calculated accordingly. In cases where both input vectors have dimension 2, the z-component of the cross product is returned. Parameters ---------- a : array_like Components of the first vector(s). b : array_like Components of the second vector(s). axisa : int, optional Axis of `a` that defines the vector(s). By default, the last axis. axisb : int, optional Axis of `b` that defines the vector(s). By default, the last axis. axisc : int, optional Axis of `c` containing the cross product vector(s). Ignored if both input vectors have dimension 2, as the return is scalar. By default, the last axis. axis : int, optional If defined, the axis of `a`, `b` and `c` that defines the vector(s) and cross product(s). Overrides `axisa`, `axisb` and `axisc`. Returns ------- c : ndarray Vector cross product(s). Raises ------ ValueError When the dimension of the vector(s) in `a` and/or `b` does not equal 2 or 3. See Also -------- inner : Inner product outer : Outer product. ix_ : Construct index arrays. Notes ----- .. versionadded:: 1.9.0 Supports full broadcasting of the inputs. Examples -------- Vector cross-product. >>> x = [1, 2, 3] >>> y = [4, 5, 6] >>> np.cross(x, y) array([-3, 6, -3]) One vector with dimension 2. >>> x = [1, 2] >>> y = [4, 5, 6] >>> np.cross(x, y) array([12, -6, -3]) Equivalently: >>> x = [1, 2, 0] >>> y = [4, 5, 6] >>> np.cross(x, y) array([12, -6, -3]) Both vectors with dimension 2. >>> x = [1,2] >>> y = [4,5] >>> np.cross(x, y) array(-3) Multiple vector cross-products. Note that the direction of the cross product vector is defined by the `right-hand rule`. >>> x = np.array([[1,2,3], [4,5,6]]) >>> y = np.array([[4,5,6], [1,2,3]]) >>> np.cross(x, y) array([[-3, 6, -3], [ 3, -6, 3]]) The orientation of `c` can be changed using the `axisc` keyword. >>> np.cross(x, y, axisc=0) array([[-3, 3], [ 6, -6], [-3, 3]]) Change the vector definition of `x` and `y` using `axisa` and `axisb`. >>> x = np.array([[1,2,3], [4,5,6], [7, 8, 9]]) >>> y = np.array([[7, 8, 9], [4,5,6], [1,2,3]]) >>> np.cross(x, y) array([[ -6, 12, -6], [ 0, 0, 0], [ 6, -12, 6]]) >>> np.cross(x, y, axisa=0, axisb=0) array([[-24, 48, -24], [-30, 60, -30], [-36, 72, -36]]) " :arglists '[[& [args {:as kwargs}]]]} cross (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cross")))) (def ^{:doc "Capsule objects let you wrap a C \"void *\" pointer in a Python object. They're a way of passing data through the Python interpreter without creating your own custom type. Capsules are used for communication between extension modules. They provide a way for an extension module to export a C interface to other extension modules, so that extension modules can use the Python import mechanism to link to one another. "} _UFUNC_API (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "_UFUNC_API")))) (def ^{:doc " Return the character for the minimum-size type to which given types can be safely cast. The returned type character must represent the smallest size dtype such that an array of the returned type can handle the data from an array of all types in `typechars` (or if `typechars` is an array, then its dtype.char). Parameters ---------- typechars : list of str or array_like If a list of strings, each string should represent a dtype. If array_like, the character representation of the array dtype is used. typeset : str or list of str, optional The set of characters that the returned character is chosen from. The default set is 'GDFgdf'. default : str, optional The default character, this is returned if none of the characters in `typechars` matches a character in `typeset`. Returns ------- typechar : str The character representing the minimum-size type that was found. See Also -------- dtype, sctype2char, maximum_sctype Examples -------- >>> np.mintypecode(['d', 'f', 'S']) 'd' >>> x = np.array([1.1, 2-3.j]) >>> np.mintypecode(x) 'D' >>> np.mintypecode('abceh', default='G') 'G' " :arglists '[[typechars & [{typeset :typeset, default :default}]] [typechars & [{typeset :typeset}]] [typechars]]} mintypecode (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "mintypecode")))) (def ^{:doc " Return the cumulative product of elements along a given axis. Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative product is computed. By default the input is flattened. dtype : dtype, optional Type of the returned array, as well as of the accumulator in which the elements are multiplied. If *dtype* is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used instead. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type of the resulting values will be cast if necessary. Returns ------- cumprod : ndarray A new array holding the result is returned unless `out` is specified, in which case a reference to out is returned. See Also -------- :ref:`ufuncs-output-type` Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow. Examples -------- >>> a = np.array([1,2,3]) >>> np.cumprod(a) # intermediate results 1, 1*2 ... # total product 1*2*3 = 6 array([1, 2, 6]) >>> a = np.array([[1, 2, 3], [4, 5, 6]]) >>> np.cumprod(a, dtype=float) # specify type of output array([ 1., 2., 6., 24., 120., 720.]) The cumulative product for each column (i.e., over the rows) of `a`: >>> np.cumprod(a, axis=0) array([[ 1, 2, 3], [ 4, 10, 18]]) The cumulative product for each row (i.e. over the columns) of `a`: >>> np.cumprod(a,axis=1) array([[ 1, 2, 6], [ 4, 20, 120]]) " :arglists '[[& [args {:as kwargs}]]]} cumprod (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cumprod")))) (def ^{:doc " Repeat elements of an array. Parameters ---------- a : array_like Input array. repeats : int or array of ints The number of repetitions for each element. `repeats` is broadcasted to fit the shape of the given axis. axis : int, optional The axis along which to repeat values. By default, use the flattened input array, and return a flat output array. Returns ------- repeated_array : ndarray Output array which has the same shape as `a`, except along the given axis. See Also -------- tile : Tile an array. unique : Find the unique elements of an array. Examples -------- >>> np.repeat(3, 4) array([3, 3, 3, 3]) >>> x = np.array([[1,2],[3,4]]) >>> np.repeat(x, 2) array([1, 1, 2, 2, 3, 3, 4, 4]) >>> np.repeat(x, 3, axis=1) array([[1, 1, 1, 2, 2, 2], [3, 3, 3, 4, 4, 4]]) >>> np.repeat(x, [1, 2], axis=0) array([[1, 2], [3, 4], [3, 4]]) " :arglists '[[& [args {:as kwargs}]]]} repeat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "repeat")))) (def ^{:doc " matrix(data, dtype=None, copy=True) .. note:: It is no longer recommended to use this class, even for linear algebra. Instead use regular arrays. The class may be removed in the future. Returns a matrix from an array-like object, or from a string of data. A matrix is a specialized 2-D array that retains its 2-D nature through operations. It has certain special operators, such as ``*`` (matrix multiplication) and ``**`` (matrix power). Parameters ---------- data : array_like or string If `data` is a string, it is interpreted as a matrix with commas or spaces separating columns, and semicolons separating rows. dtype : data-type Data-type of the output matrix. copy : bool If `data` is already an `ndarray`, then this flag determines whether the data is copied (the default), or whether a view is constructed. See Also -------- array Examples -------- >>> a = np.matrix('1 2; 3 4') >>> a matrix([[1, 2], [3, 4]]) >>> np.matrix([[1, 2], [3, 4]]) matrix([[1, 2], [3, 4]]) " :arglists '[[self & [args {:as kwargs}]]]} matrix (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "matrix")))) (def ^{:doc "less_equal(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the truth value of (x1 <= x2) element-wise. Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array, element-wise comparison of `x1` and `x2`. Typically of type bool, unless ``dtype=object`` is passed. This is a scalar if both `x1` and `x2` are scalars. See Also -------- greater, less, greater_equal, equal, not_equal Examples -------- >>> np.less_equal([4, 2, 1], [2, 2, 2]) array([False, True, True]) The ``<=`` operator can be used as a shorthand for ``np.less_equal`` on ndarrays. >>> a = np.array([4, 2, 1]) >>> b = np.array([2, 2, 2]) >>> a <= b array([False, True, True])" :arglists '[[self & [args {:as kwargs}]]]} less_equal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "less_equal")))) (def ^{:doc " Return the Kaiser window. The Kaiser window is a taper formed by using a Bessel function. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. beta : float Shape parameter for window. Returns ------- out : array The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd). See Also -------- bartlett, blackman, hamming, hanning Notes ----- The Kaiser window is defined as .. math:: w(n) = I_0\\left( \\beta \\sqrt{1-\\frac{4n^2}{(M-1)^2}} \\right)/I_0(\\beta) with .. math:: \\quad -\\frac{M-1}{2} \\leq n \\leq \\frac{M-1}{2}, where :math:`I_0` is the modified zeroth-order Bessel function. The Kaiser was named for Jim Kaiser, who discovered a simple approximation to the DPSS window based on Bessel functions. The Kaiser window is a very good approximation to the Digital Prolate Spheroidal Sequence, or Slepian window, which is the transform which maximizes the energy in the main lobe of the window relative to total energy. The Kaiser can approximate many other windows by varying the beta parameter. ==== ======================= beta Window shape ==== ======================= 0 Rectangular 5 Similar to a Hamming 6 Similar to a Hanning 8.6 Similar to a Blackman ==== ======================= A beta value of 14 is probably a good starting point. Note that as beta gets large, the window narrows, and so the number of samples needs to be large enough to sample the increasingly narrow spike, otherwise NaNs will get returned. Most references to the Kaiser window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means \"removing the foot\", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. References ---------- .. [1] J. F. Kaiser, \"Digital Filters\" - Ch 7 in \"Systems analysis by digital computer\", Editors: F.F. Kuo and J.F. Kaiser, p 218-285. John Wiley and Sons, New York, (1966). .. [2] E.R. Kanasewich, \"Time Sequence Analysis in Geophysics\", The University of Alberta Press, 1975, pp. 177-178. .. [3] Wikipedia, \"Window function\", https://en.wikipedia.org/wiki/Window_function Examples -------- >>> import matplotlib.pyplot as plt >>> np.kaiser(12, 14) array([7.72686684e-06, 3.46009194e-03, 4.65200189e-02, # may vary 2.29737120e-01, 5.99885316e-01, 9.45674898e-01, 9.45674898e-01, 5.99885316e-01, 2.29737120e-01, 4.65200189e-02, 3.46009194e-03, 7.72686684e-06]) Plot the window and the frequency response: >>> from numpy.fft import fft, fftshift >>> window = np.kaiser(51, 14) >>> plt.plot(window) [] >>> plt.title(\"Kaiser window\") Text(0.5, 1.0, 'Kaiser window') >>> plt.ylabel(\"Amplitude\") Text(0, 0.5, 'Amplitude') >>> plt.xlabel(\"Sample\") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure()
>>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> response = 20 * np.log10(mag) >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [] >>> plt.title(\"Frequency response of Kaiser window\") Text(0.5, 1.0, 'Frequency response of Kaiser window') >>> plt.ylabel(\"Magnitude [dB]\") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel(\"Normalized frequency [cycles per sample]\") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> plt.axis('tight') (-0.5, 0.5, -100.0, ...) # may vary >>> plt.show() " :arglists '[[M beta]]} kaiser (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "kaiser")))) (def ^{:doc "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." :arglists '[[self & [args {:as kwargs}]]]} add_newdoc_ufunc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "add_newdoc_ufunc")))) (def ^{:doc "Create a memory-map to an array stored in a *binary* file on disk. Memory-mapped files are used for accessing small segments of large files on disk, without reading the entire file into memory. NumPy's memmap's are array-like objects. This differs from Python's ``mmap`` module, which uses file-like objects. This subclass of ndarray has some unpleasant interactions with some operations, because it doesn't quite fit properly as a subclass. An alternative to using this subclass is to create the ``mmap`` object yourself, then create an ndarray with ndarray.__new__ directly, passing the object created in its 'buffer=' parameter. This class may at some point be turned into a factory function which returns a view into an mmap buffer. Flush the memmap instance to write the changes to the file. Currently there is no API to close the underlying ``mmap``. It is tricky to ensure the resource is actually closed, since it may be shared between different memmap instances. Parameters ---------- filename : str, file-like object, or pathlib.Path instance The file name or file object to be used as the array data buffer. dtype : data-type, optional The data-type used to interpret the file contents. Default is `uint8`. mode : {'r+', 'r', 'w+', 'c'}, optional The file is opened in this mode: +------+-------------------------------------------------------------+ | 'r' | Open existing file for reading only. | +------+-------------------------------------------------------------+ | 'r+' | Open existing file for reading and writing. | +------+-------------------------------------------------------------+ | 'w+' | Create or overwrite existing file for reading and writing. | +------+-------------------------------------------------------------+ | 'c' | Copy-on-write: assignments affect data in memory, but | | | changes are not saved to disk. The file on disk is | | | read-only. | +------+-------------------------------------------------------------+ Default is 'r+'. offset : int, optional In the file, array data starts at this offset. Since `offset` is measured in bytes, it should normally be a multiple of the byte-size of `dtype`. When ``mode != 'r'``, even positive offsets beyond end of file are valid; The file will be extended to accommodate the additional data. By default, ``memmap`` will start at the beginning of the file, even if ``filename`` is a file pointer ``fp`` and ``fp.tell() != 0``. shape : tuple, optional The desired shape of the array. If ``mode == 'r'`` and the number of remaining bytes after `offset` is not a multiple of the byte-size of `dtype`, you must specify `shape`. By default, the returned array will be 1-D with the number of elements determined by file size and data-type. order : {'C', 'F'}, optional Specify the order of the ndarray memory layout: :term:`row-major`, C-style or :term:`column-major`, Fortran-style. This only has an effect if the shape is greater than 1-D. The default order is 'C'. Attributes ---------- filename : str or pathlib.Path instance Path to the mapped file. offset : int Offset position in the file. mode : str File mode. Methods ------- flush Flush any changes in memory to file on disk. When you delete a memmap object, flush is called first to write changes to disk. See also -------- lib.format.open_memmap : Create or load a memory-mapped ``.npy`` file. Notes ----- The memmap object can be used anywhere an ndarray is accepted. Given a memmap ``fp``, ``isinstance(fp, numpy.ndarray)`` returns ``True``. Memory-mapped files cannot be larger than 2GB on 32-bit systems. When a memmap causes a file to be created or extended beyond its current size in the filesystem, the contents of the new part are unspecified. On systems with POSIX filesystem semantics, the extended part will be filled with zero bytes. Examples -------- >>> data = np.arange(12, dtype='float32') >>> data.resize((3,4)) This example uses a temporary file so that doctest doesn't write files to your directory. You would use a 'normal' filename. >>> from tempfile import mkdtemp >>> import os.path as path >>> filename = path.join(mkdtemp(), 'newfile.dat') Create a memmap with dtype and shape that matches our data: >>> fp = np.memmap(filename, dtype='float32', mode='w+', shape=(3,4)) >>> fp memmap([[0., 0., 0., 0.], [0., 0., 0., 0.], [0., 0., 0., 0.]], dtype=float32) Write data to memmap array: >>> fp[:] = data[:] >>> fp memmap([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.]], dtype=float32) >>> fp.filename == path.abspath(filename) True Flushes memory changes to disk in order to read them back >>> fp.flush() Load the memmap and verify data was stored: >>> newfp = np.memmap(filename, dtype='float32', mode='r', shape=(3,4)) >>> newfp memmap([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.]], dtype=float32) Read-only memmap: >>> fpr = np.memmap(filename, dtype='float32', mode='r', shape=(3,4)) >>> fpr.flags.writeable False Copy-on-write memmap: >>> fpc = np.memmap(filename, dtype='float32', mode='c', shape=(3,4)) >>> fpc.flags.writeable True It's possible to assign to copy-on-write array, but values are only written into the memory copy of the array, and not written to disk: >>> fpc memmap([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.]], dtype=float32) >>> fpc[0,:] = 0 >>> fpc memmap([[ 0., 0., 0., 0.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.]], dtype=float32) File on disk is unchanged: >>> fpr memmap([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.]], dtype=float32) Offset into a memmap: >>> fpo = np.memmap(filename, dtype='float32', mode='r', offset=16) >>> fpo memmap([ 4., 5., 6., 7., 8., 9., 10., 11.], dtype=float32) " :arglists '[[self & [args {:as kwargs}]]]} memmap (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "memmap")))) (def ^{:doc ""} RAISE 2) (def ^{:doc " Return the indices of the elements that are non-zero. Returns a tuple of arrays, one for each dimension of `a`, containing the indices of the non-zero elements in that dimension. The values in `a` are always tested and returned in row-major, C-style order. To group the indices by element, rather than dimension, use `argwhere`, which returns a row for each non-zero element. .. note:: When called on a zero-d array or scalar, ``nonzero(a)`` is treated as ``nonzero(atleast_1d(a))``. .. deprecated:: 1.17.0 Use `atleast_1d` explicitly if this behavior is deliberate. Parameters ---------- a : array_like Input array. Returns ------- tuple_of_arrays : tuple Indices of elements that are non-zero. See Also -------- flatnonzero : Return indices that are non-zero in the flattened version of the input array. ndarray.nonzero : Equivalent ndarray method. count_nonzero : Counts the number of non-zero elements in the input array. Notes ----- While the nonzero values can be obtained with ``a[nonzero(a)]``, it is recommended to use ``x[x.astype(bool)]`` or ``x[x != 0]`` instead, which will correctly handle 0-d arrays. Examples -------- >>> x = np.array([[3, 0, 0], [0, 4, 0], [5, 6, 0]]) >>> x array([[3, 0, 0], [0, 4, 0], [5, 6, 0]]) >>> np.nonzero(x) (array([0, 1, 2, 2]), array([0, 1, 0, 1])) >>> x[np.nonzero(x)] array([3, 4, 5, 6]) >>> np.transpose(np.nonzero(x)) array([[0, 0], [1, 1], [2, 0], [2, 1]]) A common use for ``nonzero`` is to find the indices of an array, where a condition is True. Given an array `a`, the condition `a` > 3 is a boolean array and since False is interpreted as 0, np.nonzero(a > 3) yields the indices of the `a` where the condition is true. >>> a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]) >>> a > 3 array([[False, False, False], [ True, True, True], [ True, True, True]]) >>> np.nonzero(a > 3) (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2])) Using this result to index `a` is equivalent to using the mask directly: >>> a[np.nonzero(a > 3)] array([4, 5, 6, 7, 8, 9]) >>> a[a > 3] # prefer this spelling array([4, 5, 6, 7, 8, 9]) ``nonzero`` can also be called as a method of the array. >>> (a > 3).nonzero() (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2])) " :arglists '[[& [args {:as kwargs}]]]} nonzero (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nonzero")))) (def ^{:doc "Concrete implementation of SourceLoader using the file system."} __loader__ (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "__loader__")))) (def ^{:doc " Roll the specified axis backwards, until it lies in a given position. This function continues to be supported for backward compatibility, but you should prefer `moveaxis`. The `moveaxis` function was added in NumPy 1.11. Parameters ---------- a : ndarray Input array. axis : int The axis to be rolled. The positions of the other axes do not change relative to one another. start : int, optional When ``start <= axis``, the axis is rolled back until it lies in this position. When ``start > axis``, the axis is rolled until it lies before this position. The default, 0, results in a \"complete\" roll. The following table describes how negative values of ``start`` are interpreted: .. table:: :align: left +-------------------+----------------------+ | ``start`` | Normalized ``start`` | +===================+======================+ | ``-(arr.ndim+1)`` | raise ``AxisError`` | +-------------------+----------------------+ | ``-arr.ndim`` | 0 | +-------------------+----------------------+ | |vdots| | |vdots| | +-------------------+----------------------+ | ``-1`` | ``arr.ndim-1`` | +-------------------+----------------------+ | ``0`` | ``0`` | +-------------------+----------------------+ | |vdots| | |vdots| | +-------------------+----------------------+ | ``arr.ndim`` | ``arr.ndim`` | +-------------------+----------------------+ | ``arr.ndim + 1`` | raise ``AxisError`` | +-------------------+----------------------+ .. |vdots| unicode:: U+22EE .. Vertical Ellipsis Returns ------- res : ndarray For NumPy >= 1.10.0 a view of `a` is always returned. For earlier NumPy versions a view of `a` is returned only if the order of the axes is changed, otherwise the input array is returned. See Also -------- moveaxis : Move array axes to new positions. roll : Roll the elements of an array by a number of positions along a given axis. Examples -------- >>> a = np.ones((3,4,5,6)) >>> np.rollaxis(a, 3, 1).shape (3, 6, 4, 5) >>> np.rollaxis(a, 2).shape (5, 3, 4, 6) >>> np.rollaxis(a, 1, 4).shape (3, 5, 6, 4) " :arglists '[[& [args {:as kwargs}]]]} rollaxis (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "rollaxis")))) (def ^{:doc ""} ERR_RAISE 2) (def ^{:doc "isnat(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Test element-wise for NaT (not a time) and return result as a boolean array. .. versionadded:: 1.13.0 Parameters ---------- x : array_like Input array with datetime or timedelta data type. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or bool True where ``x`` is NaT, false otherwise. This is a scalar if `x` is a scalar. See Also -------- isnan, isinf, isneginf, isposinf, isfinite Examples -------- >>> np.isnat(np.datetime64(\"NaT\")) True >>> np.isnat(np.datetime64(\"2016-01-01\")) False >>> np.isnat(np.array([\"NaT\", \"2016-01-01\"], dtype=\"datetime64[ns]\")) array([ True, False])" :arglists '[[self & [args {:as kwargs}]]]} isnat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isnat")))) (def ^{:doc " Return the roots of a polynomial with coefficients given in p. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. The values in the rank-1 array `p` are coefficients of a polynomial. If the length of `p` is n+1 then the polynomial is described by:: p[0] * x**n + p[1] * x**(n-1) + ... + p[n-1]*x + p[n] Parameters ---------- p : array_like Rank-1 array of polynomial coefficients. Returns ------- out : ndarray An array containing the roots of the polynomial. Raises ------ ValueError When `p` cannot be converted to a rank-1 array. See also -------- poly : Find the coefficients of a polynomial with a given sequence of roots. polyval : Compute polynomial values. polyfit : Least squares polynomial fit. poly1d : A one-dimensional polynomial class. Notes ----- The algorithm relies on computing the eigenvalues of the companion matrix [1]_. References ---------- .. [1] R. A. Horn & C. R. Johnson, *Matrix Analysis*. Cambridge, UK: Cambridge University Press, 1999, pp. 146-7. Examples -------- >>> coeff = [3.2, 2, 1] >>> np.roots(coeff) array([-0.3125+0.46351241j, -0.3125-0.46351241j]) " :arglists '[[& [args {:as kwargs}]]]} roots (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "roots")))) (def ^{:doc " Return the maximum of an array or maximum along an axis. Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional Axis or axes along which to operate. By default, flattened input is used. .. versionadded:: 1.7.0 If this is a tuple of ints, the maximum is selected over multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See :ref:`ufuncs-output-type` for more details. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `amax` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. initial : scalar, optional The minimum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.15.0 where : array_like of bool, optional Elements to compare for the maximum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.17.0 Returns ------- amax : ndarray or scalar Maximum of `a`. If `axis` is None, the result is a scalar value. If `axis` is given, the result is an array of dimension ``a.ndim - 1``. See Also -------- amin : The minimum value of an array along a given axis, propagating any NaNs. nanmax : The maximum value of an array along a given axis, ignoring any NaNs. maximum : Element-wise maximum of two arrays, propagating any NaNs. fmax : Element-wise maximum of two arrays, ignoring any NaNs. argmax : Return the indices of the maximum values. nanmin, minimum, fmin Notes ----- NaN values are propagated, that is if at least one item is NaN, the corresponding max value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmax. Don't use `amax` for element-wise comparison of 2 arrays; when ``a.shape[0]`` is 2, ``maximum(a[0], a[1])`` is faster than ``amax(a, axis=0)``. Examples -------- >>> a = np.arange(4).reshape((2,2)) >>> a array([[0, 1], [2, 3]]) >>> np.amax(a) # Maximum of the flattened array 3 >>> np.amax(a, axis=0) # Maxima along the first axis array([2, 3]) >>> np.amax(a, axis=1) # Maxima along the second axis array([1, 3]) >>> np.amax(a, where=[False, True], initial=-1, axis=0) array([-1, 3]) >>> b = np.arange(5, dtype=float) >>> b[2] = np.NaN >>> np.amax(b) nan >>> np.amax(b, where=~np.isnan(b), initial=-1) 4.0 >>> np.nanmax(b) 4.0 You can use an initial value to compute the maximum of an empty slice, or to initialize it to a different value: >>> np.max([[-50], [10]], axis=-1, initial=0) array([ 0, 10]) Notice that the initial value is used as one of the elements for which the maximum is determined, unlike for the default argument Python's max function, which is only used for empty iterables. >>> np.max([5], initial=6) 6 >>> max([5], default=6) 5 " :arglists '[[& [args {:as kwargs}]]]} max (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "max")))) (def ^{:doc " Get help information for a function, class, or module. Parameters ---------- object : object or str, optional Input object or name to get information about. If `object` is a numpy object, its docstring is given. If it is a string, available modules are searched for matching objects. If None, information about `info` itself is returned. maxwidth : int, optional Printing width. output : file like object, optional File like object that the output is written to, default is ``stdout``. The object has to be opened in 'w' or 'a' mode. toplevel : str, optional Start search at this level. See Also -------- source, lookfor Notes ----- When used interactively with an object, ``np.info(obj)`` is equivalent to ``help(obj)`` on the Python prompt or ``obj?`` on the IPython prompt. Examples -------- >>> np.info(np.polyval) # doctest: +SKIP polyval(p, x) Evaluate the polynomial p at x. ... When using a string for `object` it is possible to get multiple results. >>> np.info('fft') # doctest: +SKIP *** Found in numpy *** Core FFT routines ... *** Found in numpy.fft *** fft(a, n=None, axis=-1) ... *** Repeat reference found in numpy.fft.fftpack *** *** Total of 3 references found. *** " :arglists '[[& [{object :object, maxwidth :maxwidth, output :output, toplevel :toplevel}]] [& [{object :object, maxwidth :maxwidth, output :output}]] [& [{object :object, maxwidth :maxwidth}]] [& [{object :object}]] []]} info (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "info")))) (def ^{:doc " Compatibility module. This module contains duplicated code from Python itself or 3rd party extensions, which may be included for the following reasons: * compatibility * we may only need a small subset of the copied library/module "} compat (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "compat")))) (def ^{:doc " Split an array into multiple sub-arrays vertically (row-wise). Please refer to the ``split`` documentation. ``vsplit`` is equivalent to ``split`` with `axis=0` (default), the array is always split along the first axis regardless of the array dimension. See Also -------- split : Split an array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(16.0).reshape(4, 4) >>> x array([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.], [12., 13., 14., 15.]]) >>> np.vsplit(x, 2) [array([[0., 1., 2., 3.], [4., 5., 6., 7.]]), array([[ 8., 9., 10., 11.], [12., 13., 14., 15.]])] >>> np.vsplit(x, np.array([3, 6])) [array([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.]]), array([[12., 13., 14., 15.]]), array([], shape=(0, 4), dtype=float64)] With a higher dimensional array the split is still along the first axis. >>> x = np.arange(8.0).reshape(2, 2, 2) >>> x array([[[0., 1.], [2., 3.]], [[4., 5.], [6., 7.]]]) >>> np.vsplit(x, 2) [array([[[0., 1.], [2., 3.]]]), array([[[4., 5.], [6., 7.]]])] " :arglists '[[& [args {:as kwargs}]]]} vsplit (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "vsplit")))) (def ^{:doc " Difference (subtraction) of two polynomials. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. Given two polynomials `a1` and `a2`, returns ``a1 - a2``. `a1` and `a2` can be either array_like sequences of the polynomials' coefficients (including coefficients equal to zero), or `poly1d` objects. Parameters ---------- a1, a2 : array_like or poly1d Minuend and subtrahend polynomials, respectively. Returns ------- out : ndarray or poly1d Array or `poly1d` object of the difference polynomial's coefficients. See Also -------- polyval, polydiv, polymul, polyadd Examples -------- .. math:: (2 x^2 + 10 x - 2) - (3 x^2 + 10 x -4) = (-x^2 + 2) >>> np.polysub([2, 10, -2], [3, 10, -4]) array([-1, 0, 2]) " :arglists '[[& [args {:as kwargs}]]]} polysub (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polysub")))) (def ^{:doc " True if two arrays have the same shape and elements, False otherwise. Parameters ---------- a1, a2 : array_like Input arrays. equal_nan : bool Whether to compare NaN's as equal. If the dtype of a1 and a2 is complex, values will be considered equal if either the real or the imaginary component of a given value is ``nan``. .. versionadded:: 1.19.0 Returns ------- b : bool Returns True if the arrays are equal. See Also -------- allclose: Returns True if two arrays are element-wise equal within a tolerance. array_equiv: Returns True if input arrays are shape consistent and all elements equal. Examples -------- >>> np.array_equal([1, 2], [1, 2]) True >>> np.array_equal(np.array([1, 2]), np.array([1, 2])) True >>> np.array_equal([1, 2], [1, 2, 3]) False >>> np.array_equal([1, 2], [1, 4]) False >>> a = np.array([1, np.nan]) >>> np.array_equal(a, a) False >>> np.array_equal(a, a, equal_nan=True) True When ``equal_nan`` is True, complex values with nan components are considered equal if either the real *or* the imaginary components are nan. >>> a = np.array([1 + 1j]) >>> b = a.copy() >>> a.real = np.nan >>> b.imag = np.nan >>> np.array_equal(a, b, equal_nan=True) True " :arglists '[[& [args {:as kwargs}]]]} array_equal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "array_equal")))) (def ^{:doc " Return evenly spaced numbers over a specified interval. Returns `num` evenly spaced samples, calculated over the interval [`start`, `stop`]. The endpoint of the interval can optionally be excluded. .. versionchanged:: 1.16.0 Non-scalar `start` and `stop` are now supported. .. versionchanged:: 1.20.0 Values are rounded towards ``-inf`` instead of ``0`` when an integer ``dtype`` is specified. The old behavior can still be obtained with ``np.linspace(start, stop, num).astype(int)`` Parameters ---------- start : array_like The starting value of the sequence. stop : array_like The end value of the sequence, unless `endpoint` is set to False. In that case, the sequence consists of all but the last of ``num + 1`` evenly spaced samples, so that `stop` is excluded. Note that the step size changes when `endpoint` is False. num : int, optional Number of samples to generate. Default is 50. Must be non-negative. endpoint : bool, optional If True, `stop` is the last sample. Otherwise, it is not included. Default is True. retstep : bool, optional If True, return (`samples`, `step`), where `step` is the spacing between samples. dtype : dtype, optional The type of the output array. If `dtype` is not given, the data type is inferred from `start` and `stop`. The inferred dtype will never be an integer; `float` is chosen even if the arguments would produce an array of integers. .. versionadded:: 1.9.0 axis : int, optional The axis in the result to store the samples. Relevant only if start or stop are array-like. By default (0), the samples will be along a new axis inserted at the beginning. Use -1 to get an axis at the end. .. versionadded:: 1.16.0 Returns ------- samples : ndarray There are `num` equally spaced samples in the closed interval ``[start, stop]`` or the half-open interval ``[start, stop)`` (depending on whether `endpoint` is True or False). step : float, optional Only returned if `retstep` is True Size of spacing between samples. See Also -------- arange : Similar to `linspace`, but uses a step size (instead of the number of samples). geomspace : Similar to `linspace`, but with numbers spaced evenly on a log scale (a geometric progression). logspace : Similar to `geomspace`, but with the end points specified as logarithms. Examples -------- >>> np.linspace(2.0, 3.0, num=5) array([2. , 2.25, 2.5 , 2.75, 3. ]) >>> np.linspace(2.0, 3.0, num=5, endpoint=False) array([2. , 2.2, 2.4, 2.6, 2.8]) >>> np.linspace(2.0, 3.0, num=5, retstep=True) (array([2. , 2.25, 2.5 , 2.75, 3. ]), 0.25) Graphical illustration: >>> import matplotlib.pyplot as plt >>> N = 8 >>> y = np.zeros(N) >>> x1 = np.linspace(0, 10, N, endpoint=True) >>> x2 = np.linspace(0, 10, N, endpoint=False) >>> plt.plot(x1, y, 'o') [] >>> plt.plot(x2, y + 0.5, 'o') [] >>> plt.ylim([-0.5, 1]) (-0.5, 1) >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} linspace (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "linspace")))) (def ^{:doc " Interpret the input as a matrix. Unlike `matrix`, `asmatrix` does not make a copy if the input is already a matrix or an ndarray. Equivalent to ``matrix(data, copy=False)``. Parameters ---------- data : array_like Input data. dtype : data-type Data-type of the output matrix. Returns ------- mat : matrix `data` interpreted as a matrix. Examples -------- >>> x = np.array([[1, 2], [3, 4]]) >>> m = np.asmatrix(x) >>> x[0,0] = 5 >>> m matrix([[5, 2], [3, 4]]) " :arglists '[[data & [{dtype :dtype}]] [data]]} mat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "mat")))) (def ^{:doc "frombuffer(buffer, dtype=float, count=-1, offset=0, *, like=None) 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.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)" :arglists '[[self & [args {:as kwargs}]]]} frombuffer (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "frombuffer")))) (def ^{:doc "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) >>> for item in fl: ... print(item) ... 0 1 2 3 4 5 >>> fl[2:4] array([2, 3])" :arglists '[[self & [args {:as kwargs}]]]} flatiter (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "flatiter")))) (def ^{:doc " Set the size of the buffer used in ufuncs. Parameters ---------- size : int Size of buffer. " :arglists '[[size]]} setbufsize (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "setbufsize")))) (def ^{:doc ""} PZERO 0.0) (def ^{:doc "Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified."} __all__ (as-jvm/generic-python-as-list (py-global-delay (py/get-attr @src-obj* "__all__")))) (def ^{:doc " busday_count(begindates, enddates, weekmask='1111100', holidays=[], busdaycal=None, out=None) Counts the number of valid days between `begindates` and `enddates`, not including the day of `enddates`. If ``enddates`` specifies a date value that is earlier than the corresponding ``begindates`` date value, the count will be negative. .. versionadded:: 1.7.0 Parameters ---------- begindates : array_like of datetime64[D] The array of the first dates for counting. enddates : array_like of datetime64[D] The array of the end dates for counting, which are excluded from the count themselves. 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. They 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. busdaycal : busdaycalendar, optional A `busdaycalendar` object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided. out : array of int, optional If provided, this array is filled with the result. Returns ------- out : array of int An array with a shape from broadcasting ``begindates`` and ``enddates`` together, containing the number of valid days between the begin and end dates. See Also -------- busdaycalendar: An object that specifies a custom set of valid days. is_busday : Returns a boolean array indicating valid days. busday_offset : Applies an offset counted in valid days. Examples -------- >>> # Number of weekdays in January 2011 ... np.busday_count('2011-01', '2011-02') 21 >>> # Number of weekdays in 2011 >>> np.busday_count('2011', '2012') 260 >>> # Number of Saturdays in 2011 ... np.busday_count('2011', '2012', weekmask='Sat') 53 " :arglists '[[& [args {:as kwargs}]]]} busday_count (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "busday_count")))) (def ^{:doc " Return an antiderivative (indefinite integral) of a polynomial. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. The returned order `m` antiderivative `P` of polynomial `p` satisfies :math:`\\frac{d^m}{dx^m}P(x) = p(x)` and is defined up to `m - 1` integration constants `k`. The constants determine the low-order polynomial part .. math:: \\frac{k_{m-1}}{0!} x^0 + \\ldots + \\frac{k_0}{(m-1)!}x^{m-1} of `P` so that :math:`P^{(j)}(0) = k_{m-j-1}`. Parameters ---------- p : array_like or poly1d Polynomial to integrate. A sequence is interpreted as polynomial coefficients, see `poly1d`. m : int, optional Order of the antiderivative. (Default: 1) k : list of `m` scalars or scalar, optional Integration constants. They are given in the order of integration: those corresponding to highest-order terms come first. If ``None`` (default), all constants are assumed to be zero. If `m = 1`, a single scalar can be given instead of a list. See Also -------- polyder : derivative of a polynomial poly1d.integ : equivalent method Examples -------- The defining property of the antiderivative: >>> p = np.poly1d([1,1,1]) >>> P = np.polyint(p) >>> P poly1d([ 0.33333333, 0.5 , 1. , 0. ]) # may vary >>> np.polyder(P) == p True The integration constants default to zero, but can be specified: >>> P = np.polyint(p, 3) >>> P(0) 0.0 >>> np.polyder(P)(0) 0.0 >>> np.polyder(P, 2)(0) 0.0 >>> P = np.polyint(p, 3, k=[6,5,3]) >>> P poly1d([ 0.01666667, 0.04166667, 0.16666667, 3. , 5. , 3. ]) # may vary Note that 3 = 6 / 2!, and that the constants are given in the order of integrations. Constant of the highest-order polynomial term comes first: >>> np.polyder(P, 2)(0) 6.0 >>> np.polyder(P, 1)(0) 5.0 >>> P(0) 3.0 " :arglists '[[& [args {:as kwargs}]]]} polyint (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polyint")))) (def ^{:doc "maximum(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Element-wise maximum of array elements. Compare two arrays and returns a new array containing the element-wise maxima. If one of the elements being compared is a NaN, then that element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are propagated. Parameters ---------- x1, x2 : array_like The arrays holding the elements to be compared. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The maximum of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars. See Also -------- minimum : Element-wise minimum of two arrays, propagates NaNs. fmax : Element-wise maximum of two arrays, ignores NaNs. amax : The maximum value of an array along a given axis, propagates NaNs. nanmax : The maximum value of an array along a given axis, ignores NaNs. fmin, amin, nanmin Notes ----- The maximum is equivalent to ``np.where(x1 >= x2, x1, x2)`` when neither x1 nor x2 are nans, but it is faster and does proper broadcasting. Examples -------- >>> np.maximum([2, 3, 4], [1, 5, 2]) array([2, 5, 4]) >>> np.maximum(np.eye(2), [0.5, 2]) # broadcasting array([[ 1. , 2. ], [ 0.5, 2. ]]) >>> np.maximum([np.nan, 0, np.nan], [0, np.nan, np.nan]) array([nan, nan, nan]) >>> np.maximum(np.Inf, 1) inf" :arglists '[[self & [args {:as kwargs}]]]} maximum (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "maximum")))) (def ^{:doc "negative(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Numerical negative, element-wise. Parameters ---------- x : array_like or scalar Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar Returned array or scalar: `y = -x`. This is a scalar if `x` is a scalar. Examples -------- >>> np.negative([1.,-1.]) array([-1., 1.]) The unary ``-`` operator can be used as a shorthand for ``np.negative`` on ndarrays. >>> x1 = np.array(([1., -1.])) >>> -x1 array([-1., 1.])" :arglists '[[self & [args {:as kwargs}]]]} negative (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "negative")))) (def ^{:doc " Return specified diagonals. If `a` is 2-D, returns the diagonal of `a` with the given offset, i.e., the collection of elements of the form ``a[i, i+offset]``. If `a` has more than two dimensions, then the axes specified by `axis1` and `axis2` are used to determine the 2-D sub-array whose diagonal is returned. The shape of the resulting array can be determined by removing `axis1` and `axis2` and appending an index to the right equal to the size of the resulting diagonals. In versions of NumPy prior to 1.7, this function always returned a new, independent array containing a copy of the values in the diagonal. In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal, but depending on this fact is deprecated. Writing to the resulting array continues to work as it used to, but a FutureWarning is issued. Starting in NumPy 1.9 it returns a read-only view on the original array. Attempting to write to the resulting array will produce an error. In some future release, it will return a read/write view and writing to the returned array will alter your original array. The returned array will have the same type as the input array. If you don't write to the array returned by this function, then you can just ignore all of the above. If you depend on the current behavior, then we suggest copying the returned array explicitly, i.e., use ``np.diagonal(a).copy()`` instead of just ``np.diagonal(a)``. This will work with both past and future versions of NumPy. Parameters ---------- a : array_like Array from which the diagonals are taken. offset : int, optional Offset of the diagonal from the main diagonal. Can be positive or negative. Defaults to main diagonal (0). axis1 : int, optional Axis to be used as the first axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to first axis (0). axis2 : int, optional Axis to be used as the second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to second axis (1). Returns ------- array_of_diagonals : ndarray If `a` is 2-D, then a 1-D array containing the diagonal and of the same type as `a` is returned unless `a` is a `matrix`, in which case a 1-D array rather than a (2-D) `matrix` is returned in order to maintain backward compatibility. If ``a.ndim > 2``, then the dimensions specified by `axis1` and `axis2` are removed, and a new axis inserted at the end corresponding to the diagonal. Raises ------ ValueError If the dimension of `a` is less than 2. See Also -------- diag : MATLAB work-a-like for 1-D and 2-D arrays. diagflat : Create diagonal arrays. trace : Sum along diagonals. Examples -------- >>> a = np.arange(4).reshape(2,2) >>> a array([[0, 1], [2, 3]]) >>> a.diagonal() array([0, 3]) >>> a.diagonal(1) array([1]) A 3-D example: >>> a = np.arange(8).reshape(2,2,2); a array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]]) >>> a.diagonal(0, # Main diagonals of two arrays created by skipping ... 0, # across the outer(left)-most axis last and ... 1) # the \"middle\" (row) axis first. array([[0, 6], [1, 7]]) The sub-arrays whose main diagonals we just obtained; note that each corresponds to fixing the right-most (column) axis, and that the diagonals are \"packed\" in rows. >>> a[:,:,0] # main diagonal is [0 6] array([[0, 2], [4, 6]]) >>> a[:,:,1] # main diagonal is [1 7] array([[1, 3], [5, 7]]) The anti-diagonal can be obtained by reversing the order of elements using either `numpy.flipud` or `numpy.fliplr`. >>> a = np.arange(9).reshape(3, 3) >>> a array([[0, 1, 2], [3, 4, 5], [6, 7, 8]]) >>> np.fliplr(a).diagonal() # Horizontal flip array([2, 4, 6]) >>> np.flipud(a).diagonal() # Vertical flip array([6, 4, 2]) Note that the order in which the diagonal is retrieved varies depending on the flip function. " :arglists '[[& [args {:as kwargs}]]]} diagonal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "diagonal")))) (def ^{:doc " einsum_path(subscripts, *operands, optimize='greedy') Evaluates the lowest cost contraction order for an einsum expression by considering the creation of intermediate arrays. Parameters ---------- subscripts : str Specifies the subscripts for summation. *operands : list of array_like These are the arrays for the operation. optimize : {bool, list, tuple, 'greedy', 'optimal'} Choose the type of path. If a tuple is provided, the second argument is assumed to be the maximum intermediate size created. If only a single argument is provided the largest input or output array size is used as a maximum intermediate size. * if a list is given that starts with ``einsum_path``, uses this as the contraction path * if False no optimization is taken * if True defaults to the 'greedy' algorithm * 'optimal' An algorithm that combinatorially explores all possible ways of contracting the listed tensors and choosest the least costly path. Scales exponentially with the number of terms in the contraction. * 'greedy' An algorithm that chooses the best pair contraction at each step. Effectively, this algorithm searches the largest inner, Hadamard, and then outer products at each step. Scales cubically with the number of terms in the contraction. Equivalent to the 'optimal' path for most contractions. Default is 'greedy'. Returns ------- path : list of tuples A list representation of the einsum path. string_repr : str A printable representation of the einsum path. Notes ----- The resulting path indicates which terms of the input contraction should be contracted first, the result of this contraction is then appended to the end of the contraction list. This list can then be iterated over until all intermediate contractions are complete. See Also -------- einsum, linalg.multi_dot Examples -------- We can begin with a chain dot example. In this case, it is optimal to contract the ``b`` and ``c`` tensors first as represented by the first element of the path ``(1, 2)``. The resulting tensor is added to the end of the contraction and the remaining contraction ``(0, 1)`` is then completed. >>> np.random.seed(123) >>> a = np.random.rand(2, 2) >>> b = np.random.rand(2, 5) >>> c = np.random.rand(5, 2) >>> path_info = np.einsum_path('ij,jk,kl->il', a, b, c, optimize='greedy') >>> print(path_info[0]) ['einsum_path', (1, 2), (0, 1)] >>> print(path_info[1]) Complete contraction: ij,jk,kl->il # may vary Naive scaling: 4 Optimized scaling: 3 Naive FLOP count: 1.600e+02 Optimized FLOP count: 5.600e+01 Theoretical speedup: 2.857 Largest intermediate: 4.000e+00 elements ------------------------------------------------------------------------- scaling current remaining ------------------------------------------------------------------------- 3 kl,jk->jl ij,jl->il 3 jl,ij->il il->il A more complex index transformation example. >>> I = np.random.rand(10, 10, 10, 10) >>> C = np.random.rand(10, 10) >>> path_info = np.einsum_path('ea,fb,abcd,gc,hd->efgh', C, C, I, C, C, ... optimize='greedy') >>> print(path_info[0]) ['einsum_path', (0, 2), (0, 3), (0, 2), (0, 1)] >>> print(path_info[1]) Complete contraction: ea,fb,abcd,gc,hd->efgh # may vary Naive scaling: 8 Optimized scaling: 5 Naive FLOP count: 8.000e+08 Optimized FLOP count: 8.000e+05 Theoretical speedup: 1000.000 Largest intermediate: 1.000e+04 elements -------------------------------------------------------------------------- scaling current remaining -------------------------------------------------------------------------- 5 abcd,ea->bcde fb,gc,hd,bcde->efgh 5 bcde,fb->cdef gc,hd,cdef->efgh 5 cdef,gc->defg hd,defg->efgh 5 defg,hd->efgh efgh->efgh " :arglists '[[& [args {:as kwargs}]]]} einsum_path (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "einsum_path")))) (def ^{:doc ""} FPE_DIVIDEBYZERO 1) (def ^{:doc " Return an ndarray of the provided type that satisfies requirements. This function is useful to be sure that an array with the correct flags is returned for passing to compiled code (perhaps through ctypes). Parameters ---------- a : array_like The object to be converted to a type-and-requirement-satisfying array. dtype : data-type The required data-type. If None preserve the current dtype. If your application requires the data to be in native byteorder, include a byteorder specification as a part of the dtype specification. requirements : str or list of str The requirements list can be any of the following * 'F_CONTIGUOUS' ('F') - ensure a Fortran-contiguous array * 'C_CONTIGUOUS' ('C') - ensure a C-contiguous array * 'ALIGNED' ('A') - ensure a data-type aligned array * 'WRITEABLE' ('W') - ensure a writable array * 'OWNDATA' ('O') - ensure an array that owns its own data * 'ENSUREARRAY', ('E') - ensure a base array, instead of a subclass like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray Array with specified requirements and type if given. See Also -------- asarray : Convert input to an ndarray. asanyarray : Convert to an ndarray, but pass through ndarray subclasses. ascontiguousarray : Convert input to a contiguous array. asfortranarray : Convert input to an ndarray with column-major memory order. ndarray.flags : Information about the memory layout of the array. Notes ----- The returned array will be guaranteed to have the listed requirements by making a copy if needed. Examples -------- >>> x = np.arange(6).reshape(2,3) >>> x.flags C_CONTIGUOUS : True F_CONTIGUOUS : False OWNDATA : False WRITEABLE : True ALIGNED : True WRITEBACKIFCOPY : False UPDATEIFCOPY : False >>> y = np.require(x, dtype=np.float32, requirements=['A', 'O', 'W', 'F']) >>> y.flags C_CONTIGUOUS : False F_CONTIGUOUS : True OWNDATA : True WRITEABLE : True ALIGNED : True WRITEBACKIFCOPY : False UPDATEIFCOPY : False " :arglists '[[a & [{dtype :dtype, requirements :requirements, like :like}]] [a & [{dtype :dtype, like :like}]] [a & [{like :like}]]]} require (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "require")))) (def ^{:doc " Return the cumulative sum of array elements over a given axis treating Not a Numbers (NaNs) as zero. The cumulative sum does not change when NaNs are encountered and leading NaNs are replaced by zeros. Zeros are returned for slices that are all-NaN or empty. .. versionadded:: 1.12.0 Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative sum is computed. The default (None) is to compute the cumsum over the flattened array. dtype : dtype, optional Type of the returned array and of the accumulator in which the elements are summed. If `dtype` is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. Returns ------- nancumsum : ndarray. A new array holding the result is returned unless `out` is specified, in which it is returned. The result has the same size as `a`, and the same shape as `a` if `axis` is not None or `a` is a 1-d array. See Also -------- numpy.cumsum : Cumulative sum across array propagating NaNs. isnan : Show which elements are NaN. Examples -------- >>> np.nancumsum(1) array([1]) >>> np.nancumsum([1]) array([1]) >>> np.nancumsum([1, np.nan]) array([1., 1.]) >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nancumsum(a) array([1., 3., 6., 6.]) >>> np.nancumsum(a, axis=0) array([[1., 2.], [4., 2.]]) >>> np.nancumsum(a, axis=1) array([[1., 3.], [3., 3.]]) " :arglists '[[& [args {:as kwargs}]]]} nancumsum (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nancumsum")))) (def ^{:doc "Complex number type composed of two extended-precision floating-point numbers. :Character code: ``'G'`` :Canonical name: `numpy.clongdouble` :Alias: `numpy.clongfloat` :Alias: `numpy.longcomplex` :Alias on this platform: `numpy.complex256`: Complex number type composed of 2 128-bit extended-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} clongfloat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "clongfloat")))) (def ^{:doc "isnan(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Test element-wise for NaN and return result as a boolean array. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or bool True where ``x`` is NaN, false otherwise. This is a scalar if `x` is a scalar. See Also -------- isinf, isneginf, isposinf, isfinite, isnat Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Examples -------- >>> np.isnan(np.nan) True >>> np.isnan(np.inf) False >>> np.isnan([np.log(-1.),1.,np.log(0)]) array([ True, False, False])" :arglists '[[self & [args {:as kwargs}]]]} isnan (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isnan")))) (def ^{:doc "reciprocal(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the reciprocal of the argument, element-wise. Calculates ``1/x``. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray Return array. This is a scalar if `x` is a scalar. Notes ----- .. note:: This function is not designed to work with integers. For integer arguments with absolute value larger than 1 the result is always zero because of the way Python handles integer division. For integer zero the result is an overflow. Examples -------- >>> np.reciprocal(2.) 0.5 >>> np.reciprocal([1, 2., 3.33]) array([ 1. , 0.5 , 0.3003003])" :arglists '[[self & [args {:as kwargs}]]]} reciprocal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "reciprocal")))) (def ^{:doc " Return a partitioned copy of an array. Creates a copy of the array with its elements rearranged in such a way that the value of the element in k-th position is in the position it would be in a sorted array. All elements smaller than the k-th 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 ---------- a : array_like Array to be sorted. kth : int or sequence of ints Element index to partition by. The k-th value of the element 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 k-th it will partition all elements indexed by k-th of them into their sorted position at once. axis : int or None, optional Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts 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. 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. Returns ------- partitioned_array : ndarray Array of the same type and shape as `a`. See Also -------- ndarray.partition : Method to sort an array in-place. argpartition : Indirect partition. sort : Full sorting Notes ----- The various selection algorithms are characterized by their average speed, worst case performance, work space size, and whether they are stable. A stable sort keeps items with the same key in the same relative order. The available algorithms have the following properties: ================= ======= ============= ============ ======= kind speed worst case work space stable ================= ======= ============= ============ ======= 'introselect' 1 O(n) 0 no ================= ======= ============= ============ ======= All the partition algorithms make temporary copies of the data when partitioning along any but the last axis. Consequently, partitioning along the last axis is faster and uses less space than partitioning along any other axis. The sort order for complex numbers is lexicographic. If both the real and imaginary parts are non-nan then the order is determined by the real parts except when they are equal, in which case the order is determined by the imaginary parts. Examples -------- >>> a = np.array([3, 4, 2, 1]) >>> np.partition(a, 3) array([2, 1, 3, 4]) >>> np.partition(a, (1, 3)) array([1, 2, 3, 4]) " :arglists '[[& [args {:as kwargs}]]]} partition (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "partition")))) (def ^{:doc " where(condition, [x, y]) Return elements chosen from `x` or `y` depending on `condition`. .. note:: When only `condition` is provided, this function is a shorthand for ``np.asarray(condition).nonzero()``. Using `nonzero` directly should be preferred, as it behaves correctly for subclasses. The rest of this documentation covers only the case where all three arguments are provided. Parameters ---------- condition : array_like, bool Where True, yield `x`, otherwise yield `y`. x, y : array_like Values from which to choose. `x`, `y` and `condition` need to be broadcastable to some shape. Returns ------- out : ndarray An array with elements from `x` where `condition` is True, and elements from `y` elsewhere. See Also -------- choose nonzero : The function that is called when x and y are omitted Notes ----- If all the arrays are 1-D, `where` is equivalent to:: [xv if c else yv for c, xv, yv in zip(condition, x, y)] Examples -------- >>> a = np.arange(10) >>> a array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> np.where(a < 5, a, 10*a) array([ 0, 1, 2, 3, 4, 50, 60, 70, 80, 90]) This can be used on multidimensional arrays too: >>> np.where([[True, False], [True, True]], ... [[1, 2], [3, 4]], ... [[9, 8], [7, 6]]) array([[1, 8], [3, 4]]) The shapes of x, y, and the condition are broadcast together: >>> x, y = np.ogrid[:3, :4] >>> np.where(x < y, x, 10 + y) # both x and 10+y are broadcast array([[10, 0, 0, 0], [10, 11, 1, 1], [10, 11, 12, 2]]) >>> a = np.array([[0, 1, 2], ... [0, 2, 4], ... [0, 3, 6]]) >>> np.where(a < 4, a, -1) # -1 is broadcast array([[ 0, 1, 2], [ 0, 2, -1], [ 0, 3, -1]]) " :arglists '[[& [args {:as kwargs}]]]} where (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "where")))) (def ^{:doc "minimum(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Element-wise minimum of array elements. Compare two arrays and returns a new array containing the element-wise minima. If one of the elements being compared is a NaN, then that element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are propagated. Parameters ---------- x1, x2 : array_like The arrays holding the elements to be compared. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The minimum of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars. See Also -------- maximum : Element-wise maximum of two arrays, propagates NaNs. fmin : Element-wise minimum of two arrays, ignores NaNs. amin : The minimum value of an array along a given axis, propagates NaNs. nanmin : The minimum value of an array along a given axis, ignores NaNs. fmax, amax, nanmax Notes ----- The minimum is equivalent to ``np.where(x1 <= x2, x1, x2)`` when neither x1 nor x2 are NaNs, but it is faster and does proper broadcasting. Examples -------- >>> np.minimum([2, 3, 4], [1, 5, 2]) array([1, 3, 2]) >>> np.minimum(np.eye(2), [0.5, 2]) # broadcasting array([[ 0.5, 0. ], [ 0. , 1. ]]) >>> np.minimum([np.nan, 0, np.nan],[0, np.nan, np.nan]) array([nan, nan, nan]) >>> np.minimum(-np.Inf, 1) -inf" :arglists '[[self & [args {:as kwargs}]]]} minimum (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "minimum")))) (def ^{:doc " One-dimensional linear interpolation. Returns the one-dimensional piecewise linear interpolant to a function with given discrete data points (`xp`, `fp`), evaluated at `x`. Parameters ---------- x : array_like The x-coordinates at which to evaluate the interpolated values. xp : 1-D sequence of floats The x-coordinates of the data points, must be increasing if argument `period` is not specified. Otherwise, `xp` is internally sorted after normalizing the periodic boundaries with ``xp = xp % period``. fp : 1-D sequence of float or complex The y-coordinates of the data points, same length as `xp`. left : optional float or complex corresponding to fp Value to return for `x < xp[0]`, default is `fp[0]`. right : optional float or complex corresponding to fp Value to return for `x > xp[-1]`, default is `fp[-1]`. period : None or float, optional A period for the x-coordinates. This parameter allows the proper interpolation of angular x-coordinates. Parameters `left` and `right` are ignored if `period` is specified. .. versionadded:: 1.10.0 Returns ------- y : float or complex (corresponding to fp) or ndarray The interpolated values, same shape as `x`. Raises ------ ValueError If `xp` and `fp` have different length If `xp` or `fp` are not 1-D sequences If `period == 0` See Also -------- scipy.interpolate Notes ----- The x-coordinate sequence is expected to be increasing, but this is not explicitly enforced. However, if the sequence `xp` is non-increasing, interpolation results are meaningless. Note that, since NaN is unsortable, `xp` also cannot contain NaNs. A simple check for `xp` being strictly increasing is:: np.all(np.diff(xp) > 0) Examples -------- >>> xp = [1, 2, 3] >>> fp = [3, 2, 0] >>> np.interp(2.5, xp, fp) 1.0 >>> np.interp([0, 1, 1.5, 2.72, 3.14], xp, fp) array([3. , 3. , 2.5 , 0.56, 0. ]) >>> UNDEF = -99.0 >>> np.interp(3.14, xp, fp, right=UNDEF) -99.0 Plot an interpolant to the sine function: >>> x = np.linspace(0, 2*np.pi, 10) >>> y = np.sin(x) >>> xvals = np.linspace(0, 2*np.pi, 50) >>> yinterp = np.interp(xvals, x, y) >>> import matplotlib.pyplot as plt >>> plt.plot(x, y, 'o') [] >>> plt.plot(xvals, yinterp, '-x') [] >>> plt.show() Interpolation with periodic x-coordinates: >>> x = [-180, -170, -185, 185, -10, -5, 0, 365] >>> xp = [190, -190, 350, -350] >>> fp = [5, 10, 3, 4] >>> np.interp(x, xp, fp, period=360) array([7.5 , 5. , 8.75, 6.25, 3. , 3.25, 3.5 , 3.75]) Complex interpolation: >>> x = [1.5, 4.0] >>> xp = [2,3,5] >>> fp = [1.0j, 0, 2+3j] >>> np.interp(x, xp, fp) array([0.+1.j , 1.+1.5j]) " :arglists '[[& [args {:as kwargs}]]]} interp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "interp")))) (def ^{:doc " Load data from a text file, with missing values handled as specified. Each line past the first `skip_header` lines is split at the `delimiter` character, and characters following the `comments` character are discarded. Parameters ---------- fname : file, str, pathlib.Path, list of str, generator File, filename, list, or generator to read. If the filename extension is `.gz` or `.bz2`, the file is first decompressed. Note that generators must return byte strings. The strings in a list or produced by a generator are treated as lines. dtype : dtype, optional Data type of the resulting array. If None, the dtypes will be determined by the contents of each column, individually. comments : str, optional The character used to indicate the start of a comment. All the characters occurring on a line after a comment are discarded delimiter : str, int, or sequence, optional The string used to separate values. By default, any consecutive whitespaces act as delimiter. An integer or sequence of integers can also be provided as width(s) of each field. skiprows : int, optional `skiprows` was removed in numpy 1.10. Please use `skip_header` instead. skip_header : int, optional The number of lines to skip at the beginning of the file. skip_footer : int, optional The number of lines to skip at the end of the file. converters : variable, optional The set of functions that convert the data of a column to a value. The converters can also be used to provide a default value for missing data: ``converters = {3: lambda s: float(s or 0)}``. missing : variable, optional `missing` was removed in numpy 1.10. Please use `missing_values` instead. missing_values : variable, optional The set of strings corresponding to missing data. filling_values : variable, optional The set of values to be used as default when the data are missing. usecols : sequence, optional Which columns to read, with 0 being the first. For example, ``usecols = (1, 4, 5)`` will extract the 2nd, 5th and 6th columns. names : {None, True, str, sequence}, optional If `names` is True, the field names are read from the first line after the first `skip_header` lines. This line can optionally be proceeded by a comment delimiter. If `names` is a sequence or a single-string of comma-separated names, the names will be used to define the field names in a structured dtype. If `names` is None, the names of the dtype fields will be used, if any. excludelist : sequence, optional A list of names to exclude. This list is appended to the default list ['return','file','print']. Excluded names are appended an underscore: for example, `file` would become `file_`. deletechars : str, optional A string combining invalid characters that must be deleted from the names. defaultfmt : str, optional A format used to define default field names, such as \"f%i\" or \"f_%02i\". autostrip : bool, optional Whether to automatically strip white spaces from the variables. replace_space : char, optional Character(s) used in replacement of white spaces in the variables names. By default, use a '_'. case_sensitive : {True, False, 'upper', 'lower'}, optional If True, field names are case sensitive. If False or 'upper', field names are converted to upper case. If 'lower', field names are converted to lower case. unpack : bool, optional If True, the returned array is transposed, so that arguments may be unpacked using ``x, y, z = genfromtxt(...)``. When used with a structured data-type, arrays are returned for each field. Default is False. usemask : bool, optional If True, return a masked array. If False, return a regular array. loose : bool, optional If True, do not raise errors for invalid values. invalid_raise : bool, optional If True, an exception is raised if an inconsistency is detected in the number of columns. If False, a warning is emitted and the offending lines are skipped. max_rows : int, optional The maximum number of rows to read. Must not be used with skip_footer at the same time. If given, the value must be at least 1. Default is to read the entire file. .. versionadded:: 1.10.0 encoding : str, optional Encoding used to decode the inputfile. Does not apply when `fname` is a file object. The special value 'bytes' enables backward compatibility workarounds that ensure that you receive byte arrays when possible and passes latin1 encoded strings to converters. Override this value to receive unicode arrays and pass strings as input to converters. If set to None the system default is used. The default value is 'bytes'. .. versionadded:: 1.14.0 like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray Data read from the text file. If `usemask` is True, this is a masked array. See Also -------- numpy.loadtxt : equivalent function when no data is missing. Notes ----- * When spaces are used as delimiters, or when no delimiter has been given as input, there should not be any missing data between two fields. * When the variables are named (either by a flexible dtype or with `names`), there must not be any header in the file (else a ValueError exception is raised). * Individual values are not stripped of spaces by default. When using a custom converter, make sure the function does remove spaces. References ---------- .. [1] NumPy User Guide, section `I/O with NumPy `_. Examples -------- >>> from io import StringIO >>> import numpy as np Comma delimited file with mixed dtype >>> s = StringIO(u\"1,1.3,abcde\") >>> data = np.genfromtxt(s, dtype=[('myint','i8'),('myfloat','f8'), ... ('mystring','S5')], delimiter=\",\") >>> data array((1, 1.3, b'abcde'), dtype=[('myint', '>> _ = s.seek(0) # needed for StringIO example only >>> data = np.genfromtxt(s, dtype=None, ... names = ['myint','myfloat','mystring'], delimiter=\",\") >>> data array((1, 1.3, b'abcde'), dtype=[('myint', '>> _ = s.seek(0) >>> data = np.genfromtxt(s, dtype=\"i8,f8,S5\", ... names=['myint','myfloat','mystring'], delimiter=\",\") >>> data array((1, 1.3, b'abcde'), dtype=[('myint', '>> s = StringIO(u\"11.3abcde\") >>> data = np.genfromtxt(s, dtype=None, names=['intvar','fltvar','strvar'], ... delimiter=[1,3,5]) >>> data array((1, 1.3, b'abcde'), dtype=[('intvar', '>> f = StringIO(''' ... text,# of chars ... hello world,11 ... numpy,5''') >>> np.genfromtxt(f, dtype='S12,S12', delimiter=',') array([(b'text', b''), (b'hello world', b'11'), (b'numpy', b'5')], dtype=[('f0', 'S12'), ('f1', 'S12')]) " :arglists '[[fname & [{names :names, max_rows :max_rows, encoding :encoding, case_sensitive :case_sensitive, usemask :usemask, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, unpack :unpack, converters :converters, filling_values :filling_values, deletechars :deletechars, defaultfmt :defaultfmt, excludelist :excludelist, delimiter :delimiter, loose :loose, invalid_raise :invalid_raise, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, max_rows :max_rows, case_sensitive :case_sensitive, usemask :usemask, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, unpack :unpack, converters :converters, filling_values :filling_values, deletechars :deletechars, defaultfmt :defaultfmt, excludelist :excludelist, delimiter :delimiter, loose :loose, invalid_raise :invalid_raise, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, case_sensitive :case_sensitive, usemask :usemask, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, unpack :unpack, converters :converters, filling_values :filling_values, deletechars :deletechars, defaultfmt :defaultfmt, excludelist :excludelist, delimiter :delimiter, loose :loose, invalid_raise :invalid_raise, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, case_sensitive :case_sensitive, usemask :usemask, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, unpack :unpack, converters :converters, filling_values :filling_values, deletechars :deletechars, defaultfmt :defaultfmt, excludelist :excludelist, delimiter :delimiter, loose :loose, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, case_sensitive :case_sensitive, usemask :usemask, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, unpack :unpack, converters :converters, filling_values :filling_values, deletechars :deletechars, defaultfmt :defaultfmt, excludelist :excludelist, delimiter :delimiter, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, case_sensitive :case_sensitive, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, unpack :unpack, converters :converters, filling_values :filling_values, deletechars :deletechars, defaultfmt :defaultfmt, excludelist :excludelist, delimiter :delimiter, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, case_sensitive :case_sensitive, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, deletechars :deletechars, defaultfmt :defaultfmt, excludelist :excludelist, delimiter :delimiter, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, case_sensitive :case_sensitive, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, deletechars :deletechars, excludelist :excludelist, delimiter :delimiter, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, like :like, dtype :dtype, skip_header :skip_header, autostrip :autostrip, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, deletechars :deletechars, excludelist :excludelist, delimiter :delimiter, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, like :like, dtype :dtype, skip_header :skip_header, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, deletechars :deletechars, excludelist :excludelist, delimiter :delimiter, replace_space :replace_space, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, like :like, dtype :dtype, skip_header :skip_header, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, deletechars :deletechars, excludelist :excludelist, delimiter :delimiter, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, like :like, dtype :dtype, skip_header :skip_header, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, excludelist :excludelist, delimiter :delimiter, missing_values :missing_values, usecols :usecols}]] [fname & [{names :names, like :like, dtype :dtype, skip_header :skip_header, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, delimiter :delimiter, missing_values :missing_values, usecols :usecols}]] [fname & [{like :like, dtype :dtype, skip_header :skip_header, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, delimiter :delimiter, missing_values :missing_values, usecols :usecols}]] [fname & [{like :like, dtype :dtype, skip_header :skip_header, skip_footer :skip_footer, comments :comments, converters :converters, filling_values :filling_values, delimiter :delimiter, missing_values :missing_values}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, skip_header :skip_header, skip_footer :skip_footer, converters :converters, missing_values :missing_values, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, skip_header :skip_header, skip_footer :skip_footer, converters :converters, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, skip_header :skip_header, skip_footer :skip_footer, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, skip_header :skip_header, like :like}]] [fname & [{dtype :dtype, comments :comments, delimiter :delimiter, like :like}]] [fname & [{dtype :dtype, comments :comments, like :like}]] [fname & [{dtype :dtype, like :like}]] [fname & [{like :like}]]]} genfromtxt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "genfromtxt")))) (def ^{:doc " errstate(**kwargs) Context manager for floating-point error handling. Using an instance of `errstate` as a context manager allows statements in that context to execute with a known error handling behavior. Upon entering the context the error handling is set with `seterr` and `seterrcall`, and upon exiting it is reset to what it was before. .. versionchanged:: 1.17.0 `errstate` is also usable as a function decorator, saving a level of indentation if an entire function is wrapped. See :py:class:`contextlib.ContextDecorator` for more information. Parameters ---------- kwargs : {divide, over, under, invalid} Keyword arguments. The valid keywords are the possible floating-point exceptions. Each keyword should have a string value that defines the treatment for the particular error. Possible values are {'ignore', 'warn', 'raise', 'call', 'print', 'log'}. See Also -------- seterr, geterr, seterrcall, geterrcall Notes ----- For complete documentation of the types of floating-point exceptions and treatment options, see `seterr`. Examples -------- >>> from collections import OrderedDict >>> olderr = np.seterr(all='ignore') # Set error handling to known state. >>> np.arange(3) / 0. array([nan, inf, inf]) >>> with np.errstate(divide='warn'): ... np.arange(3) / 0. array([nan, inf, inf]) >>> np.sqrt(-1) nan >>> with np.errstate(invalid='raise'): ... np.sqrt(-1) Traceback (most recent call last): File \"\", line 2, in FloatingPointError: invalid value encountered in sqrt Outside the context the error handling behavior has not changed: >>> OrderedDict(sorted(np.geterr().items())) OrderedDict([('divide', 'ignore'), ('invalid', 'ignore'), ('over', 'ignore'), ('under', 'ignore')]) " :arglists '[[self & [{call :call, :as kwargs}]]]} errstate (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "errstate")))) (def ^{:doc "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" :arglists '[[self & [args {:as kwargs}]]]} set_numeric_ops (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "set_numeric_ops")))) (def ^{:doc "degrees(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Convert angles from radians to degrees. Parameters ---------- x : array_like Input array in radians. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray of floats The corresponding degree values; if `out` was supplied this is a reference to it. This is a scalar if `x` is a scalar. See Also -------- rad2deg : equivalent function Examples -------- Convert a radian array to degrees >>> rad = np.arange(12.)*np.pi/6 >>> np.degrees(rad) array([ 0., 30., 60., 90., 120., 150., 180., 210., 240., 270., 300., 330.]) >>> out = np.zeros((rad.shape)) >>> r = np.degrees(rad, out) >>> np.all(r == out) True" :arglists '[[self & [args {:as kwargs}]]]} degrees (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "degrees")))) (def ^{:doc ""} True_ true) (def ^{:doc " Calculate the n-th discrete difference along the given axis. The first difference is given by ``out[i] = a[i+1] - a[i]`` along the given axis, higher differences are calculated by using `diff` recursively. Parameters ---------- a : array_like Input array n : int, optional The number of times values are differenced. If zero, the input is returned as-is. axis : int, optional The axis along which the difference is taken, default is the last axis. prepend, append : array_like, optional Values to prepend or append to `a` along axis prior to performing the difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match `a` except along axis. .. versionadded:: 1.16.0 Returns ------- diff : ndarray The n-th differences. The shape of the output is the same as `a` except along `axis` where the dimension is smaller by `n`. The type of the output is the same as the type of the difference between any two elements of `a`. This is the same as the type of `a` in most cases. A notable exception is `datetime64`, which results in a `timedelta64` output array. See Also -------- gradient, ediff1d, cumsum Notes ----- Type is preserved for boolean arrays, so the result will contain `False` when consecutive elements are the same and `True` when they differ. For unsigned integer arrays, the results will also be unsigned. This should not be surprising, as the result is consistent with calculating the difference directly: >>> u8_arr = np.array([1, 0], dtype=np.uint8) >>> np.diff(u8_arr) array([255], dtype=uint8) >>> u8_arr[1,...] - u8_arr[0,...] 255 If this is not desirable, then the array should be cast to a larger integer type first: >>> i16_arr = u8_arr.astype(np.int16) >>> np.diff(i16_arr) array([-1], dtype=int16) Examples -------- >>> x = np.array([1, 2, 4, 7, 0]) >>> np.diff(x) array([ 1, 2, 3, -7]) >>> np.diff(x, n=2) array([ 1, 1, -10]) >>> x = np.array([[1, 3, 6, 10], [0, 5, 6, 8]]) >>> np.diff(x) array([[2, 3, 4], [5, 1, 2]]) >>> np.diff(x, axis=0) array([[-1, 2, 0, -2]]) >>> x = np.arange('1066-10-13', '1066-10-16', dtype=np.datetime64) >>> np.diff(x) array([1, 1], dtype='timedelta64[D]') " :arglists '[[& [args {:as kwargs}]]]} diff (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "diff")))) (def ^{:doc " Calculates `element in test_elements`, broadcasting over `element` only. Returns a boolean array of the same shape as `element` that is True where an element of `element` is in `test_elements` and False otherwise. Parameters ---------- element : array_like Input array. test_elements : array_like The values against which to test each value of `element`. This argument is flattened if it is an array or array_like. See notes for behavior with non-array-like parameters. assume_unique : bool, optional If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. invert : bool, optional If True, the values in the returned array are inverted, as if calculating `element not in test_elements`. Default is False. ``np.isin(a, b, invert=True)`` is equivalent to (but faster than) ``np.invert(np.isin(a, b))``. Returns ------- isin : ndarray, bool Has the same shape as `element`. The values `element[isin]` are in `test_elements`. See Also -------- in1d : Flattened version of this function. numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Notes ----- `isin` is an element-wise function version of the python keyword `in`. ``isin(a, b)`` is roughly equivalent to ``np.array([item in b for item in a])`` if `a` and `b` are 1-D sequences. `element` and `test_elements` are converted to arrays if they are not already. If `test_elements` is a set (or other non-sequence collection) it will be converted to an object array with one element, rather than an array of the values contained in `test_elements`. This is a consequence of the `array` constructor's way of handling non-sequence collections. Converting the set to a list usually gives the desired behavior. .. versionadded:: 1.13.0 Examples -------- >>> element = 2*np.arange(4).reshape((2, 2)) >>> element array([[0, 2], [4, 6]]) >>> test_elements = [1, 2, 4, 8] >>> mask = np.isin(element, test_elements) >>> mask array([[False, True], [ True, False]]) >>> element[mask] array([2, 4]) The indices of the matched values can be obtained with `nonzero`: >>> np.nonzero(mask) (array([0, 1]), array([1, 0])) The test can also be inverted: >>> mask = np.isin(element, test_elements, invert=True) >>> mask array([[ True, False], [False, True]]) >>> element[mask] array([0, 6]) Because of how `array` handles sets, the following does not work as expected: >>> test_set = {1, 2, 4, 8} >>> np.isin(element, test_set) array([[False, False], [False, False]]) Casting the set to a list gives the expected result: >>> np.isin(element, list(test_set)) array([[False, True], [ True, False]]) " :arglists '[[& [args {:as kwargs}]]]} isin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isin")))) (def ^{:doc " Returns the indices of the minimum values along an axis. Parameters ---------- a : array_like Input array. axis : int, optional By default, the index is into the flattened array, otherwise along the specified axis. out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. Returns ------- index_array : ndarray of ints Array of indices into the array. It has the same shape as `a.shape` with the dimension along `axis` removed. See Also -------- ndarray.argmin, argmax amin : The minimum value along a given axis. unravel_index : Convert a flat index into an index tuple. take_along_axis : Apply ``np.expand_dims(index_array, axis)`` from argmin to an array as if by calling min. Notes ----- In case of multiple occurrences of the minimum values, the indices corresponding to the first occurrence are returned. Examples -------- >>> a = np.arange(6).reshape(2,3) + 10 >>> a array([[10, 11, 12], [13, 14, 15]]) >>> np.argmin(a) 0 >>> np.argmin(a, axis=0) array([0, 0, 0]) >>> np.argmin(a, axis=1) array([0, 0]) Indices of the minimum elements of a N-dimensional array: >>> ind = np.unravel_index(np.argmin(a, axis=None), a.shape) >>> ind (0, 0) >>> a[ind] 10 >>> b = np.arange(6) + 10 >>> b[4] = 10 >>> b array([10, 11, 12, 13, 10, 15]) >>> np.argmin(b) # Only the first occurrence is returned. 0 >>> x = np.array([[4,2,3], [1,0,3]]) >>> index_array = np.argmin(x, axis=-1) >>> # Same as np.min(x, axis=-1, keepdims=True) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1) array([[2], [0]]) >>> # Same as np.max(x, axis=-1) >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1) array([2, 0]) " :arglists '[[& [args {:as kwargs}]]]} argmin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "argmin")))) (def ^{:doc " chararray(shape, itemsize=1, unicode=False, buffer=None, offset=0, strides=None, order=None) Provides a convenient view on arrays of string and unicode values. .. note:: The `chararray` class exists for backwards compatibility with Numarray, it is not recommended for new development. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of `dtype` `object_`, `string_` or `unicode_`, and use the free functions in the `numpy.char` module for fast vectorized string operations. Versus a regular NumPy array of type `str` or `unicode`, this class adds the following functionality: 1) values automatically have whitespace removed from the end when indexed 2) comparison operators automatically remove whitespace from the end when comparing values 3) vectorized string operations are provided as methods (e.g. `.endswith`) and infix operators (e.g. ``\"+\", \"*\", \"%\"``) chararrays should be created using `numpy.char.array` or `numpy.char.asarray`, rather than this constructor directly. This constructor creates the array, using `buffer` (with `offset` and `strides`) if it is not ``None``. If `buffer` is ``None``, then constructs a new array with `strides` in \"C order\", unless both ``len(shape) >= 2`` and ``order='F'``, in which case `strides` is in \"Fortran order\". Methods ------- astype argsort copy count decode dump dumps encode endswith expandtabs fill find flatten getfield index isalnum isalpha isdecimal isdigit islower isnumeric isspace istitle isupper item join ljust lower lstrip nonzero put ravel repeat replace reshape resize rfind rindex rjust rsplit rstrip searchsorted setfield setflags sort split splitlines squeeze startswith strip swapaxes swapcase take title tofile tolist tostring translate transpose upper view zfill Parameters ---------- shape : tuple Shape of the array. itemsize : int, optional Length of each array element, in number of characters. Default is 1. unicode : bool, optional Are the array elements of type unicode (True) or string (False). Default is False. buffer : object exposing the buffer interface or str, optional Memory address of the start of the array data. Default is None, in which case a new array is created. offset : int, optional Fixed stride displacement from the beginning of an axis? Default is 0. Needs to be >=0. strides : array_like of ints, optional Strides for the array (see `ndarray.strides` for full description). Default is None. order : {'C', 'F'}, optional The order in which the array data is stored in memory: 'C' -> \"row major\" order (the default), 'F' -> \"column major\" (Fortran) order. Examples -------- >>> charar = np.chararray((3, 3)) >>> charar[:] = 'a' >>> charar chararray([[b'a', b'a', b'a'], [b'a', b'a', b'a'], [b'a', b'a', b'a']], dtype='|S1') >>> charar = np.chararray(charar.shape, itemsize=5) >>> charar[:] = 'abc' >>> charar chararray([[b'abc', b'abc', b'abc'], [b'abc', b'abc', b'abc'], [b'abc', b'abc', b'abc']], dtype='|S5') " :arglists '[[self & [args {:as kwargs}]]]} chararray (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "chararray")))) (def ^{:doc " shares_memory(a, b, max_work=None) Determine if two arrays share memory. .. warning:: This function can be exponentially slow for some inputs, unless `max_work` is set to a finite number or ``MAY_SHARE_BOUNDS``. If in doubt, use `numpy.may_share_memory` instead. Parameters ---------- a, b : ndarray Input arrays max_work : int, optional Effort to spend on solving the overlap problem (maximum number of candidate solutions to consider). The following special values are recognized: max_work=MAY_SHARE_EXACT (default) The problem is solved exactly. In this case, the function returns True only if there is an element shared between the arrays. Finding the exact solution may take extremely long in some cases. max_work=MAY_SHARE_BOUNDS Only the memory bounds of a and b are checked. Raises ------ numpy.TooHardError Exceeded max_work. Returns ------- out : bool See Also -------- may_share_memory Examples -------- >>> x = np.array([1, 2, 3, 4]) >>> np.shares_memory(x, np.array([5, 6, 7])) False >>> np.shares_memory(x[::2], x) True >>> np.shares_memory(x[::2], x[1::2]) False Checking whether two arrays share memory is NP-complete, and runtime may increase exponentially in the number of dimensions. Hence, `max_work` should generally be set to a finite number, as it is possible to construct examples that take extremely long to run: >>> from numpy.lib.stride_tricks import as_strided >>> x = np.zeros([192163377], dtype=np.int8) >>> x1 = as_strided(x, strides=(36674, 61119, 85569), shape=(1049, 1049, 1049)) >>> x2 = as_strided(x[64023025:], strides=(12223, 12224, 1), shape=(1049, 1049, 1)) >>> np.shares_memory(x1, x2, max_work=1000) Traceback (most recent call last): ... numpy.TooHardError: Exceeded max_work Running ``np.shares_memory(x1, x2)`` without `max_work` set takes around 1 minute for this case. It is possible to find problems that take still significantly longer. " :arglists '[[& [args {:as kwargs}]]]} shares_memory (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "shares_memory")))) (def ^{:doc " Reverse the order of elements in an array along the given axis. The shape of the array is preserved, but the elements are reordered. .. versionadded:: 1.12.0 Parameters ---------- m : array_like Input array. axis : None or int or tuple of ints, optional Axis or axes along which to flip over. The default, axis=None, will flip over all of the axes of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, flipping is performed on all of the axes specified in the tuple. .. versionchanged:: 1.15.0 None and tuples of axes are supported Returns ------- out : array_like A view of `m` with the entries of axis reversed. Since a view is returned, this operation is done in constant time. See Also -------- flipud : Flip an array vertically (axis=0). fliplr : Flip an array horizontally (axis=1). Notes ----- flip(m, 0) is equivalent to flipud(m). flip(m, 1) is equivalent to fliplr(m). flip(m, n) corresponds to ``m[...,::-1,...]`` with ``::-1`` at position n. flip(m) corresponds to ``m[::-1,::-1,...,::-1]`` with ``::-1`` at all positions. flip(m, (0, 1)) corresponds to ``m[::-1,::-1,...]`` with ``::-1`` at position 0 and position 1. Examples -------- >>> A = np.arange(8).reshape((2,2,2)) >>> A array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]]) >>> np.flip(A, 0) array([[[4, 5], [6, 7]], [[0, 1], [2, 3]]]) >>> np.flip(A, 1) array([[[2, 3], [0, 1]], [[6, 7], [4, 5]]]) >>> np.flip(A) array([[[7, 6], [5, 4]], [[3, 2], [1, 0]]]) >>> np.flip(A, (0, 2)) array([[[5, 4], [7, 6]], [[1, 0], [3, 2]]]) >>> A = np.random.randn(3,4,5) >>> np.all(np.flip(A,2) == A[:,:,::-1,...]) True " :arglists '[[& [args {:as kwargs}]]]} flip (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "flip")))) (def ^{:doc " Assemble an nd-array from nested lists of blocks. Blocks in the innermost lists are concatenated (see `concatenate`) along the last dimension (-1), then these are concatenated along the second-last dimension (-2), and so on until the outermost list is reached. Blocks can be of any dimension, but will not be broadcasted using the normal rules. Instead, leading axes of size 1 are inserted, to make ``block.ndim`` the same for all blocks. This is primarily useful for working with scalars, and means that code like ``np.block([v, 1])`` is valid, where ``v.ndim == 1``. When the nested list is two levels deep, this allows block matrices to be constructed from their components. .. versionadded:: 1.13.0 Parameters ---------- arrays : nested list of array_like or scalars (but not tuples) If passed a single ndarray or scalar (a nested list of depth 0), this is returned unmodified (and not copied). Elements shapes must match along the appropriate axes (without broadcasting), but leading 1s will be prepended to the shape as necessary to make the dimensions match. Returns ------- block_array : ndarray The array assembled from the given blocks. The dimensionality of the output is equal to the greatest of: * the dimensionality of all the inputs * the depth to which the input list is nested Raises ------ ValueError * If list depths are mismatched - for instance, ``[[a, b], c]`` is illegal, and should be spelt ``[[a, b], [c]]`` * If lists are empty - for instance, ``[[a, b], []]`` See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. vstack : Stack arrays in sequence vertically (row wise). hstack : Stack arrays in sequence horizontally (column wise). dstack : Stack arrays in sequence depth wise (along third axis). column_stack : Stack 1-D arrays as columns into a 2-D array. vsplit : Split an array into multiple sub-arrays vertically (row-wise). Notes ----- When called with only scalars, ``np.block`` is equivalent to an ndarray call. So ``np.block([[1, 2], [3, 4]])`` is equivalent to ``np.array([[1, 2], [3, 4]])``. This function does not enforce that the blocks lie on a fixed grid. ``np.block([[a, b], [c, d]])`` is not restricted to arrays of the form:: AAAbb AAAbb cccDD But is also allowed to produce, for some ``a, b, c, d``:: AAAbb AAAbb cDDDD Since concatenation happens along the last axis first, `block` is _not_ capable of producing the following directly:: AAAbb cccbb cccDD Matlab's \"square bracket stacking\", ``[A, B, ...; p, q, ...]``, is equivalent to ``np.block([[A, B, ...], [p, q, ...]])``. Examples -------- The most common use of this function is to build a block matrix >>> A = np.eye(2) * 2 >>> B = np.eye(3) * 3 >>> np.block([ ... [A, np.zeros((2, 3))], ... [np.ones((3, 2)), B ] ... ]) array([[2., 0., 0., 0., 0.], [0., 2., 0., 0., 0.], [1., 1., 3., 0., 0.], [1., 1., 0., 3., 0.], [1., 1., 0., 0., 3.]]) With a list of depth 1, `block` can be used as `hstack` >>> np.block([1, 2, 3]) # hstack([1, 2, 3]) array([1, 2, 3]) >>> a = np.array([1, 2, 3]) >>> b = np.array([2, 3, 4]) >>> np.block([a, b, 10]) # hstack([a, b, 10]) array([ 1, 2, 3, 2, 3, 4, 10]) >>> A = np.ones((2, 2), int) >>> B = 2 * A >>> np.block([A, B]) # hstack([A, B]) array([[1, 1, 2, 2], [1, 1, 2, 2]]) With a list of depth 2, `block` can be used in place of `vstack`: >>> a = np.array([1, 2, 3]) >>> b = np.array([2, 3, 4]) >>> np.block([[a], [b]]) # vstack([a, b]) array([[1, 2, 3], [2, 3, 4]]) >>> A = np.ones((2, 2), int) >>> B = 2 * A >>> np.block([[A], [B]]) # vstack([A, B]) array([[1, 1], [1, 1], [2, 2], [2, 2]]) It can also be used in places of `atleast_1d` and `atleast_2d` >>> a = np.array(0) >>> b = np.array([1]) >>> np.block([a]) # atleast_1d(a) array([0]) >>> np.block([b]) # atleast_1d(b) array([1]) >>> np.block([[a]]) # atleast_2d(a) array([[0]]) >>> np.block([[b]]) # atleast_2d(b) array([[1]]) " :arglists '[[& [args {:as kwargs}]]]} block (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "block")))) (def ^{:doc " putmask(a, mask, values) Changes elements of an array based on conditional and input values. Sets ``a.flat[n] = values[n]`` for each n where ``mask.flat[n]==True``. If `values` is not the same size as `a` and `mask` then it will repeat. This gives behavior different from ``a[mask] = values``. Parameters ---------- a : ndarray Target array. mask : array_like Boolean mask array. It has to be the same shape as `a`. values : array_like Values to put into `a` where `mask` is True. If `values` is smaller than `a` it will be repeated. See Also -------- place, put, take, copyto Examples -------- >>> x = np.arange(6).reshape(2, 3) >>> np.putmask(x, x>2, x**2) >>> x array([[ 0, 1, 2], [ 9, 16, 25]]) If `values` is smaller than `a` it is repeated: >>> x = np.arange(5) >>> np.putmask(x, x>1, [-33, -44]) >>> x array([ 0, 1, -33, -44, -33]) " :arglists '[[& [args {:as kwargs}]]]} putmask (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "putmask")))) (def ^{:doc "arctanh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Inverse hyperbolic tangent element-wise. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Array of the same shape as `x`. This is a scalar if `x` is a scalar. See Also -------- emath.arctanh Notes ----- `arctanh` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `tanh(z) = x`. The convention is to return the `z` whose imaginary part lies in `[-pi/2, pi/2]`. For real-valued input data types, `arctanh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `arctanh` is a complex analytical function that has branch cuts `[-1, -inf]` and `[1, inf]` and is continuous from above on the former and from below on the latter. The inverse hyperbolic tangent is also known as `atanh` or ``tanh^-1``. References ---------- .. [1] M. Abramowitz and I.A. Stegun, \"Handbook of Mathematical Functions\", 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, \"Inverse hyperbolic function\", https://en.wikipedia.org/wiki/Arctanh Examples -------- >>> np.arctanh([0, -0.5]) array([ 0. , -0.54930614])" :arglists '[[self & [args {:as kwargs}]]]} arctanh (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arctanh")))) (def ^{:doc " Take elements from an array along an axis. When axis is not None, this function does the same thing as \"fancy\" indexing (indexing arrays using arrays); however, it can be easier to use if you need elements along a given axis. A call such as ``np.take(arr, indices, axis=3)`` is equivalent to ``arr[:,:,:,indices,...]``. Explained without fancy indexing, this is equivalent to the following use of `ndindex`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of indices:: Ni, Nk = a.shape[:axis], a.shape[axis+1:] Nj = indices.shape for ii in ndindex(Ni): for jj in ndindex(Nj): for kk in ndindex(Nk): out[ii + jj + kk] = a[ii + (indices[jj],) + kk] Parameters ---------- a : array_like (Ni..., M, Nk...) The source array. indices : array_like (Nj...) The indices of the values to extract. .. versionadded:: 1.8.0 Also allow scalars for indices. axis : int, optional The axis over which to select values. By default, the flattened input array is used. out : ndarray, optional (Ni..., Nj..., Nk...) If provided, the result will be placed in this array. It should be of the appropriate shape and dtype. Note that `out` is always buffered if `mode='raise'`; use other modes for better performance. mode : {'raise', 'wrap', 'clip'}, optional Specifies how out-of-bounds indices will behave. * 'raise' -- raise an error (default) * 'wrap' -- wrap around * 'clip' -- clip to the range 'clip' mode means that all indices that are too large are replaced by the index that addresses the last element along that axis. Note that this disables indexing with negative numbers. Returns ------- out : ndarray (Ni..., Nj..., Nk...) The returned array has the same type as `a`. See Also -------- compress : Take elements using a boolean mask ndarray.take : equivalent method take_along_axis : Take elements by matching the array and the index arrays Notes ----- By eliminating the inner loop in the description above, and using `s_` to build simple slice objects, `take` can be expressed in terms of applying fancy indexing to each 1-d slice:: Ni, Nk = a.shape[:axis], a.shape[axis+1:] for ii in ndindex(Ni): for kk in ndindex(Nj): out[ii + s_[...,] + kk] = a[ii + s_[:,] + kk][indices] For this reason, it is equivalent to (but faster than) the following use of `apply_along_axis`:: out = np.apply_along_axis(lambda a_1d: a_1d[indices], axis, a) Examples -------- >>> a = [4, 3, 5, 7, 6, 8] >>> indices = [0, 1, 4] >>> np.take(a, indices) array([4, 3, 6]) In this example if `a` is an ndarray, \"fancy\" indexing can be used. >>> a = np.array(a) >>> a[indices] array([4, 3, 6]) If `indices` is not one dimensional, the output also has these dimensions. >>> np.take(a, [[0, 1], [2, 3]]) array([[4, 3], [5, 7]]) " :arglists '[[& [args {:as kwargs}]]]} take (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "take")))) (def ^{:doc "conjugate(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the complex conjugate, element-wise. The complex conjugate of a complex number is obtained by changing the sign of its imaginary part. Parameters ---------- x : array_like Input value. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The complex conjugate of `x`, with same dtype as `y`. This is a scalar if `x` is a scalar. Notes ----- `conj` is an alias for `conjugate`: >>> np.conj is np.conjugate True Examples -------- >>> np.conjugate(1+2j) (1-2j) >>> x = np.eye(2) + 1j * np.eye(2) >>> np.conjugate(x) array([[ 1.-1.j, 0.-0.j], [ 0.-0.j, 1.-1.j]])" :arglists '[[self & [args {:as kwargs}]]]} conjugate (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "conjugate")))) (def ^{:doc "" :arglists '[[attr]]} __getattr__ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "__getattr__")))) (def ^{:doc " Set the floating-point error callback function or log object. There are two ways to capture floating-point error messages. The first is to set the error-handler to 'call', using `seterr`. Then, set the function to call using this function. The second is to set the error-handler to 'log', using `seterr`. Floating-point errors then trigger a call to the 'write' method of the provided object. Parameters ---------- func : callable f(err, flag) or object with write method Function to call upon floating-point errors ('call'-mode) or object whose 'write' method is used to log such message ('log'-mode). The call function takes two arguments. The first is a string describing the type of error (such as \"divide by zero\", \"overflow\", \"underflow\", or \"invalid value\"), and the second is the status flag. The flag is a byte, whose four least-significant bits indicate the type of error, one of \"divide\", \"over\", \"under\", \"invalid\":: [0 0 0 0 divide over under invalid] In other words, ``flags = divide + 2*over + 4*under + 8*invalid``. If an object is provided, its write method should take one argument, a string. Returns ------- h : callable, log instance or None The old error handler. See Also -------- seterr, geterr, geterrcall Examples -------- Callback upon error: >>> def err_handler(type, flag): ... print(\"Floating point error (%s), with flag %s\" % (type, flag)) ... >>> saved_handler = np.seterrcall(err_handler) >>> save_err = np.seterr(all='call') >>> from collections import OrderedDict >>> np.array([1, 2, 3]) / 0.0 Floating point error (divide by zero), with flag 1 array([inf, inf, inf]) >>> np.seterrcall(saved_handler) >>> OrderedDict(sorted(np.seterr(**save_err).items())) OrderedDict([('divide', 'call'), ('invalid', 'call'), ('over', 'call'), ('under', 'call')]) Log error message: >>> class Log: ... def write(self, msg): ... print(\"LOG: %s\" % msg) ... >>> log = Log() >>> saved_handler = np.seterrcall(log) >>> save_err = np.seterr(all='log') >>> np.array([1, 2, 3]) / 0.0 LOG: Warning: divide by zero encountered in true_divide array([inf, inf, inf]) >>> np.seterrcall(saved_handler) >>> OrderedDict(sorted(np.seterr(**save_err).items())) OrderedDict([('divide', 'log'), ('invalid', 'log'), ('over', 'log'), ('under', 'log')]) " :arglists '[[func]]} seterrcall (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "seterrcall")))) (def ^{:doc ""} SHIFT_OVERFLOW 3) (def ^{:doc " Returns a bool array, where True if input element is complex. What is tested is whether the input has a non-zero imaginary part, not if the input type is complex. Parameters ---------- x : array_like Input array. Returns ------- out : ndarray of bools Output array. See Also -------- isreal iscomplexobj : Return True if x is a complex type or an array of complex numbers. Examples -------- >>> np.iscomplex([1+1j, 1+0j, 4.5, 3, 2, 2j]) array([ True, False, False, False, False, True]) " :arglists '[[& [args {:as kwargs}]]]} iscomplex (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "iscomplex")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned short``. :Character code: ``'H'`` :Canonical name: `numpy.ushort` :Alias on this platform: `numpy.uint16`: 16-bit unsigned integer (``0`` to ``65_535``)." :arglists '[[self & [args {:as kwargs}]]]} ushort (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ushort")))) (def ^{:doc "fmod(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the element-wise remainder of division. This is the NumPy implementation of the C library function fmod, the remainder has the same sign as the dividend `x1`. It is equivalent to the Matlab(TM) ``rem`` function and should not be confused with the Python modulus operator ``x1 % x2``. Parameters ---------- x1 : array_like Dividend. x2 : array_like Divisor. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : array_like The remainder of the division of `x1` by `x2`. This is a scalar if both `x1` and `x2` are scalars. See Also -------- remainder : Equivalent to the Python ``%`` operator. divide Notes ----- The result of the modulo operation for negative dividend and divisors is bound by conventions. For `fmod`, the sign of result is the sign of the dividend, while for `remainder` the sign of the result is the sign of the divisor. The `fmod` function is equivalent to the Matlab(TM) ``rem`` function. Examples -------- >>> np.fmod([-3, -2, -1, 1, 2, 3], 2) array([-1, 0, -1, 1, 0, 1]) >>> np.remainder([-3, -2, -1, 1, 2, 3], 2) array([1, 0, 1, 1, 0, 1]) >>> np.fmod([5, 3], [2, 2.]) array([ 1., 1.]) >>> a = np.arange(-3, 3).reshape(3, 2) >>> a array([[-3, -2], [-1, 0], [ 1, 2]]) >>> np.fmod(a, [2,2]) array([[-1, 0], [-1, 0], [ 1, 0]])" :arglists '[[self & [args {:as kwargs}]]]} fmod (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fmod")))) (def ^{:doc " can_cast(from_, to, casting='safe') Returns True if cast between data types can occur according to the casting rule. If from is a scalar or array scalar, also returns True if the scalar value can be cast without overflow or truncation to an integer. Parameters ---------- from_ : dtype, dtype specifier, scalar, or array Data type, scalar, or array to cast from. to : dtype or dtype specifier Data type to cast to. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur. * '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. Returns ------- out : bool True if cast can occur according to the casting rule. 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 maximum integer/float value converted. See also -------- dtype, result_type Examples -------- Basic examples >>> np.can_cast(np.int32, np.int64) True >>> np.can_cast(np.float64, complex) True >>> np.can_cast(complex, float) False >>> np.can_cast('i8', 'f8') True >>> np.can_cast('i8', 'f4') False >>> np.can_cast('i4', 'S4') False Casting scalars >>> np.can_cast(100, 'i1') True >>> np.can_cast(150, 'i1') False >>> np.can_cast(150, 'u1') True >>> np.can_cast(3.5e100, np.float32) False >>> np.can_cast(1000.0, np.float32) True Array scalar checks the value, array does not >>> np.can_cast(np.array(1000.0), np.float32) True >>> np.can_cast(np.array([1000.0]), np.float32) False Using the casting rules >>> np.can_cast('i8', 'i8', 'no') True >>> np.can_cast('i8', 'no') False >>> np.can_cast('i8', 'equiv') True >>> np.can_cast('i8', 'equiv') False >>> np.can_cast('i8', 'safe') True >>> np.can_cast('i4', 'safe') False >>> np.can_cast('i4', 'same_kind') True >>> np.can_cast('u4', 'same_kind') False >>> np.can_cast('u4', 'unsafe') True " :arglists '[[& [args {:as kwargs}]]]} can_cast (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "can_cast")))) (def ^{:doc " Compute the q-th quantile of the data along the specified axis. .. versionadded:: 1.15.0 Parameters ---------- a : array_like Input array or object that can be converted to an array. q : array_like of float Quantile or sequence of quantiles to compute, which must be between 0 and 1 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the quantiles are computed. The default is to compute the quantile(s) along a flattened version of the array. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} This optional parameter specifies the interpolation method to use when the desired quantile lies between two data points ``i < j``: * linear: ``i + (j - i) * fraction``, where ``fraction`` is the fractional part of the index surrounded by ``i`` and ``j``. * lower: ``i``. * higher: ``j``. * nearest: ``i`` or ``j``, whichever is nearest. * midpoint: ``(i + j) / 2``. 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 array `a`. Returns ------- quantile : scalar or ndarray If `q` is a single quantile and `axis=None`, then the result is a scalar. If multiple quantiles are given, first axis of the result corresponds to the quantiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean percentile : equivalent to quantile, but with q in the range [0, 100]. median : equivalent to ``quantile(..., 0.5)`` nanquantile Notes ----- Given a vector ``V`` of length ``N``, the q-th quantile of ``V`` is the value ``q`` of the way from the minimum to the maximum in a sorted copy of ``V``. The values and distances of the two nearest neighbors as well as the `interpolation` parameter will determine the quantile if the normalized ranking does not match the location of ``q`` exactly. This function is the same as the median if ``q=0.5``, the same as the minimum if ``q=0.0`` and the same as the maximum if ``q=1.0``. Examples -------- >>> a = np.array([[10, 7, 4], [3, 2, 1]]) >>> a array([[10, 7, 4], [ 3, 2, 1]]) >>> np.quantile(a, 0.5) 3.5 >>> np.quantile(a, 0.5, axis=0) array([6.5, 4.5, 2.5]) >>> np.quantile(a, 0.5, axis=1) array([7., 2.]) >>> np.quantile(a, 0.5, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.quantile(a, 0.5, axis=0) >>> out = np.zeros_like(m) >>> np.quantile(a, 0.5, axis=0, out=out) array([6.5, 4.5, 2.5]) >>> m array([6.5, 4.5, 2.5]) >>> b = a.copy() >>> np.quantile(b, 0.5, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a == b) " :arglists '[[& [args {:as kwargs}]]]} quantile (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "quantile")))) (def ^{:doc ""} use_hugepage 1) (def ^{:doc " Unwrap by changing deltas between values to 2*pi complement. Unwrap radian phase `p` by changing absolute jumps greater than `discont` to their 2*pi complement along the given axis. Parameters ---------- p : array_like Input array. discont : float, optional Maximum discontinuity between values, default is ``pi``. axis : int, optional Axis along which unwrap will operate, default is the last axis. Returns ------- out : ndarray Output array. See Also -------- rad2deg, deg2rad Notes ----- If the discontinuity in `p` is smaller than ``pi``, but larger than `discont`, no unwrapping is done because taking the 2*pi complement would only make the discontinuity larger. Examples -------- >>> phase = np.linspace(0, np.pi, num=5) >>> phase[3:] += np.pi >>> phase array([ 0. , 0.78539816, 1.57079633, 5.49778714, 6.28318531]) # may vary >>> np.unwrap(phase) array([ 0. , 0.78539816, 1.57079633, -0.78539816, 0. ]) # may vary " :arglists '[[& [args {:as kwargs}]]]} unwrap (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "unwrap")))) (def ^{:doc ""} __file__ "/home/chrisn/miniconda3/lib/python3.9/site-packages/numpy/__init__.py") (def ^{:doc "Signed integer type, compatible with C ``short``. :Character code: ``'h'`` :Canonical name: `numpy.short` :Alias on this platform: `numpy.int16`: 16-bit signed integer (``-32_768`` to ``32_767``)." :arglists '[[self & [args {:as kwargs}]]]} short (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "short")))) (def ^{:doc " datetime_as_string(arr, unit=None, timezone='naive', casting='same_kind') Convert an array of datetimes into an array of strings. Parameters ---------- arr : array_like of datetime64 The array of UTC timestamps to format. unit : str One of None, 'auto', or a :ref:`datetime unit `. timezone : {'naive', 'UTC', 'local'} or tzinfo Timezone information to use when displaying the datetime. If 'UTC', end with a Z to indicate UTC time. If 'local', convert to the local timezone first, and suffix with a +-#### timezone offset. If a tzinfo object, then do as with 'local', but use the specified timezone. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'} Casting to allow when changing between datetime units. Returns ------- str_arr : ndarray An array of strings the same shape as `arr`. Examples -------- >>> import pytz >>> d = np.arange('2002-10-27T04:30', 4*60, 60, dtype='M8[m]') >>> d array(['2002-10-27T04:30', '2002-10-27T05:30', '2002-10-27T06:30', '2002-10-27T07:30'], dtype='datetime64[m]') Setting the timezone to UTC shows the same information, but with a Z suffix >>> np.datetime_as_string(d, timezone='UTC') array(['2002-10-27T04:30Z', '2002-10-27T05:30Z', '2002-10-27T06:30Z', '2002-10-27T07:30Z'], dtype='>> np.datetime_as_string(d, timezone=pytz.timezone('US/Eastern')) array(['2002-10-27T00:30-0400', '2002-10-27T01:30-0400', '2002-10-27T01:30-0500', '2002-10-27T02:30-0500'], dtype='>> np.datetime_as_string(d, unit='h') array(['2002-10-27T04', '2002-10-27T05', '2002-10-27T06', '2002-10-27T07'], dtype='>> np.datetime_as_string(d, unit='s') array(['2002-10-27T04:30:00', '2002-10-27T05:30:00', '2002-10-27T06:30:00', '2002-10-27T07:30:00'], dtype='>> np.datetime_as_string(d, unit='h', casting='safe') Traceback (most recent call last): ... TypeError: Cannot create a datetime string as units 'h' from a NumPy datetime with units 'm' according to the rule 'safe' " :arglists '[[& [args {:as kwargs}]]]} datetime_as_string (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "datetime_as_string")))) (def ^{:doc "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 ` 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')" :arglists '[[self & [args {:as kwargs}]]]} datetime_data (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "datetime_data")))) (def ^{:doc ""} nan ##NaN) (def ^{:doc " Return the imaginary part of the complex argument. Parameters ---------- val : array_like Input array. Returns ------- out : ndarray or scalar The imaginary component of the complex argument. If `val` is real, the type of `val` is used for the output. If `val` has complex elements, the returned type is float. See Also -------- real, angle, real_if_close Examples -------- >>> a = np.array([1+2j, 3+4j, 5+6j]) >>> a.imag array([2., 4., 6.]) >>> a.imag = np.array([8, 10, 12]) >>> a array([1. +8.j, 3.+10.j, 5.+12.j]) >>> np.imag(1 + 1j) 1.0 " :arglists '[[& [args {:as kwargs}]]]} imag (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "imag")))) (def ^{:doc " Counts the number of non-zero values in the array ``a``. The word \"non-zero\" is in reference to the Python 2.x built-in method ``__nonzero__()`` (renamed ``__bool__()`` in Python 3.x) of Python objects that tests an object's \"truthfulness\". For example, any number is considered truthful if it is nonzero, whereas any string is considered truthful if it is not the empty string. Thus, this function (recursively) counts how many elements in ``a`` (and in sub-arrays thereof) have their ``__nonzero__()`` or ``__bool__()`` method evaluated to ``True``. Parameters ---------- a : array_like The array for which to count non-zeros. axis : int or tuple, optional Axis or tuple of axes along which to count non-zeros. Default is None, meaning that non-zeros will be counted along a flattened version of ``a``. .. versionadded:: 1.12.0 keepdims : bool, optional If this is set to True, the axes that are counted are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array. .. versionadded:: 1.19.0 Returns ------- count : int or array of int Number of non-zero values in the array along a given axis. Otherwise, the total number of non-zero values in the array is returned. See Also -------- nonzero : Return the coordinates of all the non-zero values. Examples -------- >>> np.count_nonzero(np.eye(4)) 4 >>> a = np.array([[0, 1, 7, 0], ... [3, 0, 2, 19]]) >>> np.count_nonzero(a) 5 >>> np.count_nonzero(a, axis=0) array([1, 1, 2, 1]) >>> np.count_nonzero(a, axis=1) array([2, 3]) >>> np.count_nonzero(a, axis=1, keepdims=True) array([[2], [3]]) " :arglists '[[& [args {:as kwargs}]]]} count_nonzero (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "count_nonzero")))) (def ^{:doc "Extended-precision floating-point number type, compatible with C ``long double`` but not necessarily with IEEE 754 quadruple-precision. :Character code: ``'g'`` :Canonical name: `numpy.longdouble` :Alias: `numpy.longfloat` :Alias on this platform: `numpy.float128`: 128-bit extended-precision floating-point number type." :arglists '[[self & [args {:as kwargs}]]]} float128 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "float128")))) (def ^{:doc "greater(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the truth value of (x1 > x2) element-wise. Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array, element-wise comparison of `x1` and `x2`. Typically of type bool, unless ``dtype=object`` is passed. This is a scalar if both `x1` and `x2` are scalars. See Also -------- greater_equal, less, less_equal, equal, not_equal Examples -------- >>> np.greater([4,2],[2,2]) array([ True, False]) The ``>`` operator can be used as a shorthand for ``np.greater`` on ndarrays. >>> a = np.array([4, 2]) >>> b = np.array([2, 2]) >>> a > b array([ True, False])" :arglists '[[self & [args {:as kwargs}]]]} greater (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "greater")))) (def ^{:doc " Return a sorted copy of an array. Parameters ---------- a : array_like Array to be sorted. axis : int or None, optional Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis. kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional Sorting algorithm. The default is 'quicksort'. Note that both 'stable' and 'mergesort' use timsort or radix sort under the covers and, in general, the actual implementation will vary with data type. 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. Returns ------- sorted_array : ndarray Array of the same type and shape as `a`. See Also -------- ndarray.sort : Method to sort an array in-place. argsort : Indirect sort. lexsort : Indirect stable sort on multiple keys. searchsorted : Find elements in a sorted array. partition : Partial sort. Notes ----- The various sorting algorithms are characterized by their average speed, worst case performance, work space size, and whether they are stable. A stable sort keeps items with the same key in the same relative order. The four algorithms implemented in NumPy have the following properties: =========== ======= ============= ============ ======== kind speed worst case work space stable =========== ======= ============= ============ ======== 'quicksort' 1 O(n^2) 0 no 'heapsort' 3 O(n*log(n)) 0 no 'mergesort' 2 O(n*log(n)) ~n/2 yes 'timsort' 2 O(n*log(n)) ~n/2 yes =========== ======= ============= ============ ======== .. note:: The datatype determines which of 'mergesort' or 'timsort' is actually used, even if 'mergesort' is specified. User selection at a finer scale is not currently available. All the sort algorithms make temporary copies of the data when sorting along any but the last axis. Consequently, sorting along the last axis is faster and uses less space than sorting along any other axis. The sort order for complex numbers is lexicographic. If both the real and imaginary parts are non-nan then the order is determined by the real parts except when they are equal, in which case the order is determined by the imaginary parts. Previous to numpy 1.4.0 sorting real and complex arrays containing nan values led to undefined behaviour. In numpy versions >= 1.4.0 nan values are sorted to the end. The extended sort order is: * Real: [R, nan] * Complex: [R + Rj, R + nanj, nan + Rj, nan + nanj] where R is a non-nan real value. Complex values with the same nan placements are sorted according to the non-nan part if it exists. Non-nan values are sorted as before. .. versionadded:: 1.12.0 quicksort has been changed to `introsort `_. When sorting does not make enough progress it switches to `heapsort `_. This implementation makes quicksort O(n*log(n)) in the worst case. 'stable' automatically chooses the best stable sorting algorithm for the data type being sorted. It, along with 'mergesort' is currently mapped to `timsort `_ or `radix sort `_ depending on the data type. API forward compatibility currently limits the ability to select the implementation and it is hardwired for the different data types. .. versionadded:: 1.17.0 Timsort is added for better performance on already or nearly sorted data. On random data timsort is almost identical to mergesort. It is now used for stable sort while quicksort is still the default sort if none is chosen. For timsort details, refer to `CPython listsort.txt `_. 'mergesort' and 'stable' are mapped to radix sort for integer data types. Radix sort is an O(n) sort instead of O(n log n). .. versionchanged:: 1.18.0 NaT now sorts to the end of arrays for consistency with NaN. Examples -------- >>> a = np.array([[1,4],[3,1]]) >>> np.sort(a) # sort along the last axis array([[1, 4], [1, 3]]) >>> np.sort(a, axis=None) # sort the flattened array array([1, 1, 3, 4]) >>> np.sort(a, axis=0) # sort along the first axis array([[1, 1], [3, 4]]) Use the `order` keyword to specify a field to use when sorting a structured array: >>> dtype = [('name', 'S10'), ('height', float), ('age', int)] >>> values = [('Arthur', 1.8, 41), ('Lancelot', 1.9, 38), ... ('Galahad', 1.7, 38)] >>> a = np.array(values, dtype=dtype) # create a structured array >>> np.sort(a, order='height') # doctest: +SKIP array([('Galahad', 1.7, 38), ('Arthur', 1.8, 41), ('Lancelot', 1.8999999999999999, 38)], dtype=[('name', '|S10'), ('height', '>> np.sort(a, order=['age', 'height']) # doctest: +SKIP array([('Galahad', 1.7, 38), ('Lancelot', 1.8999999999999999, 38), ('Arthur', 1.8, 41)], dtype=[('name', '|S10'), ('height', '`. A convenience class, used to encapsulate \"natural\" operations on polynomials so that said operations may take on their customary form in code (see Examples). Parameters ---------- c_or_r : array_like The polynomial's coefficients, in decreasing powers, or if the value of the second parameter is True, the polynomial's roots (values where the polynomial evaluates to 0). For example, ``poly1d([1, 2, 3])`` returns an object that represents :math:`x^2 + 2x + 3`, whereas ``poly1d([1, 2, 3], True)`` returns one that represents :math:`(x-1)(x-2)(x-3) = x^3 - 6x^2 + 11x -6`. r : bool, optional If True, `c_or_r` specifies the polynomial's roots; the default is False. variable : str, optional Changes the variable used when printing `p` from `x` to `variable` (see Examples). Examples -------- Construct the polynomial :math:`x^2 + 2x + 3`: >>> p = np.poly1d([1, 2, 3]) >>> print(np.poly1d(p)) 2 1 x + 2 x + 3 Evaluate the polynomial at :math:`x = 0.5`: >>> p(0.5) 4.25 Find the roots: >>> p.r array([-1.+1.41421356j, -1.-1.41421356j]) >>> p(p.r) array([ -4.44089210e-16+0.j, -4.44089210e-16+0.j]) # may vary These numbers in the previous line represent (0, 0) to machine precision Show the coefficients: >>> p.c array([1, 2, 3]) Display the order (the leading zero-coefficients are removed): >>> p.order 2 Show the coefficient of the k-th power in the polynomial (which is equivalent to ``p.c[-(i+1)]``): >>> p[1] 2 Polynomials can be added, subtracted, multiplied, and divided (returns quotient and remainder): >>> p * p poly1d([ 1, 4, 10, 12, 9]) >>> (p**3 + 4) / p (poly1d([ 1., 4., 10., 12., 9.]), poly1d([4.])) ``asarray(p)`` gives the coefficient array, so polynomials can be used in all functions that accept arrays: >>> p**2 # square of polynomial poly1d([ 1, 4, 10, 12, 9]) >>> np.square(p) # square of individual coefficients array([1, 4, 9]) The variable used in the string representation of `p` can be modified, using the `variable` parameter: >>> p = np.poly1d([1,2,3], variable='z') >>> print(p) 2 1 z + 2 z + 3 Construct a polynomial from its roots: >>> np.poly1d([1, 2], True) poly1d([ 1., -3., 2.]) This is the same polynomial as obtained by: >>> np.poly1d([1, -1]) * np.poly1d([1, -2]) poly1d([ 1, -3, 2]) " :arglists '[[self c_or_r & [{r :r, variable :variable}]] [self c_or_r & [{r :r}]] [self c_or_r]]} poly1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "poly1d")))) (def ^{:doc "isfinite(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Test element-wise for finiteness (not infinity or not Not a Number). The result is returned as a boolean array. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray, bool True where ``x`` is not positive infinity, negative infinity, or NaN; false otherwise. This is a scalar if `x` is a scalar. See Also -------- isinf, isneginf, isposinf, isnan Notes ----- Not a Number, positive infinity and negative infinity are considered to be non-finite. NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Also that positive infinity is not equivalent to negative infinity. But infinity is equivalent to positive infinity. Errors result if the second argument is also supplied when `x` is a scalar input, or if first and second arguments have different shapes. Examples -------- >>> np.isfinite(1) True >>> np.isfinite(0) True >>> np.isfinite(np.nan) False >>> np.isfinite(np.inf) False >>> np.isfinite(np.NINF) False >>> np.isfinite([np.log(-1.),1.,np.log(0)]) array([False, True, False]) >>> x = np.array([-np.inf, 0., np.inf]) >>> y = np.array([2, 2, 2]) >>> np.isfinite(x, y) array([0, 1, 0]) >>> y array([0, 1, 0])" :arglists '[[self & [args {:as kwargs}]]]} isfinite (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isfinite")))) (def ^{:doc "log(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Natural logarithm, element-wise. The natural logarithm `log` is the inverse of the exponential function, so that `log(exp(x)) = x`. The natural logarithm is logarithm in base `e`. Parameters ---------- x : array_like Input value. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The natural logarithm of `x`, element-wise. This is a scalar if `x` is a scalar. See Also -------- log10, log2, log1p, emath.log Notes ----- Logarithm is a multivalued function: for each `x` there is an infinite number of `z` such that `exp(z) = x`. The convention is to return the `z` whose imaginary part lies in `[-pi, pi]`. For real-valued input data types, `log` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `log` is a complex analytical function that has a branch cut `[-inf, 0]` and is continuous from above on it. `log` handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard. References ---------- .. [1] M. Abramowitz and I.A. Stegun, \"Handbook of Mathematical Functions\", 10th printing, 1964, pp. 67. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, \"Logarithm\". https://en.wikipedia.org/wiki/Logarithm Examples -------- >>> np.log([1, np.e, np.e**2, 0]) array([ 0., 1., 2., -Inf])" :arglists '[[self & [args {:as kwargs}]]]} log (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "log")))) (def ^{:doc "Complex number type composed of two double-precision floating-point numbers, compatible with Python `complex`. :Character code: ``'D'`` :Canonical name: `numpy.cdouble` :Alias: `numpy.cfloat` :Alias: `numpy.complex_` :Alias on this platform: `numpy.complex128`: Complex number type composed of 2 64-bit-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} complex128 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "complex128")))) (def ^{:doc " Construct an array by executing a function over each coordinate. The resulting array therefore has a value ``fn(x, y, z)`` at coordinate ``(x, y, z)``. Parameters ---------- function : callable The function is called with N parameters, where N is the rank of `shape`. Each parameter represents the coordinates of the array varying along a specific axis. For example, if `shape` were ``(2, 2)``, then the parameters would be ``array([[0, 0], [1, 1]])`` and ``array([[0, 1], [0, 1]])`` shape : (N,) tuple of ints Shape of the output array, which also determines the shape of the coordinate arrays passed to `function`. dtype : data-type, optional Data-type of the coordinate arrays passed to `function`. By default, `dtype` is float. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- fromfunction : any The result of the call to `function` is passed back directly. Therefore the shape of `fromfunction` is completely determined by `function`. If `function` returns a scalar value, the shape of `fromfunction` would not match the `shape` parameter. See Also -------- indices, meshgrid Notes ----- Keywords other than `dtype` are passed to `function`. Examples -------- >>> np.fromfunction(lambda i, j: i == j, (3, 3), dtype=int) array([[ True, False, False], [False, True, False], [False, False, True]]) >>> np.fromfunction(lambda i, j: i + j, (3, 3), dtype=int) array([[0, 1, 2], [1, 2, 3], [2, 3, 4]]) " :arglists '[[function shape & [{dtype :dtype, like :like, :as kwargs}]]]} fromfunction (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fromfunction")))) (def ^{:doc " Return the cumulative product of array elements over a given axis treating Not a Numbers (NaNs) as one. The cumulative product does not change when NaNs are encountered and leading NaNs are replaced by ones. Ones are returned for slices that are all-NaN or empty. .. versionadded:: 1.12.0 Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative product is computed. By default the input is flattened. dtype : dtype, optional Type of the returned array, as well as of the accumulator in which the elements are multiplied. If *dtype* is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used instead. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type of the resulting values will be cast if necessary. Returns ------- nancumprod : ndarray A new array holding the result is returned unless `out` is specified, in which case it is returned. See Also -------- numpy.cumprod : Cumulative product across array propagating NaNs. isnan : Show which elements are NaN. Examples -------- >>> np.nancumprod(1) array([1]) >>> np.nancumprod([1]) array([1]) >>> np.nancumprod([1, np.nan]) array([1., 1.]) >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nancumprod(a) array([1., 2., 6., 6.]) >>> np.nancumprod(a, axis=0) array([[1., 2.], [3., 2.]]) >>> np.nancumprod(a, axis=1) array([[1., 2.], [3., 3.]]) " :arglists '[[& [args {:as kwargs}]]]} nancumprod (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nancumprod")))) (def ^{:doc "divmod(x1, x2[, out1, out2], / [, out=(None, None)], *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return element-wise quotient and remainder simultaneously. .. versionadded:: 1.13.0 ``np.divmod(x, y)`` is equivalent to ``(x // y, x % y)``, but faster because it avoids redundant work. It is used to implement the Python built-in function ``divmod`` on NumPy arrays. Parameters ---------- x1 : array_like Dividend array. x2 : array_like Divisor array. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out1 : ndarray Element-wise quotient resulting from floor division. This is a scalar if both `x1` and `x2` are scalars. out2 : ndarray Element-wise remainder from floor division. This is a scalar if both `x1` and `x2` are scalars. See Also -------- floor_divide : Equivalent to Python's ``//`` operator. remainder : Equivalent to Python's ``%`` operator. modf : Equivalent to ``divmod(x, 1)`` for positive ``x`` with the return values switched. Examples -------- >>> np.divmod(np.arange(5), 3) (array([0, 0, 0, 1, 1]), array([0, 1, 2, 0, 1])) The `divmod` function can be used as a shorthand for ``np.divmod`` on ndarrays. >>> x = np.arange(5) >>> divmod(x, 3) (array([0, 0, 0, 1, 1]), array([0, 1, 2, 0, 1]))" :arglists '[[self & [args {:as kwargs}]]]} divmod (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "divmod")))) (def ^{:doc ""} ERR_DEFAULT 521) (def ^{:doc " Return the indices to access the main diagonal of an n-dimensional array. See `diag_indices` for full details. Parameters ---------- arr : array, at least 2-D See Also -------- diag_indices Notes ----- .. versionadded:: 1.4.0 " :arglists '[[& [args {:as kwargs}]]]} diag_indices_from (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "diag_indices_from")))) (def ^{:doc " Save an array to a text file. Parameters ---------- fname : filename or file handle If the filename ends in ``.gz``, the file is automatically saved in compressed gzip format. `loadtxt` understands gzipped files transparently. X : 1D or 2D array_like Data to be saved to a text file. fmt : str or sequence of strs, optional A single format (%10.5f), a sequence of formats, or a multi-format string, e.g. 'Iteration %d -- %10.5f', in which case `delimiter` is ignored. For complex `X`, the legal options for `fmt` are: * a single specifier, `fmt='%.4e'`, resulting in numbers formatted like `' (%s+%sj)' % (fmt, fmt)` * a full string specifying every real and imaginary part, e.g. `' %.4e %+.4ej %.4e %+.4ej %.4e %+.4ej'` for 3 columns * a list of specifiers, one per column - in this case, the real and imaginary part must have separate specifiers, e.g. `['%.3e + %.3ej', '(%.15e%+.15ej)']` for 2 columns delimiter : str, optional String or character separating columns. newline : str, optional String or character separating lines. .. versionadded:: 1.5.0 header : str, optional String that will be written at the beginning of the file. .. versionadded:: 1.7.0 footer : str, optional String that will be written at the end of the file. .. versionadded:: 1.7.0 comments : str, optional String that will be prepended to the ``header`` and ``footer`` strings, to mark them as comments. Default: '# ', as expected by e.g. ``numpy.loadtxt``. .. versionadded:: 1.7.0 encoding : {None, str}, optional Encoding used to encode the outputfile. Does not apply to output streams. If the encoding is something other than 'bytes' or 'latin1' you will not be able to load the file in NumPy versions < 1.14. Default is 'latin1'. .. versionadded:: 1.14.0 See Also -------- save : Save an array to a binary file in NumPy ``.npy`` format savez : Save several arrays into an uncompressed ``.npz`` archive savez_compressed : Save several arrays into a compressed ``.npz`` archive Notes ----- Further explanation of the `fmt` parameter (``%[flag]width[.precision]specifier``): flags: ``-`` : left justify ``+`` : Forces to precede result with + or -. ``0`` : Left pad the number with zeros instead of space (see width). width: Minimum number of characters to be printed. The value is not truncated if it has more characters. precision: - For integer specifiers (eg. ``d,i,o,x``), the minimum number of digits. - For ``e, E`` and ``f`` specifiers, the number of digits to print after the decimal point. - For ``g`` and ``G``, the maximum number of significant digits. - For ``s``, the maximum number of characters. specifiers: ``c`` : character ``d`` or ``i`` : signed decimal integer ``e`` or ``E`` : scientific notation with ``e`` or ``E``. ``f`` : decimal floating point ``g,G`` : use the shorter of ``e,E`` or ``f`` ``o`` : signed octal ``s`` : string of characters ``u`` : unsigned decimal integer ``x,X`` : unsigned hexadecimal integer This explanation of ``fmt`` is not complete, for an exhaustive specification see [1]_. References ---------- .. [1] `Format Specification Mini-Language `_, Python Documentation. Examples -------- >>> x = y = z = np.arange(0.0,5.0,1.0) >>> np.savetxt('test.out', x, delimiter=',') # X is an array >>> np.savetxt('test.out', (x,y,z)) # x,y,z equal sized 1D arrays >>> np.savetxt('test.out', x, fmt='%1.4e') # use exponential notation " :arglists '[[& [args {:as kwargs}]]]} savetxt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "savetxt")))) (def ^{:doc "A timedelta stored as a 64-bit integer. See :ref:`arrays.datetime` for more information. :Character code: ``'m'``" :arglists '[[self & [args {:as kwargs}]]]} timedelta64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "timedelta64")))) (def ^{:doc " View inputs as arrays with at least three dimensions. Parameters ---------- arys1, arys2, ... : array_like One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have three or more dimensions are preserved. Returns ------- res1, res2, ... : ndarray An array, or list of arrays, each with ``a.ndim >= 3``. Copies are avoided where possible, and views with three or more dimensions are returned. For example, a 1-D array of shape ``(N,)`` becomes a view of shape ``(1, N, 1)``, and a 2-D array of shape ``(M, N)`` becomes a view of shape ``(M, N, 1)``. See Also -------- atleast_1d, atleast_2d Examples -------- >>> np.atleast_3d(3.0) array([[[3.]]]) >>> x = np.arange(3.0) >>> np.atleast_3d(x).shape (1, 3, 1) >>> x = np.arange(12.0).reshape(4,3) >>> np.atleast_3d(x).shape (4, 3, 1) >>> np.atleast_3d(x).base is x.base # x is a reshape, so not base itself True >>> for arr in np.atleast_3d([1, 2], [[1, 2]], [[[1, 2]]]): ... print(arr, arr.shape) # doctest: +SKIP ... [[[1] [2]]] (1, 2, 1) [[[1] [2]]] (1, 2, 1) [[[1 2]]] (1, 1, 2) " :arglists '[[& [args {:as kwargs}]]]} atleast_3d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "atleast_3d")))) (def ^{:doc "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])" :arglists '[[self & [args {:as kwargs}]]]} ndarray (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ndarray")))) (def ^{:doc " Return the product of array elements over a given axis. See Also -------- prod : equivalent function; see for details. " :arglists '[[& [args {:as kwargs}]]]} product (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "product")))) (def ^{:doc "Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified."} __path__ (as-jvm/generic-python-as-list (py-global-delay (py/get-attr @src-obj* "__path__")))) (def ^{:doc " Range of values (maximum - minimum) along an axis. The name of the function comes from the acronym for 'peak to peak'. .. warning:: `ptp` preserves the data type of the array. This means the return value for an input of signed integers with n bits (e.g. `np.int8`, `np.int16`, etc) is also a signed integer with n bits. In that case, peak-to-peak values greater than ``2**(n-1)-1`` will be returned as negative values. An example with a work-around is shown below. Parameters ---------- a : array_like Input values. axis : None or int or tuple of ints, optional Axis along which to find the peaks. By default, flatten the array. `axis` may be negative, in which case it counts from the last to the first axis. .. versionadded:: 1.15.0 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. out : array_like Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type of the output values will be cast if necessary. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `ptp` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. Returns ------- ptp : ndarray A new array holding the result, unless `out` was specified, in which case a reference to `out` is returned. Examples -------- >>> x = np.array([[4, 9, 2, 10], ... [6, 9, 7, 12]]) >>> np.ptp(x, axis=1) array([8, 6]) >>> np.ptp(x, axis=0) array([2, 0, 5, 2]) >>> np.ptp(x) 10 This example shows that a negative value can be returned when the input is an array of signed integers. >>> y = np.array([[1, 127], ... [0, 127], ... [-1, 127], ... [-2, 127]], dtype=np.int8) >>> np.ptp(y, axis=1) array([ 126, 127, -128, -127], dtype=int8) A work-around is to use the `view()` method to view the result as unsigned integers with the same bit width: >>> np.ptp(y, axis=1).view(np.uint8) array([126, 127, 128, 129], dtype=uint8) " :arglists '[[& [args {:as kwargs}]]]} ptp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ptp")))) (def ^{:doc "Abstract base class of all floating-point scalar types." :arglists '[[self & [args {:as kwargs}]]]} floating (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "floating")))) (def ^{:doc "arctan(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Trigonometric inverse tangent, element-wise. The inverse of tan, so that if ``y = tan(x)`` then ``x = arctan(y)``. Parameters ---------- x : array_like out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Out has the same shape as `x`. Its real part is in ``[-pi/2, pi/2]`` (``arctan(+/-inf)`` returns ``+/-pi/2``). This is a scalar if `x` is a scalar. See Also -------- arctan2 : The \"four quadrant\" arctan of the angle formed by (`x`, `y`) and the positive `x`-axis. angle : Argument of complex values. Notes ----- `arctan` is a multi-valued function: for each `x` there are infinitely many numbers `z` such that tan(`z`) = `x`. The convention is to return the angle `z` whose real part lies in [-pi/2, pi/2]. For real-valued input data types, `arctan` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `arctan` is a complex analytic function that has [`1j, infj`] and [`-1j, -infj`] as branch cuts, and is continuous from the left on the former and from the right on the latter. The inverse tangent is also known as `atan` or tan^{-1}. References ---------- Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, 10th printing, New York: Dover, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/ Examples -------- We expect the arctan of 0 to be 0, and of 1 to be pi/4: >>> np.arctan([0, 1]) array([ 0. , 0.78539816]) >>> np.pi/4 0.78539816339744828 Plot arctan: >>> import matplotlib.pyplot as plt >>> x = np.linspace(-10, 10) >>> plt.plot(x, np.arctan(x)) >>> plt.axis('tight') >>> plt.show()" :arglists '[[self & [args {:as kwargs}]]]} arctan (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arctan")))) (def ^{:doc "fromstring(string, dtype=float, count=-1, sep='', *, like=None) 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 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])" :arglists '[[self & [args {:as kwargs}]]]} fromstring (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fromstring")))) (def ^{:doc "Special keyword value. The instance of this class may be used as the default value assigned to a deprecated keyword in order to check if it has been given a user defined value. "} _NoValue (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "_NoValue")))) (def ^{:doc "Abstract base class of all signed integer scalar types." :arglists '[[self & [args {:as kwargs}]]]} signedinteger (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "signedinteger")))) (def ^{:doc " Test whether any array element along a given axis evaluates to True. Returns single boolean unless `axis` is not ``None`` Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : None or int or tuple of ints, optional Axis or axes along which a logical OR reduction is performed. The default (``axis=None``) is to perform a logical OR over all the dimensions 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 a tuple of ints, a reduction is performed on multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved (e.g., if it is of type float, then it will remain so, returning 1.0 for True and 0.0 for False, regardless of the type of `a`). See :ref:`ufuncs-output-type` for more details. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `any` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. where : array_like of bool, optional Elements to include in checking for any `True` values. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.20.0 Returns ------- any : bool or ndarray A new boolean or `ndarray` is returned unless `out` is specified, in which case a reference to `out` is returned. See Also -------- ndarray.any : equivalent method all : Test whether all elements along a given axis evaluate to True. Notes ----- Not a Number (NaN), positive infinity and negative infinity evaluate to `True` because these are not equal to zero. Examples -------- >>> np.any([[True, False], [True, True]]) True >>> np.any([[True, False], [False, False]], axis=0) array([ True, False]) >>> np.any([-1, 0, 5]) True >>> np.any(np.nan) True >>> np.any([[True, False], [False, False]], where=[[False], [True]]) False >>> o=np.array(False) >>> z=np.any([-1, 4, 5], out=o) >>> z, o (array(True), array(True)) >>> # Check now that z is a reference to o >>> z is o True >>> id(z), id(o) # identity of z and o # doctest: +SKIP (191614240, 191614240) " :arglists '[[& [args {:as kwargs}]]]} any (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "any")))) (def ^{:doc " Return the angle of the complex argument. Parameters ---------- z : array_like A complex number or sequence of complex numbers. deg : bool, optional Return angle in degrees if True, radians if False (default). Returns ------- angle : ndarray or scalar The counterclockwise angle from the positive real axis on the complex plane in the range ``(-pi, pi]``, with dtype as numpy.float64. .. versionchanged:: 1.16.0 This function works on subclasses of ndarray like `ma.array`. See Also -------- arctan2 absolute Notes ----- Although the angle of the complex number 0 is undefined, ``numpy.angle(0)`` returns the value 0. Examples -------- >>> np.angle([1.0, 1.0j, 1+1j]) # in radians array([ 0. , 1.57079633, 0.78539816]) # may vary >>> np.angle(1+1j, deg=True) # in degrees 45.0 " :arglists '[[& [args {:as kwargs}]]]} angle (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "angle")))) (def ^{:doc " Gives a new shape to an array without changing its data. Parameters ---------- a : array_like Array to be reshaped. newshape : int or tuple of ints The new shape should be compatible with the original shape. If an integer, then the result will be a 1-D array of that length. One shape dimension can be -1. In this case, the value is inferred from the length of the array and remaining dimensions. order : {'C', 'F', 'A'}, optional Read the elements of `a` using this index order, and place the elements into the reshaped array using this index order. 'C' means to read / write the elements using C-like index order, with the last axis index changing fastest, back to the first axis index changing slowest. 'F' means to read / write the elements using Fortran-like index order, with the first index changing fastest, and the last index changing slowest. Note that the 'C' and 'F' options take no account of the memory layout of the underlying array, and only refer to the order of indexing. 'A' means to read / write the elements in Fortran-like index order if `a` is Fortran *contiguous* in memory, C-like order otherwise. Returns ------- reshaped_array : ndarray This will be a new view object if possible; otherwise, it will be a copy. Note there is no guarantee of the *memory layout* (C- or Fortran- contiguous) of the returned array. See Also -------- ndarray.reshape : Equivalent method. Notes ----- It is not always possible to change the shape of an array without copying the data. If you want an error to be raised when the data is copied, you should assign the new shape to the shape attribute of the array:: >>> a = np.zeros((10, 2)) # A transpose makes the array non-contiguous >>> b = a.T # Taking a view makes it possible to modify the shape without modifying # the initial object. >>> c = b.view() >>> c.shape = (20) Traceback (most recent call last): ... AttributeError: Incompatible shape for in-place modification. Use `.reshape()` to make a copy with the desired shape. The `order` keyword gives the index ordering both for *fetching* the values from `a`, and then *placing* the values into the output array. For example, let's say you have an array: >>> a = np.arange(6).reshape((3, 2)) >>> a array([[0, 1], [2, 3], [4, 5]]) You can think of reshaping as first raveling the array (using the given index order), then inserting the elements from the raveled array into the new array using the same kind of index ordering as was used for the raveling. >>> np.reshape(a, (2, 3)) # C-like index ordering array([[0, 1, 2], [3, 4, 5]]) >>> np.reshape(np.ravel(a), (2, 3)) # equivalent to C ravel then C reshape array([[0, 1, 2], [3, 4, 5]]) >>> np.reshape(a, (2, 3), order='F') # Fortran-like index ordering array([[0, 4, 3], [2, 1, 5]]) >>> np.reshape(np.ravel(a, order='F'), (2, 3), order='F') array([[0, 4, 3], [2, 1, 5]]) Examples -------- >>> a = np.array([[1,2,3], [4,5,6]]) >>> np.reshape(a, 6) array([1, 2, 3, 4, 5, 6]) >>> np.reshape(a, 6, order='F') array([1, 4, 2, 5, 3, 6]) >>> np.reshape(a, (3,-1)) # the unspecified value is inferred to be 2 array([[1, 2], [3, 4], [5, 6]]) " :arglists '[[& [args {:as kwargs}]]]} reshape (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "reshape")))) (def ^{:doc " Modified Bessel function of the first kind, order 0. Usually denoted :math:`I_0`. Parameters ---------- x : array_like of float Argument of the Bessel function. Returns ------- out : ndarray, shape = x.shape, dtype = float The modified Bessel function evaluated at each of the elements of `x`. See Also -------- scipy.special.i0, scipy.special.iv, scipy.special.ive Notes ----- The scipy implementation is recommended over this function: it is a proper ufunc written in C, and more than an order of magnitude faster. We use the algorithm published by Clenshaw [1]_ and referenced by Abramowitz and Stegun [2]_, for which the function domain is partitioned into the two intervals [0,8] and (8,inf), and Chebyshev polynomial expansions are employed in each interval. Relative error on the domain [0,30] using IEEE arithmetic is documented [3]_ as having a peak of 5.8e-16 with an rms of 1.4e-16 (n = 30000). References ---------- .. [1] C. W. Clenshaw, \"Chebyshev series for mathematical functions\", in *National Physical Laboratory Mathematical Tables*, vol. 5, London: Her Majesty's Stationery Office, 1962. .. [2] M. Abramowitz and I. A. Stegun, *Handbook of Mathematical Functions*, 10th printing, New York: Dover, 1964, pp. 379. http://www.math.sfu.ca/~cbm/aands/page_379.htm .. [3] https://metacpan.org/pod/distribution/Math-Cephes/lib/Math/Cephes.pod#i0:-Modified-Bessel-function-of-order-zero Examples -------- >>> np.i0(0.) array(1.0) >>> np.i0([0, 1, 2, 3]) array([1. , 1.26606588, 2.2795853 , 4.88079259]) " :arglists '[[& [args {:as kwargs}]]]} i0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "i0")))) (def ^{:doc " Multidimensional index iterator. Return an iterator yielding pairs of array coordinates and values. Parameters ---------- arr : ndarray Input array. See Also -------- ndindex, flatiter Examples -------- >>> a = np.array([[1, 2], [3, 4]]) >>> for index, x in np.ndenumerate(a): ... print(index, x) (0, 0) 1 (0, 1) 2 (1, 0) 3 (1, 1) 4 " :arglists '[[self arr]]} ndenumerate (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ndenumerate")))) (def ^{:doc " Return the Hamming window. The Hamming window is a taper formed by using a weighted cosine. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : ndarray The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd). See Also -------- bartlett, blackman, hanning, kaiser Notes ----- The Hamming window is defined as .. math:: w(n) = 0.54 - 0.46cos\\left(\\frac{2\\pi{n}}{M-1}\\right) \\qquad 0 \\leq n \\leq M-1 The Hamming was named for R. W. Hamming, an associate of J. W. Tukey and is described in Blackman and Tukey. It was recommended for smoothing the truncated autocovariance function in the time domain. Most references to the Hamming window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means \"removing the foot\", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. References ---------- .. [1] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York. .. [2] E.R. Kanasewich, \"Time Sequence Analysis in Geophysics\", The University of Alberta Press, 1975, pp. 109-110. .. [3] Wikipedia, \"Window function\", https://en.wikipedia.org/wiki/Window_function .. [4] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, \"Numerical Recipes\", Cambridge University Press, 1986, page 425. Examples -------- >>> np.hamming(12) array([ 0.08 , 0.15302337, 0.34890909, 0.60546483, 0.84123594, # may vary 0.98136677, 0.98136677, 0.84123594, 0.60546483, 0.34890909, 0.15302337, 0.08 ]) Plot the window and the frequency response: >>> import matplotlib.pyplot as plt >>> from numpy.fft import fft, fftshift >>> window = np.hamming(51) >>> plt.plot(window) [] >>> plt.title(\"Hamming window\") Text(0.5, 1.0, 'Hamming window') >>> plt.ylabel(\"Amplitude\") Text(0, 0.5, 'Amplitude') >>> plt.xlabel(\"Sample\") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure()
>>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> response = 20 * np.log10(mag) >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [] >>> plt.title(\"Frequency response of Hamming window\") Text(0.5, 1.0, 'Frequency response of Hamming window') >>> plt.ylabel(\"Magnitude [dB]\") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel(\"Normalized frequency [cycles per sample]\") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> plt.axis('tight') ... >>> plt.show() " :arglists '[[M]]} hamming (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "hamming")))) (def ^{:doc ""} NAN ##NaN) (def ^{:doc ""} Infinity ##Inf) (def ^{:doc ""} MAY_SHARE_EXACT -1) (def ^{:doc " Return a string representation of an array. Parameters ---------- a : array_like Input array. max_line_width : int, optional Inserts newlines if text is longer than `max_line_width`. Defaults to ``numpy.get_printoptions()['linewidth']``. precision : int or None, optional Floating point precision. Defaults to ``numpy.get_printoptions()['precision']``. suppress_small : bool, optional Represent numbers \"very close\" to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to ``numpy.get_printoptions()['suppress']``. separator : str, optional Inserted between elements. prefix : str, optional suffix: str, optional The length of the prefix and suffix strings are used to respectively align and wrap the output. An array is typically printed as:: prefix + array2string(a) + suffix The output is left-padded by the length of the prefix string, and wrapping is forced at the column ``max_line_width - len(suffix)``. It should be noted that the content of prefix and suffix strings are not included in the output. style : _NoValue, optional Has no effect, do not use. .. deprecated:: 1.14.0 formatter : dict of callables, optional If not None, the keys should indicate the type(s) that the respective formatting function applies to. Callables should return a string. Types that are not specified (by their corresponding keys) are handled by the default formatters. Individual types for which a formatter can be set are: - 'bool' - 'int' - 'timedelta' : a `numpy.timedelta64` - 'datetime' : a `numpy.datetime64` - 'float' - 'longfloat' : 128-bit floats - 'complexfloat' - 'longcomplexfloat' : composed of two 128-bit floats - 'void' : type `numpy.void` - 'numpystr' : types `numpy.string_` and `numpy.unicode_` - 'str' : all other strings Other keys that can be used to set a group of types at once are: - 'all' : sets all types - 'int_kind' : sets 'int' - 'float_kind' : sets 'float' and 'longfloat' - 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat' - 'str_kind' : sets 'str' and 'numpystr' threshold : int, optional Total number of array elements which trigger summarization rather than full repr. Defaults to ``numpy.get_printoptions()['threshold']``. edgeitems : int, optional Number of array items in summary at beginning and end of each dimension. Defaults to ``numpy.get_printoptions()['edgeitems']``. sign : string, either '-', '+', or ' ', optional Controls printing of the sign of floating-point types. If '+', always print the sign of positive values. If ' ', always prints a space (whitespace character) in the sign position of positive values. If '-', omit the sign character of positive values. Defaults to ``numpy.get_printoptions()['sign']``. floatmode : str, optional Controls the interpretation of the `precision` option for floating-point types. Defaults to ``numpy.get_printoptions()['floatmode']``. Can take the following values: - 'fixed': Always print exactly `precision` fractional digits, even if this would print more or fewer digits than necessary to specify the value uniquely. - 'unique': Print the minimum number of fractional digits necessary to represent each value uniquely. Different elements may have a different number of digits. The value of the `precision` option is ignored. - 'maxprec': Print at most `precision` fractional digits, but if an element can be uniquely represented with fewer digits only print it with that many. - 'maxprec_equal': Print at most `precision` fractional digits, but if every element in the array can be uniquely represented with an equal number of fewer digits, use that many digits for all elements. legacy : string or `False`, optional If set to the string `'1.13'` enables 1.13 legacy printing mode. This approximates numpy 1.13 print output by including a space in the sign position of floats and different behavior for 0d arrays. If set to `False`, disables legacy mode. Unrecognized strings will be ignored with a warning for forward compatibility. .. versionadded:: 1.14.0 Returns ------- array_str : str String representation of the array. Raises ------ TypeError if a callable in `formatter` does not return a string. See Also -------- array_str, array_repr, set_printoptions, get_printoptions Notes ----- If a formatter is specified for a certain type, the `precision` keyword is ignored for that type. This is a very flexible function; `array_repr` and `array_str` are using `array2string` internally so keywords with the same name should work identically in all three functions. Examples -------- >>> x = np.array([1e-16,1,2,3]) >>> np.array2string(x, precision=2, separator=',', ... suppress_small=True) '[0.,1.,2.,3.]' >>> x = np.arange(3.) >>> np.array2string(x, formatter={'float_kind':lambda x: \"%.2f\" % x}) '[0.00 1.00 2.00]' >>> x = np.arange(3) >>> np.array2string(x, formatter={'int':lambda x: hex(x)}) '[0x0 0x1 0x2]' " :arglists '[[& [args {:as kwargs}]]]} array2string (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "array2string")))) (def ^{:doc " Display a message on a device. Parameters ---------- mesg : str Message to display. device : object Device to write message. If None, defaults to ``sys.stdout`` which is very similar to ``print``. `device` needs to have ``write()`` and ``flush()`` methods. linefeed : bool, optional Option whether to print a line feed or not. Defaults to True. Raises ------ AttributeError If `device` does not have a ``write()`` or ``flush()`` method. Examples -------- Besides ``sys.stdout``, a file-like object can also be used as it has both required methods: >>> from io import StringIO >>> buf = StringIO() >>> np.disp(u'\"Display\" in a file', device=buf) >>> buf.getvalue() '\"Display\" in a file\\n' " :arglists '[[mesg & [{device :device, linefeed :linefeed}]] [mesg & [{device :device}]] [mesg]]} disp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "disp")))) (def ^{:doc " packbits(a, axis=None, bitorder='big') Packs the elements of a binary-valued array into bits in a uint8 array. The result is padded to full bytes by inserting zero bits at the end. Parameters ---------- a : array_like An array of integers or booleans whose elements should be packed to bits. axis : int, optional The dimension over which bit-packing is done. ``None`` implies packing the flattened array. bitorder : {'big', 'little'}, optional The order of the input bits. 'big' will mimic bin(val), ``[0, 0, 0, 0, 0, 0, 1, 1] => 3 = 0b00000011``, 'little' will reverse the order so ``[1, 1, 0, 0, 0, 0, 0, 0] => 3``. Defaults to 'big'. .. versionadded:: 1.17.0 Returns ------- packed : ndarray Array of type uint8 whose elements represent bits corresponding to the logical (0 or nonzero) value of the input elements. The shape of `packed` has the same number of dimensions as the input (unless `axis` is None, in which case the output is 1-D). See Also -------- unpackbits: Unpacks elements of a uint8 array into a binary-valued output array. Examples -------- >>> a = np.array([[[1,0,1], ... [0,1,0]], ... [[1,1,0], ... [0,0,1]]]) >>> b = np.packbits(a, axis=-1) >>> b array([[[160], [ 64]], [[192], [ 32]]], dtype=uint8) Note that in binary 160 = 1010 0000, 64 = 0100 0000, 192 = 1100 0000, and 32 = 0010 0000. " :arglists '[[& [args {:as kwargs}]]]} packbits (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "packbits")))) (def ^{:doc ""} ERR_WARN 1) (def ^{:doc " Compute the q-th percentile of the data along the specified axis. Returns the q-th percentile(s) of the array elements. Parameters ---------- a : array_like Input array or object that can be converted to an array. q : array_like of float Percentile or sequence of percentiles to compute, which must be between 0 and 100 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the percentiles are computed. The default is to compute the percentile(s) along a flattened version of the array. .. versionchanged:: 1.9.0 A tuple of axes is supported out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} This optional parameter specifies the interpolation method to use when the desired percentile lies between two data points ``i < j``: * 'linear': ``i + (j - i) * fraction``, where ``fraction`` is the fractional part of the index surrounded by ``i`` and ``j``. * 'lower': ``i``. * 'higher': ``j``. * 'nearest': ``i`` or ``j``, whichever is nearest. * 'midpoint': ``(i + j) / 2``. .. versionadded:: 1.9.0 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 array `a`. .. versionadded:: 1.9.0 Returns ------- percentile : scalar or ndarray If `q` is a single percentile and `axis=None`, then the result is a scalar. If multiple percentiles are given, first axis of the result corresponds to the percentiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean median : equivalent to ``percentile(..., 50)`` nanpercentile quantile : equivalent to percentile, except with q in the range [0, 1]. Notes ----- Given a vector ``V`` of length ``N``, the q-th percentile of ``V`` is the value ``q/100`` of the way from the minimum to the maximum in a sorted copy of ``V``. The values and distances of the two nearest neighbors as well as the `interpolation` parameter will determine the percentile if the normalized ranking does not match the location of ``q`` exactly. This function is the same as the median if ``q=50``, the same as the minimum if ``q=0`` and the same as the maximum if ``q=100``. Examples -------- >>> a = np.array([[10, 7, 4], [3, 2, 1]]) >>> a array([[10, 7, 4], [ 3, 2, 1]]) >>> np.percentile(a, 50) 3.5 >>> np.percentile(a, 50, axis=0) array([6.5, 4.5, 2.5]) >>> np.percentile(a, 50, axis=1) array([7., 2.]) >>> np.percentile(a, 50, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.percentile(a, 50, axis=0) >>> out = np.zeros_like(m) >>> np.percentile(a, 50, axis=0, out=out) array([6.5, 4.5, 2.5]) >>> m array([6.5, 4.5, 2.5]) >>> b = a.copy() >>> np.percentile(b, 50, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a == b) The different types of interpolation can be visualized graphically: .. plot:: import matplotlib.pyplot as plt a = np.arange(4) p = np.linspace(0, 100, 6001) ax = plt.gca() lines = [ ('linear', None), ('higher', '--'), ('lower', '--'), ('nearest', '-.'), ('midpoint', '-.'), ] for interpolation, style in lines: ax.plot( p, np.percentile(a, p, interpolation=interpolation), label=interpolation, linestyle=style) ax.set( title='Interpolation methods for list: ' + str(a), xlabel='Percentile', ylabel='List item returned', yticks=a) ax.legend() plt.show() " :arglists '[[& [args {:as kwargs}]]]} percentile (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "percentile")))) (def ^{:doc " Compute the qth quantile of the data along the specified axis, while ignoring nan values. Returns the qth quantile(s) of the array elements. .. versionadded:: 1.15.0 Parameters ---------- a : array_like Input array or object that can be converted to an array, containing nan values to be ignored q : array_like of float Quantile or sequence of quantiles to compute, which must be between 0 and 1 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the quantiles are computed. The default is to compute the quantile(s) along a flattened version of the array. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} This optional parameter specifies the interpolation method to use when the desired quantile lies between two data points ``i < j``: * linear: ``i + (j - i) * fraction``, where ``fraction`` is the fractional part of the index surrounded by ``i`` and ``j``. * lower: ``i``. * higher: ``j``. * nearest: ``i`` or ``j``, whichever is nearest. * midpoint: ``(i + j) / 2``. 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 array `a`. If this is anything but the default value it will be passed through (in the special case of an empty array) to the `mean` function of the underlying array. If the array is a sub-class and `mean` does not have the kwarg `keepdims` this will raise a RuntimeError. Returns ------- quantile : scalar or ndarray If `q` is a single percentile and `axis=None`, then the result is a scalar. If multiple quantiles are given, first axis of the result corresponds to the quantiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- quantile nanmean, nanmedian nanmedian : equivalent to ``nanquantile(..., 0.5)`` nanpercentile : same as nanquantile, but with q in the range [0, 100]. Examples -------- >>> a = np.array([[10., 7., 4.], [3., 2., 1.]]) >>> a[0][1] = np.nan >>> a array([[10., nan, 4.], [ 3., 2., 1.]]) >>> np.quantile(a, 0.5) nan >>> np.nanquantile(a, 0.5) 3.0 >>> np.nanquantile(a, 0.5, axis=0) array([6.5, 2. , 2.5]) >>> np.nanquantile(a, 0.5, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.nanquantile(a, 0.5, axis=0) >>> out = np.zeros_like(m) >>> np.nanquantile(a, 0.5, axis=0, out=out) array([6.5, 2. , 2.5]) >>> m array([6.5, 2. , 2.5]) >>> b = a.copy() >>> np.nanquantile(b, 0.5, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) " :arglists '[[& [args {:as kwargs}]]]} nanquantile (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanquantile")))) (def ^{:doc "dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)"} typecodes (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* "typecodes")))) (def ^{:doc " Lower triangle of an array. Return a copy of an array with elements above the `k`-th diagonal zeroed. Parameters ---------- m : array_like, shape (M, N) Input array. k : int, optional Diagonal above which to zero elements. `k = 0` (the default) is the main diagonal, `k < 0` is below it and `k > 0` is above. Returns ------- tril : ndarray, shape (M, N) Lower triangle of `m`, of same shape and data-type as `m`. See Also -------- triu : same thing, only for the upper triangle Examples -------- >>> np.tril([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1) array([[ 0, 0, 0], [ 4, 0, 0], [ 7, 8, 0], [10, 11, 12]]) " :arglists '[[& [args {:as kwargs}]]]} tril (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tril")))) (def ^{:doc "sin(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Trigonometric sine, element-wise. Parameters ---------- x : array_like Angle, in radians (:math:`2 \\pi` rad equals 360 degrees). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : array_like The sine of each element of x. This is a scalar if `x` is a scalar. See Also -------- arcsin, sinh, cos Notes ----- The sine is one of the fundamental functions of trigonometry (the mathematical study of triangles). Consider a circle of radius 1 centered on the origin. A ray comes in from the :math:`+x` axis, makes an angle at the origin (measured counter-clockwise from that axis), and departs from the origin. The :math:`y` coordinate of the outgoing ray's intersection with the unit circle is the sine of that angle. It ranges from -1 for :math:`x=3\\pi / 2` to +1 for :math:`\\pi / 2.` The function has zeroes where the angle is a multiple of :math:`\\pi`. Sines of angles between :math:`\\pi` and :math:`2\\pi` are negative. The numerous properties of the sine and related functions are included in any standard trigonometry text. Examples -------- Print sine of one angle: >>> np.sin(np.pi/2.) 1.0 Print sines of an array of angles given in degrees: >>> np.sin(np.array((0., 30., 45., 60., 90.)) * np.pi / 180. ) array([ 0. , 0.5 , 0.70710678, 0.8660254 , 1. ]) Plot the sine function: >>> import matplotlib.pylab as plt >>> x = np.linspace(-np.pi, np.pi, 201) >>> plt.plot(x, np.sin(x)) >>> plt.xlabel('Angle [rad]') >>> plt.ylabel('sin(x)') >>> plt.axis('tight') >>> plt.show()" :arglists '[[self & [args {:as kwargs}]]]} sin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sin")))) (def ^{:doc " Flip array in the up/down direction. Flip the entries in each column in the up/down direction. Rows are preserved, but appear in a different order than before. Parameters ---------- m : array_like Input array. Returns ------- out : array_like A view of `m` with the rows reversed. Since a view is returned, this operation is :math:`\\mathcal O(1)`. See Also -------- fliplr : Flip array in the left/right direction. rot90 : Rotate array counterclockwise. Notes ----- Equivalent to ``m[::-1,...]``. Does not require the array to be two-dimensional. Examples -------- >>> A = np.diag([1.0, 2, 3]) >>> A array([[1., 0., 0.], [0., 2., 0.], [0., 0., 3.]]) >>> np.flipud(A) array([[0., 0., 3.], [0., 2., 0.], [1., 0., 0.]]) >>> A = np.random.randn(2,3,5) >>> np.all(np.flipud(A) == A[::-1,...]) True >>> np.flipud([1,2]) array([2, 1]) " :arglists '[[& [args {:as kwargs}]]]} flipud (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "flipud")))) (def ^{:doc "power(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) First array elements raised to powers from second array, element-wise. Raise each base in `x1` to the positionally-corresponding power in `x2`. `x1` and `x2` must be broadcastable to the same shape. Note that an integer type raised to a negative integer power will raise a ValueError. Parameters ---------- x1 : array_like The bases. x2 : array_like The exponents. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The bases in `x1` raised to the exponents in `x2`. This is a scalar if both `x1` and `x2` are scalars. See Also -------- float_power : power function that promotes integers to float Examples -------- Cube each element in an array. >>> x1 = np.arange(6) >>> x1 [0, 1, 2, 3, 4, 5] >>> np.power(x1, 3) array([ 0, 1, 8, 27, 64, 125]) Raise the bases to different exponents. >>> x2 = [1.0, 2.0, 3.0, 3.0, 2.0, 1.0] >>> np.power(x1, x2) array([ 0., 1., 8., 27., 16., 5.]) The effect of broadcasting. >>> x2 = np.array([[1, 2, 3, 3, 2, 1], [1, 2, 3, 3, 2, 1]]) >>> x2 array([[1, 2, 3, 3, 2, 1], [1, 2, 3, 3, 2, 1]]) >>> np.power(x1, x2) array([[ 0, 1, 8, 27, 16, 5], [ 0, 1, 8, 27, 16, 5]]) The ``**`` operator can be used as a shorthand for ``np.power`` on ndarrays. >>> x2 = np.array([1, 2, 3, 3, 2, 1]) >>> x1 = np.arange(6) >>> x1 ** x2 array([ 0, 1, 8, 27, 16, 5])" :arglists '[[self & [args {:as kwargs}]]]} power (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "power")))) (def ^{:doc ""} pi 3.141592653589793) (def ^{:doc " Pytest test running. This module implements the ``test()`` function for NumPy modules. The usual boiler plate for doing that is to put the following in the module ``__init__.py`` file:: from numpy._pytesttester import PytestTester test = PytestTester(__name__) del PytestTester Warnings filtering and other runtime settings should be dealt with in the ``pytest.ini`` file in the numpy repo root. The behavior of the test depends on whether or not that file is found as follows: * ``pytest.ini`` is present (develop mode) All warnings except those explicitly filtered out are raised as error. * ``pytest.ini`` is absent (release mode) DeprecationWarnings and PendingDeprecationWarnings are ignored, other warnings are passed through. In practice, tests run from the numpy repo are run in develop mode. That includes the standard ``python runtests.py`` invocation. This module is imported by every numpy subpackage, so lies at the top level to simplify circular import issues. For the same reason, it contains no numpy imports at module scope, instead importing numpy within function calls. "} _pytesttester (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "_pytesttester")))) (def ^{:doc "fabs(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the absolute values element-wise. This function returns the absolute values (positive magnitude) of the data in `x`. Complex values are not handled, use `absolute` to find the absolute values of complex data. Parameters ---------- x : array_like The array of numbers for which the absolute values are required. If `x` is a scalar, the result `y` will also be a scalar. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The absolute values of `x`, the returned values are always floats. This is a scalar if `x` is a scalar. See Also -------- absolute : Absolute values including `complex` types. Examples -------- >>> np.fabs(-1) 1.0 >>> np.fabs([-1.2, 1.2]) array([ 1.2, 1.2])" :arglists '[[self & [args {:as kwargs}]]]} fabs (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fabs")))) (def ^{:doc "gcd(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Returns the greatest common divisor of ``|x1|`` and ``|x2|`` Parameters ---------- x1, x2 : array_like, int Arrays of values. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). Returns ------- y : ndarray or scalar The greatest common divisor of the absolute value of the inputs This is a scalar if both `x1` and `x2` are scalars. See Also -------- lcm : The lowest common multiple Examples -------- >>> np.gcd(12, 20) 4 >>> np.gcd.reduce([15, 25, 35]) 5 >>> np.gcd(np.arange(6), 20) array([20, 1, 2, 1, 4, 5])" :arglists '[[self & [args {:as kwargs}]]]} gcd (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "gcd")))) (def ^{:doc "hypot(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Given the \"legs\" of a right triangle, return its hypotenuse. Equivalent to ``sqrt(x1**2 + x2**2)``, element-wise. If `x1` or `x2` is scalar_like (i.e., unambiguously cast-able to a scalar type), it is broadcast for use with each element of the other argument. (See Examples) Parameters ---------- x1, x2 : array_like Leg of the triangle(s). If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- z : ndarray The hypotenuse of the triangle(s). This is a scalar if both `x1` and `x2` are scalars. Examples -------- >>> np.hypot(3*np.ones((3, 3)), 4*np.ones((3, 3))) array([[ 5., 5., 5.], [ 5., 5., 5.], [ 5., 5., 5.]]) Example showing broadcast of scalar_like argument: >>> np.hypot(3*np.ones((3, 3)), [4]) array([[ 5., 5., 5.], [ 5., 5., 5.], [ 5., 5., 5.]])" :arglists '[[self & [args {:as kwargs}]]]} hypot (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "hypot")))) (def ^{:doc "A unicode string. When used in arrays, this type strips trailing null codepoints. Unlike the builtin `str`, this supports the :ref:`python:bufferobjects`, exposing its contents as UCS4: >>> m = memoryview(np.str_(\"abc\")) >>> m.format '3w' >>> m.tobytes() b'a\\x00\\x00\\x00b\\x00\\x00\\x00c\\x00\\x00\\x00' :Character code: ``'U'`` :Alias: `numpy.unicode_`" :arglists '[[self & [args {:as kwargs}]]]} unicode_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "unicode_")))) (def ^{:doc "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" :arglists '[[self & [args {:as kwargs}]]]} nested_iters (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nested_iters")))) (def ^{:doc "This module provides access to the mathematical functions defined by the C standard."} math (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "math")))) (def ^{:doc " ============= Masked Arrays ============= Arrays sometimes contain invalid or missing data. When doing operations on such arrays, we wish to suppress invalid values, which is the purpose masked arrays fulfill (an example of typical use is given below). For example, examine the following array: >>> x = np.array([2, 1, 3, np.nan, 5, 2, 3, np.nan]) When we try to calculate the mean of the data, the result is undetermined: >>> np.mean(x) nan The mean is calculated using roughly ``np.sum(x)/len(x)``, but since any number added to ``NaN`` [1]_ produces ``NaN``, this doesn't work. Enter masked arrays: >>> m = np.ma.masked_array(x, np.isnan(x)) >>> m masked_array(data = [2.0 1.0 3.0 -- 5.0 2.0 3.0 --], mask = [False False False True False False False True], fill_value=1e+20) Here, we construct a masked array that suppress all ``NaN`` values. We may now proceed to calculate the mean of the other values: >>> np.mean(m) 2.6666666666666665 .. [1] Not-a-Number, a floating point value that is the result of an invalid operation. .. moduleauthor:: Pierre Gerard-Marchant .. moduleauthor:: Jarrod Millman "} ma (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "ma")))) (def ^{:doc " Load ASCII data stored in a file and return it as a single array. .. deprecated:: 1.17 ndfromtxt` is a deprecated alias of `genfromtxt` which overwrites the ``usemask`` argument with `False` even when explicitly called as ``ndfromtxt(..., usemask=True)``. Use `genfromtxt` instead. Parameters ---------- fname, kwargs : For a description of input parameters, see `genfromtxt`. See Also -------- numpy.genfromtxt : generic function. " :arglists '[[fname & [{:as kwargs}]]]} ndfromtxt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ndfromtxt")))) (def ^{:doc "bitwise_and(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the bit-wise AND of two arrays element-wise. Computes the bit-wise AND of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``&``. Parameters ---------- x1, x2 : array_like Only integer and boolean types are handled. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Result. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logical_and bitwise_or bitwise_xor binary_repr : Return the binary representation of the input number as a string. Examples -------- The number 13 is represented by ``00001101``. Likewise, 17 is represented by ``00010001``. The bit-wise AND of 13 and 17 is therefore ``000000001``, or 1: >>> np.bitwise_and(13, 17) 1 >>> np.bitwise_and(14, 13) 12 >>> np.binary_repr(12) '1100' >>> np.bitwise_and([14,3], 13) array([12, 1]) >>> np.bitwise_and([11,7], [4,25]) array([0, 1]) >>> np.bitwise_and(np.array([2,5,255]), np.array([3,14,16])) array([ 2, 4, 16]) >>> np.bitwise_and([True, True], [False, True]) array([False, True]) The ``&`` operator can be used as a shorthand for ``np.bitwise_and`` on ndarrays. >>> x1 = np.array([2, 5, 255]) >>> x2 = np.array([3, 14, 16]) >>> x1 & x2 array([ 2, 4, 16])" :arglists '[[self & [args {:as kwargs}]]]} bitwise_and (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bitwise_and")))) (def ^{:doc "Complex number type composed of two double-precision floating-point numbers, compatible with Python `complex`. :Character code: ``'D'`` :Canonical name: `numpy.cdouble` :Alias: `numpy.cfloat` :Alias: `numpy.complex_` :Alias on this platform: `numpy.complex128`: Complex number type composed of 2 64-bit-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} cdouble (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cdouble")))) (def ^{:doc " Return the real part of the complex argument. Parameters ---------- val : array_like Input array. Returns ------- out : ndarray or scalar The real component of the complex argument. If `val` is real, the type of `val` is used for the output. If `val` has complex elements, the returned type is float. See Also -------- real_if_close, imag, angle Examples -------- >>> a = np.array([1+2j, 3+4j, 5+6j]) >>> a.real array([1., 3., 5.]) >>> a.real = 9 >>> a array([9.+2.j, 9.+4.j, 9.+6.j]) >>> a.real = np.array([9, 8, 7]) >>> a array([9.+2.j, 8.+4.j, 7.+6.j]) >>> np.real(1 + 1j) 1.0 " :arglists '[[& [args {:as kwargs}]]]} real (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "real")))) (def ^{:doc "fmin(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Element-wise minimum of array elements. Compare two arrays and returns a new array containing the element-wise minima. If one of the elements being compared is a NaN, then the non-nan element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are ignored when possible. Parameters ---------- x1, x2 : array_like The arrays holding the elements to be compared. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The minimum of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars. See Also -------- fmax : Element-wise maximum of two arrays, ignores NaNs. minimum : Element-wise minimum of two arrays, propagates NaNs. amin : The minimum value of an array along a given axis, propagates NaNs. nanmin : The minimum value of an array along a given axis, ignores NaNs. maximum, amax, nanmax Notes ----- .. versionadded:: 1.3.0 The fmin is equivalent to ``np.where(x1 <= x2, x1, x2)`` when neither x1 nor x2 are NaNs, but it is faster and does proper broadcasting. Examples -------- >>> np.fmin([2, 3, 4], [1, 5, 2]) array([1, 3, 2]) >>> np.fmin(np.eye(2), [0.5, 2]) array([[ 0.5, 0. ], [ 0. , 1. ]]) >>> np.fmin([np.nan, 0, np.nan],[0, np.nan, np.nan]) array([ 0., 0., nan])" :arglists '[[self & [args {:as kwargs}]]]} fmin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fmin")))) (def ^{:doc " Format a floating-point scalar as a decimal string in positional notation. Provides control over rounding, trimming and padding. Uses and assumes IEEE unbiased rounding. Uses the \"Dragon4\" algorithm. Parameters ---------- x : python float or numpy floating scalar Value to format. precision : non-negative integer or None, optional Maximum number of digits to print. May be None if `unique` is `True`, but must be an integer if unique is `False`. unique : boolean, optional If `True`, use a digit-generation strategy which gives the shortest representation which uniquely identifies the floating-point number from other values of the same type, by judicious rounding. If `precision` was omitted, print out all necessary digits, otherwise digit generation is cut off after `precision` digits and the remaining value is rounded. If `False`, digits are generated as if printing an infinite-precision value and stopping after `precision` digits, rounding the remaining value. fractional : boolean, optional If `True`, the cutoff of `precision` digits refers to the total number of digits after the decimal point, including leading zeros. If `False`, `precision` refers to the total number of significant digits, before or after the decimal point, ignoring leading zeros. trim : one of 'k', '.', '0', '-', optional Controls post-processing trimming of trailing digits, as follows: * 'k' : keep trailing zeros, keep decimal point (no trimming) * '.' : trim all trailing zeros, leave decimal point * '0' : trim all but the zero before the decimal point. Insert the zero if it is missing. * '-' : trim trailing zeros and any trailing decimal point sign : boolean, optional Whether to show the sign for positive values. pad_left : non-negative integer, optional Pad the left side of the string with whitespace until at least that many characters are to the left of the decimal point. pad_right : non-negative integer, optional Pad the right side of the string with whitespace until at least that many characters are to the right of the decimal point. Returns ------- rep : string The string representation of the floating point value See Also -------- format_float_scientific Examples -------- >>> np.format_float_positional(np.float32(np.pi)) '3.1415927' >>> np.format_float_positional(np.float16(np.pi)) '3.14' >>> np.format_float_positional(np.float16(0.3)) '0.3' >>> np.format_float_positional(np.float16(0.3), unique=False, precision=10) '0.3000488281' " :arglists '[[x & [{precision :precision, unique :unique, fractional :fractional, trim :trim, sign :sign, pad_left :pad_left, pad_right :pad_right}]] [x & [{precision :precision, unique :unique, fractional :fractional, trim :trim, sign :sign, pad_left :pad_left}]] [x & [{precision :precision, unique :unique, fractional :fractional, trim :trim, sign :sign}]] [x & [{precision :precision, unique :unique, fractional :fractional, trim :trim}]] [x & [{precision :precision, unique :unique, fractional :fractional}]] [x & [{precision :precision, unique :unique}]] [x & [{precision :precision}]] [x]]} format_float_positional (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "format_float_positional")))) (def ^{:doc "" :arglists '[[]]} __dir__ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "__dir__")))) (def ^{:doc " vectorize(pyfunc, otypes=None, doc=None, excluded=None, cache=False, signature=None) Generalized function class. Define a vectorized function which takes a nested sequence of objects or numpy arrays as inputs and returns a single numpy array or a tuple of numpy arrays. The vectorized function evaluates `pyfunc` over successive tuples of the input arrays like the python map function, except it uses the broadcasting rules of numpy. The data type of the output of `vectorized` is determined by calling the function with the first element of the input. This can be avoided by specifying the `otypes` argument. Parameters ---------- pyfunc : callable A python function or method. otypes : str or list of dtypes, optional The output data type. It must be specified as either a string of typecode characters or a list of data type specifiers. There should be one data type specifier for each output. doc : str, optional The docstring for the function. If None, the docstring will be the ``pyfunc.__doc__``. excluded : set, optional Set of strings or integers representing the positional or keyword arguments for which the function will not be vectorized. These will be passed directly to `pyfunc` unmodified. .. versionadded:: 1.7.0 cache : bool, optional If `True`, then cache the first function call that determines the number of outputs if `otypes` is not provided. .. versionadded:: 1.7.0 signature : string, optional Generalized universal function signature, e.g., ``(m,n),(n)->(m)`` for vectorized matrix-vector multiplication. If provided, ``pyfunc`` will be called with (and expected to return) arrays with shapes given by the size of corresponding core dimensions. By default, ``pyfunc`` is assumed to take scalars as input and output. .. versionadded:: 1.12.0 Returns ------- vectorized : callable Vectorized function. See Also -------- frompyfunc : Takes an arbitrary Python function and returns a ufunc Notes ----- The `vectorize` function is provided primarily for convenience, not for performance. The implementation is essentially a for loop. If `otypes` is not specified, then a call to the function with the first argument will be used to determine the number of outputs. The results of this call will be cached if `cache` is `True` to prevent calling the function twice. However, to implement the cache, the original function must be wrapped which will slow down subsequent calls, so only do this if your function is expensive. The new keyword argument interface and `excluded` argument support further degrades performance. References ---------- .. [1] :doc:`/reference/c-api/generalized-ufuncs` Examples -------- >>> def myfunc(a, b): ... \"Return a-b if a>b, otherwise return a+b\" ... if a > b: ... return a - b ... else: ... return a + b >>> vfunc = np.vectorize(myfunc) >>> vfunc([1, 2, 3, 4], 2) array([3, 4, 1, 2]) The docstring is taken from the input function to `vectorize` unless it is specified: >>> vfunc.__doc__ 'Return a-b if a>b, otherwise return a+b' >>> vfunc = np.vectorize(myfunc, doc='Vectorized `myfunc`') >>> vfunc.__doc__ 'Vectorized `myfunc`' The output type is determined by evaluating the first element of the input, unless it is specified: >>> out = vfunc([1, 2, 3, 4], 2) >>> type(out[0]) >>> vfunc = np.vectorize(myfunc, otypes=[float]) >>> out = vfunc([1, 2, 3, 4], 2) >>> type(out[0]) The `excluded` argument can be used to prevent vectorizing over certain arguments. This can be useful for array-like arguments of a fixed length such as the coefficients for a polynomial as in `polyval`: >>> def mypolyval(p, x): ... _p = list(p) ... res = _p.pop(0) ... while _p: ... res = res*x + _p.pop(0) ... return res >>> vpolyval = np.vectorize(mypolyval, excluded=['p']) >>> vpolyval(p=[1, 2, 3], x=[0, 1]) array([3, 6]) Positional arguments may also be excluded by specifying their position: >>> vpolyval.excluded.add(0) >>> vpolyval([1, 2, 3], x=[0, 1]) array([3, 6]) The `signature` argument allows for vectorizing functions that act on non-scalar arrays of fixed length. For example, you can use it for a vectorized calculation of Pearson correlation coefficient and its p-value: >>> import scipy.stats >>> pearsonr = np.vectorize(scipy.stats.pearsonr, ... signature='(n),(n)->(),()') >>> pearsonr([[0, 1, 2, 3]], [[1, 2, 3, 4], [4, 3, 2, 1]]) (array([ 1., -1.]), array([ 0., 0.])) Or for a vectorized convolution: >>> convolve = np.vectorize(np.convolve, signature='(n),(m)->(k)') >>> convolve(np.eye(4), [1, 2, 1]) array([[1., 2., 1., 0., 0., 0.], [0., 1., 2., 1., 0., 0.], [0., 0., 1., 2., 1., 0.], [0., 0., 0., 1., 2., 1.]]) " :arglists '[[self pyfunc & [{otypes :otypes, doc :doc, excluded :excluded, cache :cache, signature :signature}]] [self pyfunc & [{otypes :otypes, doc :doc, excluded :excluded, cache :cache}]] [self pyfunc & [{otypes :otypes, doc :doc, excluded :excluded}]] [self pyfunc & [{otypes :otypes, doc :doc}]] [self pyfunc & [{otypes :otypes}]] [self pyfunc]]} vectorize (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "vectorize")))) (def ^{:doc "radians(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Convert angles from degrees to radians. Parameters ---------- x : array_like Input array in degrees. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The corresponding radian values. This is a scalar if `x` is a scalar. See Also -------- deg2rad : equivalent function Examples -------- Convert a degree array to radians >>> deg = np.arange(12.) * 30. >>> np.radians(deg) array([ 0. , 0.52359878, 1.04719755, 1.57079633, 2.0943951 , 2.61799388, 3.14159265, 3.66519143, 4.1887902 , 4.71238898, 5.23598776, 5.75958653]) >>> out = np.zeros((deg.shape)) >>> ret = np.radians(deg, out) >>> ret is out True" :arglists '[[self & [args {:as kwargs}]]]} radians (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "radians")))) (def ^{:doc " Compute the histogram of a set of data. Parameters ---------- a : array_like Input data. The histogram is computed over the flattened array. bins : int or sequence of scalars or str, optional If `bins` is an int, it defines the number of equal-width bins in the given range (10, by default). If `bins` is a sequence, it defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths. .. versionadded:: 1.11.0 If `bins` is a string, it defines the method used to calculate the optimal bin width, as defined by `histogram_bin_edges`. range : (float, float), optional The lower and upper range of the bins. If not provided, range is simply ``(a.min(), a.max())``. Values outside the range are ignored. The first element of the range must be less than or equal to the second. `range` affects the automatic bin computation as well. While bin width is computed to be optimal based on the actual data within `range`, the bin count will fill the entire range including portions containing no data. normed : bool, optional .. deprecated:: 1.6.0 This is equivalent to the `density` argument, but produces incorrect results for unequal bin widths. It should not be used. .. versionchanged:: 1.15.0 DeprecationWarnings are actually emitted. weights : array_like, optional An array of weights, of the same shape as `a`. Each value in `a` only contributes its associated weight towards the bin count (instead of 1). If `density` is True, the weights are normalized, so that the integral of the density over the range remains 1. density : bool, optional If ``False``, the result will contain the number of samples in each bin. If ``True``, the result is the value of the probability *density* function at the bin, normalized such that the *integral* over the range is 1. Note that the sum of the histogram values will not be equal to 1 unless bins of unity width are chosen; it is not a probability *mass* function. Overrides the ``normed`` keyword if given. Returns ------- hist : array The values of the histogram. See `density` and `weights` for a description of the possible semantics. bin_edges : array of dtype float Return the bin edges ``(length(hist)+1)``. See Also -------- histogramdd, bincount, searchsorted, digitize, histogram_bin_edges Notes ----- All but the last (righthand-most) bin is half-open. In other words, if `bins` is:: [1, 2, 3, 4] then the first bin is ``[1, 2)`` (including 1, but excluding 2) and the second ``[2, 3)``. The last bin, however, is ``[3, 4]``, which *includes* 4. Examples -------- >>> np.histogram([1, 2, 1], bins=[0, 1, 2, 3]) (array([0, 2, 1]), array([0, 1, 2, 3])) >>> np.histogram(np.arange(4), bins=np.arange(5), density=True) (array([0.25, 0.25, 0.25, 0.25]), array([0, 1, 2, 3, 4])) >>> np.histogram([[1, 2, 1], [1, 0, 1]], bins=[0,1,2,3]) (array([1, 4, 1]), array([0, 1, 2, 3])) >>> a = np.arange(5) >>> hist, bin_edges = np.histogram(a, density=True) >>> hist array([0.5, 0. , 0.5, 0. , 0. , 0.5, 0. , 0.5, 0. , 0.5]) >>> hist.sum() 2.4999999999999996 >>> np.sum(hist * np.diff(bin_edges)) 1.0 .. versionadded:: 1.11.0 Automated Bin Selection Methods example, using 2 peak random data with 2000 points: >>> import matplotlib.pyplot as plt >>> rng = np.random.RandomState(10) # deterministic random data >>> a = np.hstack((rng.normal(size=1000), ... rng.normal(loc=5, scale=2, size=1000))) >>> _ = plt.hist(a, bins='auto') # arguments are passed to np.histogram >>> plt.title(\"Histogram with 'auto' bins\") Text(0.5, 1.0, \"Histogram with 'auto' bins\") >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} histogram (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "histogram")))) (def ^{:doc ""} UFUNC_PYVALS_NAME "UFUNC_PYVALS") (def ^{:doc " Check if the array is Fortran contiguous but *not* C contiguous. This function is obsolete and, because of changes due to relaxed stride checking, its return value for the same array may differ for versions of NumPy >= 1.10.0 and previous versions. If you only want to check if an array is Fortran contiguous use ``a.flags.f_contiguous`` instead. Parameters ---------- a : ndarray Input array. Returns ------- isfortran : bool Returns True if the array is Fortran contiguous but *not* C contiguous. Examples -------- np.array allows to specify whether the array is written in C-contiguous order (last index varies the fastest), or FORTRAN-contiguous order in memory (first index varies the fastest). >>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C') >>> a array([[1, 2, 3], [4, 5, 6]]) >>> np.isfortran(a) False >>> b = np.array([[1, 2, 3], [4, 5, 6]], order='F') >>> b array([[1, 2, 3], [4, 5, 6]]) >>> np.isfortran(b) True The transpose of a C-ordered array is a FORTRAN-ordered array. >>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C') >>> a array([[1, 2, 3], [4, 5, 6]]) >>> np.isfortran(a) False >>> b = a.T >>> b array([[1, 4], [2, 5], [3, 6]]) >>> np.isfortran(b) True C-ordered arrays evaluate as False even if they are also FORTRAN-ordered. >>> np.isfortran(np.array([1, 2], order='F')) False " :arglists '[[a]]} isfortran (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isfortran")))) (def ^{:doc "Half-precision floating-point number type. :Character code: ``'e'`` :Canonical name: `numpy.half` :Alias on this platform: `numpy.float16`: 16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa." :arglists '[[self & [args {:as kwargs}]]]} float16 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "float16")))) (def ^{:doc " Find indices where elements should be inserted to maintain order. Find the indices into a sorted array `a` such that, if the corresponding elements in `v` were inserted before the indices, the order of `a` would be preserved. Assuming that `a` is sorted: ====== ============================ `side` returned index `i` satisfies ====== ============================ left ``a[i-1] < v <= a[i]`` right ``a[i-1] <= v < a[i]`` ====== ============================ Parameters ---------- a : 1-D array_like Input array. If `sorter` is None, then it must be sorted in ascending order, otherwise `sorter` must be an array of indices that sort it. v : array_like Values to insert into `a`. side : {'left', 'right'}, optional If 'left', the index of the first suitable location found is given. If 'right', return the last such index. If there is no suitable index, return either 0 or N (where N is the length of `a`). sorter : 1-D array_like, optional Optional array of integer indices that sort array a into ascending order. They are typically the result of argsort. .. versionadded:: 1.7.0 Returns ------- indices : array of ints Array of insertion points with the same shape as `v`. See Also -------- sort : Return a sorted copy of an array. histogram : Produce histogram from 1-D data. Notes ----- Binary search is used to find the required insertion points. As of NumPy 1.4.0 `searchsorted` works with real/complex arrays containing `nan` values. The enhanced sort order is documented in `sort`. This function uses the same algorithm as the builtin python `bisect.bisect_left` (``side='left'``) and `bisect.bisect_right` (``side='right'``) functions, which is also vectorized in the `v` argument. Examples -------- >>> np.searchsorted([1,2,3,4,5], 3) 2 >>> np.searchsorted([1,2,3,4,5], 3, side='right') 3 >>> np.searchsorted([1,2,3,4,5], [-10, 10, 2, 3]) array([0, 5, 1, 2]) " :arglists '[[& [args {:as kwargs}]]]} searchsorted (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "searchsorted")))) (def ^{:doc "fromiter(iterable, dtype, count=-1, *, like=None) 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 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.])" :arglists '[[self & [args {:as kwargs}]]]} fromiter (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fromiter")))) (def ^{:doc "Abstract base class of all character string scalar types." :arglists '[[self & [args {:as kwargs}]]]} character (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "character")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned long``. :Character code: ``'L'`` :Canonical name: `numpy.uint` :Alias on this platform: `numpy.uint64`: 64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``). :Alias on this platform: `numpy.uintp`: Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``." :arglists '[[self & [args {:as kwargs}]]]} uint64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uint64")))) (def ^{:doc " Return a new array of given shape and type, filled with `fill_value`. Parameters ---------- shape : int or sequence of ints Shape of the new array, e.g., ``(2, 3)`` or ``2``. fill_value : scalar or array_like Fill value. dtype : data-type, optional The desired data-type for the array The default, None, means `np.array(fill_value).dtype`. order : {'C', 'F'}, optional Whether to store multidimensional data in C- or Fortran-contiguous (row- or column-wise) order in memory. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray Array of `fill_value` with the given shape, dtype, and order. See Also -------- 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. Examples -------- >>> np.full((2, 2), np.inf) array([[inf, inf], [inf, inf]]) >>> np.full((2, 2), 10) array([[10, 10], [10, 10]]) >>> np.full((2, 2), [1, 2]) array([[1, 2], [1, 2]]) " :arglists '[[shape fill_value & [{dtype :dtype, order :order, like :like}]] [shape fill_value & [{dtype :dtype, like :like}]] [shape fill_value & [{like :like}]]]} full (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "full")))) (def ^{:doc " Return the elements of an array that satisfy some condition. This is equivalent to ``np.compress(ravel(condition), ravel(arr))``. If `condition` is boolean ``np.extract`` is equivalent to ``arr[condition]``. Note that `place` does the exact opposite of `extract`. Parameters ---------- condition : array_like An array whose nonzero or True entries indicate the elements of `arr` to extract. arr : array_like Input array of the same size as `condition`. Returns ------- extract : ndarray Rank 1 array of values from `arr` where `condition` is True. See Also -------- take, put, copyto, compress, place Examples -------- >>> arr = np.arange(12).reshape((3, 4)) >>> arr array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]]) >>> condition = np.mod(arr, 3)==0 >>> condition array([[ True, False, False, True], [False, False, True, False], [False, True, False, False]]) >>> np.extract(condition, arr) array([0, 3, 6, 9]) If `condition` is boolean: >>> arr[condition] array([0, 3, 6, 9]) " :arglists '[[& [args {:as kwargs}]]]} extract (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "extract")))) (def ^{:doc " unravel_index(indices, shape, order='C') Converts a flat index or array of flat indices into a tuple of coordinate arrays. Parameters ---------- indices : array_like An integer array whose elements are indices into the flattened version of an array of dimensions ``shape``. Before version 1.6.0, this function accepted just one index value. shape : tuple of ints The shape of the array to use for unraveling ``indices``. .. versionchanged:: 1.16.0 Renamed from ``dims`` to ``shape``. order : {'C', 'F'}, optional Determines whether the indices should be viewed as indexing in row-major (C-style) or column-major (Fortran-style) order. .. versionadded:: 1.6.0 Returns ------- unraveled_coords : tuple of ndarray Each array in the tuple has the same shape as the ``indices`` array. See Also -------- ravel_multi_index Examples -------- >>> np.unravel_index([22, 41, 37], (7,6)) (array([3, 6, 6]), array([4, 5, 1])) >>> np.unravel_index([31, 41, 13], (7,6), order='F') (array([3, 6, 6]), array([4, 5, 1])) >>> np.unravel_index(1621, (6,7,8,9)) (3, 1, 4, 1) " :arglists '[[& [args {:as kwargs}]]]} unravel_index (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "unravel_index")))) (def ^{:doc " Return the Blackman window. The Blackman window is a taper formed by using the first three terms of a summation of cosines. It was designed to have close to the minimal leakage possible. It is close to optimal, only slightly worse than a Kaiser window. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : ndarray The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd). See Also -------- bartlett, hamming, hanning, kaiser Notes ----- The Blackman window is defined as .. math:: w(n) = 0.42 - 0.5 \\cos(2\\pi n/M) + 0.08 \\cos(4\\pi n/M) Most references to the Blackman window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means \"removing the foot\", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. It is known as a \"near optimal\" tapering function, almost as good (by some measures) as the kaiser window. References ---------- Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York. Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing. Upper Saddle River, NJ: Prentice-Hall, 1999, pp. 468-471. Examples -------- >>> import matplotlib.pyplot as plt >>> np.blackman(12) array([-1.38777878e-17, 3.26064346e-02, 1.59903635e-01, # may vary 4.14397981e-01, 7.36045180e-01, 9.67046769e-01, 9.67046769e-01, 7.36045180e-01, 4.14397981e-01, 1.59903635e-01, 3.26064346e-02, -1.38777878e-17]) Plot the window and the frequency response: >>> from numpy.fft import fft, fftshift >>> window = np.blackman(51) >>> plt.plot(window) [] >>> plt.title(\"Blackman window\") Text(0.5, 1.0, 'Blackman window') >>> plt.ylabel(\"Amplitude\") Text(0, 0.5, 'Amplitude') >>> plt.xlabel(\"Sample\") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure()
>>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 * np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [] >>> plt.title(\"Frequency response of Blackman window\") Text(0.5, 1.0, 'Frequency response of Blackman window') >>> plt.ylabel(\"Magnitude [dB]\") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel(\"Normalized frequency [cycles per sample]\") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> _ = plt.axis('tight') >>> plt.show() " :arglists '[[M]]} blackman (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "blackman")))) (def ^{:doc " This module contains a set of functions for vectorized string operations and methods. .. note:: The `chararray` class exists for backwards compatibility with Numarray, it is not recommended for new development. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of `dtype` `object_`, `string_` or `unicode_`, and use the free functions in the `numpy.char` module for fast vectorized string operations. Some methods will only be available if the corresponding string method is available in your version of Python. The preferred alias for `defchararray` is `numpy.char`. "} char (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "char")))) (def ^{:doc " Construct an array by repeating A the number of times given by reps. If `reps` has length ``d``, the result will have dimension of ``max(d, A.ndim)``. If ``A.ndim < d``, `A` is promoted to be d-dimensional by prepending new axes. So a shape (3,) array is promoted to (1, 3) for 2-D replication, or shape (1, 1, 3) for 3-D replication. If this is not the desired behavior, promote `A` to d-dimensions manually before calling this function. If ``A.ndim > d``, `reps` is promoted to `A`.ndim by pre-pending 1's to it. Thus for an `A` of shape (2, 3, 4, 5), a `reps` of (2, 2) is treated as (1, 1, 2, 2). Note : Although tile may be used for broadcasting, it is strongly recommended to use numpy's broadcasting operations and functions. Parameters ---------- A : array_like The input array. reps : array_like The number of repetitions of `A` along each axis. Returns ------- c : ndarray The tiled output array. See Also -------- repeat : Repeat elements of an array. broadcast_to : Broadcast an array to a new shape Examples -------- >>> a = np.array([0, 1, 2]) >>> np.tile(a, 2) array([0, 1, 2, 0, 1, 2]) >>> np.tile(a, (2, 2)) array([[0, 1, 2, 0, 1, 2], [0, 1, 2, 0, 1, 2]]) >>> np.tile(a, (2, 1, 2)) array([[[0, 1, 2, 0, 1, 2]], [[0, 1, 2, 0, 1, 2]]]) >>> b = np.array([[1, 2], [3, 4]]) >>> np.tile(b, 2) array([[1, 2, 1, 2], [3, 4, 3, 4]]) >>> np.tile(b, (2, 1)) array([[1, 2], [3, 4], [1, 2], [3, 4]]) >>> c = np.array([1,2,3,4]) >>> np.tile(c,(4,1)) array([[1, 2, 3, 4], [1, 2, 3, 4], [1, 2, 3, 4], [1, 2, 3, 4]]) " :arglists '[[& [args {:as kwargs}]]]} tile (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tile")))) (def ^{:doc "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 broadcast_shapes 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]])" :arglists '[[self & [args {:as kwargs}]]]} broadcast (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "broadcast")))) (def ^{:doc "Half-precision floating-point number type. :Character code: ``'e'`` :Canonical name: `numpy.half` :Alias on this platform: `numpy.float16`: 16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa." :arglists '[[self & [args {:as kwargs}]]]} half (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "half")))) (def ^{:doc " Find the set difference of two arrays. Return the unique values in `ar1` that are not in `ar2`. Parameters ---------- ar1 : array_like Input array. ar2 : array_like Input comparison array. assume_unique : bool If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. Returns ------- setdiff1d : ndarray 1D array of values in `ar1` that are not in `ar2`. The result is sorted when `assume_unique=False`, but otherwise only sorted if the input is sorted. See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- >>> a = np.array([1, 2, 3, 2, 4, 1]) >>> b = np.array([3, 4, 5, 6]) >>> np.setdiff1d(a, b) array([1, 2]) " :arglists '[[& [args {:as kwargs}]]]} setdiff1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "setdiff1d")))) (def ^{:doc "remainder(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return element-wise remainder of division. Computes the remainder complementary to the `floor_divide` function. It is equivalent to the Python modulus operator``x1 % x2`` and has the same sign as the divisor `x2`. The MATLAB function equivalent to ``np.remainder`` is ``mod``. .. warning:: This should not be confused with: * Python 3.7's `math.remainder` and C's ``remainder``, which computes the IEEE remainder, which are the complement to ``round(x1 / x2)``. * The MATLAB ``rem`` function and or the C ``%`` operator which is the complement to ``int(x1 / x2)``. Parameters ---------- x1 : array_like Dividend array. x2 : array_like Divisor array. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The element-wise remainder of the quotient ``floor_divide(x1, x2)``. This is a scalar if both `x1` and `x2` are scalars. See Also -------- floor_divide : Equivalent of Python ``//`` operator. divmod : Simultaneous floor division and remainder. fmod : Equivalent of the MATLAB ``rem`` function. divide, floor Notes ----- Returns 0 when `x2` is 0 and both `x1` and `x2` are (arrays of) integers. ``mod`` is an alias of ``remainder``. Examples -------- >>> np.remainder([4, 7], [2, 3]) array([0, 1]) >>> np.remainder(np.arange(7), 5) array([0, 1, 2, 3, 4, 0, 1]) The ``%`` operator can be used as a shorthand for ``np.remainder`` on ndarrays. >>> x1 = np.arange(7) >>> x1 % 5 array([0, 1, 2, 3, 4, 0, 1])" :arglists '[[self & [args {:as kwargs}]]]} remainder (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "remainder")))) (def ^{:doc ""} ALLOW_THREADS 1) (def ^{:doc "exp(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Calculate the exponential of all elements in the input array. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array, element-wise exponential of `x`. This is a scalar if `x` is a scalar. See Also -------- expm1 : Calculate ``exp(x) - 1`` for all elements in the array. exp2 : Calculate ``2**x`` for all elements in the array. Notes ----- The irrational number ``e`` is also known as Euler's number. It is approximately 2.718281, and is the base of the natural logarithm, ``ln`` (this means that, if :math:`x = \\ln y = \\log_e y`, then :math:`e^x = y`. For real input, ``exp(x)`` is always positive. For complex arguments, ``x = a + ib``, we can write :math:`e^x = e^a e^{ib}`. The first term, :math:`e^a`, is already known (it is the real argument, described above). The second term, :math:`e^{ib}`, is :math:`\\cos b + i \\sin b`, a function with magnitude 1 and a periodic phase. References ---------- .. [1] Wikipedia, \"Exponential function\", https://en.wikipedia.org/wiki/Exponential_function .. [2] M. Abramovitz and I. A. Stegun, \"Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables,\" Dover, 1964, p. 69, http://www.math.sfu.ca/~cbm/aands/page_69.htm Examples -------- Plot the magnitude and phase of ``exp(x)`` in the complex plane: >>> import matplotlib.pyplot as plt >>> x = np.linspace(-2*np.pi, 2*np.pi, 100) >>> xx = x + 1j * x[:, np.newaxis] # a + ib over complex plane >>> out = np.exp(xx) >>> plt.subplot(121) >>> plt.imshow(np.abs(out), ... extent=[-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi], cmap='gray') >>> plt.title('Magnitude of exp(x)') >>> plt.subplot(122) >>> plt.imshow(np.angle(out), ... extent=[-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi], cmap='hsv') >>> plt.title('Phase (angle) of exp(x)') >>> plt.show()" :arglists '[[self & [args {:as kwargs}]]]} exp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "exp")))) (def ^{:doc " Compute the outer product of two vectors. Given two vectors, ``a = [a0, a1, ..., aM]`` and ``b = [b0, b1, ..., bN]``, the outer product [1]_ is:: [[a0*b0 a0*b1 ... a0*bN ] [a1*b0 . [ ... . [aM*b0 aM*bN ]] Parameters ---------- a : (M,) array_like First input vector. Input is flattened if not already 1-dimensional. b : (N,) array_like Second input vector. Input is flattened if not already 1-dimensional. out : (M, N) ndarray, optional A location where the result is stored .. versionadded:: 1.9.0 Returns ------- out : (M, N) ndarray ``out[i, j] = a[i] * b[j]`` See also -------- inner einsum : ``einsum('i,j->ij', a.ravel(), b.ravel())`` is the equivalent. ufunc.outer : A generalization to dimensions other than 1D and other operations. ``np.multiply.outer(a.ravel(), b.ravel())`` is the equivalent. tensordot : ``np.tensordot(a.ravel(), b.ravel(), axes=((), ()))`` is the equivalent. References ---------- .. [1] : G. H. Golub and C. F. Van Loan, *Matrix Computations*, 3rd ed., Baltimore, MD, Johns Hopkins University Press, 1996, pg. 8. Examples -------- Make a (*very* coarse) grid for computing a Mandelbrot set: >>> rl = np.outer(np.ones((5,)), np.linspace(-2, 2, 5)) >>> rl array([[-2., -1., 0., 1., 2.], [-2., -1., 0., 1., 2.], [-2., -1., 0., 1., 2.], [-2., -1., 0., 1., 2.], [-2., -1., 0., 1., 2.]]) >>> im = np.outer(1j*np.linspace(2, -2, 5), np.ones((5,))) >>> im array([[0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j], [0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j], [0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j], [0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j], [0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j]]) >>> grid = rl + im >>> grid array([[-2.+2.j, -1.+2.j, 0.+2.j, 1.+2.j, 2.+2.j], [-2.+1.j, -1.+1.j, 0.+1.j, 1.+1.j, 2.+1.j], [-2.+0.j, -1.+0.j, 0.+0.j, 1.+0.j, 2.+0.j], [-2.-1.j, -1.-1.j, 0.-1.j, 1.-1.j, 2.-1.j], [-2.-2.j, -1.-2.j, 0.-2.j, 1.-2.j, 2.-2.j]]) An example using a \"vector\" of letters: >>> x = np.array(['a', 'b', 'c'], dtype=object) >>> np.outer(x, [1, 2, 3]) array([['a', 'aa', 'aaa'], ['b', 'bb', 'bbb'], ['c', 'cc', 'ccc']], dtype=object) " :arglists '[[& [args {:as kwargs}]]]} outer (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "outer")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned char``. :Character code: ``'B'`` :Canonical name: `numpy.ubyte` :Alias on this platform: `numpy.uint8`: 8-bit unsigned integer (``0`` to ``255``)." :arglists '[[self & [args {:as kwargs}]]]} uint8 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uint8")))) (def ^{:doc " View inputs as arrays with at least two dimensions. Parameters ---------- arys1, arys2, ... : array_like One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have two or more dimensions are preserved. Returns ------- res, res2, ... : ndarray An array, or list of arrays, each with ``a.ndim >= 2``. Copies are avoided where possible, and views with two or more dimensions are returned. See Also -------- atleast_1d, atleast_3d Examples -------- >>> np.atleast_2d(3.0) array([[3.]]) >>> x = np.arange(3.0) >>> np.atleast_2d(x) array([[0., 1., 2.]]) >>> np.atleast_2d(x).base is x True >>> np.atleast_2d(1, [1, 2], [[1, 2]]) [array([[1]]), array([[1, 2]]), array([[1, 2]])] " :arglists '[[& [args {:as kwargs}]]]} atleast_2d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "atleast_2d")))) (def ^{:doc ""} SHIFT_DIVIDEBYZERO 0) (def ^{:doc " lexsort(keys, axis=-1) Perform an indirect stable sort using a sequence of keys. Given multiple sorting keys, which can be interpreted as columns in a spreadsheet, lexsort returns an array of integer indices that describes the sort order by multiple columns. The last key in the sequence is used for the primary sort order, the second-to-last key for the secondary sort order, and so on. The keys argument must be a sequence of objects that can be converted to arrays of the same shape. If a 2D array is provided for the keys argument, its rows are interpreted as the sorting keys and sorting is according to the last row, second last row etc. Parameters ---------- keys : (k, N) array or tuple containing k (N,)-shaped sequences The `k` different \"columns\" to be sorted. The last column (or row if `keys` is a 2D array) is the primary sort key. axis : int, optional Axis to be indirectly sorted. By default, sort over the last axis. Returns ------- indices : (N,) ndarray of ints Array of indices that sort the keys along the specified axis. See Also -------- argsort : Indirect sort. ndarray.sort : In-place sort. sort : Return a sorted copy of an array. Examples -------- Sort names: first by surname, then by name. >>> surnames = ('Hertz', 'Galilei', 'Hertz') >>> first_names = ('Heinrich', 'Galileo', 'Gustav') >>> ind = np.lexsort((first_names, surnames)) >>> ind array([1, 2, 0]) >>> [surnames[i] + \", \" + first_names[i] for i in ind] ['Galilei, Galileo', 'Hertz, Gustav', 'Hertz, Heinrich'] Sort two columns of numbers: >>> a = [1,5,1,4,3,4,4] # First column >>> b = [9,4,0,4,0,2,1] # Second column >>> ind = np.lexsort((b,a)) # Sort by a, then by b >>> ind array([2, 0, 4, 6, 5, 3, 1]) >>> [(a[i],b[i]) for i in ind] [(1, 0), (1, 9), (3, 0), (4, 1), (4, 2), (4, 4), (5, 4)] Note that sorting is first according to the elements of ``a``. Secondary sorting is according to the elements of ``b``. A normal ``argsort`` would have yielded: >>> [(a[i],b[i]) for i in np.argsort(a)] [(1, 9), (1, 0), (3, 0), (4, 4), (4, 2), (4, 1), (5, 4)] Structured arrays are sorted lexically by ``argsort``: >>> x = np.array([(1,9), (5,4), (1,0), (4,4), (3,0), (4,2), (4,1)], ... dtype=np.dtype([('x', int), ('y', int)])) >>> np.argsort(x) # or np.argsort(x, order=('x', 'y')) array([2, 0, 4, 6, 5, 3, 1]) " :arglists '[[& [args {:as kwargs}]]]} lexsort (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "lexsort")))) (def ^{:doc "subtract(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Subtract arguments, element-wise. Parameters ---------- x1, x2 : array_like The arrays to be subtracted from each other. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The difference of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars. Notes ----- Equivalent to ``x1 - x2`` in terms of array broadcasting. Examples -------- >>> np.subtract(1.0, 4.0) -3.0 >>> x1 = np.arange(9.0).reshape((3, 3)) >>> x2 = np.arange(3.0) >>> np.subtract(x1, x2) array([[ 0., 0., 0.], [ 3., 3., 3.], [ 6., 6., 6.]]) The ``-`` operator can be used as a shorthand for ``np.subtract`` on ndarrays. >>> x1 = np.arange(9.0).reshape((3, 3)) >>> x2 = np.arange(3.0) >>> x1 - x2 array([[0., 0., 0.], [3., 3., 3.], [6., 6., 6.]])" :arglists '[[self & [args {:as kwargs}]]]} subtract (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "subtract")))) (def ^{:doc "dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)"} sctypeDict (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* "sctypeDict")))) (def ^{:doc ""} FPE_OVERFLOW 2) (def ^{:doc " Returns a bool array, where True if input element is real. If element has complex type with zero complex part, the return value for that element is True. Parameters ---------- x : array_like Input array. Returns ------- out : ndarray, bool Boolean array of same shape as `x`. See Also -------- iscomplex isrealobj : Return True if x is not a complex type. Examples -------- >>> np.isreal([1+1j, 1+0j, 4.5, 3, 2, 2j]) array([False, True, True, True, True, False]) " :arglists '[[& [args {:as kwargs}]]]} isreal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isreal")))) (def ^{:doc " Convert an array of size 1 to its scalar equivalent. .. deprecated:: 1.16 Deprecated, use `numpy.ndarray.item()` instead. Parameters ---------- a : ndarray Input array of size 1. Returns ------- out : scalar Scalar representation of `a`. The output data type is the same type returned by the input's `item` method. Examples -------- >>> np.asscalar(np.array([24])) 24 " :arglists '[[& [args {:as kwargs}]]]} asscalar (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "asscalar")))) (def ^{:doc " Return an array drawn from elements in choicelist, depending on conditions. Parameters ---------- condlist : list of bool ndarrays The list of conditions which determine from which array in `choicelist` the output elements are taken. When multiple conditions are satisfied, the first one encountered in `condlist` is used. choicelist : list of ndarrays The list of arrays from which the output elements are taken. It has to be of the same length as `condlist`. default : scalar, optional The element inserted in `output` when all conditions evaluate to False. Returns ------- output : ndarray The output at position m is the m-th element of the array in `choicelist` where the m-th element of the corresponding array in `condlist` is True. See Also -------- where : Return elements from one of two arrays depending on condition. take, choose, compress, diag, diagonal Examples -------- >>> x = np.arange(10) >>> condlist = [x<3, x>5] >>> choicelist = [x, x**2] >>> np.select(condlist, choicelist) array([ 0, 1, 2, ..., 49, 64, 81]) " :arglists '[[& [args {:as kwargs}]]]} select (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "select")))) (def ^{:doc " Return the identity array. The identity array is a square array with ones on the main diagonal. Parameters ---------- n : int Number of rows (and columns) in `n` x `n` output. dtype : data-type, optional Data-type of the output. Defaults to ``float``. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray `n` x `n` array with its main diagonal set to one, and all other elements 0. Examples -------- >>> np.identity(3) array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]) " :arglists '[[n & [{dtype :dtype, like :like}]] [n & [{like :like}]]]} identity (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "identity")))) (def ^{:doc " Get the current way of handling floating-point errors. Returns ------- res : dict A dictionary with keys \"divide\", \"over\", \"under\", and \"invalid\", whose values are from the strings \"ignore\", \"print\", \"log\", \"warn\", \"raise\", and \"call\". The keys represent possible floating-point exceptions, and the values define how these exceptions are handled. See Also -------- geterrcall, seterr, seterrcall Notes ----- For complete documentation of the types of floating-point exceptions and treatment options, see `seterr`. Examples -------- >>> from collections import OrderedDict >>> sorted(np.geterr().items()) [('divide', 'warn'), ('invalid', 'warn'), ('over', 'warn'), ('under', 'ignore')] >>> np.arange(3.) / np.arange(3.) array([nan, 1., 1.]) >>> oldsettings = np.seterr(all='warn', over='raise') >>> OrderedDict(sorted(np.geterr().items())) OrderedDict([('divide', 'warn'), ('invalid', 'warn'), ('over', 'raise'), ('under', 'warn')]) >>> np.arange(3.) / np.arange(3.) array([nan, 1., 1.]) " :arglists '[[]]} geterr (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "geterr")))) (def ^{:doc " Return a 2-D array with ones on the diagonal and zeros elsewhere. Parameters ---------- N : int Number of rows in the output. M : int, optional Number of columns in the output. If None, defaults to `N`. k : int, optional Index of the diagonal: 0 (the default) refers to the main diagonal, a positive value refers to an upper diagonal, and a negative value to a lower diagonal. dtype : data-type, optional Data-type of the returned array. order : {'C', 'F'}, optional Whether the output should be stored in row-major (C-style) or column-major (Fortran-style) order in memory. .. versionadded:: 1.14.0 like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- I : ndarray of shape (N,M) An array where all elements are equal to zero, except for the `k`-th diagonal, whose values are equal to one. See Also -------- identity : (almost) equivalent function diag : diagonal 2-D array from a 1-D array specified by the user. Examples -------- >>> np.eye(2, dtype=int) array([[1, 0], [0, 1]]) >>> np.eye(3, k=1) array([[0., 1., 0.], [0., 0., 1.], [0., 0., 0.]]) " :arglists '[[N & [{M :M, k :k, dtype :dtype, order :order, like :like}]] [N & [{M :M, k :k, dtype :dtype, like :like}]] [N & [{M :M, k :k, like :like}]] [N & [{M :M, like :like}]] [N & [{like :like}]]]} eye (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "eye")))) (def ^{:doc "heaviside(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the Heaviside step function. The Heaviside step function is defined as:: 0 if x1 < 0 heaviside(x1, x2) = x2 if x1 == 0 1 if x1 > 0 where `x2` is often taken to be 0.5, but 0 and 1 are also sometimes used. Parameters ---------- x1 : array_like Input values. x2 : array_like The value of the function when x1 is 0. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar The output array, element-wise Heaviside step function of `x1`. This is a scalar if both `x1` and `x2` are scalars. Notes ----- .. versionadded:: 1.13.0 References ---------- .. Wikipedia, \"Heaviside step function\", https://en.wikipedia.org/wiki/Heaviside_step_function Examples -------- >>> np.heaviside([-1.5, 0, 2.0], 0.5) array([ 0. , 0.5, 1. ]) >>> np.heaviside([-1.5, 0, 2.0], 1) array([ 0., 1., 1.])" :arglists '[[self & [args {:as kwargs}]]]} heaviside (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "heaviside")))) (def ^{:doc " busday_offset(dates, offsets, roll='raise', weekmask='1111100', holidays=None, busdaycal=None, out=None) First adjusts the date to fall on a valid day according to the ``roll`` rule, then applies offsets to the given dates counted in valid days. .. versionadded:: 1.7.0 Parameters ---------- dates : array_like of datetime64[D] The array of dates to process. offsets : array_like of int The array of offsets, which is broadcast with ``dates``. roll : {'raise', 'nat', 'forward', 'following', 'backward', 'preceding', 'modifiedfollowing', 'modifiedpreceding'}, optional How to treat dates that do not fall on a valid day. The default is 'raise'. * 'raise' means to raise an exception for an invalid day. * 'nat' means to return a NaT (not-a-time) for an invalid day. * 'forward' and 'following' mean to take the first valid day later in time. * 'backward' and 'preceding' mean to take the first valid day earlier in time. * 'modifiedfollowing' means to take the first valid day later in time unless it is across a Month boundary, in which case to take the first valid day earlier in time. * 'modifiedpreceding' means to take the first valid day earlier in time unless it is across a Month boundary, in which case to take the first valid day later in time. 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. They 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. busdaycal : busdaycalendar, optional A `busdaycalendar` object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided. out : array of datetime64[D], optional If provided, this array is filled with the result. Returns ------- out : array of datetime64[D] An array with a shape from broadcasting ``dates`` and ``offsets`` together, containing the dates with offsets applied. See Also -------- busdaycalendar: An object that specifies a custom set of valid days. is_busday : Returns a boolean array indicating valid days. busday_count : Counts how many valid days are in a half-open date range. Examples -------- >>> # First business day in October 2011 (not accounting for holidays) ... np.busday_offset('2011-10', 0, roll='forward') numpy.datetime64('2011-10-03') >>> # Last business day in February 2012 (not accounting for holidays) ... np.busday_offset('2012-03', -1, roll='forward') numpy.datetime64('2012-02-29') >>> # Third Wednesday in January 2011 ... np.busday_offset('2011-01', 2, roll='forward', weekmask='Wed') numpy.datetime64('2011-01-19') >>> # 2012 Mother's Day in Canada and the U.S. ... np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun') numpy.datetime64('2012-05-13') >>> # First business day on or after a date ... np.busday_offset('2011-03-20', 0, roll='forward') numpy.datetime64('2011-03-21') >>> np.busday_offset('2011-03-22', 0, roll='forward') numpy.datetime64('2011-03-22') >>> # First business day after a date ... np.busday_offset('2011-03-20', 1, roll='backward') numpy.datetime64('2011-03-21') >>> np.busday_offset('2011-03-22', 1, roll='backward') numpy.datetime64('2011-03-23') " :arglists '[[& [args {:as kwargs}]]]} busday_offset (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "busday_offset")))) (def ^{:doc "greater_equal(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the truth value of (x1 >= x2) element-wise. Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : bool or ndarray of bool Output array, element-wise comparison of `x1` and `x2`. Typically of type bool, unless ``dtype=object`` is passed. This is a scalar if both `x1` and `x2` are scalars. See Also -------- greater, less, less_equal, equal, not_equal Examples -------- >>> np.greater_equal([4, 2, 1], [2, 2, 2]) array([ True, True, False]) The ``>=`` operator can be used as a shorthand for ``np.greater_equal`` on ndarrays. >>> a = np.array([4, 2, 1]) >>> b = np.array([2, 2, 2]) >>> a >= b array([ True, True, False])" :arglists '[[self & [args {:as kwargs}]]]} greater_equal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "greater_equal")))) (def ^{:doc ""} ERR_IGNORE 0) (def ^{:doc "Signed integer type, compatible with C ``unsigned long long``. :Character code: ``'Q'``" :arglists '[[self & [args {:as kwargs}]]]} ulonglong (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ulonglong")))) (def ^{:doc "dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)"} typeDict (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* "typeDict")))) (def ^{:doc " Split an array into multiple sub-arrays as views into `ary`. Parameters ---------- ary : ndarray Array to be divided into sub-arrays. indices_or_sections : int or 1-D array If `indices_or_sections` is an integer, N, the array will be divided into N equal arrays along `axis`. If such a split is not possible, an error is raised. If `indices_or_sections` is a 1-D array of sorted integers, the entries indicate where along `axis` the array is split. For example, ``[2, 3]`` would, for ``axis=0``, result in - ary[:2] - ary[2:3] - ary[3:] If an index exceeds the dimension of the array along `axis`, an empty sub-array is returned correspondingly. axis : int, optional The axis along which to split, default is 0. Returns ------- sub-arrays : list of ndarrays A list of sub-arrays as views into `ary`. Raises ------ ValueError If `indices_or_sections` is given as an integer, but a split does not result in equal division. See Also -------- array_split : Split an array into multiple sub-arrays of equal or near-equal size. Does not raise an exception if an equal division cannot be made. hsplit : Split array into multiple sub-arrays horizontally (column-wise). vsplit : Split array into multiple sub-arrays vertically (row wise). dsplit : Split array into multiple sub-arrays along the 3rd axis (depth). concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. hstack : Stack arrays in sequence horizontally (column wise). vstack : Stack arrays in sequence vertically (row wise). dstack : Stack arrays in sequence depth wise (along third dimension). Examples -------- >>> x = np.arange(9.0) >>> np.split(x, 3) [array([0., 1., 2.]), array([3., 4., 5.]), array([6., 7., 8.])] >>> x = np.arange(8.0) >>> np.split(x, [3, 5, 6, 10]) [array([0., 1., 2.]), array([3., 4.]), array([5.]), array([6., 7.]), array([], dtype=float64)] " :arglists '[[& [args {:as kwargs}]]]} split (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "split")))) (def ^{:doc " Return an array converted to a float type. Parameters ---------- a : array_like The input array. dtype : str or dtype object, optional Float type code to coerce input array `a`. If `dtype` is one of the 'int' dtypes, it is replaced with float64. Returns ------- out : ndarray The input `a` as a float ndarray. Examples -------- >>> np.asfarray([2, 3]) array([2., 3.]) >>> np.asfarray([2, 3], dtype='float') array([2., 3.]) >>> np.asfarray([2, 3], dtype='int8') array([2., 3.]) " :arglists '[[& [args {:as kwargs}]]]} asfarray (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "asfarray")))) (def ^{:doc " Load ASCII data from a file and return it in a record array. If ``usemask=False`` a standard `recarray` is returned, if ``usemask=True`` a MaskedRecords array is returned. Parameters ---------- fname, kwargs : For a description of input parameters, see `genfromtxt`. See Also -------- numpy.genfromtxt : generic function Notes ----- By default, `dtype` is None, which means that the data-type of the output array will be determined from the data. " :arglists '[[fname & [{:as kwargs}]]]} recfromtxt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "recfromtxt")))) (def ^{:doc " empty_like(prototype, dtype=None, order='K', subok=True, shape=None) Return a new array with the same shape and type as a given array. Parameters ---------- prototype : array_like The shape and data-type of `prototype` define these same attributes of the returned array. dtype : data-type, optional Overrides the data type of the result. .. versionadded:: 1.6.0 order : {'C', 'F', 'A', or 'K'}, optional Overrides the memory layout of the result. 'C' means C-order, 'F' means F-order, 'A' means 'F' if `prototype` is Fortran contiguous, 'C' otherwise. 'K' means match the layout of `prototype` as closely as possible. .. versionadded:: 1.6.0 subok : bool, optional. If True, then the newly created array will use the sub-class type of `prototype`, otherwise it will be a base-class array. Defaults to True. shape : int or sequence of ints, optional. Overrides the shape of the result. If order='K' and the number of dimensions is unchanged, will try to keep order, otherwise, order='C' is implied. .. versionadded:: 1.17.0 Returns ------- out : ndarray Array of uninitialized (arbitrary) data with the same shape and type as `prototype`. See Also -------- 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. Notes ----- This function does *not* initialize the returned array; to do that use `zeros_like` or `ones_like` instead. It may be marginally faster than the functions that do set the array values. Examples -------- >>> a = ([1,2,3], [4,5,6]) # a is array-like >>> np.empty_like(a) array([[-1073741821, -1073741821, 3], # uninitialized [ 0, 0, -1073741821]]) >>> a = np.array([[1., 2., 3.],[4.,5.,6.]]) >>> np.empty_like(a) array([[ -2.00000715e+000, 1.48219694e-323, -2.00000572e+000], # uninitialized [ 4.38791518e-305, -2.00000715e+000, 4.17269252e-309]]) " :arglists '[[& [args {:as kwargs}]]]} empty_like (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "empty_like")))) (def ^{:doc "log10(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the base 10 logarithm of the input array, element-wise. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The logarithm to the base 10 of `x`, element-wise. NaNs are returned where x is negative. This is a scalar if `x` is a scalar. See Also -------- emath.log10 Notes ----- Logarithm is a multivalued function: for each `x` there is an infinite number of `z` such that `10**z = x`. The convention is to return the `z` whose imaginary part lies in `[-pi, pi]`. For real-valued input data types, `log10` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `log10` is a complex analytical function that has a branch cut `[-inf, 0]` and is continuous from above on it. `log10` handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard. References ---------- .. [1] M. Abramowitz and I.A. Stegun, \"Handbook of Mathematical Functions\", 10th printing, 1964, pp. 67. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, \"Logarithm\". https://en.wikipedia.org/wiki/Logarithm Examples -------- >>> np.log10([1e-15, -3.]) array([-15., nan])" :arglists '[[self & [args {:as kwargs}]]]} log10 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "log10")))) (def ^{:doc " Return the indices to access (n, n) arrays, given a masking function. Assume `mask_func` is a function that, for a square array a of size ``(n, n)`` with a possible offset argument `k`, when called as ``mask_func(a, k)`` returns a new array with zeros in certain locations (functions like `triu` or `tril` do precisely this). Then this function returns the indices where the non-zero values would be located. Parameters ---------- n : int The returned indices will be valid to access arrays of shape (n, n). mask_func : callable A function whose call signature is similar to that of `triu`, `tril`. That is, ``mask_func(x, k)`` returns a boolean array, shaped like `x`. `k` is an optional argument to the function. k : scalar An optional argument which is passed through to `mask_func`. Functions like `triu`, `tril` take a second argument that is interpreted as an offset. Returns ------- indices : tuple of arrays. The `n` arrays of indices corresponding to the locations where ``mask_func(np.ones((n, n)), k)`` is True. See Also -------- triu, tril, triu_indices, tril_indices Notes ----- .. versionadded:: 1.4.0 Examples -------- These are the indices that would allow you to access the upper triangular part of any 3x3 array: >>> iu = np.mask_indices(3, np.triu) For example, if `a` is a 3x3 array: >>> a = np.arange(9).reshape(3, 3) >>> a array([[0, 1, 2], [3, 4, 5], [6, 7, 8]]) >>> a[iu] array([0, 1, 2, 4, 5, 8]) An offset can be passed also to the masking function. This gets us the indices starting on the first diagonal right of the main one: >>> iu1 = np.mask_indices(3, np.triu, 1) with which we now extract only three elements: >>> a[iu1] array([1, 2, 5]) " :arglists '[[n mask_func & [{k :k}]] [n mask_func]]} mask_indices (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "mask_indices")))) (def ^{:doc "A unicode string. When used in arrays, this type strips trailing null codepoints. Unlike the builtin `str`, this supports the :ref:`python:bufferobjects`, exposing its contents as UCS4: >>> m = memoryview(np.str_(\"abc\")) >>> m.format '3w' >>> m.tobytes() b'a\\x00\\x00\\x00b\\x00\\x00\\x00c\\x00\\x00\\x00' :Character code: ``'U'`` :Alias: `numpy.unicode_`" :arglists '[[self & [args {:as kwargs}]]]} str0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "str0")))) (def ^{:doc "Abstract base class of all numeric scalar types." :arglists '[[self & [args {:as kwargs}]]]} number (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "number")))) (def ^{:doc " Return the indices of the maximum values in the specified axis ignoring NaNs. For all-NaN slices ``ValueError`` is raised. Warning: the results cannot be trusted if a slice contains only NaNs and -Infs. Parameters ---------- a : array_like Input data. axis : int, optional Axis along which to operate. By default flattened input is used. Returns ------- index_array : ndarray An array of indices or a single index value. See Also -------- argmax, nanargmin Examples -------- >>> a = np.array([[np.nan, 4], [2, 3]]) >>> np.argmax(a) 0 >>> np.nanargmax(a) 1 >>> np.nanargmax(a, axis=0) array([1, 0]) >>> np.nanargmax(a, axis=1) array([1, 1]) " :arglists '[[& [args {:as kwargs}]]]} nanargmax (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanargmax")))) (def ^{:doc " Return the normalized sinc function. The sinc function is :math:`\\sin(\\pi x)/(\\pi x)`. .. note:: Note the normalization factor of ``pi`` used in the definition. This is the most commonly used definition in signal processing. Use ``sinc(x / np.pi)`` to obtain the unnormalized sinc function :math:`\\sin(x)/(x)` that is more common in mathematics. Parameters ---------- x : ndarray Array (possibly multi-dimensional) of values for which to to calculate ``sinc(x)``. Returns ------- out : ndarray ``sinc(x)``, which has the same shape as the input. Notes ----- ``sinc(0)`` is the limit value 1. The name sinc is short for \"sine cardinal\" or \"sinus cardinalis\". The sinc function is used in various signal processing applications, including in anti-aliasing, in the construction of a Lanczos resampling filter, and in interpolation. For bandlimited interpolation of discrete-time signals, the ideal interpolation kernel is proportional to the sinc function. References ---------- .. [1] Weisstein, Eric W. \"Sinc Function.\" From MathWorld--A Wolfram Web Resource. http://mathworld.wolfram.com/SincFunction.html .. [2] Wikipedia, \"Sinc function\", https://en.wikipedia.org/wiki/Sinc_function Examples -------- >>> import matplotlib.pyplot as plt >>> x = np.linspace(-4, 4, 41) >>> np.sinc(x) array([-3.89804309e-17, -4.92362781e-02, -8.40918587e-02, # may vary -8.90384387e-02, -5.84680802e-02, 3.89804309e-17, 6.68206631e-02, 1.16434881e-01, 1.26137788e-01, 8.50444803e-02, -3.89804309e-17, -1.03943254e-01, -1.89206682e-01, -2.16236208e-01, -1.55914881e-01, 3.89804309e-17, 2.33872321e-01, 5.04551152e-01, 7.56826729e-01, 9.35489284e-01, 1.00000000e+00, 9.35489284e-01, 7.56826729e-01, 5.04551152e-01, 2.33872321e-01, 3.89804309e-17, -1.55914881e-01, -2.16236208e-01, -1.89206682e-01, -1.03943254e-01, -3.89804309e-17, 8.50444803e-02, 1.26137788e-01, 1.16434881e-01, 6.68206631e-02, 3.89804309e-17, -5.84680802e-02, -8.90384387e-02, -8.40918587e-02, -4.92362781e-02, -3.89804309e-17]) >>> plt.plot(x, np.sinc(x)) [] >>> plt.title(\"Sinc Function\") Text(0.5, 1.0, 'Sinc Function') >>> plt.ylabel(\"Amplitude\") Text(0, 0.5, 'Amplitude') >>> plt.xlabel(\"X\") Text(0.5, 0, 'X') >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} sinc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sinc")))) (def ^{:doc "fmax(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Element-wise maximum of array elements. Compare two arrays and returns a new array containing the element-wise maxima. If one of the elements being compared is a NaN, then the non-nan element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are ignored when possible. Parameters ---------- x1, x2 : array_like The arrays holding the elements to be compared. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The maximum of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars. See Also -------- fmin : Element-wise minimum of two arrays, ignores NaNs. maximum : Element-wise maximum of two arrays, propagates NaNs. amax : The maximum value of an array along a given axis, propagates NaNs. nanmax : The maximum value of an array along a given axis, ignores NaNs. minimum, amin, nanmin Notes ----- .. versionadded:: 1.3.0 The fmax is equivalent to ``np.where(x1 >= x2, x1, x2)`` when neither x1 nor x2 are NaNs, but it is faster and does proper broadcasting. Examples -------- >>> np.fmax([2, 3, 4], [1, 5, 2]) array([ 2., 5., 4.]) >>> np.fmax(np.eye(2), [0.5, 2]) array([[ 1. , 2. ], [ 0.5, 2. ]]) >>> np.fmax([np.nan, 0, np.nan],[0, np.nan, np.nan]) array([ 0., 0., nan])" :arglists '[[self & [args {:as kwargs}]]]} fmax (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fmax")))) (def ^{:doc "Return a contiguous flattened array. A 1-D array, containing the elements of the input, is returned. A copy is made only if needed. As of NumPy 1.10, the returned array will have the same type as the input array. (for example, a masked array will be returned for a masked array input) Parameters ---------- a : array_like Input array. The elements in `a` are read in the order specified by `order`, and packed as a 1-D array. order : {'C','F', 'A', 'K'}, optional The elements of `a` are read using this index order. 'C' means to index the elements in row-major, C-style order, with the last axis index changing fastest, back to the first axis index changing slowest. 'F' means to index the elements in column-major, Fortran-style order, with the first index changing fastest, and the last index changing slowest. Note that the 'C' and 'F' options take no account of the memory layout of the underlying array, and only refer to the order of axis indexing. 'A' means to read the elements in Fortran-like index order if `a` is Fortran *contiguous* in memory, C-like order otherwise. 'K' means to read the elements in the order they occur in memory, except for reversing the data when strides are negative. By default, 'C' index order is used. Returns ------- y : array_like y is an array of the same subtype as `a`, with shape ``(a.size,)``. Note that matrices are special cased for backward compatibility, if `a` is a matrix, then y is a 1-D ndarray. See Also -------- ndarray.flat : 1-D iterator over an array. ndarray.flatten : 1-D array copy of the elements of an array in row-major order. ndarray.reshape : Change the shape of an array without changing its data. Notes ----- In row-major, C-style order, in two dimensions, the row index varies the slowest, and the column index the quickest. This can be generalized to multiple dimensions, where row-major order implies that the index along the first axis varies slowest, and the index along the last quickest. The opposite holds for column-major, Fortran-style index ordering. When a view is desired in as many cases as possible, ``arr.reshape(-1)`` may be preferable. Examples -------- It is equivalent to ``reshape(-1, order=order)``. >>> x = np.array([[1, 2, 3], [4, 5, 6]]) >>> np.ravel(x) array([1, 2, 3, 4, 5, 6]) >>> x.reshape(-1) array([1, 2, 3, 4, 5, 6]) >>> np.ravel(x, order='F') array([1, 4, 2, 5, 3, 6]) When ``order`` is 'A', it will preserve the array's 'C' or 'F' ordering: >>> np.ravel(x.T) array([1, 4, 2, 5, 3, 6]) >>> np.ravel(x.T, order='A') array([1, 2, 3, 4, 5, 6]) When ``order`` is 'K', it will preserve orderings that are neither 'C' nor 'F', but won't reverse axes: >>> a = np.arange(3)[::-1]; a array([2, 1, 0]) >>> a.ravel(order='C') array([2, 1, 0]) >>> a.ravel(order='K') array([2, 1, 0]) >>> a = np.arange(12).reshape(2,3,2).swapaxes(1,2); a array([[[ 0, 2, 4], [ 1, 3, 5]], [[ 6, 8, 10], [ 7, 9, 11]]]) >>> a.ravel(order='C') array([ 0, 2, 4, 1, 3, 5, 6, 8, 10, 7, 9, 11]) >>> a.ravel(order='K') array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]) " :arglists '[[& [args {:as kwargs}]]]} ravel (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ravel")))) (def ^{:doc " Cross-correlation of two 1-dimensional sequences. This function computes the correlation as generally defined in signal processing texts:: c_{av}[k] = sum_n a[n+k] * conj(v[n]) with a and v sequences being zero-padded where necessary and conj being the conjugate. Parameters ---------- a, v : array_like Input sequences. mode : {'valid', 'same', 'full'}, optional Refer to the `convolve` docstring. Note that the default is 'valid', unlike `convolve`, which uses 'full'. old_behavior : bool `old_behavior` was removed in NumPy 1.10. If you need the old behavior, use `multiarray.correlate`. Returns ------- out : ndarray Discrete cross-correlation of `a` and `v`. See Also -------- convolve : Discrete, linear convolution of two one-dimensional sequences. multiarray.correlate : Old, no conjugate, version of correlate. Notes ----- The definition of correlation above is not unique and sometimes correlation may be defined differently. Another common definition is:: c'_{av}[k] = sum_n a[n] conj(v[n+k]) which is related to ``c_{av}[k]`` by ``c'_{av}[k] = c_{av}[-k]``. Examples -------- >>> np.correlate([1, 2, 3], [0, 1, 0.5]) array([3.5]) >>> np.correlate([1, 2, 3], [0, 1, 0.5], \"same\") array([2. , 3.5, 3. ]) >>> np.correlate([1, 2, 3], [0, 1, 0.5], \"full\") array([0.5, 2. , 3.5, 3. , 0. ]) Using complex sequences: >>> np.correlate([1+1j, 2, 3-1j], [0, 1, 0.5j], 'full') array([ 0.5-0.5j, 1.0+0.j , 1.5-1.5j, 3.0-1.j , 0.0+0.j ]) Note that you get the time reversed, complex conjugated result when the two input sequences change places, i.e., ``c_{va}[k] = c^{*}_{av}[-k]``: >>> np.correlate([0, 1, 0.5j], [1+1j, 2, 3-1j], 'full') array([ 0.0+0.j , 3.0+1.j , 1.5+1.5j, 1.0+0.j , 0.5+0.5j]) " :arglists '[[& [args {:as kwargs}]]]} correlate (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "correlate")))) (def ^{:doc " Return minimum of an array or minimum along an axis, ignoring any NaNs. When all-NaN slices are encountered a ``RuntimeWarning`` is raised and Nan is returned for that slice. Parameters ---------- a : array_like Array containing numbers whose minimum is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the minimum is computed. The default is to compute the minimum of the flattened array. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. .. versionadded:: 1.8.0 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 `a`. If the value is anything but the default, then `keepdims` will be passed through to the `min` method of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. .. versionadded:: 1.8.0 Returns ------- nanmin : ndarray An array with the same shape as `a`, with the specified axis removed. If `a` is a 0-d array, or if axis is None, an ndarray scalar is returned. The same dtype as `a` is returned. See Also -------- nanmax : The maximum value of an array along a given axis, ignoring any NaNs. amin : The minimum value of an array along a given axis, propagating any NaNs. fmin : Element-wise minimum of two arrays, ignoring any NaNs. minimum : Element-wise minimum of two arrays, propagating any NaNs. isnan : Shows which elements are Not a Number (NaN). isfinite: Shows which elements are neither NaN nor infinity. amax, fmax, maximum Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Positive infinity is treated as a very large number and negative infinity is treated as a very small (i.e. negative) number. If the input has a integer type the function is equivalent to np.min. Examples -------- >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nanmin(a) 1.0 >>> np.nanmin(a, axis=0) array([1., 2.]) >>> np.nanmin(a, axis=1) array([1., 3.]) When positive infinity and negative infinity are present: >>> np.nanmin([1, 2, np.nan, np.inf]) 1.0 >>> np.nanmin([1, 2, np.nan, np.NINF]) -inf " :arglists '[[& [args {:as kwargs}]]]} nanmin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanmin")))) (def ^{:doc " Find the sum of two polynomials. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. Returns the polynomial resulting from the sum of two input polynomials. Each input must be either a poly1d object or a 1D sequence of polynomial coefficients, from highest to lowest degree. Parameters ---------- a1, a2 : array_like or poly1d object Input polynomials. Returns ------- out : ndarray or poly1d object The sum of the inputs. If either input is a poly1d object, then the output is also a poly1d object. Otherwise, it is a 1D array of polynomial coefficients from highest to lowest degree. See Also -------- poly1d : A one-dimensional polynomial class. poly, polyadd, polyder, polydiv, polyfit, polyint, polysub, polyval Examples -------- >>> np.polyadd([1, 2], [9, 5, 4]) array([9, 6, 6]) Using poly1d objects: >>> p1 = np.poly1d([1, 2]) >>> p2 = np.poly1d([9, 5, 4]) >>> print(p1) 1 x + 2 >>> print(p2) 2 9 x + 5 x + 4 >>> print(np.polyadd(p1, p2)) 2 9 x + 6 x + 6 " :arglists '[[& [args {:as kwargs}]]]} polyadd (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polyadd")))) (def ^{:doc "The specification for a module, used for loading. A module's spec is the source for information about the module. For data associated with the module, including source, use the spec's loader. `name` is the absolute name of the module. `loader` is the loader to use when loading the module. `parent` is the name of the package the module is in. The parent is derived from the name. `is_package` determines if the module is considered a package or not. On modules this is reflected by the `__path__` attribute. `origin` is the specific location used by the loader from which to load the module, if that information is available. When filename is set, origin will match. `has_location` indicates that a spec's \"origin\" reflects a location. When this is True, `__file__` attribute of the module is set. `cached` is the location of the cached bytecode file, if any. It corresponds to the `__cached__` attribute. `submodule_search_locations` is the sequence of path entries to search when importing submodules. If set, is_package should be True--and False otherwise. Packages are simply modules that (may) have submodules. If a spec has a non-None value in `submodule_search_locations`, the import system will consider modules loaded from the spec as packages. Only finders (see importlib.abc.MetaPathFinder and importlib.abc.PathEntryFinder) should modify ModuleSpec instances. "} __spec__ (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "__spec__")))) (def ^{:doc "arcsinh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Inverse hyperbolic sine element-wise. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Array of the same shape as `x`. This is a scalar if `x` is a scalar. Notes ----- `arcsinh` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `sinh(z) = x`. The convention is to return the `z` whose imaginary part lies in `[-pi/2, pi/2]`. For real-valued input data types, `arcsinh` always returns real output. For each value that cannot be expressed as a real number or infinity, it returns ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `arccos` is a complex analytical function that has branch cuts `[1j, infj]` and `[-1j, -infj]` and is continuous from the right on the former and from the left on the latter. The inverse hyperbolic sine is also known as `asinh` or ``sinh^-1``. References ---------- .. [1] M. Abramowitz and I.A. Stegun, \"Handbook of Mathematical Functions\", 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, \"Inverse hyperbolic function\", https://en.wikipedia.org/wiki/Arcsinh Examples -------- >>> np.arcsinh(np.array([np.e, 10.0])) array([ 1.72538256, 2.99822295])" :arglists '[[self & [args {:as kwargs}]]]} arcsinh (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arcsinh")))) (def ^{:doc " A nicer way to build up index tuples for arrays. .. note:: Use one of the two predefined instances `index_exp` or `s_` rather than directly using `IndexExpression`. For any index combination, including slicing and axis insertion, ``a[indices]`` is the same as ``a[np.index_exp[indices]]`` for any array `a`. However, ``np.index_exp[indices]`` can be used anywhere in Python code and returns a tuple of slice objects that can be used in the construction of complex index expressions. Parameters ---------- maketuple : bool If True, always returns a tuple. See Also -------- index_exp : Predefined instance that always returns a tuple: `index_exp = IndexExpression(maketuple=True)`. s_ : Predefined instance without tuple conversion: `s_ = IndexExpression(maketuple=False)`. Notes ----- You can do all this with `slice()` plus a few special objects, but there's a lot to remember and this version is simpler because it uses the standard array indexing syntax. Examples -------- >>> np.s_[2::2] slice(2, None, 2) >>> np.index_exp[2::2] (slice(2, None, 2),) >>> np.array([0, 1, 2, 3, 4])[np.s_[2::2]] array([2, 4]) "} index_exp (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "index_exp")))) (def ^{:doc " The warning raised when casting a complex dtype to a real dtype. As implemented, casting a complex number to a real discards its imaginary part, but this behavior may not be what the user actually wants. " :arglists '[[self & [args {:as kwargs}]]]} ComplexWarning (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ComplexWarning")))) (def ^{:doc " Determines whether the given object represents a scalar data-type. Parameters ---------- rep : any If `rep` is an instance of a scalar dtype, True is returned. If not, False is returned. Returns ------- out : bool Boolean result of check whether `rep` is a scalar dtype. See Also -------- issubsctype, issubdtype, obj2sctype, sctype2char Examples -------- >>> np.issctype(np.int32) True >>> np.issctype(list) False >>> np.issctype(1.1) False Strings are also a scalar type: >>> np.issctype(np.dtype('str')) True " :arglists '[[rep]]} issctype (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "issctype")))) (def ^{:doc "sqrt(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the non-negative square-root of an array, element-wise. Parameters ---------- x : array_like The values whose square-roots are required. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray An array of the same shape as `x`, containing the positive square-root of each element in `x`. If any element in `x` is complex, a complex array is returned (and the square-roots of negative reals are calculated). If all of the elements in `x` are real, so is `y`, with negative elements returning ``nan``. If `out` was provided, `y` is a reference to it. This is a scalar if `x` is a scalar. See Also -------- lib.scimath.sqrt A version which returns complex numbers when given negative reals. Notes ----- *sqrt* has--consistent with common convention--as its branch cut the real \"interval\" [`-inf`, 0), and is continuous from above on it. A branch cut is a curve in the complex plane across which a given complex function fails to be continuous. Examples -------- >>> np.sqrt([1,4,9]) array([ 1., 2., 3.]) >>> np.sqrt([4, -1, -3+4J]) array([ 2.+0.j, 0.+1.j, 1.+2.j]) >>> np.sqrt([4, -1, np.inf]) array([ 2., nan, inf])" :arglists '[[self & [args {:as kwargs}]]]} sqrt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sqrt")))) (def ^{:doc " Find the product of two polynomials. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. Finds the polynomial resulting from the multiplication of the two input polynomials. Each input must be either a poly1d object or a 1D sequence of polynomial coefficients, from highest to lowest degree. Parameters ---------- a1, a2 : array_like or poly1d object Input polynomials. Returns ------- out : ndarray or poly1d object The polynomial resulting from the multiplication of the inputs. If either inputs is a poly1d object, then the output is also a poly1d object. Otherwise, it is a 1D array of polynomial coefficients from highest to lowest degree. See Also -------- poly1d : A one-dimensional polynomial class. poly, polyadd, polyder, polydiv, polyfit, polyint, polysub, polyval convolve : Array convolution. Same output as polymul, but has parameter for overlap mode. Examples -------- >>> np.polymul([1, 2, 3], [9, 5, 1]) array([ 9, 23, 38, 17, 3]) Using poly1d objects: >>> p1 = np.poly1d([1, 2, 3]) >>> p2 = np.poly1d([9, 5, 1]) >>> print(p1) 2 1 x + 2 x + 3 >>> print(p2) 2 9 x + 5 x + 1 >>> print(np.polymul(p1, p2)) 4 3 2 9 x + 23 x + 38 x + 17 x + 3 " :arglists '[[& [args {:as kwargs}]]]} polymul (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polymul")))) (def ^{:doc "empty(shape, dtype=float, order='C', *, like=None) 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 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" :arglists '[[self & [args {:as kwargs}]]]} empty (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "empty")))) (def ^{:doc "Any Python object. :Character code: ``'O'``" :arglists '[[self & [args {:as kwargs}]]]} object0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "object0")))) (def ^{:doc " Return the number of dimensions of an array. Parameters ---------- a : array_like Input array. If it is not already an ndarray, a conversion is attempted. Returns ------- number_of_dimensions : int The number of dimensions in `a`. Scalars are zero-dimensional. See Also -------- ndarray.ndim : equivalent method shape : dimensions of array ndarray.shape : dimensions of array Examples -------- >>> np.ndim([[1,2,3],[4,5,6]]) 2 >>> np.ndim(np.array([[1,2,3],[4,5,6]])) 2 >>> np.ndim(1) 0 " :arglists '[[& [args {:as kwargs}]]]} ndim (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ndim")))) (def ^{:doc " Least squares polynomial fit. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. Fit a polynomial ``p(x) = p[0] * x**deg + ... + p[deg]`` of degree `deg` to points `(x, y)`. Returns a vector of coefficients `p` that minimises the squared error in the order `deg`, `deg-1`, ... `0`. The `Polynomial.fit ` class method is recommended for new code as it is more stable numerically. See the documentation of the method for more information. Parameters ---------- x : array_like, shape (M,) x-coordinates of the M sample points ``(x[i], y[i])``. y : array_like, shape (M,) or (M, K) y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column. deg : int Degree of the fitting polynomial rcond : float, optional Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases. full : bool, optional Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned. w : array_like, shape (M,), optional Weights to apply to the y-coordinates of the sample points. For gaussian uncertainties, use 1/sigma (not 1/sigma**2). cov : bool or str, optional If given and not `False`, return not just the estimate but also its covariance matrix. By default, the covariance are scaled by chi2/dof, where dof = M - (deg + 1), i.e., the weights are presumed to be unreliable except in a relative sense and everything is scaled such that the reduced chi2 is unity. This scaling is omitted if ``cov='unscaled'``, as is relevant for the case that the weights are 1/sigma**2, with sigma known to be a reliable estimate of the uncertainty. Returns ------- p : ndarray, shape (deg + 1,) or (deg + 1, K) Polynomial coefficients, highest power first. If `y` was 2-D, the coefficients for `k`-th data set are in ``p[:,k]``. residuals, rank, singular_values, rcond Present only if `full` = True. Residuals is sum of squared residuals of the least-squares fit, the effective rank of the scaled Vandermonde coefficient matrix, its singular values, and the specified value of `rcond`. For more details, see `linalg.lstsq`. V : ndarray, shape (M,M) or (M,M,K) Present only if `full` = False and `cov`=True. The covariance matrix of the polynomial coefficient estimates. The diagonal of this matrix are the variance estimates for each coefficient. If y is a 2-D array, then the covariance matrix for the `k`-th data set are in ``V[:,:,k]`` Warns ----- RankWarning The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if `full` = False. The warnings can be turned off by >>> import warnings >>> warnings.simplefilter('ignore', np.RankWarning) See Also -------- polyval : Compute polynomial values. linalg.lstsq : Computes a least-squares fit. scipy.interpolate.UnivariateSpline : Computes spline fits. Notes ----- The solution minimizes the squared error .. math :: E = \\sum_{j=0}^k |p(x_j) - y_j|^2 in the equations:: x[0]**n * p[0] + ... + x[0] * p[n-1] + p[n] = y[0] x[1]**n * p[0] + ... + x[1] * p[n-1] + p[n] = y[1] ... x[k]**n * p[0] + ... + x[k] * p[n-1] + p[n] = y[k] The coefficient matrix of the coefficients `p` is a Vandermonde matrix. `polyfit` issues a `RankWarning` when the least-squares fit is badly conditioned. This implies that the best fit is not well-defined due to numerical error. The results may be improved by lowering the polynomial degree or by replacing `x` by `x` - `x`.mean(). The `rcond` parameter can also be set to a value smaller than its default, but the resulting fit may be spurious: including contributions from the small singular values can add numerical noise to the result. Note that fitting polynomial coefficients is inherently badly conditioned when the degree of the polynomial is large or the interval of sample points is badly centered. The quality of the fit should always be checked in these cases. When polynomial fits are not satisfactory, splines may be a good alternative. References ---------- .. [1] Wikipedia, \"Curve fitting\", https://en.wikipedia.org/wiki/Curve_fitting .. [2] Wikipedia, \"Polynomial interpolation\", https://en.wikipedia.org/wiki/Polynomial_interpolation Examples -------- >>> import warnings >>> x = np.array([0.0, 1.0, 2.0, 3.0, 4.0, 5.0]) >>> y = np.array([0.0, 0.8, 0.9, 0.1, -0.8, -1.0]) >>> z = np.polyfit(x, y, 3) >>> z array([ 0.08703704, -0.81349206, 1.69312169, -0.03968254]) # may vary It is convenient to use `poly1d` objects for dealing with polynomials: >>> p = np.poly1d(z) >>> p(0.5) 0.6143849206349179 # may vary >>> p(3.5) -0.34732142857143039 # may vary >>> p(10) 22.579365079365115 # may vary High-order polynomials may oscillate wildly: >>> with warnings.catch_warnings(): ... warnings.simplefilter('ignore', np.RankWarning) ... p30 = np.poly1d(np.polyfit(x, y, 30)) ... >>> p30(4) -0.80000000000000204 # may vary >>> p30(5) -0.99999999999999445 # may vary >>> p30(4.5) -0.10547061179440398 # may vary Illustration: >>> import matplotlib.pyplot as plt >>> xp = np.linspace(-2, 6, 100) >>> _ = plt.plot(x, y, '.', xp, p(xp), '-', xp, p30(xp), '--') >>> plt.ylim(-2,2) (-2, 2) >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} polyfit (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polyfit")))) (def ^{:doc "A byte string. When used in arrays, this type strips trailing null bytes. :Character code: ``'S'`` :Alias: `numpy.string_`" :arglists '[[self & [args {:as kwargs}]]]} string_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "string_")))) (def ^{:doc " Construct an array from an index array and a set of arrays to choose from. First of all, if confused or uncertain, definitely look at the Examples - in its full generality, this function is less simple than it might seem from the following code description (below ndi = `numpy.lib.index_tricks`): ``np.choose(a,c) == np.array([c[a[I]][I] for I in ndi.ndindex(a.shape)])``. But this omits some subtleties. Here is a fully general summary: Given an \"index\" array (`a`) of integers and a sequence of `n` arrays (`choices`), `a` and each choice array are first broadcast, as necessary, to arrays of a common shape; calling these *Ba* and *Bchoices[i], i = 0,...,n-1* we have that, necessarily, ``Ba.shape == Bchoices[i].shape`` for each `i`. Then, a new array with shape ``Ba.shape`` is created as follows: * if ``mode=raise`` (the default), then, first of all, each element of `a` (and thus `Ba`) must be in the range `[0, n-1]`; now, suppose that `i` (in that range) is the value at the `(j0, j1, ..., jm)` position in `Ba` - then the value at the same position in the new array is the value in `Bchoices[i]` at that same position; * if ``mode=wrap``, values in `a` (and thus `Ba`) may be any (signed) integer; modular arithmetic is used to map integers outside the range `[0, n-1]` back into that range; and then the new array is constructed as above; * if ``mode=clip``, values in `a` (and thus `Ba`) may be any (signed) integer; negative integers are mapped to 0; values greater than `n-1` are mapped to `n-1`; and then the new array is constructed as above. Parameters ---------- a : int array This array must contain integers in `[0, n-1]`, where `n` is the number of choices, unless ``mode=wrap`` or ``mode=clip``, in which cases any integers are permissible. choices : sequence of arrays Choice arrays. `a` and all of the choices must be broadcastable to the same shape. If `choices` is itself an array (not recommended), then its outermost dimension (i.e., the one corresponding to ``choices.shape[0]``) is taken as defining the \"sequence\". out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. Note that `out` is always buffered if `mode='raise'`; use other modes for better performance. mode : {'raise' (default), 'wrap', 'clip'}, optional Specifies how indices outside `[0, n-1]` will be treated: * 'raise' : an exception is raised * 'wrap' : value becomes value mod `n` * 'clip' : values < 0 are mapped to 0, values > n-1 are mapped to n-1 Returns ------- merged_array : array The merged result. Raises ------ ValueError: shape mismatch If `a` and each choice array are not all broadcastable to the same shape. See Also -------- ndarray.choose : equivalent method numpy.take_along_axis : Preferable if `choices` is an array Notes ----- To reduce the chance of misinterpretation, even though the following \"abuse\" is nominally supported, `choices` should neither be, nor be thought of as, a single array, i.e., the outermost sequence-like container should be either a list or a tuple. Examples -------- >>> choices = [[0, 1, 2, 3], [10, 11, 12, 13], ... [20, 21, 22, 23], [30, 31, 32, 33]] >>> np.choose([2, 3, 1, 0], choices ... # the first element of the result will be the first element of the ... # third (2+1) \"array\" in choices, namely, 20; the second element ... # will be the second element of the fourth (3+1) choice array, i.e., ... # 31, etc. ... ) array([20, 31, 12, 3]) >>> np.choose([2, 4, 1, 0], choices, mode='clip') # 4 goes to 3 (4-1) array([20, 31, 12, 3]) >>> # because there are 4 choice arrays >>> np.choose([2, 4, 1, 0], choices, mode='wrap') # 4 goes to (4 mod 4) array([20, 1, 12, 3]) >>> # i.e., 0 A couple examples illustrating how choose broadcasts: >>> a = [[1, 0, 1], [0, 1, 0], [1, 0, 1]] >>> choices = [-10, 10] >>> np.choose(a, choices) array([[ 10, -10, 10], [-10, 10, -10], [ 10, -10, 10]]) >>> # With thanks to Anne Archibald >>> a = np.array([0, 1]).reshape((2,1,1)) >>> c1 = np.array([1, 2, 3]).reshape((1,3,1)) >>> c2 = np.array([-1, -2, -3, -4, -5]).reshape((1,1,5)) >>> np.choose(a, (c1, c2)) # result is 2x3x5, res[0,:,:]=c1, res[1,:,:]=c2 array([[[ 1, 1, 1, 1, 1], [ 2, 2, 2, 2, 2], [ 3, 3, 3, 3, 3]], [[-1, -2, -3, -4, -5], [-1, -2, -3, -4, -5], [-1, -2, -3, -4, -5]]]) " :arglists '[[& [args {:as kwargs}]]]} choose (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "choose")))) (def ^{:doc " Return numbers spaced evenly on a log scale. In linear space, the sequence starts at ``base ** start`` (`base` to the power of `start`) and ends with ``base ** stop`` (see `endpoint` below). .. versionchanged:: 1.16.0 Non-scalar `start` and `stop` are now supported. Parameters ---------- start : array_like ``base ** start`` is the starting value of the sequence. stop : array_like ``base ** stop`` is the final value of the sequence, unless `endpoint` is False. In that case, ``num + 1`` values are spaced over the interval in log-space, of which all but the last (a sequence of length `num`) are returned. num : integer, optional Number of samples to generate. Default is 50. endpoint : boolean, optional If true, `stop` is the last sample. Otherwise, it is not included. Default is True. base : array_like, optional The base of the log space. The step size between the elements in ``ln(samples) / ln(base)`` (or ``log_base(samples)``) is uniform. Default is 10.0. dtype : dtype The type of the output array. If `dtype` is not given, the data type is inferred from `start` and `stop`. The inferred type will never be an integer; `float` is chosen even if the arguments would produce an array of integers. axis : int, optional The axis in the result to store the samples. Relevant only if start or stop are array-like. By default (0), the samples will be along a new axis inserted at the beginning. Use -1 to get an axis at the end. .. versionadded:: 1.16.0 Returns ------- samples : ndarray `num` samples, equally spaced on a log scale. See Also -------- arange : Similar to linspace, with the step size specified instead of the number of samples. Note that, when used with a float endpoint, the endpoint may or may not be included. linspace : Similar to logspace, but with the samples uniformly distributed in linear space, instead of log space. geomspace : Similar to logspace, but with endpoints specified directly. Notes ----- Logspace is equivalent to the code >>> y = np.linspace(start, stop, num=num, endpoint=endpoint) ... # doctest: +SKIP >>> power(base, y).astype(dtype) ... # doctest: +SKIP Examples -------- >>> np.logspace(2.0, 3.0, num=4) array([ 100. , 215.443469 , 464.15888336, 1000. ]) >>> np.logspace(2.0, 3.0, num=4, endpoint=False) array([100. , 177.827941 , 316.22776602, 562.34132519]) >>> np.logspace(2.0, 3.0, num=4, base=2.0) array([4. , 5.0396842 , 6.34960421, 8. ]) Graphical illustration: >>> import matplotlib.pyplot as plt >>> N = 10 >>> x1 = np.logspace(0.1, 1, N, endpoint=True) >>> x2 = np.logspace(0.1, 1, N, endpoint=False) >>> y = np.zeros(N) >>> plt.plot(x1, y, 'o') [] >>> plt.plot(x2, y + 0.5, 'o') [] >>> plt.ylim([-0.5, 1]) (-0.5, 1) >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} logspace (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "logspace")))) (def ^{:doc "logical_not(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the truth value of NOT x element-wise. Parameters ---------- x : array_like Logical NOT is applied to the elements of `x`. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : bool or ndarray of bool Boolean result with the same shape as `x` of the NOT operation on elements of `x`. This is a scalar if `x` is a scalar. See Also -------- logical_and, logical_or, logical_xor Examples -------- >>> np.logical_not(3) False >>> np.logical_not([True, False, 0, 1]) array([False, True, True, False]) >>> x = np.arange(5) >>> np.logical_not(x<3) array([False, False, False, True, True])" :arglists '[[self & [args {:as kwargs}]]]} logical_not (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "logical_not")))) (def ^{:doc "" :arglists '[[& [args {:as kwargs}]]]} loads (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "loads")))) (def ^{:doc " bincount(x, weights=None, minlength=0) Count number of occurrences of each value in array of non-negative ints. The number of bins (of size 1) is one larger than the largest value in `x`. If `minlength` is specified, there will be at least this number of bins in the output array (though it will be longer if necessary, depending on the contents of `x`). Each bin gives the number of occurrences of its index value in `x`. If `weights` is specified the input array is weighted by it, i.e. if a value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead of ``out[n] += 1``. Parameters ---------- x : array_like, 1 dimension, nonnegative ints Input array. weights : array_like, optional Weights, array of the same shape as `x`. minlength : int, optional A minimum number of bins for the output array. .. versionadded:: 1.6.0 Returns ------- out : ndarray of ints The result of binning the input array. The length of `out` is equal to ``np.amax(x)+1``. Raises ------ ValueError If the input is not 1-dimensional, or contains elements with negative values, or if `minlength` is negative. TypeError If the type of the input is float or complex. See Also -------- histogram, digitize, unique Examples -------- >>> np.bincount(np.arange(5)) array([1, 1, 1, 1, 1]) >>> np.bincount(np.array([0, 1, 1, 3, 2, 1, 7])) array([1, 3, 1, 1, 0, 0, 0, 1]) >>> x = np.array([0, 1, 1, 3, 2, 1, 7, 23]) >>> np.bincount(x).size == np.amax(x)+1 True The input array needs to be of integer dtype, otherwise a TypeError is raised: >>> np.bincount(np.arange(5, dtype=float)) Traceback (most recent call last): ... TypeError: Cannot cast array data from dtype('float64') to dtype('int64') according to the rule 'safe' A possible use of ``bincount`` is to perform sums over variable-size chunks of an array, using the ``weights`` keyword. >>> w = np.array([0.3, 0.5, 0.2, 0.7, 1., -0.6]) # weights >>> x = np.array([0, 1, 1, 2, 2, 2]) >>> np.bincount(x, weights=w) array([ 0.3, 0.7, 1.1]) " :arglists '[[& [args {:as kwargs}]]]} bincount (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bincount")))) (def ^{:doc " Format a floating-point scalar as a decimal string in scientific notation. Provides control over rounding, trimming and padding. Uses and assumes IEEE unbiased rounding. Uses the \"Dragon4\" algorithm. Parameters ---------- x : python float or numpy floating scalar Value to format. precision : non-negative integer or None, optional Maximum number of digits to print. May be None if `unique` is `True`, but must be an integer if unique is `False`. unique : boolean, optional If `True`, use a digit-generation strategy which gives the shortest representation which uniquely identifies the floating-point number from other values of the same type, by judicious rounding. If `precision` was omitted, print all necessary digits, otherwise digit generation is cut off after `precision` digits and the remaining value is rounded. If `False`, digits are generated as if printing an infinite-precision value and stopping after `precision` digits, rounding the remaining value. trim : one of 'k', '.', '0', '-', optional Controls post-processing trimming of trailing digits, as follows: * 'k' : keep trailing zeros, keep decimal point (no trimming) * '.' : trim all trailing zeros, leave decimal point * '0' : trim all but the zero before the decimal point. Insert the zero if it is missing. * '-' : trim trailing zeros and any trailing decimal point sign : boolean, optional Whether to show the sign for positive values. pad_left : non-negative integer, optional Pad the left side of the string with whitespace until at least that many characters are to the left of the decimal point. exp_digits : non-negative integer, optional Pad the exponent with zeros until it contains at least this many digits. If omitted, the exponent will be at least 2 digits. Returns ------- rep : string The string representation of the floating point value See Also -------- format_float_positional Examples -------- >>> np.format_float_scientific(np.float32(np.pi)) '3.1415927e+00' >>> s = np.float32(1.23e24) >>> np.format_float_scientific(s, unique=False, precision=15) '1.230000071797338e+24' >>> np.format_float_scientific(s, exp_digits=4) '1.23e+0024' " :arglists '[[x & [{precision :precision, unique :unique, trim :trim, sign :sign, pad_left :pad_left, exp_digits :exp_digits}]] [x & [{precision :precision, unique :unique, trim :trim, sign :sign, pad_left :pad_left}]] [x & [{precision :precision, unique :unique, trim :trim, sign :sign}]] [x & [{precision :precision, unique :unique, trim :trim}]] [x & [{precision :precision, unique :unique}]] [x & [{precision :precision}]] [x]]} format_float_scientific (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "format_float_scientific")))) (def ^{:doc "tan(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute tangent element-wise. Equivalent to ``np.sin(x)/np.cos(x)`` element-wise. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The corresponding tangent values. This is a scalar if `x` is a scalar. Notes ----- If `out` is provided, the function writes the result into it, and returns a reference to `out`. (See Examples) References ---------- M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972. Examples -------- >>> from math import pi >>> np.tan(np.array([-pi,pi/2,pi])) array([ 1.22460635e-16, 1.63317787e+16, -1.22460635e-16]) >>> >>> # Example of providing the optional output parameter illustrating >>> # that what is returned is a reference to said parameter >>> out1 = np.array([0], dtype='d') >>> out2 = np.cos([0.1], out1) >>> out2 is out1 True >>> >>> # Example of ValueError due to provision of shape mis-matched `out` >>> np.cos(np.zeros((3,3)),np.zeros((2,2))) Traceback (most recent call last): File \"\", line 1, in ValueError: operands could not be broadcast together with shapes (3,3) (2,2)" :arglists '[[self & [args {:as kwargs}]]]} tan (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tan")))) (def ^{:doc "Signed integer type, compatible with Python `int` and C ``long``. :Character code: ``'l'`` :Canonical name: `numpy.int_` :Alias on this platform: `numpy.int64`: 64-bit signed integer (``-9_223_372_036_854_775_808`` to ``9_223_372_036_854_775_807``). :Alias on this platform: `numpy.intp`: Signed integer large enough to fit pointer, compatible with C ``intptr_t``." :arglists '[[self & [args {:as kwargs}]]]} int_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "int_")))) (def ^{:doc "dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)"} __expired_functions__ (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* "__expired_functions__")))) (def ^{:doc "Construct an ndarray that allows field access using attributes. Arrays may have a data-types containing fields, analogous to columns in a spread sheet. An example is ``[(x, int), (y, float)]``, where each entry in the array is a pair of ``(int, float)``. Normally, these attributes are accessed using dictionary lookups such as ``arr['x']`` and ``arr['y']``. Record arrays allow the fields to be accessed as members of the array, using ``arr.x`` and ``arr.y``. Parameters ---------- shape : tuple Shape of output array. dtype : data-type, optional The desired data-type. By default, the data-type is determined from `formats`, `names`, `titles`, `aligned` and `byteorder`. formats : list of data-types, optional A list containing the data-types for the different columns, e.g. ``['i4', 'f8', 'i4']``. `formats` does *not* support the new convention of using types directly, i.e. ``(int, float, int)``. Note that `formats` must be a list, not a tuple. Given that `formats` is somewhat limited, we recommend specifying `dtype` instead. names : tuple of str, optional The name of each column, e.g. ``('x', 'y', 'z')``. buf : buffer, optional By default, a new array is created of the given shape and data-type. If `buf` is specified and is an object exposing the buffer interface, the array will use the memory from the existing buffer. In this case, the `offset` and `strides` keywords are available. Other Parameters ---------------- titles : tuple of str, optional Aliases for column names. For example, if `names` were ``('x', 'y', 'z')`` and `titles` is ``('x_coordinate', 'y_coordinate', 'z_coordinate')``, then ``arr['x']`` is equivalent to both ``arr.x`` and ``arr.x_coordinate``. byteorder : {'<', '>', '='}, optional Byte-order for all fields. aligned : bool, optional Align the fields in memory as the C-compiler would. strides : tuple of ints, optional Buffer (`buf`) is interpreted according to these strides (strides define how many bytes each array element, row, column, etc. occupy in memory). offset : int, optional Start reading buffer (`buf`) from this offset onwards. order : {'C', 'F'}, optional Row-major (C-style) or column-major (Fortran-style) order. Returns ------- rec : recarray Empty array of the given shape and type. See Also -------- core.records.fromrecords : Construct a record array from data. record : fundamental data-type for `recarray`. format_parser : determine a data-type from formats, names, titles. Notes ----- This constructor can be compared to ``empty``: it creates a new record array but does not fill it with data. To create a record array from data, use one of the following methods: 1. Create a standard ndarray and convert it to a record array, using ``arr.view(np.recarray)`` 2. Use the `buf` keyword. 3. Use `np.rec.fromrecords`. Examples -------- Create an array with two fields, ``x`` and ``y``: >>> x = np.array([(1.0, 2), (3.0, 4)], dtype=[('x', '>> x array([(1., 2), (3., 4)], dtype=[('x', '>> x['x'] array([1., 3.]) View the array as a record array: >>> x = x.view(np.recarray) >>> x.x array([1., 3.]) >>> x.y array([2, 4]) Create a new, empty record array: >>> np.recarray((2,), ... dtype=[('x', int), ('y', float), ('z', int)]) #doctest: +SKIP rec.array([(-1073741821, 1.2249118382103472e-301, 24547520), (3471280, 1.2134086255804012e-316, 0)], dtype=[('x', '`. Returns ------- y : ndarray The corresponding cosine values. This is a scalar if `x` is a scalar. Notes ----- If `out` is provided, the function writes the result into it, and returns a reference to `out`. (See Examples) References ---------- M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972. Examples -------- >>> np.cos(np.array([0, np.pi/2, np.pi])) array([ 1.00000000e+00, 6.12303177e-17, -1.00000000e+00]) >>> >>> # Example of providing the optional output parameter >>> out1 = np.array([0], dtype='d') >>> out2 = np.cos([0.1], out1) >>> out2 is out1 True >>> >>> # Example of ValueError due to provision of shape mis-matched `out` >>> np.cos(np.zeros((3,3)),np.zeros((2,2))) Traceback (most recent call last): File \"\", line 1, in ValueError: operands could not be broadcast together with shapes (3,3) (2,2)" :arglists '[[self & [args {:as kwargs}]]]} cos (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cos")))) (def ^{:doc " Compute tensor dot product along specified axes. Given two tensors, `a` and `b`, and an array_like object containing two array_like objects, ``(a_axes, b_axes)``, sum the products of `a`'s and `b`'s elements (components) over the axes specified by ``a_axes`` and ``b_axes``. The third argument can be a single non-negative integer_like scalar, ``N``; if it is such, then the last ``N`` dimensions of `a` and the first ``N`` dimensions of `b` are summed over. Parameters ---------- a, b : array_like Tensors to \"dot\". axes : int or (2,) array_like * integer_like If an int N, sum over the last N axes of `a` and the first N axes of `b` in order. The sizes of the corresponding axes must match. * (2,) array_like Or, a list of axes to be summed over, first sequence applying to `a`, second to `b`. Both elements array_like must be of the same length. Returns ------- output : ndarray The tensor dot product of the input. See Also -------- dot, einsum Notes ----- Three common use cases are: * ``axes = 0`` : tensor product :math:`a\\otimes b` * ``axes = 1`` : tensor dot product :math:`a\\cdot b` * ``axes = 2`` : (default) tensor double contraction :math:`a:b` When `axes` is integer_like, the sequence for evaluation will be: first the -Nth axis in `a` and 0th axis in `b`, and the -1th axis in `a` and Nth axis in `b` last. When there is more than one axis to sum over - and they are not the last (first) axes of `a` (`b`) - the argument `axes` should consist of two sequences of the same length, with the first axis to sum over given first in both sequences, the second axis second, and so forth. The shape of the result consists of the non-contracted axes of the first tensor, followed by the non-contracted axes of the second. Examples -------- A \"traditional\" example: >>> a = np.arange(60.).reshape(3,4,5) >>> b = np.arange(24.).reshape(4,3,2) >>> c = np.tensordot(a,b, axes=([1,0],[0,1])) >>> c.shape (5, 2) >>> c array([[4400., 4730.], [4532., 4874.], [4664., 5018.], [4796., 5162.], [4928., 5306.]]) >>> # A slower but equivalent way of computing the same... >>> d = np.zeros((5,2)) >>> for i in range(5): ... for j in range(2): ... for k in range(3): ... for n in range(4): ... d[i,j] += a[k,n,i] * b[n,k,j] >>> c == d array([[ True, True], [ True, True], [ True, True], [ True, True], [ True, True]]) An extended example taking advantage of the overloading of + and \\*: >>> a = np.array(range(1, 9)) >>> a.shape = (2, 2, 2) >>> A = np.array(('a', 'b', 'c', 'd'), dtype=object) >>> A.shape = (2, 2) >>> a; A array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]) array([['a', 'b'], ['c', 'd']], dtype=object) >>> np.tensordot(a, A) # third argument default is 2 for double-contraction array(['abbcccdddd', 'aaaaabbbbbbcccccccdddddddd'], dtype=object) >>> np.tensordot(a, A, 1) array([[['acc', 'bdd'], ['aaacccc', 'bbbdddd']], [['aaaaacccccc', 'bbbbbdddddd'], ['aaaaaaacccccccc', 'bbbbbbbdddddddd']]], dtype=object) >>> np.tensordot(a, A, 0) # tensor product (result too long to incl.) array([[[[['a', 'b'], ['c', 'd']], ... >>> np.tensordot(a, A, (0, 1)) array([[['abbbbb', 'cddddd'], ['aabbbbbb', 'ccdddddd']], [['aaabbbbbbb', 'cccddddddd'], ['aaaabbbbbbbb', 'ccccdddddddd']]], dtype=object) >>> np.tensordot(a, A, (2, 1)) array([[['abb', 'cdd'], ['aaabbbb', 'cccdddd']], [['aaaaabbbbbb', 'cccccdddddd'], ['aaaaaaabbbbbbbb', 'cccccccdddddddd']]], dtype=object) >>> np.tensordot(a, A, ((0, 1), (0, 1))) array(['abbbcccccddddddd', 'aabbbbccccccdddddddd'], dtype=object) >>> np.tensordot(a, A, ((2, 1), (1, 0))) array(['acccbbdddd', 'aaaaacccccccbbbbbbdddddddd'], dtype=object) " :arglists '[[& [args {:as kwargs}]]]} tensordot (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tensordot")))) (def ^{:doc " DataSource(destpath='.') A generic data source file (file, http, ftp, ...). DataSources can be local files or remote files/URLs. The files may also be compressed or uncompressed. DataSource hides some of the low-level details of downloading the file, allowing you to simply pass in a valid file path (or URL) and obtain a file object. Parameters ---------- destpath : str or None, optional Path to the directory where the source file gets downloaded to for use. If `destpath` is None, a temporary directory will be created. The default path is the current directory. Notes ----- URLs require a scheme string (``http://``) to be used, without it they will fail:: >>> repos = np.DataSource() >>> repos.exists('www.google.com/index.html') False >>> repos.exists('http://www.google.com/index.html') True Temporary directories are deleted when the DataSource is deleted. Examples -------- :: >>> ds = np.DataSource('/home/guido') >>> urlname = 'http://www.google.com/' >>> gfile = ds.open('http://www.google.com/') >>> ds.abspath(urlname) '/home/guido/www.google.com/index.html' >>> ds = np.DataSource(None) # use with temporary file >>> ds.open('/home/guido/foobar.txt') >>> ds.abspath('/home/guido/foobar.txt') '/tmp/.../home/guido/foobar.txt' " :arglists '[[self & [{destpath :destpath}]] [self]]} DataSource (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "DataSource")))) (def ^{:doc " Returns the indices that would sort an array. Perform an indirect sort along the given axis using the algorithm specified by the `kind` keyword. It returns an array of indices of the same shape as `a` that index data along the given axis in sorted order. Parameters ---------- a : array_like Array to sort. axis : int or None, optional Axis along which to sort. The default is -1 (the last axis). If None, the flattened array is used. 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 data type. 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. Returns ------- index_array : ndarray, int Array of indices that sort `a` along the specified `axis`. If `a` is one-dimensional, ``a[index_array]`` yields a sorted `a`. More generally, ``np.take_along_axis(a, index_array, axis=axis)`` always yields the sorted `a`, irrespective of dimensionality. See Also -------- sort : Describes sorting algorithms used. lexsort : Indirect stable sort with multiple keys. ndarray.sort : Inplace sort. argpartition : Indirect partial sort. take_along_axis : Apply ``index_array`` from argsort to an array as if by calling sort. Notes ----- See `sort` for notes on the different sorting algorithms. As of NumPy 1.4.0 `argsort` works with real/complex arrays containing nan values. The enhanced sort order is documented in `sort`. Examples -------- One dimensional array: >>> x = np.array([3, 1, 2]) >>> np.argsort(x) array([1, 2, 0]) Two-dimensional array: >>> x = np.array([[0, 3], [2, 2]]) >>> x array([[0, 3], [2, 2]]) >>> ind = np.argsort(x, axis=0) # sorts along first axis (down) >>> ind array([[0, 1], [1, 0]]) >>> np.take_along_axis(x, ind, axis=0) # same as np.sort(x, axis=0) array([[0, 2], [2, 3]]) >>> ind = np.argsort(x, axis=1) # sorts along last axis (across) >>> ind array([[0, 1], [0, 1]]) >>> np.take_along_axis(x, ind, axis=1) # same as np.sort(x, axis=1) array([[0, 3], [2, 2]]) Indices of the sorted elements of a N-dimensional array: >>> ind = np.unravel_index(np.argsort(x, axis=None), x.shape) >>> ind (array([0, 1, 1, 0]), array([0, 0, 1, 1])) >>> x[ind] # same as np.sort(x, axis=None) array([0, 2, 2, 3]) Sorting with keys: >>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '>> x array([(1, 0), (0, 1)], dtype=[('x', '>> np.argsort(x, order=('x','y')) array([1, 0]) >>> np.argsort(x, order=('y','x')) array([0, 1]) " :arglists '[[& [args {:as kwargs}]]]} argsort (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "argsort")))) (def ^{:doc "trunc(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the truncated value of the input, element-wise. The truncated value of the scalar `x` is the nearest integer `i` which is closer to zero than `x` is. In short, the fractional part of the signed number `x` is discarded. Parameters ---------- x : array_like Input data. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The truncated value of each element in `x`. This is a scalar if `x` is a scalar. See Also -------- ceil, floor, rint Notes ----- .. versionadded:: 1.3.0 Examples -------- >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.trunc(a) array([-1., -1., -0., 0., 1., 1., 2.])" :arglists '[[self & [args {:as kwargs}]]]} trunc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "trunc")))) (def ^{:doc " Find the intersection of two arrays. Return the sorted, unique values that are in both of the input arrays. Parameters ---------- ar1, ar2 : array_like Input arrays. Will be flattened if not already 1D. assume_unique : bool If True, the input arrays are both assumed to be unique, which can speed up the calculation. If True but ``ar1`` or ``ar2`` are not unique, incorrect results and out-of-bounds indices could result. Default is False. return_indices : bool If True, the indices which correspond to the intersection of the two arrays are returned. The first instance of a value is used if there are multiple. Default is False. .. versionadded:: 1.15.0 Returns ------- intersect1d : ndarray Sorted 1D array of common and unique elements. comm1 : ndarray The indices of the first occurrences of the common values in `ar1`. Only provided if `return_indices` is True. comm2 : ndarray The indices of the first occurrences of the common values in `ar2`. Only provided if `return_indices` is True. See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- >>> np.intersect1d([1, 3, 4, 3], [3, 1, 2, 1]) array([1, 3]) To intersect more than two arrays, use functools.reduce: >>> from functools import reduce >>> reduce(np.intersect1d, ([1, 3, 4, 3], [3, 1, 2, 1], [6, 3, 4, 2])) array([3]) To return the indices of the values common to the input arrays along with the intersected values: >>> x = np.array([1, 1, 2, 3, 4]) >>> y = np.array([2, 1, 4, 6]) >>> xy, x_ind, y_ind = np.intersect1d(x, y, return_indices=True) >>> x_ind, y_ind (array([0, 2, 4]), array([1, 0, 2])) >>> xy, x[x_ind], y[y_ind] (array([1, 2, 4]), array([1, 2, 4]), array([1, 2, 4])) " :arglists '[[& [args {:as kwargs}]]]} intersect1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "intersect1d")))) (def ^{:doc "Fill the main diagonal of the given array of any dimensionality. For an array `a` with ``a.ndim >= 2``, the diagonal is the list of locations with indices ``a[i, ..., i]`` all identical. This function modifies the input array in-place, it does not return a value. Parameters ---------- a : array, at least 2-D. Array whose diagonal is to be filled, it gets modified in-place. val : scalar or array_like Value(s) to write on the diagonal. If `val` is scalar, the value is written along the diagonal. If array-like, the flattened `val` is written along the diagonal, repeating if necessary to fill all diagonal entries. wrap : bool For tall matrices in NumPy version up to 1.6.2, the diagonal \"wrapped\" after N columns. You can have this behavior with this option. This affects only tall matrices. See also -------- diag_indices, diag_indices_from Notes ----- .. versionadded:: 1.4.0 This functionality can be obtained via `diag_indices`, but internally this version uses a much faster implementation that never constructs the indices and uses simple slicing. Examples -------- >>> a = np.zeros((3, 3), int) >>> np.fill_diagonal(a, 5) >>> a array([[5, 0, 0], [0, 5, 0], [0, 0, 5]]) The same function can operate on a 4-D array: >>> a = np.zeros((3, 3, 3, 3), int) >>> np.fill_diagonal(a, 4) We only show a few blocks for clarity: >>> a[0, 0] array([[4, 0, 0], [0, 0, 0], [0, 0, 0]]) >>> a[1, 1] array([[0, 0, 0], [0, 4, 0], [0, 0, 0]]) >>> a[2, 2] array([[0, 0, 0], [0, 0, 0], [0, 0, 4]]) The wrap option affects only tall matrices: >>> # tall matrices no wrap >>> a = np.zeros((5, 3), int) >>> np.fill_diagonal(a, 4) >>> a array([[4, 0, 0], [0, 4, 0], [0, 0, 4], [0, 0, 0], [0, 0, 0]]) >>> # tall matrices wrap >>> a = np.zeros((5, 3), int) >>> np.fill_diagonal(a, 4, wrap=True) >>> a array([[4, 0, 0], [0, 4, 0], [0, 0, 4], [0, 0, 0], [4, 0, 0]]) >>> # wide matrices >>> a = np.zeros((3, 5), int) >>> np.fill_diagonal(a, 4, wrap=True) >>> a array([[4, 0, 0, 0, 0], [0, 4, 0, 0, 0], [0, 0, 4, 0, 0]]) The anti-diagonal can be filled by reversing the order of elements using either `numpy.flipud` or `numpy.fliplr`. >>> a = np.zeros((3, 3), int); >>> np.fill_diagonal(np.fliplr(a), [1,2,3]) # Horizontal flip >>> a array([[0, 0, 1], [0, 2, 0], [3, 0, 0]]) >>> np.fill_diagonal(np.flipud(a), [1,2,3]) # Vertical flip >>> a array([[0, 0, 3], [0, 2, 0], [1, 0, 0]]) Note that the order in which the diagonal is filled varies depending on the flip function. " :arglists '[[& [args {:as kwargs}]]]} fill_diagonal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fill_diagonal")))) (def ^{:doc " ``numpy.linalg`` ================ The NumPy linear algebra functions rely on BLAS and LAPACK to provide efficient low level implementations of standard linear algebra algorithms. Those libraries may be provided by NumPy itself using C versions of a subset of their reference implementations but, when possible, highly optimized libraries that take advantage of specialized processor functionality are preferred. Examples of such libraries are OpenBLAS, MKL (TM), and ATLAS. Because those libraries are multithreaded and processor dependent, environmental variables and external packages such as threadpoolctl may be needed to control the number of threads or specify the processor architecture. - OpenBLAS: https://www.openblas.net/ - threadpoolctl: https://github.com/joblib/threadpoolctl Please note that the most-used linear algebra functions in NumPy are present in the main ``numpy`` namespace rather than in ``numpy.linalg``. There are: ``dot``, ``vdot``, ``inner``, ``outer``, ``matmul``, ``tensordot``, ``einsum``, ``einsum_path`` and ``kron``. Functions present in numpy.linalg are listed below. Matrix and vector products -------------------------- multi_dot matrix_power Decompositions -------------- cholesky qr svd Matrix eigenvalues ------------------ eig eigh eigvals eigvalsh Norms and other numbers ----------------------- norm cond det matrix_rank slogdet Solving equations and inverting matrices ---------------------------------------- solve tensorsolve lstsq inv pinv tensorinv Exceptions ---------- LinAlgError "} linalg (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "linalg")))) (def ^{:doc " Return the indices for the upper-triangle of an (n, m) array. Parameters ---------- n : int The size of the arrays for which the returned indices will be valid. k : int, optional Diagonal offset (see `triu` for details). m : int, optional .. versionadded:: 1.9.0 The column dimension of the arrays for which the returned arrays will be valid. By default `m` is taken equal to `n`. Returns ------- inds : tuple, shape(2) of ndarrays, shape(`n`) The indices for the triangle. The returned tuple contains two arrays, each with the indices along one dimension of the array. Can be used to slice a ndarray of shape(`n`, `n`). See also -------- tril_indices : similar function, for lower-triangular. mask_indices : generic function accepting an arbitrary mask function. triu, tril Notes ----- .. versionadded:: 1.4.0 Examples -------- Compute two different sets of indices to access 4x4 arrays, one for the upper triangular part starting at the main diagonal, and one starting two diagonals further right: >>> iu1 = np.triu_indices(4) >>> iu2 = np.triu_indices(4, 2) Here is how they can be used with a sample array: >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) Both for indexing: >>> a[iu1] array([ 0, 1, 2, ..., 10, 11, 15]) And for assigning values: >>> a[iu1] = -1 >>> a array([[-1, -1, -1, -1], [ 4, -1, -1, -1], [ 8, 9, -1, -1], [12, 13, 14, -1]]) These cover only a small part of the whole array (two diagonals right of the main one): >>> a[iu2] = -10 >>> a array([[ -1, -1, -10, -10], [ 4, -1, -1, -10], [ 8, 9, -1, -1], [ 12, 13, 14, -1]]) " :arglists '[[n & [{k :k, m :m}]] [n & [{k :k}]] [n]]} triu_indices (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "triu_indices")))) (def ^{:doc "remainder(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return element-wise remainder of division. Computes the remainder complementary to the `floor_divide` function. It is equivalent to the Python modulus operator``x1 % x2`` and has the same sign as the divisor `x2`. The MATLAB function equivalent to ``np.remainder`` is ``mod``. .. warning:: This should not be confused with: * Python 3.7's `math.remainder` and C's ``remainder``, which computes the IEEE remainder, which are the complement to ``round(x1 / x2)``. * The MATLAB ``rem`` function and or the C ``%`` operator which is the complement to ``int(x1 / x2)``. Parameters ---------- x1 : array_like Dividend array. x2 : array_like Divisor array. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The element-wise remainder of the quotient ``floor_divide(x1, x2)``. This is a scalar if both `x1` and `x2` are scalars. See Also -------- floor_divide : Equivalent of Python ``//`` operator. divmod : Simultaneous floor division and remainder. fmod : Equivalent of the MATLAB ``rem`` function. divide, floor Notes ----- Returns 0 when `x2` is 0 and both `x1` and `x2` are (arrays of) integers. ``mod`` is an alias of ``remainder``. Examples -------- >>> np.remainder([4, 7], [2, 3]) array([0, 1]) >>> np.remainder(np.arange(7), 5) array([0, 1, 2, 3, 4, 0, 1]) The ``%`` operator can be used as a shorthand for ``np.remainder`` on ndarrays. >>> x1 = np.arange(7) >>> x1 % 5 array([0, 1, 2, 3, 4, 0, 1])" :arglists '[[self & [args {:as kwargs}]]]} mod (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "mod")))) (def ^{:doc " Broadcast any number of arrays against each other. Parameters ---------- `*args` : array_likes The arrays to broadcast. subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned arrays will be forced to be a base-class array (default). Returns ------- broadcasted : list of arrays These arrays are views on the original arrays. They are typically not contiguous. Furthermore, more than one element of a broadcasted array may refer to a single memory location. If you need to write to the arrays, make copies first. While you can set the ``writable`` flag True, writing to a single output value may end up changing more than one location in the output array. .. deprecated:: 1.17 The output is currently marked so that if written to, a deprecation warning will be emitted. A future version will set the ``writable`` flag False so writing to it will raise an error. See Also -------- broadcast broadcast_to broadcast_shapes Examples -------- >>> x = np.array([[1,2,3]]) >>> y = np.array([[4],[5]]) >>> np.broadcast_arrays(x, y) [array([[1, 2, 3], [1, 2, 3]]), array([[4, 4, 4], [5, 5, 5]])] Here is a useful idiom for getting contiguous copies instead of non-contiguous views. >>> [np.array(a) for a in np.broadcast_arrays(x, y)] [array([[1, 2, 3], [1, 2, 3]]), array([[4, 4, 4], [5, 5, 5]])] " :arglists '[[& [args {:as kwargs}]]]} broadcast_arrays (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "broadcast_arrays")))) (def ^{:doc "Abstract base class of all integer scalar types." :arglists '[[self & [args {:as kwargs}]]]} integer (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "integer")))) (def ^{:doc "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, ] >>> 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'" :arglists '[[self & [args {:as kwargs}]]]} geterrobj (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "geterrobj")))) (def ^{:doc "Context manager for setting print options. Set print options for the scope of the `with` block, and restore the old options at the end. See `set_printoptions` for the full description of available options. Examples -------- >>> from numpy.testing import assert_equal >>> with np.printoptions(precision=2): ... np.array([2.0]) / 3 array([0.67]) The `as`-clause of the `with`-statement gives the current print options: >>> with np.printoptions(precision=2) as opts: ... assert_equal(opts, np.get_printoptions()) See Also -------- set_printoptions, get_printoptions " :arglists '[[& [args {:as kwds}]]]} printoptions (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "printoptions")))) (def ^{:doc "Signed integer type, compatible with C ``char``. :Character code: ``'b'`` :Canonical name: `numpy.byte` :Alias on this platform: `numpy.int8`: 8-bit signed integer (``-128`` to ``127``)." :arglists '[[self & [args {:as kwargs}]]]} int8 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "int8")))) (def ^{:doc " Protected string evaluation. Evaluate a string containing a Python literal expression without allowing the execution of arbitrary non-literal code. Parameters ---------- source : str The string to evaluate. Returns ------- obj : object The result of evaluating `source`. Raises ------ SyntaxError If the code has invalid Python syntax, or if it contains non-literal code. Examples -------- >>> np.safe_eval('1') 1 >>> np.safe_eval('[1, 2, 3]') [1, 2, 3] >>> np.safe_eval('{\"foo\": (\"bar\", 10.0)}') {'foo': ('bar', 10.0)} >>> np.safe_eval('import os') Traceback (most recent call last): ... SyntaxError: invalid syntax >>> np.safe_eval('open(\"/home/user/.ssh/id_dsa\").read()') Traceback (most recent call last): ... ValueError: malformed node or string: <_ast.Call object at 0x...> " :arglists '[[source]]} safe_eval (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "safe_eval")))) (def ^{:doc " **Note:** almost all functions in the ``numpy.lib`` namespace are also present in the main ``numpy`` namespace. Please use the functions as ``np.`` where possible. ``numpy.lib`` is mostly a space for implementing functions that don't belong in core or in another NumPy submodule with a clear purpose (e.g. ``random``, ``fft``, ``linalg``, ``ma``). Most contains basic functions that are used by several submodules and are useful to have in the main name-space. "} lib (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "lib")))) (def ^{:doc "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', '>> 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')" :arglists '[[self & [args {:as kwargs}]]]} promote_types (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "promote_types")))) (def ^{:doc "square(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the element-wise square of the input. Parameters ---------- x : array_like Input data. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Element-wise `x*x`, of the same shape and dtype as `x`. This is a scalar if `x` is a scalar. See Also -------- numpy.linalg.matrix_power sqrt power Examples -------- >>> np.square([-1j, 1]) array([-1.-0.j, 1.+0.j])" :arglists '[[self & [args {:as kwargs}]]]} square (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "square")))) (def ^{:doc "Module deprecation warning. The nose tester turns ordinary Deprecation warnings into test failures. That makes it hard to deprecate whole modules, because they get imported by default. So this is a special Deprecation warning that the nose tester will let pass without making tests fail. " :arglists '[[self & [args {:as kwargs}]]]} ModuleDeprecationWarning (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ModuleDeprecationWarning")))) (def ^{:doc " may_share_memory(a, b, max_work=None) Determine if two arrays might share memory A return of True does not necessarily mean that the two arrays share any element. It just means that they *might*. Only the memory bounds of a and b are checked by default. Parameters ---------- a, b : ndarray Input arrays max_work : int, optional Effort to spend on solving the overlap problem. See `shares_memory` for details. Default for ``may_share_memory`` is to do a bounds check. Returns ------- out : bool See Also -------- shares_memory Examples -------- >>> np.may_share_memory(np.array([1,2]), np.array([5,8,9])) False >>> x = np.zeros([3, 4]) >>> np.may_share_memory(x[:,0], x[:,1]) True " :arglists '[[& [args {:as kwargs}]]]} may_share_memory (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "may_share_memory")))) (def ^{:doc "dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)"} __builtins__ (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* "__builtins__")))) (def ^{:doc " Print or write to a file the source code for a NumPy object. The source code is only returned for objects written in Python. Many functions and classes are defined in C and will therefore not return useful information. Parameters ---------- object : numpy object Input object. This can be any object (function, class, module, ...). output : file object, optional If `output` not supplied then source code is printed to screen (sys.stdout). File object must be created with either write 'w' or append 'a' modes. See Also -------- lookfor, info Examples -------- >>> np.source(np.interp) #doctest: +SKIP In file: /usr/lib/python2.6/dist-packages/numpy/lib/function_base.py def interp(x, xp, fp, left=None, right=None): \"\"\".... (full docstring printed)\"\"\" if isinstance(x, (float, int, number)): return compiled_interp([x], xp, fp, left, right).item() else: return compiled_interp(x, xp, fp, left, right) The source code is only returned for objects written in Python. >>> np.source(np.array) #doctest: +SKIP Not available for this object. " :arglists '[[object & [{output :output}]] [object]]} source (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "source")))) (def ^{:doc " Interchange two axes of an array. Parameters ---------- a : array_like Input array. axis1 : int First axis. axis2 : int Second axis. Returns ------- a_swapped : ndarray For NumPy >= 1.10.0, if `a` is an ndarray, then a view of `a` is returned; otherwise a new array is created. For earlier NumPy versions a view of `a` is returned only if the order of the axes is changed, otherwise the input array is returned. Examples -------- >>> x = np.array([[1,2,3]]) >>> np.swapaxes(x,0,1) array([[1], [2], [3]]) >>> x = np.array([[[0,1],[2,3]],[[4,5],[6,7]]]) >>> x array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]]) >>> np.swapaxes(x,0,2) array([[[0, 4], [2, 6]], [[1, 5], [3, 7]]]) " :arglists '[[& [args {:as kwargs}]]]} swapaxes (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "swapaxes")))) (def ^{:doc ""} ERR_LOG 5) (def ^{:doc " Sort a complex array using the real part first, then the imaginary part. Parameters ---------- a : array_like Input array Returns ------- out : complex ndarray Always returns a sorted complex array. Examples -------- >>> np.sort_complex([5, 3, 6, 2, 1]) array([1.+0.j, 2.+0.j, 3.+0.j, 5.+0.j, 6.+0.j]) >>> np.sort_complex([1 + 2j, 2 - 1j, 3 - 2j, 3 - 3j, 3 + 5j]) array([1.+2.j, 2.-1.j, 3.-3.j, 3.-2.j, 3.+5.j]) " :arglists '[[& [args {:as kwargs}]]]} sort_complex (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sort_complex")))) (def ^{:doc "less(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the truth value of (x1 < x2) element-wise. Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array, element-wise comparison of `x1` and `x2`. Typically of type bool, unless ``dtype=object`` is passed. This is a scalar if both `x1` and `x2` are scalars. See Also -------- greater, less_equal, greater_equal, equal, not_equal Examples -------- >>> np.less([1, 2], [2, 2]) array([ True, False]) The ``<`` operator can be used as a shorthand for ``np.less`` on ndarrays. >>> a = np.array([1, 2]) >>> b = np.array([2, 2]) >>> a < b array([ True, False])" :arglists '[[self & [args {:as kwargs}]]]} less (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "less")))) (def ^{:doc "Abstract base class of all complex number scalar types that are made up of floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} complexfloating (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "complexfloating")))) (def ^{:doc " unpackbits(a, axis=None, count=None, bitorder='big') Unpacks elements of a uint8 array into a binary-valued output array. Each element of `a` represents a bit-field that should be unpacked into a binary-valued output array. The shape of the output array is either 1-D (if `axis` is ``None``) or the same shape as the input array with unpacking done along the axis specified. Parameters ---------- a : ndarray, uint8 type Input array. axis : int, optional The dimension over which bit-unpacking is done. ``None`` implies unpacking the flattened array. count : int or None, optional The number of elements to unpack along `axis`, provided as a way of undoing the effect of packing a size that is not a multiple of eight. A non-negative number means to only unpack `count` bits. A negative number means to trim off that many bits from the end. ``None`` means to unpack the entire array (the default). Counts larger than the available number of bits will add zero padding to the output. Negative counts must not exceed the available number of bits. .. versionadded:: 1.17.0 bitorder : {'big', 'little'}, optional The order of the returned bits. 'big' will mimic bin(val), ``3 = 0b00000011 => [0, 0, 0, 0, 0, 0, 1, 1]``, 'little' will reverse the order to ``[1, 1, 0, 0, 0, 0, 0, 0]``. Defaults to 'big'. .. versionadded:: 1.17.0 Returns ------- unpacked : ndarray, uint8 type The elements are binary-valued (0 or 1). See Also -------- packbits : Packs the elements of a binary-valued array into bits in a uint8 array. Examples -------- >>> a = np.array([[2], [7], [23]], dtype=np.uint8) >>> a array([[ 2], [ 7], [23]], dtype=uint8) >>> b = np.unpackbits(a, axis=1) >>> b array([[0, 0, 0, 0, 0, 0, 1, 0], [0, 0, 0, 0, 0, 1, 1, 1], [0, 0, 0, 1, 0, 1, 1, 1]], dtype=uint8) >>> c = np.unpackbits(a, axis=1, count=-3) >>> c array([[0, 0, 0, 0, 0], [0, 0, 0, 0, 0], [0, 0, 0, 1, 0]], dtype=uint8) >>> p = np.packbits(b, axis=0) >>> np.unpackbits(p, axis=0) array([[0, 0, 0, 0, 0, 0, 1, 0], [0, 0, 0, 0, 0, 1, 1, 1], [0, 0, 0, 1, 0, 1, 1, 1], [0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0]], dtype=uint8) >>> np.array_equal(b, np.unpackbits(p, axis=0, count=b.shape[0])) True " :arglists '[[& [args {:as kwargs}]]]} unpackbits (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "unpackbits")))) (def ^{:doc " Find the union of two arrays. Return the unique, sorted array of values that are in either of the two input arrays. Parameters ---------- ar1, ar2 : array_like Input arrays. They are flattened if they are not already 1D. Returns ------- union1d : ndarray Unique, sorted union of the input arrays. See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- >>> np.union1d([-1, 0, 1], [-2, 0, 2]) array([-2, -1, 0, 1, 2]) To find the union of more than two arrays, use functools.reduce: >>> from functools import reduce >>> reduce(np.union1d, ([1, 3, 4, 3], [3, 1, 2, 1], [6, 3, 4, 2])) array([1, 2, 3, 4, 6]) " :arglists '[[& [args {:as kwargs}]]]} union1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "union1d")))) (def ^{:doc " Evaluate a piecewise-defined function. Given a set of conditions and corresponding functions, evaluate each function on the input data wherever its condition is true. Parameters ---------- x : ndarray or scalar The input domain. condlist : list of bool arrays or bool scalars Each boolean array corresponds to a function in `funclist`. Wherever `condlist[i]` is True, `funclist[i](x)` is used as the output value. Each boolean array in `condlist` selects a piece of `x`, and should therefore be of the same shape as `x`. The length of `condlist` must correspond to that of `funclist`. If one extra function is given, i.e. if ``len(funclist) == len(condlist) + 1``, then that extra function is the default value, used wherever all conditions are false. funclist : list of callables, f(x,*args,**kw), or scalars Each function is evaluated over `x` wherever its corresponding condition is True. It should take a 1d array as input and give an 1d array or a scalar value as output. If, instead of a callable, a scalar is provided then a constant function (``lambda x: scalar``) is assumed. args : tuple, optional Any further arguments given to `piecewise` are passed to the functions upon execution, i.e., if called ``piecewise(..., ..., 1, 'a')``, then each function is called as ``f(x, 1, 'a')``. kw : dict, optional Keyword arguments used in calling `piecewise` are passed to the functions upon execution, i.e., if called ``piecewise(..., ..., alpha=1)``, then each function is called as ``f(x, alpha=1)``. Returns ------- out : ndarray The output is the same shape and type as x and is found by calling the functions in `funclist` on the appropriate portions of `x`, as defined by the boolean arrays in `condlist`. Portions not covered by any condition have a default value of 0. See Also -------- choose, select, where Notes ----- This is similar to choose or select, except that functions are evaluated on elements of `x` that satisfy the corresponding condition from `condlist`. The result is:: |-- |funclist[0](x[condlist[0]]) out = |funclist[1](x[condlist[1]]) |... |funclist[n2](x[condlist[n2]]) |-- Examples -------- Define the sigma function, which is -1 for ``x < 0`` and +1 for ``x >= 0``. >>> x = np.linspace(-2.5, 2.5, 6) >>> np.piecewise(x, [x < 0, x >= 0], [-1, 1]) array([-1., -1., -1., 1., 1., 1.]) Define the absolute value, which is ``-x`` for ``x <0`` and ``x`` for ``x >= 0``. >>> np.piecewise(x, [x < 0, x >= 0], [lambda x: -x, lambda x: x]) array([2.5, 1.5, 0.5, 0.5, 1.5, 2.5]) Apply the same function to a scalar value. >>> y = -2 >>> np.piecewise(y, [y < 0, y >= 0], [lambda x: -x, lambda x: x]) array(2) " :arglists '[[& [args {:as kwargs}]]]} piecewise (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "piecewise")))) (def ^{:doc "absolute(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Calculate the absolute value element-wise. ``np.abs`` is a shorthand for this function. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- absolute : ndarray An ndarray containing the absolute value of each element in `x`. For complex input, ``a + ib``, the absolute value is :math:`\\sqrt{ a^2 + b^2 }`. This is a scalar if `x` is a scalar. Examples -------- >>> x = np.array([-1.2, 1.2]) >>> np.absolute(x) array([ 1.2, 1.2]) >>> np.absolute(1.2 + 1j) 1.5620499351813308 Plot the function over ``[-10, 10]``: >>> import matplotlib.pyplot as plt >>> x = np.linspace(start=-10, stop=10, num=101) >>> plt.plot(x, np.absolute(x)) >>> plt.show() Plot the function over the complex plane: >>> xx = x + 1j * x[:, np.newaxis] >>> plt.imshow(np.abs(xx), extent=[-10, 10, -10, 10], cmap='gray') >>> plt.show() The `abs` function can be used as a shorthand for ``np.absolute`` on ndarrays. >>> x = np.array([-1.2, 1.2]) >>> abs(x) array([1.2, 1.2])" :arglists '[[self & [args {:as kwargs}]]]} abs (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "abs")))) (def ^{:doc " Return the size of the buffer used in ufuncs. Returns ------- getbufsize : int Size of ufunc buffer in bytes. " :arglists '[[]]} getbufsize (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "getbufsize")))) (def ^{:doc " Return the indices for the lower-triangle of arr. See `tril_indices` for full details. Parameters ---------- arr : array_like The indices will be valid for square arrays whose dimensions are the same as arr. k : int, optional Diagonal offset (see `tril` for details). See Also -------- tril_indices, tril Notes ----- .. versionadded:: 1.4.0 " :arglists '[[& [args {:as kwargs}]]]} tril_indices_from (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tril_indices_from")))) (def ^{:doc " Module defining global singleton classes. This module raises a RuntimeError if an attempt to reload it is made. In that way the identities of the classes defined here are fixed and will remain so even if numpy itself is reloaded. In particular, a function like the following will still work correctly after numpy is reloaded:: def foo(arg=np._NoValue): if arg is np._NoValue: ... That was not the case when the singleton classes were defined in the numpy ``__init__.py`` file. See gh-7844 for a discussion of the reload problem that motivated this module. "} _globals (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "_globals")))) (def ^{:doc "A unicode string. When used in arrays, this type strips trailing null codepoints. Unlike the builtin `str`, this supports the :ref:`python:bufferobjects`, exposing its contents as UCS4: >>> m = memoryview(np.str_(\"abc\")) >>> m.format '3w' >>> m.tobytes() b'a\\x00\\x00\\x00b\\x00\\x00\\x00c\\x00\\x00\\x00' :Character code: ``'U'`` :Alias: `numpy.unicode_`" :arglists '[[self & [args {:as kwargs}]]]} Str0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "Str0")))) (def ^{:doc "conjugate(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the complex conjugate, element-wise. The complex conjugate of a complex number is obtained by changing the sign of its imaginary part. Parameters ---------- x : array_like Input value. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The complex conjugate of `x`, with same dtype as `y`. This is a scalar if `x` is a scalar. Notes ----- `conj` is an alias for `conjugate`: >>> np.conj is np.conjugate True Examples -------- >>> np.conjugate(1+2j) (1-2j) >>> x = np.eye(2) + 1j * np.eye(2) >>> np.conjugate(x) array([[ 1.-1.j, 0.-0.j], [ 0.-0.j, 1.-1.j]])" :arglists '[[self & [args {:as kwargs}]]]} conj (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "conj")))) (def ^{:doc " Perform an indirect partition along the given axis using the algorithm specified by the `kind` keyword. It returns an array of indices of the same shape as `a` that index data along the given axis in partitioned order. .. versionadded:: 1.8.0 Parameters ---------- a : array_like Array to sort. kth : int or sequence of ints Element index to partition by. The k-th element will be in its final sorted position and all smaller elements will be moved before it and all larger elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of k-th it will partition all of them into their sorted position at once. axis : int or None, optional Axis along which to sort. The default is -1 (the last axis). If None, the flattened array is used. 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 be specified, but unspecified fields will still be used, in the order in which they come up in the dtype, to break ties. Returns ------- index_array : ndarray, int Array of indices that partition `a` along the specified axis. If `a` is one-dimensional, ``a[index_array]`` yields a partitioned `a`. More generally, ``np.take_along_axis(a, index_array, axis=a)`` always yields the partitioned `a`, irrespective of dimensionality. See Also -------- partition : Describes partition algorithms used. ndarray.partition : Inplace partition. argsort : Full indirect sort. take_along_axis : Apply ``index_array`` from argpartition to an array as if by calling partition. Notes ----- See `partition` for notes on the different selection algorithms. Examples -------- One dimensional array: >>> x = np.array([3, 4, 2, 1]) >>> x[np.argpartition(x, 3)] array([2, 1, 3, 4]) >>> x[np.argpartition(x, (1, 3))] array([1, 2, 3, 4]) >>> x = [3, 4, 2, 1] >>> np.array(x)[np.argpartition(x, 3)] array([2, 1, 3, 4]) Multi-dimensional array: >>> x = np.array([[3, 4, 2], [1, 3, 1]]) >>> index_array = np.argpartition(x, kth=1, axis=-1) >>> np.take_along_axis(x, index_array, axis=-1) # same as np.partition(x, kth=1) array([[2, 3, 4], [1, 1, 3]]) " :arglists '[[& [args {:as kwargs}]]]} argpartition (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "argpartition")))) (def ^{:doc " Show libraries in the system on which NumPy was built. Print information about various resources (libraries, library directories, include directories, etc.) in the system on which NumPy was built. See Also -------- get_include : Returns the directory containing NumPy C header files. Notes ----- Classes specifying the information to be printed are defined in the `numpy.distutils.system_info` module. Information may include: * ``language``: language used to write the libraries (mostly C or f77) * ``libraries``: names of libraries found in the system * ``library_dirs``: directories containing the libraries * ``include_dirs``: directories containing library header files * ``src_dirs``: directories containing library source files * ``define_macros``: preprocessor macros used by ``distutils.setup`` Examples -------- >>> import numpy as np >>> np.show_config() blas_opt_info: language = c define_macros = [('HAVE_CBLAS', None)] libraries = ['openblas', 'openblas'] library_dirs = ['/usr/local/lib'] " :arglists '[[]]} show_config (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "show_config")))) (def ^{:doc "arange([start,] stop[, step,], dtype=None, *, like=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 : integer or real, optional Start of interval. The interval includes this value. The default start value is 0. stop : integer or real 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 : integer or real, 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 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])" :arglists '[[self & [args {:as kwargs}]]]} arange (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arange")))) (def ^{:doc " Generate a Vandermonde matrix. The columns of the output matrix are powers of the input vector. The order of the powers is determined by the `increasing` boolean argument. Specifically, when `increasing` is False, the `i`-th output column is the input vector raised element-wise to the power of ``N - i - 1``. Such a matrix with a geometric progression in each row is named for Alexandre- Theophile Vandermonde. Parameters ---------- x : array_like 1-D input array. N : int, optional Number of columns in the output. If `N` is not specified, a square array is returned (``N = len(x)``). increasing : bool, optional Order of the powers of the columns. If True, the powers increase from left to right, if False (the default) they are reversed. .. versionadded:: 1.9.0 Returns ------- out : ndarray Vandermonde matrix. If `increasing` is False, the first column is ``x^(N-1)``, the second ``x^(N-2)`` and so forth. If `increasing` is True, the columns are ``x^0, x^1, ..., x^(N-1)``. See Also -------- polynomial.polynomial.polyvander Examples -------- >>> x = np.array([1, 2, 3, 5]) >>> N = 3 >>> np.vander(x, N) array([[ 1, 1, 1], [ 4, 2, 1], [ 9, 3, 1], [25, 5, 1]]) >>> np.column_stack([x**(N-1-i) for i in range(N)]) array([[ 1, 1, 1], [ 4, 2, 1], [ 9, 3, 1], [25, 5, 1]]) >>> x = np.array([1, 2, 3, 5]) >>> np.vander(x) array([[ 1, 1, 1, 1], [ 8, 4, 2, 1], [ 27, 9, 3, 1], [125, 25, 5, 1]]) >>> np.vander(x, increasing=True) array([[ 1, 1, 1, 1], [ 1, 2, 4, 8], [ 1, 3, 9, 27], [ 1, 5, 25, 125]]) The determinant of a square Vandermonde matrix is the product of the differences between the values of the input vector: >>> np.linalg.det(np.vander(x)) 48.000000000000043 # may vary >>> (5-3)*(5-2)*(5-1)*(3-2)*(3-1)*(2-1) 48 " :arglists '[[& [args {:as kwargs}]]]} vander (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "vander")))) (def ^{:doc "expm1(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Calculate ``exp(x) - 1`` for all elements in the array. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Element-wise exponential minus one: ``out = exp(x) - 1``. This is a scalar if `x` is a scalar. See Also -------- log1p : ``log(1 + x)``, the inverse of expm1. Notes ----- This function provides greater precision than ``exp(x) - 1`` for small values of ``x``. Examples -------- The true value of ``exp(1e-10) - 1`` is ``1.00000000005e-10`` to about 32 significant digits. This example shows the superiority of expm1 in this case. >>> np.expm1(1e-10) 1.00000000005e-10 >>> np.exp(1e-10) - 1 1.000000082740371e-10" :arglists '[[self & [args {:as kwargs}]]]} expm1 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "expm1")))) (def ^{:doc " Return the binary representation of the input number as a string. For negative numbers, if width is not given, a minus sign is added to the front. If width is given, the two's complement of the number is returned, with respect to that width. In a two's-complement system negative numbers are represented by the two's complement of the absolute value. This is the most common method of representing signed integers on computers [1]_. A N-bit two's-complement system can represent every integer in the range :math:`-2^{N-1}` to :math:`+2^{N-1}-1`. Parameters ---------- num : int Only an integer decimal number can be used. width : int, optional The length of the returned string if `num` is positive, or the length of the two's complement if `num` is negative, provided that `width` is at least a sufficient number of bits for `num` to be represented in the designated form. If the `width` value is insufficient, it will be ignored, and `num` will be returned in binary (`num` > 0) or two's complement (`num` < 0) form with its width equal to the minimum number of bits needed to represent the number in the designated form. This behavior is deprecated and will later raise an error. .. deprecated:: 1.12.0 Returns ------- bin : str Binary representation of `num` or two's complement of `num`. See Also -------- base_repr: Return a string representation of a number in the given base system. bin: Python's built-in binary representation generator of an integer. Notes ----- `binary_repr` is equivalent to using `base_repr` with base 2, but about 25x faster. References ---------- .. [1] Wikipedia, \"Two's complement\", https://en.wikipedia.org/wiki/Two's_complement Examples -------- >>> np.binary_repr(3) '11' >>> np.binary_repr(-3) '-11' >>> np.binary_repr(3, width=4) '0011' The two's complement is returned when the input number is negative and width is specified: >>> np.binary_repr(-3, width=3) '101' >>> np.binary_repr(-3, width=5) '11101' " :arglists '[[num & [{width :width}]] [num]]} binary_repr (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "binary_repr")))) (def ^{:doc "Double-precision floating-point number type, compatible with Python `float` and C ``double``. :Character code: ``'d'`` :Canonical name: `numpy.double` :Alias: `numpy.float_` :Alias on this platform: `numpy.float64`: 64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa." :arglists '[[self & [args {:as kwargs}]]]} double (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "double")))) (def ^{:doc " Stack arrays in sequence vertically (row wise). This is equivalent to concatenation along the first axis after 1-D arrays of shape `(N,)` have been reshaped to `(1,N)`. Rebuilds arrays divided by `vsplit`. This function makes most sense for arrays with up to 3 dimensions. For instance, for pixel-data with a height (first axis), width (second axis), and r/g/b channels (third axis). The functions `concatenate`, `stack` and `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of ndarrays The arrays must have the same shape along all but the first axis. 1-D arrays must have the same length. Returns ------- stacked : ndarray The array formed by stacking the given arrays, will be at least 2-D. See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. block : Assemble an nd-array from nested lists of blocks. hstack : Stack arrays in sequence horizontally (column wise). dstack : Stack arrays in sequence depth wise (along third axis). column_stack : Stack 1-D arrays as columns into a 2-D array. vsplit : Split an array into multiple sub-arrays vertically (row-wise). Examples -------- >>> a = np.array([1, 2, 3]) >>> b = np.array([2, 3, 4]) >>> np.vstack((a,b)) array([[1, 2, 3], [2, 3, 4]]) >>> a = np.array([[1], [2], [3]]) >>> b = np.array([[2], [3], [4]]) >>> np.vstack((a,b)) array([[1], [2], [3], [2], [3], [4]]) " :arglists '[[& [args {:as kwargs}]]]} vstack (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "vstack")))) (def ^{:doc ""} version (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "version")))) (def ^{:doc " Find the indices of array elements that are non-zero, grouped by element. Parameters ---------- a : array_like Input data. Returns ------- index_array : (N, a.ndim) ndarray Indices of elements that are non-zero. Indices are grouped by element. This array will have shape ``(N, a.ndim)`` where ``N`` is the number of non-zero items. See Also -------- where, nonzero Notes ----- ``np.argwhere(a)`` is almost the same as ``np.transpose(np.nonzero(a))``, but produces a result of the correct shape for a 0D array. The output of ``argwhere`` is not suitable for indexing arrays. For this purpose use ``nonzero(a)`` instead. Examples -------- >>> x = np.arange(6).reshape(2,3) >>> x array([[0, 1, 2], [3, 4, 5]]) >>> np.argwhere(x>1) array([[0, 2], [1, 0], [1, 1], [1, 2]]) " :arglists '[[& [args {:as kwargs}]]]} argwhere (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "argwhere")))) (def ^{:doc " Check whether or not an object can be iterated over. Parameters ---------- y : object Input object. Returns ------- b : bool Return ``True`` if the object has an iterator method or is a sequence and ``False`` otherwise. Examples -------- >>> np.iterable([1, 2, 3]) True >>> np.iterable(2) False " :arglists '[[y]]} iterable (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "iterable")))) (def ^{:doc "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." :arglists '[[self & [args {:as kwargs}]]]} _add_newdoc_ufunc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "_add_newdoc_ufunc")))) (def ^{:doc " Append values to the end of an array. Parameters ---------- arr : array_like Values are appended to a copy of this array. values : array_like These values are appended to a copy of `arr`. It must be of the correct shape (the same shape as `arr`, excluding `axis`). If `axis` is not specified, `values` can be any shape and will be flattened before use. axis : int, optional The axis along which `values` are appended. If `axis` is not given, both `arr` and `values` are flattened before use. Returns ------- append : ndarray A copy of `arr` with `values` appended to `axis`. Note that `append` does not occur in-place: a new array is allocated and filled. If `axis` is None, `out` is a flattened array. See Also -------- insert : Insert elements into an array. delete : Delete elements from an array. Examples -------- >>> np.append([1, 2, 3], [[4, 5, 6], [7, 8, 9]]) array([1, 2, 3, ..., 7, 8, 9]) When `axis` is specified, `values` must have the correct shape. >>> np.append([[1, 2, 3], [4, 5, 6]], [[7, 8, 9]], axis=0) array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]) >>> np.append([[1, 2, 3], [4, 5, 6]], [7, 8, 9], axis=0) Traceback (most recent call last): ... ValueError: all the input arrays must have same number of dimensions, but the array at index 0 has 2 dimension(s) and the array at index 1 has 1 dimension(s) " :arglists '[[& [args {:as kwargs}]]]} append (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "append")))) (def ^{:doc " iinfo(type) Machine limits for integer types. Attributes ---------- bits : int The number of bits occupied by the type. min : int The smallest integer expressible by the type. max : int The largest integer expressible by the type. Parameters ---------- int_type : integer type, dtype, or instance The kind of integer data type to get information about. See Also -------- finfo : The equivalent for floating point data types. Examples -------- With types: >>> ii16 = np.iinfo(np.int16) >>> ii16.min -32768 >>> ii16.max 32767 >>> ii32 = np.iinfo(np.int32) >>> ii32.min -2147483648 >>> ii32.max 2147483647 With instances: >>> ii32 = np.iinfo(np.int32(10)) >>> ii32.min -2147483648 >>> ii32.max 2147483647 " :arglists '[[self int_type]]} iinfo (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "iinfo")))) (def ^{:doc " Return an array of ones with the same shape and type as a given array. Parameters ---------- a : array_like The shape and data-type of `a` define these same attributes of the returned array. dtype : data-type, optional Overrides the data type of the result. .. versionadded:: 1.6.0 order : {'C', 'F', 'A', or 'K'}, optional Overrides the memory layout of the result. '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. .. versionadded:: 1.6.0 subok : bool, optional. If True, then the newly created array will use the sub-class type of `a`, otherwise it will be a base-class array. Defaults to True. shape : int or sequence of ints, optional. Overrides the shape of the result. If order='K' and the number of dimensions is unchanged, will try to keep order, otherwise, order='C' is implied. .. versionadded:: 1.17.0 Returns ------- out : ndarray Array of ones with the same shape and type as `a`. See Also -------- empty_like : Return an empty array 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. ones : Return a new array setting values to one. Examples -------- >>> x = np.arange(6) >>> x = x.reshape((2, 3)) >>> x array([[0, 1, 2], [3, 4, 5]]) >>> np.ones_like(x) array([[1, 1, 1], [1, 1, 1]]) >>> y = np.arange(3, dtype=float) >>> y array([0., 1., 2.]) >>> np.ones_like(y) array([1., 1., 1.]) " :arglists '[[& [args {:as kwargs}]]]} ones_like (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ones_like")))) (def ^{:doc " Return a full array with the same shape and type as a given array. Parameters ---------- a : array_like The shape and data-type of `a` define these same attributes of the returned array. fill_value : scalar Fill value. dtype : data-type, optional Overrides the data type of the result. order : {'C', 'F', 'A', or 'K'}, optional Overrides the memory layout of the result. '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. subok : bool, optional. If True, then the newly created array will use the sub-class type of `a`, otherwise it will be a base-class array. Defaults to True. shape : int or sequence of ints, optional. Overrides the shape of the result. If order='K' and the number of dimensions is unchanged, will try to keep order, otherwise, order='C' is implied. .. versionadded:: 1.17.0 Returns ------- out : ndarray Array of `fill_value` with the same shape and type as `a`. 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 : Return a new array of given shape filled with value. Examples -------- >>> x = np.arange(6, dtype=int) >>> np.full_like(x, 1) array([1, 1, 1, 1, 1, 1]) >>> np.full_like(x, 0.1) array([0, 0, 0, 0, 0, 0]) >>> np.full_like(x, 0.1, dtype=np.double) array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1]) >>> np.full_like(x, np.nan, dtype=np.double) array([nan, nan, nan, nan, nan, nan]) >>> y = np.arange(6, dtype=np.double) >>> np.full_like(y, 0.1) array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1]) " :arglists '[[& [args {:as kwargs}]]]} full_like (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "full_like")))) (def ^{:doc " Convert inputs to arrays with at least one dimension. Scalar inputs are converted to 1-dimensional arrays, whilst higher-dimensional inputs are preserved. Parameters ---------- arys1, arys2, ... : array_like One or more input arrays. Returns ------- ret : ndarray An array, or list of arrays, each with ``a.ndim >= 1``. Copies are made only if necessary. See Also -------- atleast_2d, atleast_3d Examples -------- >>> np.atleast_1d(1.0) array([1.]) >>> x = np.arange(9.0).reshape(3,3) >>> np.atleast_1d(x) array([[0., 1., 2.], [3., 4., 5.], [6., 7., 8.]]) >>> np.atleast_1d(x) is x True >>> np.atleast_1d(1, [3, 4]) [array([1]), array([3, 4])] " :arglists '[[& [args {:as kwargs}]]]} atleast_1d (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "atleast_1d")))) (def ^{:doc ""} SHIFT_UNDERFLOW 6) (def ^{:doc "Convert the input to an ndarray, but pass ndarray subclasses through. Parameters ---------- a : array_like Input data, in any form that can be converted to an array. This includes scalars, lists, lists of tuples, tuples, tuples of tuples, tuples of lists, and ndarrays. dtype : data-type, optional By default, the data-type is inferred from the input data. order : {'C', 'F', 'A', 'K'}, optional Memory layout. 'A' and 'K' depend on the order of input array a. 'C' row-major (C-style), 'F' column-major (Fortran-style) memory representation. 'A' (any) means 'F' if `a` is Fortran contiguous, 'C' otherwise 'K' (keep) preserve input order Defaults to 'C'. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray or an ndarray subclass Array interpretation of `a`. If `a` is an ndarray or a subclass of ndarray, it is returned as-is and no copy is performed. See Also -------- asarray : Similar function which always returns ndarrays. ascontiguousarray : Convert input to a contiguous array. asfarray : Convert input to a floating point ndarray. asfortranarray : Convert input to an ndarray with column-major memory order. asarray_chkfinite : Similar function which checks input for NaNs and Infs. fromiter : Create an array from an iterator. fromfunction : Construct an array by executing a function on grid positions. Examples -------- Convert a list into an array: >>> a = [1, 2] >>> np.asanyarray(a) array([1, 2]) Instances of `ndarray` subclasses are passed through as-is: >>> a = np.array([(1.0, 2), (3.0, 4)], dtype='f4,i4').view(np.recarray) >>> np.asanyarray(a) is a True " :arglists '[[a & [{dtype :dtype, order :order, like :like}]] [a & [{dtype :dtype, like :like}]] [a & [{like :like}]]]} asanyarray (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "asanyarray")))) (def ^{:doc " Do a keyword search on docstrings. A list of objects that matched the search is displayed, sorted by relevance. All given keywords need to be found in the docstring for it to be returned as a result, but the order does not matter. Parameters ---------- what : str String containing words to look for. module : str or list, optional Name of module(s) whose docstrings to go through. import_modules : bool, optional Whether to import sub-modules in packages. Default is True. regenerate : bool, optional Whether to re-generate the docstring cache. Default is False. output : file-like, optional File-like object to write the output to. If omitted, use a pager. See Also -------- source, info Notes ----- Relevance is determined only roughly, by checking if the keywords occur in the function name, at the start of a docstring, etc. Examples -------- >>> np.lookfor('binary representation') # doctest: +SKIP Search results for 'binary representation' ------------------------------------------ numpy.binary_repr Return the binary representation of the input number as a string. numpy.core.setup_common.long_double_representation Given a binary dump as given by GNU od -b, look for long double numpy.base_repr Return a string representation of a number in the given base system. ... " :arglists '[[what & [{module :module, import_modules :import_modules, regenerate :regenerate, output :output}]] [what & [{module :module, import_modules :import_modules, regenerate :regenerate}]] [what & [{module :module, import_modules :import_modules}]] [what & [{module :module}]] [what]]} lookfor (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "lookfor")))) (def ^{:doc "true_divide(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Returns a true division of the inputs, element-wise. Instead of the Python traditional 'floor division', this returns a true division. True division adjusts the output type to present the best answer, regardless of input types. Parameters ---------- x1 : array_like Dividend array. x2 : array_like Divisor array. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar This is a scalar if both `x1` and `x2` are scalars. Notes ----- In Python, ``//`` is the floor division operator and ``/`` the true division operator. The ``true_divide(x1, x2)`` function is equivalent to true division in Python. Examples -------- >>> x = np.arange(5) >>> np.true_divide(x, 4) array([ 0. , 0.25, 0.5 , 0.75, 1. ]) >>> x/4 array([ 0. , 0.25, 0.5 , 0.75, 1. ]) >>> x//4 array([0, 0, 0, 0, 1]) The ``/`` operator can be used as a shorthand for ``np.true_divide`` on ndarrays. >>> x = np.arange(5) >>> x / 4 array([0. , 0.25, 0.5 , 0.75, 1. ])" :arglists '[[self & [args {:as kwargs}]]]} divide (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "divide")))) (def ^{:doc " Trim the leading and/or trailing zeros from a 1-D array or sequence. Parameters ---------- filt : 1-D array or sequence Input array. trim : str, optional A string with 'f' representing trim from front and 'b' to trim from back. Default is 'fb', trim zeros from both front and back of the array. Returns ------- trimmed : 1-D array or sequence The result of trimming the input. The input data type is preserved. Examples -------- >>> a = np.array((0, 0, 0, 1, 2, 3, 0, 2, 1, 0)) >>> np.trim_zeros(a) array([1, 2, 3, 0, 2, 1]) >>> np.trim_zeros(a, 'b') array([0, 0, 0, ..., 0, 2, 1]) The input data type is preserved, list/tuple in means list/tuple out. >>> np.trim_zeros([0, 1, 2, 0]) [1, 2] " :arglists '[[& [args {:as kwargs}]]]} trim_zeros (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "trim_zeros")))) (def ^{:doc " Insert values along the given axis before the given indices. Parameters ---------- arr : array_like Input array. obj : int, slice or sequence of ints Object that defines the index or indices before which `values` is inserted. .. versionadded:: 1.8.0 Support for multiple insertions when `obj` is a single scalar or a sequence with one element (similar to calling insert multiple times). values : array_like Values to insert into `arr`. If the type of `values` is different from that of `arr`, `values` is converted to the type of `arr`. `values` should be shaped so that ``arr[...,obj,...] = values`` is legal. axis : int, optional Axis along which to insert `values`. If `axis` is None then `arr` is flattened first. Returns ------- out : ndarray A copy of `arr` with `values` inserted. Note that `insert` does not occur in-place: a new array is returned. If `axis` is None, `out` is a flattened array. See Also -------- append : Append elements at the end of an array. concatenate : Join a sequence of arrays along an existing axis. delete : Delete elements from an array. Notes ----- Note that for higher dimensional inserts `obj=0` behaves very different from `obj=[0]` just like `arr[:,0,:] = values` is different from `arr[:,[0],:] = values`. Examples -------- >>> a = np.array([[1, 1], [2, 2], [3, 3]]) >>> a array([[1, 1], [2, 2], [3, 3]]) >>> np.insert(a, 1, 5) array([1, 5, 1, ..., 2, 3, 3]) >>> np.insert(a, 1, 5, axis=1) array([[1, 5, 1], [2, 5, 2], [3, 5, 3]]) Difference between sequence and scalars: >>> np.insert(a, [1], [[1],[2],[3]], axis=1) array([[1, 1, 1], [2, 2, 2], [3, 3, 3]]) >>> np.array_equal(np.insert(a, 1, [1, 2, 3], axis=1), ... np.insert(a, [1], [[1],[2],[3]], axis=1)) True >>> b = a.flatten() >>> b array([1, 1, 2, 2, 3, 3]) >>> np.insert(b, [2, 2], [5, 6]) array([1, 1, 5, ..., 2, 3, 3]) >>> np.insert(b, slice(2, 4), [5, 6]) array([1, 1, 5, ..., 2, 3, 3]) >>> np.insert(b, [2, 2], [7.13, False]) # type casting array([1, 1, 7, ..., 2, 3, 3]) >>> x = np.arange(8).reshape(2, 4) >>> idx = (1, 3) >>> np.insert(x, idx, 999, axis=1) array([[ 0, 999, 1, 2, 999, 3], [ 4, 999, 5, 6, 999, 7]]) " :arglists '[[& [args {:as kwargs}]]]} insert (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "insert")))) (def ^{:doc ""} __version__ "1.20.3") (def ^{:doc "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])" :arglists '[[self & [args {:as kwargs}]]]} compare_chararrays (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "compare_chararrays")))) (def ^{:doc ""} __git_revision__ "27b98cbe0dd9d2969e9c227e7a2070aa56f41d6d") (def ^{:doc " Return the string representation of an array. Parameters ---------- arr : ndarray Input array. max_line_width : int, optional Inserts newlines if text is longer than `max_line_width`. Defaults to ``numpy.get_printoptions()['linewidth']``. precision : int, optional Floating point precision. Defaults to ``numpy.get_printoptions()['precision']``. suppress_small : bool, optional Represent numbers \"very close\" to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero. Defaults to ``numpy.get_printoptions()['suppress']``. Returns ------- string : str The string representation of an array. See Also -------- array_str, array2string, set_printoptions Examples -------- >>> np.array_repr(np.array([1,2])) 'array([1, 2])' >>> np.array_repr(np.ma.array([0.])) 'MaskedArray([0.])' >>> np.array_repr(np.array([], np.int32)) 'array([], dtype=int32)' >>> x = np.array([1e-6, 4e-7, 2, 3]) >>> np.array_repr(x, precision=6, suppress_small=True) 'array([0.000001, 0. , 2. , 3. ])' " :arglists '[[& [args {:as kwargs}]]]} array_repr (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "array_repr")))) (def ^{:doc " Determine if the first argument is a subclass of the second argument. Parameters ---------- arg1, arg2 : dtype or dtype specifier Data-types. Returns ------- out : bool The result. See Also -------- issctype, issubdtype, obj2sctype Examples -------- >>> np.issubsctype('S8', str) False >>> np.issubsctype(np.array([1]), int) True >>> np.issubsctype(np.array([1]), float) False " :arglists '[[arg1 arg2]]} issubsctype (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "issubsctype")))) (def ^{:doc ""} PINF ##Inf) (def ^{:doc "Built-in immutable sequence. If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items. If the argument is a tuple, the return value is the same object."} ScalarType (as-jvm/generic-python-as-list (py-global-delay (py/get-attr @src-obj* "ScalarType")))) (def ^{:doc " Stack arrays in sequence depth wise (along third axis). This is equivalent to concatenation along the third axis after 2-D arrays of shape `(M,N)` have been reshaped to `(M,N,1)` and 1-D arrays of shape `(N,)` have been reshaped to `(1,N,1)`. Rebuilds arrays divided by `dsplit`. This function makes most sense for arrays with up to 3 dimensions. For instance, for pixel-data with a height (first axis), width (second axis), and r/g/b channels (third axis). The functions `concatenate`, `stack` and `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of arrays The arrays must have the same shape along all but the third axis. 1-D or 2-D arrays must have the same shape. Returns ------- stacked : ndarray The array formed by stacking the given arrays, will be at least 3-D. See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. block : Assemble an nd-array from nested lists of blocks. vstack : Stack arrays in sequence vertically (row wise). hstack : Stack arrays in sequence horizontally (column wise). column_stack : Stack 1-D arrays as columns into a 2-D array. dsplit : Split array along third axis. Examples -------- >>> a = np.array((1,2,3)) >>> b = np.array((2,3,4)) >>> np.dstack((a,b)) array([[[1, 2], [2, 3], [3, 4]]]) >>> a = np.array([[1],[2],[3]]) >>> b = np.array([[2],[3],[4]]) >>> np.dstack((a,b)) array([[[1, 2]], [[2, 3]], [[3, 4]]]) " :arglists '[[& [args {:as kwargs}]]]} dstack (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "dstack")))) (def ^{:doc " `nd_grid` instance which returns an open multi-dimensional \"meshgrid\". An instance of `numpy.lib.index_tricks.nd_grid` which returns an open (i.e. not fleshed out) mesh-grid when indexed, so that only one dimension of each returned array is greater than 1. The dimension and number of the output arrays are equal to the number of indexing dimensions. If the step length is not a complex number, then the stop is not inclusive. However, if the step length is a **complex number** (e.g. 5j), then the integer part of its magnitude is interpreted as specifying the number of points to create between the start and stop values, where the stop value **is inclusive**. Returns ------- mesh-grid `ndarrays` with only one dimension not equal to 1 See Also -------- np.lib.index_tricks.nd_grid : class of `ogrid` and `mgrid` objects mgrid : like `ogrid` but returns dense (or fleshed out) mesh grids r_ : array concatenator Examples -------- >>> from numpy import ogrid >>> ogrid[-1:1:5j] array([-1. , -0.5, 0. , 0.5, 1. ]) >>> ogrid[0:5,0:5] [array([[0], [1], [2], [3], [4]]), array([[0, 1, 2, 3, 4]])] "} ogrid (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "ogrid")))) (def ^{:doc " Test element-wise for positive infinity, return result as bool array. Parameters ---------- x : array_like The input array. out : array_like, optional A location into which the result is stored. If provided, it must have a shape that the input broadcasts to. If not provided or None, a freshly-allocated boolean array is returned. Returns ------- out : ndarray A boolean array with the same dimensions as the input. If second argument is not supplied then a boolean array is returned with values True where the corresponding element of the input is positive infinity and values False where the element of the input is not positive infinity. If a second argument is supplied the result is stored there. If the type of that array is a numeric type the result is represented as zeros and ones, if the type is boolean then as False and True. The return value `out` is then a reference to that array. See Also -------- isinf, isneginf, isfinite, isnan Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). Errors result if the second argument is also supplied when x is a scalar input, if first and second arguments have different shapes, or if the first argument has complex values Examples -------- >>> np.isposinf(np.PINF) True >>> np.isposinf(np.inf) True >>> np.isposinf(np.NINF) False >>> np.isposinf([-np.inf, 0., np.inf]) array([False, False, True]) >>> x = np.array([-np.inf, 0., np.inf]) >>> y = np.array([2, 2, 2]) >>> np.isposinf(x, y) array([0, 0, 1]) >>> y array([0, 0, 1]) " :arglists '[[& [args {:as kwargs}]]]} isposinf (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isposinf")))) (def ^{:doc "exp2(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Calculate `2**p` for all `p` in the input array. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Element-wise 2 to the power `x`. This is a scalar if `x` is a scalar. See Also -------- power Notes ----- .. versionadded:: 1.3.0 Examples -------- >>> np.exp2([2, 3]) array([ 4., 8.])" :arglists '[[self & [args {:as kwargs}]]]} exp2 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "exp2")))) (def ^{:doc "A byte string. When used in arrays, this type strips trailing null bytes. :Character code: ``'S'`` :Alias: `numpy.string_`" :arglists '[[self & [args {:as kwargs}]]]} Bytes0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "Bytes0")))) (def ^{:doc " Roll array elements along a given axis. Elements that roll beyond the last position are re-introduced at the first. Parameters ---------- a : array_like Input array. shift : int or tuple of ints The number of places by which elements are shifted. If a tuple, then `axis` must be a tuple of the same size, and each of the given axes is shifted by the corresponding number. If an int while `axis` is a tuple of ints, then the same value is used for all given axes. axis : int or tuple of ints, optional Axis or axes along which elements are shifted. By default, the array is flattened before shifting, after which the original shape is restored. Returns ------- res : ndarray Output array, with the same shape as `a`. See Also -------- rollaxis : Roll the specified axis backwards, until it lies in a given position. Notes ----- .. versionadded:: 1.12.0 Supports rolling over multiple dimensions simultaneously. Examples -------- >>> x = np.arange(10) >>> np.roll(x, 2) array([8, 9, 0, 1, 2, 3, 4, 5, 6, 7]) >>> np.roll(x, -2) array([2, 3, 4, 5, 6, 7, 8, 9, 0, 1]) >>> x2 = np.reshape(x, (2,5)) >>> x2 array([[0, 1, 2, 3, 4], [5, 6, 7, 8, 9]]) >>> np.roll(x2, 1) array([[9, 0, 1, 2, 3], [4, 5, 6, 7, 8]]) >>> np.roll(x2, -1) array([[1, 2, 3, 4, 5], [6, 7, 8, 9, 0]]) >>> np.roll(x2, 1, axis=0) array([[5, 6, 7, 8, 9], [0, 1, 2, 3, 4]]) >>> np.roll(x2, -1, axis=0) array([[5, 6, 7, 8, 9], [0, 1, 2, 3, 4]]) >>> np.roll(x2, 1, axis=1) array([[4, 0, 1, 2, 3], [9, 5, 6, 7, 8]]) >>> np.roll(x2, -1, axis=1) array([[1, 2, 3, 4, 0], [6, 7, 8, 9, 5]]) " :arglists '[[& [args {:as kwargs}]]]} roll (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "roll")))) (def ^{:doc ""} WRAP 1) (def ^{:doc "Convert the input to an array. Parameters ---------- a : array_like Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays. dtype : data-type, optional By default, the data-type is inferred from the input data. order : {'C', 'F', 'A', 'K'}, optional Memory layout. 'A' and 'K' depend on the order of input array a. 'C' row-major (C-style), 'F' column-major (Fortran-style) memory representation. 'A' (any) means 'F' if `a` is Fortran contiguous, 'C' otherwise 'K' (keep) preserve input order Defaults to 'C'. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray Array interpretation of `a`. No copy is performed if the input is already an ndarray with matching dtype and order. If `a` is a subclass of ndarray, a base class ndarray is returned. See Also -------- asanyarray : Similar function which passes through subclasses. ascontiguousarray : Convert input to a contiguous array. asfarray : Convert input to a floating point ndarray. asfortranarray : Convert input to an ndarray with column-major memory order. asarray_chkfinite : Similar function which checks input for NaNs and Infs. fromiter : Create an array from an iterator. fromfunction : Construct an array by executing a function on grid positions. Examples -------- Convert a list into an array: >>> a = [1, 2] >>> np.asarray(a) array([1, 2]) Existing arrays are not copied: >>> a = np.array([1, 2]) >>> np.asarray(a) is a True If `dtype` is set, array is copied only if dtype does not match: >>> a = np.array([1, 2], dtype=np.float32) >>> np.asarray(a, dtype=np.float32) is a True >>> np.asarray(a, dtype=np.float64) is a False Contrary to `asanyarray`, ndarray subclasses are not passed through: >>> issubclass(np.recarray, np.ndarray) True >>> a = np.array([(1.0, 2), (3.0, 4)], dtype='f4,i4').view(np.recarray) >>> np.asarray(a) is a False >>> np.asanyarray(a) is a True " :arglists '[[a & [{dtype :dtype, order :order, like :like}]] [a & [{dtype :dtype, like :like}]] [a & [{like :like}]]]} asarray (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "asarray")))) (def ^{:doc "_fastCopyAndTranspose(a)" :arglists '[[self & [args {:as kwargs}]]]} fastCopyAndTranspose (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fastCopyAndTranspose")))) (def ^{:doc ""} oldnumeric "removed") (def ^{:doc " Returns a boolean array where two arrays are element-wise equal within a tolerance. The tolerance values are positive, typically very small numbers. The relative difference (`rtol` * abs(`b`)) and the absolute difference `atol` are added together to compare against the absolute difference between `a` and `b`. .. warning:: The default `atol` is not appropriate for comparing numbers that are much smaller than one (see Notes). Parameters ---------- a, b : array_like Input arrays to compare. rtol : float The relative tolerance parameter (see Notes). atol : float The absolute tolerance parameter (see Notes). equal_nan : bool Whether to compare NaN's as equal. If True, NaN's in `a` will be considered equal to NaN's in `b` in the output array. Returns ------- y : array_like Returns a boolean array of where `a` and `b` are equal within the given tolerance. If both `a` and `b` are scalars, returns a single boolean value. See Also -------- allclose math.isclose Notes ----- .. versionadded:: 1.7.0 For finite values, isclose uses the following equation to test whether two floating point values are equivalent. absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`)) Unlike the built-in `math.isclose`, the above equation is not symmetric in `a` and `b` -- it assumes `b` is the reference value -- so that `isclose(a, b)` might be different from `isclose(b, a)`. Furthermore, the default value of atol is not zero, and is used to determine what small values should be considered close to zero. The default value is appropriate for expected values of order unity: if the expected values are significantly smaller than one, it can result in false positives. `atol` should be carefully selected for the use case at hand. A zero value for `atol` will result in `False` if either `a` or `b` is zero. `isclose` is not defined for non-numeric data types. Examples -------- >>> np.isclose([1e10,1e-7], [1.00001e10,1e-8]) array([ True, False]) >>> np.isclose([1e10,1e-8], [1.00001e10,1e-9]) array([ True, True]) >>> np.isclose([1e10,1e-8], [1.0001e10,1e-9]) array([False, True]) >>> np.isclose([1.0, np.nan], [1.0, np.nan]) array([ True, False]) >>> np.isclose([1.0, np.nan], [1.0, np.nan], equal_nan=True) array([ True, True]) >>> np.isclose([1e-8, 1e-7], [0.0, 0.0]) array([ True, False]) >>> np.isclose([1e-100, 1e-7], [0.0, 0.0], atol=0.0) array([False, False]) >>> np.isclose([1e-10, 1e-10], [1e-20, 0.0]) array([ True, True]) >>> np.isclose([1e-10, 1e-10], [1e-20, 0.999999e-10], atol=0.0) array([False, True]) " :arglists '[[& [args {:as kwargs}]]]} isclose (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isclose")))) (def ^{:doc "invert(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute bit-wise inversion, or bit-wise NOT, element-wise. Computes the bit-wise NOT of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``~``. For signed integer inputs, the two's complement is returned. In a two's-complement system negative numbers are represented by the two's complement of the absolute value. This is the most common method of representing signed integers on computers [1]_. A N-bit two's-complement system can represent every integer in the range :math:`-2^{N-1}` to :math:`+2^{N-1}-1`. Parameters ---------- x : array_like Only integer and boolean types are handled. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Result. This is a scalar if `x` is a scalar. See Also -------- bitwise_and, bitwise_or, bitwise_xor logical_not binary_repr : Return the binary representation of the input number as a string. Notes ----- `bitwise_not` is an alias for `invert`: >>> np.bitwise_not is np.invert True References ---------- .. [1] Wikipedia, \"Two's complement\", https://en.wikipedia.org/wiki/Two's_complement Examples -------- We've seen that 13 is represented by ``00001101``. The invert or bit-wise NOT of 13 is then: >>> x = np.invert(np.array(13, dtype=np.uint8)) >>> x 242 >>> np.binary_repr(x, width=8) '11110010' The result depends on the bit-width: >>> x = np.invert(np.array(13, dtype=np.uint16)) >>> x 65522 >>> np.binary_repr(x, width=16) '1111111111110010' When using signed integer types the result is the two's complement of the result for the unsigned type: >>> np.invert(np.array([13], dtype=np.int8)) array([-14], dtype=int8) >>> np.binary_repr(-14, width=8) '11110010' Booleans are accepted as well: >>> np.invert(np.array([True, False])) array([False, True]) The ``~`` operator can be used as a shorthand for ``np.invert`` on ndarrays. >>> x1 = np.array([True, False]) >>> ~x1 array([False, True])" :arglists '[[self & [args {:as kwargs}]]]} bitwise_not (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bitwise_not")))) (def ^{:doc "Signed integer type, compatible with Python `int` and C ``long``. :Character code: ``'l'`` :Canonical name: `numpy.int_` :Alias on this platform: `numpy.int64`: 64-bit signed integer (``-9_223_372_036_854_775_808`` to ``9_223_372_036_854_775_807``). :Alias on this platform: `numpy.intp`: Signed integer large enough to fit pointer, compatible with C ``intptr_t``." :arglists '[[self & [args {:as kwargs}]]]} int0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "int0")))) (def ^{:doc "ldexp(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Returns x1 * 2**x2, element-wise. The mantissas `x1` and twos exponents `x2` are used to construct floating point numbers ``x1 * 2**x2``. Parameters ---------- x1 : array_like Array of multipliers. x2 : array_like, int Array of twos exponents. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray or scalar The result of ``x1 * 2**x2``. This is a scalar if both `x1` and `x2` are scalars. See Also -------- frexp : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to `ldexp`. Notes ----- Complex dtypes are not supported, they will raise a TypeError. `ldexp` is useful as the inverse of `frexp`, if used by itself it is more clear to simply use the expression ``x1 * 2**x2``. Examples -------- >>> np.ldexp(5, np.arange(4)) array([ 5., 10., 20., 40.], dtype=float16) >>> x = np.arange(6) >>> np.ldexp(*np.frexp(x)) array([ 0., 1., 2., 3., 4., 5.])" :arglists '[[self & [args {:as kwargs}]]]} ldexp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ldexp")))) (def ^{:doc " Evenly round to the given number of decimals. Parameters ---------- a : array_like Input data. decimals : int, optional Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left of the decimal point. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output, but the type of the output values will be cast if necessary. See :ref:`ufuncs-output-type` for more details. Returns ------- rounded_array : ndarray An array of the same type as `a`, containing the rounded values. Unless `out` was specified, a new array is created. A reference to the result is returned. The real and imaginary parts of complex numbers are rounded separately. The result of rounding a float is a float. See Also -------- ndarray.round : equivalent method ceil, fix, floor, rint, trunc Notes ----- For values exactly halfway between rounded decimal values, NumPy rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0, -0.5 and 0.5 round to 0.0, etc. ``np.around`` uses a fast but sometimes inexact algorithm to round floating-point datatypes. For positive `decimals` it is equivalent to ``np.true_divide(np.rint(a * 10**decimals), 10**decimals)``, which has error due to the inexact representation of decimal fractions in the IEEE floating point standard [1]_ and errors introduced when scaling by powers of ten. For instance, note the extra \"1\" in the following: >>> np.round(56294995342131.5, 3) 56294995342131.51 If your goal is to print such values with a fixed number of decimals, it is preferable to use numpy's float printing routines to limit the number of printed decimals: >>> np.format_float_positional(56294995342131.5, precision=3) '56294995342131.5' The float printing routines use an accurate but much more computationally demanding algorithm to compute the number of digits after the decimal point. Alternatively, Python's builtin `round` function uses a more accurate but slower algorithm for 64-bit floating point values: >>> round(56294995342131.5, 3) 56294995342131.5 >>> np.round(16.055, 2), round(16.055, 2) # equals 16.0549999999999997 (16.06, 16.05) References ---------- .. [1] \"Lecture Notes on the Status of IEEE 754\", William Kahan, https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF .. [2] \"How Futile are Mindless Assessments of Roundoff in Floating-Point Computation?\", William Kahan, https://people.eecs.berkeley.edu/~wkahan/Mindless.pdf Examples -------- >>> np.around([0.37, 1.64]) array([0., 2.]) >>> np.around([0.37, 1.64], decimals=1) array([0.4, 1.6]) >>> np.around([.5, 1.5, 2.5, 3.5, 4.5]) # rounds to nearest even value array([0., 2., 2., 4., 4.]) >>> np.around([1,2,3,11], decimals=1) # ndarray of ints is returned array([ 1, 2, 3, 11]) >>> np.around([1,2,3,11], decimals=-1) array([ 0, 0, 0, 10]) " :arglists '[[& [args {:as kwargs}]]]} around (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "around")))) (def ^{:doc " Returns the discrete, linear convolution of two one-dimensional sequences. The convolution operator is often seen in signal processing, where it models the effect of a linear time-invariant system on a signal [1]_. In probability theory, the sum of two independent random variables is distributed according to the convolution of their individual distributions. If `v` is longer than `a`, the arrays are swapped before computation. Parameters ---------- a : (N,) array_like First one-dimensional input array. v : (M,) array_like Second one-dimensional input array. mode : {'full', 'valid', 'same'}, optional 'full': By default, mode is 'full'. This returns the convolution at each point of overlap, with an output shape of (N+M-1,). At the end-points of the convolution, the signals do not overlap completely, and boundary effects may be seen. 'same': Mode 'same' returns output of length ``max(M, N)``. Boundary effects are still visible. 'valid': Mode 'valid' returns output of length ``max(M, N) - min(M, N) + 1``. The convolution product is only given for points where the signals overlap completely. Values outside the signal boundary have no effect. Returns ------- out : ndarray Discrete, linear convolution of `a` and `v`. See Also -------- scipy.signal.fftconvolve : Convolve two arrays using the Fast Fourier Transform. scipy.linalg.toeplitz : Used to construct the convolution operator. polymul : Polynomial multiplication. Same output as convolve, but also accepts poly1d objects as input. Notes ----- The discrete convolution operation is defined as .. math:: (a * v)[n] = \\sum_{m = -\\infty}^{\\infty} a[m] v[n - m] It can be shown that a convolution :math:`x(t) * y(t)` in time/space is equivalent to the multiplication :math:`X(f) Y(f)` in the Fourier domain, after appropriate padding (padding is necessary to prevent circular convolution). Since multiplication is more efficient (faster) than convolution, the function `scipy.signal.fftconvolve` exploits the FFT to calculate the convolution of large data-sets. References ---------- .. [1] Wikipedia, \"Convolution\", https://en.wikipedia.org/wiki/Convolution Examples -------- Note how the convolution operator flips the second array before \"sliding\" the two across one another: >>> np.convolve([1, 2, 3], [0, 1, 0.5]) array([0. , 1. , 2.5, 4. , 1.5]) Only return the middle values of the convolution. Contains boundary effects, where zeros are taken into account: >>> np.convolve([1,2,3],[0,1,0.5], 'same') array([1. , 2.5, 4. ]) The two arrays are of the same length, so there is only one position where they completely overlap: >>> np.convolve([1,2,3],[0,1,0.5], 'valid') array([2.5]) " :arglists '[[& [args {:as kwargs}]]]} convolve (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "convolve")))) (def ^{:doc " Round an array to the given number of decimals. See Also -------- around : equivalent function; see for details. " :arglists '[[& [args {:as kwargs}]]]} round_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "round_")))) (def ^{:doc "add(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Add arguments element-wise. Parameters ---------- x1, x2 : array_like The arrays to be added. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- add : ndarray or scalar The sum of `x1` and `x2`, element-wise. This is a scalar if both `x1` and `x2` are scalars. Notes ----- Equivalent to `x1` + `x2` in terms of array broadcasting. Examples -------- >>> np.add(1.0, 4.0) 5.0 >>> x1 = np.arange(9.0).reshape((3, 3)) >>> x2 = np.arange(3.0) >>> np.add(x1, x2) array([[ 0., 2., 4.], [ 3., 5., 7.], [ 6., 8., 10.]]) The ``+`` operator can be used as a shorthand for ``np.add`` on ndarrays. >>> x1 = np.arange(9.0).reshape((3, 3)) >>> x2 = np.arange(3.0) >>> x1 + x2 array([[ 0., 2., 4.], [ 3., 5., 7.], [ 6., 8., 10.]])" :arglists '[[self & [args {:as kwargs}]]]} add (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "add")))) (def ^{:doc " Return a string representation of a number in the given base system. Parameters ---------- number : int The value to convert. Positive and negative values are handled. base : int, optional Convert `number` to the `base` number system. The valid range is 2-36, the default value is 2. padding : int, optional Number of zeros padded on the left. Default is 0 (no padding). Returns ------- out : str String representation of `number` in `base` system. See Also -------- binary_repr : Faster version of `base_repr` for base 2. Examples -------- >>> np.base_repr(5) '101' >>> np.base_repr(6, 5) '11' >>> np.base_repr(7, base=5, padding=3) '00012' >>> np.base_repr(10, base=16) 'A' >>> np.base_repr(32, base=16) '20' " :arglists '[[number & [{base :base, padding :padding}]] [number & [{base :base}]] [number]]} base_repr (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "base_repr")))) (def ^{:doc " Load ASCII data stored in a text file and return a masked array. .. deprecated:: 1.17 np.mafromtxt is a deprecated alias of `genfromtxt` which overwrites the ``usemask`` argument with `True` even when explicitly called as ``mafromtxt(..., usemask=False)``. Use `genfromtxt` instead. Parameters ---------- fname, kwargs : For a description of input parameters, see `genfromtxt`. See Also -------- numpy.genfromtxt : generic function to load ASCII data. " :arglists '[[fname & [{:as kwargs}]]]} mafromtxt (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "mafromtxt")))) (def ^{:doc " Compute the standard deviation along the specified axis, while ignoring NaNs. Returns the standard deviation, a measure of the spread of a distribution, of the non-NaN array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis. For all-NaN slices or slices with zero degrees of freedom, NaN is returned and a `RuntimeWarning` is raised. .. versionadded:: 1.8.0 Parameters ---------- a : array_like Calculate the standard deviation of the non-NaN values. axis : {int, tuple of int, None}, optional Axis or axes along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array. dtype : dtype, optional Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary. ddof : int, optional Means Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of non-NaN elements. By default `ddof` is zero. 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 `a`. If this value is anything but the default it is passed through as-is to the relevant functions of the sub-classes. If these functions do not have a `keepdims` kwarg, a RuntimeError will be raised. Returns ------- standard_deviation : ndarray, see dtype parameter above. If `out` is None, return a new array containing the standard deviation, otherwise return a reference to the output array. If ddof is >= the number of non-NaN elements in a slice or the slice contains only NaNs, then the result for that slice is NaN. See Also -------- var, mean, std nanvar, nanmean :ref:`ufuncs-output-type` Notes ----- The standard deviation is the square root of the average of the squared deviations from the mean: ``std = sqrt(mean(abs(x - x.mean())**2))``. The average squared deviation is normally calculated as ``x.sum() / N``, where ``N = len(x)``. If, however, `ddof` is specified, the divisor ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1`` provides an unbiased estimator of the variance of the infinite population. ``ddof=0`` provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ``ddof=1``, it will not be an unbiased estimate of the standard deviation per se. Note that, for complex numbers, `std` takes the absolute value before squaring, so that the result is always real and nonnegative. For floating-point input, the *std* is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the `dtype` keyword can alleviate this issue. Examples -------- >>> a = np.array([[1, np.nan], [3, 4]]) >>> np.nanstd(a) 1.247219128924647 >>> np.nanstd(a, axis=0) array([1., 0.]) >>> np.nanstd(a, axis=1) array([0., 0.5]) # may vary " :arglists '[[& [args {:as kwargs}]]]} nanstd (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanstd")))) (def ^{:doc "Single-precision floating-point number type, compatible with C ``float``. :Character code: ``'f'`` :Canonical name: `numpy.single` :Alias on this platform: `numpy.float32`: 32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits mantissa." :arglists '[[self & [args {:as kwargs}]]]} single (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "single")))) (def ^{:doc " inner(a, b) Inner product of two arrays. Ordinary inner product of vectors for 1-D arrays (without complex conjugation), in higher dimensions a sum product over the last axes. Parameters ---------- a, b : array_like If `a` and `b` are nonscalar, their last dimensions must match. Returns ------- out : ndarray `out.shape = a.shape[:-1] + b.shape[:-1]` Raises ------ ValueError If the last dimension of `a` and `b` has different size. See Also -------- tensordot : Sum products over arbitrary axes. dot : Generalised matrix product, using second last dimension of `b`. einsum : Einstein summation convention. Notes ----- For vectors (1-D arrays) it computes the ordinary inner-product:: np.inner(a, b) = sum(a[:]*b[:]) More generally, if `ndim(a) = r > 0` and `ndim(b) = s > 0`:: np.inner(a, b) = np.tensordot(a, b, axes=(-1,-1)) or explicitly:: np.inner(a, b)[i0,...,ir-1,j0,...,js-1] = sum(a[i0,...,ir-1,:]*b[j0,...,js-1,:]) In addition `a` or `b` may be scalars, in which case:: np.inner(a,b) = a*b Examples -------- Ordinary inner product for vectors: >>> a = np.array([1,2,3]) >>> b = np.array([0,1,0]) >>> np.inner(a, b) 2 A multidimensional example: >>> a = np.arange(24).reshape((2,3,4)) >>> b = np.arange(4) >>> np.inner(a, b) array([[ 14, 38, 62], [ 86, 110, 134]]) An example where `b` is a scalar: >>> np.inner(np.eye(2), 7) array([[7., 0.], [0., 7.]]) " :arglists '[[& [args {:as kwargs}]]]} inner (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "inner")))) (def ^{:doc " Stack 1-D arrays as columns into a 2-D array. Take a sequence of 1-D arrays and stack them as columns to make a single 2-D array. 2-D arrays are stacked as-is, just like with `hstack`. 1-D arrays are turned into 2-D columns first. Parameters ---------- tup : sequence of 1-D or 2-D arrays. Arrays to stack. All of them must have the same first dimension. Returns ------- stacked : 2-D array The array formed by stacking the given arrays. See Also -------- stack, hstack, vstack, concatenate Examples -------- >>> a = np.array((1,2,3)) >>> b = np.array((2,3,4)) >>> np.column_stack((a,b)) array([[1, 2], [2, 3], [3, 4]]) " :arglists '[[& [args {:as kwargs}]]]} column_stack (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "column_stack")))) (def ^{:doc " Estimate a covariance matrix, given data and weights. Covariance indicates the level to which two variables vary together. If we examine N-dimensional samples, :math:`X = [x_1, x_2, ... x_N]^T`, then the covariance matrix element :math:`C_{ij}` is the covariance of :math:`x_i` and :math:`x_j`. The element :math:`C_{ii}` is the variance of :math:`x_i`. See the notes for an outline of the algorithm. Parameters ---------- m : array_like A 1-D or 2-D array containing multiple variables and observations. Each row of `m` represents a variable, and each column a single observation of all those variables. Also see `rowvar` below. y : array_like, optional An additional set of variables and observations. `y` has the same form as that of `m`. rowvar : bool, optional If `rowvar` is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations. bias : bool, optional Default normalization (False) is by ``(N - 1)``, where ``N`` is the number of observations given (unbiased estimate). If `bias` is True, then normalization is by ``N``. These values can be overridden by using the keyword ``ddof`` in numpy versions >= 1.5. ddof : int, optional If not ``None`` the default value implied by `bias` is overridden. Note that ``ddof=1`` will return the unbiased estimate, even if both `fweights` and `aweights` are specified, and ``ddof=0`` will return the simple average. See the notes for the details. The default value is ``None``. .. versionadded:: 1.5 fweights : array_like, int, optional 1-D array of integer frequency weights; the number of times each observation vector should be repeated. .. versionadded:: 1.10 aweights : array_like, optional 1-D array of observation vector weights. These relative weights are typically large for observations considered \"important\" and smaller for observations considered less \"important\". If ``ddof=0`` the array of weights can be used to assign probabilities to observation vectors. .. versionadded:: 1.10 dtype : data-type, optional Data-type of the result. By default, the return data-type will have at least `numpy.float64` precision. .. versionadded:: 1.20 Returns ------- out : ndarray The covariance matrix of the variables. See Also -------- corrcoef : Normalized covariance matrix Notes ----- Assume that the observations are in the columns of the observation array `m` and let ``f = fweights`` and ``a = aweights`` for brevity. The steps to compute the weighted covariance are as follows:: >>> m = np.arange(10, dtype=np.float64) >>> f = np.arange(10) * 2 >>> a = np.arange(10) ** 2. >>> ddof = 1 >>> w = f * a >>> v1 = np.sum(w) >>> v2 = np.sum(w * a) >>> m -= np.sum(m * w, axis=None, keepdims=True) / v1 >>> cov = np.dot(m * w, m.T) * v1 / (v1**2 - ddof * v2) Note that when ``a == 1``, the normalization factor ``v1 / (v1**2 - ddof * v2)`` goes over to ``1 / (np.sum(f) - ddof)`` as it should. Examples -------- Consider two variables, :math:`x_0` and :math:`x_1`, which correlate perfectly, but in opposite directions: >>> x = np.array([[0, 2], [1, 1], [2, 0]]).T >>> x array([[0, 1, 2], [2, 1, 0]]) Note how :math:`x_0` increases while :math:`x_1` decreases. The covariance matrix shows this clearly: >>> np.cov(x) array([[ 1., -1.], [-1., 1.]]) Note that element :math:`C_{0,1}`, which shows the correlation between :math:`x_0` and :math:`x_1`, is negative. Further, note how `x` and `y` are combined: >>> x = [-2.1, -1, 4.3] >>> y = [3, 1.1, 0.12] >>> X = np.stack((x, y), axis=0) >>> np.cov(X) array([[11.71 , -4.286 ], # may vary [-4.286 , 2.144133]]) >>> np.cov(x, y) array([[11.71 , -4.286 ], # may vary [-4.286 , 2.144133]]) >>> np.cov(x) array(11.71) " :arglists '[[& [args {:as kwargs}]]]} cov (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cov")))) (def ^{:doc " Return the current callback function used on floating-point errors. When the error handling for a floating-point error (one of \"divide\", \"over\", \"under\", or \"invalid\") is set to 'call' or 'log', the function that is called or the log instance that is written to is returned by `geterrcall`. This function or log instance has been set with `seterrcall`. Returns ------- errobj : callable, log instance or None The current error handler. If no handler was set through `seterrcall`, ``None`` is returned. See Also -------- seterrcall, seterr, geterr Notes ----- For complete documentation of the types of floating-point exceptions and treatment options, see `seterr`. Examples -------- >>> np.geterrcall() # we did not yet set a handler, returns None >>> oldsettings = np.seterr(all='call') >>> def err_handler(type, flag): ... print(\"Floating point error (%s), with flag %s\" % (type, flag)) >>> oldhandler = np.seterrcall(err_handler) >>> np.array([1, 2, 3]) / 0.0 Floating point error (divide by zero), with flag 1 array([inf, inf, inf]) >>> cur_handler = np.geterrcall() >>> cur_handler is err_handler True " :arglists '[[]]} geterrcall (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "geterrcall")))) (def ^{:doc "signbit(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Returns element-wise True where signbit is set (less than zero). Parameters ---------- x : array_like The input value(s). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- result : ndarray of bool Output array, or reference to `out` if that was supplied. This is a scalar if `x` is a scalar. Examples -------- >>> np.signbit(-1.2) True >>> np.signbit(np.array([1, -2.3, 2.1])) array([False, True, False])" :arglists '[[self & [args {:as kwargs}]]]} signbit (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "signbit")))) (def ^{:doc " Return the maximum of an array or maximum along an axis. Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional Axis or axes along which to operate. By default, flattened input is used. .. versionadded:: 1.7.0 If this is a tuple of ints, the maximum is selected over multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See :ref:`ufuncs-output-type` for more details. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `amax` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. initial : scalar, optional The minimum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.15.0 where : array_like of bool, optional Elements to compare for the maximum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.17.0 Returns ------- amax : ndarray or scalar Maximum of `a`. If `axis` is None, the result is a scalar value. If `axis` is given, the result is an array of dimension ``a.ndim - 1``. See Also -------- amin : The minimum value of an array along a given axis, propagating any NaNs. nanmax : The maximum value of an array along a given axis, ignoring any NaNs. maximum : Element-wise maximum of two arrays, propagating any NaNs. fmax : Element-wise maximum of two arrays, ignoring any NaNs. argmax : Return the indices of the maximum values. nanmin, minimum, fmin Notes ----- NaN values are propagated, that is if at least one item is NaN, the corresponding max value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmax. Don't use `amax` for element-wise comparison of 2 arrays; when ``a.shape[0]`` is 2, ``maximum(a[0], a[1])`` is faster than ``amax(a, axis=0)``. Examples -------- >>> a = np.arange(4).reshape((2,2)) >>> a array([[0, 1], [2, 3]]) >>> np.amax(a) # Maximum of the flattened array 3 >>> np.amax(a, axis=0) # Maxima along the first axis array([2, 3]) >>> np.amax(a, axis=1) # Maxima along the second axis array([1, 3]) >>> np.amax(a, where=[False, True], initial=-1, axis=0) array([-1, 3]) >>> b = np.arange(5, dtype=float) >>> b[2] = np.NaN >>> np.amax(b) nan >>> np.amax(b, where=~np.isnan(b), initial=-1) 4.0 >>> np.nanmax(b) 4.0 You can use an initial value to compute the maximum of an empty slice, or to initialize it to a different value: >>> np.max([[-50], [10]], axis=-1, initial=0) array([ 0, 10]) Notice that the initial value is used as one of the elements for which the maximum is determined, unlike for the default argument Python's max function, which is only used for empty iterables. >>> np.max([5], initial=6) 6 >>> max([5], default=6) 5 " :arglists '[[& [args {:as kwargs}]]]} amax (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "amax")))) (def ^{:doc " Test whether all array elements along a given axis evaluate to True. Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : None or int or tuple of ints, optional Axis or axes along which a logical AND reduction is performed. The default (``axis=None``) is to perform a logical AND over all the dimensions 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 a tuple of ints, a reduction is performed on multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved (e.g., if ``dtype(out)`` is float, the result will consist of 0.0's and 1.0's). See :ref:`ufuncs-output-type` for more details. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `all` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. where : array_like of bool, optional Elements to include in checking for all `True` values. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.20.0 Returns ------- all : ndarray, bool A new boolean or array is returned unless `out` is specified, in which case a reference to `out` is returned. See Also -------- ndarray.all : equivalent method any : Test whether any element along a given axis evaluates to True. Notes ----- Not a Number (NaN), positive infinity and negative infinity evaluate to `True` because these are not equal to zero. Examples -------- >>> np.all([[True,False],[True,True]]) False >>> np.all([[True,False],[True,True]], axis=0) array([ True, False]) >>> np.all([-1, 4, 5]) True >>> np.all([1.0, np.nan]) True >>> np.all([[True, True], [False, True]], where=[[True], [False]]) True >>> o=np.array(False) >>> z=np.all([-1, 4, 5], out=o) >>> id(z), id(o), z (28293632, 28293632, array(True)) # may vary " :arglists '[[& [args {:as kwargs}]]]} all (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "all")))) (def ^{:doc "This module provides access to some objects used or maintained by the interpreter and to functions that interact strongly with the interpreter. Dynamic objects: argv -- command line arguments; argv[0] is the script pathname if known path -- module search path; path[0] is the script directory, else '' modules -- dictionary of loaded modules displayhook -- called to show results in an interactive session excepthook -- called to handle any uncaught exception other than SystemExit To customize printing in an interactive session or to install a custom top-level exception handler, assign other functions to replace these. stdin -- standard input file object; used by input() stdout -- standard output file object; used by print() stderr -- standard error object; used for error messages By assigning other file objects (or objects that behave like files) to these, it is possible to redirect all of the interpreter's I/O. last_type -- type of last uncaught exception last_value -- value of last uncaught exception last_traceback -- traceback of last uncaught exception These three are only available in an interactive session after a traceback has been printed. Static objects: builtin_module_names -- tuple of module names built into this interpreter copyright -- copyright notice pertaining to this interpreter exec_prefix -- prefix used to find the machine-specific Python library executable -- absolute path of the executable binary of the Python interpreter float_info -- a named tuple with information about the float implementation. float_repr_style -- string indicating the style of repr() output for floats hash_info -- a named tuple with information about the hash algorithm. hexversion -- version information encoded as a single integer implementation -- Python implementation information. int_info -- a named tuple with information about the int implementation. maxsize -- the largest supported length of containers. maxunicode -- the value of the largest Unicode code point platform -- platform identifier prefix -- prefix used to find the Python library thread_info -- a named tuple with information about the thread implementation. version -- the version of this interpreter as a string version_info -- version information as a named tuple __stdin__ -- the original stdin; don't touch! __stdout__ -- the original stdout; don't touch! __stderr__ -- the original stderr; don't touch! __displayhook__ -- the original displayhook; don't touch! __excepthook__ -- the original excepthook; don't touch! Functions: displayhook() -- print an object to the screen, and save it in builtins._ excepthook() -- print an exception and its traceback to sys.stderr exc_info() -- return thread-safe information about the current exception exit() -- exit the interpreter by raising SystemExit getdlopenflags() -- returns flags to be used for dlopen() calls getprofile() -- get the global profiling function getrefcount() -- return the reference count for an object (plus one :-) getrecursionlimit() -- return the max recursion depth for the interpreter getsizeof() -- return the size of an object in bytes gettrace() -- get the global debug tracing function setdlopenflags() -- set the flags to be used for dlopen() calls setprofile() -- set the global profiling function setrecursionlimit() -- set the max recursion depth for the interpreter settrace() -- set the global debug tracing function "} sys (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "sys")))) (def ^{:doc "true_divide(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Returns a true division of the inputs, element-wise. Instead of the Python traditional 'floor division', this returns a true division. True division adjusts the output type to present the best answer, regardless of input types. Parameters ---------- x1 : array_like Dividend array. x2 : array_like Divisor array. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar This is a scalar if both `x1` and `x2` are scalars. Notes ----- In Python, ``//`` is the floor division operator and ``/`` the true division operator. The ``true_divide(x1, x2)`` function is equivalent to true division in Python. Examples -------- >>> x = np.arange(5) >>> np.true_divide(x, 4) array([ 0. , 0.25, 0.5 , 0.75, 1. ]) >>> x/4 array([ 0. , 0.25, 0.5 , 0.75, 1. ]) >>> x//4 array([0, 0, 0, 0, 1]) The ``/`` operator can be used as a shorthand for ``np.true_divide`` on ndarrays. >>> x = np.arange(5) >>> x / 4 array([0. , 0.25, 0.5 , 0.75, 1. ])" :arglists '[[self & [args {:as kwargs}]]]} true_divide (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "true_divide")))) (def ^{:doc ""} NZERO -0.0) (def ^{:doc " Broadcast the input shapes into a single shape. :ref:`Learn more about broadcasting here `. .. versionadded:: 1.20.0 Parameters ---------- `*args` : tuples of ints, or ints The shapes to be broadcast against each other. Returns ------- tuple Broadcasted shape. Raises ------ ValueError If the shapes are not compatible and cannot be broadcast according to NumPy's broadcasting rules. See Also -------- broadcast broadcast_arrays broadcast_to Examples -------- >>> np.broadcast_shapes((1, 2), (3, 1), (3, 2)) (3, 2) >>> np.broadcast_shapes((6, 7), (5, 6, 1), (7,), (5, 1, 7)) (5, 6, 7) " :arglists '[[& [args]]]} broadcast_shapes (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "broadcast_shapes")))) (def ^{:doc ""} FPE_INVALID 8) (def ^{:doc " Return the Hanning window. The Hanning window is a taper formed by using a weighted cosine. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : ndarray, shape(M,) The window, with the maximum value normalized to one (the value one appears only if `M` is odd). See Also -------- bartlett, blackman, hamming, kaiser Notes ----- The Hanning window is defined as .. math:: w(n) = 0.5 - 0.5cos\\left(\\frac{2\\pi{n}}{M-1}\\right) \\qquad 0 \\leq n \\leq M-1 The Hanning was named for Julius von Hann, an Austrian meteorologist. It is also known as the Cosine Bell. Some authors prefer that it be called a Hann window, to help avoid confusion with the very similar Hamming window. Most references to the Hanning window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means \"removing the foot\", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. References ---------- .. [1] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York. .. [2] E.R. Kanasewich, \"Time Sequence Analysis in Geophysics\", The University of Alberta Press, 1975, pp. 106-108. .. [3] Wikipedia, \"Window function\", https://en.wikipedia.org/wiki/Window_function .. [4] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, \"Numerical Recipes\", Cambridge University Press, 1986, page 425. Examples -------- >>> np.hanning(12) array([0. , 0.07937323, 0.29229249, 0.57115742, 0.82743037, 0.97974649, 0.97974649, 0.82743037, 0.57115742, 0.29229249, 0.07937323, 0. ]) Plot the window and its frequency response: >>> import matplotlib.pyplot as plt >>> from numpy.fft import fft, fftshift >>> window = np.hanning(51) >>> plt.plot(window) [] >>> plt.title(\"Hann window\") Text(0.5, 1.0, 'Hann window') >>> plt.ylabel(\"Amplitude\") Text(0, 0.5, 'Amplitude') >>> plt.xlabel(\"Sample\") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure()
>>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 * np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [] >>> plt.title(\"Frequency response of the Hann window\") Text(0.5, 1.0, 'Frequency response of the Hann window') >>> plt.ylabel(\"Magnitude [dB]\") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel(\"Normalized frequency [cycles per sample]\") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> plt.axis('tight') ... >>> plt.show() " :arglists '[[M]]} hanning (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "hanning")))) (def ^{:doc "Python part of the warnings subsystem."} warnings (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "warnings")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned int``. :Character code: ``'I'`` :Canonical name: `numpy.uintc` :Alias on this platform: `numpy.uint32`: 32-bit unsigned integer (``0`` to ``4_294_967_295``)." :arglists '[[self & [args {:as kwargs}]]]} uintc (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uintc")))) (def ^{:doc " Return a new array with the specified shape. If the new array is larger than the original array, then the new array is filled with repeated copies of `a`. Note that this behavior is different from a.resize(new_shape) which fills with zeros instead of repeated copies of `a`. Parameters ---------- a : array_like Array to be resized. new_shape : int or tuple of int Shape of resized array. Returns ------- reshaped_array : ndarray The new array is formed from the data in the old array, repeated if necessary to fill out the required number of elements. The data are repeated in the order that they are stored in memory. See Also -------- np.reshape : Reshape an array without changing the total size. np.pad : Enlarge and pad an array. np.repeat: Repeat elements of an array. ndarray.resize : resize an array in-place. Notes ----- When the total size of the array does not change `~numpy.reshape` should be used. In most other cases either indexing (to reduce the size) or padding (to increase the size) may be a more appropriate solution. Warning: This functionality does **not** consider axes separately, i.e. it does not apply interpolation/extrapolation. It fills the return array with the required number of elements, taken from `a` as they are laid out in memory, disregarding strides and axes. (This is in case the new shape is smaller. For larger, see above.) This functionality is therefore not suitable to resize images, or data where each axis represents a separate and distinct entity. Examples -------- >>> a=np.array([[0,1],[2,3]]) >>> np.resize(a,(2,3)) array([[0, 1, 2], [3, 0, 1]]) >>> np.resize(a,(1,4)) array([[0, 1, 2, 3]]) >>> np.resize(a,(2,4)) array([[0, 1, 2, 3], [0, 1, 2, 3]]) " :arglists '[[& [args {:as kwargs}]]]} resize (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "resize")))) (def ^{:doc " Return the number of elements along a given axis. Parameters ---------- a : array_like Input data. axis : int, optional Axis along which the elements are counted. By default, give the total number of elements. Returns ------- element_count : int Number of elements along the specified axis. See Also -------- shape : dimensions of array ndarray.shape : dimensions of array ndarray.size : number of elements in array Examples -------- >>> a = np.array([[1,2,3],[4,5,6]]) >>> np.size(a) 6 >>> np.size(a,1) 3 >>> np.size(a,0) 2 " :arglists '[[& [args {:as kwargs}]]]} size (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "size")))) (def ^{:doc "Abstract base class of all unsigned integer scalar types." :arglists '[[self & [args {:as kwargs}]]]} unsignedinteger (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "unsignedinteger")))) (def ^{:doc "float_power(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) First array elements raised to powers from second array, element-wise. Raise each base in `x1` to the positionally-corresponding power in `x2`. `x1` and `x2` must be broadcastable to the same shape. This differs from the power function in that integers, float16, and float32 are promoted to floats with a minimum precision of float64 so that the result is always inexact. The intent is that the function will return a usable result for negative powers and seldom overflow for positive powers. .. versionadded:: 1.12.0 Parameters ---------- x1 : array_like The bases. x2 : array_like The exponents. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The bases in `x1` raised to the exponents in `x2`. This is a scalar if both `x1` and `x2` are scalars. See Also -------- power : power function that preserves type Examples -------- Cube each element in a list. >>> x1 = range(6) >>> x1 [0, 1, 2, 3, 4, 5] >>> np.float_power(x1, 3) array([ 0., 1., 8., 27., 64., 125.]) Raise the bases to different exponents. >>> x2 = [1.0, 2.0, 3.0, 3.0, 2.0, 1.0] >>> np.float_power(x1, x2) array([ 0., 1., 8., 27., 16., 5.]) The effect of broadcasting. >>> x2 = np.array([[1, 2, 3, 3, 2, 1], [1, 2, 3, 3, 2, 1]]) >>> x2 array([[1, 2, 3, 3, 2, 1], [1, 2, 3, 3, 2, 1]]) >>> np.float_power(x1, x2) array([[ 0., 1., 8., 27., 16., 5.], [ 0., 1., 8., 27., 16., 5.]])" :arglists '[[self & [args {:as kwargs}]]]} float_power (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "float_power")))) (def ^{:doc "logical_xor(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the truth value of x1 XOR x2, element-wise. Parameters ---------- x1, x2 : array_like Logical XOR is applied to the elements of `x1` and `x2`. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : bool or ndarray of bool Boolean result of the logical XOR operation applied to the elements of `x1` and `x2`; the shape is determined by broadcasting. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logical_and, logical_or, logical_not, bitwise_xor Examples -------- >>> np.logical_xor(True, False) True >>> np.logical_xor([True, True, False, False], [True, False, True, False]) array([False, True, True, False]) >>> x = np.arange(5) >>> np.logical_xor(x < 1, x > 3) array([ True, False, False, False, True]) Simple example showing support of broadcasting >>> np.logical_xor(0, np.eye(2)) array([[ True, False], [False, True]])" :arglists '[[self & [args {:as kwargs}]]]} logical_xor (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "logical_xor")))) (def ^{:doc " Set a Python function to be used when pretty printing arrays. Parameters ---------- f : function or None Function to be used to pretty print arrays. The function should expect a single array argument and return a string of the representation of the array. If None, the function is reset to the default NumPy function to print arrays. repr : bool, optional If True (default), the function for pretty printing (``__repr__``) is set, if False the function that returns the default string representation (``__str__``) is set. See Also -------- set_printoptions, get_printoptions Examples -------- >>> def pprint(arr): ... return 'HA! - What are you going to do now?' ... >>> np.set_string_function(pprint) >>> a = np.arange(10) >>> a HA! - What are you going to do now? >>> _ = a >>> # [0 1 2 3 4 5 6 7 8 9] We can reset the function to the default: >>> np.set_string_function(None) >>> a array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) `repr` affects either pretty printing or normal string representation. Note that ``__repr__`` is still affected by setting ``__str__`` because the width of each array element in the returned string becomes equal to the length of the result of ``__str__()``. >>> x = np.arange(4) >>> np.set_string_function(lambda x:'random', repr=False) >>> x.__str__() 'random' >>> x.__repr__() 'array([0, 1, 2, 3])' " :arglists '[[f & [{repr :repr}]] [f]]} set_string_function (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "set_string_function")))) (def ^{:doc " Returns True if two arrays are element-wise equal within a tolerance. The tolerance values are positive, typically very small numbers. The relative difference (`rtol` * abs(`b`)) and the absolute difference `atol` are added together to compare against the absolute difference between `a` and `b`. NaNs are treated as equal if they are in the same place and if ``equal_nan=True``. Infs are treated as equal if they are in the same place and of the same sign in both arrays. Parameters ---------- a, b : array_like Input arrays to compare. rtol : float The relative tolerance parameter (see Notes). atol : float The absolute tolerance parameter (see Notes). equal_nan : bool Whether to compare NaN's as equal. If True, NaN's in `a` will be considered equal to NaN's in `b` in the output array. .. versionadded:: 1.10.0 Returns ------- allclose : bool Returns True if the two arrays are equal within the given tolerance; False otherwise. See Also -------- isclose, all, any, equal Notes ----- If the following equation is element-wise True, then allclose returns True. absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`)) The above equation is not symmetric in `a` and `b`, so that ``allclose(a, b)`` might be different from ``allclose(b, a)`` in some rare cases. The comparison of `a` and `b` uses standard broadcasting, which means that `a` and `b` need not have the same shape in order for ``allclose(a, b)`` to evaluate to True. The same is true for `equal` but not `array_equal`. `allclose` is not defined for non-numeric data types. Examples -------- >>> np.allclose([1e10,1e-7], [1.00001e10,1e-8]) False >>> np.allclose([1e10,1e-8], [1.00001e10,1e-9]) True >>> np.allclose([1e10,1e-8], [1.0001e10,1e-9]) False >>> np.allclose([1.0, np.nan], [1.0, np.nan]) False >>> np.allclose([1.0, np.nan], [1.0, np.nan], equal_nan=True) True " :arglists '[[& [args {:as kwargs}]]]} allclose (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "allclose")))) (def ^{:doc ""} Inf ##Inf) (def ^{:doc " Return the cumulative product over the given axis. See Also -------- cumprod : equivalent function; see for details. " :arglists '[[& [args {:as kwargs}]]]} cumproduct (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cumproduct")))) (def ^{:doc " Return the minimum of an array or minimum along an axis. Parameters ---------- a : array_like Input data. axis : None or int or tuple of ints, optional Axis or axes along which to operate. By default, flattened input is used. .. versionadded:: 1.7.0 If this is a tuple of ints, the minimum is selected over multiple axes, instead of a single axis or all the axes as before. out : ndarray, optional Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See :ref:`ufuncs-output-type` for more details. 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 input array. If the default value is passed, then `keepdims` will not be passed through to the `amin` method of sub-classes of `ndarray`, however any non-default value will be. If the sub-class' method does not implement `keepdims` any exceptions will be raised. initial : scalar, optional The maximum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.15.0 where : array_like of bool, optional Elements to compare for the minimum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.17.0 Returns ------- amin : ndarray or scalar Minimum of `a`. If `axis` is None, the result is a scalar value. If `axis` is given, the result is an array of dimension ``a.ndim - 1``. See Also -------- amax : The maximum value of an array along a given axis, propagating any NaNs. nanmin : The minimum value of an array along a given axis, ignoring any NaNs. minimum : Element-wise minimum of two arrays, propagating any NaNs. fmin : Element-wise minimum of two arrays, ignoring any NaNs. argmin : Return the indices of the minimum values. nanmax, maximum, fmax Notes ----- NaN values are propagated, that is if at least one item is NaN, the corresponding min value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmin. Don't use `amin` for element-wise comparison of 2 arrays; when ``a.shape[0]`` is 2, ``minimum(a[0], a[1])`` is faster than ``amin(a, axis=0)``. Examples -------- >>> a = np.arange(4).reshape((2,2)) >>> a array([[0, 1], [2, 3]]) >>> np.amin(a) # Minimum of the flattened array 0 >>> np.amin(a, axis=0) # Minima along the first axis array([0, 1]) >>> np.amin(a, axis=1) # Minima along the second axis array([0, 2]) >>> np.amin(a, where=[False, True], initial=10, axis=0) array([10, 1]) >>> b = np.arange(5, dtype=float) >>> b[2] = np.NaN >>> np.amin(b) nan >>> np.amin(b, where=~np.isnan(b), initial=10) 0.0 >>> np.nanmin(b) 0.0 >>> np.min([[-50], [10]], axis=-1, initial=0) array([-50, 0]) Notice that the initial value is used as one of the elements for which the minimum is determined, unlike for the default argument Python's max function, which is only used for empty iterables. Notice that this isn't the same as Python's ``default`` argument. >>> np.min([6], initial=5) 5 >>> min([6], default=5) 6 " :arglists '[[& [args {:as kwargs}]]]} amin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "amin")))) (def ^{:doc " Replace NaN with zero and infinity with large finite numbers (default behaviour) or with the numbers defined by the user using the `nan`, `posinf` and/or `neginf` keywords. If `x` is inexact, NaN is replaced by zero or by the user defined value in `nan` keyword, infinity is replaced by the largest finite floating point values representable by ``x.dtype`` or by the user defined value in `posinf` keyword and -infinity is replaced by the most negative finite floating point values representable by ``x.dtype`` or by the user defined value in `neginf` keyword. For complex dtypes, the above is applied to each of the real and imaginary components of `x` separately. If `x` is not inexact, then no replacements are made. Parameters ---------- x : scalar or array_like Input data. copy : bool, optional Whether to create a copy of `x` (True) or to replace values in-place (False). The in-place operation only occurs if casting to an array does not require a copy. Default is True. .. versionadded:: 1.13 nan : int, float, optional Value to be used to fill NaN values. If no value is passed then NaN values will be replaced with 0.0. .. versionadded:: 1.17 posinf : int, float, optional Value to be used to fill positive infinity values. If no value is passed then positive infinity values will be replaced with a very large number. .. versionadded:: 1.17 neginf : int, float, optional Value to be used to fill negative infinity values. If no value is passed then negative infinity values will be replaced with a very small (or negative) number. .. versionadded:: 1.17 Returns ------- out : ndarray `x`, with the non-finite values replaced. If `copy` is False, this may be `x` itself. See Also -------- isinf : Shows which elements are positive or negative infinity. isneginf : Shows which elements are negative infinity. isposinf : Shows which elements are positive infinity. isnan : Shows which elements are Not a Number (NaN). isfinite : Shows which elements are finite (not NaN, not infinity) Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Examples -------- >>> np.nan_to_num(np.inf) 1.7976931348623157e+308 >>> np.nan_to_num(-np.inf) -1.7976931348623157e+308 >>> np.nan_to_num(np.nan) 0.0 >>> x = np.array([np.inf, -np.inf, np.nan, -128, 128]) >>> np.nan_to_num(x) array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary -1.28000000e+002, 1.28000000e+002]) >>> np.nan_to_num(x, nan=-9999, posinf=33333333, neginf=33333333) array([ 3.3333333e+07, 3.3333333e+07, -9.9990000e+03, -1.2800000e+02, 1.2800000e+02]) >>> y = np.array([complex(np.inf, np.nan), np.nan, complex(np.nan, np.inf)]) array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary -1.28000000e+002, 1.28000000e+002]) >>> np.nan_to_num(y) array([ 1.79769313e+308 +0.00000000e+000j, # may vary 0.00000000e+000 +0.00000000e+000j, 0.00000000e+000 +1.79769313e+308j]) >>> np.nan_to_num(y, nan=111111, posinf=222222) array([222222.+111111.j, 111111. +0.j, 111111.+222222.j]) " :arglists '[[& [args {:as kwargs}]]]} nan_to_num (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nan_to_num")))) (def ^{:doc " Return the indices to access the main diagonal of an array. This returns a tuple of indices that can be used to access the main diagonal of an array `a` with ``a.ndim >= 2`` dimensions and shape (n, n, ..., n). For ``a.ndim = 2`` this is the usual diagonal, for ``a.ndim > 2`` this is the set of indices to access ``a[i, i, ..., i]`` for ``i = [0..n-1]``. Parameters ---------- n : int The size, along each dimension, of the arrays for which the returned indices can be used. ndim : int, optional The number of dimensions. See Also -------- diag_indices_from Notes ----- .. versionadded:: 1.4.0 Examples -------- Create a set of indices to access the diagonal of a (4, 4) array: >>> di = np.diag_indices(4) >>> di (array([0, 1, 2, 3]), array([0, 1, 2, 3])) >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) >>> a[di] = 100 >>> a array([[100, 1, 2, 3], [ 4, 100, 6, 7], [ 8, 9, 100, 11], [ 12, 13, 14, 100]]) Now, we create indices to manipulate a 3-D array: >>> d3 = np.diag_indices(2, 3) >>> d3 (array([0, 1]), array([0, 1]), array([0, 1])) And use it to set the diagonal of an array of zeros to 1: >>> a = np.zeros((2, 2, 2), dtype=int) >>> a[d3] = 1 >>> a array([[[1, 0], [0, 0]], [[0, 0], [0, 1]]]) " :arglists '[[n & [{ndim :ndim}]] [n]]} diag_indices (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "diag_indices")))) (def ^{:doc " Check whether some values are true. Refer to `any` for full documentation. See Also -------- any : equivalent function; see for details. " :arglists '[[& [args {:as kwargs}]]]} sometrue (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sometrue")))) (def ^{:doc "A unicode string. When used in arrays, this type strips trailing null codepoints. Unlike the builtin `str`, this supports the :ref:`python:bufferobjects`, exposing its contents as UCS4: >>> m = memoryview(np.str_(\"abc\")) >>> m.format '3w' >>> m.tobytes() b'a\\x00\\x00\\x00b\\x00\\x00\\x00c\\x00\\x00\\x00' :Character code: ``'U'`` :Alias: `numpy.unicode_`" :arglists '[[self & [args {:as kwargs}]]]} str_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "str_")))) (def ^{:doc "Complex number type composed of two single-precision floating-point numbers. :Character code: ``'F'`` :Canonical name: `numpy.csingle` :Alias: `numpy.singlecomplex` :Alias on this platform: `numpy.complex64`: Complex number type composed of 2 32-bit-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} singlecomplex (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "singlecomplex")))) (def ^{:doc " Return the current print options. Returns ------- print_opts : dict Dictionary of current print options with keys - precision : int - threshold : int - edgeitems : int - linewidth : int - suppress : bool - nanstr : str - infstr : str - formatter : dict of callables - sign : str For a full description of these options, see `set_printoptions`. See Also -------- set_printoptions, printoptions, set_string_function " :arglists '[[]]} get_printoptions (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "get_printoptions")))) (def ^{:doc "sinh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Hyperbolic sine, element-wise. Equivalent to ``1/2 * (np.exp(x) - np.exp(-x))`` or ``-1j * np.sin(1j*x)``. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The corresponding hyperbolic sine values. This is a scalar if `x` is a scalar. Notes ----- If `out` is provided, the function writes the result into it, and returns a reference to `out`. (See Examples) References ---------- M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972, pg. 83. Examples -------- >>> np.sinh(0) 0.0 >>> np.sinh(np.pi*1j/2) 1j >>> np.sinh(np.pi*1j) # (exact value is 0) 1.2246063538223773e-016j >>> # Discrepancy due to vagaries of floating point arithmetic. >>> # Example of providing the optional output parameter >>> out1 = np.array([0], dtype='d') >>> out2 = np.sinh([0.1], out1) >>> out2 is out1 True >>> # Example of ValueError due to provision of shape mis-matched `out` >>> np.sinh(np.zeros((3,3)),np.zeros((2,2))) Traceback (most recent call last): File \"\", line 1, in ValueError: operands could not be broadcast together with shapes (3,3) (2,2)" :arglists '[[self & [args {:as kwargs}]]]} sinh (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sinh")))) (def ^{:doc " Return the indices for the upper-triangle of arr. See `triu_indices` for full details. Parameters ---------- arr : ndarray, shape(N, N) The indices will be valid for square arrays. k : int, optional Diagonal offset (see `triu` for details). Returns ------- triu_indices_from : tuple, shape(2) of ndarray, shape(N) Indices for the upper-triangle of `arr`. See Also -------- triu_indices, triu Notes ----- .. versionadded:: 1.4.0 " :arglists '[[& [args {:as kwargs}]]]} triu_indices_from (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "triu_indices_from")))) (def ^{:doc ""} __doc__ " NumPy ===== Provides 1. An array object of arbitrary homogeneous items 2. Fast mathematical operations over arrays 3. Linear Algebra, Fourier Transforms, Random Number Generation How to use the documentation ---------------------------- Documentation is available in two forms: docstrings provided with the code, and a loose standing reference guide, available from `the NumPy homepage `_. We recommend exploring the docstrings using `IPython `_, an advanced Python shell with TAB-completion and introspection capabilities. See below for further instructions. The docstring examples assume that `numpy` has been imported as `np`:: >>> import numpy as np Code snippets are indicated by three greater-than signs:: >>> x = 42 >>> x = x + 1 Use the built-in ``help`` function to view a function's docstring:: >>> help(np.sort) ... # doctest: +SKIP For some objects, ``np.info(obj)`` may provide additional help. This is particularly true if you see the line \"Help on ufunc object:\" at the top of the help() page. Ufuncs are implemented in C, not Python, for speed. The native Python help() does not know how to view their help, but our np.info() function does. To search for documents containing a keyword, do:: >>> np.lookfor('keyword') ... # doctest: +SKIP General-purpose documents like a glossary and help on the basic concepts of numpy are available under the ``doc`` sub-module:: >>> from numpy import doc >>> help(doc) ... # doctest: +SKIP Available subpackages --------------------- doc Topical documentation on broadcasting, indexing, etc. lib Basic functions used by several sub-packages. random Core Random Tools linalg Core Linear Algebra Tools fft Core FFT routines polynomial Polynomial tools testing NumPy testing tools f2py Fortran to Python Interface Generator. distutils Enhancements to distutils with support for Fortran compilers support and more. Utilities --------- test Run numpy unittests show_config Show numpy build configuration dual Overwrite certain functions with high-performance SciPy tools. Note: `numpy.dual` is deprecated. Use the functions from NumPy or Scipy directly instead of importing them from `numpy.dual`. matlib Make everything matrices. __version__ NumPy version string Viewing documentation using IPython ----------------------------------- Start IPython with the NumPy profile (``ipython -p numpy``), which will import `numpy` under the alias `np`. Then, use the ``cpaste`` command to paste examples into the shell. To see which functions are available in `numpy`, type ``np.`` (where ```` refers to the TAB key), or use ``np.*cos*?`` (where ```` refers to the ENTER key) to narrow down the list. To view the docstring for a function, use ``np.cos?`` (to view the docstring) and ``np.cos??`` (to view the source code). Copies vs. in-place operation ----------------------------- Most of the functions in `numpy` return a copy of the array argument (e.g., `np.sort`). In-place versions of these functions are often available as array methods, i.e. ``x = np.array([1,2,3]); x.sort()``. Exceptions to this rule are documented. ") (def ^{:doc " Rotate an array by 90 degrees in the plane specified by axes. Rotation direction is from the first towards the second axis. Parameters ---------- m : array_like Array of two or more dimensions. k : integer Number of times the array is rotated by 90 degrees. axes: (2,) array_like The array is rotated in the plane defined by the axes. Axes must be different. .. versionadded:: 1.12.0 Returns ------- y : ndarray A rotated view of `m`. See Also -------- flip : Reverse the order of elements in an array along the given axis. fliplr : Flip an array horizontally. flipud : Flip an array vertically. Notes ----- rot90(m, k=1, axes=(1,0)) is the reverse of rot90(m, k=1, axes=(0,1)) rot90(m, k=1, axes=(1,0)) is equivalent to rot90(m, k=-1, axes=(0,1)) Examples -------- >>> m = np.array([[1,2],[3,4]], int) >>> m array([[1, 2], [3, 4]]) >>> np.rot90(m) array([[2, 4], [1, 3]]) >>> np.rot90(m, 2) array([[4, 3], [2, 1]]) >>> m = np.arange(8).reshape((2,2,2)) >>> np.rot90(m, 1, (1,2)) array([[[1, 3], [0, 2]], [[5, 7], [4, 6]]]) " :arglists '[[& [args {:as kwargs}]]]} rot90 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "rot90")))) (def ^{:doc " Split array into multiple sub-arrays along the 3rd axis (depth). Please refer to the `split` documentation. `dsplit` is equivalent to `split` with ``axis=2``, the array is always split along the third axis provided the array dimension is greater than or equal to 3. See Also -------- split : Split an array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(16.0).reshape(2, 2, 4) >>> x array([[[ 0., 1., 2., 3.], [ 4., 5., 6., 7.]], [[ 8., 9., 10., 11.], [12., 13., 14., 15.]]]) >>> np.dsplit(x, 2) [array([[[ 0., 1.], [ 4., 5.]], [[ 8., 9.], [12., 13.]]]), array([[[ 2., 3.], [ 6., 7.]], [[10., 11.], [14., 15.]]])] >>> np.dsplit(x, np.array([3, 6])) [array([[[ 0., 1., 2.], [ 4., 5., 6.]], [[ 8., 9., 10.], [12., 13., 14.]]]), array([[[ 3.], [ 7.]], [[11.], [15.]]]), array([], shape=(2, 2, 0), dtype=float64)] " :arglists '[[& [args {:as kwargs}]]]} dsplit (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "dsplit")))) (def ^{:doc "equal(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return (x1 == x2) element-wise. Parameters ---------- x1, x2 : array_like Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array, element-wise comparison of `x1` and `x2`. Typically of type bool, unless ``dtype=object`` is passed. This is a scalar if both `x1` and `x2` are scalars. See Also -------- not_equal, greater_equal, less_equal, greater, less Examples -------- >>> np.equal([0, 1, 3], np.arange(3)) array([ True, True, False]) What is compared are values, not types. So an int (1) and an array of length one can evaluate as True: >>> np.equal(1, np.ones(1)) array([ True]) The ``==`` operator can be used as a shorthand for ``np.equal`` on ndarrays. >>> a = np.array([2, 4, 6]) >>> b = np.array([2, 4, 2]) >>> a == b array([ True, True, False])" :arglists '[[self & [args {:as kwargs}]]]} equal (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "equal")))) (def ^{:doc ""} CLIP 0) (def ^{:doc "Broadcast an array to a new shape. Parameters ---------- array : array_like The array to broadcast. shape : tuple The shape of the desired array. 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). Returns ------- broadcast : array A readonly view on the original array with the given shape. It is typically not contiguous. Furthermore, more than one element of a broadcasted array may refer to a single memory location. Raises ------ ValueError If the array is not compatible with the new shape according to NumPy's broadcasting rules. See Also -------- broadcast broadcast_arrays broadcast_shapes Notes ----- .. versionadded:: 1.10.0 Examples -------- >>> x = np.array([1, 2, 3]) >>> np.broadcast_to(x, (3, 3)) array([[1, 2, 3], [1, 2, 3], [1, 2, 3]]) " :arglists '[[& [args {:as kwargs}]]]} broadcast_to (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "broadcast_to")))) (def ^{:doc " einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe', optimize=False) 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 einops: similar verbose interface is provided by `einops `_ package to cover additional operations: transpose, reshape/flatten, repeat/tile, squeeze/unsqueeze and reductions. opt_einsum: `opt_einsum `_ optimizes contraction order for einsum-like expressions in backend-agnostic manner. 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) `. 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) `. Repeated subscript labels in one operand take the diagonal. For example, ``np.einsum('ii', a)`` is equivalent to :py:func:`np.trace(a) `. 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) `, and ``np.einsum('ii->i', a)`` is like :py:func:`np.diag(a) `. 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) ` and ``np.einsum('ii->i', a)`` will return a writeable view of the diagonal of a 2D array. .. versionadded:: 1.12.0 Added the ``optimize`` argument which will optimize the contraction order of an einsum expression. For a contraction with three or more operands this can greatly increase the computational efficiency at the cost of a larger memory footprint during computation. Typically a 'greedy' algorithm is applied which empirical tests have shown returns the optimal path in the majority of cases. In some cases 'optimal' will return the superlative path through a more expensive, exhaustive search. For iterative calculations it may be advisable to calculate the optimal path once and reuse that path by supplying it as an argument. An example is given below. See :py:func:`numpy.einsum_path` for more details. 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]]) Chained array operations. For more complicated contractions, speed ups might be achieved by repeatedly computing a 'greedy' path or pre-computing the 'optimal' path and repeatedly applying it, using an `einsum_path` insertion (since version 1.12.0). Performance improvements can be particularly significant with larger arrays: >>> a = np.ones(64).reshape(2,4,8) Basic `einsum`: ~1520ms (benchmarked on 3.1GHz Intel i5.) >>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a) Sub-optimal `einsum` (due to repeated path calculation time): ~330ms >>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='optimal') Greedy `einsum` (faster optimal path approximation): ~160ms >>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='greedy') Optimal `einsum` (best usage pattern in some use cases): ~110ms >>> path = np.einsum_path('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='optimal')[0] >>> for iteration in range(500): ... _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize=path) " :arglists '[[& [args {:as kwargs}]]]} einsum (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "einsum")))) (def ^{:doc ""} numarray "removed") (def ^{:doc "A byte string. When used in arrays, this type strips trailing null bytes. :Character code: ``'S'`` :Alias: `numpy.string_`" :arglists '[[self & [args {:as kwargs}]]]} bytes0 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bytes0")))) (def ^{:doc ""} little_endian true) (def ^{:doc "Visible deprecation warning. By default, python will not show deprecation warnings, so this class can be used when a very visible warning is helpful, for example because the usage is most likely a user bug. " :arglists '[[self & [args {:as kwargs}]]]} VisibleDeprecationWarning (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "VisibleDeprecationWarning")))) (def ^{:doc " Axis supplied was invalid. " :arglists '[[self axis & [{ndim :ndim, msg_prefix :msg_prefix}]] [self axis & [{ndim :ndim}]] [self axis]]} AxisError (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "AxisError")))) (def ^{:doc " Apply a function to 1-D slices along the given axis. Execute `func1d(a, *args, **kwargs)` where `func1d` operates on 1-D arrays and `a` is a 1-D slice of `arr` along `axis`. This is equivalent to (but faster than) the following use of `ndindex` and `s_`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of indices:: Ni, Nk = a.shape[:axis], a.shape[axis+1:] for ii in ndindex(Ni): for kk in ndindex(Nk): f = func1d(arr[ii + s_[:,] + kk]) Nj = f.shape for jj in ndindex(Nj): out[ii + jj + kk] = f[jj] Equivalently, eliminating the inner loop, this can be expressed as:: Ni, Nk = a.shape[:axis], a.shape[axis+1:] for ii in ndindex(Ni): for kk in ndindex(Nk): out[ii + s_[...,] + kk] = func1d(arr[ii + s_[:,] + kk]) Parameters ---------- func1d : function (M,) -> (Nj...) This function should accept 1-D arrays. It is applied to 1-D slices of `arr` along the specified axis. axis : integer Axis along which `arr` is sliced. arr : ndarray (Ni..., M, Nk...) Input array. args : any Additional arguments to `func1d`. kwargs : any Additional named arguments to `func1d`. .. versionadded:: 1.9.0 Returns ------- out : ndarray (Ni..., Nj..., Nk...) The output array. The shape of `out` is identical to the shape of `arr`, except along the `axis` dimension. This axis is removed, and replaced with new dimensions equal to the shape of the return value of `func1d`. So if `func1d` returns a scalar `out` will have one fewer dimensions than `arr`. See Also -------- apply_over_axes : Apply a function repeatedly over multiple axes. Examples -------- >>> def my_func(a): ... \"\"\"Average first and last element of a 1-D array\"\"\" ... return (a[0] + a[-1]) * 0.5 >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]]) >>> np.apply_along_axis(my_func, 0, b) array([4., 5., 6.]) >>> np.apply_along_axis(my_func, 1, b) array([2., 5., 8.]) For a function that returns a 1D array, the number of dimensions in `outarr` is the same as `arr`. >>> b = np.array([[8,1,7], [4,3,9], [5,2,6]]) >>> np.apply_along_axis(sorted, 1, b) array([[1, 7, 8], [3, 4, 9], [2, 5, 6]]) For a function that returns a higher dimensional array, those dimensions are inserted in place of the `axis` dimension. >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]]) >>> np.apply_along_axis(np.diag, -1, b) array([[[1, 0, 0], [0, 2, 0], [0, 0, 3]], [[4, 0, 0], [0, 5, 0], [0, 0, 6]], [[7, 0, 0], [0, 8, 0], [0, 0, 9]]]) " :arglists '[[& [args {:as kwargs}]]]} apply_along_axis (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "apply_along_axis")))) (def ^{:doc "nextafter(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the next floating-point value after x1 towards x2, element-wise. Parameters ---------- x1 : array_like Values to find the next representable value of. x2 : array_like The direction where to look for the next representable value of `x1`. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar The next representable values of `x1` in the direction of `x2`. This is a scalar if both `x1` and `x2` are scalars. Examples -------- >>> eps = np.finfo(np.float64).eps >>> np.nextafter(1, 2) == eps + 1 True >>> np.nextafter([1, 2], [2, 1]) == [eps + 1, 2 - eps] array([ True, True])" :arglists '[[self & [args {:as kwargs}]]]} nextafter (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nextafter")))) (def ^{:doc " Return the cumulative sum of the elements along a given axis. Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative sum is computed. The default (None) is to compute the cumsum over the flattened array. dtype : dtype, optional Type of the returned array and of the accumulator in which the elements are summed. If `dtype` is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. Returns ------- cumsum_along_axis : ndarray. A new array holding the result is returned unless `out` is specified, in which case a reference to `out` is returned. The result has the same size as `a`, and the same shape as `a` if `axis` is not None or `a` is a 1-d array. See Also -------- sum : Sum array elements. trapz : Integration of array values using the composite trapezoidal rule. diff : Calculate the n-th discrete difference along given axis. Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow. Examples -------- >>> a = np.array([[1,2,3], [4,5,6]]) >>> a array([[1, 2, 3], [4, 5, 6]]) >>> np.cumsum(a) array([ 1, 3, 6, 10, 15, 21]) >>> np.cumsum(a, dtype=float) # specifies type of output value(s) array([ 1., 3., 6., 10., 15., 21.]) >>> np.cumsum(a,axis=0) # sum over rows for each of the 3 columns array([[1, 2, 3], [5, 7, 9]]) >>> np.cumsum(a,axis=1) # sum over columns for each of the 2 rows array([[ 1, 3, 6], [ 4, 9, 15]]) " :arglists '[[& [args {:as kwargs}]]]} cumsum (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cumsum")))) (def ^{:doc " Return the Bartlett window. The Bartlett window is very similar to a triangular window, except that the end points are at zero. It is often used in signal processing for tapering a signal, without generating too much ripple in the frequency domain. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : array The triangular window, with the maximum value normalized to one (the value one appears only if the number of samples is odd), with the first and last samples equal to zero. See Also -------- blackman, hamming, hanning, kaiser Notes ----- The Bartlett window is defined as .. math:: w(n) = \\frac{2}{M-1} \\left( \\frac{M-1}{2} - \\left|n - \\frac{M-1}{2}\\right| \\right) Most references to the Bartlett window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. Note that convolution with this window produces linear interpolation. It is also known as an apodization (which means\"removing the foot\", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. The fourier transform of the Bartlett is the product of two sinc functions. Note the excellent discussion in Kanasewich. References ---------- .. [1] M.S. Bartlett, \"Periodogram Analysis and Continuous Spectra\", Biometrika 37, 1-16, 1950. .. [2] E.R. Kanasewich, \"Time Sequence Analysis in Geophysics\", The University of Alberta Press, 1975, pp. 109-110. .. [3] A.V. Oppenheim and R.W. Schafer, \"Discrete-Time Signal Processing\", Prentice-Hall, 1999, pp. 468-471. .. [4] Wikipedia, \"Window function\", https://en.wikipedia.org/wiki/Window_function .. [5] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, \"Numerical Recipes\", Cambridge University Press, 1986, page 429. Examples -------- >>> import matplotlib.pyplot as plt >>> np.bartlett(12) array([ 0. , 0.18181818, 0.36363636, 0.54545455, 0.72727273, # may vary 0.90909091, 0.90909091, 0.72727273, 0.54545455, 0.36363636, 0.18181818, 0. ]) Plot the window and its frequency response (requires SciPy and matplotlib): >>> from numpy.fft import fft, fftshift >>> window = np.bartlett(51) >>> plt.plot(window) [] >>> plt.title(\"Bartlett window\") Text(0.5, 1.0, 'Bartlett window') >>> plt.ylabel(\"Amplitude\") Text(0, 0.5, 'Amplitude') >>> plt.xlabel(\"Sample\") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure()
>>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 * np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [] >>> plt.title(\"Frequency response of Bartlett window\") Text(0.5, 1.0, 'Frequency response of Bartlett window') >>> plt.ylabel(\"Magnitude [dB]\") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel(\"Normalized frequency [cycles per sample]\") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> _ = plt.axis('tight') >>> plt.show() " :arglists '[[M]]} bartlett (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bartlett")))) (def ^{:doc "Boolean type (True or False), stored as a byte. .. warning:: The :class:`bool_` type is not a subclass of the :class:`int_` type (the :class:`bool_` is not even a number type). This is different than Python's default implementation of :class:`bool` as a sub-class of :class:`int`. :Character code: ``'?'`` :Alias: `numpy.bool8`" :arglists '[[self & [args {:as kwargs}]]]} bool8 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bool8")))) (def ^{:doc " Compute the arithmetic mean along the specified axis, ignoring NaNs. Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. `float64` intermediate and return values are used for integer inputs. For all-NaN slices, NaN is returned and a `RuntimeWarning` is raised. .. versionadded:: 1.8.0 Parameters ---------- a : array_like Array containing numbers whose mean is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the means are computed. The default is to compute the mean of the flattened array. dtype : data-type, optional Type to use in computing the mean. For integer inputs, the default is `float64`; for inexact inputs, it is the same as the input dtype. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. 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 `a`. If the value is anything but the default, then `keepdims` will be passed through to the `mean` or `sum` methods of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. Returns ------- m : ndarray, see dtype parameter above If `out=None`, returns a new array containing the mean values, otherwise a reference to the output array is returned. Nan is returned for slices that contain only NaNs. See Also -------- average : Weighted average mean : Arithmetic mean taken while not ignoring NaNs var, nanvar Notes ----- The arithmetic mean is the sum of the non-NaN elements along the axis divided by the number of non-NaN elements. Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for `float32`. Specifying a higher-precision accumulator using the `dtype` keyword can alleviate this issue. Examples -------- >>> a = np.array([[1, np.nan], [3, 4]]) >>> np.nanmean(a) 2.6666666666666665 >>> np.nanmean(a, axis=0) array([2., 4.]) >>> np.nanmean(a, axis=1) array([1., 3.5]) # may vary " :arglists '[[& [args {:as kwargs}]]]} nanmean (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanmean")))) (def ^{:doc "" :arglists '[[self & [args {:as kwargs}]]]} dtype (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "dtype")))) (def ^{:doc " Return numbers spaced evenly on a log scale (a geometric progression). This is similar to `logspace`, but with endpoints specified directly. Each output sample is a constant multiple of the previous. .. versionchanged:: 1.16.0 Non-scalar `start` and `stop` are now supported. Parameters ---------- start : array_like The starting value of the sequence. stop : array_like The final value of the sequence, unless `endpoint` is False. In that case, ``num + 1`` values are spaced over the interval in log-space, of which all but the last (a sequence of length `num`) are returned. num : integer, optional Number of samples to generate. Default is 50. endpoint : boolean, optional If true, `stop` is the last sample. Otherwise, it is not included. Default is True. dtype : dtype The type of the output array. If `dtype` is not given, the data type is inferred from `start` and `stop`. The inferred dtype will never be an integer; `float` is chosen even if the arguments would produce an array of integers. axis : int, optional The axis in the result to store the samples. Relevant only if start or stop are array-like. By default (0), the samples will be along a new axis inserted at the beginning. Use -1 to get an axis at the end. .. versionadded:: 1.16.0 Returns ------- samples : ndarray `num` samples, equally spaced on a log scale. See Also -------- logspace : Similar to geomspace, but with endpoints specified using log and base. linspace : Similar to geomspace, but with arithmetic instead of geometric progression. arange : Similar to linspace, with the step size specified instead of the number of samples. Notes ----- If the inputs or dtype are complex, the output will follow a logarithmic spiral in the complex plane. (There are an infinite number of spirals passing through two points; the output will follow the shortest such path.) Examples -------- >>> np.geomspace(1, 1000, num=4) array([ 1., 10., 100., 1000.]) >>> np.geomspace(1, 1000, num=3, endpoint=False) array([ 1., 10., 100.]) >>> np.geomspace(1, 1000, num=4, endpoint=False) array([ 1. , 5.62341325, 31.6227766 , 177.827941 ]) >>> np.geomspace(1, 256, num=9) array([ 1., 2., 4., 8., 16., 32., 64., 128., 256.]) Note that the above may not produce exact integers: >>> np.geomspace(1, 256, num=9, dtype=int) array([ 1, 2, 4, 7, 16, 32, 63, 127, 256]) >>> np.around(np.geomspace(1, 256, num=9)).astype(int) array([ 1, 2, 4, 8, 16, 32, 64, 128, 256]) Negative, decreasing, and complex inputs are allowed: >>> np.geomspace(1000, 1, num=4) array([1000., 100., 10., 1.]) >>> np.geomspace(-1000, -1, num=4) array([-1000., -100., -10., -1.]) >>> np.geomspace(1j, 1000j, num=4) # Straight line array([0. +1.j, 0. +10.j, 0. +100.j, 0.+1000.j]) >>> np.geomspace(-1+0j, 1+0j, num=5) # Circle array([-1.00000000e+00+1.22464680e-16j, -7.07106781e-01+7.07106781e-01j, 6.12323400e-17+1.00000000e+00j, 7.07106781e-01+7.07106781e-01j, 1.00000000e+00+0.00000000e+00j]) Graphical illustration of ``endpoint`` parameter: >>> import matplotlib.pyplot as plt >>> N = 10 >>> y = np.zeros(N) >>> plt.semilogx(np.geomspace(1, 1000, N, endpoint=True), y + 1, 'o') [] >>> plt.semilogx(np.geomspace(1, 1000, N, endpoint=False), y + 2, 'o') [] >>> plt.axis([0.5, 2000, 0, 3]) [0.5, 2000, 0, 3] >>> plt.grid(True, color='0.7', linestyle='-', which='both', axis='both') >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} geomspace (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "geomspace")))) (def ^{:doc " Round an array to the given number of decimals. See Also -------- around : equivalent function; see for details. " :arglists '[[& [args {:as kwargs}]]]} round (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "round")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned long``. :Character code: ``'L'`` :Canonical name: `numpy.uint` :Alias on this platform: `numpy.uint64`: 64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``). :Alias on this platform: `numpy.uintp`: Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``." :arglists '[[self & [args {:as kwargs}]]]} uintp (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "uintp")))) (def ^{:doc "Unsigned integer type, compatible with C ``unsigned char``. :Character code: ``'B'`` :Canonical name: `numpy.ubyte` :Alias on this platform: `numpy.uint8`: 8-bit unsigned integer (``0`` to ``255``)." :arglists '[[self & [args {:as kwargs}]]]} ubyte (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ubyte")))) (def ^{:doc " Upper triangle of an array. Return a copy of an array with the elements below the `k`-th diagonal zeroed. Please refer to the documentation for `tril` for further details. See Also -------- tril : lower triangle of an array Examples -------- >>> np.triu([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1) array([[ 1, 2, 3], [ 4, 5, 6], [ 0, 8, 9], [ 0, 0, 12]]) " :arglists '[[& [args {:as kwargs}]]]} triu (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "triu")))) (def ^{:doc " Create a two-dimensional array with the flattened input as a diagonal. Parameters ---------- v : array_like Input data, which is flattened and set as the `k`-th diagonal of the output. k : int, optional Diagonal to set; 0, the default, corresponds to the \"main\" diagonal, a positive (negative) `k` giving the number of the diagonal above (below) the main. Returns ------- out : ndarray The 2-D output array. See Also -------- diag : MATLAB work-alike for 1-D and 2-D arrays. diagonal : Return specified diagonals. trace : Sum along diagonals. Examples -------- >>> np.diagflat([[1,2], [3,4]]) array([[1, 0, 0, 0], [0, 2, 0, 0], [0, 0, 3, 0], [0, 0, 0, 4]]) >>> np.diagflat([1,2], 1) array([[0, 1, 0], [0, 0, 2], [0, 0, 0]]) " :arglists '[[& [args {:as kwargs}]]]} diagflat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "diagflat")))) (def ^{:doc "Any Python object. :Character code: ``'O'``" :arglists '[[self & [args {:as kwargs}]]]} object_ (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "object_")))) (def ^{:doc " Return True if x is a not complex type or an array of complex numbers. The type of the input is checked, not the value. So even if the input has an imaginary part equal to zero, `isrealobj` evaluates to False if the data type is complex. Parameters ---------- x : any The input can be of any type and shape. Returns ------- y : bool The return value, False if `x` is of a complex type. See Also -------- iscomplexobj, isreal Examples -------- >>> np.isrealobj(1) True >>> np.isrealobj(1+0j) False >>> np.isrealobj([3, 1+0j, True]) False " :arglists '[[& [args {:as kwargs}]]]} isrealobj (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "isrealobj")))) (def ^{:doc ""} __name__ "numpy") (def ^{:doc " Record Arrays ============= Record arrays expose the fields of structured arrays as properties. Most commonly, ndarrays contain elements of a single type, e.g. floats, integers, bools etc. However, it is possible for elements to be combinations of these using structured types, such as:: >>> a = np.array([(1, 2.0), (1, 2.0)], dtype=[('x', np.int64), ('y', np.float64)]) >>> a array([(1, 2.), (1, 2.)], dtype=[('x', '>> a['x'] array([1, 1]) >>> a['y'] array([2., 2.]) Record arrays allow us to access fields as properties:: >>> ar = np.rec.array(a) >>> ar.x array([1, 1]) >>> ar.y array([2., 2.]) "} rec (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "rec")))) (def ^{:doc ""} euler_gamma 0.5772156649015329) (def ^{:doc "Complex number type composed of two double-precision floating-point numbers, compatible with Python `complex`. :Character code: ``'D'`` :Canonical name: `numpy.cdouble` :Alias: `numpy.cfloat` :Alias: `numpy.complex_` :Alias on this platform: `numpy.complex128`: Complex number type composed of 2 64-bit-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} cfloat (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "cfloat")))) (def ^{:doc " Stack arrays in sequence horizontally (column wise). This is equivalent to concatenation along the second axis, except for 1-D arrays where it concatenates along the first axis. Rebuilds arrays divided by `hsplit`. This function makes most sense for arrays with up to 3 dimensions. For instance, for pixel-data with a height (first axis), width (second axis), and r/g/b channels (third axis). The functions `concatenate`, `stack` and `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of ndarrays The arrays must have the same shape along all but the second axis, except 1-D arrays which can be any length. Returns ------- stacked : ndarray The array formed by stacking the given arrays. See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. block : Assemble an nd-array from nested lists of blocks. vstack : Stack arrays in sequence vertically (row wise). dstack : Stack arrays in sequence depth wise (along third axis). column_stack : Stack 1-D arrays as columns into a 2-D array. hsplit : Split an array into multiple sub-arrays horizontally (column-wise). Examples -------- >>> a = np.array((1,2,3)) >>> b = np.array((2,3,4)) >>> np.hstack((a,b)) array([1, 2, 3, 2, 3, 4]) >>> a = np.array([[1],[2],[3]]) >>> b = np.array([[2],[3],[4]]) >>> np.hstack((a,b)) array([[1, 2], [2, 3], [3, 4]]) " :arglists '[[& [args {:as kwargs}]]]} hstack (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "hstack")))) (def ^{:doc " Base object for a dictionary for look-up with any alias for an array dtype. Instances of `_typedict` can not be used as dictionaries directly, first they have to be populated. "} nbytes (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "nbytes")))) (def ^{:doc " Compute the median along the specified axis, while ignoring NaNs. Returns the median of the array elements. .. versionadded:: 1.9.0 Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : {int, sequence of int, None}, optional Axis or axes along which the medians are computed. The default is to compute the median along a flattened version of the array. A sequence of axes is supported since version 1.9.0. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow use of memory of input array `a` for calculations. The input array will be modified by the call to `median`. This will save memory when you do not need to preserve the contents of the input array. Treat the input as undefined, but it will probably be fully or partially sorted. Default is False. If `overwrite_input` is ``True`` and `a` is not already an `ndarray`, an error will be raised. 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 `a`. If this is anything but the default value it will be passed through (in the special case of an empty array) to the `mean` function of the underlying array. If the array is a sub-class and `mean` does not have the kwarg `keepdims` this will raise a RuntimeError. Returns ------- median : ndarray A new array holding the result. If the input contains integers or floats smaller than ``float64``, then the output data-type is ``np.float64``. Otherwise, the data-type of the output is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean, median, percentile Notes ----- Given a vector ``V`` of length ``N``, the median of ``V`` is the middle value of a sorted copy of ``V``, ``V_sorted`` - i.e., ``V_sorted[(N-1)/2]``, when ``N`` is odd and the average of the two middle values of ``V_sorted`` when ``N`` is even. Examples -------- >>> a = np.array([[10.0, 7, 4], [3, 2, 1]]) >>> a[0, 1] = np.nan >>> a array([[10., nan, 4.], [ 3., 2., 1.]]) >>> np.median(a) nan >>> np.nanmedian(a) 3.0 >>> np.nanmedian(a, axis=0) array([6.5, 2. , 2.5]) >>> np.median(a, axis=1) array([nan, 2.]) >>> b = a.copy() >>> np.nanmedian(b, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) >>> b = a.copy() >>> np.nanmedian(b, axis=None, overwrite_input=True) 3.0 >>> assert not np.all(a==b) " :arglists '[[& [args {:as kwargs}]]]} nanmedian (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanmedian")))) (def ^{:doc "sign(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Returns an element-wise indication of the sign of a number. The `sign` function returns ``-1 if x < 0, 0 if x==0, 1 if x > 0``. nan is returned for nan inputs. For complex inputs, the `sign` function returns ``sign(x.real) + 0j if x.real != 0 else sign(x.imag) + 0j``. complex(nan, 0) is returned for complex nan inputs. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The sign of `x`. This is a scalar if `x` is a scalar. Notes ----- There is more than one definition of sign in common use for complex numbers. The definition used here is equivalent to :math:`x/\\sqrt{x*x}` which is different from a common alternative, :math:`x/|x|`. Examples -------- >>> np.sign([-5., 4.5]) array([-1., 1.]) >>> np.sign(0) 0 >>> np.sign(5-2j) (1+0j)" :arglists '[[self & [args {:as kwargs}]]]} sign (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "sign")))) (def ^{:doc " Discrete Fourier Transform (:mod:`numpy.fft`) ============================================= .. currentmodule:: numpy.fft The SciPy module `scipy.fft` is a more comprehensive superset of ``numpy.fft``, which includes only a basic set of routines. Standard FFTs ------------- .. autosummary:: :toctree: generated/ fft Discrete Fourier transform. ifft Inverse discrete Fourier transform. fft2 Discrete Fourier transform in two dimensions. ifft2 Inverse discrete Fourier transform in two dimensions. fftn Discrete Fourier transform in N-dimensions. ifftn Inverse discrete Fourier transform in N dimensions. Real FFTs --------- .. autosummary:: :toctree: generated/ rfft Real discrete Fourier transform. irfft Inverse real discrete Fourier transform. rfft2 Real discrete Fourier transform in two dimensions. irfft2 Inverse real discrete Fourier transform in two dimensions. rfftn Real discrete Fourier transform in N dimensions. irfftn Inverse real discrete Fourier transform in N dimensions. Hermitian FFTs -------------- .. autosummary:: :toctree: generated/ hfft Hermitian discrete Fourier transform. ihfft Inverse Hermitian discrete Fourier transform. Helper routines --------------- .. autosummary:: :toctree: generated/ fftfreq Discrete Fourier Transform sample frequencies. rfftfreq DFT sample frequencies (for usage with rfft, irfft). fftshift Shift zero-frequency component to center of spectrum. ifftshift Inverse of fftshift. Background information ---------------------- Fourier analysis is fundamentally a method for expressing a function as a sum of periodic components, and for recovering the function from those components. When both the function and its Fourier transform are replaced with discretized counterparts, it is called the discrete Fourier transform (DFT). The DFT has become a mainstay of numerical computing in part because of a very fast algorithm for computing it, called the Fast Fourier Transform (FFT), which was known to Gauss (1805) and was brought to light in its current form by Cooley and Tukey [CT]_. Press et al. [NR]_ provide an accessible introduction to Fourier analysis and its applications. Because the discrete Fourier transform separates its input into components that contribute at discrete frequencies, it has a great number of applications in digital signal processing, e.g., for filtering, and in this context the discretized input to the transform is customarily referred to as a *signal*, which exists in the *time domain*. The output is called a *spectrum* or *transform* and exists in the *frequency domain*. Implementation details ---------------------- There are many ways to define the DFT, varying in the sign of the exponent, normalization, etc. In this implementation, the DFT is defined as .. math:: A_k = \\sum_{m=0}^{n-1} a_m \\exp\\left\\{-2\\pi i{mk \\over n}\\right\\} \\qquad k = 0,\\ldots,n-1. The DFT is in general defined for complex inputs and outputs, and a single-frequency component at linear frequency :math:`f` is represented by a complex exponential :math:`a_m = \\exp\\{2\\pi i\\,f m\\Delta t\\}`, where :math:`\\Delta t` is the sampling interval. The values in the result follow so-called \"standard\" order: If ``A = fft(a, n)``, then ``A[0]`` contains the zero-frequency term (the sum of the signal), which is always purely real for real inputs. Then ``A[1:n/2]`` contains the positive-frequency terms, and ``A[n/2+1:]`` contains the negative-frequency terms, in order of decreasingly negative frequency. For an even number of input points, ``A[n/2]`` represents both positive and negative Nyquist frequency, and is also purely real for real input. For an odd number of input points, ``A[(n-1)/2]`` contains the largest positive frequency, while ``A[(n+1)/2]`` contains the largest negative frequency. The routine ``np.fft.fftfreq(n)`` returns an array giving the frequencies of corresponding elements in the output. The routine ``np.fft.fftshift(A)`` shifts transforms and their frequencies to put the zero-frequency components in the middle, and ``np.fft.ifftshift(A)`` undoes that shift. When the input `a` is a time-domain signal and ``A = fft(a)``, ``np.abs(A)`` is its amplitude spectrum and ``np.abs(A)**2`` is its power spectrum. The phase spectrum is obtained by ``np.angle(A)``. The inverse DFT is defined as .. math:: a_m = \\frac{1}{n}\\sum_{k=0}^{n-1}A_k\\exp\\left\\{2\\pi i{mk\\over n}\\right\\} \\qquad m = 0,\\ldots,n-1. It differs from the forward transform by the sign of the exponential argument and the default normalization by :math:`1/n`. Type Promotion -------------- `numpy.fft` promotes ``float32`` and ``complex64`` arrays to ``float64`` and ``complex128`` arrays respectively. For an FFT implementation that does not promote input arrays, see `scipy.fftpack`. Normalization ------------- The argument ``norm`` indicates which direction of the pair of direct/inverse transforms is scaled and with what normalization factor. The default normalization (``\"backward\"``) has the direct (forward) transforms unscaled and the inverse (backward) transforms scaled by :math:`1/n`. It is possible to obtain unitary transforms by setting the keyword argument ``norm`` to ``\"ortho\"`` so that both direct and inverse transforms are scaled by :math:`1/\\sqrt{n}`. Finally, setting the keyword argument ``norm`` to ``\"forward\"`` has the direct transforms scaled by :math:`1/n` and the inverse transforms unscaled (i.e. exactly opposite to the default ``\"backward\"``). `None` is an alias of the default option ``\"backward\"`` for backward compatibility. Real and Hermitian transforms ----------------------------- When the input is purely real, its transform is Hermitian, i.e., the component at frequency :math:`f_k` is the complex conjugate of the component at frequency :math:`-f_k`, which means that for real inputs there is no information in the negative frequency components that is not already available from the positive frequency components. The family of `rfft` functions is designed to operate on real inputs, and exploits this symmetry by computing only the positive frequency components, up to and including the Nyquist frequency. Thus, ``n`` input points produce ``n/2+1`` complex output points. The inverses of this family assumes the same symmetry of its input, and for an output of ``n`` points uses ``n/2+1`` input points. Correspondingly, when the spectrum is purely real, the signal is Hermitian. The `hfft` family of functions exploits this symmetry by using ``n/2+1`` complex points in the input (time) domain for ``n`` real points in the frequency domain. In higher dimensions, FFTs are used, e.g., for image analysis and filtering. The computational efficiency of the FFT means that it can also be a faster way to compute large convolutions, using the property that a convolution in the time domain is equivalent to a point-by-point multiplication in the frequency domain. Higher dimensions ----------------- In two dimensions, the DFT is defined as .. math:: A_{kl} = \\sum_{m=0}^{M-1} \\sum_{n=0}^{N-1} a_{mn}\\exp\\left\\{-2\\pi i \\left({mk\\over M}+{nl\\over N}\\right)\\right\\} \\qquad k = 0, \\ldots, M-1;\\quad l = 0, \\ldots, N-1, which extends in the obvious way to higher dimensions, and the inverses in higher dimensions also extend in the same way. References ---------- .. [CT] Cooley, James W., and John W. Tukey, 1965, \"An algorithm for the machine calculation of complex Fourier series,\" *Math. Comput.* 19: 297-301. .. [NR] Press, W., Teukolsky, S., Vetterline, W.T., and Flannery, B.P., 2007, *Numerical Recipes: The Art of Scientific Computing*, ch. 12-13. Cambridge Univ. Press, Cambridge, UK. Examples -------- For examples, see the various functions. "} fft (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "fft")))) (def ^{:doc " finfo(dtype) Machine limits for floating point types. Attributes ---------- bits : int The number of bits occupied by the type. eps : float The difference between 1.0 and the next smallest representable float larger than 1.0. For example, for 64-bit binary floats in the IEEE-754 standard, ``eps = 2**-52``, approximately 2.22e-16. epsneg : float The difference between 1.0 and the next smallest representable float less than 1.0. For example, for 64-bit binary floats in the IEEE-754 standard, ``epsneg = 2**-53``, approximately 1.11e-16. iexp : int The number of bits in the exponent portion of the floating point representation. machar : MachAr The object which calculated these parameters and holds more detailed information. machep : int The exponent that yields `eps`. max : floating point number of the appropriate type The largest representable number. maxexp : int The smallest positive power of the base (2) that causes overflow. min : floating point number of the appropriate type The smallest representable number, typically ``-max``. minexp : int The most negative power of the base (2) consistent with there being no leading 0's in the mantissa. negep : int The exponent that yields `epsneg`. nexp : int The number of bits in the exponent including its sign and bias. nmant : int The number of bits in the mantissa. precision : int The approximate number of decimal digits to which this kind of float is precise. resolution : floating point number of the appropriate type The approximate decimal resolution of this type, i.e., ``10**-precision``. tiny : float The smallest positive floating point number with full precision (see Notes). Parameters ---------- dtype : float, dtype, or instance Kind of floating point data-type about which to get information. See Also -------- MachAr : The implementation of the tests that produce this information. iinfo : The equivalent for integer data types. spacing : The distance between a value and the nearest adjacent number nextafter : The next floating point value after x1 towards x2 Notes ----- For developers of NumPy: do not instantiate this at the module level. The initial calculation of these parameters is expensive and negatively impacts import times. These objects are cached, so calling ``finfo()`` repeatedly inside your functions is not a problem. Note that ``tiny`` is not actually the smallest positive representable value in a NumPy floating point type. As in the IEEE-754 standard [1]_, NumPy floating point types make use of subnormal numbers to fill the gap between 0 and ``tiny``. However, subnormal numbers may have significantly reduced precision [2]_. References ---------- .. [1] IEEE Standard for Floating-Point Arithmetic, IEEE Std 754-2008, pp.1-70, 2008, http://www.doi.org/10.1109/IEEESTD.2008.4610935 .. [2] Wikipedia, \"Denormal Numbers\", https://en.wikipedia.org/wiki/Denormal_number " :arglists '[[self & [args {:as kwargs}]]]} finfo (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "finfo")))) (def ^{:doc " Returns True if first argument is a typecode lower/equal in type hierarchy. This is like the builtin :func:`issubclass`, but for `dtype`\\ s. Parameters ---------- arg1, arg2 : dtype_like `dtype` or object coercible to one Returns ------- out : bool See Also -------- :ref:`arrays.scalars` : Overview of the numpy type hierarchy. issubsctype, issubclass_ Examples -------- `issubdtype` can be used to check the type of arrays: >>> ints = np.array([1, 2, 3], dtype=np.int32) >>> np.issubdtype(ints.dtype, np.integer) True >>> np.issubdtype(ints.dtype, np.floating) False >>> floats = np.array([1, 2, 3], dtype=np.float32) >>> np.issubdtype(floats.dtype, np.integer) False >>> np.issubdtype(floats.dtype, np.floating) True Similar types of different sizes are not subdtypes of each other: >>> np.issubdtype(np.float64, np.float32) False >>> np.issubdtype(np.float32, np.float64) False but both are subtypes of `floating`: >>> np.issubdtype(np.float64, np.floating) True >>> np.issubdtype(np.float32, np.floating) True For convenience, dtype-like objects are allowed too: >>> np.issubdtype('S1', np.string_) True >>> np.issubdtype('i4', np.signedinteger) True " :arglists '[[arg1 arg2]]} issubdtype (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "issubdtype")))) (def ^{:doc "array(object, dtype=None, *, copy=True, order='K', subok=False, ndmin=0, like=None) 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. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 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','>> 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]])" :arglists '[[self & [args {:as kwargs}]]]} array (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "array")))) (def ^{:doc "logaddexp2(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Logarithm of the sum of exponentiations of the inputs in base-2. Calculates ``log2(2**x1 + 2**x2)``. This function is useful in machine learning when the calculated probabilities of events may be so small as to exceed the range of normal floating point numbers. In such cases the base-2 logarithm of the calculated probability can be used instead. This function allows adding probabilities stored in such a fashion. Parameters ---------- x1, x2 : array_like Input values. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- result : ndarray Base-2 logarithm of ``2**x1 + 2**x2``. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logaddexp: Logarithm of the sum of exponentiations of the inputs. Notes ----- .. versionadded:: 1.3.0 Examples -------- >>> prob1 = np.log2(1e-50) >>> prob2 = np.log2(2.5e-50) >>> prob12 = np.logaddexp2(prob1, prob2) >>> prob1, prob2, prob12 (-166.09640474436813, -164.77447664948076, -164.28904982231052) >>> 2**prob12 3.4999999999999914e-50" :arglists '[[self & [args {:as kwargs}]]]} logaddexp2 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "logaddexp2")))) (def ^{:doc " Reverse or permute the axes of an array; returns the modified array. For an array a with two axes, transpose(a) gives the matrix transpose. Parameters ---------- a : array_like Input array. axes : tuple or list of ints, optional If specified, it must be a tuple or list which contains a permutation of [0,1,..,N-1] where N is the number of axes of a. The i'th axis of the returned array will correspond to the axis numbered ``axes[i]`` of the input. If not specified, defaults to ``range(a.ndim)[::-1]``, which reverses the order of the axes. Returns ------- p : ndarray `a` with its axes permuted. A view is returned whenever possible. See Also -------- moveaxis argsort Notes ----- Use `transpose(a, argsort(axes))` to invert the transposition of tensors when using the `axes` keyword argument. Transposing a 1-D array returns an unchanged view of the original array. Examples -------- >>> x = np.arange(4).reshape((2,2)) >>> x array([[0, 1], [2, 3]]) >>> np.transpose(x) array([[0, 2], [1, 3]]) >>> x = np.ones((1, 2, 3)) >>> np.transpose(x, (1, 0, 2)).shape (2, 1, 3) >>> x = np.ones((2, 3, 4, 5)) >>> np.transpose(x).shape (5, 4, 3, 2) " :arglists '[[& [args {:as kwargs}]]]} transpose (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "transpose")))) (def ^{:doc " Return the indices for the lower-triangle of an (n, m) array. Parameters ---------- n : int The row dimension of the arrays for which the returned indices will be valid. k : int, optional Diagonal offset (see `tril` for details). m : int, optional .. versionadded:: 1.9.0 The column dimension of the arrays for which the returned arrays will be valid. By default `m` is taken equal to `n`. Returns ------- inds : tuple of arrays The indices for the triangle. The returned tuple contains two arrays, each with the indices along one dimension of the array. See also -------- triu_indices : similar function, for upper-triangular. mask_indices : generic function accepting an arbitrary mask function. tril, triu Notes ----- .. versionadded:: 1.4.0 Examples -------- Compute two different sets of indices to access 4x4 arrays, one for the lower triangular part starting at the main diagonal, and one starting two diagonals further right: >>> il1 = np.tril_indices(4) >>> il2 = np.tril_indices(4, 2) Here is how they can be used with a sample array: >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) Both for indexing: >>> a[il1] array([ 0, 4, 5, ..., 13, 14, 15]) And for assigning values: >>> a[il1] = -1 >>> a array([[-1, 1, 2, 3], [-1, -1, 6, 7], [-1, -1, -1, 11], [-1, -1, -1, -1]]) These cover almost the whole array (two diagonals right of the main one): >>> a[il2] = -10 >>> a array([[-10, -10, -10, 3], [-10, -10, -10, -10], [-10, -10, -10, -10], [-10, -10, -10, -10]]) " :arglists '[[n & [{k :k, m :m}]] [n & [{k :k}]] [n]]} tril_indices (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tril_indices")))) (def ^{:doc "Convert the input to an array, checking for NaNs or Infs. Parameters ---------- a : array_like Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays. Success requires no NaNs or Infs. dtype : data-type, optional By default, the data-type is inferred from the input data. order : {'C', 'F', 'A', 'K'}, optional Memory layout. 'A' and 'K' depend on the order of input array a. 'C' row-major (C-style), 'F' column-major (Fortran-style) memory representation. 'A' (any) means 'F' if `a` is Fortran contiguous, 'C' otherwise 'K' (keep) preserve input order Defaults to 'C'. Returns ------- out : ndarray Array interpretation of `a`. No copy is performed if the input is already an ndarray. If `a` is a subclass of ndarray, a base class ndarray is returned. Raises ------ ValueError Raises ValueError if `a` contains NaN (Not a Number) or Inf (Infinity). See Also -------- asarray : Create and array. asanyarray : Similar function which passes through subclasses. ascontiguousarray : Convert input to a contiguous array. asfarray : Convert input to a floating point ndarray. asfortranarray : Convert input to an ndarray with column-major memory order. fromiter : Create an array from an iterator. fromfunction : Construct an array by executing a function on grid positions. Examples -------- Convert a list into an array. If all elements are finite ``asarray_chkfinite`` is identical to ``asarray``. >>> a = [1, 2] >>> np.asarray_chkfinite(a, dtype=float) array([1., 2.]) Raises ValueError if array_like contains Nans or Infs. >>> a = [1, 2, np.inf] >>> try: ... np.asarray_chkfinite(a) ... except ValueError: ... print('ValueError') ... ValueError " :arglists '[[a & [{dtype :dtype, order :order}]] [a & [{dtype :dtype}]] [a]]} asarray_chkfinite (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "asarray_chkfinite")))) (def ^{:doc "arccos(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Trigonometric inverse cosine, element-wise. The inverse of `cos` so that, if ``y = cos(x)``, then ``x = arccos(y)``. Parameters ---------- x : array_like `x`-coordinate on the unit circle. For real arguments, the domain is [-1, 1]. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- angle : ndarray The angle of the ray intersecting the unit circle at the given `x`-coordinate in radians [0, pi]. This is a scalar if `x` is a scalar. See Also -------- cos, arctan, arcsin, emath.arccos Notes ----- `arccos` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `cos(z) = x`. The convention is to return the angle `z` whose real part lies in `[0, pi]`. For real-valued input data types, `arccos` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `arccos` is a complex analytic function that has branch cuts `[-inf, -1]` and `[1, inf]` and is continuous from above on the former and from below on the latter. The inverse `cos` is also known as `acos` or cos^-1. References ---------- M. Abramowitz and I.A. Stegun, \"Handbook of Mathematical Functions\", 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/ Examples -------- We expect the arccos of 1 to be 0, and of -1 to be pi: >>> np.arccos([1, -1]) array([ 0. , 3.14159265]) Plot arccos: >>> import matplotlib.pyplot as plt >>> x = np.linspace(-1, 1, num=100) >>> plt.plot(x, np.arccos(x)) >>> plt.axis('tight') >>> plt.show()" :arglists '[[self & [args {:as kwargs}]]]} arccos (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arccos")))) (def ^{:doc " A nicer way to build up index tuples for arrays. .. note:: Use one of the two predefined instances `index_exp` or `s_` rather than directly using `IndexExpression`. For any index combination, including slicing and axis insertion, ``a[indices]`` is the same as ``a[np.index_exp[indices]]`` for any array `a`. However, ``np.index_exp[indices]`` can be used anywhere in Python code and returns a tuple of slice objects that can be used in the construction of complex index expressions. Parameters ---------- maketuple : bool If True, always returns a tuple. See Also -------- index_exp : Predefined instance that always returns a tuple: `index_exp = IndexExpression(maketuple=True)`. s_ : Predefined instance without tuple conversion: `s_ = IndexExpression(maketuple=False)`. Notes ----- You can do all this with `slice()` plus a few special objects, but there's a lot to remember and this version is simpler because it uses the standard array indexing syntax. Examples -------- >>> np.s_[2::2] slice(2, None, 2) >>> np.index_exp[2::2] (slice(2, None, 2),) >>> np.array([0, 1, 2, 3, 4])[np.s_[2::2]] array([2, 4]) "} s_ (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "s_")))) (def ^{:doc " Contains the core of NumPy: ndarray, ufuncs, dtypes, etc. Please note that this module is private. All functions and objects are available in the main ``numpy`` namespace - use that instead. "} core (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "core")))) (def ^{:doc "Complex number type composed of two single-precision floating-point numbers. :Character code: ``'F'`` :Canonical name: `numpy.csingle` :Alias: `numpy.singlecomplex` :Alias on this platform: `numpy.complex64`: Complex number type composed of 2 32-bit-precision floating-point numbers." :arglists '[[self & [args {:as kwargs}]]]} complex64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "complex64")))) (def ^{:doc "arccosh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Inverse hyperbolic cosine, element-wise. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- arccosh : ndarray Array of the same shape as `x`. This is a scalar if `x` is a scalar. See Also -------- cosh, arcsinh, sinh, arctanh, tanh Notes ----- `arccosh` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `cosh(z) = x`. The convention is to return the `z` whose imaginary part lies in `[-pi, pi]` and the real part in ``[0, inf]``. For real-valued input data types, `arccosh` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `arccosh` is a complex analytical function that has a branch cut `[-inf, 1]` and is continuous from above on it. References ---------- .. [1] M. Abramowitz and I.A. Stegun, \"Handbook of Mathematical Functions\", 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, \"Inverse hyperbolic function\", https://en.wikipedia.org/wiki/Arccosh Examples -------- >>> np.arccosh([np.e, 10.0]) array([ 1.65745445, 2.99322285]) >>> np.arccosh(1) 0.0" :arglists '[[self & [args {:as kwargs}]]]} arccosh (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arccosh")))) (def ^{:doc "Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified."} _financial_names (as-jvm/generic-python-as-list (py-global-delay (py/get-attr @src-obj* "_financial_names")))) (def ^{:doc " Apply a function repeatedly over multiple axes. `func` is called as `res = func(a, axis)`, where `axis` is the first element of `axes`. The result `res` of the function call must have either the same dimensions as `a` or one less dimension. If `res` has one less dimension than `a`, a dimension is inserted before `axis`. The call to `func` is then repeated for each axis in `axes`, with `res` as the first argument. Parameters ---------- func : function This function must take two arguments, `func(a, axis)`. a : array_like Input array. axes : array_like Axes over which `func` is applied; the elements must be integers. Returns ------- apply_over_axis : ndarray The output array. The number of dimensions is the same as `a`, but the shape can be different. This depends on whether `func` changes the shape of its output with respect to its input. See Also -------- apply_along_axis : Apply a function to 1-D slices of an array along the given axis. Notes ----- This function is equivalent to tuple axis arguments to reorderable ufuncs with keepdims=True. Tuple axis arguments to ufuncs have been available since version 1.7.0. Examples -------- >>> a = np.arange(24).reshape(2,3,4) >>> a 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]]]) Sum over axes 0 and 2. The result has same number of dimensions as the original array: >>> np.apply_over_axes(np.sum, a, [0,2]) array([[[ 60], [ 92], [124]]]) Tuple axis arguments to ufuncs are equivalent: >>> np.sum(a, axis=(0,2), keepdims=True) array([[[ 60], [ 92], [124]]]) " :arglists '[[& [args {:as kwargs}]]]} apply_over_axes (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "apply_over_axes")))) (def ^{:doc "tanh(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute hyperbolic tangent element-wise. Equivalent to ``np.sinh(x)/np.cosh(x)`` or ``-1j * np.tan(1j*x)``. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The corresponding hyperbolic tangent values. This is a scalar if `x` is a scalar. Notes ----- If `out` is provided, the function writes the result into it, and returns a reference to `out`. (See Examples) References ---------- .. [1] M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972, pg. 83. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, \"Hyperbolic function\", https://en.wikipedia.org/wiki/Hyperbolic_function Examples -------- >>> np.tanh((0, np.pi*1j, np.pi*1j/2)) array([ 0. +0.00000000e+00j, 0. -1.22460635e-16j, 0. +1.63317787e+16j]) >>> # Example of providing the optional output parameter illustrating >>> # that what is returned is a reference to said parameter >>> out1 = np.array([0], dtype='d') >>> out2 = np.tanh([0.1], out1) >>> out2 is out1 True >>> # Example of ValueError due to provision of shape mis-matched `out` >>> np.tanh(np.zeros((3,3)),np.zeros((2,2))) Traceback (most recent call last): File \"\", line 1, in ValueError: operands could not be broadcast together with shapes (3,3) (2,2)" :arglists '[[self & [args {:as kwargs}]]]} tanh (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tanh")))) (def ^{:doc "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=' a.ndim`` will be treated as ``axis == a.ndim``, and passing ``axis < -a.ndim - 1`` will be treated as ``axis == 0``. This behavior is deprecated. .. versionchanged:: 1.18.0 A tuple of axes is now supported. Out of range axes as described above are now forbidden and raise an `AxisError`. Returns ------- result : ndarray View of `a` with the number of dimensions increased. See Also -------- squeeze : The inverse operation, removing singleton dimensions reshape : Insert, remove, and combine dimensions, and resize existing ones doc.indexing, atleast_1d, atleast_2d, atleast_3d Examples -------- >>> x = np.array([1, 2]) >>> x.shape (2,) The following is equivalent to ``x[np.newaxis, :]`` or ``x[np.newaxis]``: >>> y = np.expand_dims(x, axis=0) >>> y array([[1, 2]]) >>> y.shape (1, 2) The following is equivalent to ``x[:, np.newaxis]``: >>> y = np.expand_dims(x, axis=1) >>> y array([[1], [2]]) >>> y.shape (2, 1) ``axis`` may also be a tuple: >>> y = np.expand_dims(x, axis=(0, 1)) >>> y array([[[1, 2]]]) >>> y = np.expand_dims(x, axis=(2, 0)) >>> y array([[[1], [2]]]) Note that some examples may use ``None`` instead of ``np.newaxis``. These are the same objects: >>> np.newaxis is None True " :arglists '[[& [args {:as kwargs}]]]} expand_dims (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "expand_dims")))) (def ^{:doc " Flip array in the left/right direction. Flip the entries in each row in the left/right direction. Columns are preserved, but appear in a different order than before. Parameters ---------- m : array_like Input array, must be at least 2-D. Returns ------- f : ndarray A view of `m` with the columns reversed. Since a view is returned, this operation is :math:`\\mathcal O(1)`. See Also -------- flipud : Flip array in the up/down direction. rot90 : Rotate array counterclockwise. Notes ----- Equivalent to m[:,::-1]. Requires the array to be at least 2-D. Examples -------- >>> A = np.diag([1.,2.,3.]) >>> A array([[1., 0., 0.], [0., 2., 0.], [0., 0., 3.]]) >>> np.fliplr(A) array([[0., 0., 1.], [0., 2., 0.], [3., 0., 0.]]) >>> A = np.random.randn(2,3,5) >>> np.all(np.fliplr(A) == A[:,::-1,...]) True " :arglists '[[& [args {:as kwargs}]]]} fliplr (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "fliplr")))) (def ^{:doc " An array with ones at and below the given diagonal and zeros elsewhere. Parameters ---------- N : int Number of rows in the array. M : int, optional Number of columns in the array. By default, `M` is taken equal to `N`. k : int, optional The sub-diagonal at and below which the array is filled. `k` = 0 is the main diagonal, while `k` < 0 is below it, and `k` > 0 is above. The default is 0. dtype : dtype, optional Data type of the returned array. The default is float. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- tri : ndarray of shape (N, M) Array with its lower triangle filled with ones and zero elsewhere; in other words ``T[i,j] == 1`` for ``j <= i + k``, 0 otherwise. Examples -------- >>> np.tri(3, 5, 2, dtype=int) array([[1, 1, 1, 0, 0], [1, 1, 1, 1, 0], [1, 1, 1, 1, 1]]) >>> np.tri(3, 5, -1) array([[0., 0., 0., 0., 0.], [1., 0., 0., 0., 0.], [1., 1., 0., 0., 0.]]) " :arglists '[[N & [{M :M, k :k, dtype :dtype, like :like}]] [N & [{M :M, k :k, like :like}]] [N & [{M :M, like :like}]] [N & [{like :like}]]]} tri (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "tri")))) (def ^{:doc "absolute(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Calculate the absolute value element-wise. ``np.abs`` is a shorthand for this function. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- absolute : ndarray An ndarray containing the absolute value of each element in `x`. For complex input, ``a + ib``, the absolute value is :math:`\\sqrt{ a^2 + b^2 }`. This is a scalar if `x` is a scalar. Examples -------- >>> x = np.array([-1.2, 1.2]) >>> np.absolute(x) array([ 1.2, 1.2]) >>> np.absolute(1.2 + 1j) 1.5620499351813308 Plot the function over ``[-10, 10]``: >>> import matplotlib.pyplot as plt >>> x = np.linspace(start=-10, stop=10, num=101) >>> plt.plot(x, np.absolute(x)) >>> plt.show() Plot the function over the complex plane: >>> xx = x + 1j * x[:, np.newaxis] >>> plt.imshow(np.abs(xx), extent=[-10, 10, -10, 10], cmap='gray') >>> plt.show() The `abs` function can be used as a shorthand for ``np.absolute`` on ndarrays. >>> x = np.array([-1.2, 1.2]) >>> abs(x) array([1.2, 1.2])" :arglists '[[self & [args {:as kwargs}]]]} absolute (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "absolute")))) (def ^{:doc " Split an array into multiple sub-arrays horizontally (column-wise). Please refer to the `split` documentation. `hsplit` is equivalent to `split` with ``axis=1``, the array is always split along the second axis regardless of the array dimension. See Also -------- split : Split an array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(16.0).reshape(4, 4) >>> x array([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.], [12., 13., 14., 15.]]) >>> np.hsplit(x, 2) [array([[ 0., 1.], [ 4., 5.], [ 8., 9.], [12., 13.]]), array([[ 2., 3.], [ 6., 7.], [10., 11.], [14., 15.]])] >>> np.hsplit(x, np.array([3, 6])) [array([[ 0., 1., 2.], [ 4., 5., 6.], [ 8., 9., 10.], [12., 13., 14.]]), array([[ 3.], [ 7.], [11.], [15.]]), array([], shape=(4, 0), dtype=float64)] With a higher dimensional array the split is still along the second axis. >>> x = np.arange(8.0).reshape(2, 2, 2) >>> x array([[[0., 1.], [2., 3.]], [[4., 5.], [6., 7.]]]) >>> np.hsplit(x, 2) [array([[[0., 1.]], [[4., 5.]]]), array([[[2., 3.]], [[6., 7.]]])] " :arglists '[[& [args {:as kwargs}]]]} hsplit (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "hsplit")))) (def ^{:doc "Signed integer type, compatible with C ``char``. :Character code: ``'b'`` :Canonical name: `numpy.byte` :Alias on this platform: `numpy.int8`: 8-bit signed integer (``-128`` to ``127``)." :arglists '[[self & [args {:as kwargs}]]]} byte (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "byte")))) (def ^{:doc "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" :arglists '[[self & [args {:as kwargs}]]]} seterrobj (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "seterrobj")))) (def ^{:doc "log2(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Base-2 logarithm of `x`. Parameters ---------- x : array_like Input values. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray Base-2 logarithm of `x`. This is a scalar if `x` is a scalar. See Also -------- log, log10, log1p, emath.log2 Notes ----- .. versionadded:: 1.3.0 Logarithm is a multivalued function: for each `x` there is an infinite number of `z` such that `2**z = x`. The convention is to return the `z` whose imaginary part lies in `[-pi, pi]`. For real-valued input data types, `log2` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `log2` is a complex analytical function that has a branch cut `[-inf, 0]` and is continuous from above on it. `log2` handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard. Examples -------- >>> x = np.array([0, 1, 2, 2**4]) >>> np.log2(x) array([-Inf, 0., 1., 4.]) >>> xi = np.array([0+1.j, 1, 2+0.j, 4.j]) >>> np.log2(xi) array([ 0.+2.26618007j, 0.+0.j , 1.+0.j , 2.+2.26618007j])" :arglists '[[self & [args {:as kwargs}]]]} log2 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "log2")))) (def ^{:doc "left_shift(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Shift the bits of an integer to the left. Bits are shifted to the left by appending `x2` 0s at the right of `x1`. Since the internal representation of numbers is in binary format, this operation is equivalent to multiplying `x1` by ``2**x2``. Parameters ---------- x1 : array_like of integer type Input values. x2 : array_like of integer type Number of zeros to append to `x1`. Has to be non-negative. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : array of integer type Return `x1` with bits shifted `x2` times to the left. This is a scalar if both `x1` and `x2` are scalars. See Also -------- right_shift : Shift the bits of an integer to the right. binary_repr : Return the binary representation of the input number as a string. Examples -------- >>> np.binary_repr(5) '101' >>> np.left_shift(5, 2) 20 >>> np.binary_repr(20) '10100' >>> np.left_shift(5, [1,2,3]) array([10, 20, 40]) Note that the dtype of the second argument may change the dtype of the result and can lead to unexpected results in some cases (see :ref:`Casting Rules `): >>> a = np.left_shift(np.uint8(255), 1) # Expect 254 >>> print(a, type(a)) # Unexpected result due to upcasting 510 >>> b = np.left_shift(np.uint8(255), np.uint8(1)) >>> print(b, type(b)) 254 The ``<<`` operator can be used as a shorthand for ``np.left_shift`` on ndarrays. >>> x1 = 5 >>> x2 = np.array([1, 2, 3]) >>> x1 << x2 array([10, 20, 40])" :arglists '[[self & [args {:as kwargs}]]]} left_shift (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "left_shift")))) (def ^{:doc " Return a contiguous array (ndim >= 1) in memory (C order). Parameters ---------- a : array_like Input array. dtype : str or dtype object, optional Data-type of returned array. like : array_like Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as ``like`` supports the ``__array_function__`` protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument. .. note:: The ``like`` keyword is an experimental feature pending on acceptance of :ref:`NEP 35 `. .. versionadded:: 1.20.0 Returns ------- out : ndarray Contiguous array of same shape and content as `a`, with type `dtype` if specified. See Also -------- asfortranarray : Convert input to an ndarray with column-major memory order. require : Return an ndarray that satisfies requirements. ndarray.flags : Information about the memory layout of the array. Examples -------- >>> x = np.arange(6).reshape(2,3) >>> np.ascontiguousarray(x, dtype=np.float32) array([[0., 1., 2.], [3., 4., 5.]], dtype=float32) >>> x.flags['C_CONTIGUOUS'] True Note: This function returns an array with at least one-dimension (1-d) so it will not preserve 0-d arrays. " :arglists '[[a & [{dtype :dtype, like :like}]] [a & [{like :like}]]]} ascontiguousarray (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "ascontiguousarray")))) (def ^{:doc " Stack arrays in sequence vertically (row wise). This is equivalent to concatenation along the first axis after 1-D arrays of shape `(N,)` have been reshaped to `(1,N)`. Rebuilds arrays divided by `vsplit`. This function makes most sense for arrays with up to 3 dimensions. For instance, for pixel-data with a height (first axis), width (second axis), and r/g/b channels (third axis). The functions `concatenate`, `stack` and `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of ndarrays The arrays must have the same shape along all but the first axis. 1-D arrays must have the same length. Returns ------- stacked : ndarray The array formed by stacking the given arrays, will be at least 2-D. See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. block : Assemble an nd-array from nested lists of blocks. hstack : Stack arrays in sequence horizontally (column wise). dstack : Stack arrays in sequence depth wise (along third axis). column_stack : Stack 1-D arrays as columns into a 2-D array. vsplit : Split an array into multiple sub-arrays vertically (row-wise). Examples -------- >>> a = np.array([1, 2, 3]) >>> b = np.array([2, 3, 4]) >>> np.vstack((a,b)) array([[1, 2, 3], [2, 3, 4]]) >>> a = np.array([[1], [2], [3]]) >>> b = np.array([[2], [3], [4]]) >>> np.vstack((a,b)) array([[1], [2], [3], [2], [3], [4]]) " :arglists '[[& [args {:as kwargs}]]]} row_stack (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "row_stack")))) (def ^{:doc "Save several arrays into a single file in uncompressed ``.npz`` format. If arguments are passed in with no keywords, the corresponding variable names, in the ``.npz`` file, are 'arr_0', 'arr_1', etc. If keyword arguments are given, the corresponding variable names, in the ``.npz`` file will match the keyword names. Parameters ---------- file : str or file Either the filename (string) or an open file (file-like object) where the data will be saved. If file is a string or a Path, the ``.npz`` extension will be appended to the filename if it is not already there. args : Arguments, optional Arrays to save to the file. Since it is not possible for Python to know the names of the arrays outside `savez`, the arrays will be saved with names \"arr_0\", \"arr_1\", and so on. These arguments can be any expression. kwds : Keyword arguments, optional Arrays to save to the file. Arrays will be saved in the file with the keyword names. Returns ------- None See Also -------- save : Save a single array to a binary file in NumPy format. savetxt : Save an array to a file as plain text. savez_compressed : Save several arrays into a compressed ``.npz`` archive Notes ----- The ``.npz`` file format is a zipped archive of files named after the variables they contain. The archive is not compressed and each file in the archive contains one variable in ``.npy`` format. For a description of the ``.npy`` format, see :py:mod:`numpy.lib.format`. When opening the saved ``.npz`` file with `load` a `NpzFile` object is returned. This is a dictionary-like object which can be queried for its list of arrays (with the ``.files`` attribute), and for the arrays themselves. When saving dictionaries, the dictionary keys become filenames inside the ZIP archive. Therefore, keys should be valid filenames. E.g., avoid keys that begin with ``/`` or contain ``.``. Examples -------- >>> from tempfile import TemporaryFile >>> outfile = TemporaryFile() >>> x = np.arange(10) >>> y = np.sin(x) Using `savez` with \\*args, the arrays are saved with default names. >>> np.savez(outfile, x, y) >>> _ = outfile.seek(0) # Only needed here to simulate closing & reopening file >>> npzfile = np.load(outfile) >>> npzfile.files ['arr_0', 'arr_1'] >>> npzfile['arr_0'] array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) Using `savez` with \\**kwds, the arrays are saved with the keyword names. >>> outfile = TemporaryFile() >>> np.savez(outfile, x=x, y=y) >>> _ = outfile.seek(0) >>> npzfile = np.load(outfile) >>> sorted(npzfile.files) ['x', 'y'] >>> npzfile['x'] array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) " :arglists '[[& [args {:as kwargs}]]]} savez (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "savez")))) (def ^{:doc " Return a description for the given data type code. Parameters ---------- char : str Data type code. Returns ------- out : str Description of the input data type code. See Also -------- dtype, typecodes Examples -------- >>> typechars = ['S1', '?', 'B', 'D', 'G', 'F', 'I', 'H', 'L', 'O', 'Q', ... 'S', 'U', 'V', 'b', 'd', 'g', 'f', 'i', 'h', 'l', 'q'] >>> for typechar in typechars: ... print(typechar, ' : ', np.typename(typechar)) ... S1 : character ? : bool B : unsigned char D : complex double precision G : complex long double precision F : complex single precision I : unsigned integer H : unsigned short L : unsigned long integer O : object Q : unsigned long long integer S : string U : unicode V : void b : signed char d : double precision g : long precision f : single precision i : integer h : short l : long integer q : long long integer " :arglists '[[char]]} typename (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "typename")))) (def ^{:doc " Pytest test runner. A test function is typically added to a package's __init__.py like so:: from numpy._pytesttester import PytestTester test = PytestTester(__name__).test del PytestTester Calling this test function finds and runs all tests associated with the module and all its sub-modules. Attributes ---------- module_name : str Full path to the package to test. Parameters ---------- module_name : module name The name of the module to test. Notes ----- Unlike the previous ``nose``-based implementation, this class is not publicly exposed as it performs some ``numpy``-specific warning suppression. " :arglists '[[self module_name]]} test (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "test")))) (def ^{:doc ""} __package__ "numpy") (def ^{:doc " Returns True if input arrays are shape consistent and all elements equal. Shape consistent means they are either the same shape, or one input array can be broadcasted to create the same shape as the other one. Parameters ---------- a1, a2 : array_like Input arrays. Returns ------- out : bool True if equivalent, False otherwise. Examples -------- >>> np.array_equiv([1, 2], [1, 2]) True >>> np.array_equiv([1, 2], [1, 3]) False Showing the shape equivalence: >>> np.array_equiv([1, 2], [[1, 2], [1, 2]]) True >>> np.array_equiv([1, 2], [[1, 2, 1, 2], [1, 2, 1, 2]]) False >>> np.array_equiv([1, 2], [[1, 2], [1, 3]]) False " :arglists '[[& [args {:as kwargs}]]]} array_equiv (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "array_equiv")))) (def ^{:doc " Join a sequence of arrays along a new axis. The ``axis`` parameter specifies the index of the new axis in the dimensions of the result. For example, if ``axis=0`` it will be the first dimension and if ``axis=-1`` it will be the last dimension. .. versionadded:: 1.10.0 Parameters ---------- arrays : sequence of array_like Each array must have the same shape. axis : int, optional The axis in the result array along which the input arrays are stacked. out : ndarray, optional If provided, the destination to place the result. The shape must be correct, matching that of what stack would have returned if no out argument were specified. Returns ------- stacked : ndarray The stacked array has one more dimension than the input arrays. See Also -------- concatenate : Join a sequence of arrays along an existing axis. block : Assemble an nd-array from nested lists of blocks. split : Split array into a list of multiple sub-arrays of equal size. Examples -------- >>> arrays = [np.random.randn(3, 4) for _ in range(10)] >>> np.stack(arrays, axis=0).shape (10, 3, 4) >>> np.stack(arrays, axis=1).shape (3, 10, 4) >>> np.stack(arrays, axis=2).shape (3, 4, 10) >>> a = np.array([1, 2, 3]) >>> b = np.array([2, 3, 4]) >>> np.stack((a, b)) array([[1, 2, 3], [2, 3, 4]]) >>> np.stack((a, b), axis=-1) array([[1, 2], [2, 3], [3, 4]]) " :arglists '[[& [args {:as kwargs}]]]} stack (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "stack")))) (def ^{:doc "right_shift(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Shift the bits of an integer to the right. Bits are shifted to the right `x2`. Because the internal representation of numbers is in binary format, this operation is equivalent to dividing `x1` by ``2**x2``. Parameters ---------- x1 : array_like, int Input values. x2 : array_like, int Number of bits to remove at the right of `x1`. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray, int Return `x1` with bits shifted `x2` times to the right. This is a scalar if both `x1` and `x2` are scalars. See Also -------- left_shift : Shift the bits of an integer to the left. binary_repr : Return the binary representation of the input number as a string. Examples -------- >>> np.binary_repr(10) '1010' >>> np.right_shift(10, 1) 5 >>> np.binary_repr(5) '101' >>> np.right_shift(10, [1,2,3]) array([5, 2, 1]) The ``>>`` operator can be used as a shorthand for ``np.right_shift`` on ndarrays. >>> x1 = 10 >>> x2 = np.array([1,2,3]) >>> x1 >> x2 array([5, 2, 1])" :arglists '[[self & [args {:as kwargs}]]]} right_shift (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "right_shift")))) (def ^{:doc " Compute the variance along the specified axis, while ignoring NaNs. Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis. For all-NaN slices or slices with zero degrees of freedom, NaN is returned and a `RuntimeWarning` is raised. .. versionadded:: 1.8.0 Parameters ---------- a : array_like Array containing numbers whose variance is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the variance is computed. The default is to compute the variance of the flattened array. dtype : data-type, optional Type to use in computing the variance. For arrays of integer type the default is `float64`; for arrays of float types it is the same as the array type. out : ndarray, optional Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary. ddof : int, optional \"Delta Degrees of Freedom\": the divisor used in the calculation is ``N - ddof``, where ``N`` represents the number of non-NaN elements. By default `ddof` is zero. 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 `a`. Returns ------- variance : ndarray, see dtype parameter above If `out` is None, return a new array containing the variance, otherwise return a reference to the output array. If ddof is >= the number of non-NaN elements in a slice or the slice contains only NaNs, then the result for that slice is NaN. See Also -------- std : Standard deviation mean : Average var : Variance while not ignoring NaNs nanstd, nanmean :ref:`ufuncs-output-type` Notes ----- The variance is the average of the squared deviations from the mean, i.e., ``var = mean(abs(x - x.mean())**2)``. The mean is normally calculated as ``x.sum() / N``, where ``N = len(x)``. If, however, `ddof` is specified, the divisor ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1`` provides an unbiased estimator of the variance of a hypothetical infinite population. ``ddof=0`` provides a maximum likelihood estimate of the variance for normally distributed variables. Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative. For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for `float32` (see example below). Specifying a higher-accuracy accumulator using the ``dtype`` keyword can alleviate this issue. For this function to work on sub-classes of ndarray, they must define `sum` with the kwarg `keepdims` Examples -------- >>> a = np.array([[1, np.nan], [3, 4]]) >>> np.nanvar(a) 1.5555555555555554 >>> np.nanvar(a, axis=0) array([1., 0.]) >>> np.nanvar(a, axis=1) array([0., 0.25]) # may vary " :arglists '[[& [args {:as kwargs}]]]} nanvar (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "nanvar")))) (def ^{:doc " A sub-package for efficiently dealing with polynomials. Within the documentation for this sub-package, a \"finite power series,\" i.e., a polynomial (also referred to simply as a \"series\") is represented by a 1-D numpy array of the polynomial's coefficients, ordered from lowest order term to highest. For example, array([1,2,3]) represents ``P_0 + 2*P_1 + 3*P_2``, where P_n is the n-th order basis polynomial applicable to the specific module in question, e.g., `polynomial` (which \"wraps\" the \"standard\" basis) or `chebyshev`. For optimal performance, all operations on polynomials, including evaluation at an argument, are implemented as operations on the coefficients. Additional (module-specific) information can be found in the docstring for the module of interest. This package provides *convenience classes* for each of six different kinds of polynomials: ============ ================ **Name** **Provides** ============ ================ Polynomial Power series Chebyshev Chebyshev series Legendre Legendre series Laguerre Laguerre series Hermite Hermite series HermiteE HermiteE series ============ ================ These *convenience classes* provide a consistent interface for creating, manipulating, and fitting data with polynomials of different bases. The convenience classes are the preferred interface for the `~numpy.polynomial` package, and are available from the `numpy.polynomial` namespace. This eliminates the need to navigate to the corresponding submodules, e.g. ``np.polynomial.Polynomial`` or ``np.polynomial.Chebyshev`` instead of ``np.polynomial.polynomial.Polynomial`` or ``np.polynomial.chebyshev.Chebyshev``, respectively. The classes provide a more consistent and concise interface than the type-specific functions defined in the submodules for each type of polynomial. For example, to fit a Chebyshev polynomial with degree ``1`` to data given by arrays ``xdata`` and ``ydata``, the `~chebyshev.Chebyshev.fit` class method:: >>> from numpy.polynomial import Chebyshev >>> c = Chebyshev.fit(xdata, ydata, deg=1) is preferred over the `chebyshev.chebfit` function from the `numpy.polynomial.chebyshev` module:: >>> from numpy.polynomial.chebyshev import chebfit >>> c = chebfit(xdata, ydata, deg=1) See :doc:`routines.polynomials.classes` for more details. Convenience Classes =================== The following lists the various constants and methods common to all of the classes representing the various kinds of polynomials. In the following, the term ``Poly`` represents any one of the convenience classes (e.g. ``Polynomial``, ``Chebyshev``, ``Hermite``, etc.) while the lowercase ``p`` represents an **instance** of a polynomial class. Constants --------- - ``Poly.domain`` -- Default domain - ``Poly.window`` -- Default window - ``Poly.basis_name`` -- String used to represent the basis - ``Poly.maxpower`` -- Maximum value ``n`` such that ``p**n`` is allowed - ``Poly.nickname`` -- String used in printing Creation -------- Methods for creating polynomial instances. - ``Poly.basis(degree)`` -- Basis polynomial of given degree - ``Poly.identity()`` -- ``p`` where ``p(x) = x`` for all ``x`` - ``Poly.fit(x, y, deg)`` -- ``p`` of degree ``deg`` with coefficients determined by the least-squares fit to the data ``x``, ``y`` - ``Poly.fromroots(roots)`` -- ``p`` with specified roots - ``p.copy()`` -- Create a copy of ``p`` Conversion ---------- Methods for converting a polynomial instance of one kind to another. - ``p.cast(Poly)`` -- Convert ``p`` to instance of kind ``Poly`` - ``p.convert(Poly)`` -- Convert ``p`` to instance of kind ``Poly`` or map between ``domain`` and ``window`` Calculus -------- - ``p.deriv()`` -- Take the derivative of ``p`` - ``p.integ()`` -- Integrate ``p`` Validation ---------- - ``Poly.has_samecoef(p1, p2)`` -- Check if coefficients match - ``Poly.has_samedomain(p1, p2)`` -- Check if domains match - ``Poly.has_sametype(p1, p2)`` -- Check if types match - ``Poly.has_samewindow(p1, p2)`` -- Check if windows match Misc ---- - ``p.linspace()`` -- Return ``x, p(x)`` at equally-spaced points in ``domain`` - ``p.mapparms()`` -- Return the parameters for the linear mapping between ``domain`` and ``window``. - ``p.roots()`` -- Return the roots of `p`. - ``p.trim()`` -- Remove trailing coefficients. - ``p.cutdeg(degree)`` -- Truncate p to given degree - ``p.truncate(size)`` -- Truncate p to given size "} polynomial (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "polynomial")))) (def ^{:doc " Return the derivative of the specified order of a polynomial. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. Parameters ---------- p : poly1d or sequence Polynomial to differentiate. A sequence is interpreted as polynomial coefficients, see `poly1d`. m : int, optional Order of differentiation (default: 1) Returns ------- der : poly1d A new polynomial representing the derivative. See Also -------- polyint : Anti-derivative of a polynomial. poly1d : Class for one-dimensional polynomials. Examples -------- The derivative of the polynomial :math:`x^3 + x^2 + x^1 + 1` is: >>> p = np.poly1d([1,1,1,1]) >>> p2 = np.polyder(p) >>> p2 poly1d([3, 2, 1]) which evaluates to: >>> p2(2.) 17.0 We can verify this, approximating the derivative with ``(f(x + h) - f(x))/h``: >>> (p(2. + 0.001) - p(2.)) / 0.001 17.007000999997857 The fourth-order derivative of a 3rd-order polynomial is zero: >>> np.polyder(p, 2) poly1d([6, 2]) >>> np.polyder(p, 3) poly1d([6]) >>> np.polyder(p, 4) poly1d([0]) " :arglists '[[& [args {:as kwargs}]]]} polyder (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polyder")))) (def ^{:doc " Move axes of an array to new positions. Other axes remain in their original order. .. versionadded:: 1.11.0 Parameters ---------- a : np.ndarray The array whose axes should be reordered. source : int or sequence of int Original positions of the axes to move. These must be unique. destination : int or sequence of int Destination positions for each of the original axes. These must also be unique. Returns ------- result : np.ndarray Array with moved axes. This array is a view of the input array. See Also -------- transpose: Permute the dimensions of an array. swapaxes: Interchange two axes of an array. Examples -------- >>> x = np.zeros((3, 4, 5)) >>> np.moveaxis(x, 0, -1).shape (4, 5, 3) >>> np.moveaxis(x, -1, 0).shape (5, 3, 4) These all achieve the same result: >>> np.transpose(x).shape (5, 4, 3) >>> np.swapaxes(x, 0, -1).shape (5, 4, 3) >>> np.moveaxis(x, [0, 1], [-1, -2]).shape (5, 4, 3) >>> np.moveaxis(x, [0, 1, 2], [-1, -2, -3]).shape (5, 4, 3) " :arglists '[[& [args {:as kwargs}]]]} moveaxis (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "moveaxis")))) (def ^{:doc " concatenate((a1, a2, ...), axis=0, out=None, dtype=None, casting=\"same_kind\") Join a sequence of arrays along an existing axis. Parameters ---------- a1, a2, ... : sequence of array_like The arrays must have the same shape, except in the dimension corresponding to `axis` (the first, by default). axis : int, optional The axis along which the arrays will be joined. If axis is None, arrays are flattened before use. Default is 0. out : ndarray, optional If provided, the destination to place the result. The shape must be correct, matching that of what concatenate would have returned if no out argument were specified. dtype : str or dtype If provided, the destination array will have this dtype. Cannot be provided together with `out`. .. versionadded:: 1.20.0 casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur. Defaults to 'same_kind'. .. versionadded:: 1.20.0 Returns ------- res : ndarray The concatenated array. See Also -------- ma.concatenate : Concatenate function that preserves input masks. array_split : Split an array into multiple sub-arrays of equal or near-equal size. split : Split array into a list of multiple sub-arrays of equal size. hsplit : Split array into multiple sub-arrays horizontally (column wise). vsplit : Split array into multiple sub-arrays vertically (row wise). dsplit : Split array into multiple sub-arrays along the 3rd axis (depth). stack : Stack a sequence of arrays along a new axis. block : Assemble arrays from blocks. hstack : Stack arrays in sequence horizontally (column wise). vstack : Stack arrays in sequence vertically (row wise). dstack : Stack arrays in sequence depth wise (along third dimension). column_stack : Stack 1-D arrays as columns into a 2-D array. Notes ----- When one or more of the arrays to be concatenated is a MaskedArray, this function will return a MaskedArray object instead of an ndarray, but the input masks are *not* preserved. In cases where a MaskedArray is expected as input, use the ma.concatenate function from the masked array module instead. Examples -------- >>> a = np.array([[1, 2], [3, 4]]) >>> b = np.array([[5, 6]]) >>> np.concatenate((a, b), axis=0) array([[1, 2], [3, 4], [5, 6]]) >>> np.concatenate((a, b.T), axis=1) array([[1, 2, 5], [3, 4, 6]]) >>> np.concatenate((a, b), axis=None) array([1, 2, 3, 4, 5, 6]) This function will not preserve masking of MaskedArray inputs. >>> a = np.ma.arange(3) >>> a[1] = np.ma.masked >>> b = np.arange(2, 5) >>> a masked_array(data=[0, --, 2], mask=[False, True, False], fill_value=999999) >>> b array([2, 3, 4]) >>> np.concatenate([a, b]) masked_array(data=[0, 1, 2, 2, 3, 4], mask=False, fill_value=999999) >>> np.ma.concatenate([a, b]) masked_array(data=[0, --, 2, 2, 3, 4], mask=[False, True, False, False, False, False], fill_value=999999) " :arglists '[[& [args {:as kwargs}]]]} concatenate (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "concatenate")))) (def ^{:doc " Return an array of zeros with the same shape and type as a given array. Parameters ---------- a : array_like The shape and data-type of `a` define these same attributes of the returned array. dtype : data-type, optional Overrides the data type of the result. .. versionadded:: 1.6.0 order : {'C', 'F', 'A', or 'K'}, optional Overrides the memory layout of the result. '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. .. versionadded:: 1.6.0 subok : bool, optional. If True, then the newly created array will use the sub-class type of `a`, otherwise it will be a base-class array. Defaults to True. shape : int or sequence of ints, optional. Overrides the shape of the result. If order='K' and the number of dimensions is unchanged, will try to keep order, otherwise, order='C' is implied. .. versionadded:: 1.17.0 Returns ------- out : ndarray Array of zeros with the same shape and type as `a`. 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. full_like : Return a new array with shape of input filled with value. zeros : Return a new array setting values to zero. Examples -------- >>> x = np.arange(6) >>> x = x.reshape((2, 3)) >>> x array([[0, 1, 2], [3, 4, 5]]) >>> np.zeros_like(x) array([[0, 0, 0], [0, 0, 0]]) >>> y = np.arange(3, dtype=float) >>> y array([0., 1., 2.]) >>> np.zeros_like(y) array([0., 0., 0.]) " :arglists '[[& [args {:as kwargs}]]]} zeros_like (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "zeros_like")))) (def ^{:doc "rint(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Round elements of the array to the nearest integer. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Output array is same shape and type as `x`. This is a scalar if `x` is a scalar. See Also -------- ceil, floor, trunc Examples -------- >>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0]) >>> np.rint(a) array([-2., -2., -0., 0., 2., 2., 2.])" :arglists '[[self & [args {:as kwargs}]]]} rint (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "rint")))) (def ^{:doc "arcsin(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Inverse sine, element-wise. Parameters ---------- x : array_like `y`-coordinate on the unit circle. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- angle : ndarray The inverse sine of each element in `x`, in radians and in the closed interval ``[-pi/2, pi/2]``. This is a scalar if `x` is a scalar. See Also -------- sin, cos, arccos, tan, arctan, arctan2, emath.arcsin Notes ----- `arcsin` is a multivalued function: for each `x` there are infinitely many numbers `z` such that :math:`sin(z) = x`. The convention is to return the angle `z` whose real part lies in [-pi/2, pi/2]. For real-valued input data types, *arcsin* always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `arcsin` is a complex analytic function that has, by convention, the branch cuts [-inf, -1] and [1, inf] and is continuous from above on the former and from below on the latter. The inverse sine is also known as `asin` or sin^{-1}. References ---------- Abramowitz, M. and Stegun, I. A., *Handbook of Mathematical Functions*, 10th printing, New York: Dover, 1964, pp. 79ff. http://www.math.sfu.ca/~cbm/aands/ Examples -------- >>> np.arcsin(1) # pi/2 1.5707963267948966 >>> np.arcsin(-1) # -pi/2 -1.5707963267948966 >>> np.arcsin(0) 0.0" :arglists '[[self & [args {:as kwargs}]]]} arcsin (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "arcsin")))) (def ^{:doc " Returns pointers to the end-points of an array. Parameters ---------- a : ndarray Input array. It must conform to the Python-side of the array interface. Returns ------- (low, high) : tuple of 2 integers The first integer is the first byte of the array, the second integer is just past the last byte of the array. If `a` is not contiguous it will not use every byte between the (`low`, `high`) values. Examples -------- >>> I = np.eye(2, dtype='f'); I.dtype dtype('float32') >>> low, high = np.byte_bounds(I) >>> high - low == I.size*I.itemsize True >>> I = np.eye(2); I.dtype dtype('float64') >>> low, high = np.byte_bounds(I) >>> high - low == I.size*I.itemsize True " :arglists '[[a]]} byte_bounds (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "byte_bounds")))) (def ^{:doc " Return an array representing the indices of a grid. Compute an array where the subarrays contain index values 0, 1, ... varying only along the corresponding axis. Parameters ---------- dimensions : sequence of ints The shape of the grid. dtype : dtype, optional Data type of the result. sparse : boolean, optional Return a sparse representation of the grid instead of a dense representation. Default is False. .. versionadded:: 1.17 Returns ------- grid : one ndarray or tuple of ndarrays If sparse is False: Returns one array of grid indices, ``grid.shape = (len(dimensions),) + tuple(dimensions)``. If sparse is True: Returns a tuple of arrays, with ``grid[i].shape = (1, ..., 1, dimensions[i], 1, ..., 1)`` with dimensions[i] in the ith place See Also -------- mgrid, ogrid, meshgrid Notes ----- The output shape in the dense case is obtained by prepending the number of dimensions in front of the tuple of dimensions, i.e. if `dimensions` is a tuple ``(r0, ..., rN-1)`` of length ``N``, the output shape is ``(N, r0, ..., rN-1)``. The subarrays ``grid[k]`` contains the N-D array of indices along the ``k-th`` axis. Explicitly:: grid[k, i0, i1, ..., iN-1] = ik Examples -------- >>> grid = np.indices((2, 3)) >>> grid.shape (2, 2, 3) >>> grid[0] # row indices array([[0, 0, 0], [1, 1, 1]]) >>> grid[1] # column indices array([[0, 1, 2], [0, 1, 2]]) The indices can be used as an index into an array. >>> x = np.arange(20).reshape(5, 4) >>> row, col = np.indices((2, 3)) >>> x[row, col] array([[0, 1, 2], [4, 5, 6]]) Note that it would be more straightforward in the above example to extract the required elements directly with ``x[:2, :3]``. If sparse is set to true, the grid will be returned in a sparse representation. >>> i, j = np.indices((2, 3), sparse=True) >>> i.shape (2, 1) >>> j.shape (1, 3) >>> i # row indices array([[0], [1]]) >>> j # column indices array([[0, 1, 2]]) " :arglists '[[dimensions & [{dtype :dtype, sparse :sparse}]] [dimensions & [{dtype :dtype}]] [dimensions]]} indices (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "indices")))) (def ^{:doc " Return coordinate matrices from coordinate vectors. Make N-D coordinate arrays for vectorized evaluations of N-D scalar/vector fields over N-D grids, given one-dimensional coordinate arrays x1, x2,..., xn. .. versionchanged:: 1.9 1-D and 0-D cases are allowed. Parameters ---------- x1, x2,..., xn : array_like 1-D arrays representing the coordinates of a grid. indexing : {'xy', 'ij'}, optional Cartesian ('xy', default) or matrix ('ij') indexing of output. See Notes for more details. .. versionadded:: 1.7.0 sparse : bool, optional If True a sparse grid is returned in order to conserve memory. Default is False. .. versionadded:: 1.7.0 copy : bool, optional If False, a view into the original arrays are returned in order to conserve memory. Default is True. Please note that ``sparse=False, copy=False`` will likely return non-contiguous arrays. Furthermore, more than one element of a broadcast array may refer to a single memory location. If you need to write to the arrays, make copies first. .. versionadded:: 1.7.0 Returns ------- X1, X2,..., XN : ndarray For vectors `x1`, `x2`,..., 'xn' with lengths ``Ni=len(xi)`` , return ``(N1, N2, N3,...Nn)`` shaped arrays if indexing='ij' or ``(N2, N1, N3,...Nn)`` shaped arrays if indexing='xy' with the elements of `xi` repeated to fill the matrix along the first dimension for `x1`, the second for `x2` and so on. Notes ----- This function supports both indexing conventions through the indexing keyword argument. Giving the string 'ij' returns a meshgrid with matrix indexing, while 'xy' returns a meshgrid with Cartesian indexing. In the 2-D case with inputs of length M and N, the outputs are of shape (N, M) for 'xy' indexing and (M, N) for 'ij' indexing. In the 3-D case with inputs of length M, N and P, outputs are of shape (N, M, P) for 'xy' indexing and (M, N, P) for 'ij' indexing. The difference is illustrated by the following code snippet:: xv, yv = np.meshgrid(x, y, sparse=False, indexing='ij') for i in range(nx): for j in range(ny): # treat xv[i,j], yv[i,j] xv, yv = np.meshgrid(x, y, sparse=False, indexing='xy') for i in range(nx): for j in range(ny): # treat xv[j,i], yv[j,i] In the 1-D and 0-D case, the indexing and sparse keywords have no effect. See Also -------- mgrid : Construct a multi-dimensional \"meshgrid\" using indexing notation. ogrid : Construct an open multi-dimensional \"meshgrid\" using indexing notation. Examples -------- >>> nx, ny = (3, 2) >>> x = np.linspace(0, 1, nx) >>> y = np.linspace(0, 1, ny) >>> xv, yv = np.meshgrid(x, y) >>> xv array([[0. , 0.5, 1. ], [0. , 0.5, 1. ]]) >>> yv array([[0., 0., 0.], [1., 1., 1.]]) >>> xv, yv = np.meshgrid(x, y, sparse=True) # make sparse output arrays >>> xv array([[0. , 0.5, 1. ]]) >>> yv array([[0.], [1.]]) `meshgrid` is very useful to evaluate functions on a grid. >>> import matplotlib.pyplot as plt >>> x = np.arange(-5, 5, 0.1) >>> y = np.arange(-5, 5, 0.1) >>> xx, yy = np.meshgrid(x, y, sparse=True) >>> z = np.sin(xx**2 + yy**2) / (xx**2 + yy**2) >>> h = plt.contourf(x,y,z) >>> plt.show() " :arglists '[[& [args {:as kwargs}]]]} meshgrid (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "meshgrid")))) (def ^{:doc "A datetime stored as a 64-bit integer, counting from ``1970-01-01T00:00:00``. >>> np.datetime64(10, 'Y') numpy.datetime64('1980') >>> np.datetime64(10, 'D') numpy.datetime64('1970-01-11') See :ref:`arrays.datetime` for more information. :Character code: ``'M'``" :arglists '[[self & [args {:as kwargs}]]]} datetime64 (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "datetime64")))) (def ^{:doc " copyto(dst, src, casting='same_kind', where=True) Copies values from one array to another, broadcasting as necessary. Raises a TypeError if the `casting` rule is violated, and if `where` is provided, it selects which elements to copy. .. versionadded:: 1.7.0 Parameters ---------- dst : ndarray The array into which values are copied. src : array_like The array from which values are copied. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur when copying. * '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. where : array_like of bool, optional A boolean array which is broadcasted to match the dimensions of `dst`, and selects elements to copy from `src` to `dst` wherever it contains the value True. " :arglists '[[& [args {:as kwargs}]]]} copyto (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "copyto")))) (def ^{:doc " Returns the quotient and remainder of polynomial division. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide `. The input arrays are the coefficients (including any coefficients equal to zero) of the \"numerator\" (dividend) and \"denominator\" (divisor) polynomials, respectively. Parameters ---------- u : array_like or poly1d Dividend polynomial's coefficients. v : array_like or poly1d Divisor polynomial's coefficients. Returns ------- q : ndarray Coefficients, including those equal to zero, of the quotient. r : ndarray Coefficients, including those equal to zero, of the remainder. See Also -------- poly, polyadd, polyder, polydiv, polyfit, polyint, polymul, polysub polyval Notes ----- Both `u` and `v` must be 0-d or 1-d (ndim = 0 or 1), but `u.ndim` need not equal `v.ndim`. In other words, all four possible combinations - ``u.ndim = v.ndim = 0``, ``u.ndim = v.ndim = 1``, ``u.ndim = 1, v.ndim = 0``, and ``u.ndim = 0, v.ndim = 1`` - work. Examples -------- .. math:: \\frac{3x^2 + 5x + 2}{2x + 1} = 1.5x + 1.75, remainder 0.25 >>> x = np.array([3.0, 5.0, 2.0]) >>> y = np.array([2.0, 1.0]) >>> np.polydiv(x, y) (array([1.5 , 1.75]), array([0.25])) " :arglists '[[& [args {:as kwargs}]]]} polydiv (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "polydiv")))) (def ^{:doc ""} ERR_PRINT 4) (def ^{:doc "modf(x[, out1, out2], / [, out=(None, None)], *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Return the fractional and integral parts of an array, element-wise. The fractional and integral parts are negative if the given number is negative. Parameters ---------- x : array_like Input array. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y1 : ndarray Fractional part of `x`. This is a scalar if `x` is a scalar. y2 : ndarray Integral part of `x`. This is a scalar if `x` is a scalar. Notes ----- For integer input the return values are floats. See Also -------- divmod : ``divmod(x, 1)`` is equivalent to ``modf`` with the return values switched, except it always has a positive remainder. Examples -------- >>> np.modf([0, 3.5]) (array([ 0. , 0.5]), array([ 0., 3.])) >>> np.modf(-0.5) (-0.5, -0)" :arglists '[[self & [args {:as kwargs}]]]} modf (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "modf")))) (def ^{:doc "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]')" :arglists '[[self & [args {:as kwargs}]]]} busdaycalendar (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "busdaycalendar")))) (def ^{:doc "deg2rad(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Convert angles from degrees to radians. Parameters ---------- x : array_like Angles in degrees. out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- y : ndarray The corresponding angle in radians. This is a scalar if `x` is a scalar. See Also -------- rad2deg : Convert angles from radians to degrees. unwrap : Remove large jumps in angle by wrapping. Notes ----- .. versionadded:: 1.3.0 ``deg2rad(x)`` is ``x * pi / 180``. Examples -------- >>> np.deg2rad(180) 3.1415926535897931" :arglists '[[self & [args {:as kwargs}]]]} deg2rad (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "deg2rad")))) (def ^{:doc ""} FPE_UNDERFLOW 4) (def ^{:doc "Signed integer type, compatible with C ``long long``. :Character code: ``'q'``" :arglists '[[self & [args {:as kwargs}]]]} longlong (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "longlong")))) (def ^{:doc " Distributor init file Distributors: you can add custom code here to support particular distributions of numpy. For example, this is a good place to put any checks for hardware requirements. The numpy standard source distribution will not put code in this file, so you can safely replace this file with your own version. "} _distributor_init (as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* "_distributor_init")))) (def ^{:doc "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" :arglists '[[self & [args {:as kwargs}]]]} add_docstring (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "add_docstring")))) (def ^{:doc " Compute the median along the specified axis. Returns the median of the array elements. Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : {int, sequence of int, None}, optional Axis or axes along which the medians are computed. The default is to compute the median along a flattened version of the array. A sequence of axes is supported since version 1.9.0. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow use of memory of input array `a` for calculations. The input array will be modified by the call to `median`. This will save memory when you do not need to preserve the contents of the input array. Treat the input as undefined, but it will probably be fully or partially sorted. Default is False. If `overwrite_input` is ``True`` and `a` is not already an `ndarray`, an error will be raised. 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.9.0 Returns ------- median : ndarray A new array holding the result. If the input contains integers or floats smaller than ``float64``, then the output data-type is ``np.float64``. Otherwise, the data-type of the output is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean, percentile Notes ----- Given a vector ``V`` of length ``N``, the median of ``V`` is the middle value of a sorted copy of ``V``, ``V_sorted`` - i e., ``V_sorted[(N-1)/2]``, when ``N`` is odd, and the average of the two middle values of ``V_sorted`` when ``N`` is even. Examples -------- >>> a = np.array([[10, 7, 4], [3, 2, 1]]) >>> a array([[10, 7, 4], [ 3, 2, 1]]) >>> np.median(a) 3.5 >>> np.median(a, axis=0) array([6.5, 4.5, 2.5]) >>> np.median(a, axis=1) array([7., 2.]) >>> m = np.median(a, axis=0) >>> out = np.zeros_like(m) >>> np.median(a, axis=0, out=m) array([6.5, 4.5, 2.5]) >>> m array([6.5, 4.5, 2.5]) >>> b = a.copy() >>> np.median(b, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) >>> b = a.copy() >>> np.median(b, axis=None, overwrite_input=True) 3.5 >>> assert not np.all(a==b) " :arglists '[[& [args {:as kwargs}]]]} median (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "median")))) (def ^{:doc "bitwise_xor(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) Compute the bit-wise XOR of two arrays element-wise. Computes the bit-wise XOR of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ``^``. Parameters ---------- x1, x2 : array_like Only integer and boolean types are handled. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which becomes the shape of the output). out : ndarray, None, or tuple of ndarray and None, optional A location into which the result is stored. If provided, it must have a shape that the inputs broadcast to. If not provided or None, a freshly-allocated array is returned. A tuple (possible only as a keyword argument) must have length equal to the number of outputs. 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 `. Returns ------- out : ndarray or scalar Result. This is a scalar if both `x1` and `x2` are scalars. See Also -------- logical_xor bitwise_and bitwise_or binary_repr : Return the binary representation of the input number as a string. Examples -------- The number 13 is represented by ``00001101``. Likewise, 17 is represented by ``00010001``. The bit-wise XOR of 13 and 17 is therefore ``00011100``, or 28: >>> np.bitwise_xor(13, 17) 28 >>> np.binary_repr(28) '11100' >>> np.bitwise_xor(31, 5) 26 >>> np.bitwise_xor([31,3], 5) array([26, 6]) >>> np.bitwise_xor([31,3], [5,6]) array([26, 5]) >>> np.bitwise_xor([True, True], [False, True]) array([ True, False]) The ``^`` operator can be used as a shorthand for ``np.bitwise_xor`` on ndarrays. >>> x1 = np.array([True, True]) >>> x2 = np.array([False, True]) >>> x1 ^ x2 array([ True, False])" :arglists '[[self & [args {:as kwargs}]]]} bitwise_xor (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* "bitwise_xor")))) ================================================ FILE: deps.edn ================================================ {:paths ["src"] :deps {org.clojure/clojure {:mvn/version "1.11.1" :scope "provided"} cnuernber/dtype-next {:mvn/version "10.124"} net.java.dev.jna/jna {:mvn/version "5.12.1"} org.clojure/data.json {:mvn/version "1.0.0"} ;;Replace me with caffeine... com.google.guava/guava {:mvn/version "31.1-jre"}} :aliases {:dev {:extra-deps {criterium/criterium {:mvn/version"0.4.5"} ch.qos.logback/logback-classic {:mvn/version "1.1.3"}}} :fastcall {:jvm-opts ["-Dlibpython_clj.manual_gil=true"]} :jdk-17 {:jvm-opts ["--add-modules" "jdk.incubator.foreign" "--enable-native-access=ALL-UNNAMED"]} :jdk-19 {:jvm-opts ["--enable-native-access=ALL-UNNAMED"]} :codox {:extra-deps {codox-theme-rdash/codox-theme-rdash {:mvn/version "0.1.2"} nrepl/nrepl {:mvn/version "0.8.3"} cider/cider-nrepl {:mvn/version "0.25.5"} com.cnuernber/codox {:mvn/version "1.001"}} :exec-fn codox.main/-main :exec-args {:arg-paths [[:aliases :depstar :exec-args]] :name "libpython-clj" :group-id "clj-python" :artifact-id "libpython-clj" :version "2.026" :description "Python bindings for Clojure" :metadata {:doc/format :markdown} :google-analytics "G-LN7PG6FJ2D" :html {:transforms [[:head] [:append [:script {:async true :src "https://www.googletagmanager.com/gtag/js?id=G-LN7PG6FJ2D"}]] [:head] [:append [:script "window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-LN7PG6FJ2D');"]]]} :themes [:rdash] :source-paths ["src"] :output-path "docs" :doc-paths ["topics"] :source-uri "https://github.com/clj-python/libpython-clj/blob/master/{filepath}#L{line}" :namespaces [libpython-clj2.python libpython-clj2.python.class libpython-clj2.codegen libpython-clj2.python.np-array libpython-clj2.require libpython-clj2.embedded libpython-clj2.java-api]}} :test {:extra-deps {com.cognitect/test-runner {:git/url "https://github.com/cognitect-labs/test-runner" :sha "209b64504cb3bd3b99ecfec7937b358a879f55c1"} ch.qos.logback/logback-classic {:mvn/version "1.1.3"}} :extra-paths ["test"] :main-opts ["-m" "cognitect.test-runner"]} :build {:deps {io.github.clojure/tools.build {:mvn/version "0.10.5"}} :ns-default build} :deploy {:replace-deps {slipset/deps-deploy {:mvn/version "0.1.5"}} :exec-fn deps-deploy.deps-deploy/deploy :exec-args {:installer :remote :sign-releases? true :artifact "target/libpython-clj.jar"}} :install {:replace-deps {slipset/deps-deploy {:mvn/version "0.1.5"}} :exec-fn deps-deploy.deps-deploy/deploy :exec-args {:installer :local :artifact "target/libpython-clj.jar"}} }} ================================================ FILE: dockerfiles/CondaDockerfile ================================================ # We will use Ubuntu for our image FROM ubuntu:22.04 # Updating Ubuntu packages ARG CLOJURE_TOOLS_VERSION=1.10.1.507 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get -qq update && apt-get -qq -y install curl wget bzip2 openjdk-8-jdk-headless \ && curl -sSL https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -o /tmp/miniconda.sh \ && bash /tmp/miniconda.sh -bfp /usr/local \ && rm -rf /tmp/miniconda.sh \ && conda install -y python=3 \ && conda update conda \ && curl -o install-clojure https://download.clojure.org/install/linux-install-${CLOJURE_TOOLS_VERSION}.sh \ && chmod +x install-clojure \ && ./install-clojure && rm install-clojure \ && wget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein \ && chmod a+x lein \ && mv lein /usr/bin \ && apt-get -qq -y autoremove \ && apt-get autoclean \ && rm -rf /var/lib/apt/lists/* /var/log/dpkg.log \ && conda clean --all --yes ENV PATH /opt/conda/bin:$PATH ARG USERID ARG GROUPID ARG USERNAME RUN groupadd -g $GROUPID $USERNAME RUN useradd -u $USERID -g $GROUPID $USERNAME RUN mkdir /home/$USERNAME && chown $USERNAME:$USERNAME /home/$USERNAME USER $USERNAME RUN conda create -n pyclj python=3.6 && conda install -n pyclj numpy mxnet \ && echo "source activate pyclj" > /home/$USERNAME/.bashrc ## cause leiningen to install RUN lein -v ## To install pip packages into the pyclj environment do RUN conda run -n pyclj python3 -mpip install numpy ================================================ FILE: dockerfiles/Py38Dockerfile ================================================ # We will use Ubuntu for our image FROM ubuntu:22.04 # Updating Ubuntu packages ARG CLOJURE_TOOLS_VERSION=1.10.1.507 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get -qq update && apt-get -qq -y install curl wget bzip2 openjdk-8-jdk-headless python3.8 libpython3.8 python3-pip \ && curl -o install-clojure https://download.clojure.org/install/linux-install-${CLOJURE_TOOLS_VERSION}.sh \ && chmod +x install-clojure \ && ./install-clojure && rm install-clojure \ && wget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein \ && chmod a+x lein \ && mv lein /usr/bin \ && apt-get -qq -y autoremove \ && apt-get autoclean \ && rm -rf /var/lib/apt/lists/* /var/log/dpkg.log ARG USERID ARG GROUPID ARG USERNAME RUN groupadd -g $GROUPID $USERNAME RUN useradd -u $USERID -g $GROUPID $USERNAME RUN mkdir /home/$USERNAME && chown $USERNAME:$USERNAME /home/$USERNAME USER $USERNAME # Install leiningen during build process RUN lein -v RUN python3.8 -mpip install numpy ================================================ FILE: dockerfiles/Py39Dockerfile ================================================ # We will use Ubuntu for our image FROM ubuntu:22.04 # Updating Ubuntu packages ARG CLOJURE_TOOLS_VERSION=1.10.1.507 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get -qq update \ && apt install -y software-properties-common \ && add-apt-repository -y ppa:deadsnakes/ppa RUN apt-get -qq update && apt-get -qq -y install curl wget bzip2 openjdk-8-jdk-headless python3.9 libpython3.9 python3-pip python3-distutils\ && curl -o install-clojure https://download.clojure.org/install/linux-install-${CLOJURE_TOOLS_VERSION}.sh \ && chmod +x install-clojure \ && ./install-clojure && rm install-clojure \ && wget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein \ && chmod a+x lein \ && mv lein /usr/bin \ && apt-get -qq -y autoremove \ && apt-get autoclean \ && rm -rf /var/lib/apt/lists/* /var/log/dpkg.log ARG USERID ARG GROUPID ARG USERNAME RUN groupadd -g $GROUPID $USERNAME RUN useradd -u $USERID -g $GROUPID $USERNAME RUN mkdir /home/$USERNAME && chown $USERNAME:$USERNAME /home/$USERNAME USER $USERNAME # Install leiningen during build process RUN lein -v # RUN python3.9 -mpip install numpy ================================================ FILE: docs/Usage.html ================================================ LibPython-CLJ Usage

Project

Topics

Namespaces

LibPython-CLJ Usage

Python objects are essentially two dictionaries, one for 'attributes' and one for 'items'. When you use python and use the '.' operator, you are referencing attributes. If you use the '[]' operator, then you are referencing items. Attributes are built in, item access is optional and happens via the __getitem__ and __setitem__ attributes. This is important to realize in that the code below doesn't look like python because we are referencing the item and attribute systems by name and not via '.' or '[]'.

This would result in the following analogous code (full example further on):

table.loc[row_date]

(get-item (get-attr table :loc) row-date)

Installation

Ubuntu

sudo apt install libpython3.6
# numpy and pandas are required for unit tests.  Numpy is required for
# zero copy support.
python3.6 -m pip install numpy pandas --user

MacOSX

Python installation instructions here.

Initialize python

user> (require '[libpython-clj2.python
                 :refer [as-python as-jvm
                         ->python ->jvm
                         get-attr call-attr call-attr-kw
                         get-item initialize!
                         run-simple-string
                         add-module module-dict
                         import-module
                         python-type
                         dir]
                 :as py])

nil

; Mac and Linux
user> (initialize!)
Jun 30, 2019 4:47:39 PM clojure.tools.logging$eval7369$fn__7372 invoke
INFO: executing python initialize!
Jun 30, 2019 4:47:39 PM clojure.tools.logging$eval7369$fn__7372 invoke
INFO: Library python3.6m found at [:system "python3.6m"]
Jun 30, 2019 4:47:39 PM clojure.tools.logging$eval7369$fn__7372 invoke
INFO: Reference thread starting
:ok

; Windows with Anaconda
(initialize! ; Python executable
             :python-executable "C:\\Users\\USER\\AppData\\Local\\Continuum\\anaconda3\\python.exe"
             ; Python Library
             :library-path "C:\\Users\\USER\\AppData\\Local\\Continuum\\anaconda3\\python37.dll"
             ; Anacondas PATH environment to load native dlls of modules (numpy, etc.)
             :windows-anaconda-activate-bat "C:\\Users\\USER\\AppData\\Local\\Continuum\\anaconda3\\Scripts\\activate.bat"
             )
...
:ok

This dynamically finds the python shared library and loads it using output from the python3 executable on your system. For information about how that works, please checkout the code here.

Execute Some Python

*out* and *err* capture python stdout and stderr respectively.


user> (run-simple-string "print('hey')")
hey
{:globals
 {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>},
 :locals
 {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>}}

The results have been 'bridged' into java meaning they are still python objects but there are java wrappers over the top of them. For instance, Object.toString forwards its implementation to the python function __str__.

(def bridged (run-simple-string "print('hey')"))
(instance? java.util.Map (:globals bridged))
true
user> (:globals bridged)
{'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>}

We can get and set global variables here. If we run another string, these are in the environment. The globals map itself is the global dict of the main module:

(def main-globals (-> (add-module "__main__")
                            (module-dict)))
#'user/main-globals

user> main-globals
{'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>}
user> (keys main-globals)
("__name__"
 "__doc__"
 "__package__"
 "__loader__"
 "__spec__"
 "__annotations__"
 "__builtins__")
user> (get main-globals "__name__")
"__main__"
user> (.put main-globals "my_var" 200)
nil

user> (run-simple-string "print('your variable is:' + str(my_var))")
your variable is:200
{:globals
 {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>, 'my_var': 200},
 :locals
 {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>, 'my_var': 200}}

Running Python isn't ever really necessary, however, although it may at times be convenient. You can call attributes from clojure easily:

user> (def np (import-module "numpy"))
#'user/np
user> (def ones-ary (call-attr np "ones" [2 3]))
#'user/ones-ary
user> ones-ary
[[1. 1. 1.]
 [1. 1. 1.]]
user> (call-attr ones-ary "__len__")
2
user> (vec ones-ary)
[[1. 1. 1.] [1. 1. 1.]]
user> (type (first *1))
:pyobject
user> (get-attr ones-ary "shape")
(2, 3)
user> (vec (get-attr ones-ary "shape"))
[2 3]

user> (dir ones-ary)
["T"
 "__abs__"
 "__add__"
 "__and__"
 "__array__"
 "__array_finalize__"
 ...
 ...
 "strides"
 "sum"
 "swapaxes"
 "take"
 "tobytes"
 "tofile"
 "tolist"
 "tostring"
 "trace"
 "transpose"
 "var"
 "view"]

### DataFrame access full example

Here's how to create Pandas DataFrame and accessing its rows via `loc` in both Python and Clojure:

```python
# Python
import numpy as np
import pandas as pan

dates = pan.date_range("1/1/2000", periods=8)
table = pan.DataFrame(np.random.randn(8, 4), index=dates, columns=["A", "B", "C", "D"])
row_date = pan.date_range(start="2000-01-01", end="2000-01-01")
table.loc[row_date]

; Clojure
(require '[libpython-clj2.require :refer [require-python]])
(require-python '[numpy :as np])
(require-python '[pandas :as pan])

(def dates (pan/date_range "1/1/2000" :periods 8))
(def table (pan/DataFrame (call-attr np/random :randn 8 4) :index dates :columns ["A" "B" "C" "D"]))
(def row-date (pan/date_range :start "2000-01-01" :end "2000-01-01"))
(get-item (get-attr table :loc) row-date)

Errors

Errors are caught and an exception is thrown. The error text is saved verbatim in the exception:

user> (run-simple-string "print('syntax errrr")
Execution error (ExceptionInfo) at libpython-clj.python.interpreter/check-error-throw (interpreter.clj:260).
  File "<string>", line 1
    print('syntax errrr
                      ^
SyntaxError: EOL while scanning string literal

Some Syntax Sugar

user> (py/from-import numpy linspace)
#'user/linspace
user> (linspace 2 3 :num 10)
[2.         2.11111111 2.22222222 2.33333333 2.44444444 2.55555556
 2.66666667 2.77777778 2.88888889 3.        ]
user> (doc linspace)
-------------------------
user/linspace

    Return evenly spaced numbers over a specified interval.

    Returns `num` evenly spaced samples, calculated over the
    interval [`start`, `stop`].
  • from-import - sugar around python from a import b. Takes multiple b's.
  • import-as - sugar around python import a as b.
  • $a - call an attribute using symbol att name. Keywords map to kwargs
  • $c - call an object mapping keywords to kwargs

Experimental Sugar

We are trying to find the best way to handle attributes in order to shorten generic python notebook-type usage. The currently implemented direction is:

  • $. - get an attribute. Can pass in symbol, string, or keyword
  • $.. - get an attribute. If more args are present, get the attribute on that result.
user> (py/$. numpy linspace)
<function linspace at 0x7fa6642766a8>
user> (py/$.. numpy random shuffle)
<built-in method shuffle of numpy.random.mtrand.RandomState object at 0x7fa66410cca8>
Extra sugar

libpython-clj offers syntactic forms similar to those offered by Clojure for interacting with Python classes and objects.

Class/object methods Where in Clojure you would use (. obj method arg1 arg2 ... argN), you can use (py. pyobj method arg1 arg2 ... argN).

In Python, this is equivalent to pyobj.method(arg1, arg2, ..., argN). Concrete examples are shown below.

Class/object attributes Where in Clojure you would use (.- obj attr), you can use (py.- pyobj attr).

In Python, this is equivalent to pyobj.attr. Concrete examples shown below.

Nested attribute access To achieve a chain of method/attribute access, use the py.. for.

(py.. (requests/get "http://www.google.com")
      -content
      (decode "latin-1"))

(Note: requires Python requests module installled)

Examples

user=> (require '[libpython-clj2.python :as py :refer [py. py.. py.-]])
nil
user=> (require '[libpython-clj2.require :refer [require-python]])

... debug info ...

user=> (require-python '[builtins :as python])
WARNING: AssertionError already refers to: class java.lang.AssertionError in namespace: builtins, being replaced by: #'builtins/AssertionError
WARNING: Exception already refers to: class java.lang.Exception in namespace: builtins, being replaced by: #'builtins/Exception
nil
user=> (def xs (python/list))
#'user/xs
user=> (py. xs append 1)
nil
user=> xs
[1]
user=> (py. xs extend [1 2 3])
nil
user=> xs
[1, 1, 2, 3]
user=> (py. xs __len__)
4
user=> ((py.- xs __len__)) ;; attribute syntax to get then call method
4
user=> (py. xs pop)
3
user=> (py. xs clear)
nil
;; requires Python requests module installed
user=> (require-python 'requests)
nil
user=> (def requests (py/import-module "requests"))
#'user/requests
user=> (py.. requests (get "http://www.google.com") -content (decode "latin-1"))
"<!doctype html><html itemscope=\"\" ... snip ... "

Numpy

Speaking of numpy, you can move data between numpy and java easily.

(require '[tech.v3.tensor :as dtt])
;;includes the appropriate protocols and multimethod overloads
(require '[libpython-clj2.python.np-array]
;;python objects created now for numpy arrays will be different.  So you have to require
;;np-array *before* you create your numpy data.
user> (def ones-ary (py/py. np ones [2 3]))
#'user/ones-ary
user> (def tens-data (dtt/as-tensor ones-ary))
#'user/tens-data
user> tens-data
#tech.v3.tensor<float64>[2 3]
[[1.000 1.000 1.000]
 [1.000 1.000 1.000]]


user> (require '[tech.v3.datatype :as dtype])
nil
;;Only constant-time count items can be copied, so vectors and arrays and such.
user> (def ignored (dtype/copy! (vec (repeat 6 5)) tens-data))
#'user/ignored
user> (.put main-globals "ones_ary" ones-ary)
nil

user> (run-simple-string "print(ones_ary)")
[[5. 5. 5.]
 [5. 5. 5.]]
{:globals
 {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>, 'my_var': 200, 'ones_ary': array([[5., 5., 5.],
       [5., 5., 5.]])},
 :locals
 {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>, 'my_var': 200, 'ones_ary': array([[5., 5., 5.],
       [5., 5., 5.]])}}

So heavy data has a zero-copy route. Anything backed by a :native-buffer has a zero copy pathway to and from numpy. For more information on how this happens, please refer to the datatype library documentation.

Just keep in mind, careless usage of zero copy is going to cause spooky action at a distance.

Pickle

Speaking of numpy, you can pickle python objects and transform the result via numpy and dtype to a java byte array and back:

user> (require '[libpython-clj2.python :as py])
nil
user> (py/initialize!)
Sep 03, 2022 11:23:34 AM clojure.tools.logging$eval5948$fn__5951 invoke
INFO: Detecting startup info
Sep 03, 2022 11:23:34 AM clojure.tools.logging$eval5948$fn__5951 invoke
INFO: Startup info {:lib-version "3.9", :java-library-path-addendum "/home/chrisn/miniconda3/lib", :exec-prefix "/home/chrisn/miniconda3", :executable "/home/chrisn/miniconda3/bin/python3", :libnames ("python3.9m" "python3.9"), :prefix "/home/chrisn/miniconda3", :base-prefix "/home/chrisn/miniconda3", :libname "python3.9m", :base-exec-prefix "/home/chrisn/miniconda3", :python-home "/home/chrisn/miniconda3", :version [3 9 1], :platform "linux"}
Sep 03, 2022 11:23:34 AM clojure.tools.logging$eval5948$fn__5951 invoke
INFO: Prefixing java library path: /home/chrisn/miniconda3/lib
Sep 03, 2022 11:23:35 AM clojure.tools.logging$eval5948$fn__5951 invoke
INFO: Loading python library: python3.9
Sep 03, 2022 11:23:35 AM clojure.tools.logging$eval5948$fn__5951 invoke
INFO: Reference thread starting
:ok
user> (def data (py/->python {:a 1 :b 2}))
#'user/data
user> (def pickle (py/import-module "pickle"))
#'user/pickle
user> (def bdata (py/py. pickle dumps data))
#'user/bdata
user> bdata
b'\x80\x04\x95\x11\x00\x00\x00\x00\x00\x00\x00}\x94(\x8c\x01a\x94K\x01\x8c\x01b\x94K\x02u.'
user> (def np (py/import-module "numpy"))
#'user/np
user> (py/py. np frombuffer bdata :dtype "int8")
[-128    4 -107   17    0    0    0    0    0    0    0  125 -108   40
 -116    1   97 -108   75    1 -116    1   98 -108   75    2  117   46]
user> (require '[libpython-clj2.python.np-array])
nil
user> (def ary (py/py. np frombuffer bdata :dtype "int8"))
#'user/ary
user> (py/->jvm ary)
#tech.v3.tensor<int8>[28]
[-128 4 -107 17 0 0 0 0 0 0 0 125 -108 40 -116 1 97 -108 75 1 -116 1 98 -108 75 2 117 46]
user> (require '[tech.v3.datatype :as dt])
nil
user> (dt/->byte-array *2)
[-128, 4, -107, 17, 0, 0, 0, 0, 0, 0, 0, 125, -108, 40, -116, 1, 97, -108, 75, 1,
 -116, 1, 98, -108, 75, 2, 117, 46]
user> (require '[tech.v3.tensor :as dtt])
nil
user> (dtt/as-tensor *2)
nil
user> (def bdata *3)
#'user/bdata
user> bdata
[-128, 4, -107, 17, 0, 0, 0, 0, 0, 0, 0, 125, -108, 40, -116, 1, 97, -108, 75, 1,
 -116, 1, 98, -108, 75, 2, 117, 46]
user> (type bdata)
[B
user> (def tens (dtt/reshape bdata [(dt/ecount bdata)]))
#'user/tens
user> (def pdata (py/->python tens))
#'user/pdata
user> pdata
[-128    4 -107   17    0    0    0    0    0    0    0  125 -108   40
 -116    1   97 -108   75    1 -116    1   98 -108   75    2  117   46]
user> (py/python-type *1)
:ndarray
user> (def py-ary *2)
#'user/py-ary
user> (def py-bytes (py/py. py-ary tobytes))
#'user/py-bytes
user> (py/py. pickle loads py-bytes)
{'a': 1, 'b': 2}
user>
================================================ FILE: docs/css/default.css ================================================ @import url('https://fonts.googleapis.com/css?family=PT+Sans'); body { font-family: 'PT Sans', Helvetica, sans-serif; font-size: 14px; } a { color: #337ab7; text-decoration: none; } a:hover { color: #30426a; text-decoration: underline; } pre, code { font-family: Monaco, DejaVu Sans Mono, Consolas, monospace; font-size: 9pt; margin: 15px 0; } h1 { font-weight: normal; font-size: 29px; margin: 10px 0 2px 0; padding: 0; } h2 { font-weight: normal; font-size: 25px; } h3 > a:hover { text-decoration: none; } .document h1, .namespace-index h1 { font-size: 32px; margin-top: 12px; } #header, #content, .sidebar { position: fixed; } #header { top: 0; left: 0; right: 0; height: 22px; color: #f5f5f5; padding: 5px 7px; } #content { top: 32px; right: 0; bottom: 0; overflow: auto; background: #fff; color: #333; padding: 0 18px; } .sidebar { position: fixed; top: 32px; bottom: 0; overflow: auto; } .sidebar.primary { background: #30426a; border-right: solid 1px #cccccc; left: 0; width: 250px; color: white; font-size: 110%; } .sidebar.secondary { background: #f2f2f2; border-right: solid 1px #d7d7d7; left: 251px; width: 200px; font-size: 110%; } #content.namespace-index, #content.document { left: 251px; } #content.namespace-docs { left: 452px; } #content.document { padding-bottom: 10%; } #header { background: #2d3e63; box-shadow: 0 0 8px rgba(0, 0, 0, 0.4); z-index: 100; } #header h1 { margin: 0; padding: 0; font-size: 18px; font-weight: lighter; text-shadow: -1px -1px 0px #333; } #header h1 .project-version { font-weight: normal; } .project-version { padding-left: 0.15em; } #header a, .sidebar a { display: block; text-decoration: none; } #header a { color: #f5f5f5; } .sidebar.primary, .sidebar.primary a { color: #b2bfdc; } .sidebar.primary a:hover { color: white; } .sidebar.secondary, .sidebar.secondary a { color: #738bc0; } .sidebar.secondary a:hover { color: #2d3e63; } #header h2 { float: right; font-size: 9pt; font-weight: normal; margin: 4px 3px; padding: 0; color: #bbb; } #header h2 a { display: inline; } .sidebar h3 { margin: 0; padding: 10px 13px 0 13px; font-size: 19px; font-weight: lighter; } .sidebar.primary h3.no-link { text-transform: uppercase; font-size: 12px; color: #738bc0; } .sidebar.secondary h3 a { text-transform: uppercase; font-size: 12px; color: #2d3e63; } .sidebar ul { padding: 7px 0 6px 0; margin: 0; } .sidebar ul.index-link { padding-bottom: 4px; } .sidebar li { display: block; vertical-align: middle; } .sidebar li a, .sidebar li .no-link { border-left: 3px solid transparent; padding: 0 10px; white-space: nowrap; } .sidebar li .inner { display: inline-block; padding-top: 7px; height: 24px; } .sidebar li a, .sidebar li .tree { height: 31px; } .depth-1 .inner { padding-left: 2px; } .depth-2 .inner { padding-left: 6px; } .depth-3 .inner { padding-left: 20px; } .depth-4 .inner { padding-left: 34px; } .depth-5 .inner { padding-left: 48px; } .depth-6 .inner { padding-left: 62px; } .sidebar li .tree { display: block; float: left; position: relative; top: -10px; margin: 0 4px 0 0; padding: 0; } .sidebar li.depth-1 .tree { display: none; } .sidebar li .tree .top, .sidebar li .tree .bottom { display: block; margin: 0; padding: 0; width: 7px; } .sidebar li .tree .top { border-left: 1px solid #aaa; border-bottom: 1px solid #aaa; height: 19px; } .sidebar li .tree .bottom { height: 22px; } .sidebar li.branch .tree .bottom { border-left: 1px solid #aaa; } .sidebar.primary li.current a { border-left: 3px solid #e99d1a; color: white; } .sidebar.secondary li.current a { border-left: 3px solid #2d3e63; color: #33a; } .namespace-index h2 { margin: 30px 0 0 0; } .namespace-index h3 { font-size: 16px; font-weight: bold; margin-bottom: 0; letter-spacing: 0.05em; border-bottom: solid 1px #ddd; max-width: 680px; background-color: #fafafa; padding: 0.5em; } .namespace-index .topics { padding-left: 30px; margin: 11px 0 0 0; } .namespace-index .topics li { padding: 5px 0; } .namespace-docs h3 { font-size: 18px; font-weight: bold; } .public h3 { margin: 0; float: left; } .usage { clear: both; } .public { margin: 0; border-top: 1px solid #e0e0e0; padding-top: 14px; padding-bottom: 6px; } .public:last-child { margin-bottom: 20%; } .members .public:last-child { margin-bottom: 0; } .members { margin: 15px 0; } .members h4 { color: #555; font-weight: normal; font-variant: small-caps; margin: 0 0 5px 0; } .members .inner { padding-top: 5px; padding-left: 12px; margin-top: 2px; margin-left: 7px; border-left: 1px solid #bbb; } #content .members .inner h3 { font-size: 12pt; } .members .public { border-top: none; margin-top: 0; padding-top: 6px; padding-bottom: 0; } .members .public:first-child { padding-top: 0; } h4.type, h4.dynamic, h4.added, h4.deprecated { float: left; margin: 3px 10px 15px 0; font-size: 15px; font-weight: bold; font-variant: small-caps; } .public h4.type, .public h4.dynamic, .public h4.added, .public h4.deprecated { font-size: 13px; font-weight: bold; margin: 3px 0 0 10px; } .members h4.type, .members h4.added, .members h4.deprecated { margin-top: 1px; } h4.type { color: #717171; } h4.dynamic { color: #9933aa; } h4.added { color: #508820; } h4.deprecated { color: #880000; } .namespace { margin-bottom: 30px; } .namespace:last-child { margin-bottom: 10%; } .index { padding: 0; font-size: 80%; margin: 15px 0; line-height: 1.6em; } .index * { display: inline; } .index p { padding-right: 3px; } .index li { padding-right: 5px; } .index ul { padding-left: 0; } .type-sig { clear: both; color: #088; } .type-sig pre { padding-top: 10px; margin: 0; } .usage code { display: block; color: #008; margin: 2px 0; } .usage code:first-child { padding-top: 10px; } p { margin: 15px 0; } .public p:first-child, .public pre.plaintext { margin-top: 12px; } .doc { margin: 0 0 26px 0; clear: both; } .public .doc { margin: 0; } .namespace-index { font-size: 120%; } .namespace-index .doc { margin-bottom: 20px; } .namespace-index .namespace .doc { margin-bottom: 10px; } .markdown p, .markdown li, .markdown dt, .markdown dd, .markdown td { line-height: 1.6em; } .markdown h2 { font-weight: normal; font-size: 25px; } #content .markdown h3 { font-size: 20px; } .markdown h4 { font-size: 15px; } .doc, .public, .namespace .index { max-width: 680px; overflow-x: visible; } .markdown pre > code { display: block; padding: 10px; } .markdown pre > code, .src-link a { border: 1px solid #e4e4e4; border-radius: 2px; } .src-link a { background: #f6f6f6; } .markdown code:not(.hljs) { color: #c7254e; background-color: #f9f2f4; border-radius: 4px; font-size: 90%; padding: 2px 4px; } pre.deps { display: inline-block; margin: 0 10px; border: 1px solid #e4e4e4; border-radius: 2px; padding: 10px; background-color: #f6f6f6; } .markdown hr { border-style: solid; border-top: none; color: #ccc; } .doc ul, .doc ol { padding-left: 30px; } .doc table { border-collapse: collapse; margin: 0 10px; } .doc table td, .doc table th { border: 1px solid #dddddd; padding: 4px 6px; } .doc table th { background: #f2f2f2; } .doc dl { margin: 0 10px 20px 10px; } .doc dl dt { font-weight: bold; margin: 0; padding: 3px 0; border-bottom: 1px solid #ddd; } .doc dl dd { padding: 5px 0; margin: 0 0 5px 10px; } .doc abbr { border-bottom: 1px dotted #333; font-variant: none; cursor: help; } .src-link { margin-bottom: 15px; } .src-link a { font-size: 70%; padding: 1px 4px; text-decoration: none; color: #5555bb; background-color: #f6f6f6; } blockquote { opacity: 0.6; border-left: solid 2px #ddd; margin-left: 0; padding-left: 1em; } /* Responsiveness Theme */ @media (max-device-width: 480px) { .sidebar { display:none; } #content { position: relative; left: initial !important; top: 110px; padding: 0 1em; } #header { display: flex; flex-direction: column-reverse; height: 100px; } #header > h1 { font-size: 52px; } #header h2 { float: none; font-size: 20px; } .namespace-index > h1 { display: none; } .public, .doc, .namespace > .index, .namespace > .doc, .namespace > h3 { max-width: initial; } .doc { text-align: justify; } .public { padding-top: 2em; padding-bottom: 2em; } .public > h3 { font-size: 300%; } .public > h4.type, .public > h4.added, .public > h4.deprecated { font-size: 150%; margin-top: 1em; } pre > code { font-size: 200%; } } ================================================ FILE: docs/embedded.html ================================================ Embedding Clojure In Python

Project

Topics

Namespaces

Embedding Clojure In Python

The initial development push for libpython-clj was simply to embed Python in Clojure allowing Clojure developers to use Python modules simply transparently. This approach relied on libpython-clj being able to find the Python shared library and having some capability to setup various Python system variables before loading any modules. While this works great most of the time there are several reasons for which this approach is less than ideal:

  1. In some cases a mainly Python team wants to use some Clojure for a small part of their work. Telling them to host Python from Clojure is for them a potentially very disruptive change.
  2. The python ecosystem is moving away from the shared library and towards compiling a statically linked executable. This can never work with libpython-clj's default pathway.
  3. Embedded Python cannot use all of Python functionality available due to the fact that the host process isn't python. Specifically the multithreading module relies on forking the host process and thus produces a hang if the JVM is the main underlying process.
  4. Replicating the exact python environment is error prone especially when Python environment managers such as pyenv and Conda are taken into account.

Due to the above reasons there is a solid argument for, if possible, embedding Clojure into Python allowing the Python executable to be the host process.

Enter: cljbridge

Python already had a nascent system for embedding Java in Python - the javabridge module.

We went a step further and provide cljbridge python module.

In order to compile javabridge a JDK is required and not just the JRE. tristanstraub had found a way to use this in order to work with Blender. We took a bit more time and worked out ways to smooth out these interactions and make sure they were supported throughout the system.

From the Python REPL

The next step involves starting a python repl.

This requires a python library cljbridge, which can be installed via

export JAVA_HOME=<--YOUR JAVA HOME-->
python3 -m pip install cljbridge

This will install and eventually compile javabridge as well.

If the installation cannot find 'jni.h' then most likely you have the Java runtime (JRE) installed as opposed to the Java development kit (JDK).

So we start by importing that script:

Python 3.8.5 (default, Jan 27 2021, 15:41:15)
[GCC 9.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from clojurebridge import cljbridge
>>> test_var=10
>>> cljbridge.init_jvm(start_repl=True)
Mar 11, 2021 9:08:47 AM clojure.tools.logging$eval3186$fn__3189 invoke
INFO: nREPL server started on port 40241 on host localhost - nrepl://localhost:40241

At this point we do not get control back; we have released the GIL and java is blocking this thread to allow the Clojure REPL systems access to the GIL. We have two important libraries for clojure loaded, nrepl and cider which allow a rich, interactive development experience so let's now connect to that port with our favorite Clojure editor - emacs of course ;-).

Passing JVM arguments

If you want to specify arbitrary arguments for the JVM to be started by Python, you can use the environment variable JDK_JAVA_OPTIONS to do so. It will be picked up by the JVM when starting.

Since clojurebridge 0.0.8, you can as well specify a list of aliases, which get resolved from the deps.edn file. This allows as well to specify JVM arguments and JVM properties.

Example:

Starting Clojure embedded from python via

cljbridge.init_jvm(aliases=["jdk-17","fastcall"],start_repl=True)

and a deps.edn with

:aliases {

           :fastcall
           {:jvm-opts ["-Dlibpython_clj.manual_gil=true"]}
           :jdk-17
           {:jvm-opts ["--add-modules=jdk.incubator.foreign"
                       "--enable-native-access=ALL-UNNAMED"]}}

would add then the appropriate JVM options.

From the Clojure REPL

From emacs, I run the command 'cider-connect' which allows me to specify a host and port to connect to. Once connected, I get a minimal repl environment:

;; M-x cider-connect ...localhost...40241
;; I am not sure why but to initialize the user namespace I have to eval ns user

user> (eval '(ns user))
nil
user> (require '[libpython-clj2.python :as py])
nil
;; Python has been initialized and libpython-clj can detect this
user> (py/initialize!)
:already-initialized
user> ;;We can share data via the main module
user> (def main-mod (py/add-module "__main__"))
#'user/main-mod
user> (def mod-dict (py/module-dict main-mod))
#'user/mod-dict
user> (keys mod-dict)
("__name__"
 "__doc__"
 "__package__"
 "__loader__"
 "__spec__"
 "__annotations__"
 "__builtins__"
 "cljbridge"
 "test_var")
user> (get mod-dict "test_var")
10
user> (.put mod-dict "clj_fn" (fn [& args] (println "Printing from Clojure: " (vec args))))
nil
user> ;;Now if we stop the repl server we can access our python environment again
user> (require '[libpython-clj2.embedded :as embedded])
nil
user> (embedded/stop-repl!)

And Back to Python!!

Shutting down the repl always gives us an exception; something perhaps to work on. But the important thing is that we can access variables and data that we set in the main module -

>>> Exception in thread "nREPL-session-d684061e-f21c-4265-a9a2-828b99dcaf42" java.net.SocketException: Socket closed
	at java.net.SocketOutputStream.socketWrite(SocketOutputStream.java:118)
	at java.net.SocketOutputStream.write(SocketOutputStream.java:155)
	at java.io.BufferedOutputStream.flushBuffer(BufferedOutputStream.java:82)
	at java.io.BufferedOutputStream.flush(BufferedOutputStream.java:140)
	at nrepl.transport$bencode$fn__7714.invoke(transport.clj:121)
	at nrepl.transport.FnTransport.send(transport.clj:28)
	at nrepl.middleware.print$send_streamed.invokeStatic(print.clj:136)
	at nrepl.middleware.print$send_streamed.invoke(print.clj:122)
	at nrepl.middleware.print$printing_transport$reify__8149.send(print.clj:173)
	at cider.nrepl.middleware.track_state$make_transport$reify__17923.send(track_state.clj:228)
	at nrepl.middleware.caught$caught_transport$reify__8184.send(caught.clj:58)
	at nrepl.middleware.interruptible_eval$evaluate$fn__8250.invoke(interruptible_eval.clj:132)
	at clojure.main$repl$fn__9121.invoke(main.clj:460)
	at clojure.main$repl.invokeStatic(main.clj:458)
	at clojure.main$repl.doInvoke(main.clj:368)
	at clojure.lang.RestFn.invoke(RestFn.java:1523)
	at nrepl.middleware.interruptible_eval$evaluate.invokeStatic(interruptible_eval.clj:84)
	at nrepl.middleware.interruptible_eval$evaluate.invoke(interruptible_eval.clj:56)
	at nrepl.middleware.interruptible_eval$interruptible_eval$fn__8258$fn__8262.invoke(interruptible_eval.clj:152)
	at clojure.lang.AFn.run(AFn.java:22)
	at nrepl.middleware.session$session_exec$main_loop__8326$fn__8330.invoke(session.clj:202)
	at nrepl.middleware.session$session_exec$main_loop__8326.invoke(session.clj:201)
	at clojure.lang.AFn.run(AFn.java:22)
	at java.lang.Thread.run(Thread.java:748)

>>> # So let's call our new clojure fn
>>> clj_fn(1, 2, 3, 4, "Embedded Clojure FTW!!")
Printing from Clojure:  [1 2 3 4 Embedded Clojure FTW!!]
>>>

Loading and running a Clojure file in embedded mode

We can runs as well a .clj file in embedded mode. The following does this without an interactive pytho shell, it just runs the provided clj file with clojure.core/load-file

python3 -c 'import cljbridge;cljbridge.load_clojure_file(clj_file="my-file.clj")'

Are You Not Entertained???

So there you have it, embedding a Clojure repl in a Python process and passing data in between these two systems. This sidesteps a ton of issues with embedding Python and provides another interesting set of possibilities, essentially extending existing Python systems with some of the greatest tech the JVM has to offer :-).

================================================ FILE: docs/environments.html ================================================ Python Environments

Project

Topics

Namespaces

Python Environments

pyenv

pyenv requires that you build the shared library. This is a separate configuration option than a lot of pyenv users have used before.

Conda

Conda requires that we set the LD_LIBRARY_PATH to the conda install.

================================================ FILE: docs/highlight/solarized-light.css ================================================ /* Orginal Style from ethanschoonover.com/solarized (c) Jeremy Hull */ .hljs { display: block; overflow-x: auto; padding: 0.5em; background: #fdf6e3; color: #657b83; } .hljs-comment, .hljs-quote { color: #93a1a1; } /* Solarized Green */ .hljs-keyword, .hljs-selector-tag, .hljs-addition { color: #859900; } /* Solarized Cyan */ .hljs-number, .hljs-string, .hljs-meta .hljs-meta-string, .hljs-literal, .hljs-doctag, .hljs-regexp { color: #2aa198; } /* Solarized Blue */ .hljs-title, .hljs-section, .hljs-name, .hljs-selector-id, .hljs-selector-class { color: #268bd2; } /* Solarized Yellow */ .hljs-attribute, .hljs-attr, .hljs-variable, .hljs-template-variable, .hljs-class .hljs-title, .hljs-type { color: #b58900; } /* Solarized Orange */ .hljs-symbol, .hljs-bullet, .hljs-subst, .hljs-meta, .hljs-meta .hljs-keyword, .hljs-selector-attr, .hljs-selector-pseudo, .hljs-link { color: #cb4b16; } /* Solarized Red */ .hljs-built_in, .hljs-deletion { color: #dc322f; } .hljs-formula { background: #eee8d5; } .hljs-emphasis { font-style: italic; } .hljs-strong { font-weight: bold; } ================================================ FILE: docs/index.html ================================================ libpython-clj 2.026

Project

Topics

Namespaces

libpython-clj 2.026

Python bindings for Clojure.

Topics

Namespaces

libpython-clj2.codegen

Generate a namespace on disk for a python module or instances

Public variables and functions:

libpython-clj2.embedded

Tools for embedding clojure into a python host process. See jbridge.py for python details. This namespace relies on the classpath having nrepl and cider-nrepl on it. For example:

Public variables and functions:

libpython-clj2.java-api

A java api is exposed for libpython-clj2. The methods below are statically callable without the leading '-'. Note that returned python objects implement the respective java interfaces so a python dict will implement java.util.Map, etc. There is some startup time as Clojure dynamically compiles the source code but this binding should have great runtime characteristics in comparison to any other java python engine.

Public variables and functions:

libpython-clj2.python

Python bindings for Clojure. This library dynamically finds the installed python, loads the shared library and allows Clojure users to use Python modules as if they were Clojure namespaces.

Public variables and functions:

libpython-clj2.python.class

Namespace to help create a new python class from Clojure. Used as a core implementation technique for bridging JVM objects into python.

Public variables and functions:

libpython-clj2.python.np-array

Bindings for deeper intergration of numpy into the tech.v3.datatype system. This allows seamless usage of numpy arrays in datatype and tensor functionality such as enabling the tech.v3.tensor/ensure-tensor call to work with numpy arrays -- using zero copying when possible.

Public variables and functions:

libpython-clj2.require

Namespace implementing requiring python modules as Clojure namespaces. This works via scanning the module for metadata and dynamically building the Clojure namespace.

Public variables and functions:

================================================ FILE: docs/js/page_effects.js ================================================ function visibleInParent(element) { var position = $(element).position().top return position > -50 && position < ($(element).offsetParent().height() - 50) } function hasFragment(link, fragment) { return $(link).attr("href").indexOf("#" + fragment) != -1 } function findLinkByFragment(elements, fragment) { return $(elements).filter(function(i, e) { return hasFragment(e, fragment)}).first() } function scrollToCurrentVarLink(elements) { var elements = $(elements); var parent = elements.offsetParent(); if (elements.length == 0) return; var top = elements.first().position().top; var bottom = elements.last().position().top + elements.last().height(); if (top >= 0 && bottom <= parent.height()) return; if (top < 0) { parent.scrollTop(parent.scrollTop() + top); } else if (bottom > parent.height()) { parent.scrollTop(parent.scrollTop() + bottom - parent.height()); } } function setCurrentVarLink() { $('.secondary a').parent().removeClass('current') $('.anchor'). filter(function(index) { return visibleInParent(this) }). each(function(index, element) { findLinkByFragment(".secondary a", element.id). parent(). addClass('current') }); scrollToCurrentVarLink('.secondary .current'); } var hasStorage = (function() { try { return localStorage.getItem } catch(e) {} }()) function scrollPositionId(element) { var directory = window.location.href.replace(/[^\/]+\.html$/, '') return 'scroll::' + $(element).attr('id') + '::' + directory } function storeScrollPosition(element) { if (!hasStorage) return; localStorage.setItem(scrollPositionId(element) + "::x", $(element).scrollLeft()) localStorage.setItem(scrollPositionId(element) + "::y", $(element).scrollTop()) } function recallScrollPosition(element) { if (!hasStorage) return; $(element).scrollLeft(localStorage.getItem(scrollPositionId(element) + "::x")) $(element).scrollTop(localStorage.getItem(scrollPositionId(element) + "::y")) } function persistScrollPosition(element) { recallScrollPosition(element) $(element).scroll(function() { storeScrollPosition(element) }) } function sidebarContentWidth(element) { var widths = $(element).find('.inner').map(function() { return $(this).innerWidth() }) return Math.max.apply(Math, widths) } function calculateSize(width, snap, margin, minimum) { if (width == 0) { return 0 } else { return Math.max(minimum, (Math.ceil(width / snap) * snap) + (margin * 2)) } } function resizeSidebars() { var primaryWidth = sidebarContentWidth('.primary') var secondaryWidth = 0 if ($('.secondary').length != 0) { secondaryWidth = sidebarContentWidth('.secondary') } // snap to grid primaryWidth = calculateSize(primaryWidth, 32, 13, 160) secondaryWidth = calculateSize(secondaryWidth, 32, 13, 160) $('.primary').css('width', primaryWidth) $('.secondary').css('width', secondaryWidth).css('left', primaryWidth + 1) if (secondaryWidth > 0) { $('#content').css('left', primaryWidth + secondaryWidth + 2) } else { $('#content').css('left', primaryWidth + 1) } } $(window).ready(resizeSidebars) $(window).ready(setCurrentVarLink) $(window).ready(function() { persistScrollPosition('.primary')}) $(window).ready(function() { $('#content').scroll(setCurrentVarLink) $(window).resize(setCurrentVarLink) $(window).resize(resizeSidebars) }) ================================================ FILE: docs/libpython-clj.python.html ================================================ libpython-clj.python documentation

Project

Topics

Namespaces

Public Vars

libpython-clj.python

Base low-level namespace for accessing Python via Clojure. Higher level interfaces are found in libpython-clj.require specifically require-python and import-python.

$.

macro

($. item attname)

Get the attribute of an object.

view source

$..

macro

($.. item attname & args)

Get the attribute of an object. If there are extra args, apply successive get-attribute calls to the arguments.

view source

$a

macro

($a item attr & args)

Call an attribute of an object. Similar calling conventions to afn except: Keywords must be compile time constants. So this won’t work with ‘apply’. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime. The attr name can be a symbol.

view source

$c

macro

($c item & args)

Call an object. Similar calling conventions to cfn except: Keywords must be compile time constants. So this won’t work with ‘apply’. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime.

view source

->jvm

(->jvm item & [options])

Copy an object into the jvm (if it wasn’t there already.)

view source

->numpy

(->numpy item & [options])

Convert an object to numpy throwing an error if this isn’t possible.

view source

->py-dict

(->py-dict item)

Create a python dictionary

view source

->py-float

(->py-float item)

Convert an object into a python float

view source

->py-fn

(->py-fn item)

Make a python function. If clojure function is passed in the arguments are marshalled from python to clojure, the function called, and the return value will be marshalled back.

view source

->py-list

(->py-list item)

Create a python list

view source

->py-long

(->py-long item)

Convert an object into a python long

view source

->py-string

(->py-string item)

Copy an object into a python string

view source

->py-tuple

(->py-tuple item)

Create a python tuple

view source

->python

(->python item & [options])

Completely convert a jvm object to a python copy.

view source

->python-incref

(->python-incref item)

Convert to python and add a reference. This is necessary for return values from functions as the ->python pathway adds a reference but it also tracks it and releases it when it is not in use any more. Thus python ends up holding onto something with fewer refcounts than it should have. If you are just messing around in the repl you only need ->python. There is an expectation that the return value of a function call is a new reference and not a borrowed reference hence this pathway.

view source

a$

macro

(a$ item attr & args)

Call an attribute of an object. Similar calling conventions to afn except: Keywords must be compile time constants. So this won’t work with ‘apply’. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime. The attr name can be a symbol.

DEPRECATION POSSIBLE - use $a.

view source

add-module

(add-module modname)

Add a python module. Returns a bridge

view source

afn

(afn item attr & args)

Call an attribute of an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs.

Not having an argument after a keyword argument is an error.

view source

args->pos-kw-args

(args->pos-kw-args arglist)

Utility function that, given a list of arguments, separates them into positional and keyword arguments. Throws an exception if the keyword argument is not followed by any more arguments.

view source

as-jvm

(as-jvm item & [options])

Bridge a python object into the jvm. Attempts to build a jvm bridge that ‘hides’ the python type. This bridge is lazy and noncaching so use it wisely; it may be better to just copy the type once into the JVM. Bridging is recursive so any subtypes are also bridged if possible or represented by a hashmap of {:type :value} if not.

view source

as-list

(as-list item)

Return a List implementation using getitem, setitem.

view source

as-map

(as-map item)

Return a Map implementation using getitem, setitem. Note that it may be incomplete especially if the object has no ‘keys’ attribute.

view source

as-numpy

(as-numpy item & [options])

Bridge an object into numpy sharing the backing store. If it is not possible to do this without copying data then return nil.

view source

as-python

(as-python item & [options])

Bridge a jvm object into python

view source

as-python-incref

(as-python-incref item)

Convert to python and add a reference. Necessary for return values from functions as python expects a new reference and the as-python pathway ensures the jvm garbage collector also sees the reference.

view source

att-type-map

(att-type-map item)

Get hashmap of att name to keyword datatype.

view source

c$

macro

(c$ item & args)

Call an object. Similar calling conventions to cfn except: Keywords must be compile time constants. So this won’t work with ‘apply’. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime.

DEPRECATION POSSIBLE - use $c.

view source

call

(call callable & args)

Call a python function with positional args. For keyword args, see call-kw.

view source

call-attr

(call-attr item att-name & args)

Call an object attribute with positional arguments.

view source

call-attr-kw

(call-attr-kw item att-name arglist kw-map)

Call an object attribute with a vector of positional args and a map of keyword args.

view source

call-kw

(call-kw callable arglist kw-args)

Call a python function with a vector of positional args and a map of keyword args.

view source

callable?

(callable? item)

Return true if object is a python callable object.

view source

cfn

(cfn item & args)

Call an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs.

Not having an argument after a keyword argument is an error.

view source

create-bridge-from-att-map

(create-bridge-from-att-map src-item att-map)
view source

create-class

(create-class name bases cls-hashmap)

Create a new class object. Any callable values in the cls-hashmap will be presented as instance methods. Things in the cls hashmap had better be either atoms or already converted python objects. You may get surprised otherwise; you have been warned. See the classes-test file in test/libpython-clj

view source

dir

(dir item)

Get sorted list of all attribute names.

view source

equals?

(equals? lhs rhs)

Returns true of the python equals operator returns 1.

view source

finalize!

(finalize!)

Finalize the interpreter. You probably shouldn’t call this as it destroys the global interpreter and reinitialization is unsupported cpython.

view source

from-import

macro

(from-import module-path item & args)

Support for the from a import b,c style of importing modules and symbols in python. Documentation is included.

view source

gc!

(gc!)

Run the system garbage collection facility and then call the cooperative ‘cleanup python objects’ queue

view source

get-attr

(get-attr item item-name)

Get attribute from object

view source

get-item

(get-item item item-name)

Get an item of a given name from an object

view source

has-attr?

(has-attr? item item-name)

Return true of object has attribute

view source

has-item?

(has-item? item item-name)

Return true of object has item

view source

hash-code

(hash-code py-inst)
view source

import-as

macro

(import-as module-path varname)

Import a module and assign it to a var. Documentation is included.

view source

import-module

(import-module modname)

Import a python module. Returns a bridge

view source

initialize!

(initialize! & {:keys [program-name library-path python-home no-io-redirect? python-executable windows-anaconda-activate-bat]})

Initialize the python library. If library path is provided, then the python :library-path Library path of the python library to use. :program-name - optional but will show up in error messages from python. :no-io-redirect - there if you don’t want python stdout and stderr redirection to out and err.

view source

is-instance?

(is-instance? py-inst py-type)

Returns true if inst is an instance of type. False otherwise.

view source

len

(len item)

Call the len attribute.

view source

libpython-clj-module-name

Module name of the libpython-clj python model. Used to find binding-level objects such as the type used for actual jvm bridging objects.

view source

make-tuple-fn

(make-tuple-fn fn-obj & {:keys [arg-converter result-converter], :or {arg-converter ->jvm, result-converter ->python-incref}, :as options})

Given a clojure function, create a python tuple function. arg-convert is applied to arguments before the clojure function gets them and result-converter is applied to the outbound result. Exceptions are caught, logged, and propagated to python.

arg-converter: A function to be called on arguments before they get to clojure. Defaults to ->jvm. result-converter: A function to be called on the return value before it makes it back to python. Defaults to ->python-incref. method-name: Name of function exposed to python. documentation: Documentation of function exposed to python.

view source

make-tuple-instance-fn

(make-tuple-instance-fn clj-fn & {:keys [arg-converter], :as options})

Make an instance function. In this case the default behavior is to pass raw python object ptr args to the clojure function without marshalling as that can add confusion and unnecessary overhead. Self will be the first argument. Callers can change this behavior by setting the ‘arg-converter’ option as in ‘make-tuple-fn’. Options are the same as make-tuple-fn.

view source

module-dict

(module-dict module)

Get the module dictionary. Returns bridge.

view source

ptr-refcnt

(ptr-refcnt item)
view source

py*

macro

(py* x method args)(py* x method args kwargs)

Special syntax for passing along *args and **kwargs style arguments to methods.

Usage:

(py* obj method args kwargs)

Example:

(def d (python/dict)) d ;;=> {} (def iterable :a 1] [:b 2) (def kwargs {:cat “dog” :name “taco”}) (py* d update [iterable] kwargs) d ;;=> {“a”: 1, “b”: 2, “cat”: “dog”, “name”: “taco”}

view source

py**

macro

(py** x method kwargs)(py** x method arg & args)

Like py*, but it is assumed that the LAST argument is kwargs.

view source

py.

macro

(py. x & args)

Class/object method syntax. (py. obj method arg1 arg2 … argN) is equivalent to Python’s obj.method(arg1, arg2, …, argN) syntax.

view source

py.-

macro

(py.- x arg)

Class/object getter syntax. (py.- obj attr) is equivalent to Python’s obj.attr syntax.

view source

py..

macro

(py.. x & args)

Extended accessor notation, similar to the .. macro in Clojure.

(require-python ’sys) (py.. sys -path (append “/home/user/bin”))

is equivalent to Python’s

import sys sys.path.append(‘/home/user/bin’)

SPECIAL SYNTAX for programmatic *args and **kwargs

Special syntax is provided to meet the needs required by Python’s *args and **kwargs syntax programmatically.

(= (py.. obj (*method args)) (py* obj methods args))

(= (py.. obj (*methods args kwargs)) (py* obj method args kwargs))

(= (py.. obj (**method kwargs)) (py** obj kwargs))

(= (py.. obj (**method arg1 arg2 arg3 … argN kwargs)) (py** obj method arg1 arg2 arg3 … argN kwargs) (py* obj method [arg1 arg2 arg3 … argN] kwargs))

These forms exist for when you need to pass in a map of options in the same way you would use the f(*args, **kwargs) forms in Python.

view source

python-pyerr-fetch-error-handler

(python-pyerr-fetch-error-handler)

Utility code used in with macro

view source

python-type

(python-type item)

Return a keyword that describes the python datatype of this object.

view source

run-simple-string

(run-simple-string program & {:keys [globals locals]})

Run a string expression returning a map of {:globals :locals}. This uses the global main dict under the covers so it matches the behavior of the cpython implementation with the exception of returning the various maps used.

Note this will never return the result of the expression: https://mail.python.org/pipermail/python-list/1999-April/018011.html

Globals, locals may be provided but are not necessary.

Implemented in cpython as:

PyObject *m, *d, *v; m = PyImport_AddModule(“main”); if (m == NULL) return -1; d = PyModule_GetDict(m); v = PyRun_StringFlags(command, Py_file_input, d, d, flags); if (v == NULL) { PyErr_Print(); return -1; } Py_DECREF(v); return 0;

view source

run-string

(run-string program & {:keys [globals locals]})

Wrapper around the python c runtime PyRun_String method. This requires you to understand what needs to be in the globals and locals dict in order for everything to work out right and for this reason we recommend run-simple-string.

view source

set-attr!

(set-attr! item item-name item-value)

Set attribute on object

view source

set-attrs!

(set-attrs! item att-seq)

Set a sequence of [name value] attributes. Returns item

view source

set-item!

(set-item! item item-name item-value)

Set an item of to a value

view source

set-items!

(set-items! item item-seq)

Set a sequence of [name value]. Returns item

view source

stack-resource-context

macro

(stack-resource-context & body)

Create a stack-based resource context. All python objects allocated within this context will be released at the termination of this context. !!This means that no python objects can escape from this context!! You must use copy semantics (->jvm) for anything escaping this context. Furthermore, if you are returning generic python objects you may need to call (into {}) or something like that just to ensure that absolutely everything is copied into the jvm.

view source

with

macro

(with bind-vec & body)

Support for the ‘with’ statement in python: (py/with [item (py/call-attr testcode-module “WithObjClass” true fn-list)] (py/call-attr item “doit_err”))

view source

with-exit-error-handler

(with-exit-error-handler with-var error)

Utility code used in with macro

view source

with-gil

macro

(with-gil & body)

Capture the gil for an extended amount of time. This can greatly speed up operations as the mutex is captured and held once as opposed to find grained grabbing/releasing of the mutex.

view source

with-gil-stack-rc-context

macro

(with-gil-stack-rc-context & body)

Capture the gil, open a resource context. The resource context is released before the gil is leading to much faster resource collection. See documentation on stack-resource-context for multiple warnings; the most important one being that if a python object escapes this context your program will eventually, at some undefined point in the future crash. That being said, this is the recommended pathway to use in production contexts where you want defined behavior and timings related to use of python.

view source
================================================ FILE: docs/libpython-clj.python.np-array.html ================================================ libpython-clj.python.np-array documentation

Project

Topics

Namespaces

Public Vars

libpython-clj.python.np-array

Bindings for deeper intergration of numpy into the tech.v3.datatype system. This allows somewhat more seamless usage of numpy arrays in datatype and tensor functionality such as enabling the tech.v3.tensor/ensure-tensor call to work with numpy arrays (as zero copying when possible).

np-mod*

Delay that dereferences to the python numpy module

view source
================================================ FILE: docs/libpython-clj.require.html ================================================ libpython-clj.require documentation

Project

Topics

Namespaces

Public Vars

libpython-clj.require

Namespace implementing requiring python modules as Clojure namespaces. This works via scanning the module for metadata and dynamically building the Clojure namespace.

import-python

(import-python)

Loads python, python.list, python.dict, python.set, python.tuple, and python.frozenset.

view source

require-python

(require-python req)(require-python req & reqs)

Basic usage

(require-python ’math) (math/sin 1.0) ;;=> 0.8414709848078965

(require-python ’[math :as maaaath])

(maaaath/sin 1.0) ;;=> 0.8414709848078965

(require-python ‘math ‘csv) (require-python ’[math :as pymath] ‘csv)) (require-python ’[math :as pymath] ’[csv :as py-csv]) (require-python ‘concurrent.futures) (require-python ’[concurrent.futures :as fs]) (require-python ’(concurrent [futures :as fs]))

(require-python ’[requests :refer [get post]])

(requests/get “https//www.google.com”) ;;=> <Response [200]> (get “https//www.google.com”) ;;=> <Response [200]>

In some cases we may generate invalid arglists metadata for the clojure compiler. In those cases we have a flag, :no-arglists that will disable adding arglists to the generated metadata for the vars. Use the reload flag below if you need to force reload a namespace where invalid arglists have been generated.

(require-python ’[numpy :refer [linspace] :no-arglists :as np])

If you would like to bind the Python module to the namespace, use the :bind-ns flag.

(require-python ‘[requests :bind-ns true]) or (require-python ’[requests :bind-ns])

Use with custom modules

For use with a custom namespace foo.py while developing, you can use:

(require-python ’[foo :reload])

NOTE: unless you specify the :reload flag, ..: the module will NOT reload. If the :reload flag is set, ..: the behavior mimics importlib.reload

Setting up classpath for custom modules

Note: you may need to setup your PYTHONPATH correctly. One technique to do this is, if your foo.py lives at /path/to/foodir/foo.py:

(require-python ’sys) (py/call-attr (py/get-attr sys “path”) “append” “/path/to/foodir”)

Another option is

(require-python ’os) (os/chdir “/path/to/foodir”)

prefix lists

For convenience, if you are loading multiple Python modules with the same prefix, you can use the following notation:

(require-python ’(a b c)) is equivalent to (require-python ’a.b ’a.c)

(require-python ‘(foo [bar :as baz :refer [qux]])) is equivalent to (require-python ’[foo.bar :as baz :refer [qux]])

(require-python ‘(foo [bar :as baz :refer [qux]] buster)) (require-python ’[foo.bar :as baz :refer [qux]] ’foo.buster))

For library developers

If you want to intern all symbols to your current namespace, you can do the following –

(require-python ’[math :refer :all])

However, if you only want to use those things designated by the module under the all attribute, you can do

(require-python ’[operators :refer :*])

view source
================================================ FILE: docs/libpython-clj2.codegen.html ================================================ libpython-clj2.codegen documentation

Project

Topics

Namespaces

Public Vars

libpython-clj2.codegen

Generate a namespace on disk for a python module or instances

write-namespace!

(write-namespace! py-mod-or-cls {:keys [output-fname output-dir ns-symbol ns-prefix symbol-name-remaps exclude], :or {output-dir "src", ns-prefix "python", exclude default-exclude}})(write-namespace! py-mod-or-cls)

Generate a clojure namespace file from a python module or class. If python hasn't been initialized yet this will call the default python initialization. Accessing the generated namespace without initialization will cause an error.

Once generated this namespace is safe to be used for AOT,

Options:

  • :output-fname - override the autogenerated file path.
  • :output-dir - Defaults "src". Set the output directory. The final filename, if :output-fname is not provided, is built up from :ns-prefix andpy-mod-or-cls`.
  • :ns-symbol - The fully qualified namespace symbol. If not provided is built from :ns-prefix and py-mod-or-cls.
  • :ns-prefix - The prefix used for all python namespaces. Defaults to "python".
  • :symbol-name-remaps - A list of remaps used to avoid name clashes with clojure.core or builtin java symbols.
  • :exclude - List of symbols used like (:refer-clojure :exclude %s). You can see the default list as codegen/default-exclude.

Example:

user> (require '[libpython-clj2.codegen :as codegen])
nil
user> (codegen/write-namespace!
       "builtins" {:symbol-name-remaps {"AssertionError" "PyAssertionError"
                                          "Exception" "PyException"}})
:ok
user> (require '[python.builtins :as python])
nil
user> (doc python/list)
-------------------------
python.builtins/list
[[self & [args {:as kwargs}]]]
  Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list.
The argument must be an iterable if specified.
nil
user> (doto (python/list)
        (.add 1)
        (.add 2))
[1, 2]
view source
================================================ FILE: docs/libpython-clj2.embedded.html ================================================ libpython-clj2.embedded documentation

Project

Topics

Namespaces

Public Vars

libpython-clj2.embedded

Tools for embedding clojure into a python host process. See jbridge.py for python details. This namespace relies on the classpath having nrepl and cider-nrepl on it. For example:

clojure -SPath '{:deps {nrepl/nrepl {:mvn/version "0.8.3"} cider/cider-nrepl {:mvn/version "0.25.5"}}}' ...

initialize!

(initialize!)(initialize! libpath)

Initialize python when this library is being called from a python program. In that case, unless libpath is explicitly provided the system will look for the python symbols in the current executable.

view source

start-repl!

(start-repl! options)(start-repl!)

This is called to start a clojure repl and block the thread. This function does not return control to the calling thread until another thread calls `stop-repl!; this design is explicit to ensure the python GIL is released and thus when connected to the REPL you can use Python.

If an existing repl server has been started this returns the port of the previous server else it returns the port of the new server.

To return control to the calling thread call stop-repl!.

Options are the same as the command line options found in nrepl.cmdline.

view source

stop-repl!

(stop-repl!)

If an existing repl has been started, stop it. This returns control to the thread that called start-repl!.

view source
================================================ FILE: docs/libpython-clj2.java-api.html ================================================ libpython-clj2.java-api documentation

Project

Topics

Namespaces

Public Vars

libpython-clj2.java-api

A java api is exposed for libpython-clj2. The methods below are statically callable without the leading '-'. Note that returned python objects implement the respective java interfaces so a python dict will implement java.util.Map, etc. There is some startup time as Clojure dynamically compiles the source code but this binding should have great runtime characteristics in comparison to any other java python engine.

Note that you can pass java objects into python. An implementation of java.util.Map will appear to python as a dict-like object an implementation of java.util.List will look like a sequence and if the thing is iterable then it will be iterable in python. To receive callbacks from python you can provide an implementation of the interface clojure.lang.IFn

Performance:

There are a two logical ways to repeatedly invoke python functionality. The first is to set some globals and repeatedly runStringAsInput a script. The second is 'exec'ing a script, finding an exported function in the global dict and calling that. With libpython-clj, the second pathway -- repeatedly calling a function -- is going to be faster than the first if the user makes a fastcallable out of the function to be invoked. Here are some sample timings for an extremely simple function with two arguments:

Python fn calls/ms 1923.2490094806021
Python fastcallable calls/ms 3776.767751742239
Python eval pathway calls/ms 2646.0478013509883

  • makeFastcallable - - For the use case of repeatedly calling a single function - this will cache the argument tuple for repeated use as opposed to allocating the argument tuple every call. This can be a surprising amount faster -- 2x-3x -- than directly calling the python callable. Once a fastcallable object is made you can either cast it to a clojure.lang.IFn or call it via the provided call static method.

  • HAIR ON FIRE MODE - If you are certain you are correctly calling lockGIL and unlockGIL then you can define a variable, -Dlibpython_clj.manual_gil=true that will disable automatic GIL lock/unlock system and gil correctness checking. This is useful, for instance, if you are going to lock libpython-clj to a thread and control all access to it yourself. This pathway will get at most 10% above using fastcall by itself.

Example:

  java_api.initialize(null);
  try (AutoCloseable locker = java_api.GILLocker()) {
    np = java_api.importModule("numpy");
    Object ones = java_api.getAttr(np, "ones");
    ArrayList dims = new ArrayList();
    dims.add(2);
    dims.add(3);
    Object npArray = java_api.call(ones, dims); //see fastcall notes above
    ...
  }

-arrayToJVM

(-arrayToJVM pyobj)

Copy (efficiently) a numeric numpy array into a jvm map containing keys "datatype", "shape", and a jvm array "data" in flattened row-major form.

view source

-call

(-call item)(-call item arg1)(-call item arg1 arg2)(-call item arg1 arg2 arg3)(-call item arg1 arg2 arg3 arg4)(-call item arg1 arg2 arg3 arg4 arg5)(-call item arg1 arg2 arg3 arg4 arg5 arg6)

Call a clojure IFn object. Python callables implement this interface so this works for python objects. This is a convenience method around casting implementation of clojure.lang.IFn and calling invoke directly.

view source

-callKw

(-callKw pyobj pos-args kw-args)

Call a python callable with keyword arguments. Note that you don't need this pathway to call python methods if you do not need keyword arguments; if the python object is callable then it will implement clojure.lang.IFn and you can use invoke.

view source

-copyData

(-copyData from to)

Copy data from a jvm container into a numpy array or back. This allows you to use a fixed preallocated set of numpy (and potentially jvm arrays) to transfer data back and forth efficiently. The most efficient transfer will be from a java primitive array that matches the numeric type of the numpy array. Also note the element count of the numpy array and the jvm array must match.

Note this copies from the first argument to the second argument -- this is reverse the normal memcpy argument order!!. Returns the destination (to) argument.

Not this does not work with array-of-arrays. It will work with, for instance, a numpy matrix of shape 2, 2 and an double array of length 4.

view source

-copyToJVM

(-copyToJVM object)

Copy a python object such as a dict or a list into a comparable JVM object.

view source

-copyToPy

(-copyToPy object)

Copy a basic jvm object, such as an implementation of java.util.Map or java.util.List to a python object.

view source

-createArray

(-createArray datatype shape data)

Create a numpy array from a tuple of string datatype, shape and data.

  • datatype - One of "int8" "uint8" "int16" "uint16" "int32" "uint32" "int64" "uint64" "float32" "float64".
  • shape - integer array of dimension e.g. [2,3].
  • data - list or array of data. This will of course be fastest if the datatype of the array matches the requested datatype.

This does work with array-of-array structures assuming the shape is correct but those will be slower than a single primitive array and a shape.

view source

-getAttr

(-getAttr pyobj attname)

Get a python attribute. This corresponds to the python '.' operator.

view source

-getGlobal

(-getGlobal varname)

Get a value from the global dict. This function expects the GIL to be locked - it will not lock/unlock it for you.

view source

-getItem

(-getItem pyobj itemName)
view source

-GILLocker

(-GILLocker)

Lock the gil returning an AutoCloseable that will unlock the gil upon close.

Example:

  try (AutoCloseable locker = java_api.GILLocker()) {
    ... Do your python stuff.
  }
view source

-hasAttr

(-hasAttr pyobj attname)

Returns true if this python object has this attribute.

view source

-hasItem

(-hasItem pyobj itemName)

Return true if this pyobj has this item

view source

-importModule

(-importModule modname)

Import a python module. Module entries can be accessed via getAttr.

view source

-initialize

(-initialize options)

See options for libpython-clj2.python/initialize!. Note that the keyword option arguments can be provided by using strings so :library-path becomes the key "library-path". Also note that there is still a GIL underlying all of the further operations so java should access python via single-threaded pathways.

view source

-initializeEmbedded

(-initializeEmbedded)

Initialize python when this library is being called from a python program. In that case the system will look for the python symbols in the current executable. See the embedded topic

view source

-lockGIL

(-lockGIL)

Attempt to lock the gil. This is safe to call in a reentrant manner. Returns a long representing the gil state that must be passed into unlockGIL.

See documentation for pyGILState_Ensure.

Note that the API will do this for you but locking the GIL before doing a string of operations is faster than having each operation lock the GIL individually.

view source

-makeFastcallable

(-makeFastcallable item)

Given a normal python callable, make a fastcallable object that needs to be closed. This should be seen as a callsite optimization for repeatedly calling a specific python function in a tight loop with positional arguments. It is not intended to be used in a context where you will then pass this object around as this is not a reentrant optimization.

  try (AutoCloseable fastcaller = java_api.makeFastcallable(pycallable)) {
     tightloop: {
       java_api.call(fastcaller, arg1, arg2);
     }
  }
view source

-runStringAsFile

(-runStringAsFile strdata)

Run a string returning the result of the last expression. Strings are compiled and live for the life of the interpreter. This is the equivalent to the python exec all.

The global context is returned as a java map.

This function expects the GIL to be locked - it will not lock/unlock it for you.

Example:

   Map globals = java_api.runStringAsFile("def calcSpread(bid,ask):
	return bid-ask

");
   Object spreadFn = globals.get("calcSpread");
   java_api.call(spreadFn, 1, 2); // Returns -1
view source

-runStringAsInput

(-runStringAsInput strdata)

Run a string returning the result of the last expression. Strings are compiled and live for the life of the interpreter. This is the equivalent to the python eval call.

This function expects the GIL to be locked - it will not lock/unlock it for you.

Example:

  java_api.setGlobal("bid", 1);
  java_api.setGlobal("ask", 2);
  java_api.runStringAsInput("bid-ask"); //Returns -1
view source

-setAttr

(-setAttr pyobj attname objval)

Set an attribute on a python object. This corresponds to the __setattr python call.

view source

-setGlobal

(-setGlobal varname varval)

Set a value in the global dict. This function expects the GIL to be locked - it will not lock/unlock it for you.

In addition to numbers and strings, this method can take an implementation of clojure.lang.IFn that will be converted to a python callable, arrays and lists will be converted to python lists. If you would like numpy arrays use -createArray.

view source

-setItem

(-setItem pyobj itemName itemVal)
view source

-unlockGIL

(-unlockGIL gilstate)

Unlock the gil passing in the gilstate returned from lockGIL. Each call to lockGIL must be paired to a call to unlockGIL.

view source
================================================ FILE: docs/libpython-clj2.python.class.html ================================================ libpython-clj2.python.class documentation

Project

Topics

Namespaces

Public Vars

libpython-clj2.python.class

Namespace to help create a new python class from Clojure. Used as a core implementation technique for bridging JVM objects into python.

create-class

(create-class name bases cls-hashmap)

Create a new class object. Any callable values in the cls-hashmap will be presented as instance methods. Things in the cls hashmap had better be either atoms or already converted python objects. You may get surprised otherwise; you have been warned. See the classes-test file in test/libpython-clj.

Calling super.init() may be done in a non-obvious way:

(py. (py/get-item (py.. self -__class__ -__mro__) 1) __init__ self)

More feedback/research in this area is needed to integrated deeper into the python class hierarchies.

view source

make-kw-instance-fn

(make-kw-instance-fn clj-fn & [{:keys [arg-converter result-converter], :or {arg-converter py-base/as-jvm}, :as options}])

Make an instance function - a function which will be passed the 'this' object as it's first argument. In this case the default behavior is to pass as-jvm bridged python object ptr args and kw dict args to the clojure function without marshalling. Self will be the first argument of the arg vector.

See options to libpython-clj2.python/make-callable.

Options:

  • :arg-converter - gets one argument and must convert into jvm space - defaults to as-jvm.
  • :result-converter - gets one argument and must convert to python space. Has reasonable default.
view source

make-tuple-instance-fn

(make-tuple-instance-fn clj-fn & [{:keys [arg-converter], :or {arg-converter py-base/as-jvm}, :as options}])

Make an instance function - a function which will be passed the 'this' object as it's first argument. In this case the default behavior is to pass raw python object ptr args to the clojure function without marshalling as that can add confusion and unnecessary overhead. Self will be the first argument. Callers can change this behavior by setting the 'arg-converter' option as in 'make-tuple-fn'.

See options to libpython-clj2.python/make-callable.

view source

py-fn->instance-fn

(py-fn->instance-fn py-fn)

Given a python callable, return an instance function meant to be used in class definitions.

view source
================================================ FILE: docs/libpython-clj2.python.html ================================================ libpython-clj2.python documentation

Project

Topics

Namespaces

Public Vars

libpython-clj2.python

Python bindings for Clojure. This library dynamically finds the installed python, loads the shared library and allows Clojure users to use Python modules as if they were Clojure namespaces.

Example:

user> (require '[libpython-clj2.python :as py])
nil
user> (py/initialize!)
;;  ... (logging)
:ok
user> (def np (py/import-module "numpy"))
#'user/np
user> (py/py. np linspace 2 3 :num 10)
[2.         2.11111111 2.22222222 2.33333333 2.44444444 2.55555556
 2.66666667 2.77777778 2.88888889 3.        ]

$a

macro

($a item attr & args)

Call an attribute of an object using automatic detection of the python kwargs. Keywords must be compile time constants. So this won't work with 'apply'. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime. The attr name can be a symbol.

view source

$c

macro

($c item & args)

Call an object using automatic detection of the python kwargs. Keywords must be compile time constants. So this won't work with 'apply'. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime.

view source

->jvm

(->jvm v & [opts])

Copy a python value into java datastructures

view source

->py-dict

(->py-dict v)

Copy v into a python dict

view source

->py-list

(->py-list v)

Copy the data into a python list

view source

->py-tuple

(->py-tuple v)

Copy v into a python tuple

view source

->python

(->python v)

Copy a jvm value into a python object

view source

add-module

(add-module modname)

Add a python module. This can create a module if it doesn't exist.

view source

afn

(afn item attr & args)

Call an attribute of an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs.

Not having an argument after a keyword is an error.

view source

as-jvm

(as-jvm v & [opts])

Copy a python value into java datastructures

view source

as-list

(as-list pobj)

Make a python object appear as a list

view source

as-map

(as-map pobj)

Make a python object appear as a map of it's items

view source

as-python

(as-python v)

Bridge a jvm value into a python object

view source

attr-type-map

(attr-type-map pyobj)

Return a map of attr name to python-type of the attribute

view source

call-attr

(call-attr pyobj attname & args)

Call an attribute on a python object using only positional arguments

view source

call-attr-kw

(call-attr-kw pyobj attname args kw-list)

Call an attribute passing in both positional and keyword arguments.

view source

callable?

(callable? pyobj)

Return true if python object is callable.

view source

cfn

(cfn item & args)

Call an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs.

Not having an argument after a keyword argument is an error.

view source

create-class

(create-class name bases cls-hashmap)

Create a new class object. Any callable values in the cls-hashmap will be presented as instance methods. If you want access to the 'this' object then you must use make-instance-fn.

Example:

user> (require '[libpython-clj2.python :as py])
nil
user> (def cls-obj (py/create-class
                    "myfancyclass"
                    nil
                    {"__init__" (py/make-instance-fn
                                 (fn [this arg]
                                   (py/set-attr! this "arg" arg)
                                   ;;If you don't return nil from __init__ that is an
                                   ;;error.
                                   nil))
                     "addarg" (py/make-instance-fn
                               (fn [this otherarg]
                                 (+ (py/get-attr this "arg")
                                    otherarg)))}))
#'user/cls-obj
user> cls-obj
__no_module__.myfancyclass
user> (def inst (cls-obj 10))
#'user/inst
user> (py/call-attr inst "addarg" 10)
20
view source

def-unpack

macro

(def-unpack symbols input)

Unpack a set of symbols into a set of defs. Useful when trying to match Python idioms - this is definitely not idiomatic Clojure.

Example:

user> (py/def-unpack [a b c] (py/->py-tuple [1 2 3]))
#'user/c
user> a
1
user> b
2
user> c
3
view source

dir

(dir pyobj)
view source

from-import

macro

(from-import module-path item & args)

Support for the from a import b,c style of importing modules and symbols in python. Documentation is included.

view source

get-attr

(get-attr pyobj attname)

Get an attribute from a python object

view source

get-item

(get-item pyobj item-name)

Get an item from a python object using getitem

view source

has-attr?

(has-attr? pyobj att-name)

Return true if this python object has this attribute.

view source

has-item?

(has-item? pyobj item-name)

Return true if the python object has an item. Calls hasitem.

view source

import-as

macro

(import-as module-path varname)

Import a module and assign it to a var. Documentation is included.

view source

import-module

(import-module modname)

Import a python module. Module entries can be accessed via get-attr.

view source

initialize!

(initialize! & {:keys [windows-anaconda-activate-bat library-path no-io-redirect?], :as options})

Initialize the python library. If library path is not provided, then the system attempts to execute a simple python program and have python return system info.

Note: all of the options passed to initialize! may now be provided in a root-level python.edn file. Example:

;; python.edn
{:python-executable   "/usr/bin/python3.7"
 :python-library-path "/usr/lib/libpython3.7m.so"
 :python-home         "/usr/lib/python3.7"
 :python-verbose      true}

or, using a local virtual environment:

;; python.edn
{:python-executable   "env/bin/python"}

Additionaly the file can contain two keys which can can refer to custom hooks to run code just before and just after python is initialised. Typical use case for this is to setup / verify the python virtual enviornment to be used.

:pre-initialize-fn my-ns/my-venv-setup-fn!
:post-initialize-fn my-ns/my-venv-validate-fn!

A :pre-initialize-fn could for example shell out and setup a python virtual enviornment.

The :post-initialize-fn can use all functions from ns libpython-clj2.python as libpython-clj is initialised alreday and could for example be used to validate that later needed libraries can be loaded via calling import-module.

The file MUST be named python.edn and be in the root of the classpath. With a python.edn file in place, the initialize! function may be called with no arguments and the options will be read from the file. If arguments are passed to initialize! then they will override the values in the file.

Returns either :ok in which case the initialization completed successfully or :already-initialized in which case we detected that python has already been initialized via Py_IsInitialized and we do nothing more.

Options:

  • :library-path - Library path of the python library to use.
  • :program-name - Optional -- will show up in error messages from python.
  • :no-io-redirect? - True if you don't want python stdout and stderr redirection to out and err.
  • :python-executable - The python executable to use to find system information.
  • :python-home - Python home directory. The system first uses this variable, then the environment variable PYTHON_HOME, and finally information returned from python system info.
  • :signals? - defaults to false - true if you want python to initialized signals. Be aware that the JVM itself uses quite a few signals - SIGSEGV, for instance - during it's normal course of operation. For more information see:
view source

is-instance?

(is-instance? py-inst py-cls)

Return true if inst is an instance of cls. Note that arguments are reversed as compared to instance?

view source

make-callable

(make-callable ifn options)(make-callable ifn)

Make a python callable object from a clojure function. This is called for you if you use as-python on an implementation of IFn.

Options:

  • :arg-converter - Function called for each function argument before your ifn gets access to it. Defaults to ->jvm.
  • :result-converter - Function called on return value before it gets returned to python. Must return a python object. Defaults to ->python; the result will get an extra incref before being returned to Python to account for the implied tracking of as-python or ->python.
  • :name - Name of the python method. This will appear in stack traces.
  • :doc - documentation for method.
view source

make-fastcallable

(make-fastcallable item)

Wrap a python callable such that calling it in a tight loop with purely positional arguments is a bit (2x-3x) faster.

Example:

user> (def test-fn (-> (py/run-simple-string "def spread(bid,ask):
	return bid-ask

")
                       (get :globals)
                       (get "spread")))
#'user/test-fn
user> test-fn
<function spread at 0x7f330c046040>
user> (py/with-gil (time (dotimes [iter 10000]
                           (test-fn 1 2))))
"Elapsed time: 85.140418 msecs"
nil
user> (py/with-gil (time (dotimes [iter 10000]
                           (test-fn 1 2))))
"Elapsed time: 70.894275 msecs"
nil
user> (with-open [test-fn (py/make-fastcallable test-fn)]
        (py/with-gil (time (dotimes [iter 10000]
                             (test-fn 1 2)))))

"Elapsed time: 39.442622 msecs"
nil
user> (with-open [test-fn (py/make-fastcallable test-fn)]
        (py/with-gil (time (dotimes [iter 10000]
                             (test-fn 1 2)))))

"Elapsed time: 35.492965 msecs"
nil
view source

make-instance-fn

(make-instance-fn ifn options)(make-instance-fn ifn)

Make an callable instance function - a function which will be passed the 'this' object as it's first argument. In addition, this function calls make-callable with a arg-converter defaulted to as-jvm. See documentation for make-callable and libpython-clj2.python.class/make-tuple-instance-fn.

view source

make-kw-instance-fn

(make-kw-instance-fn ifn options)(make-kw-instance-fn ifn)

Make an kw callable instance function - function by default is passed 2 arguments, the positional argument vector and a map of keyword arguments. Results are marshalled back to python using libpython-clj2.python.fn/bridged-fn-arg->python which is also used when bridging an object into python. See documentation for make-callable libpython-clj2.python.class/make-kw-instance-fn.

view source

module-dict

(module-dict mod)

Get the module dictionary.

view source

path->py-obj

(path->py-obj item-path & {:keys [reload?]})

Given a string such as "builtins" or "builtins.list", load the module or the class object in the module.

Options:

  • :reload - Reload the module.
view source

py*

macro

(py* x method args)(py* x method args kwargs)

Special syntax for passing along *args and **kwargs style arguments to methods.

Usage:

(py* obj method args kwargs)

Example:

(def d (python/dict)) d ;;=> {} (def iterable [:a 1 :b 2]) (def kwargs {:cat "dog" :name "taco"}) (py* d update iterable kwargs) d ;;=> {"a": 1, "b": 2, "cat": "dog", "name": "taco"}

view source

py**

macro

(py** x method kwargs)(py** x method arg & args)

Like py*, but it is assumed that the LAST argument is kwargs.

view source

py.

macro

(py. x method-name & args)

Class/object method syntax. (py. obj method arg1 arg2 ... argN) is equivalent to Python's obj.method(arg1, arg2, ..., argN) syntax.

view source

py.-

macro

(py.- x arg)

Class/object getter syntax. (py.- obj attr) is equivalent to Python's obj.attr syntax.

view source

py..

macro

(py.. x & args)

Extended accessor notation, similar to the .. macro in Clojure.

(require-python 'sys) (py.. sys -path (append "/home/user/bin"))

is equivalent to Python's

import sys sys.path.append('/home/user/bin')

SPECIAL SYNTAX for programmatic *args and **kwargs

Special syntax is provided to meet the needs required by Python's *args and **kwargs syntax programmatically.

(= (py.. obj (method args)) (py obj methods args))

(= (py.. obj (method args kwargs)) (py obj method args kwargs))

(= (py.. obj (method kwargs)) (py obj method kwargs))

(= (py.. obj (method arg1 arg2 arg3 ... argN kwargs)) (py obj method arg1 arg2 arg3 ... argN kwargs) (py* obj method arg1 arg2 arg3 ... argN kwargs))

These forms exist for when you need to pass in a map of options in the same way you would use the f(*args, **kwargs) forms in Python.

view source

python-type

(python-type v)

Get the type (as a keyword) of a python object

view source

run-simple-string

(run-simple-string program & {:keys [globals locals]})

Run a string expression returning a map of {:globals :locals}. This uses the global main dict under the covers so it matches the behavior of the cpython implementation with the exception of returning the various maps used.

Note this will never return the result of the expression: https://mail.python.org/pipermail/python-list/1999-April/018011.html

Globals, locals may be provided but are not necessary.

Implemented in cpython as:

PyObject *m, *d, *v; m = PyImport_AddModule("main"); if (m == NULL) return -1; d = PyModule_GetDict(m); v = PyRun_StringFlags(command, Py_file_input, d, d, flags); if (v == NULL) { PyErr_Print(); return -1; } Py_DECREF(v); return 0;

view source

set-attr!

(set-attr! pyobj attname attval)

Set an attribute on a python object. Returns pyobj.

view source

set-attrs!

(set-attrs! pyobj att-seq)

Set a sequence of name value attributes. Returns pyobj.

view source

set-item!

(set-item! pyobj item-name item-val)

Set an item on a python object using setitem

view source

set-items!

(set-items! pyobj item-seq)

Set a sequence of name value. Returns pyobj

view source

stack-resource-context

macro

(stack-resource-context & body)

Create a stack-based resource context. All python objects allocated within this context will be released at the termination of this context. !!This means that no python objects can escape from this context!! You must use copy semantics (->jvm) for anything escaping this context. Furthermore, if you are returning generic python objects you may need to call (into {}) or something like that just to ensure that absolutely everything is copied into the jvm.

view source

with

macro

(with bind-vec & body)

Support for the 'with' statement in python: (py/with item (py/call-attr testcode-module "WithObjClass" true fn-list) (py/call-attr item "doit_err"))

view source

with-gil

macro

(with-gil & body)

Capture the gil for an extended amount of time. This can greatly speed up operations as the mutex is captured and held once as opposed to fine grained grabbing/releasing of the mutex.

view source

with-gil-stack-rc-context

macro

(with-gil-stack-rc-context & body)

Capture the gil, open a resource context. The resource context is released before the gil is leading to much faster resource collection. See documentation on stack-resource-context for multiple warnings; the most important one being that if a python object escapes this context your program will eventually, at some undefined point in the future crash. That being said, this is the recommended pathway to use in production contexts where you want defined behavior and timings related to use of python.

view source

with-manual-gil

macro

(with-manual-gil & body)

When running with -Dlibpython_clj.manual_gil=true, you need to wrap all accesses to the python runtime with this locker. This includes calls to require-python or any other pathways.

  (with-manual-gil
    ...)
view source

with-manual-gil-stack-rc-context

macro

(with-manual-gil-stack-rc-context & body)

When running with -Dlibpython_clj.manual_gil=true, you need to wrap all accesses to the python runtime with this locker. This includes calls to require-python or any other pathways. This macro furthermore defines a stack-based gc context to immediately release objects when the stack frame exits.

view source
================================================ FILE: docs/libpython-clj2.python.np-array.html ================================================ libpython-clj2.python.np-array documentation

Project

Topics

Namespaces

Public Vars

libpython-clj2.python.np-array

Bindings for deeper intergration of numpy into the tech.v3.datatype system. This allows seamless usage of numpy arrays in datatype and tensor functionality such as enabling the tech.v3.tensor/ensure-tensor call to work with numpy arrays -- using zero copying when possible.

All users need to do is call require this namespace; then as-jvm will convert a numpy array into a tech tensor in-place.

datatype->ptr-type-name

(datatype->ptr-type-name dtype)
view source

descriptor->numpy

(descriptor->numpy {:keys [ptr shape strides elemwise-datatype], :as buffer-desc})
view source

dtype->py-dtype-map

view source

numpy->desc

(numpy->desc np-obj)
view source

obj-dtype->dtype

(obj-dtype->dtype py-dtype)
view source

py-dtype->dtype-map

view source
================================================ FILE: docs/libpython-clj2.require.html ================================================ libpython-clj2.require documentation

Project

Topics

Namespaces

Public Vars

libpython-clj2.require

Namespace implementing requiring python modules as Clojure namespaces. This works via scanning the module for metadata and dynamically building the Clojure namespace.

import-python

(import-python)

Loads python, python.list, python.dict, python.set, python.tuple, and python.frozenset.

view source

require-python

(require-python req)(require-python req & reqs)

Basic usage

(require-python 'math) (math/sin 1.0) ;;=> 0.8414709848078965

(require-python 'math :as maaaath)

(maaaath/sin 1.0) ;;=> 0.8414709848078965

(require-python 'math 'csv) (require-python 'math :as pymath 'csv)) (require-python 'math :as pymath 'csv :as py-csv) (require-python 'concurrent.futures) (require-python 'concurrent.futures :as fs) (require-python '(concurrent futures :as fs))

(require-python '[requests :refer get post])

(requests/get "https//www.google.com") ;;=> <Response 200> (get "https//www.google.com") ;;=> <Response 200>

In some cases we may generate invalid arglists metadata for the clojure compiler. In those cases we have a flag, :no-arglists that will disable adding arglists to the generated metadata for the vars. Use the reload flag below if you need to force reload a namespace where invalid arglists have been generated.

(require-python '[numpy :refer linspace :no-arglists :as np])

If you would like to bind the Python module to the namespace, use the :bind-ns flag.

(require-python 'requests :bind-ns true) or (require-python 'requests :bind-ns)

Use with custom modules

For use with a custom namespace foo.py while developing, you can use:

(require-python 'foo :reload)

NOTE: unless you specify the :reload flag, ..: the module will NOT reload. If the :reload flag is set, ..: the behavior mimics importlib.reload

Setting up classpath for custom modules

Note: you may need to setup your PYTHONPATH correctly. WARNING: This is very handy for local REPL development, ..: if you are going to AOT classes, ..: refer to the documentation on codegen ..: or your AOT compilation will fail. If your foo.py lives at /path/to/foodir/foo.py, the easiest way to do it is:

(require-python :from "/path/to/foodir" 'foo) ;; or (require-python "/path/to/foodir" 'foo) ;; or (require-python {:from "/path/to/foodir"} 'foo)

as you prefer.

Additionally, if you want to keep the namespacing as you have it in Python, you may prefer to use a relative import starting from a location of your choosing. If your os.getcwd() => /some/path/foo, and your directory structure looks something like:

/some $ tree . └── path ├── baz │ └── quux.py └── foo └── bar.py

(require-python :from "path" 'baz.quux :as quux :from "path/foo" 'bar)

is perfectly acceptable. It probably makes the most sense to keep you style consistent, but you can mix and match as you see fit between , :from , and {:from }. can either be a file or a directory. If it is a file, the Python path will be set to the directory containing that file.

You may also stack several require-pythons under one path:

(require-python {:from "dir-a"} 'a 'b 'c {:from "dir-b"} 'e.f 'g {:from "dir-c} 'hi.there)

Other options more in keeping with traditional PYTHONPATH management include:

(require-python 'sys) (py/call-attr (py/get-attr sys "path") "append" "/path/to/foodir")

Another option is

(require-python 'os) (os/chdir "/path/to/foodir")

prefix lists

For convenience, if you are loading multiple Python modules with the same prefix, you can use the following notation:

(require-python '(a b c)) is equivalent to (require-python 'a.b 'a.c)

(require-python '(foo [bar :as baz :refer qux])) is equivalent to (require-python '[foo.bar :as baz :refer qux])

(require-python '(foo [bar :as baz :refer qux] buster)) (require-python '[foo.bar :as baz :refer qux] 'foo.buster))

For library developers

If you want to intern all symbols to your current namespace, you can do the following --

(require-python 'math :refer :all)

However, if you only want to use those things designated by the module under the all attribute, you can do

(require-python 'operators :refer :*)

view source
================================================ FILE: docs/new-to-clojure.html ================================================ So Many Parenthesis!

Project

Topics

Namespaces

So Many Parenthesis!

About Clojure

LISP stands for List Processing and it was originally designed by John McCarthy around 1958. It was the first language with a garbage collector making it the first truly high level language assuming you don't consider Fortran a high level language. Here is Dr. McCarthy's seminal paper and for a much better intro than I can give please see here.

Time passed and along came a man named Rich Hickey. Making a long story short, Rich was working in a variety of languages such as C++, Java, and C# when he did a project in Common Lisp and was hooked. There are many YouTube videos and documents that Rich has produced but simple made easy is one I found very compelling. If you enjoy that video, don't stop there; Rich has many interesting, profound, and sometimes provocative things to add to the conversation. For more about his reasoning behind Clojure, please check out his rationale.

My perspective is closer to Uncle Bob's.

To address the parenthesis, we need to talk about homoiconicity. LISPs are part of a subset of languages that build themselves out of their own data structures so that when you type symbols into a file or repl, you get back a data structure of the language itself. This means that several parts of the programmers toolbox can be simpler and you can load a file as data, transform it, and then execute some portion of it all without leaving the language. This isn't something you will really need to understand today, but the point is that the look and structure of the language is a sweet spot to make it more of middle ground between what a human and a machine can understand.

The fallout from having a language that is both a language and a data structure is that you can extend the language without needing to change the compiler. For example, the very first standardized 'object oriented programming' system was CLOS, or Common Lisp Object System. This was implemented on top of Common Lisp with no updates to the compiler whatsoever. In Clojure, we have been able to add things like an async library or software transactional memory without changing the compiler itself because we can extend or change the language quite substantially at compile time.

Clojure is a deeply functional language with pragmatic pathways built for mutation. All of the basic data structures of Clojure are immutable. Learning to program in a functional manner will mean learning things like map and reduce and basically re-wiring how you think about problems. I believe it is this re-wiring that is most beneficial in the long term regardless of whether you become some functional programming God or just dabble for a while.

Many systems, regardless of language, are designed in a functional manner because properties like idempotency and referential transparency make it easier to reason about code that you didn't write. That being said, Clojure doesn't force you to write functional code all the time as it is mainly a pragmatic language. You can easily write mutable code if you like.

For the web, Clojure has a version that compiles to JavaScript so that you can write one language both server and front end side. Many Clojure projects are just one repository and one artifact that when run produces both the server and client side of the equation. Another important usage of the Clojurescript is mobile application development using frameworks like React Native. Clojurescript is truly one of Clojure's greatest strengths and one that the Clojure community has strongly embraced.

No talk about Clojure would be complete without giving major credit to its excellent REPL support. One important aspect of the Clojure REPL is that you can see all of complex nested datastructures easily without needing to write toString or __str__ methods. Because of this visibility advantage a common way to use Clojure is to model your problem as a transformation from datastructure to datastructure, testing each stage of this transformation in the repl and just letting the REPL printing show you the next move. Programming with data is often just easier than programming with objects and debugging data transformations is far, far easier than debugging a complex object graph.

Learning Clojure

There are in fact many resources to learn Clojure and here are some the community recommends:

Books/Courses

  1. Clojure for the Brave and True
  2. Practicalli
  3. Clojure for Data Science
  4. Functional Programming in Scala and Clojure

Practicalli has a page devoted purely to resources on learning Clojure at whatever level you are so if these recommendations do not speak to you please review their books page.

Learn by Writing Code

  1. Clojure Koans
  2. clojinc
  3. Clojurescript Koans
  4. 4Clojure

IDEs/Editors

There are many more IDEs available than listed here; these ones are just very popular:

  1. Calva
  2. Cursive
  3. Atom
  4. emacs + cider
  5. vim + fireplace

One thing to be sure of, regardless of IDE, is to use some form of structural editing. All the better IDEs have it; all the IDEs listed here have it, and I personally really struggle without it. When I have a form of structure editing, however, I can move code around much faster than I can in Java, Python, or C++. This is another benefit of the homoiconicity that we spoke earlier in that we can transform the program easily because it is just a data structure and this includes editor level transformations and analysis.

Off We Go!

Clojure is an amazing language. It is really rewarding on a personal level because it is tailored towards extremely high individual and small group productivity. But this power comes with some caveats and one of those is that learning Clojure takes time and patience. The community is here to support you, however, so check us out:

================================================ FILE: docs/scopes-and-gc.html ================================================ Scopes And Garbage Collection

Project

Topics

Namespaces

Scopes And Garbage Collection

libpython-clj now supports stack-based scoping rules so you can guarantee all python objects created during a section of code will be released by a certain point.

Using the stack-based scoping looks like:

user> (require '[libpython-clj.python :as py])
nil
user> (py/initialize!)
... (logging elided)
:ok
user> (py/stack-resource-context
       (-> (py/->py-dict {:a 1 :b 2})
           ;;Note - Without this call you guarantee a crash.
           (py/->jvm)))
{"a" 1, "b" 2}

You must either call ->jvm or return a keyword at the end of your scope.

In the case where you are processing a batch of items (which we recommend for perf reasons), you can also grab the GIL at the top of your thing:

user> (def dict-seq (py/as-jvm (py/->py-list (repeat 1000 (py/->py-dict {:a 1 :b 2})))))
#'user/dict-seq


user> (def ignored (time (mapv py/->jvm dict-seq)))
"Elapsed time: 2200.556506 msecs"
#'user/ignored
user> (def ignored (time (py/with-gil (mapv py/->jvm dict-seq))))
"Elapsed time: 2095.815518 msecs"
#'user/ignored

The hidden thing above, regardless of if you grab the gil or not is that you are actually holding onto a lot of python objects that could be released. Hence if you aren't disciplined about calling System/gc or if the jvm gc just decides not to run you could be allocating a lot of native-heap objects. Plus what you don't see is that if you call System/gc the resource thread dedicated to releasing things will have a lot of work to do.

For production use cases where you need a bit more assurance that things get released, please consider both grabbing the gil and opening a resource context:

user> (def ignored (time (py/with-gil-stack-rc-context
                           (->> (repeatedly 1000 #(py/->py-dict {:a 1 :b 2}))
                                (py/->py-list)
                                (py/as-jvm)
                                (mapv py/->jvm)))))

"Elapsed time: 3246.847595 msecs"
#'user/ignored

This took a second longer! But, you know that all python objects allocated within that scope are released. Before, you would be in essence hoping that things would be released soon enough.

Again, for production contexts we recommend batch processing objects and using the with-gil-stack-rc-context function call that correctly grabs the gil, opens a resource context and then releases anything allocated within that context.

================================================ FILE: docs/slicing.html ================================================ Slicing And Slices

Project

Topics

Namespaces

Slicing And Slices

The way Python implements slicing is via overloading the get-item function call. This is the call the Python interpreter makes under the covers whenever you use the square bracket [] syntax.

For quite a few objects, that function call take a tuple of arguments. The trick to numpy slicing is to create builtin slice objects with the appropriate arguments and pass them into the get-item call in a tuple.

user> (require '[libpython-clj.python :as py])
nil
user> (require '[libpython-clj.require :refer [require-python]])
... lotta logs ...
user> (require-python '[builtins])
WARNING: AssertionError already refers to: class java.lang.AssertionError in namespace: builtins, being replaced by: #'builtins/AssertionError
WARNING: Exception already refers to: class java.lang.Exception in namespace: builtins, being replaced by: #'builtins/Exception
:ok
user> (doc builtins/slice)
-------------------------
builtins/slice
[[self & [args {:as kwargs}]]]
  slice(stop)
slice(start, stop[, step])

Create a slice object.  This is used for extended slicing (e.g. a[0:10:2]).
nil
user> (require-python '[numpy :as np])
:ok

user> (require-python '[numpy :as np])
:ok
user> (def ary (-> (np/arange 9)
                   (np/reshape [3 3])))
#'user/ary
user> ary
[[0 1 2]
 [3 4 5]
 [6 7 8]]

user> (py/get-item ary [(builtins/slice 1 nil) (builtins/slice 1 nil)])
[[4 5]
 [7 8]]
user> (py/get-item ary [(builtins/slice -1) (builtins/slice 1 nil)])
[[1 2]
 [4 5]]
user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 nil)])
[[1 2]
 [4 5]
 [7 8]]
user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 2)])
[[1]
 [4]
 [7]]
user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 3)])
[[1 2]
 [4 5]
 [7 8]]
user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 4)])
[[1 2]
 [4 5]
 [7 8]]
================================================ FILE: questions/32bit.txt ================================================ PyObject size: 8 PyTypeObject size: 204 type.tp_basicsize: 16 type.tp_as_number: 48 type.tp_as_buffer: 80 type.tp_finalize: 196 py_hash_t: 4 Py_TPFLAGS_DEFAULT: 262144 PyObject details object size: 8 ob_refcnt offset: 0 ob_type offset: 4 gilstate size: 4 ================================================ FILE: questions/64bit.txt ================================================ PyObject size: 16 PyTypeObject size: 408 type.tp_basicsize: 32 type.tp_as_number: 96 type.tp_as_buffer: 160 type.tp_finalize: 392 py_hash_t: 8 Py_TPFLAGS_DEFAULT: 262144 PyObject details object size: 16 ob_refcnt offset: 0 ob_type offset: 8 gilstate size: 4 PyMethodDef details object size: 32 ml_flags offset: 16 ml_doc offset: 24 ================================================ FILE: questions/compile32.sh ================================================ g++ typeobject.cpp -I../cpython/Include -I../cpython/32bit ================================================ FILE: questions/compile64.sh ================================================ g++ typeobject.cpp -I../cpython/Include -I../cpython/64bit ================================================ FILE: questions/ssizet_size.cpp ================================================ #include "Python.h" #include using namespace std; int main( int c, char** v) { printf("%ld\n", static_cast(sizeof(Py_ssize_t))); return 0; } ================================================ FILE: questions/typeobject.cpp ================================================ #include "Python.h" #include #include using namespace std; int main(int c, char** v) { printf( "PyObject size: %ld\n" "PyTypeObject size: %ld\n" "type.tp_basicsize: %ld\n" "type.tp_as_number: %ld\n" "type.tp_as_buffer: %ld\n" "type.tp_finalize: %ld\n" "py_hash_t: %ld\n" "Py_TPFLAGS_DEFAULT: %ld\n" , sizeof(PyObject), sizeof(PyTypeObject), offsetof(PyTypeObject, tp_basicsize), offsetof(PyTypeObject, tp_as_number), offsetof(PyTypeObject, tp_as_buffer), offsetof(PyTypeObject, tp_finalize), sizeof(Py_hash_t), Py_TPFLAGS_DEFAULT ); printf( "PyObject details\n" "object size: %ld\n" "ob_refcnt offset: %ld\n" "ob_type offset: %ld\n" "gilstate size: %ld\n", sizeof(PyObject), offsetof(PyObject, ob_refcnt), offsetof(PyObject, ob_type), sizeof(PyGILState_STATE)); printf( "PyMethodDef details\n" "object size: %ld\n" "ml_flags offset: %ld\n" "ml_doc offset: %ld\n", sizeof(PyMethodDef), offsetof(PyMethodDef, ml_flags), offsetof(PyMethodDef, ml_doc)); } ================================================ FILE: resources/clj-kondo.exports/clj-python/libpython-clj/config.edn ================================================ {:hooks {:analyze-call {libpython-clj.jna.base/def-pylib-fn hooks.libpython-clj.jna.base.def-pylib-fn/def-pylib-fn libpython-clj.require/import-python hooks.libpython-clj.require.import-python/import-python}} :linters {:unused-namespace {:exclude [builtins.list builtins.dict builtins.set builtins.tuple builtins.frozenset builtins.str builtins]}} } ================================================ FILE: resources/clj-kondo.exports/clj-python/libpython-clj/hooks/libpython_clj/jna/base/def_pylib_fn.clj ================================================ ;; XXX: work on export-symbols from tech.parallel.utils? (ns hooks.libpython-clj.jna.base.def-pylib-fn "The def-pylib-fn macro from libpython-clj/jna/base.clj" (:require [clj-kondo.hooks-api :as api])) ;; from: libpython-clj/jna/base.clj ;; (defmacro def-pylib-fn ;; [fn-name docstring rettype & argpairs] ;; `(defn ~fn-name ;; ~docstring ;; ~(mapv first argpairs) ;; (when-not (== (current-thread-id) (.get ^AtomicLong gil-thread-id)) ;; (throw (Exception. "Failure to capture gil when calling into libpython"))) ;; (let [~'tvm-fn (jna/find-function ~(str fn-name) *python-library*) ;; ~'fn-args (object-array ;; ~(mapv (fn [[arg-symbol arg-coersion]] ;; (when (= arg-symbol arg-coersion) ;; (throw (ex-info (format "Argument symbol (%s) cannot match coersion (%s)" ;; arg-symbol arg-coersion) ;; {}))) ;; `(~arg-coersion ~arg-symbol)) ;; argpairs))] ;; ~(if rettype ;; `(.invoke (jna-base/to-typed-fn ~'tvm-fn) ~rettype ~'fn-args) ;; `(.invoke (jna-base/to-typed-fn ~'tvm-fn) ~'fn-args))))) ;; called like: ;; (def-pylib-fn PyImport_AddModule ;; "Return value: Borrowed reference. ;; ;; Similar to PyImport_AddModuleObject(), but the name is a UTF-8 encoded string instead ;; of a Unicode object." ;; Pointer ;; [name str]) (defn def-pylib-fn "Macro in libpython-clj/jna/base.clj. Example call: (def-pylib-fn PyImport_AddModule \"Return value: Borrowed reference. Similar to PyImport_AddModuleObject(), but the name is a UTF-8 ... of a Unicode object.\" Pointer [name str]) This has the form: (def-pylib-fn fn-name docstring rettype & argpairs) May be treating it as: (defn fn-name [arg1 arg2 ,,, argn] [arg1 arg2 ,,, argn]) ; fake usage of args? where arg1, ..., argn are extracted from argpairs is acceptable. XXX: using the second elements of argpairs might be worth doing to avoid unused warnings. " [{:keys [:node]}] (let [[_ fn-name _ _ & argpairs] (:children node) pairs (map (fn [vec-node] (let [[an-arg a-type] (:children vec-node)] [an-arg a-type])) argpairs) new-node (with-meta (api/list-node (apply concat [(api/token-node 'defn) fn-name (api/vector-node (map first pairs))] pairs)) (meta node))] ;; XXX: uncomment following and run clj-kondo on cl_format.clj to debug ;;(prn (api/sexpr node)) ;;(prn (api/sexpr new-node)) {:node new-node})) ================================================ FILE: resources/clj-kondo.exports/clj-python/libpython-clj/hooks/libpython_clj/require/import_python.clj ================================================ (ns hooks.libpython-clj.require.import-python "The import-python macro from libpython-clj/require.clj" (:require [clj-kondo.hooks-api :as api])) ;; from: libpython-clj/require.clj ;; (defn import-python ;; "Loads python, python.list, python.dict, python.set, python.tuple, ;; and python.frozenset." ;; [] ;; (require-python ;; '(builtins ;; [list :as python.list] ;; [dict :as python.dict] ;; [set :as python.set] ;; [tuple :as python.tuple] ;; [frozenset :as python.frozenset] ;; [str :as python.str]) ;; '[builtins :as python]) ;; :ok) ;; alternative: ;; ;; (require ;; (quote [builtins.list :as python.list]) ;; (quote [builtins.dict :as python.dict]) ;; (quote [builtins.set :as python.set]) ;; (quote [builtins.tuple :as python.tuple]) ;; (quote [builtins.frozenset :as python.frozenset]) ;; (quote [builtins.str :as python.str]) ;; (quote [builtins :as python])) (defn make-require [ns-sym alias-sym] (api/list-node [(api/token-node 'require) (api/list-node [(api/token-node 'quote) (api/vector-node [(api/token-node ns-sym) (api/keyword-node :as) (api/token-node alias-sym)])])])) (defn import-python "Macro in libpython-clj/require.clj. Example call: (import-python) May be treating it as: (do (require (quote [builtins.list :as python.list])) (require (quote [builtins.dict :as python.dict])) ,,, ) " [{:keys [:node]}] (let [new-node (with-meta (api/list-node [(api/token-node 'do) (make-require 'builtins.list 'python.list) (make-require 'builtins.dict 'python.dict) (make-require 'builtins.set 'python.set) (make-require 'builtins.tuple 'python.tuple) (make-require 'builtins.frozenset 'python.frozenset) (make-require 'builtins.str 'python.str) (make-require 'builtins 'python)]) (meta node))] ;; XXX: uncomment following and run clj-kondo on cl_format.clj to debug ;;(prn (api/sexpr node)) ;;(prn (api/sexpr new-node)) {:node new-node})) ================================================ FILE: scripts/build-conda-docker ================================================ #!/bin/bash set -e pushd dockerfiles docker build -t docker-conda -f CondaDockerfile --build-arg USERID=$(id -u) --build-arg GROUPID=$(id -u) --build-arg USERNAME=$USER . popd ================================================ FILE: scripts/build-py38-docker ================================================ #!/bin/bash set -e pushd dockerfiles docker build -t docker-py38 -f Py38Dockerfile --build-arg USERID=$(id -u) --build-arg GROUPID=$(id -u) --build-arg USERNAME=$USER . popd ================================================ FILE: scripts/build-py39-docker ================================================ #!/bin/bash set -e pushd dockerfiles docker build -t docker-py39 -f Py39Dockerfile --build-arg USERID=$(id -u) --build-arg GROUPID=$(id -u) --build-arg USERNAME=$USER . popd ================================================ FILE: scripts/conda-repl ================================================ #!/bin/bash source activate pyclj ## This is absolutely necessary. ## https://github.com/conda/conda/issues/9500#issuecomment-565753807 export LD_LIBRARY_PATH="$(python3-config --prefix)/lib" lein update-in :dependencies conj \[nrepl\ \"0.6.0\"\]\ -- update-in :plugins conj \[cider/cider-nrepl\ \"0.25.5\"\]\ -- repl :headless :host localhost ================================================ FILE: scripts/deploy ================================================ #!/bin/bash set -e rm -rf classes scripts/run-tests clj -X:codox rm -rf pom.xml clj -T:build jar cp target/classes/META-INF/maven/clj-python/libpython-clj/pom.xml . clj -X:deploy ================================================ FILE: scripts/install ================================================ #!/bin/bash set -e clj -X:depstar clj -X:install ================================================ FILE: scripts/py38-repl ================================================ #!/bin/bash lein update-in :dependencies conj \[nrepl\ \"0.6.0\"\]\ -- update-in :plugins conj \[cider/cider-nrepl\ \"0.25.5\"\]\ -- repl :headless :host localhost ================================================ FILE: scripts/run-conda-docker ================================================ #!/bin/bash scripts/build-conda-docker docker run --rm -it -u $(id -u):$(id -g) \ -v /$HOME/.m2:/home/$USER/.m2 \ -v $(pwd)/:/libpython-clj \ --net=host -w /libpython-clj \ docker-conda scripts/conda-repl ================================================ FILE: scripts/run-py38-docker ================================================ #!/bin/bash scripts/build-py38-docker docker run --rm -it -u $(id -u):$(id -g) \ -v /$HOME/.m2:/home/$USER/.m2 \ -v $(pwd)/:/libpython-clj \ --net=host -w /libpython-clj \ docker-py38 scripts/py38-repl ================================================ FILE: scripts/run-py39-docker ================================================ #!/bin/bash scripts/build-py39-docker docker run --rm -it -u $(id -u):$(id -g) \ -v /$HOME/.m2:/home/$USER/.m2 \ -v $(pwd)/:/libpython-clj \ --net=host -w /libpython-clj \ docker-py39 scripts/py38-repl ================================================ FILE: scripts/run-tests ================================================ #!/bin/bash set -e clj -M:test ================================================ FILE: src/libpython_clj2/codegen.clj ================================================ (ns libpython-clj2.codegen "Generate a namespace on disk for a python module or instances" (:require [clojure.java.io :as io] [libpython-clj2.python :as py] [clojure.string :as s] [clojure.tools.logging :as log]) (:import [java.nio.file Paths] [java.io Writer])) (defn- escape-quotes [input-str] (if input-str (-> (.replace (str input-str) "\\" "\\\\") (.replace "\"" "\\\"")) "")) (defn- get-docs [v] (escape-quotes (:doc v "No documentation"))) (defn- output-module-list [^Writer writer clj-name k v] (.write writer (format " (def ^{:doc \"%s\"} %s (as-jvm/generic-python-as-list (py-global-delay (py/get-attr @src-obj* \"%s\")))) " (get-docs v) clj-name k))) (defn- output-module-tuple [^Writer writer clj-name k v] (.write writer (format " (def ^{:doc \"%s\"} %s (as-jvm/generic-python-as-list (py-global-delay (py/get-attr @src-obj* \"%s\")))) " (get-docs v) clj-name k))) (defn- output-module-dict [^Writer writer clj-name k v] (.write writer (format " (def ^{:doc \"%s\"} %s (as-jvm/generic-python-as-map (py-global-delay (py/get-attr @src-obj* \"%s\")))) " (get-docs v) clj-name k))) (defn- output-module-callable [^Writer writer clj-name k v] (.write writer (format " (def ^{:doc \"%s\" :arglists '%s} %s (as-jvm/generic-callable-pyobject (py-global-delay (py/get-attr @src-obj* \"%s\"))))" (get-docs v) (:arglists v) clj-name k clj-name))) (defn- output-module-generic [^Writer writer clj-name k v vv] (let [output-value (cond ;;nils and boolean require no extra formatting (or (nil? vv) (boolean? vv)) vv ;;string values should be output surrounded by double quotes (string? vv) (format "\"%s\"" (escape-quotes vv)) ;;NaN is a number and should use the proper reader macro (and (number? vv) (Double/isNaN vv)) "##NaN" ;;Finite, non NAN numbers should be treated as literals (and (number? vv) (Double/isFinite vv)) vv ;;Positive and negative infinity are numbers and should use the proper reader macros (and (number? vv) (not (neg? vv)) (Double/isInfinite vv)) "##Inf" (and (number? vv) (neg? vv) (Double/isInfinite vv)) "##-Inf" ;;Anything else should be derefed by name from Python :else (format "(as-jvm/generic-pyobject (py-global-delay (py/get-attr @src-obj* \"%s\")))" k) )] (.write writer (format "\n\n(def ^{:doc \"%s\"} %s %s)" (get-docs v) clj-name output-value)))) (def ^:no-doc default-exclude '[+ - * / float double int long mod byte test char short take partition require max min identity empty mod repeat str load cast type sort conj map range list next hash eval bytes filter compile print set format compare reduce merge]) (def ^:private invalid-symbol-names #{"__cached__" "__file__"}) (defn write-namespace! "Generate a clojure namespace file from a python module or class. If python hasn't been initialized yet this will call the default python initialization. Accessing the generated namespace without initialization will cause an error. Once generated this namespace is safe to be used for AOT, Options: * `:output-fname` - override the autogenerated file path. * `:output-dir` - Defaults \"src\". Set the output directory. The final filename, if `:output-fname` is not provided, is built up from `:ns-prefix and `py-mod-or-cls`. * `:ns-symbol` - The fully qualified namespace symbol. If not provided is built from `:ns-prefix` and `py-mod-or-cls`. * `:ns-prefix` - The prefix used for all python namespaces. Defaults to \"python\". * `:symbol-name-remaps` - A list of remaps used to avoid name clashes with clojure.core or builtin java symbols. * `:exclude` - List of symbols used like `(:refer-clojure :exclude %s)`. You can see the default list as `codegen/default-exclude`. Example: ```clojure user> (require '[libpython-clj2.codegen :as codegen]) nil user> (codegen/write-namespace! \"builtins\" {:symbol-name-remaps {\"AssertionError\" \"PyAssertionError\" \"Exception\" \"PyException\"}}) :ok user> (require '[python.builtins :as python]) nil user> (doc python/list) ------------------------- python.builtins/list [[self & [args {:as kwargs}]]] Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified. nil user> (doto (python/list) (.add 1) (.add 2)) [1, 2] ```" ([py-mod-or-cls {:keys [output-fname output-dir ns-symbol ns-prefix symbol-name-remaps exclude] :or {output-dir "src" ns-prefix "python" exclude default-exclude}}] (let [metadata-fn (requiring-resolve 'libpython-clj2.metadata/datafy-module-or-class) ns-symbol (or ns-symbol (symbol (str (when-not (s/blank? ns-prefix) (str ns-prefix ".")) py-mod-or-cls)))] (py/with-gil-stack-rc-context (let [target (py/path->py-obj py-mod-or-cls) target-metadata (metadata-fn target) output-fname (or output-fname (-> (->> (-> (str ns-symbol) (.replace "-" "_") (s/split #"\.")) (into-array String) (Paths/get output-dir)) (str ".clj")))] (log/debugf "Writing python module %s to file %s" target output-fname) (io/make-parents output-fname) (with-open [writer (io/writer output-fname)] (.write writer (format "(ns %s \"%s\" (:require [libpython-clj2.python :as py] [libpython-clj2.python.jvm-handle :refer [py-global-delay]] [libpython-clj2.python.bridge-as-jvm :as as-jvm]) (:refer-clojure :exclude %s))" (name ns-symbol) (escape-quotes (get target "__doc__" "No documentation provided")) (or exclude []))) (.write writer (format "\n\n(defonce ^:private src-obj* (py-global-delay (py/path->py-obj \"%s\")))" py-mod-or-cls)) (doseq [[k v] target-metadata] (when (and (string? k) (not= "__cached__" k) (not= 0 (count k)) (map? v) (py/has-attr? target k)) (let [clj-name (get symbol-name-remaps k k)] (case (:type v) :list (output-module-list writer clj-name k v) :tuple (output-module-tuple writer clj-name k v) :dict (output-module-dict writer clj-name k v) (if (:callable? (:flags v)) (output-module-callable writer clj-name k v) (output-module-generic writer clj-name k v (py/get-attr target k)))))))) :ok)))) ([py-mod-or-cls] (write-namespace! py-mod-or-cls nil))) (comment (do (write-namespace! "builtins" {:symbol-name-remaps {"AssertionError" "PyAssertionError" "Exception" "PyException"}}) (write-namespace! "numpy") ) ) ================================================ FILE: src/libpython_clj2/embedded.clj ================================================ (ns libpython-clj2.embedded "Tools for embedding clojure into a python host process. See jbridge.py for python details. This namespace relies on the classpath having nrepl and cider-nrepl on it. For example: ```console clojure -SPath '{:deps {nrepl/nrepl {:mvn/version \"0.8.3\"} cider/cider-nrepl {:mvn/version \"0.25.5\"}}}' ... ```" (:require [libpython-clj2.python.ffi :as py-ffi] [nrepl.server :as server] [nrepl.cmdline :as cmdline] [clojure.tools.logging :as log])) (defn initialize! "Initialize python when this library is being called *from* a python program. In that case, unless libpath is explicitly provided the system will look for the python symbols in the current executable." ([] (py-ffi/set-library! nil)) ([libpath] (py-ffi/set-library! libpath))) (defonce ^:private repl-server* (atom nil)) (defn stop-repl! "If an existing repl has been started, stop it. This returns control to the thread that called `start-repl!`." [] (swap! repl-server* (fn [server] (when server (try (locking #'repl-server* (server/stop-server server) (.notifyAll ^Object #'repl-server*)) nil (catch Throwable e (log/errorf e "Failed to stop nrepl server!") nil)))))) (defn start-repl! "This is called to start a clojure repl and block the thread. This function does not return control to the calling thread until another thread calls `stop-repl!; this design is explicit to ensure the python GIL is released and thus when connected to the REPL you can use Python. If an existing repl server has been started this returns the port of the previous server else it returns the port of the new server. To return control to the calling thread call `stop-repl!`. Options are the same as the command line options found in nrepl.cmdline." ([options] (when-not @repl-server* (let [options (cmdline/server-opts (merge {:middleware '[cider.nrepl/cider-middleware]} options)) server (cmdline/start-server options) _ (reset! repl-server* server)] (cmdline/ack-server server options) (cmdline/save-port-file server options) (log/info (cmdline/server-started-message server options)) (locking #'repl-server* (.wait ^Object #'repl-server*)))) (:port @repl-server*)) ([] (start-repl! nil))) ================================================ FILE: src/libpython_clj2/java_api.clj ================================================ (ns libpython-clj2.java-api "A java api is exposed for libpython-clj2. The methods below are statically callable without the leading '-'. Note that returned python objects implement the respective java interfaces so a python dict will implement java.util.Map, etc. There is some startup time as Clojure dynamically compiles the source code but this binding should have great runtime characteristics in comparison to any other java python engine. Note that you can pass java objects into python. An implementation of java.util.Map will appear to python as a dict-like object an implementation of java.util.List will look like a sequence and if the thing is iterable then it will be iterable in python. To receive callbacks from python you can provide an implementation of the interface [clojure.lang.IFn](https://clojure.github.io/clojure/javadoc/clojure/lang/IFn.html) - see [clojure.lang.AFn](https://github.com/clojure/clojure/blob/master/src/jvm/clojure/lang/AFn.java) for a base class that makes this easier. Performance: There are a two logical ways to repeatedly invoke python functionality. The first is to set some globals and repeatedly [[runStringAsInput]] a script. The second is 'exec'ing a script, finding an exported function in the global dict and calling that. With libpython-clj, the second pathway -- repeatedly calling a function -- is going to be faster than the first if the user makes a fastcallable out of the function to be invoked. Here are some sample timings for an extremely simple function with two arguments: ```console Python fn calls/ms 1923.2490094806021 Python fastcallable calls/ms 3776.767751742239 Python eval pathway calls/ms 2646.0478013509883 ``` * [[makeFastcallable]] - - For the use case of repeatedly calling a single function - this will cache the argument tuple for repeated use as opposed to allocating the argument tuple every call. This can be a surprising amount faster -- 2x-3x -- than directly calling the python callable. Once a fastcallable object is made you can either cast it to a [clojure.lang.IFn](https://clojure.github.io/clojure/javadoc/clojure/lang/IFn.html) or call it via the provided `call` static method. * HAIR ON FIRE MODE - If you are certain you are correctly calling lockGIL and unlockGIL then you can define a variable, `-Dlibpython_clj.manual_gil=true` that will disable automatic GIL lock/unlock system and gil correctness checking. This is useful, for instance, if you are going to lock libpython-clj to a thread and control all access to it yourself. This pathway will get at most 10% above using fastcall by itself. Example: ```java java_api.initialize(null); try (AutoCloseable locker = java_api.GILLocker()) { np = java_api.importModule(\"numpy\"); Object ones = java_api.getAttr(np, \"ones\"); ArrayList dims = new ArrayList(); dims.add(2); dims.add(3); Object npArray = java_api.call(ones, dims); //see fastcall notes above ... } ```" (:import [java.util Map Map$Entry List HashMap LinkedHashMap Set HashSet] [java.util.function Supplier] [java.lang AutoCloseable] [clojure.java.api Clojure] [com.google.common.cache CacheBuilder RemovalListener]) (:gen-class :name libpython_clj2.java_api :main false :methods [#^{:static true} [initialize [java.util.Map] Object] #^{:static true} [initializeEmbedded [] Object] #^{:static true} [lockGIL [] long] #^{:static true} [unlockGIL [long] Object] #^{:static true} [GILLocker [] java.lang.AutoCloseable] #^{:static true} [hasAttr [Object String] Boolean] #^{:static true} [getAttr [Object String] Object] #^{:static true} [setAttr [Object String Object] Object] #^{:static true} [hasItem [Object Object] Boolean] #^{:static true} [getItem [Object Object] Object] #^{:static true} [setItem [Object Object Object] Object] #^{:static true} [getGlobal [String] Object] #^{:static true} [setGlobal [String Object] Object] #^{:static true} [runStringAsInput [String] Object] #^{:static true} [runStringAsFile [String] java.util.Map] #^{:static true} [importModule [String] Object] #^{:static true} [callKw [Object java.util.List java.util.Map] Object] #^{:static true} [call [Object] Object] #^{:static true} [call [Object Object] Object] #^{:static true} [call [Object Object Object] Object] #^{:static true} [call [Object Object Object Object] Object] #^{:static true} [call [Object Object Object Object Object] Object] #^{:static true} [call [Object Object Object Object Object Object] Object] #^{:static true} [call [Object Object Object Object Object Object Object] Object] #^{:static true} [allocateFastcallContext [] Object] #^{:static true} [releaseFastcallContext [Object] Object] ;;args require context #^{:static true} [fastcall [Object Object] Object] #^{:static true} [fastcall [Object Object Object] Object] ;;1 #^{:static true} [fastcall [Object Object Object Object] Object] ;;2 #^{:static true} [fastcall [Object Object Object Object Object] Object] ;;3 #^{:static true} [fastcall [Object Object Object Object Object Object] Object] ;;4 #^{:static true} [makeFastcallable [Object] java.lang.AutoCloseable] #^{:static true} [copyToPy [Object] Object] #^{:static true} [copyToJVM [Object] Object] #^{:static true} [createArray [String Object Object] Object] #^{:static true} [arrayToJVM [Object] java.util.Map] #^{:static true} [copyData [Object Object] Object]] )) (set! *warn-on-reflection* true) (def ^:private requires* (delay (let [require (Clojure/var "clojure.core" "require")] (doseq [clj-ns ["tech.v3.datatype" "tech.v3.tensor" "libpython-clj2.python" "libpython-clj2.python.fn" "libpython-clj2.python.ffi" "libpython-clj2.python.gc" "libpython-clj2.python.np-array"]] (require (Clojure/read clj-ns)))))) (def ^:private ->python* (delay (Clojure/var "libpython-clj2.python" "->python"))) (def ^:private fastcall* (delay (Clojure/var "libpython-clj2.python.fn" "fastcall"))) (def ^:private allocate-fastcall-context* (delay (Clojure/var "libpython-clj2.python.fn" "allocate-fastcall-context"))) (def ^:private release-fastcall-context* (delay (Clojure/var "libpython-clj2.python.fn" "release-fastcall-context"))) (def ^:private make-fastcallable* (delay (Clojure/var "libpython-clj2.python.fn" "make-fastcallable"))) (def ^:private check-error-throw* (delay (Clojure/var "libpython-clj2.python.ffi" "check-error-throw"))) (def ^:private simplify-or-track* (delay (Clojure/var "libpython-clj2.python.ffi" "simplify-or-track"))) (def ^:private as-jvm* (delay (Clojure/var "libpython-clj2.python" "as-jvm"))) (def ^:private ->jvm* (delay (Clojure/var "libpython-clj2.python" "->jvm"))) (def ^:private eval-code* (delay (Clojure/var "libpython-clj2.python.ffi" "PyEval_EvalCode"))) (def ^:private untracked->python* (delay (Clojure/var "libpython-clj2.python.ffi" "untracked->python"))) (def ^:private decref* (delay (Clojure/var "libpython-clj2.python.ffi" "Py_DecRef"))) (defn- decref-lru-cache ^Map [^long max-size] (let [builder (CacheBuilder/newBuilder)] (.maximumSize builder max-size) (.removalListener builder (reify RemovalListener (onRemoval [this notification] (@decref* (.getValue notification))))) (-> (.build builder) (.asMap)))) (def ^{:tag Map :private true} string-cache (decref-lru-cache 1024)) (declare -lockGIL -unlockGIL) (def ^:private globals* (delay (let [gstate (-lockGIL) main-mod ((Clojure/var "libpython-clj2.python.ffi" "PyImport_AddModule") "__main__")] (-> ((Clojure/var "libpython-clj2.python.ffi" "PyModule_GetDict") main-mod) (@as-jvm*))))) (def ^:private strcomp* (delay (let [->python @->python*] (reify java.util.function.Function (apply [this data] (->python data)))))) (declare -createArray) (def ^{:tag 'Map :private true} primitive-arrays (let [base-arrays [[(byte-array 0) {:length #(alength ^bytes %) :datatype "int8"}] [(short-array 0) {:length #(alength ^shorts %) :datatype "int16"}] [(int-array 0) {:length #(alength ^ints %) :datatype "int32"}] [(long-array 0) {:length #(alength ^longs %) :datatype "int64"}] [(float-array 0) {:length #(alength ^floats %) :datatype "float32"}] [(double-array 0) {:length #(alength ^doubles %) :datatype "float64"}]] typeset (HashMap.)] (doseq [[ary getter] base-arrays] (.put typeset (type ary) getter)) typeset)) (def ^{:tag 'Set :private true} array-types (let [base-arrays [(byte-array 0) (short-array 0) (int-array 0) (long-array 0) (float-array 0) (double-array 0)] array-of-arrays (->> base-arrays (map (fn [ary] (into-array [ary])))) typeset (HashSet.)] (doseq [t array-of-arrays] (.add typeset (type t))) (.addAll typeset (.keySet primitive-arrays)) typeset)) #_(defn- to-python "Support for auto-converting primitive arrays and array-of-arrays into python." [item] (let [item-type (type item)] (if (.contains array-types item-type) (if-let [len-getter (get primitive-arrays item-type)] (-createArray (len-getter :datatype) [((len-getter :length) item)] item) ;;potential 2d array if all lengths match (let [^objects item item item-len (alength item) [datatype shape] (when-let [fitem (when-not (== 0 item-len) (aget item 0))] (let [ary-entry (get primitive-arrays (type fitem)) inner-len (get ary-entry :length) ary-dt (get ary-entry :datatype) fitem-len (unchecked-long (inner-len fitem)) matching? (loop [idx 1 matching? true] (if (< idx item-len) (recur (unchecked-inc idx) (and matching? (== fitem-len (unchecked-long (if-let [inner-item (aget item idx)] (inner-len inner-item) 0))))) matching?))] (when matching? [ary-dt [item-len fitem-len]])))] (if shape (-createArray datatype shape item) ;;slower fallback for ragged arrays (@->python* item)))) (@->python* item)))) (def ^:private fast-dict-set-item* (delay (let [untracked->python (Clojure/var "libpython-clj2.python.ffi" "untracked->python") ->python @->python* decref (Clojure/var "libpython-clj2.python.ffi" "Py_DecRef") pydict-setitem (Clojure/var "libpython-clj2.python.ffi" "PyDict_SetItem")] (fn [dict k v] (let [v (untracked->python v ->python)] (pydict-setitem dict k v) (decref v)))))) (defn- cached-string [strval] (when strval (.computeIfAbsent string-cache strval @strcomp*))) (def ^{:tag Map :private true} compile-cache (decref-lru-cache 1024)) (def ^:private compiler* (delay (let [compile-fn (Clojure/var "libpython-clj2.python.ffi" "Py_CompileString")] (reify java.util.function.Function (apply [this [strdata run-type]] (compile-fn strdata "unnamed.py" (case run-type :file 257 :input 258))))))) (defn- compile-string [strval run-type] (when strval (.computeIfAbsent compile-cache [strval run-type] @compiler*))) (defn -initialize "See options for [[libpython-clj2.python/initialize!]]. Note that the keyword option arguments can be provided by using strings so `:library-path` becomes the key \"library-path\". Also note that there is still a GIL underlying all of the further operations so java should access python via single-threaded pathways." [options] @requires* (apply (Clojure/var "libpython-clj2.python" "initialize!") (->> options (mapcat (fn [^Map$Entry entry] [(keyword (.getKey entry)) (.getValue entry)]))))) (defn -initializeEmbedded "Initialize python when this library is being called *from* a python program. In that case the system will look for the python symbols in the current executable. See the [embedded topic](https://clj-python.github.io/libpython-clj/embedded.html)" [] @requires* ((Clojure/var "libpython-clj2.python.ffi" "set-library!") nil)) (defn -lockGIL "Attempt to lock the gil. This is safe to call in a reentrant manner. Returns a long representing the gil state that must be passed into unlockGIL. See documentation for [pyGILState_Ensure](https://docs.python.org/3/c-api/init.html#c.PyGILState_Ensure). Note that the API will do this for you but locking the GIL before doing a string of operations is faster than having each operation lock the GIL individually." [] ((Clojure/var "libpython-clj2.python.ffi" "lock-gil"))) (defn -unlockGIL "Unlock the gil passing in the gilstate returned from lockGIL. Each call to lockGIL must be paired to a call to unlockGIL." [gilstate] ((Clojure/var "libpython-clj2.python.ffi" "unlock-gil") gilstate)) (defn -GILLocker "Lock the gil returning an AutoCloseable that will unlock the gil upon close. Example: ```java try (AutoCloseable locker = java_api.GILLocker()) { ... Do your python stuff. } ```" ^AutoCloseable [] (let [gilstate (-lockGIL)] (reify AutoCloseable (close [this] (-unlockGIL gilstate))))) (defn -hasAttr "Returns true if this python object has this attribute." [pyobj attname] (boolean ((Clojure/var "libpython-clj2.python" "has-attr?") pyobj attname))) (defn -getAttr "Get a python attribute. This corresponds to the python '.' operator." [pyobj attname] ((Clojure/var "libpython-clj2.python" "get-attr") pyobj attname)) (defn -setAttr "Set an attribute on a python object. This corresponds to the `__setattr` python call." [pyobj attname objval] ((Clojure/var "libpython-clj2.python" "set-attr!") pyobj attname objval)) (defn -hasItem "Return true if this pyobj has this item" [pyobj itemName] (boolean ((Clojure/var "libpython-clj2.python" "has-item?") pyobj itemName))) (defn -getItem [pyobj itemName] ((Clojure/var "libpython-clj2.python" "get-item") pyobj itemName)) (defn -setItem [pyobj itemName itemVal] ((Clojure/var "libpython-clj2.python" "set-item!") pyobj itemName itemVal)) (defn -setGlobal "Set a value in the global dict. This function expects the GIL to be locked - it will not lock/unlock it for you. In addition to numbers and strings, this method can take an implementation of `clojure.lang.IFn` that will be converted to a python callable, arrays and lists will be converted to python lists. If you would like numpy arrays use [[-createArray]]." [^String varname varval] (@fast-dict-set-item* @globals* (cached-string varname) varval) nil) (defn -getGlobal "Get a value from the global dict. This function expects the GIL to be locked - it will not lock/unlock it for you." [^String varname] (-getItem @globals* (cached-string varname))) (defn -runStringAsInput "Run a string returning the result of the last expression. Strings are compiled and live for the life of the interpreter. This is the equivalent to the python [eval](https://docs.python.org/3/library/functions.html#eval) call. This function expects the GIL to be locked - it will not lock/unlock it for you. Example: ```java java_api.setGlobal(\"bid\", 1); java_api.setGlobal(\"ask\", 2); java_api.runStringAsInput(\"bid-ask\"); //Returns -1 ```" [strdata] (let [pyobj (compile-string strdata :input)] (when-not pyobj (@check-error-throw*)) (if-let [script-rt (@eval-code* pyobj @globals* @globals*)] (-> (@simplify-or-track* script-rt) (@as-jvm*))))) (defn -runStringAsFile "Run a string returning the result of the last expression. Strings are compiled and live for the life of the interpreter. This is the equivalent to the python [exec](https://docs.python.org/3/library/functions.html#exec) all. The global context is returned as a java map. This function expects the GIL to be locked - it will not lock/unlock it for you. Example: ```java Map globals = java_api.runStringAsFile(\"def calcSpread(bid,ask):\n\treturn bid-ask\n\n\"); Object spreadFn = globals.get(\"calcSpread\"); java_api.call(spreadFn, 1, 2); // Returns -1 ```" [strdata] (let [pyobj (compile-string strdata :file)] (when-not pyobj (@check-error-throw*)) (@eval-code* pyobj @globals* @globals*) (@check-error-throw*) @globals*)) (defn -importModule "Import a python module. Module entries can be accessed via `getAttr`." [modname] ((Clojure/var "libpython-clj2.python" "import-module") modname)) (defn -callKw "Call a python callable with keyword arguments. Note that you don't need this pathway to call python methods if you do not need keyword arguments; if the python object is callable then it will implement [clojure.lang.IFn](https://clojure.github.io/clojure/javadoc/clojure/lang/IFn.html) and you can use `invoke`." [pyobj pos-args kw-args] (let [gstate (-lockGIL)] (try ((Clojure/var "libpython-clj2.python.fn" "call-kw") pyobj pos-args (->> kw-args (map (fn [^Map$Entry entry] [(.getKey entry) (.getValue entry)])) (into {}))) (finally (-unlockGIL gstate))))) (defn -call "Call a clojure `IFn` object. Python callables implement this interface so this works for python objects. This is a convenience method around casting implementation of [clojure.lang.IFn](https://clojure.github.io/clojure/javadoc/clojure/lang/IFn.html) and calling `invoke` directly." ([item] (item)) ([item arg1] (item arg1)) ([item arg1 arg2] (item arg1 arg2)) ([item arg1 arg2 arg3] (item arg1 arg2 arg3)) ([item arg1 arg2 arg3 arg4] (item arg1 arg2 arg3 arg4)) ([item arg1 arg2 arg3 arg4 arg5] (item item arg1 arg2 arg3 arg4 arg5)) ([item arg1 arg2 arg3 arg4 arg5 arg6] (item item arg1 arg2 arg3 arg4 arg5 arg6))) (defn ^:no-doc -allocateFastcallContext "Allocate a fastcall context. See docs for [[-fastcall]]. The returned context must be release via [[-releaseFastcallContext]]." [] (@allocate-fastcall-context*)) (defn ^:no-doc -releaseFastcallContext "Release a fastcall context. See docs for [[-fastcall]]. This is safe to call with null and to call multiple times on the same context." [ctx] (when ctx (@release-fastcall-context* ctx))) (defn ^:no-doc -fastcall "Call a python function as fast as possible using a fixed number of positional arguments. The caller must provide an allocated fastcall context via [[-allocateFastcallContext]] and furthermore the caller may choose to deallocate the fastcall context with [[-releaseFastcallContext]]. Current overloads support arities up to 4 arguments. You must not use the same context with different arities - contexts are allocated in an arity-specific manner. For a more condensed version see [[makeFastcallable]]." ([ctx item] ;;ctx is unused but placed here to allow rapid search/replace to be correct. (@fastcall* item)) ([ctx item arg1] (@fastcall* ctx item arg1)) ([ctx item arg1 arg2] (@fastcall* ctx item arg1 arg2)) ([ctx item arg1 arg2 arg3] (@fastcall* ctx item arg1 arg2 arg3)) ([ctx item arg1 arg2 arg3 arg4] (@fastcall* ctx item arg1 arg2 arg3 arg4))) (defn -makeFastcallable "Given a normal python callable, make a fastcallable object that needs to be closed. This should be seen as a callsite optimization for repeatedly calling a specific python function in a tight loop with positional arguments. It is not intended to be used in a context where you will then pass this object around as this is not a reentrant optimization. ```java try (AutoCloseable fastcaller = java_api.makeFastcallable(pycallable)) { tightloop: { java_api.call(fastcaller, arg1, arg2); } } ```" ^java.lang.AutoCloseable [item] (@make-fastcallable* item)) (defn -copyToPy "Copy a basic jvm object, such as an implementation of java.util.Map or java.util.List to a python object." [object] ((Clojure/var "libpython-clj2.python" "->python") object)) (defn -copyToJVM "Copy a python object such as a dict or a list into a comparable JVM object." [object] ((Clojure/var "libpython-clj2.python" "->jvm") object)) (defn -createArray "Create a numpy array from a tuple of string datatype, shape and data. * `datatype` - One of \"int8\" \"uint8\" \"int16\" \"uint16\" \"int32\" \"uint32\" \"int64\" \"uint64\" \"float32\" \"float64\". * `shape` - integer array of dimension e.g. `[2,3]`. * `data` - list or array of data. This will of course be fastest if the datatype of the array matches the requested datatype. This does work with array-of-array structures assuming the shape is correct but those will be slower than a single primitive array and a shape." [datatype shape data] (let [reshape (Clojure/var "tech.v3.tensor" "reshape") ->python @->python*] (-> ((Clojure/var "tech.v3.tensor" "->tensor") data :datatype (keyword datatype)) (reshape shape) (->python)))) (defn -arrayToJVM "Copy (efficiently) a numeric numpy array into a jvm map containing keys \"datatype\", \"shape\", and a jvm array \"data\" in flattened row-major form." [pyobj] (let [tens-data ((Clojure/var "libpython-clj2.python" "as-jvm") pyobj)] {"datatype" (name ((Clojure/var "tech.v3.datatype" "elemwise-datatype") tens-data)) "shape" (int-array ((Clojure/var "tech.v3.datatype" "shape") tens-data)) "data" ((Clojure/var "tech.v3.datatype" "->array") tens-data)})) (def ^:private copyfn* (delay (Clojure/var "tech.v3.datatype" "copy!"))) (defn -copyData "Copy data from a jvm container into a numpy array or back. This allows you to use a fixed preallocated set of numpy (and potentially jvm arrays) to transfer data back and forth efficiently. The most efficient transfer will be from a java primitive array that matches the numeric type of the numpy array. Also note the element count of the numpy array and the jvm array must match. Note this copies *from* the first argument *to* the second argument -- this is reverse the normal memcpy argument order!!. Returns the destination (to) argument. Not this does *not* work with array-of-arrays. It will work with, for instance, a numpy matrix of shape [2, 2] and an double array of length 4." [from to] (@copyfn* from to)) ================================================ FILE: src/libpython_clj2/metadata.clj ================================================ (ns libpython-clj2.metadata "Namespace to create metadata from python objects. This namespace requires python helper fns to work correctly and thus cannot be used until after python has been initialized." (:refer-clojure :exclude [fn? doc]) (:require [libpython-clj2.python :refer [import-module as-jvm get-attr call-attr callable? has-attr? ->jvm with-gil] :as py] [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.protocols :as py-proto] [tech.v3.datatype.ffi :as dt-ffi] [clojure.core.protocols :as clj-proto] [clojure.tools.logging :as log])) (py/initialize!) (def builtins (import-module "builtins")) (def inspect (import-module "inspect")) (def argspec (get-attr inspect "getfullargspec")) (def py-source (get-attr inspect "getsource")) (def py-sourcelines (get-attr inspect "getsourcelines")) (def py-file (get-attr inspect "getfile")) (def types (import-module "types")) (def fn-type (call-attr builtins "tuple" [(get-attr types "FunctionType") (get-attr types "BuiltinFunctionType")])) (def method-type (call-attr builtins "tuple" [(get-attr types "MethodType") (get-attr types "BuiltinMethodType")])) (def isinstance? (get-attr builtins "isinstance")) (def fn? #(isinstance? % fn-type)) (def method? #(isinstance? % method-type)) (def doc #(try (get-attr % "__doc__") (catch Exception e ""))) (def os (import-module "os")) (def get-pydoc doc) (def vars (get-attr builtins "vars")) (def pyclass? (get-attr inspect "isclass")) (def pymodule? (get-attr inspect "ismodule")) (def importlib (py/import-module "importlib")) (def importlib_util (import-module "importlib.util")) (def reload-module (py/get-attr importlib "reload")) (defn findspec [x] (let [-findspec (-> importlib_util (get-attr "find_spec"))] (-findspec x))) (defn find-lineno [x] (try (-> x py-sourcelines last) (catch Exception _ nil))) (defn find-file [x] (try (py-file x) (catch Exception _ nil))) (defn py-fn-argspec [f] (if-let [spec (try (when-not (pyclass? f) (argspec f)) (catch Throwable e nil))] {:args (->jvm (get-attr spec "args")) :varargs (->jvm (get-attr spec "varargs")) :varkw (->jvm (get-attr spec "varkw")) :defaults (->jvm (get-attr spec "defaults")) :kwonlyargs (->jvm (get-attr spec "kwonlyargs")) :kwonlydefaults (->jvm (get-attr spec "kwonlydefaults")) :annotations (->jvm (get-attr spec "annotations"))} (py-fn-argspec (get-attr f "__init__")))) (defn py-class-argspec [class] (let [constructor (get-attr class "__init__")] (py-fn-argspec constructor))) (defn pyargspec [x] ;; TODO: certain builtin functions have ;; ..: signatures that are found in the first line ;; ..: of their docstring, aka, print. ;; ..: These seem to be uniform enough that ;; ..: most IDEs have a way of creating stubs ;; ..: for the signature. If there is a uniform way ;; ..: to do this that doesn't simply involve an ;; ..: army of devs doing transcription I'd like to ;; ..: pull that in here (cond (fn? x) (py-fn-argspec x) (method? x) (py-fn-argspec x) ;; (builtin-function? x) (py-builtin-fn-argspec x) ;; (builtin-method? x) (py-builtin-method-argspec x) (string? x) "" (number? x) "" :else (py-class-argspec x))) (defn pyarglists ([argspec] (pyarglists argspec (if-let [defaults (not-empty (:defaults argspec))] defaults []))) ([argspec defaults] (pyarglists argspec defaults [])) ([{:as argspec args :args varkw :varkw varargs :varargs kwonlydefaults :kwonlydefaults kwonlyargs :kwonlyargs} defaults res] (let [n-args (count args) n-defaults (count defaults) n-pos-args (- n-args n-defaults) pos-args (->> args (take n-pos-args) (map symbol) (into [])) kw-default-args (->> args (drop n-pos-args) (map symbol) (into [])) ;;These sometimes have actual python symbols in them so we can't use them ;; or-map (->> (concat ;; (interleave kw-default-args defaults) ;; (flatten (seq kwonlydefaults))) ;; (partition-all 2) ;; (map vec) ;; (map (fn [[k v]] [(symbol k) v])) ;; (into {})) as-varkw (when (not (nil? varkw)) {:as (symbol varkw)}) default-map (->> (concat (interleave kw-default-args defaults) (flatten (seq kwonlydefaults))) (partition-all 2) (map vec) (map (fn [[k v]] [(symbol k) (keyword k)])) (into {})) kwargs-map (merge default-map (when (not-empty as-varkw) as-varkw)) opt-args (cond (and (empty? kwargs-map) (nil? varargs)) '() (empty? kwargs-map) (list '& [(symbol varargs)]) (nil? varargs) (list '& [kwargs-map]) :else (list '& [(symbol varargs) kwargs-map])) arglist ((comp vec concat) (list* pos-args) opt-args)] (let [arglists (conj res arglist) defaults' (if (not-empty defaults) (pop defaults) []) argspec' (update argspec :args (fn [args] (if (not-empty args) (pop args) args)))] (if (and (empty? defaults) (empty? defaults')) arglists (recur argspec' defaults' arglists)))))) (defn py-fn-metadata [fn-name x {:keys [no-arglists?]}] (let [fn-argspec (pyargspec x) fn-docstr (get-pydoc x)] (merge fn-argspec {:doc fn-docstr :name fn-name} (when (and (callable? x) (not no-arglists?)) (try {:arglists (pyarglists fn-argspec)} (catch Throwable e nil)))))) (defn pyobj-flags [item] (->> {:pyclass? pyclass? :callable? callable? :fn? fn? :method? method? :pymodule? pymodule?} (map (fn [[kwd f]] (when (f item) kwd))) (remove nil?) set)) (defn base-pyobj-map [item] (cond-> {:type (cond (pyclass? item) :type (pymodule? item) :module :else (py/python-type item)) :doc (doc item) :str (.toString item) :flags (pyobj-flags item) :line (find-lineno item) :file (find-file item)} (has-attr? item "__module__") (assoc :module (get-attr item "__module__")) (has-attr? item "__name__") (assoc :name (get-attr item "__name__")) (and (find-lineno item) (find-file item)) (assoc :line (find-lineno item) :file (find-file item)))) (defn scalar? [att-val] (or (string? att-val) (number? att-val))) (defn py-chdir [path] (py/$a os "chdir" path)) (defn py-getcwd [] (py/$a os "getcwd")) (defn datafy-module-or-class [item] (with-gil (->> (if (or (pyclass? item) (pymodule? item)) (->> (vars item) (py/as-map) (into {})) (->> (py/dir item) (map (juxt identity #(get-attr item %))))) (map (fn [[att-name att-val]] (when att-val (try [att-name (merge (base-pyobj-map att-val) (when (callable? att-val) (py-fn-metadata att-name att-val {})) (when (scalar? att-val) {:value att-val}))] (catch Throwable e (log/warnf "Metadata generation failed for %s:%s" (.toString item) att-name) nil))))) (remove nil?) (into (base-pyobj-map item))))) (defmethod py-proto/pydatafy :default [pyobj] (if (or (pyclass? pyobj) (pymodule? pyobj)) (datafy-module-or-class pyobj) (base-pyobj-map pyobj))) (defmethod py-proto/pydatafy :dict [pyobj] (->> (py/as-jvm pyobj) (map (fn [[k v]] [k (clj-proto/datafy v)])) (into {}))) (defmethod py-proto/pydatafy :list [pyobj] (->> (py/as-jvm pyobj) (mapv clj-proto/datafy))) (defmethod py-proto/pydatafy :tuple [pyobj] (->> (py/as-jvm pyobj) (mapv clj-proto/datafy))) (defmethod py-proto/pydatafy :set [pyobj] (->> (py/as-jvm pyobj) (map clj-proto/datafy) (set))) (defmethod py-proto/pydatafy :frozenset [pyobj] (->> (py/as-jvm pyobj) (map clj-proto/datafy) (set))) (defn nav-module [coll f val] (with-gil (if (map? val) (cond (= :module (:type val)) (import-module (:name val)) (= :type (:type val)) (let [mod (import-module (:module val)) cls-obj (get-attr mod (:name val))] cls-obj) :else val) val))) (defn metadata-map->py-obj [metadata-map] (try (case (:type metadata-map) :module (import-module (:name metadata-map)) :type (-> (import-module (:module metadata-map)) (get-attr (:name metadata-map)))) (catch Exception e (log/warnf e "metadata-map: %s" metadata-map) ;; metatypes -- e.g. socket.SocketIO (-> (import-module (:module metadata-map)) (get-attr (:name metadata-map)))))) (defn get-or-create-namespace! [ns-symbol ns-doc] (if-let [ns-obj (find-ns ns-symbol)] ns-obj (create-ns (with-meta ns-symbol (merge (meta ns-symbol) {:doc ns-doc}))))) (defn apply-static-metadata-to-namespace! "Given a metadata map, find the item associated with the map and for each string keyword apply it to the namespace. Namespace is created if it does not already exist. Returns the namespace symbol." [ns-symbol metadata-map & {:keys [no-arglists?]}] (let [target-item (metadata-map->py-obj metadata-map)] (get-or-create-namespace! ns-symbol (:doc metadata-map)) (doseq [[k v] metadata-map] (when (and (string? k) (map? v) (has-attr? target-item k)) (let [att-val (get-attr target-item k)] (ns-unmap ns-symbol (symbol k)) (intern ns-symbol (with-meta (symbol k) (if no-arglists? (dissoc v :arglists) v)) att-val)))) ns-symbol)) (defn apply-instance-metadata-to-namespace! "In this case we have at some point in the past generated metadata from an instance and we want to create an namespace to get intellisense on objects of that type. The use case for this is you get a generic 'thing' back and you export its metadata to a resource edn file. You can then always create a namespace from this metadata and use that namespace to explore/use the instance and this will work regardless of if a factory returns a derived object. Returns the namespace symbol." [ns-symbol metadata-map] (get-or-create-namespace! ns-symbol (:doc metadata-map)) (doseq [[k v] metadata-map] (when (map? v) (cond (contains? (:flags v) :callable?) (do (ns-unmap ns-symbol (symbol k)) (intern ns-symbol (with-meta (symbol k) v) (fn [inst & args] (apply (get-attr inst k) args)))) (contains? v :value) (do (ns-unmap ns-symbol (symbol k)) (intern ns-symbol (with-meta (symbol k) v) (:value v)))))) ns-symbol) ================================================ FILE: src/libpython_clj2/python/base.clj ================================================ (ns libpython-clj2.python.base "Shared basic functionality and wrapper functions" (:require [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.ffi :as py-ffi] [tech.v3.datatype.ffi :as dt-ffi] [camel-snake-kebab.core :as csk]) (:import [tech.v3.datatype.ffi Pointer])) (defn ->jvm "Copying conversion to the jvm." ([obj] (when-not (nil? obj) (py-proto/->jvm obj nil))) ([obj opts] (when-not (nil? obj) (py-proto/->jvm obj opts)))) (defn as-jvm "Bridge/proxy conversion to the jvm" ([obj] (as-jvm obj nil)) ([obj opts] (when-not (nil? obj) (py-proto/as-jvm obj opts)))) (defn ->python "Copying conversion to python" ([obj] (->python obj nil)) ([obj opts] (cond (nil? obj) (py-ffi/py-none) (boolean? obj) (if obj (py-ffi/py-true) (py-ffi/py-false)) :else (py-proto/->python obj nil)))) (defn ->python-incref [pyobj] (let [pyobj (->python pyobj)] (py-ffi/Py_IncRef pyobj) pyobj)) (defn as-python "Bridge/proxy conversion to python" ([obj] (as-python obj nil)) ([obj opts] (cond (nil? obj) (py-ffi/py-none) (boolean? obj) (if obj (py-ffi/py-true) (py-ffi/py-false)) :else (py-proto/as-python obj nil)))) (defn stringable? [item] (or (keyword? item) (string? item) (symbol? item))) (defn stringable ^String [item] (when (stringable? item) (if (string? item) item (name item)))) ;;base defaults for forwarding calls (extend-type Object py-proto/PCopyToJVM (->jvm [item options] (if (py-ffi/convertible-to-pointer? item) (py-proto/pyobject->jvm item options) ;;item is already a jvm object item)) py-proto/PBridgeToJVM (as-jvm [item options] (if (py-ffi/convertible-to-pointer? item) (py-proto/pyobject-as-jvm item options) item)) py-proto/PPyCallable (callable? [this] false) py-proto/PPyAttr (has-attr? [this attr-name] false) py-proto/PPyItem (has-item? [this item-name] false) py-proto/PPyDir (dir [this] [])) (extend-protocol py-proto/PPythonType Boolean (get-python-type [item] :bool) Number (get-python-type [item] (if (integer? item) :int :float)) String (get-python-type [item] :str) Object (get-python-type [item] (py-ffi/pyobject-type-kwd item))) (extend-type Pointer py-proto/PCopyToJVM (->jvm [item options] (py-proto/pyobject->jvm item options)) py-proto/PBridgeToJVM (as-jvm [item options] (py-proto/pyobject-as-jvm item options)) py-proto/PPyDir (dir [item] (py-ffi/with-decref [dirlist (py-ffi/PyObject_Dir item)] (if dirlist (->jvm dirlist) (py-ffi/check-error-throw)))) py-proto/PPyAttr (has-attr? [item item-name] (if (stringable? item-name) (= 1 (py-ffi/PyObject_HasAttrString item (stringable item-name))) (= 1 (py-ffi/PyObject_HasAttr item (->python item-name nil))))) (get-attr [item item-name] (-> (if (stringable? item-name) (py-ffi/PyObject_GetAttrString item (stringable item-name)) (py-ffi/with-decref [item-name (py-ffi/untracked->python item-name ->python)] (py-ffi/PyObject_GetAttr item item-name))) (py-ffi/simplify-or-track))) (set-attr! [item item-name item-value] (let [item-val (->python item-value)] (if (stringable? item-name) (py-ffi/PyObject_SetAttrString item (stringable item-name) item-val) (py-ffi/PyObject_SetAttr item (->python item-name) item-val))) (py-ffi/check-error-throw) nil) py-proto/PPyCallable (callable? [item] (== 1 (long (py-ffi/PyCallable_Check item)))) py-proto/PPyItem (has-item? [item item-name] (if (stringable? item-name) (= 1 (py-ffi/PyObject_HasAttrString item (stringable item-name))) (= 1 (py-ffi/PyObject_HasAttr item (->python item-name))))) (get-item [item item-name] (py-ffi/with-decref [item-name (py-ffi/untracked->python item-name ->python)] (-> (py-ffi/PyObject_GetItem item item-name) (py-ffi/simplify-or-track)))) (set-item! [item item-name item-value] (py-ffi/with-decref [item-name (py-ffi/untracked->python item-name ->python) item-val (py-ffi/untracked->python item-value ->python)] (py-ffi/PyObject_SetItem item item-name item-val) (py-ffi/check-error-throw)) nil)) (def bool-fn-table (->> {"Py_LT" 0 "Py_LE" 1 "Py_EQ" 2 "Py_NE" 3 "Py_GT" 4 "Py_GE" 5} (map (fn [[k v]] [(csk/->kebab-case-keyword k) v])) (into {}))) (defn hash-code ^long [py-inst] (py-ffi/with-gil (long (py-ffi/PyObject_Hash py-inst)))) (defn equals? "Returns true of the python equals operator returns 1." [lhs rhs] (py-ffi/with-gil (= 1 (py-ffi/PyObject_RichCompareBool (->python lhs) (->python rhs) (bool-fn-table :py-eq))))) ================================================ FILE: src/libpython_clj2/python/bridge_as_jvm.clj ================================================ (ns libpython-clj2.python.bridge-as-jvm "Functionality related to proxying python objects such that they interact natively with the JVM -- Python dicts become java.util.Maps, for instance." (:require [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.copy :as py-copy] [libpython-clj2.python.fn :as py-fn] [libpython-clj2.python.ffi :refer [with-gil] :as py-ffi] [libpython-clj2.python.gc :as pygc] [tech.v3.datatype :as dtype] [tech.v3.datatype.protocols :as dt-proto] [tech.v3.datatype.errors :as errors] [tech.v3.datatype.ffi :as dt-ffi] [clojure.core.protocols :as clj-proto]) (:import [java.util Map Set] [clojure.lang IFn MapEntry Fn] [tech.v3.datatype.ffi Pointer] [tech.v3.datatype ObjectBuffer] [libpython_clj2.python.protocols PBridgeToPython])) (extend-protocol py-proto/PBridgeToJVM Pointer (as-jvm [ptr opts] (py-proto/pyobject-as-jvm ptr opts))) (defmethod py-proto/pyobject-as-jvm :int [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :float [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :int-8 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :uint-8 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :int-16 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :uint-16 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :int-32 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :uint-32 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :int-64 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :uint-64 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :float-64 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :float-32 [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :str [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :bool [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defmethod py-proto/pyobject-as-jvm :range [pyobj & [opts]] (py-base/->jvm pyobj opts)) (defn python->jvm-iterator "This is a tough function to get right. The iterator could return nil as in you could have a list of python none types or something so you have to iterate till you get a StopIteration error. If item-conversion-fn is nil, returns the raw fn output. Else calls item-conversion-fn." [pyobj item-conversion-fn] (with-gil (let [py-iter (py-fn/call-attr pyobj "__iter__" nil) py-next-fn (when py-iter (py-proto/get-attr py-iter "__next__")) next-fn (fn [last-item] (when (= last-item ::iteration-finished) (errors/throw-iterator-past-end)) (with-gil (let [retval (py-ffi/PyObject_CallObject py-next-fn nil)] (if (and (nil? retval) (py-ffi/PyErr_Occurred)) (pygc/with-stack-context (let [type (dt-ffi/make-ptr :pointer 0) value (dt-ffi/make-ptr :pointer 0) tb (dt-ffi/make-ptr :pointer 0) _ (py-ffi/PyErr_Fetch type value tb)] (if (= (Pointer. (type 0)) (py-ffi/py-exc-stopiter-type)) (do (py-ffi/Py_DecRef (Pointer. (type 0))) (when-not (== 0 (long (value 0))) (py-ffi/Py_DecRef (Pointer. (value 0)))) (when-not (== 0 (long (tb 0))) (py-ffi/Py_DecRef (Pointer. (tb 0)))) ::iteration-finished) (do (py-ffi/PyErr_Restore (Pointer. (type 0)) (Pointer. (value 0)) (Pointer. (tb 0))) (py-ffi/check-error-throw))))) (if item-conversion-fn (item-conversion-fn (py-ffi/track-pyobject retval)) retval))))) cur-item-store (atom (next-fn nil))] (reify java.util.Iterator (hasNext [obj-iter] (boolean (not= ::iteration-finished @cur-item-store))) (next [obj-iter] (-> (swap-vals! cur-item-store next-fn) first)))))) (defmacro bridge-pyobject [pyobj & body] `(let [pyobj*# ~pyobj] (with-meta (reify dt-ffi/PToPointer (convertible-to-pointer? [item#] true) (->pointer [item#] (dt-ffi/->pointer @pyobj*#)) py-proto/PPythonType (get-python-type [item] (with-gil (py-proto/get-python-type @pyobj*#))) py-proto/PCopyToPython (py-base/->python [item# options#] @pyobj*#) py-proto/PBridgeToPython (py-base/as-python [item# options#] @pyobj*#) py-proto/PBridgeToJVM (py-base/as-jvm [item# options#] item#) py-proto/PCopyToJVM (->jvm [item# options#] (with-gil (py-base/->jvm @pyobj*# options#))) py-proto/PPyDir (dir [item#] (with-gil (py-proto/dir @pyobj*#))) py-proto/PPyAttr (has-attr? [item# item-name#] (with-gil (py-proto/has-attr? @pyobj*# item-name#))) (get-attr [item# item-name#] (with-gil (-> (py-proto/get-attr @pyobj*# item-name#) (py-base/as-jvm)))) (set-attr! [item# item-name# item-value#] (with-gil (py-ffi/with-decref [item-value# (py-ffi/untracked->python item-value# py-base/->python)] (py-proto/set-attr! @pyobj*# item-name# item-value#)))) py-proto/PPyItem (has-item? [item# item-name#] (with-gil (py-proto/has-item? @pyobj*# item-name#))) (get-item [item# item-name#] (with-gil (-> (py-proto/get-item @pyobj*# item-name#) py-base/as-jvm))) (set-item! [item# item-name# item-value#] (with-gil (py-ffi/with-decref [item-value# (py-ffi/untracked->python item-value# py-base/->python)] (py-proto/set-item! @pyobj*# item-name# item-value#)))) py-proto/PyCall (call [callable# arglist# kw-arg-map#] (with-gil (-> (py-fn/call-py-fn @pyobj*# arglist# kw-arg-map# py-fn/bridged-fn-arg->python) (py-base/as-jvm)))) (marshal-return [callable# retval#] (with-gil (py-base/as-jvm retval#))) clj-proto/Datafiable (datafy [callable#] (with-gil (py-proto/pydatafy callable#))) Object (toString [this#] (with-gil (pygc/with-stack-context (if (= 1 (py-ffi/PyObject_IsInstance @pyobj*# (py-ffi/py-type-type))) (format "%s.%s" (if (py-proto/has-attr? @pyobj*# "__module__") (py-base/->jvm (py-proto/get-attr @pyobj*# "__module__")) "__no_module__") (if (py-proto/has-attr? @pyobj*# "__name__") (py-base/->jvm (py-proto/get-attr @pyobj*# "__name__")) "__unnamed__")) (py-base/->jvm (py-fn/call-attr @pyobj*# "__str__" nil)))))) (equals [this# other#] (boolean (when (py-ffi/convertible-to-pointer? other#) (py-base/equals? @pyobj*# other#)))) (hashCode [this#] (.hashCode ^Object (py-base/hash-code this#))) ~@body) {:type :pyobject}))) (defmethod print-method :pyobject [pyobj w] (.write ^java.io.Writer w ^String (.toString ^Object pyobj))) (defn call-impl-fn [fn-name att-map args] (if-let [py-fn* (get att-map fn-name)] ;;laziness is carefully constructed here in order to allow the arguments to ;;be released within the context of the function call during fn.clj call-py-fn. (-> (py-fn/call-py-fn @py-fn* args nil py-fn/bridged-fn-arg->python) (py-base/as-jvm)) (throw (UnsupportedOperationException. (format "Python object has no attribute: %s" fn-name))))) (defn- make-dict-att-map-delay [pyobj* attnames] (delay (let [dict-atts (set attnames) gc-ctx (pygc/gc-context)] (->> (py-proto/dir @pyobj*) (filter dict-atts) (map (juxt identity #(delay (pygc/with-gc-context gc-ctx (py-proto/get-attr @pyobj* %))))) (into {}))))) (defn make-instance-pycall [pyobj* attnames] (let [dict-att-map* (make-dict-att-map-delay pyobj* attnames)] (fn [fn-name & args] (py-ffi/with-gil (call-impl-fn fn-name @dict-att-map* args))))) (defn generic-python-as-map [pyobj*] (let [py-call (make-instance-pycall pyobj* #{"__len__" "__getitem__" "__setitem__" "__iter__" "__contains__" "__eq__" "__hash__" "clear" "keys" "values" "__delitem__"})] (bridge-pyobject pyobj* Map (clear [item] (py-call "clear")) (containsKey [item k] (boolean (py-call "__contains__" k))) (entrySet [this] (py-ffi/with-gil (->> (.iterator this) iterator-seq set))) (get [this obj-key] ;;Specifically return nil to match java map expectations ;;and thus allow destructuring. (when (py-call "__contains__" obj-key) (py-call "__getitem__" obj-key))) (getOrDefault [item obj-key obj-default-value] (if (.containsKey item obj-key) (.get item obj-key) obj-default-value)) (isEmpty [this] (= 0 (.size this))) (keySet [this] (->> (py-call "keys") set)) (put [this k v] (py-call "__setitem__" k v)) (remove [this k] (py-call "__delitem__" k)) (size [this] (int (py-call "__len__"))) (values [this] (py-ffi/with-gil (-> (py-call "values") (vec)))) Iterable (iterator [this] (let [mapentry-seq (->> (python->jvm-iterator @pyobj* nil) iterator-seq (map (fn [pyobj-key] (with-gil (let [k (py-base/as-jvm pyobj-key) v (.get this pyobj-key) retval (MapEntry. k v)] retval)))))] (.iterator ^Iterable mapentry-seq))) IFn (invoke [this arg] (.getOrDefault this arg nil)) (applyTo [this arglist] (let [arglist (vec arglist)] (case (count arglist) 1 (.get this (first arglist)))))))) (defmethod py-proto/pyobject-as-jvm :dict [pyobj & [opts]] (generic-python-as-map (delay pyobj))) (defn generic-python-as-list [pyobj*] (let [py-call (make-instance-pycall pyobj* #{"__len__" "__getitem__" "__setitem__" "__iter__" "__contains__" "__eq__" "__hash__" "clear" "insert" "pop" "append" "__delitem__" "sort"})] (bridge-pyobject pyobj* ObjectBuffer (lsize [reader] (long (py-call "__len__"))) (readObject [reader idx] (py-call "__getitem__" idx)) (sort [reader obj-com] (when-not (= nil obj-com) (throw (ex-info "Python lists do not support comparators" {}))) (py-call "sort")) (writeObject [writer idx value] (py-call "__setitem__" idx value)) (remove [writer ^int idx] (py-call "__delitem__" idx) true) (add [mutable idx value] (py-call "insert" idx value) true) (add [mutable value] (.add mutable (.size mutable) value) true)))) (defmethod py-proto/pyobject-as-jvm :list [pyobj & [opts]] (generic-python-as-list (delay pyobj))) (defmethod py-proto/pyobject-as-jvm :tuple [pyobj & [opts]] (generic-python-as-list (delay pyobj))) ;;utility fn to generate IFn arities (defn- emit-args [bodyf varf] (let [argify (fn [n argfn bodyf] (let [raw `[~'this ~@(map #(symbol (str "arg" %)) (range n))]] `~(bodyf (argfn raw))))] (concat (for [i (range 21)] (argify i identity bodyf)) [(argify 21 (fn [xs] `[~@(butlast xs) ~'arg20-obj-array]) varf)]))) ;;Python specific interop wrapper for IFn invocations. (defn- emit-py-args [] (emit-args (fn [args] `(~'invoke [~@args] (py-fn/cfn ~@args))) (fn [args] `(~'invoke [~@args] (apply py-fn/cfn ~@(butlast args) ~(last args)))))) (defmacro bridge-callable-pyobject "Like bridge-pyobject, except it populates the implementation of IFn for us, where all arg permutations are supplied, as well as applyTo, and the function invocation is of the form (invoke [this arg] (with-gil (cfn this arg))). If caller supplies an implementation for clojure.lang.IFn or aliased Fn, the macro will use that instead (allowing more control but requiring caller to specify implementations for all desired arities)." [pyobj* interpreter & body] (let [fn-specs (when-not (some #{'IFn 'clojure.lang.IFn} body) `(~'IFn ~@(emit-py-args) (~'applyTo [~'this ~'arglist] (~'apply py-fn/cfn ~'this ~'arglist))))] `(bridge-pyobject ~pyobj* ~interpreter ~@fn-specs ~@body))) (defn generic-callable-pyobject [pyobj*] (bridge-callable-pyobject pyobj* Iterable (iterator [this] (python->jvm-iterator @pyobj* py-base/as-jvm)) Fn)) (defn generic-pyobject [pyobj*] (bridge-pyobject pyobj* Iterable (iterator [this] (python->jvm-iterator @pyobj* py-base/as-jvm)))) (defn generic-python-as-jvm "Given a generic pyobject, wrap it in a read-only map interface where the keys are the attributes." [pyobj*] (with-gil (if (= :none-type (py-ffi/pyobject-type-kwd @pyobj*)) nil (if (py-proto/callable? @pyobj*) (generic-callable-pyobject pyobj*) (generic-pyobject pyobj*))))) (defmethod py-proto/pyobject-as-jvm :default [pyobj & [opts]] (generic-python-as-jvm (delay pyobj))) ================================================ FILE: src/libpython_clj2/python/bridge_as_python.clj ================================================ (ns libpython-clj2.python.bridge-as-python "Functionality related to proxying JVM objects into Python so for instance a java.util.Map implementation will appear to python as being dict-like." (:require [libpython-clj2.python.ffi :refer [with-gil] :as py-ffi] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.class :as py-class] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.gc :as pygc] [libpython-clj2.python.jvm-handle :as jvm-handle] [tech.v3.datatype.errors :as errors] [tech.v3.datatype :as dtype]) (:import [java.util Map RandomAccess UUID List Iterator] [java.util.concurrent ConcurrentHashMap] [tech.v3.datatype.ffi Pointer] [tech.v3.datatype ObjectBuffer] [clojure.lang Keyword Symbol IFn])) (defn as-python-incref "Convert to python and add a reference. Necessary for return values from functions as python expects a new reference and the as-python pathway ensures the jvm garbage collector also sees the reference." [item] (when-let [retval (py-base/as-python item)] (do (py-ffi/Py_IncRef retval) retval))) (defn- as-tuple-instance-fn [fn-obj & [options]] (py-class/make-tuple-instance-fn fn-obj (merge {:result-converter py-base/as-python :arg-converter identity} options))) (defn self->list ^List [self] (jvm-handle/py-self->jvm-obj self)) (defonce sequence-type* (jvm-handle/py-global-delay (py-ffi/with-gil (py-ffi/with-decref [mod (py-ffi/PyImport_ImportModule "collections.abc") seq-type (py-ffi/PyObject_GetAttrString mod "MutableSequence")] (py-class/create-class "jvm-list-as-python" [seq-type] {"__init__" (py-class/wrapped-jvm-constructor) "__del__" (py-class/wrapped-jvm-destructor) "__contains__" (as-tuple-instance-fn #(.contains (self->list %1) %2)) "__eq__" (as-tuple-instance-fn #(.equals (self->list %1) (py-base/->jvm %2))) "__getitem__" (as-tuple-instance-fn #(.get (self->list %1) (int (py-base/->jvm %2)))) "__setitem__" (as-tuple-instance-fn #(.set (self->list %1) (int (py-base/->jvm %2)) (py-base/as-jvm %3))) "__delitem__" (as-tuple-instance-fn #(.remove (self->list %1) (int (py-base/->jvm %2)))) "__hash__" (as-tuple-instance-fn #(.hashCode (self->list %1))) "__iter__" (as-tuple-instance-fn #(.iterator (self->list %1))) "__len__" (as-tuple-instance-fn #(.size (self->list %1))) "__str__" (as-tuple-instance-fn #(.toString (self->list %1))) "clear" (as-tuple-instance-fn #(.clear (self->list %1))) "sort" (as-tuple-instance-fn #(.sort (self->list %1) nil)) "append" (as-tuple-instance-fn #(.add (self->list %1) %2)) "insert" (as-tuple-instance-fn #(.add (self->list %1) (int (py-base/->jvm %2)) %3)) "pop" (as-tuple-instance-fn (fn [self & args] (let [jvm-data (self->list self) args (map py-base/->jvm args) index (int (if (first args) (first args) -1)) index (if (< index 0) (- (.size jvm-data) index) index)] #(.remove jvm-data index))))}))))) (defn list-as-python [item] (let [list-data (if (instance? List item) item (dtype/->buffer item)) hdl (jvm-handle/make-jvm-object-handle list-data)] (@sequence-type* hdl))) (defmethod py-proto/pyobject->jvm :jvm-list-as-python [pyobj opt] (jvm-handle/py-self->jvm-obj pyobj)) (defn self->map ^Map [self] (jvm-handle/py-self->jvm-obj self)) (defonce mapping-type* (jvm-handle/py-global-delay (with-gil (py-ffi/with-decref [mod (py-ffi/PyImport_ImportModule "collections.abc") map-type (py-ffi/PyObject_GetAttrString mod "MutableMapping")] ;;In order to make things work ingeneral (py-class/create-class "jvm-map-as-python" [map-type] {"__init__" (py-class/wrapped-jvm-constructor) "__del__" (py-class/wrapped-jvm-destructor) "__contains__" (as-tuple-instance-fn #(.containsKey (self->map %1) (py-base/as-jvm %2))) "__eq__" (as-tuple-instance-fn #(.equals (self->map %1) (py-base/as-jvm %2))) "__getitem__" (as-tuple-instance-fn #(.get (self->map %1) (py-base/as-jvm %2))) "__setitem__" (as-tuple-instance-fn #(.put (self->map %1) (py-base/as-jvm %2) %3)) "__delitem__" (as-tuple-instance-fn #(.remove (self->map %1) (py-base/as-jvm %2))) "__hash__" (as-tuple-instance-fn #(.hashCode (self->map %1))) "__iter__" (as-tuple-instance-fn #(.iterator ^Iterable (or (keys (self->map %1)) []))) "__len__" (as-tuple-instance-fn #(.size (self->map %1))) "__str__" (as-tuple-instance-fn #(.toString (self->map %1))) "clear" (as-tuple-instance-fn #(.clear (self->map %1))) "keys" (as-tuple-instance-fn #(seq (.keySet (self->map %1)))) "values" (as-tuple-instance-fn #(seq (.values (self->map %1)))) "pop" (as-tuple-instance-fn #(.remove (self->map %1) (py-base/as-jvm %2)))}))))) (defn map-as-python [^Map jvm-data] (errors/when-not-errorf (instance? Map jvm-data) "arg (%s) is not an instance of Map" (type jvm-data)) (@mapping-type* (jvm-handle/make-jvm-object-handle jvm-data))) (defmethod py-proto/pyobject->jvm :jvm-map-as-python [pyobj opt] (jvm-handle/py-self->jvm-obj pyobj)) (def iterable-type* (jvm-handle/py-global-delay (py-ffi/with-gil (py-ffi/with-decref [mod (py-ffi/PyImport_ImportModule "collections.abc") iter-base-cls (py-ffi/PyObject_GetAttrString mod "Iterable")] (py-class/create-class "jvm-iterable-as-python" [iter-base-cls] {"__init__" (py-class/wrapped-jvm-constructor) "__del__" (py-class/wrapped-jvm-destructor) "__iter__" (as-tuple-instance-fn #(.iterator ^Iterable (jvm-handle/py-self->jvm-obj %)) {:name "__iter__"}) "__eq__" (as-tuple-instance-fn #(.equals (jvm-handle/py-self->jvm-obj %1) (py-base/as-jvm %2)) {:name "__eq__"}) "__hash__" (as-tuple-instance-fn #(.hashCode (jvm-handle/py-self->jvm-obj %)) {:name "__hash__"}) "__str__" (as-tuple-instance-fn #(.toString (jvm-handle/py-self->jvm-obj %)) {:name "__str__"})}))))) (defn iterable-as-python [^Iterable jvm-data] (errors/when-not-errorf (instance? Iterable jvm-data) "Argument (%s) is not an instance of Iterable" (type jvm-data)) (@iterable-type* (jvm-handle/make-jvm-object-handle jvm-data))) (defmethod py-proto/pyobject->jvm :jvm-iterable-as-python [pyobj opt] (jvm-handle/py-self->jvm-obj pyobj)) (def iterator-type* (jvm-handle/py-global-delay (py-ffi/with-gil (let [mod (py-ffi/PyImport_ImportModule "collections.abc") iter-base-cls (py-ffi/PyObject_GetAttrString mod "Iterator") next-fn (fn [self] (let [^Iterator item (jvm-handle/py-self->jvm-obj self)] (if (.hasNext item) (pygc/with-stack-context (py-ffi/untracked->python (.next item) py-base/as-python)) (do (py-ffi/PyErr_SetNone (py-ffi/py-exc-stopiter-type)) nil))))] (py-class/create-class "jvm-iterator-as-python" [iter-base-cls] {"__init__" (py-class/wrapped-jvm-constructor) "__del__" (py-class/wrapped-jvm-destructor) "__next__" (py-class/make-tuple-instance-fn next-fn ;;In this case we are explicitly taking care of all conversions ;;to python and back so we do not ask for any converters. {:arg-converter nil :result-converter nil})}))))) (defn iterator-as-python [^Iterator jvm-data] (errors/when-not-errorf (instance? Iterator jvm-data) "Argument (%s) is not a java Iterator" (type jvm-data)) (@iterator-type* (jvm-handle/make-jvm-object-handle jvm-data))) (defmethod py-proto/pyobject->jvm :jvm-iterator-as-python [pyobj opt] (jvm-handle/py-self->jvm-obj pyobj)) (extend-protocol py-proto/PBridgeToPython ;;already bridged! Pointer (as-python [item opts] item) Boolean (as-python [item opts] (py-proto/->python item opts)) Number (as-python [item opts] (py-proto/->python item opts)) String (as-python [item opts] (py-proto/->python item opts)) Keyword (as-python [item opts] (py-proto/->python item opts)) Symbol (as-python [item opts] (py-proto/->python item opts)) Object (as-python [item opts] (cond (instance? Map item) (map-as-python item) (dtype/reader? item) (list-as-python item) (instance? IFn item) (py-class/wrap-ifn item) (instance? Iterable item) (iterable-as-python item) (instance? Iterator item) (iterator-as-python item) :else (errors/throwf "Enable to bridge type %s" (type item))))) ================================================ FILE: src/libpython_clj2/python/class.clj ================================================ (ns libpython-clj2.python.class "Namespace to help create a new python class from Clojure. Used as a core implementation technique for bridging JVM objects into python." (:require [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.jvm-handle :as jvm-handle] [libpython-clj2.python.fn :as py-fn] [libpython-clj2.python.protocols :as py-proto] [tech.v3.datatype.errors :as errors]) (:import [clojure.lang IFn])) (defn py-fn->instance-fn "Given a python callable, return an instance function meant to be used in class definitions." [py-fn] (py-ffi/check-gil) (let [retval (-> (py-ffi/PyInstanceMethod_New py-fn) (py-ffi/track-pyobject))] retval)) (defn make-tuple-instance-fn "Make an instance function - a function which will be passed the 'this' object as it's first argument. In this case the default behavior is to pass raw python object ptr args to the clojure function without marshalling as that can add confusion and unnecessary overhead. Self will be the first argument. Callers can change this behavior by setting the 'arg-converter' option as in 'make-tuple-fn'. See options to [[libpython-clj2.python/make-callable]]." ([clj-fn & [{:keys [arg-converter] :or {arg-converter py-base/as-jvm} :as options}]] (py-ffi/with-gil ;;Explicity set arg-converter to override make-tuple-fn's default ;;->jvm arg-converter. (-> (py-fn/make-tuple-fn clj-fn (assoc options :arg-converter arg-converter)) ;;Mark this as an instance function. (py-fn->instance-fn))))) (defn make-kw-instance-fn "Make an instance function - a function which will be passed the 'this' object as it's first argument. In this case the default behavior is to pass as-jvm bridged python object ptr args and kw dict args to the clojure function without marshalling. Self will be the first argument of the arg vector. See options to [[libpython-clj2.python/make-callable]]. Options: * `:arg-converter` - gets one argument and must convert into jvm space - defaults to as-jvm. * `:result-converter` - gets one argument and must convert to python space. Has reasonable default." ([clj-fn & [{:keys [arg-converter result-converter] :or {arg-converter py-base/as-jvm} :as options}]] (let [options (assoc options :arg-converter arg-converter) result-converter (or result-converter #(py-fn/bridged-fn-arg->python % options))] (py-ffi/with-gil ;;Explicity set arg-converter to override make-tuple-fn's default ;;->jvm arg-converter. (-> (py-fn/make-kw-fn clj-fn (assoc options :result-converter result-converter)) ;;Mark this as an instance function. (py-fn->instance-fn)))))) (defn create-class "Create a new class object. Any callable values in the cls-hashmap will be presented as instance methods. Things in the cls hashmap had better be either atoms or already converted python objects. You may get surprised otherwise; you have been warned. See the classes-test file in test/libpython-clj. Calling `super.init()` may be done in a non-obvious way: ```clojure (py. (py/get-item (py.. self -__class__ -__mro__) 1) __init__ self) ``` More feedback/research in this area is needed to integrated deeper into the python class hierarchies." [name bases cls-hashmap] (py-ffi/with-gil (py-ffi/with-decref [cls-dict (py-ffi/untracked-dict cls-hashmap py-base/->python) bases (py-ffi/untracked-tuple bases py-base/->python)] (-> (py-fn/call (py-ffi/py-type-type) name bases cls-dict) (py-base/as-jvm))))) (def ^:private wrapped-jvm-destructor* (jvm-handle/py-global-delay (make-tuple-instance-fn (fn [self] (let [jvm-hdl (jvm-handle/py-self->jvm-handle self)] #_(log/debugf "Deleting bridged handle %d" jvm-hdl) (jvm-handle/remove-jvm-object jvm-hdl) nil))))) (defn ^:no-doc wrapped-jvm-destructor [] @wrapped-jvm-destructor*) (def ^:private wrapped-jvm-constructor* (jvm-handle/py-global-delay (make-tuple-instance-fn jvm-handle/py-self-set-jvm-handle!))) (defn ^:no-doc wrapped-jvm-constructor [] @wrapped-jvm-constructor*) (def ^:no-doc abc-callable-type* (jvm-handle/py-global-delay (py-ffi/with-decref [mod (py-ffi/PyImport_ImportModule "collections.abc")] (py-proto/get-attr mod "Callable")))) (def ^:no-doc wrapped-fn-class* (jvm-handle/py-global-delay (create-class "LibPythonCLJWrappedFn" [@abc-callable-type*] {"__init__" (wrapped-jvm-constructor) "__del__" (wrapped-jvm-destructor) "__call__" (make-tuple-instance-fn (fn [self & args] (let [jvm-obj (jvm-handle/py-self->jvm-obj self)] (-> (apply jvm-obj (map py-base/as-jvm args)) (py-ffi/untracked->python py-base/as-python))))) "__str__" (make-tuple-instance-fn (fn [self] (format "libpython-clj-wrapper[%s]" (.toString (jvm-handle/py-self->jvm-obj self)))))}))) (defn ^:no-doc wrap-ifn [ifn] (errors/when-not-errorf (instance? IFn ifn) "Object %s is not an instance of clojure.lang.IFn" ifn) (@wrapped-fn-class* (jvm-handle/make-jvm-object-handle ifn))) (comment (def cls-obj* ) (@cls-obj* (jvm-handle/make-jvm-object-handle #(println "in python:" %))) (def cls-obj (create-class "Stock" nil {"__init__" (make-tuple-instance-fn (fn init [self name shares price] ;;Because we did not use an arg-converter, all the ;;arguments above are raw jna Pointers - borrowed ;;references. (py-proto/set-attr! self "name" name) (py-proto/set-attr! self "shares" shares) (py-proto/set-attr! self "price" price) ;;If you don't return nil from __init__ that is an ;;error. nil)) "__del__" (wrapped-jvm-destructor) "cost" (make-tuple-instance-fn (fn cost [self] (* (py-proto/get-attr self "shares") (py-proto/get-attr self "price"))) ;;Convert self to something that auto-marshals things. ;;This pathway will autoconvert all arguments to the function. {:arg-converter py-base/as-jvm}) "__str__" (make-tuple-instance-fn (fn str [self] ;;Alternative to using arg-converter. This way you can ;;explicitly control which arguments are converted. (let [self (py-base/as-jvm self)] (pr-str {"name" (py-proto/get-attr self "name") "shares" (py-proto/get-attr self "shares") "price" (py-proto/get-attr self "price")})))) "clsattr" 55})) (def inst (cls-obj "ACME" 50 90)) (py-fn/call-attr inst "cost") ) ================================================ FILE: src/libpython_clj2/python/copy.clj ================================================ (ns libpython-clj2.python.copy "Bindings to copy jvm <-> python. Most functions in this namespace expect the GIL to be captured." (:require [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.gc :as pygc] [tech.v3.datatype :as dtype] [tech.v3.datatype.protocols :as dt-proto] [tech.v3.datatype.ffi :as dt-ffi] [tech.v3.datatype.errors :as errors]) (:import [tech.v3.datatype.ffi Pointer] [java.util Map RandomAccess Set] [clojure.lang Keyword Symbol IFn])) (declare ->py-tuple) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; python -> jvm ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;protocol defaults and wrapper functions (defn python->jvm-copy-hashmap [pyobj & [map-items]] (when-not (= 1 (py-ffi/PyMapping_Check pyobj)) (errors/throwf "Object does not implement the mapping protocol: %s" (py-proto/python-type pyobj))) (when-let [map-items (or map-items (py-ffi/PyMapping_Items pyobj))] (try (->> (py-base/->jvm map-items) (into {})) (finally (py-ffi/Py_DecRef map-items))))) (defn python->jvm-copy-persistent-vector [pyobj] (when-not (= 1 (py-ffi/PySequence_Check pyobj)) (errors/throwf "Object does not implement sequence protocol: %s" (py-proto/python-type pyobj))) ;; Unfortunately sometimes things that pass the sequence check will fail ;; when you request their length. In those cases we return an empty vector ;; as that is what older versions of libpython-clj would do. (try (->> (range (py-ffi/with-error-check (py-ffi/PySequence_Length pyobj))) (mapv (fn [idx] (let [pyitem (py-ffi/PySequence_GetItem pyobj idx)] (try (py-base/->jvm pyitem) (finally (py-ffi/Py_DecRef pyitem))))))) (catch Throwable e []))) (defmethod py-proto/pyobject->jvm :str [pyobj & args] (py-ffi/pystr->str pyobj)) (defmethod py-proto/pyobject->jvm :int [pyobj & args] (py-ffi/PyLong_AsLongLong pyobj)) (defmethod py-proto/pyobject->jvm :float [pyobj & args] (py-ffi/PyFloat_AsDouble pyobj)) (defn pyobj-true? [pyobj] (= 1 (py-ffi/PyObject_IsTrue pyobj))) (defmethod py-proto/pyobject->jvm :bool [pyobj & [options]] (pyobj-true? pyobj)) (defmethod py-proto/pyobject->jvm :tuple [pyobj & [options]] (let [n-elems (py-ffi/PyTuple_Size pyobj)] (mapv (fn [^long idx] (py-base/->jvm (py-ffi/PyTuple_GetItem pyobj idx))) (range n-elems)))) (defmethod py-proto/pyobject->jvm :dict [pyobj & [options]] (let [ppos (dt-ffi/make-ptr :size-t 0) pkey (dt-ffi/make-ptr :pointer 0) pvalue (dt-ffi/make-ptr :pointer 0) retval (java.util.ArrayList.)] ;;Dictionary iteration doesn't appear to be reentrant so we have ;;to do 2 passes. (loop [next-retval (py-ffi/PyDict_Next pyobj ppos pkey pvalue)] (if (not= 0 next-retval) (do (.add retval [(Pointer. (long (pkey 0))) (Pointer. (long (pvalue 0)))]) (recur (py-ffi/PyDict_Next pyobj ppos pkey pvalue))) (->> retval (map (fn [[k v]] [(py-base/->jvm k) (py-base/->jvm v)])) (into {})))))) (defn numpy-scalar->jvm [pyobj] (pygc/with-stack-context (-> (py-proto/get-attr pyobj "data") (py-proto/get-item (->py-tuple [])) py-base/->jvm))) (defmethod py-proto/pyobject->jvm :uint-8 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :int-8 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :uint-16 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :int-16 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :uint-32 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :int-32 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :uint-64 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :int-64 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :float-64 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :float-32 [pyobj & [opts]] (numpy-scalar->jvm pyobj)) (defmethod py-proto/pyobject->jvm :range [pyobj & [opts]] (pygc/with-stack-context (let [start (py-base/->jvm (py-proto/get-attr pyobj "start")) step (py-base/->jvm (py-proto/get-attr pyobj "step")) stop (py-base/->jvm (py-proto/get-attr pyobj "stop"))] (range start stop step)))) (def mapping-exceptions "These types pass PyMapping_Check but cannot be treated as a collection." ;; See github issue#250 #{:generic-alias :union-type}) (defmethod py-proto/pyobject->jvm :default [pyobj & [options]] (let [python-type-keyword (py-ffi/pyobject-type-kwd pyobj)] (cond (= :none-type python-type-keyword) nil ;;Things could implement mapping and sequence logically so mapping ;;takes precedence (and (= 1 (py-ffi/PyMapping_Check pyobj)) (not (mapping-exceptions python-type-keyword))) (do (if-let [map-items (py-ffi/PyMapping_Items pyobj)] (try (python->jvm-copy-hashmap pyobj map-items) (finally (py-ffi/Py_DecRef map-items))) (do ;;Ignore error. The mapping check isn't thorough enough to work for all ;;python objects. (py-ffi/PyErr_Clear) (python->jvm-copy-persistent-vector pyobj)))) ;;Sequences become persistent vectors (= 1 (py-ffi/PySequence_Check pyobj)) (python->jvm-copy-persistent-vector pyobj) :else {:type python-type-keyword ;;Create a new GC root as the old reference is released. :value (let [new-obj (py-ffi/track-pyobject (Pointer. (.address (dt-ffi/->pointer pyobj))))] (py-ffi/Py_IncRef new-obj) new-obj)}))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; jvm -> python ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (def ^:dynamic *item-tuple-cutoff* 8) (defn ->py-tuple [args] (-> (py-ffi/untracked-tuple args py-base/->python) (py-ffi/track-pyobject))) (defn ->py-dict "Copy an object into a new python dictionary." [item] (py-ffi/check-gil) (-> (py-ffi/untracked-dict item py-base/->python) (py-ffi/track-pyobject))) (defn ->py-string "Copy an object into a python string" [item] (-> (py-ffi/PyUnicode_FromString (str item)) (py-ffi/track-pyobject))) (defn ->py-list "Copy an object into a new python list." [item-seq] (py-ffi/check-gil) (let [item-seq (vec item-seq) retval (py-ffi/PyList_New (count item-seq))] (pygc/with-stack-context (dotimes [idx (count item-seq)] (let [si-retval ;;setitem does steal the reference (py-ffi/PyList_SetItem retval idx (py-ffi/untracked->python (item-seq idx) py-base/->python))] (when-not (== 0 (long si-retval)) (py-ffi/check-error-throw))))) (py-ffi/track-pyobject retval))) (defn ->py-set [item] (py-ffi/check-gil) (-> (py-ffi/PySet_New (->py-list item)) (py-ffi/track-pyobject))) (defn ->py-long [item] (py-ffi/track-pyobject (py-ffi/PyLong_FromLongLong (long item)))) (defn ->py-double [item] (py-ffi/track-pyobject (py-ffi/PyFloat_FromDouble (double item)))) (defn ->py-range [item] (let [dt-range (dt-proto/->range item {}) start (long (dt-proto/range-start dt-range)) inc (long (dt-proto/range-increment dt-range)) n-elems (long (dtype/ecount dt-range)) stop (+ start (* inc n-elems)) ;;the tuple steals the references argtuple (py-ffi/untracked-tuple [start stop inc]) retval (py-ffi/PyObject_CallObject (py-ffi/py-range-type) argtuple)] ;;we drop the tuple (py-ffi/Py_DecRef argtuple) ;;and wrap the retval (py-ffi/track-pyobject retval))) (extend-protocol py-proto/PCopyToPython Boolean (->python [item opts] (if item (py-ffi/py-true) (py-ffi/py-false))) Long (->python [item opts] (->py-long item)) Double (->python [item opts] (->py-double item)) Number (->python [item opts] (if (integer? item) (->py-long item) (->py-double item))) String (->python [item ops] (->py-string item)) Keyword (->python [item ops] (->py-string (name item))) Symbol (->python [item ops] (->py-string (name item))) Character (->python [item ops] (->py-string (str item))) Map (->python [item opts] (->py-dict item)) RandomAccess (->python [item opts] (if (< (count item) (long *item-tuple-cutoff*)) (->py-tuple item) (->py-list item))) Set (->python [item opts] (->py-set item)) Pointer (->python [item opts] item) Object (->python [item opts] (cond (dt-proto/convertible-to-range? item) (->py-range item) (dtype/reader? item) (py-proto/->python (dtype/->reader item) opts) ;;There is one more case here for iterables (sequences) (instance? Iterable item) (py-proto/->python (vec item) opts) (instance? IFn item) (py-proto/as-python item opts) :else (errors/throwf "Unable to convert object: %s" item)))) ================================================ FILE: src/libpython_clj2/python/dechunk_map.clj ================================================ (ns libpython-clj2.python.dechunk-map "Utility namespace with a function that works like a single-sequence map but stops chunking.") (defn dechunk-map "Map a function across a sequence without chunking." [f s] (lazy-seq (when-let [[x] (seq s)] (cons (f x) (dechunk-map f (rest s)))))) ================================================ FILE: src/libpython_clj2/python/ffi.clj ================================================ (ns libpython-clj2.python.ffi "Low level bindings to the python shared library system. Several key pieces of functionality are implemented: * Declare/implement actual C binding layer * Low level library initialization * GIL management * Error checking * High perf tuple, dict creation * Addref/decref reference management including tracking objects - binding them to the JVM GC * python type->clojure keyword table" (:require [tech.v3.datatype :as dtype] [tech.v3.datatype.ffi :as dt-ffi] [tech.v3.datatype.ffi.size-t :as ffi-size-t] [tech.v3.datatype.struct :as dt-struct] [tech.v3.datatype.errors :as errors] [tech.v3.datatype.native-buffer :as native-buffer] [tech.v3.datatype.protocols :as dt-proto] [tech.v3.resource :as resource] [libpython-clj2.python.gc :as pygc] [camel-snake-kebab.core :as csk] [clojure.tools.logging :as log] [clojure.string :as s]) (:import [java.util.concurrent ConcurrentHashMap] [java.util.function Function] [tech.v3.datatype.ffi Pointer Library] [clojure.lang Keyword Symbol] [java.nio.charset StandardCharsets])) (set! *warn-on-reflection* true) (declare track-pyobject py-none pystr->str check-error-throw pyobject-type-kwd PyGILState_Check) (def python-library-fns {:Py_InitializeEx {:rettype :void :argtypes [['signals :int32]] :requires-gil? false :doc "Initialize the python shared library"} :Py_IsInitialized {:rettype :int32 :requires-gil? false :doc "Return 1 if library is initalized, 0 otherwise"} :PyRun_SimpleString {:rettype :int32 :argtypes [['argstr :string]] :doc "Low-level run a simple python string."} :PyRun_String {:rettype :pointer :argtypes [['program :string] ['start-sym :int32] ['globals :pointer] ['locals :pointer]] :doc "Run a string setting the start type, globals and locals"} :PySys_SetArgvEx {:rettype :void :argtypes [['argc :int32] ['argv-wide-ptr-ptr :pointer] ['update :int32]] :doc "Set the argv/argc for the interpreter. Required for some python modules"} :Py_SetProgramName {:rettype :void :requires-gil? false :argtypes [['program-name-wideptr :pointer]] :doc "Set the program name"} :Py_SetPythonHome {:rettype :void :requires-gil? false :argtypes [['python-home-wideptr :pointer]] :doc "Set the program name"} :PyEval_SaveThread {:rettype :pointer :requires-gil? false :doc "Release the GIL on the current thread"} :PyEval_RestoreThread {:rettype :void :requires-gil? false :argtypes [['threadstate :pointer]] :doc "Restore the python thread state thread"} :PyGILState_Ensure {:rettype :int32 :requires-gil? false :doc "Ensure this thread owns the python GIL. Each call must be matched with PyGILState_Release"} :PyGILState_Check {:rettype :int32 :requires-gil? false :doc "Return 1 if gil is held, 0 otherwise"} :PyGILState_Release {:rettype :void :argtypes [['modhdl :int32]] :doc "Release the GIL state."} :Py_IncRef {:rettype :void :argtypes [['pyobj :pointer]] :doc "Increment the reference count on a pyobj"} :Py_DecRef {:rettype :void :argtypes [['pyobj :pointer]] :doc "Decrement the reference count on a pyobj"} :PyErr_Occurred {:rettype :pointer :doc "Return the current in-flight exception without clearing it."} :PyErr_Fetch {:rettype :void :argtypes [['type :pointer] ['value :pointer] ['tb :pointer]] :doc "Fetch and clear the current exception information"} :PyErr_Restore {:rettype :void :argtypes [['type :pointer] ['value :pointer?] ['tb :pointer?]] :doc "Restore the current error state"} :PyErr_NormalizeException {:rettype :void :argtypes [['type :pointer] ['value :pointer] ['tb :pointer]] :doc "Normalize a python exception."} :PyErr_Clear {:rettype :void :doc "Clear the current python error"} :PyErr_SetString {:rettype :void :argtypes [['ex-type :pointer] ['data :string]] :doc "Raise an exception with a message"} :PyErr_SetNone {:rettype :void :argtypes [['ex-type :pointer]] :doc "Raise an exception with no message"} :PyException_SetTraceback {:rettype :int32 :argtypes [['val :pointer] ['tb :pointer]] :doc "Set the traceback on the exception object"} :PyUnicode_AsUTF8 {:rettype :pointer :argtypes [['obj :pointer]] :doc "convert a python unicode object to a utf8 encoded string"} :PyUnicode_AsUTF8AndSize {:rettype :pointer :argtypes [['obj :pointer] ['size :pointer]] :doc "Return both the data and the size of the data"} :PyImport_ImportModule {:rettype :pointer :argtypes [['modname :string]] :doc "Import a python module"} :PyImport_AddModule {:rettype :pointer :argtypes [['modname :string]] :doc "Add a python module"} :Py_CompileString {:rettype :pointer :argtypes [['strdata :string] ['filename :string] ['start :int32]]} :PyEval_EvalCode {:rettype :pointer :argtypes [['co :pointer] ['globals :pointer] ['locals :pointer]]} :PyModule_GetDict {:rettype :pointer :argtypes [['module :pointer]] :doc "Get the module dictionary"} :PyObject_Dir {:rettype :pointer :argtypes [['pyobj :pointer]] :doc "Get a python sequence of string attribute names"} :PyObject_HasAttr {:rettype :int32 :argtypes [['o :pointer] ['attr_name :pointer]] :doc "Return 1 if object has an attribute"} :PyObject_HasAttrString {:rettype :int32 :argtypes [['o :pointer] ['attr_name :string]] :doc "Return 1 if object has an attribute"} :PyObject_GetAttr {:rettype :pointer :argtypes [['o :pointer] ['attr_name :pointer]] :doc "get an attribute from an object"} :PyObject_GetAttrString {:rettype :pointer :argtypes [['o :pointer] ['attr_name :string]] :doc "get an attribute from an object"} :PyObject_SetAttrString {:rettype :int32 :argtypes [['o :pointer] ['attr_name :string] ['v :pointer]]} :PyObject_SetAttr {:rettype :int32 :argtypes [['o :pointer] ['attr_name :pointer] ['v :pointer]] :doc "Set an attribute on a python object"} :PyObject_GetItem {:rettype :pointer :argtypes [['o :pointer] ['args :pointer]] :doc "Get an item from a python object"} :PyObject_SetItem {:rettype :int32 :argtypes [['o :pointer] ['args :pointer] ['val :pointer]] :doc "Set an item on a python object"} :PyObject_IsTrue {:rettype :int32 :argtypes [['o :pointer]] :doc "Check if a python object is true"} :PyObject_IsInstance {:rettype :int32 :argtypes [['inst :pointer] ['cls :pointer]] :doc "Check if this object is an instance of this class"} :PyObject_Hash {:rettype :size-t :argtypes [['o :pointer]] :doc "Get the hash value of a python object"} :PyObject_RichCompareBool {:rettype :int32 :argtypes [['lhs :pointer] ['rhs :pointer] ['opid :int32]] :doc "Compare two python objects"} :PyCallable_Check {:rettype :int32 :argtypes [['o :pointer]] :doc "Return 1 if this is a callable object"} :PyObject_Call {:rettype :pointer :argtypes [['callable :pointer] ['args :pointer] ['kwargs :pointer?]] :doc "Call a callable object"} :PyObject_CallObject {:rettype :pointer :argtypes [['callable :pointer] ['args :pointer?]] :doc "Call a callable object with no kwargs. args may be nil"} :PyMapping_Check {:rettype :int32 :argtypes [['pyobj :pointer]] :doc "Check if this object implements the mapping protocol"} :PyMapping_Items {:rettype :pointer :argtypes [['pyobj :pointer]] :doc "Get an iterable of tuples of this map."} :PySequence_Check {:rettype :int32 :argtypes [['pyobj :pointer]] :doc "Check if this object implements the sequence protocol"} :PySequence_Length {:rettype :size-t :argtypes [['pyobj :pointer]] :doc "Get the length of a sequence"} :PySequence_GetItem {:rettype :pointer :argtypes [['pyobj :pointer] ['idx :size-t]] :doc "Get a specific item from a sequence"} :PyFloat_AsDouble {:rettype :float64 :argtypes [['pyobj :pointer]] :doc "Get a double value from a python float"} :PyFloat_FromDouble {:rettype :pointer :argtypes [['data :float64]] :doc "Get a pyobject form a long."} :PyLong_AsLongLong {:rettype :int64 :argtypes [['pyobj :pointer]] :doc "Get the long value from a python integer"} :PyLong_AsUnsignedLongLongMask {:rettype :int64 :argtypes [['pyobj :pointer]] :doc "Get the unsigned long value from a python integer with no overflow checking"} :PyLong_FromLongLong {:rettype :pointer :argtypes [['data :int64]] :doc "Get a pyobject form a long."} :PyDict_New {:rettype :pointer :doc "Create a new dictionary"} :PyDict_SetItem {:rettype :int32 :argtypes [['dict :pointer] ['k :pointer] ['v :pointer]] :doc "Insert val into the dictionary p with a key of key. key must be hashable; if it isn’t, TypeError will be raised. Return 0 on success or -1 on failure. This function does not steal a reference to val."} :PyDict_Next {:rettype :int32 :argtypes [['pyobj :pointer] ['ppos :pointer] ['pkey :pointer] ['pvalue :pointer]] :doc "Get the next value from a dictionary"} :PyTuple_New {:rettype :pointer :argtypes [['len :size-t]] :doc "Create a new uninitialized tuple"} :PyTuple_SetItem {:rettype :int32 :argtypes [['tuple :pointer] ['idx :size-t] ['pvalue :pointer]] :doc "Insert a reference to object o at position pos of the tuple pointed to by p. Return 0 on success. If pos is out of bounds, return -1 and set an IndexError exception."} :PyTuple_Size {:rettype :size-t :argtypes [['o :pointer]] :doc "return the length of a tuple"} :PyTuple_GetItem {:rettype :pointer :argtypes [['o :pointer] ['idx :size-t]] :doc "return a borrowed reference to item at idx"} :PyList_New {:rettype :pointer :argtypes [['len :size-t]] :doc "create a new list"} :PyList_SetItem {:rettype :int32 :argtypes [['l :pointer] ['idx :size-t] ['v :pointer]] :doc "Set the item at index index in list to item. Return 0 on success. If index is out of bounds, return -1 and set an IndexError exception. This function steals the reference to v"} :PyList_Size {:rettype :size-t :argtypes [['o :pointer]] :doc "return the length of a list"} :PyList_GetItem {:rettype :pointer :argtypes [['o :pointer] ['idx :size-t]] :doc "return a borrowed reference to item at idx"} :PySet_New {:rettype :pointer :argtypes [['items :pointer]] :doc "Create a new set"} :PyUnicode_FromString {:rettype :pointer :argtypes [['data :string]] :doc "Create a python unicode object from a string"} :PyCFunction_NewEx {:rettype :pointer :argtypes [['method-def :pointer] ['self :pointer?] ['module :pointer?]]} :PyInstanceMethod_New {:rettype :pointer :argtypes [['pyfn :pointer]] :doc "Mark a python function as being an instance method."} }) (defn define-library! [python-lib-classname] (dt-ffi/define-library python-library-fns ["_Py_NoneStruct" "_Py_FalseStruct" "_Py_TrueStruct" "PyType_Type" "PyExc_StopIteration" "PyRange_Type" "PyExc_Exception"] {:classname python-lib-classname})) (def python-lib-def* (delay (define-library! nil))) (defonce pyobject-struct-type* (delay (dt-struct/define-datatype! :pyobject [{:name :ob_refcnt :datatype (ffi-size-t/size-t-type)} {:name :ob_type :datatype (ffi-size-t/size-t-type)}]))) (defn convertible-to-pointer? "Older definition - excludes Long objects which were made convertible-to-pointer in later versions of dtype-next." [d] (boolean (when-not (instance? Long d) (dt-ffi/convertible-to-pointer? d)))) (defn pytype-offset ^long [] (first (dt-struct/offset-of @pyobject-struct-type* :ob_type))) (defn pyrefcnt-offset ^long [] (first (dt-struct/offset-of @pyobject-struct-type* :ob_refcnt))) (defn ptr->struct [struct-type ptr-type] (let [n-bytes (:datatype-size (dt-struct/get-struct-def struct-type)) src-ptr (dt-ffi/->pointer ptr-type) nbuf (native-buffer/wrap-address (.address src-ptr) n-bytes src-ptr)] (dt-struct/inplace-new-struct struct-type nbuf))) (defonce ^:private library* (atom nil)) (defonce ^:private library-path* (atom nil)) (defn reset-library! [& [library-definition]] (when @library-path* (reset! library* (dt-ffi/instantiate-library (or library-definition @python-lib-def*) (:libpath @library-path*))))) (defn set-library! [libpath & [library-definition]] (when @library* (log/warnf "Python library is being reinitialized to (%s). Is this what you want?" libpath)) (reset! library-path* {:libpath libpath}) (reset-library! library-definition)) ;;Useful for repling around - this regenerates the library function bindings (reset-library!) (defn library-loaded? [] (not (nil? @library*))) (defn current-library ^Library [] @library*) (def manual-gil (= "true" (System/getProperty "libpython_clj.manual_gil"))) (defmacro check-gil "Maybe the most important insurance policy" [] (when-not manual-gil `(errors/when-not-error (= 1 (PyGILState_Check)) "GIL is not captured"))) ;;When this is true, generated functions will throw an exception if called when the ;;GIL is not captured. It makes sense to periodically enable this flag in order ;;to ensure we aren't getting away with sneaky non-GIL access to Python. (def enable-api-gilcheck* (atom false)) (defn enable-gil-check! ([] (reset! enable-api-gilcheck* true)) ([value] (reset! enable-api-gilcheck* (boolean value)))) (defn- find-pylib-fn [fn-kwd] (let [pylib @library*] (errors/when-not-error pylib "Library not found. Has set-library! been called?") (if-let [retval (fn-kwd @pylib)] retval (errors/throwf "Python function %s not found" (symbol (name fn-kwd)))))) (defmacro def-py-fn [fn-name docs & args] (let [fn-kwd (keyword (name fn-name))] (errors/when-not-errorf (contains? python-library-fns fn-kwd) "Python function %s is not defined" fn-name) `(defn ~fn-name ~docs ~(vec (map first args)) (let [retval# (resource/stack-resource-context ((find-pylib-fn ~fn-kwd) ~@(map (fn [[argname marshal-fn]] `(~marshal-fn ~argname)) args)))])))) (defmacro define-pylib-functions [] `(do ~@(->> python-library-fns (map (fn [[fn-name {:keys [rettype argtypes] :as fn-data}]] (let [fn-symbol (symbol (name fn-name)) requires-resctx? (first (filter #(= :string %) (map second argtypes))) gilcheck? (when @enable-api-gilcheck* (if (contains? fn-data :requires-gil?) (fn-data :requires-gil?) true))] `(defn ~fn-symbol ~(:doc fn-data "No documentation!") ~(mapv first argtypes) (let [~'ifn (find-pylib-fn ~fn-name)] (do ~(when gilcheck? `(check-gil)) ~(if requires-resctx? `(resource/stack-resource-context (~'ifn ~@(map (fn [[argname argtype]] (cond (#{:int8 :int16 :int32 :int64} argtype) `(long ~argname) (#{:float32 :float64} argtype) `(double ~argname) (= :string argtype) `(dt-ffi/string->c ~argname) :else argname)) argtypes))) `(~'ifn ~@(map (fn [[argname argtype]] (cond (#{:int8 :int16 :int32 :int64} argtype) `(long ~argname) (#{:float32 :float64} argtype) `(double ~argname) (= :string argtype) `(dt-ffi/string->c ~argname) :else argname)) argtypes)))))))))))) (define-pylib-functions) (defn- deref-ptr-ptr ^Pointer [^Pointer val] (Pointer. (case (ffi-size-t/offset-t-type) :int32 (.getInt (native-buffer/unsafe) (.address val)) :int64 (.getLong (native-buffer/unsafe) (.address val))))) (defmacro define-static-symbol [symbol-fn symbol-name deref-ptr?] (let [sym-delay-name (with-meta (symbol (str symbol-fn "*")) {:doc (format "Dereferences to the value of %s" symbol-name) :private true})] `(do (def ~sym-delay-name (delay (.findSymbol (current-library) ~symbol-name))) ~(if deref-ptr? `(defn ~symbol-fn [] (deref-ptr-ptr (deref ~sym-delay-name))) `(defn ~symbol-fn [] (deref ~sym-delay-name)))))) (define-static-symbol py-none "_Py_NoneStruct" false) (define-static-symbol py-true "_Py_TrueStruct" false) (define-static-symbol py-false "_Py_FalseStruct" false) (define-static-symbol py-range-type "PyRange_Type" false) (define-static-symbol py-exc-type "PyExc_Exception" true) (define-static-symbol py-exc-stopiter-type "PyExc_StopIteration" true) (define-static-symbol py-type-type "PyType_Type" false) (defmacro with-decref [vardefs & body] (let [n-vars (count vardefs)] (if (= 2 n-vars) `(let ~vardefs (try ~@body (finally (when ~(first vardefs) (Py_DecRef ~(first vardefs)))))) `(let [~'obj-data (object-array ~n-vars)] (try (let [~@(mapcat (fn [[idx [varsym varform]]] [varsym `(let [vardata# ~varform] (aset ~'obj-data ~idx vardata#) vardata#)]) (map-indexed vector (partition 2 vardefs)))] ~@body) (finally (check-gil) (dotimes [idx# ~n-vars] (when-let [pyobj# (aget ~'obj-data idx#)] (Py_DecRef pyobj#))))))))) (defn incref "Increment the refcount returning object. Legal to call on nil, will not incref item and return nil." [pyobj] (when pyobj (Py_IncRef pyobj)) pyobj) (defonce ^{:tag ConcurrentHashMap :private true} forever-map (ConcurrentHashMap.)) (defn retain-forever [item-key item-val] (.put forever-map item-key item-val) item-val) (defonce format-exc-pyfn* (atom nil)) (defn- init-exc-formatter [] (check-gil) (let [tback-mod (PyImport_ImportModule "traceback") format-fn (PyObject_GetAttrString tback-mod "format_exception")] ;;the tback module cannot be removed from memory and it always has a reference ;;to format-fn so we drop our reference. (Py_DecRef tback-mod) (Py_DecRef format-fn) (reset! format-exc-pyfn* format-fn))) (defn- exc-formatter [] (when-not @format-exc-pyfn* (init-exc-formatter)) @format-exc-pyfn*) (defn append-java-library-path! [new-search-path] (let [existing-paths (-> (System/getProperty "java.library.path") (s/split #":"))] (when-not (contains? (set existing-paths) new-search-path) (let [new-path-str (s/join ":" (concat [new-search-path] existing-paths))] (System/setProperty "java.library.path" new-path-str))))) (defn initialize! [libpath python-home & [{:keys [signals? program-name python-home library-definition] :or {signals? true program-name ""} :as opts}]] (set-library! libpath library-definition) (when-not (= 1 (Py_IsInitialized)) (log/debug "Initializing Python C Layer") ;;platform specific encoding (let [encoding-options {:encoding :wchar-t} program-name (retain-forever :program-name (-> (or program-name "") (dt-ffi/string->c encoding-options)))] (Py_SetProgramName program-name) (when python-home (let [python-home (retain-forever :python-home (dt-ffi/string->c python-home encoding-options))] (log/debugf "Python Home: %s" (:python-home opts)) (Py_SetPythonHome python-home))) (Py_InitializeEx (if signals? 1 0)) (PySys_SetArgvEx 0 program-name 1) ;;return value ignored :-) ;;This releases the GIL until further processing and allows with-gil to work ;;correctly. (PyEval_SaveThread))) :ok) (defn untracked->python ^Pointer ([item conversion-fallback] (cond (instance? Pointer item) (-> (if (.isNil ^Pointer item) (py-none) item) (incref)) (instance? Number item) (if (integer? item) (PyLong_FromLongLong (long item)) (PyFloat_FromDouble (double item))) (instance? Boolean item) (-> (if item (py-true) (py-false)) (incref)) (instance? String item) (PyUnicode_FromString item) (instance? Keyword item) (PyUnicode_FromString (name item)) (instance? Symbol item) (PyUnicode_FromString (name item)) (nil? item) (incref (py-none)) :else (if conversion-fallback (incref (conversion-fallback item)) (throw (Exception. (format "Unable to convert value %s" item)))))) ([item] (untracked->python item nil))) (defn untracked-tuple "Low-level make tuple fn. conv-fallback is used when an argument isn't an atomically convertible python type. Returns an untracked python tuple." [args & [conv-fallback]] (check-gil) (let [args (vec args) argcount (count args) tuple (PyTuple_New argcount)] (dotimes [idx argcount] (PyTuple_SetItem tuple idx (untracked->python (args idx) conv-fallback))) tuple)) (defn untracked-dict "Low-level make dict fn. conv-fallback is used when a key or value isn't an atomically convertible python type. Returns an untracked dict." [item-seq & [conv-fallback]] (check-gil) (let [dict (PyDict_New)] (pygc/with-stack-context (doseq [[k v] item-seq] ;;setitem does not steal the reference (let [k (untracked->python k conv-fallback) v (untracked->python v conv-fallback) si-retval (PyDict_SetItem dict k v)] (Py_DecRef k) (Py_DecRef v) (when-not (== (long si-retval) 0) (check-error-throw))))) dict)) (def ^:dynamic *python-error-handler* nil) (defn fetch-normalize-exception [] (check-gil) (resource/stack-resource-context (let [type (dt-ffi/make-ptr :pointer 0) value (dt-ffi/make-ptr :pointer 0) tb (dt-ffi/make-ptr :pointer 0)] (PyErr_Fetch type value tb) (PyErr_NormalizeException type value tb) {:type (Pointer/constructNonZero (type 0)) :value (Pointer/constructNonZero (value 0)) :traceback (Pointer/constructNonZero (tb 0))}))) (defn check-error-str "Function assumes python stdout and stderr have been redirected" [] (check-gil) (when-not (= nil (PyErr_Occurred)) (if *python-error-handler* (*python-error-handler*) (let [{:keys [type value traceback]} (fetch-normalize-exception)] (with-decref [argtuple (untracked-tuple [type value traceback]) exc-str-tuple (PyObject_CallObject (exc-formatter) argtuple)] (case (pyobject-type-kwd exc-str-tuple) :list (->> (range (PyList_Size exc-str-tuple)) (map (fn [idx] (let [strdata (PyList_GetItem exc-str-tuple idx)] (pystr->str strdata)))) (s/join)) :tuple (->> (range (PyTuple_Size exc-str-tuple)) (map (fn [idx] (let [strdata (PyTuple_GetItem exc-str-tuple idx)] (pystr->str strdata)))) (s/join)))))))) (defn check-error-throw [] (when-let [error-str (check-error-str)] (throw (Exception. ^String error-str)))) (defmacro with-error-check [& body] `(let [retval# (do ~@body)] (check-error-throw) retval#)) (defn check-py-method-return [^long retval] (when-not (= 0 retval) (check-error-throw))) (defn ^:no-doc lock-gil ^long [] (if-not (== 1 (unchecked-long (PyGILState_Check))) (PyGILState_Ensure) (Long/MIN_VALUE))) (defn ^:no-doc unlock-gil [^long gilstate] (when-not (== Long/MIN_VALUE gilstate) (when (== 1 gilstate) (pygc/clear-reference-queue)) (PyGILState_Release gilstate))) (defn ^:no-doc manual-gil-locker ^java.lang.AutoCloseable [] (let [gil-state (lock-gil)] (reify java.lang.AutoCloseable (close [this] (unlock-gil gil-state))))) (defmacro with-gil "Grab the gil and use the main interpreter using reentrant acquire-gil pathway." [& body] (if manual-gil `(let [retval# (do ~@body)] (check-error-throw) retval#) `(let [gil-state# (when-not (== 1 (unchecked-long (PyGILState_Check))) (PyGILState_Ensure))] (try (let [retval# (do ~@body)] (check-error-throw) retval#) (finally (when gil-state# #_(System/gc) (pygc/clear-reference-queue) (PyGILState_Release gil-state#))))))) (defn pyobject-type ^Pointer [pobj] (if (= :int32 (ffi-size-t/size-t-type)) (Pointer. (.getInt (native-buffer/unsafe) (+ (.address (dt-ffi/->pointer pobj)) (pytype-offset)))) (Pointer. (.getLong (native-buffer/unsafe) (+ (.address (dt-ffi/->pointer pobj)) (pytype-offset)))))) (defn pyobject-refcount ^long [pobj] (if (= :int32 (ffi-size-t/size-t-type)) (.getInt (native-buffer/unsafe) (+ (.address (dt-ffi/->pointer pobj)) (pyrefcnt-offset))) (.getLong (native-buffer/unsafe) (+ (.address (dt-ffi/->pointer pobj)) (pyrefcnt-offset))))) (defn pystr->str ^String [pyobj] ;;manually allocate/deallocate for speed; this gets called a lot (let [size-obj (dt-ffi/make-ptr :pointer 0 {:resource-type nil :uninitialized? true}) ^Pointer str-ptr (PyUnicode_AsUTF8AndSize pyobj size-obj) nbuf (native-buffer/wrap-address (.address str-ptr) (size-obj 0) nil)] (native-buffer/free size-obj) (native-buffer/native-buffer->string nbuf))) (defn pytype-name ^String [type-pyobj] (with-gil (if-let [obj-name (PyObject_GetAttrString type-pyobj "__name__")] (pystr->str obj-name) (do (log/warn "Failed to get typename for object") "failed-typename-lookup")))) (defonce ^{:tag ConcurrentHashMap} type-addr->typename-kwd (ConcurrentHashMap.)) (defn pyobject-type-kwd [pyobject] (let [pytype (pyobject-type pyobject)] (.computeIfAbsent type-addr->typename-kwd (.address pytype) (reify Function (apply [this type-addr] (-> (pytype-name pytype) (csk/->kebab-case-keyword))))))) (def object-reference-logging (atom nil)) (defn- wrap-obj-ptr "This must be called with the GIL captured" [pyobj ^Pointer pyobjptr gc-data] (let [addr (.address pyobjptr)] (when @object-reference-logging (log/infof "tracking object - 0x%x:%4d:%s" addr (pyobject-refcount pyobj) (name (pyobject-type-kwd pyobjptr)) #_(with-out-str (try (throw (Exception. "test")) "" (catch Exception e (clojure.stacktrace/print-stack-trace e)))))) (pygc/track pyobj ;;we know the GIL is captured in this method #(try ;;Intentionally overshadow pyobj. We cannot access it here. (let [pyobjptr (Pointer. addr) ;;reference gc data gc-data (identity gc-data)] (let [refcount (pyobject-refcount pyobjptr) typename (pyobject-type-kwd pyobjptr)] (if (< refcount 1) (log/errorf "Fatal error -- releasing object - 0x%x:%4d:%s Object's refcount is bad. Crash is imminent" addr refcount typename) (when @object-reference-logging (log/infof (format "releasing object - 0x%x:%4d:%s" addr refcount typename))))) (Py_DecRef pyobjptr)) (catch Throwable e (log/error e "Exception while releasing object")))))) (defn track-pyobject ^Pointer [pyobj & [{:keys [skip-error-check? gc-data]}]] (check-gil) (when-let [^Pointer pyobjptr (when pyobj (dt-ffi/->pointer pyobj))] (if-not (= (py-none) pyobjptr) (wrap-obj-ptr pyobj pyobjptr gc-data) ;;Py_None is handled separately (do (Py_DecRef pyobjptr) (when-not skip-error-check? (check-error-throw)) nil)))) (defn incref-track-pyobject ^Pointer [pyobj] (when pyobj (Py_IncRef pyobj) (track-pyobject pyobj))) (def start-symbol-table {:py-single-input 256 :py-file-input 257 :py-eval-input 258}) (defn start-symbol [item] (let [value (cond (number? item) (long item) (keyword? item) (get start-symbol-table item 0)) valid-values (set (vals start-symbol-table))] (when-not (contains? valid-values value) (throw (ex-info (format "%s is not a start symbol" item) {}))) (int value))) (defn import-module [modname] (if-let [mod (PyImport_ImportModule modname)] (track-pyobject mod) (check-error-throw))) (defn run-simple-string "Run a simple string. Results are only visible if they are saved in the global or local context. https://mail.python.org/pipermail/python-list/1999-April/018011.html Implemented in cpython as: PyObject *m, *d, *v; m = PyImport_AddModule(\"__main__\"); if (m == NULL) return -1; d = PyModule_GetDict(m); v = PyRun_StringFlags(command, Py_file_input, d, d, flags); if (v == NULL) { PyErr_Print(); return -1; } Py_DECREF(v); return 0;" [program & {:keys [globals locals]}] (with-gil ;;borrowed reference (let [main-mod (PyImport_AddModule "__main__") ;;another borrowed reference that we will expose to the user globals (or globals (incref-track-pyobject (PyModule_GetDict main-mod))) locals (or locals globals) retval (track-pyobject (PyRun_String (str program) (start-symbol :py-file-input) globals locals))] {:globals globals :locals locals :retval retval}))) (defn simplify-or-track "If input is an atomic python object (long, float, string, bool), return the JVM equivalent and release the reference to pyobj. Else track the object." [^Pointer pyobj] (if-not (or (nil? pyobj) (.isNil pyobj)) (if (= pyobj (py-none)) (do (Py_DecRef pyobj) nil) (case (pyobject-type-kwd pyobj) :int (with-decref [pyobj pyobj] (PyLong_AsUnsignedLongLongMask pyobj)) :float (with-decref [pyobj pyobj] (PyFloat_AsDouble pyobj)) :str (with-decref [pyobj pyobj] (pystr->str pyobj)) :bool (with-decref [pyobj pyobj] (== 1 (long (PyObject_IsTrue pyobj)))) ;;maybe copy, maybe bridge - in any case we have to decref the item (track-pyobject pyobj))) (check-error-throw))) ================================================ FILE: src/libpython_clj2/python/fn.clj ================================================ (ns libpython-clj2.python.fn "Pathways for creating clojure functions from python callable objects and vice versa. This namespace expects the GIL is captured. Functions bridging this way is relatively expensive but it is the foundation that the more advanced bridging in class.clj is built upon. Also contains mechanisms for calling python functions and attributes." (:require [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.gc :as pygc] [libpython-clj2.python.copy :as py-copy] [tech.v3.datatype.ffi :as dt-ffi] [tech.v3.datatype.ffi.size-t :as ffi-size-t] [tech.v3.datatype.struct :as dt-struct] [tech.v3.datatype :as dtype] [tech.v3.datatype.protocols :as dt-proto] [clojure.tools.logging :as log] [clojure.stacktrace :as st]) (:import [tech.v3.datatype.ffi Pointer] [java.util Map Set] [libpython_clj2.python.protocols PBridgeToPython] [java.lang AutoCloseable])) (set! *warn-on-reflection* true) (def methoddef-type (dt-struct/define-datatype! :pymethoddef [{:name :ml_name :datatype (ffi-size-t/ptr-t-type)} {:name :ml_meth :datatype (ffi-size-t/ptr-t-type)} {:name :ml_flags :datatype :int32} {:name :ml_doc :datatype (ffi-size-t/ptr-t-type)}])) (def tuple-fn-iface* (delay (dt-ffi/define-foreign-interface :pointer? [:pointer :pointer]))) (def kw-fn-iface* (delay (dt-ffi/define-foreign-interface :pointer? [:pointer :pointer :pointer]))) (def ^{:tag 'long} METH_VARARGS 0x0001) (def ^{:tag 'long} METH_KEYWORDS 0x0002) ;; METH_NOARGS and METH_O must not be combined with the flags above. (def ^{:tag 'long} METH_NOARGS 0x0004) (defn- internal-make-py-c-fn [ifn fn-iface raw-arg-converter meth-type {:keys [name doc result-converter] :or {name "_unamed" doc "no documentation provided"}}] (py-ffi/with-gil (let [fn-inst (dt-ffi/instantiate-foreign-interface fn-iface (fn [self tuple-args & [kw-args]] (try (let [retval (apply ifn (raw-arg-converter tuple-args kw-args))] (if result-converter (py-ffi/untracked->python retval result-converter) retval)) (catch Throwable e (log/error e "Error executing clojure function.") (py-ffi/PyErr_SetString (py-ffi/py-exc-type) (format "%s:%s" e (with-out-str (st/print-stack-trace e)))))))) fn-ptr (dt-ffi/foreign-interface-instance->c fn-iface fn-inst) ;;no resource tracking - we leak the struct method-def (dt-struct/new-struct :pymethoddef {:resource-type nil :container-type :native-heap}) name (dt-ffi/string->c name {:resource-type nil}) doc (dt-ffi/string->c doc {:resource-type nil})] (.put method-def :ml_name (.address (dt-ffi/->pointer name))) (.put method-def :ml_meth (.address (dt-ffi/->pointer fn-ptr))) (.put method-def :ml_flags meth-type) (.put method-def :ml_doc (.address (dt-ffi/->pointer doc))) ;;the method def cannot ever go out of scope (py-ffi/retain-forever (gensym) {:md method-def :name name :doc doc :fn-ptr fn-ptr :fn-inst fn-inst}) ;;no self, no module reference (-> (py-ffi/PyCFunction_NewEx method-def nil nil) (py-ffi/track-pyobject))))) (defn raw-tuple-arg-converter [arg-converter tuple-args kw-args] ;;no kw arguments (->> (range (py-ffi/PyTuple_Size tuple-args)) (mapv (fn [idx] (-> (py-ffi/PyTuple_GetItem tuple-args idx) (arg-converter)))))) (defn bridged-fn-arg->python "Slightly clever so we can pass ranges and such as function arguments." ([item opts] (cond (instance? PBridgeToPython item) (py-proto/as-python item opts) (dt-proto/convertible-to-range? item) (py-copy/->py-range item) (dtype/reader? item) (py-proto/->python (dtype/->reader item) opts) ;;There is one more case here for iterables that aren't anything else - ;; - specifically for sequences. (and (instance? Iterable item) (not (instance? Map item)) (not (instance? String item)) (not (instance? Set item))) (py-proto/as-python item opts) :else (py-base/->python item opts))) ([item] (bridged-fn-arg->python item nil))) (defn convert-kw-args [{:keys [arg-converter] :as options} tuple-args kw-args] [(raw-tuple-arg-converter arg-converter tuple-args nil) (if kw-args (->> (py-proto/as-jvm kw-args options) (into {})) {})]) (defn make-tuple-fn ([ifn {:keys [arg-converter result-converter name doc] :or {arg-converter py-base/->jvm result-converter py-base/->python name "_unamed" doc "no documentation provided"} :as options}] (let [arg-converter (or arg-converter identity) ;;apply defaults to options map. options (assoc options :arg-converter arg-converter :result-converter result-converter :name name :doc doc)] (internal-make-py-c-fn ifn @tuple-fn-iface* #(raw-tuple-arg-converter arg-converter %1 %2) METH_VARARGS options))) ([ifn] (make-tuple-fn ifn nil))) (defn make-kw-fn ([ifn {:keys [arg-converter result-converter name doc kw-arg-converter] :or {arg-converter py-base/->jvm result-converter py-base/->python name "_unamed" doc "no documentation provided"} :as options}] (let [arg-converter (or arg-converter :identity) options (assoc options :arg-converter arg-converter :result-converter result-converter :name name :doc doc) kw-arg-converter (or kw-arg-converter #(convert-kw-args options %1 %2))] (internal-make-py-c-fn ifn @kw-fn-iface* kw-arg-converter (bit-or METH_VARARGS METH_KEYWORDS) options))) ([ifn] (make-kw-fn ifn nil))) (defn call-py-fn [callable arglist kw-arg-map arg-converter] (py-ffi/with-gil ;;Release objects marshalled just for this call immediately (let [retval (pygc/with-stack-context (py-ffi/with-decref ;;We go out of our way to avoid tracking the arglist because it is ;;allocated/deallocated so often [arglist (when (or (seq kw-arg-map) (seq arglist)) (py-ffi/untracked-tuple arglist arg-converter)) kw-arg-map (when (seq kw-arg-map) (py-ffi/untracked-dict kw-arg-map arg-converter))] (cond kw-arg-map (py-ffi/PyObject_Call callable arglist kw-arg-map) arglist (py-ffi/PyObject_CallObject callable arglist) :else (py-ffi/PyObject_CallObject callable nil))))] (py-ffi/simplify-or-track retval)))) (extend-type Pointer py-proto/PyCall (call [callable arglist kw-arg-map] (call-py-fn callable arglist kw-arg-map py-base/->python)) (marshal-return [callable retval] retval)) (defn call "Call a python function with positional args. For keyword args, see call-kw." [callable & args] (py-proto/call callable args nil)) (defn call-kw "Call a python function with a vector of positional args and a map of keyword args." [callable arglist kw-args] (py-proto/call callable arglist kw-args)) (defn call-attr-kw "Call an object attribute with a vector of positional args and a map of keyword args." [item att-name arglist kw-map arg-converter] (py-ffi/with-gil (if (or (string? att-name) (keyword? att-name)) (py-ffi/with-decref [attval (py-ffi/PyObject_GetAttrString item (if (keyword? att-name) (name att-name) att-name))] (when-not attval (py-ffi/check-error-throw)) (->> (call-py-fn attval arglist kw-map arg-converter) (py-proto/marshal-return item))) (py-ffi/with-decref [att-name (py-ffi/untracked->python att-name py-base/->python) att-val (py-ffi/PyObject_GetAttr item att-name)] (when (or (nil? att-name) (nil? att-val)) (py-ffi/check-error-throw)) (->> (call-py-fn att-val arglist kw-map arg-converter) (py-proto/marshal-return item)))))) (defn call-attr "Call an object attribute with only positional arguments." [item att-name arglist] (call-attr-kw item att-name arglist nil py-base/->python)) (defn args->pos-kw-args "Utility function that, given a list of arguments, separates them into positional and keyword arguments. Throws an exception if the keyword argument is not followed by any more arguments." [arglist] (loop [args arglist pos-args [] kw-args nil found-kw? false] (if-not (seq args) [pos-args kw-args] (let [arg (first args) [pos-args kw-args args found-kw?] (if (keyword? arg) (if-not (seq (rest args)) (throw (Exception. (format "Keyword arguments must be followed by another arg: %s" (str arglist)))) [pos-args (assoc kw-args arg (first (rest args))) (drop 2 args) true]) (if found-kw? (throw (Exception. (format "Positional arguments are not allowed after keyword arguments: %s" arglist))) [(conj pos-args (first args)) kw-args (rest args) found-kw?]))] (recur args pos-args kw-args found-kw?))))) (defn cfn "Call an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs. Not having an argument after a keyword argument is an error." [item & args] (let [[pos-args kw-args] (args->pos-kw-args args)] (call-kw item pos-args kw-args))) (def ^{:tag 'long} max-fastcall-args 10) (defn allocate-fastcall-context ^objects [] (object-array 1)) (defn release-fastcall-context [call-ctx] (when call-ctx (when-let [arglist (aget ^objects call-ctx 0)] (py-ffi/Py_DecRef arglist) (aset ^objects call-ctx 0 nil)))) (defmacro implement-fastcall [] `(defn ~'fastcall "Call a python function as fast as possible reusing the argument tuple. This function takes an object array of length 1 for the call context cache. Use allocate-fastcall-context and release-fastcall-context in order to manage the context's lifetime. Do not use same context with fastcall invokations of differing arities." ([~'item] (py-ffi/with-gil (-> (py-ffi/PyObject_CallObject ~'item nil) (py-ffi/simplify-or-track)))) ~@(->> (range 1 (inc max-fastcall-args)) (map (fn [n-args] (let [arity-args (map (comp symbol #(str "arg-" %)) (range n-args)) argdef (->> (concat [(with-meta 'call-ctx {:tag 'objects}) 'item] arity-args) (vec))] `(~argdef (py-ffi/with-gil (let [~'arglist (if-let [call-tuple# (aget ^objects ~'call-ctx 0)] call-tuple# (let [new-t# (py-ffi/PyTuple_New ~n-args)] (aset ^objects ~'call-ctx 0 new-t#))) ~@(mapcat (fn [argsym] [argsym `(py-ffi/untracked->python ~argsym)]) arity-args)] ~@(map-indexed (fn [idx argsym] `(py-ffi/PyTuple_SetItem ~'arglist ~idx ~argsym)) arity-args) (-> (py-ffi/PyObject_CallObject ~'item ~'arglist) (py-ffi/simplify-or-track))))))))))) (implement-fastcall) (defmacro reify-fastcallable [item] `(let [~'ctx-list (object-array max-fastcall-args)] (reify AutoCloseable (close [this#] (py-ffi/with-gil (dotimes [idx# (alength ~'ctx-list)] (release-fastcall-context (aget ~'ctx-list idx#)) (aset ~'ctx-list idx# nil)))) clojure.lang.IFn (invoke [this#] (fastcall ~item)) ~@(->> (range 1 (inc max-fastcall-args)) (map (fn [argc] (let [arglist (mapv #(symbol (str "arg-" %)) (range argc)) ctx-idx (dec argc)] `(invoke [this# ~@arglist] (let [~'ctx (if-let [ctx# (aget ~'ctx-list ~ctx-idx)] ctx# (let [ctx# (allocate-fastcall-context)] (aset ~'ctx-list ~ctx-idx ctx#) ctx#))] (fastcall ~'ctx ~item ~@arglist))))))) (applyTo [this# ~'argseq] (let [~'argseq (vec ~'argseq) ~'n-args (count ~'argseq)] (when (> ~'n-args max-fastcall-args) (throw (Exception. (format "Maximum fastcall arguments is %d - %d provided" max-fastcall-args ~'n-args)))) (if (== 0 ~'n-args) (fastcall ~item) (let [~'ctx-idx (dec ~'n-args) ~'ctx (if-let [ctx# (aget ~'ctx-list ~'ctx-idx)] ctx# (let [ctx# (allocate-fastcall-context)] (aset ~'ctx-list ~'ctx-idx ctx#) ctx#))] (case ~'n-args ~@(->> (range 1 max-fastcall-args) (mapcat (fn [argc] [argc `(fastcall ~'ctx ~item ~@(->> (range argc) (map (fn [idx] `(~'argseq ~idx)))))]))))))))))) (defn make-fastcallable "Make an auto-disposable fastcallable object that will override the IFn interface and always use the fastcall pathways. This object *must* be closed and thus should be used in a with-open scenario but there is no need to specifically allocate fastcall context objects. See [[fastcall]] for more information." ^AutoCloseable [item] (py-ffi/with-gil (when-not (= 1 (py-ffi/PyCallable_Check item)) (throw (Exception. "Item passed in does not appear to be a callable python object"))) (reify-fastcallable item))) (defn key-sym-str->str [attr-name] (cond (or (keyword? attr-name) (symbol? attr-name)) (name attr-name) (string? attr-name) attr-name :else (throw (Exception. "Only keywords, symbols, or strings can be used to access attributes.")))) (defn afn "Call an attribute of an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs. Not having an argument after a keyword argument is an error." [item attr & args] (let [[pos-args kw-args] (args->pos-kw-args args)] (call-attr-kw item (key-sym-str->str attr) pos-args kw-args py-base/->python))) ================================================ FILE: src/libpython_clj2/python/gc.clj ================================================ (ns libpython-clj2.python.gc "Binding of various sort of gc semantics optimized specifically for libpython-clj." (:import [java.util.concurrent ConcurrentHashMap ConcurrentLinkedDeque] [java.lang.ref ReferenceQueue] [tech.resource GCReference])) (set! *warn-on-reflection* true) (defonce ^:dynamic *stack-gc-context* nil) (defn stack-context ^ConcurrentLinkedDeque [] *stack-gc-context*) (defonce reference-queue-var (ReferenceQueue.)) (defn reference-queue ^ReferenceQueue [] reference-queue-var) (defonce ptr-set-var (ConcurrentHashMap/newKeySet)) (defn ptr-set ^java.util.Set [] ptr-set-var) (defn track [item dispose-fn] (let [stack-context (stack-context)] (if (= stack-context :disabled) item (let [ptr-val (GCReference. item (reference-queue) (fn [ptr-val] (.remove (ptr-set) ptr-val) (dispose-fn)))] ;;We have to keep track of the pointer. If we do not the pointer gets gc'd then ;;it will not be put on the reference queue when the object itself is gc'd. ;;Nice little gotcha there. (if stack-context (.add ^ConcurrentLinkedDeque stack-context ptr-val) ;;Ensure we don't lose track of the weak reference. If it gets cleaned up ;;the gc system will fail. (.add (ptr-set) ptr-val)) item)))) (defn clear-reference-queue [] (when-let [next-ref (.poll (reference-queue))] (.run ^Runnable next-ref) (recur))) (defn clear-stack-context [] (when-let [next-ref (.pollLast (stack-context))] (.run ^Runnable next-ref) (recur))) (defmacro with-stack-context [& body] `(with-bindings {#'*stack-gc-context* (ConcurrentLinkedDeque.)} (try ~@body (finally (clear-stack-context))))) (defmacro with-disabled-gc [& body] `(with-bindings {#'*stack-gc-context* :disabled} ~@body)) (defn gc-context [] *stack-gc-context*) (defmacro with-gc-context [gc-ctx & body] `(with-bindings {#'*stack-gc-context* ~gc-ctx} ~@body)) ================================================ FILE: src/libpython_clj2/python/info.clj ================================================ (ns libpython-clj2.python.info "Python system information. Uses the installed python executable to find out various details about how python is expecting to run." (:require [clojure.java.shell :as sh] [clojure.data.json :as json] [clojure.tools.logging :as log]) (:import [java.nio.file Paths])) (def ^:private default-python-executables ["python3" "python3.6" "python3.7" "python3.8" "python3.9" "python"]) (defn python-system-info "An information map about the Python system information provided by a Python executable (string). :platform (operating system information) :prefix A string giving the site-specific directory prefix where the platform independent Python files are installed; by default, this is the string '/usr/local'. This can be set at build time with the --prefix argument to the configure script. The main collection of Python library modules is installed in the directory prefix/lib/pythonX.Y while the platform independent header files (all except pyconfig.h) are stored in prefix/include/pythonX.Y, where X.Y is the version number of Python, for example 3.2. Note If a virtual environment is in effect, this value will be changed in site.py to point to the virtual environment. The value for the Python installation will still be available, via base_prefix. :base-prefix Set during Python startup, before site.py is run, to the same value as prefix. If not running in a virtual environment, the values will stay the same; if site.py finds that a virtual environment is in use, the values of prefix and exec_prefix will be changed to point to the virtual environment, whereas base_prefix and base_exec_prefix will remain pointing to the base Python installation (the one which the virtual environment was created from). :executable A string giving the absolute path of the executable binary for the Python interpreter, on systems where this makes sense. If Python is unable to retrieve the real path to its executable, sys.executable will be an empty string or None. :exec-prefix A string giving the site-specific directory prefix where the platform-dependent Python files are installed; by default, this is also '/usr/local'. This can be set at build time with the --exec-prefix argument to the configure script. Specifically, all configuration files (e.g. the pyconfig.h header file) are installed in the directory exec_prefix/lib/pythonX.Y/config, and shared library modules are installed in exec_prefix/lib/pythonX.Y/lib-dynload, where X.Y is the version number of Python, for example 3.2. Note If a virtual environment is in effect, this value will be changed in site.py to point to the virtual environment. The value for the Python installation will still be available, via base_exec_prefix. :base-exec-prefix Set during Python startup, before site.py is run, to the same value as exec_prefix. If not running in a virtual environment, the values will stay the same; if site.py finds that a virtual environment is in use, the values of prefix and exec_prefix will be changed to point to the virtual environment, whereas base_prefix and base_exec_prefix will remain pointing to the base Python installation (the one which the virtual environment was created from). :version (list python-major python-minor python-micro)" [executable] (let [{:keys [out err exit]} (sh/sh executable "-c" "import sys, platform, json; print(json.dumps( {'platform': sys.platform, 'prefix': sys.prefix, 'base-prefix': sys.base_prefix, 'executable': sys.executable, 'base-exec-prefix': sys.base_exec_prefix, 'exec-prefix': sys.exec_prefix, 'platform-arch': platform.machine(), 'version': list(sys.version_info)[:3]}))")] (when (= 0 exit) (json/read-str out :key-fn keyword)))) (defn find-python-info [& [{:keys [python-executable]}]] (->> (if python-executable [python-executable] default-python-executables) (map #(try (python-system-info %) (catch Throwable e nil))) (remove nil?) (first))) (defn find-python-home [system-info & [{:keys [python-home]}]] (cond python-home python-home (seq (System/getenv "PYTHONHOME")) (System/getenv "PYTHONHOME") :else (:base-prefix system-info))) (defn java-library-path-addendum [python-home] (when python-home (-> (Paths/get python-home (into-array String ["lib"])) (.toString)))) (defn detect-startup-info [& [{:keys [python-executable library-path] :as options}]] (if python-executable (log/infof "Detecting startup info for Python executable %s" python-executable) (log/info "Detecting startup info")) (let [system-info (find-python-info options) _ (when-not system-info (if python-executable (throw (Exception. (format "Failed to find value python executable. Tried \"%s\"" python-executable))) (throw (Exception. (format "Failed to find value python executable. Tried %s" default-python-executables))))) python-home (find-python-home system-info options) platform (:platform system-info) java-lib-path (java-library-path-addendum python-home) [ver-maj ver-med _ver-min] (:version system-info) lib-version (format "%s.%s" ver-maj ver-med) libname (or library-path (when (seq lib-version) (str "python" lib-version "m"))) libnames (concat [libname] ;;Make sure we try without the 'm' suffix (when lib-version [(str "python" lib-version)]) ;; The official python dll ;; does not have a dot in ;; its name. (when (= platform "win32") [(str "python" ver-maj ver-med)]))] (merge system-info {:python-home python-home :lib-version lib-version :libname libname :libnames libnames :java-os-arch (System/getProperty "os.arch")} (when java-lib-path {:java-library-path-addendum java-lib-path})))) ================================================ FILE: src/libpython_clj2/python/io_redirect.clj ================================================ (ns libpython-clj2.python.io-redirect "Implementation of optional io redirection." (:require [libpython-clj2.python.class :as py-class] [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.bridge-as-python :as py-bridge-py] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.gc :as pygc] [libpython-clj2.python.jvm-handle :as jvm-handle] [clojure.tools.logging :as log]) (:import [java.io Writer])) (set! *warn-on-reflection* true) (defn self->writer ^Writer [self] (deref (jvm-handle/py-self->jvm-obj self))) (def writer-cls* (jvm-handle/py-global-delay (py-class/create-class "jvm_io_bridge" nil {"__init__" (py-class/wrapped-jvm-constructor) "__del__" (py-class/wrapped-jvm-destructor) "write" (py-class/make-tuple-instance-fn (fn [self & args] (when (seq args) (.write (self->writer self) (str (py-base/->jvm (first args))))) (py-ffi/py-none)) {:arg-converter identity}) "flush" (py-class/make-tuple-instance-fn (fn [self & args] (.flush (self->writer self)) (py-ffi/py-none)) {:arg-converter identity} ;;avoid paying anything for argument conversion ) "isatty" (py-class/make-tuple-instance-fn (constantly (py-ffi/py-false)))}))) (defn setup-std-writer [writer-var sys-mod-attname] (assert (instance? Writer (deref writer-var))) (py-ffi/with-gil (pygc/with-stack-context (let [sys-module (py-ffi/import-module "sys") std-out-writer (@writer-cls* (jvm-handle/make-jvm-object-handle writer-var))] (py-proto/set-attr! sys-module sys-mod-attname std-out-writer) :ok)))) (defn redirect-io! [] (setup-std-writer #'*err* "stderr") (setup-std-writer #'*out* "stdout")) (comment ;;Ensure flush works (require '[libpython-clj2.python :as py]) (py/initialize!) (def _) (def _ (py/run-simple-string "import sys\nimport time")) (py/run-simple-string "for i in range(10): \ttime.sleep(1) \tsys.stderr.write('#') \tsys.stdout.flush()") ) ================================================ FILE: src/libpython_clj2/python/jvm_handle.clj ================================================ (ns libpython-clj2.python.jvm-handle "Conversion of a jvm object into an integer and back. Used for storing handles on python proxies." (:require [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.gc :as pygc] [libpython-clj2.python.ffi :as py-ffi]) (:import [java.util.concurrent ConcurrentHashMap] [java.util UUID])) (defonce ^{:private true :tag ConcurrentHashMap} jvm-handle-map (ConcurrentHashMap.)) (defn identity-hash-code ^long [obj] (long (System/identityHashCode obj))) (defn make-jvm-object-handle ^long [item] (let [^ConcurrentHashMap hash-map jvm-handle-map] (loop [handle (identity-hash-code item)] (if (not (.containsKey hash-map handle)) (do (.put hash-map handle item) handle) (recur (.hashCode (UUID/randomUUID))))))) (defn get-jvm-object [handle] (.get ^ConcurrentHashMap jvm-handle-map (long handle))) (defn remove-jvm-object [handle] (.remove ^ConcurrentHashMap jvm-handle-map (long handle)) nil) (defn py-self->jvm-handle ^long [self] (long (py-proto/get-attr self "jvm_handle"))) (defn py-self->jvm-obj ^Object [self] (-> (py-self->jvm-handle self) get-jvm-object)) (defn py-self-set-jvm-handle! [self hdl] (py-proto/set-attr! self "jvm_handle" (long hdl)) nil) (defmacro py-global-delay "Create a delay object that uses only gc reference semantics. If stack reference semantics happen to be in effect when this delay executes the object may still be reachable by your program when it's reference counts are released leading to bad/crashy behavior. This ensures that can't happen at the cost of possibly an object sticking around." [& body] `(delay (py-ffi/with-gil (with-bindings {#'pygc/*stack-gc-context* nil} ~@body)))) ================================================ FILE: src/libpython_clj2/python/np_array.clj ================================================ (ns libpython-clj2.python.np-array "Bindings for deeper intergration of numpy into the tech.v3.datatype system. This allows seamless usage of numpy arrays in datatype and tensor functionality such as enabling the tech.v3.tensor/ensure-tensor call to work with numpy arrays -- using zero copying when possible. All users need to do is call require this namespace; then as-jvm will convert a numpy array into a tech tensor in-place." (:require [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.fn :as py-fn] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.copy :as py-copy] [libpython-clj2.python.bridge-as-jvm :as py-bridge] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.gc :as pygc] [tech.v3.tensor :as dtt] [tech.v3.datatype.protocols :as dtype-proto] [tech.v3.datatype.casting :as casting] [tech.v3.datatype.argops :as argops] [tech.v3.datatype :as dtype] [clojure.set :as set]) (:import [tech.v3.datatype NDBuffer])) (def py-dtype->dtype-map (->> (concat (for [bit-width [8 16 32 64] unsigned? [true false]] (str (if unsigned? "uint" "int") bit-width)) ["float32" "float64"]) (map (juxt identity keyword)) (into {}))) (def dtype->py-dtype-map (set/map-invert py-dtype->dtype-map)) (defn obj-dtype->dtype [py-dtype] (when-let [fields (py-proto/get-attr py-dtype "fields")] (throw (ex-info (format "Cannot convert numpy object with fields: %s" (py-fn/call-attr fields "__str__" nil)) {}))) (if-let [retval (->> (py-proto/get-attr py-dtype "name") (get py-dtype->dtype-map))] retval (throw (ex-info (format "Unable to find datatype: %s" (py-proto/get-attr py-dtype "name")) {})))) (defn numpy->desc [np-obj] (py-ffi/with-gil (let [ctypes (py-proto/as-jvm (py-proto/get-attr np-obj "ctypes") {}) np-dtype (-> (py-proto/as-jvm (py-proto/get-attr np-obj "dtype") {}) (obj-dtype->dtype)) shape (-> (delay (py-proto/get-attr ctypes "shape")) (py-bridge/generic-python-as-list) vec) strides (-> (delay (py-proto/get-attr ctypes "strides")) (py-bridge/generic-python-as-list) vec) long-addr (py-proto/get-attr ctypes "data")] {:ptr long-addr :elemwise-datatype np-dtype :shape shape :strides strides :type :numpy :ctypes ctypes}))) (defmethod py-proto/pyobject->jvm :ndarray [pyobj opts] (pygc/with-stack-context (-> (numpy->desc pyobj) (dtt/nd-buffer-descriptor->tensor) (dtt/clone)))) (defmethod py-proto/pyobject-as-jvm :ndarray [pyobj opts] (let [pyobj* (delay pyobj)] (py-bridge/bridge-pyobject pyobj* Iterable (iterator [this] (py-bridge/python->jvm-iterator @pyobj* py-base/as-jvm)) dtype-proto/PToTensor (as-tensor [item] (-> (numpy->desc item) (dtt/nd-buffer-descriptor->tensor))) dtype-proto/PElemwiseDatatype (elemwise-datatype [this] (py-ffi/with-gil (-> (py-proto/get-attr pyobj "dtype") (py-proto/as-jvm {}) (obj-dtype->dtype)))) dtype-proto/PECount (ecount [this] (apply * (dtype-proto/shape this))) dtype-proto/PShape (shape [this] (py-ffi/with-gil (-> (py-proto/get-attr @pyobj* "shape") (py-proto/->jvm {})))) dtype-proto/PToNativeBuffer (convertible-to-native-buffer? [item] true) (->native-buffer [item] (py-ffi/with-gil (dtype-proto/->native-buffer (dtype-proto/as-tensor item)))) dtype-proto/PSubBuffer (sub-buffer [buffer offset length] (py-ffi/with-gil (-> (dtype-proto/as-tensor buffer) (dtype-proto/sub-buffer offset length)))) dtype-proto/PToNDBufferDesc (convertible-to-nd-buffer-desc? [item] true) (->nd-buffer-descriptor [item] (py-ffi/with-gil (numpy->desc item)))))) (defn datatype->ptr-type-name [dtype] (case dtype :int8 "c_byte" :uint8 "c_ubyte" :int16 "c_short" :uint16 "c_ushort" :int32 "c_int" :uint32 "c_uint" :int64 "c_longlong" :uint64 "c_ulonglong" :float32 "c_float" :float64 "c_double")) (defn descriptor->numpy [{:keys [ptr shape strides elemwise-datatype] :as buffer-desc}] (py-ffi/with-gil (let [stride-tricks (-> (py-ffi/import-module "numpy.lib.stride_tricks") (py-base/as-jvm)) ctypes (-> (py-ffi/import-module "ctypes") (py-base/as-jvm)) np-ctypes (-> (py-ffi/import-module "numpy.ctypeslib") (py-base/as-jvm)) dtype-size (casting/numeric-byte-width elemwise-datatype) max-stride-idx (argops/argmax strides) buffer-len (* (long (dtype/get-value shape max-stride-idx)) (long (dtype/get-value strides max-stride-idx))) n-elems (quot buffer-len dtype-size) lvalue (long ptr) void-p (py-fn/call-attr ctypes "c_void_p" [lvalue]) actual-ptr (py-fn/call-attr ctypes "cast" [void-p (py-fn/call-attr ctypes "POINTER" [(py-proto/get-attr ctypes (datatype->ptr-type-name elemwise-datatype))])]) initial-buffer (py-fn/call-attr np-ctypes "as_array" [actual-ptr (py-copy/->py-tuple [n-elems])]) retval (py-fn/call-attr stride-tricks "as_strided" [initial-buffer (py-copy/->py-tuple shape) (py-copy/->py-tuple strides)])] ;;Ensure we have metadata that allows the GC to track both buffer ;;desc and retval (vary-meta retval assoc :nd-buffer-descriptor buffer-desc)))) ;;Efficient conversion from jvm to python (extend-type NDBuffer py-proto/PCopyToPython (->python [item opts] (-> (dtt/ensure-nd-buffer-descriptor item) (descriptor->numpy))) py-proto/PBridgeToJVM (as-python [item opts] (when (dtype-proto/convertible-to-nd-buffer-desc? item) (-> (dtype-proto/->nd-buffer-descriptor item) (descriptor->numpy))))) ================================================ FILE: src/libpython_clj2/python/protocols.clj ================================================ (ns libpython-clj2.python.protocols "Internal protocols to libpython-clj. These allow a dual system where raw pointers work with copying pathways and bridged objects work with bridging pathways." (:require [libpython-clj2.python.ffi :as py-ffi] [tech.v3.datatype :as dtype])) (defprotocol PPythonType (get-python-type [item] "Return a keyword that describes the python datatype of this object.")) (defn python-type "Return a keyword that describes the python datatype of this object." ([item] (if item (get-python-type item) :none-type)) ([item options] (python-type item))) (defmulti pyobject-as-jvm "Convert (possibly bridge) a pyobject to the jvm" python-type) (defprotocol PCopyToPython (->python [item options] "Copy this item into a python representation. Must never return nil. Items may fallback to as-python if copying is untenable.")) (defprotocol PBridgeToPython (as-python [item options] "Aside from atom types, this means the object represented by a zero copy python mirror. May return nil. This convertible to pointers get converted to numpy implementations that share the backing store.")) (defprotocol PCopyToJVM (->jvm [item options] "Copy the python object into the jvm leaving no references. This not copying are converted into a {:type :pyobject-address} pairs.")) (defprotocol PBridgeToJVM (as-jvm [item options] "Return a pyobject implementation that wraps the python object.")) (defprotocol PPyDir (dir [item] "Get sorted list of all attribute names.")) (defprotocol PPyAttr (has-attr? [item item-name] "Return true of object has attribute") (get-attr [item item-name] "Get attribute from object") (set-attr! [item item-name item-value] "Set attribute on object")) (defprotocol PPyCallable (callable? [item] "Return true if object is a python callable object.")) (defprotocol PyCall (call [callable arglist kw-arg-map]) (marshal-return [callable retval])) (defprotocol PPyItem (has-item? [item item-name] "Return true of object has item") (get-item [item item-name] "Get an item of a given name from an object") (set-item! [item item-name item-value] "Set an item of to a value")) (defmulti pyobject->jvm "Copy a python object to the jvm based on its python type" python-type) (defmulti pyobject-as-jvm "Bridge a python object to the jvm based on its python type" python-type) (defmulti pydatafy "Datafy a python object. The metadata namespace must be loaded in order to datafy a python object." python-type) ================================================ FILE: src/libpython_clj2/python/windows.clj ================================================ (ns libpython-clj2.python.windows "Windows-specific functionality so that the system works with Anaconda." (:require [clojure.java.shell :refer [sh]] [clojure.java.io :as io] [clojure.string :as s])) (defn create-echo-path-bat! [] "Creates temporary file to extract condas PATH environment variable" (let [tmp (java.io.File/createTempFile "echo-path" ".bat")] (spit tmp "echo %PATH%") (.toString tmp))) (defn delete-echo-path-bat! [tmp] "Deletes temporary file" (io/delete-file tmp)) (defn- get-windows-anaconda-env-path [activate-bat echo-bat] "Get anacondas windows PATH environment variable to load native dlls for numpy etc. like python with anaconda does." (-> (sh "cmd.exe" "/K" (str activate-bat " & " echo-bat)) :out (s/split #"\r\n") reverse (nth 2))) (defn- generate-python-set-env-path [path] "Double quote windows path separator \\ -> \\\\" (let [quoted (s/replace path "\\" "\\\\")] (str "import os;\n" "path = '" quoted "';\n" "os.environ['PATH'] = path;\n"))) (defn setup-windows-conda! [windows-conda-activate-bat run-simple-string] "Setup python PATH environment variable like in anaconda to be able to load native dlls for numpy etc. like anaconda does." (let [echo-bat (create-echo-path-bat!)] (->> (get-windows-anaconda-env-path windows-conda-activate-bat echo-bat) generate-python-set-env-path run-simple-string) (delete-echo-path-bat! echo-bat))) ================================================ FILE: src/libpython_clj2/python/with.clj ================================================ (ns libpython-clj2.python.with "Implementation of the python 'with' keyword" (:require [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.fn :as py-fn] [tech.v3.datatype.ffi :as dt-ffi]) (:import [tech.v3.datatype.ffi Pointer])) (defn python-pyerr-fetch-error-handler "Utility code used in with macro" [] (py-ffi/check-gil) (throw (ex-info "python error in flight" (py-ffi/fetch-normalize-exception)))) (defn with-exit-error-handler "Utility code used in with macro" [with-var error] (let [einfo (ex-data error)] (if (every? #(contains? einfo %) [:type :value :traceback]) (let [{^Pointer ptype :type ^Pointer pvalue :value ^Pointer ptraceback :traceback} einfo suppress-error? (py-fn/call-attr with-var "__exit__" [ptype pvalue ptraceback])] (if (and ptype pvalue ptraceback (not suppress-error?)) (do ;;Manual incref here because we cannot detach the object ;;from our gc decref hook added during earlier pyerr-fetch handler. (py-ffi/PyErr_Restore ptype pvalue ptraceback) (py-ffi/check-error-throw)) (do (when ptype (py-ffi/Py_DecRef ptype)) (when pvalue (py-ffi/Py_DecRef pvalue)) (when ptraceback (py-ffi/Py_DecRef ptraceback))))) (do (py-fn/call-attr with-var "__exit__" [nil nil nil]) (throw error))))) (defmacro with "Support for the 'with' statement in python: (py/with [item (py/call-attr testcode-module \"WithObjClass\" true fn-list)] (py/call-attr item \"doit_err\"))" [bind-vec & body] (when-not (= 2 (count bind-vec)) (throw (Exception. "Bind vector must have 2 items"))) (let [varname (first bind-vec) mgr (gensym "mgr")] `(py-ffi/with-gil (let [~mgr ~(second bind-vec)] (with-bindings {#'py-ffi/*python-error-handler* python-pyerr-fetch-error-handler} (let [~varname (py-fn/call-attr ~mgr "__enter__" nil)] (try (let [retval# (do ~@body)] (py-fn/call-attr ~mgr "__exit__" [nil nil nil]) retval#) (catch Throwable e# (with-exit-error-handler ~mgr e#))))))))) ================================================ FILE: src/libpython_clj2/python.clj ================================================ (ns libpython-clj2.python "Python bindings for Clojure. This library dynamically finds the installed python, loads the shared library and allows Clojure users to use Python modules as if they were Clojure namespaces. Example: ```clojure user> (require '[libpython-clj2.python :as py]) nil user> (py/initialize!) ;; ... (logging) :ok user> (def np (py/import-module \"numpy\")) #'user/np user> (py/py. np linspace 2 3 :num 10) [2. 2.11111111 2.22222222 2.33333333 2.44444444 2.55555556 2.66666667 2.77777778 2.88888889 3. ] ```" (:require [libpython-clj2.python.info :as py-info] [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.base :as py-base] [libpython-clj2.python.fn :as py-fn] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.class :as py-class] [libpython-clj2.python.with :as py-with] [libpython-clj2.python.dechunk-map :refer [dechunk-map]] [libpython-clj2.python.copy :as py-copy] [libpython-clj2.python.bridge-as-jvm :as py-bridge-jvm] [libpython-clj2.python.bridge-as-python] [libpython-clj2.python.io-redirect :as io-redirect] [libpython-clj2.python.gc :as pygc] [libpython-clj2.python.windows :as win] [tech.v3.datatype.ffi :as dtype-ffi] [tech.v3.datatype.errors :as errors] [clojure.tools.logging :as log] clojure.edn) (:import [java.util Map List] [clojure.lang IFn])) (set! *warn-on-reflection* true) (defn initialize! "Initialize the python library. If library path is not provided, then the system attempts to execute a simple python program and have python return system info. Note: all of the options passed to `initialize!` may now be provided in a root-level `python.edn` file. Example: ``` ;; python.edn {:python-executable \"/usr/bin/python3.7\" :python-library-path \"/usr/lib/libpython3.7m.so\" :python-home \"/usr/lib/python3.7\" :python-verbose true} ``` or, using a local virtual environment: ``` ;; python.edn {:python-executable \"env/bin/python\"} ``` Additionaly the file can contain two keys which can can refer to custom hooks to run code just before and just after python is initialised. Typical use case for this is to setup / verify the python virtual enviornment to be used. ``` :pre-initialize-fn my-ns/my-venv-setup-fn! :post-initialize-fn my-ns/my-venv-validate-fn! ``` A :pre-initialize-fn could for example shell out and setup a python virtual enviornment. The :post-initialize-fn can use all functions from ns `libpython-clj2.python` as libpython-clj is initialised alreday and could for example be used to validate that later needed libraries can be loaded via calling `import-module`. The file MUST be named `python.edn` and be in the root of the classpath. With a `python.edn` file in place, the `initialize!` function may be called with no arguments and the options will be read from the file. If arguments are passed to `initialize!` then they will override the values in the file. Returns either `:ok` in which case the initialization completed successfully or `:already-initialized` in which case we detected that python has already been initialized via `Py_IsInitialized` and we do nothing more. Options: * `:library-path` - Library path of the python library to use. * `:program-name` - Optional -- will show up in error messages from python. * `:no-io-redirect?` - True if you don't want python stdout and stderr redirection to *out* and *err*. * `:python-executable` - The python executable to use to find system information. * `:python-home` - Python home directory. The system first uses this variable, then the environment variable PYTHON_HOME, and finally information returned from python system info. * `:signals?` - defaults to false - true if you want python to initialized signals. Be aware that the JVM itself uses quite a few signals - SIGSEGV, for instance - during it's normal course of operation. For more information see: * [used signals](https://docs.oracle.com/javase/10/troubleshoot/handle-signals-and-exceptions.htm#JSTGD356) * [signal-chaining](https://docs.oracle.com/javase/8/docs/technotes/guides/vm/signal-chaining.html)" [& {:keys [windows-anaconda-activate-bat library-path no-io-redirect?] :as options}] (if-not (and (py-ffi/library-loaded?) (= 1 (py-ffi/Py_IsInitialized))) (let [python-edn-opts (-> (try (slurp "python.edn") (catch java.io.FileNotFoundException _ "{}")) clojure.edn/read-string) _ (some-> python-edn-opts :pre-initialize-fn requiring-resolve (apply [])) options (merge python-edn-opts options) info (py-info/detect-startup-info options) _ (log/infof "Startup info %s" info) _ (when-let [lib-path (:java-library-path-addendum options (:java-library-path-addendum info))] (log/infof "Prefixing java library path: %s" lib-path) (py-ffi/append-java-library-path! lib-path)) libname (->> (concat (when library-path [library-path]) (:libnames info)) (dechunk-map identity) (map dtype-ffi/find-library) (remove nil?) (first))] (errors/when-not-errorf libname "Failed to find a valid python library!") (log/infof "Loading python library: %s" libname) (py-ffi/initialize! libname (:python-home info) (assoc options :program-name (:program-name options (:executable info)) :python-home (:python-home options (:python-home info)) :java-library-path-addendum (:java-library-path-addendum options (:java-library-path-addendum info)))) (let [gilstate (py-ffi/lock-gil)] (try (when-not (nil? windows-anaconda-activate-bat) (win/setup-windows-conda! windows-anaconda-activate-bat py-ffi/run-simple-string)) (when-not no-io-redirect? (io-redirect/redirect-io!)) (finally (py-ffi/unlock-gil gilstate)))) (some-> python-edn-opts :post-initialize-fn requiring-resolve (apply [])) :ok) :already-initialized)) (defmacro stack-resource-context "Create a stack-based resource context. All python objects allocated within this context will be released at the termination of this context. !!This means that no python objects can escape from this context!! You must use copy semantics (->jvm) for anything escaping this context. Furthermore, if you are returning generic python objects you may need to call (into {}) or something like that just to ensure that absolutely everything is copied into the jvm." [& body] `(pygc/with-stack-context ~@body)) (defmacro with-gil "Capture the gil for an extended amount of time. This can greatly speed up operations as the mutex is captured and held once as opposed to fine grained grabbing/releasing of the mutex." [& body] `(py-ffi/with-gil ~@body)) (defmacro with-gil-stack-rc-context "Capture the gil, open a resource context. The resource context is released before the gil is leading to much faster resource collection. See documentation on `stack-resource-context` for multiple warnings; the most important one being that if a python object escapes this context your program will eventually, at some undefined point in the future crash. That being said, this is the recommended pathway to use in production contexts where you want defined behavior and timings related to use of python." [& body] `(py-ffi/with-gil (pygc/with-stack-context ~@body))) (defmacro with-manual-gil "When running with -Dlibpython_clj.manual_gil=true, you need to wrap all accesses to the python runtime with this locker. This includes calls to require-python or any other pathways. ```clojure (with-manual-gil ...) ``` " [& body] `(with-open [locker# (py-ffi/manual-gil-locker)] ~@body)) (defmacro with-manual-gil-stack-rc-context "When running with -Dlibpython_clj.manual_gil=true, you need to wrap all accesses to the python runtime with this locker. This includes calls to require-python or any other pathways. This macro furthermore defines a stack-based gc context to immediately release objects when the stack frame exits." [& body] `(with-manual-gil (pygc/with-stack-context ~@body))) (declare ->jvm) (defn ^:no-doc in-py-ctx [^java.util.function.Supplier supplier] (with-gil-stack-rc-context (-> (.get supplier) (->jvm)))) (defn import-module "Import a python module. Module entries can be accessed via get-attr." [modname] (with-gil (if-let [mod (py-ffi/PyImport_ImportModule modname)] (-> (py-ffi/track-pyobject mod) (py-base/as-jvm)) (py-ffi/check-error-throw)))) (defn add-module "Add a python module. This can create a module if it doesn't exist." [modname] (with-gil (-> (py-ffi/PyImport_AddModule modname) (py-ffi/incref-track-pyobject) (py-base/as-jvm)))) (defn module-dict "Get the module dictionary." [mod] (with-gil (-> (py-ffi/PyModule_GetDict mod) (py-ffi/incref-track-pyobject) (py-base/as-jvm)))) (defn dir [pyobj] (with-gil (py-proto/dir pyobj))) (defn call-attr "Call an attribute on a python object using only positional arguments" [pyobj attname & args] (with-gil (py-fn/call-attr pyobj attname args))) (defn call-attr-kw "Call an attribute passing in both positional and keyword arguments." [pyobj attname args kw-list] (with-gil (py-fn/call-attr-kw pyobj attname args kw-list py-base/as-python))) (defn get-attr "Get an attribute from a python object" [pyobj attname] (with-gil (py-proto/get-attr pyobj attname))) (defn set-attr! "Set an attribute on a python object. Returns pyobj." [pyobj attname attval] (with-gil (py-proto/set-attr! pyobj attname attval)) pyobj) (defn set-attrs! "Set a sequence of [name value] attributes. Returns pyobj." [pyobj att-seq] (with-gil (doseq [[k v] att-seq] (set-attr! pyobj k v))) pyobj) (defn has-attr? "Return true if this python object has this attribute." [pyobj att-name] (py-proto/has-attr? pyobj att-name)) (defn get-item "Get an item from a python object using __getitem__" [pyobj item-name] (with-gil (py-proto/get-item pyobj item-name))) (defn set-item! "Set an item on a python object using __setitem__" [pyobj item-name item-val] (with-gil (py-proto/set-item! pyobj item-name item-val)) pyobj) (defn has-item? "Return true if the python object has an item. Calls __hasitem__." [pyobj item-name] (with-gil (py-proto/has-item? pyobj item-name))) (defn set-items! "Set a sequence of [name value]. Returns pyobj" [pyobj item-seq] (with-gil (doseq [[k v] item-seq] (set-item! pyobj k v))) pyobj) (defn ->python "Copy a jvm value into a python object" [v] (py-ffi/with-gil (py-base/->python v))) (defn as-python "Bridge a jvm value into a python object" [v] (py-ffi/with-gil (py-base/as-python v))) (defn ->jvm "Copy a python value into java datastructures" [v & [opts]] (py-ffi/with-gil (py-base/->jvm v opts))) (defn as-jvm "Copy a python value into java datastructures" [v & [opts]] (py-ffi/with-gil (py-base/as-jvm v opts))) (defn as-map "Make a python object appear as a map of it's items" ^Map [pobj] (py-bridge-jvm/generic-python-as-map (delay pobj))) (defn as-list "Make a python object appear as a list" ^List [pobj] (py-bridge-jvm/generic-python-as-list (delay pobj))) (defn python-type "Get the type (as a keyword) of a python object" [v] (if v (py-ffi/with-gil (py-proto/python-type v)) :py-none)) (defn attr-type-map "Return a map of attr name to python-type of the attribute" [pyobj] (py-ffi/with-gil (into (sorted-map) (map #(vector % (python-type (get-attr pyobj %)))) (dir pyobj)))) (defmacro import-as "Import a module and assign it to a var. Documentation is included." [module-path varname] `(let [~'mod-data (import-module ~(name module-path))] (def ~varname (import-module ~(name module-path))) (alter-meta! #'~varname assoc :doc (get-attr ~'mod-data "__doc__")) #'~varname)) (defmacro from-import "Support for the from a import b,c style of importing modules and symbols in python. Documentation is included." [module-path item & args] `(do (let [~'mod-data (import-module ~(name module-path))] ~@(map (fn [varname] `(let [~'var-data (get-attr ~'mod-data ~(name varname))] (def ~varname ~'var-data) (alter-meta! #'~varname assoc :doc (get-attr ~'var-data "__doc__")) #'~varname)) (concat [item] args))))) (defn is-instance? "Return true if inst is an instance of cls. Note that arguments are reversed as compared to `instance?`" [py-inst py-cls] (py-ffi/with-gil (let [retval (long (py-ffi/PyObject_IsInstance py-inst py-cls))] (case retval 0 false 1 true (py-ffi/check-error-throw))))) (defn callable? "Return true if python object is callable." [pyobj] (cond (instance? IFn pyobj) true (py-ffi/convertible-to-pointer? pyobj) (py-ffi/with-gil (let [retval (long (py-ffi/PyCallable_Check pyobj))] (case retval 0 false 1 true (py-ffi/check-error-throw)))) :else false)) (defn ->py-list "Copy the data into a python list" [v] (py-ffi/with-gil (-> (py-copy/->py-list v) (as-jvm)))) (defn ->py-tuple "Copy v into a python tuple" [v] (py-ffi/with-gil (-> (py-copy/->py-tuple v) (as-jvm)))) (defn ->py-dict "Copy v into a python dict" [v] (py-ffi/with-gil (-> (py-copy/->py-dict v) (as-jvm)))) (defn run-simple-string "Run a string expression returning a map of {:globals :locals}. This uses the global __main__ dict under the covers so it matches the behavior of the cpython implementation with the exception of returning the various maps used. Note this will never return the result of the expression: https://mail.python.org/pipermail/python-list/1999-April/018011.html Globals, locals may be provided but are not necessary. Implemented in cpython as: PyObject *m, *d, *v; m = PyImport_AddModule(\"__main__\"); if (m == NULL) return -1; d = PyModule_GetDict(m); v = PyRun_StringFlags(command, Py_file_input, d, d, flags); if (v == NULL) { PyErr_Print(); return -1; } Py_DECREF(v); return 0;" [program & {:keys [globals locals]}] (->> (py-ffi/run-simple-string program :globals globals :locals locals) (map (fn [[k v]] [k (py-base/as-jvm v)])) (into {}))) (defn make-callable "Make a python callable object from a clojure function. This is called for you if you use `as-python` on an implementation of IFn. Options: * `:arg-converter` - Function called for each function argument before your ifn gets access to it. Defaults to `->jvm`. * `:result-converter` - Function called on return value before it gets returned to python. Must return a python object. Defaults to `->python`; the result will get an extra incref before being returned to Python to account for the implied tracking of `as-python` or `->python`. * `:name` - Name of the python method. This will appear in stack traces. * `:doc` - documentation for method." ([ifn options] (py-fn/make-tuple-fn ifn options)) ([ifn] (make-callable ifn nil))) (defn ^:no-doc make-tuple-fn "Deprecated - use make-callable" [ifn & {:as options}] (make-callable ifn options)) (defn make-instance-fn "Make an callable instance function - a function which will be passed the 'this' object as it's first argument. In addition, this function calls `make-callable` with a `arg-converter` defaulted to `as-jvm`. See documentation for [[make-callable]] and [[libpython-clj2.python.class/make-tuple-instance-fn]]." ([ifn options] (py-class/make-tuple-instance-fn ifn options)) ([ifn] (make-instance-fn ifn nil))) (defn make-kw-instance-fn "Make an kw callable instance function - function by default is passed 2 arguments, the positional argument vector and a map of keyword arguments. Results are marshalled back to python using [[libpython-clj2.python.fn/bridged-fn-arg->python]] which is also used when bridging an object into python. See documentation for [[make-callable]] [[libpython-clj2.python.class/make-kw-instance-fn]]." ([ifn options] (py-class/make-kw-instance-fn ifn options)) ([ifn] (make-kw-instance-fn ifn nil))) (defn ^:no-doc make-tuple-instance-fn [ifn & {:as options}] (make-instance-fn ifn options)) (defn create-class "Create a new class object. Any callable values in the cls-hashmap will be presented as instance methods. If you want access to the 'this' object then you must use `make-instance-fn`. Example: ```clojure user> (require '[libpython-clj2.python :as py]) nil user> (def cls-obj (py/create-class \"myfancyclass\" nil {\"__init__\" (py/make-instance-fn (fn [this arg] (py/set-attr! this \"arg\" arg) ;;If you don't return nil from __init__ that is an ;;error. nil)) \"addarg\" (py/make-instance-fn (fn [this otherarg] (+ (py/get-attr this \"arg\") otherarg)))})) #'user/cls-obj user> cls-obj __no_module__.myfancyclass user> (def inst (cls-obj 10)) #'user/inst user> (py/call-attr inst \"addarg\" 10) 20 ```" [name bases cls-hashmap] (py-class/create-class name bases cls-hashmap)) (defn cfn "Call an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs. Not having an argument after a keyword argument is an error." [item & args] (apply py-fn/cfn item args)) (defn afn "Call an attribute of an object. Arguments are passed in positionally. Any keyword arguments are paired with the next arg, gathered, and passed into the system as *kwargs. Not having an argument after a keyword is an error." [item attr & args] (apply py-fn/afn item attr args)) (defn make-fastcallable "Wrap a python callable such that calling it in a tight loop with purely positional arguments is a bit (2x-3x) faster. Example: ```clojure user> (def test-fn (-> (py/run-simple-string \"def spread(bid,ask):\n\treturn bid-ask\n\n\") (get :globals) (get \"spread\"))) #'user/test-fn user> test-fn user> (py/with-gil (time (dotimes [iter 10000] (test-fn 1 2)))) \"Elapsed time: 85.140418 msecs\" nil user> (py/with-gil (time (dotimes [iter 10000] (test-fn 1 2)))) \"Elapsed time: 70.894275 msecs\" nil user> (with-open [test-fn (py/make-fastcallable test-fn)] (py/with-gil (time (dotimes [iter 10000] (test-fn 1 2))))) \"Elapsed time: 39.442622 msecs\" nil user> (with-open [test-fn (py/make-fastcallable test-fn)] (py/with-gil (time (dotimes [iter 10000] (test-fn 1 2))))) \"Elapsed time: 35.492965 msecs\" nil ```" ^java.lang.AutoCloseable [item] (py-fn/make-fastcallable item)) (defmacro with "Support for the 'with' statement in python: (py/with [item (py/call-attr testcode-module \"WithObjClass\" true fn-list)] (py/call-attr item \"doit_err\"))" [bind-vec & body] `(py-with/with ~bind-vec ~@body)) (defmacro $a "Call an attribute of an object using automatic detection of the python kwargs. Keywords must be compile time constants. So this won't work with 'apply'. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime. The attr name can be a symbol." [item attr & args] (let [[pos-args kw-args] (py-fn/args->pos-kw-args args)] `(call-attr-kw ~item ~(py-fn/key-sym-str->str attr) ~pos-args ~kw-args))) (defmacro $c "Call an object using automatic detection of the python kwargs. Keywords must be compile time constants. So this won't work with 'apply'. On the other hand, building the positional and kw argmaps happens at compile time as opposed to at runtime." [item & args] (let [[pos-args kw-args] (py-fn/args->pos-kw-args args)] `(py-fn/call-kw ~item ~pos-args ~kw-args))) (defmacro py.- "Class/object getter syntax. (py.- obj attr) is equivalent to Python's obj.attr syntax." [x arg] `(get-attr ~x ~(py-fn/key-sym-str->str arg))) (defmacro py. "Class/object method syntax. (py. obj method arg1 arg2 ... argN) is equivalent to Python's obj.method(arg1, arg2, ..., argN) syntax." [x method-name & args] ;; method-name cast to a string specifically for go and go-loop ;; compatability `(~#'$a ~x ~(str method-name) ~@args)) (defmacro py* "Special syntax for passing along *args and **kwargs style arguments to methods. Usage: (py* obj method args kwargs) Example: (def d (python/dict)) d ;;=> {} (def iterable [[:a 1] [:b 2]]) (def kwargs {:cat \"dog\" :name \"taco\"}) (py* d update [iterable] kwargs) d ;;=> {\"a\": 1, \"b\": 2, \"cat\": \"dog\", \"name\": \"taco\"}" ([x method args] (list #'call-attr-kw x (py-fn/key-sym-str->str method) args nil)) ([x method args kwargs] (list #'call-attr-kw x (py-fn/key-sym-str->str method) args kwargs))) (defmacro py** "Like py*, but it is assumed that the LAST argument is kwargs." ([x method kwargs] (list #'call-attr-kw x (str method) nil kwargs)) ([x method arg & args] (let [args (into [arg] args) kwargs (last args) args (vec (pop args))] (list #'call-attr-kw x (py-fn/key-sym-str->str method) args kwargs)))) (defn ^:private handle-pydotdot ([x form] (if (list? form) (let [form-data (vec form) [instance-member & args] form-data symbol-str (str instance-member)] (cond (clojure.string/starts-with? symbol-str "-") (list #'py.- x (symbol (subs symbol-str 1 (count symbol-str)))) (clojure.string/starts-with? symbol-str "**") (list* #'py** x (symbol (subs symbol-str 2 (count symbol-str))) args) (clojure.string/starts-with? symbol-str "*") (list* #'py* x (symbol (subs symbol-str 1 (count symbol-str))) args) :else ;; assumed to be method invocation (list* (into (vector #'py. x instance-member) args)))) (handle-pydotdot x (list form)))) ([x form & more] (apply handle-pydotdot (handle-pydotdot x form) more))) (defmacro py.. "Extended accessor notation, similar to the `..` macro in Clojure. (require-python 'sys) (py.. sys -path (append \"/home/user/bin\")) is equivalent to Python's import sys sys.path.append('/home/user/bin') SPECIAL SYNTAX for programmatic *args and **kwargs Special syntax is provided to meet the needs required by Python's *args and **kwargs syntax programmatically. (= (py.. obj (*method args)) (py* obj methods args)) (= (py.. obj (*method args kwargs)) (py* obj method args kwargs)) (= (py.. obj (**method kwargs)) (py** obj method kwargs)) (= (py.. obj (**method arg1 arg2 arg3 ... argN kwargs)) (py** obj method arg1 arg2 arg3 ... argN kwargs) (py* obj method [arg1 arg2 arg3 ... argN] kwargs)) These forms exist for when you need to pass in a map of options in the same way you would use the f(*args, **kwargs) forms in Python." [x & args] (apply handle-pydotdot x args)) (defn- module-path-string "Given a.b, return a Given a.b.c, return a.b Given a.b.c.d, return a.b.c etc." [x] (clojure.string/join "." (pop (clojure.string/split (str x) #"[.]")))) (defn- module-path-last-string "Given a.b.c.d, return d" [x] (last (clojure.string/split (str x) #"[.]"))) (defn path->py-obj "Given a string such as \"builtins\" or \"builtins.list\", load the module or the class object in the module. Options: * `:reload` - Reload the module." [item-path & {:keys [reload?]}] (when (seq item-path) (if-let [module-retval (try (import-module item-path) (catch Exception e (when-not (seq (module-path-string item-path)) (throw e))))] (if reload? (let [import-lib (import-module "importlib")] (call-attr import-lib "reload" module-retval)) module-retval) (let [butlast (module-path-string item-path)] (if-let [parent-mod (path->py-obj butlast :reload? reload?)] (get-attr parent-mod (module-path-last-string item-path)) (throw (Exception. (format "Failed to find module or class %s" item-path)))))))) (defmacro def-unpack "Unpack a set of symbols into a set of defs. Useful when trying to match Python idioms - this is definitely not idiomatic Clojure. Example: ```clojure user> (py/def-unpack [a b c] (py/->py-tuple [1 2 3])) #'user/c user> a 1 user> b 2 user> c 3 ```" [symbols input] `(let [~symbols ~input] ~@(for [s symbols] `(def ~s ~s)))) ================================================ FILE: src/libpython_clj2/require.clj ================================================ (ns libpython-clj2.require "Namespace implementing requiring python modules as Clojure namespaces. This works via scanning the module for metadata and dynamically building the Clojure namespace." (:refer-clojure :exclude [fn? doc]) (:require [libpython-clj2.python :as py] [libpython-clj2.metadata :as pymeta] [clojure.datafy :refer [datafy nav]] [clojure.tools.logging :as log] [clojure.core.protocols :as clj-proto]) (:import (java.io File))) (defn- parse-flags "FSM style parser for flags. Designed to support both unary style flags aka '[foo :reload] and boolean flags '[foo :reload true] to support Clojure style 'require syntax. Possibly overengineered." [supported-flags reqs] ;; Ensure we error out when flags passed in are mistyped. ;; First attempt is to filter keywords and make sure any keywords are ;; in supported-flags (let [total-flags (set (concat supported-flags [:as :refer :exclude :* :all :bind-ns :path]))] (when-let [missing-flags (->> reqs (filter #(and (not (total-flags %)) (keyword? %))) seq)] (throw (Exception. (format "Unsupported flags: %s" (set missing-flags)))))) ;;Loop through reqs. If a keyword is found and it is a supported flag, ;;see if the next thing is a boolean with a default to true. ;;If the flag is enabled (as false could be passed in), conj (or disj) to flag set ;;Return reqs minus flags and booleans. (loop [reqs reqs retval-reqs [] retval-flags #{}] (if (seq reqs) (let [next-item (first reqs) reqs (rest reqs) [bool-flag reqs] (if (and (supported-flags next-item) (boolean? (first reqs))) [(first reqs) (rest reqs)] [true reqs]) retval-flags (if (supported-flags next-item) (if bool-flag (conj retval-flags next-item) (disj retval-flags next-item)) retval-flags) retval-reqs (if (not (supported-flags next-item)) (conj retval-reqs next-item) retval-reqs)] (recur reqs retval-reqs retval-flags)) retval-flags))) (defn- extract-refer-symbols [{:keys [refer this-module]} public-data] (cond ;; include everything into the current namespace, ;; ignore __all__ directive (or (refer :all) (and (not (py/has-attr? this-module "__all__")) (refer :*))) (keys public-data) ;; only include that specfied by __all__ attribute ;; of python module if specified, else same as :all (refer :*) (->> (py/get-attr this-module "__all__") (map (fn [item-name] (let [item-sym (symbol item-name)] (when (contains? public-data item-sym) item-sym)))) (remove nil?)) ;; [.. :refer [..]] behavior :else (do (when-let [missing (->> refer (remove (partial contains? public-data)) seq)] (throw (Exception. (format "'refer' symbols not found: %s" (vec missing))))) refer))) (defn- do-require-python [reqs-vec] (let [[module-name & etc] reqs-vec supported-flags #{:reload :no-arglists :bind-ns} flags (parse-flags supported-flags etc) etc (->> etc (remove supported-flags) (remove boolean?)) _ (when-not (= 0 (rem (count etc) 2)) (throw (Exception. "Must have even number of entries"))) etc (->> etc (partition-all 2) (map vec) (into {})) reload? (:reload flags) no-arglists? (:no-arglists flags) bind-ns? (:bind-ns flags) alias-name (:as etc) path (:path etc) exclude (into #{} (:exclude etc)) refer-data (cond (= :all (:refer etc)) #{:all} (= :* (:refer etc)) #{:*} :else (into #{} (:refer etc))) pyobj (if path (let [cwd (pymeta/py-getcwd)] (try (pymeta/py-chdir path) (py/path->py-obj (str module-name) :reload? reload?) (finally (pymeta/py-chdir cwd)))) (py/path->py-obj (str module-name) :reload? reload?)) existing-py-ns? (find-ns module-name)] (create-ns module-name) (when bind-ns? (let [import-name (or (not-empty (str alias-name)) (str module-name)) ns-dots (re-find #"[.]" import-name)] (when (not (zero? (count ns-dots))) (throw (Exception. (str "Cannot have periods in module/class" "name. Please :alias " import-name " to something without periods.")))) (intern (symbol (str *ns*)) (with-meta (symbol import-name) {:file (pymeta/find-file pyobj) :line 1}) pyobj))) (when (or (not existing-py-ns?) reload?) (pymeta/apply-static-metadata-to-namespace! module-name (datafy pyobj) :no-arglists? no-arglists?)) (when-let [refer-symbols (->> (extract-refer-symbols {:refer refer-data :this-module pyobj} (ns-publics (find-ns module-name))) seq)] (refer module-name :exclude exclude :only refer-symbols)) (when alias-name (alias alias-name module-name)))) (defn ^:private req-transform ([req] (if (symbol? req) req (let [base (first req) reqs (rest req)] (map (partial req-transform base) reqs)))) ([prefix req] (cond (and (symbol? req) (clojure.string/includes? (name req) ".") ) (throw (Exception. (str "After removing prefix list, requirements cannot " "contain periods. Please remove periods from " req))) (symbol? req) (symbol (str prefix "." req)) :else (let [base (first req) reqs (rest req) alias? (reduce (fn [res [a b]] (cond (not b) nil (= :as a) (reduced b) :else nil)) nil (partition 2 1 reqs))] (if alias? (into [(symbol (str prefix "." base))] reqs) (into [(req-transform prefix base)] reqs)))))) (defn require-python "## Basic usage ## (require-python 'math) (math/sin 1.0) ;;=> 0.8414709848078965 (require-python '[math :as maaaath]) (maaaath/sin 1.0) ;;=> 0.8414709848078965 (require-python 'math 'csv) (require-python '[math :as pymath] 'csv)) (require-python '[math :as pymath] '[csv :as py-csv]) (require-python 'concurrent.futures) (require-python '[concurrent.futures :as fs]) (require-python '(concurrent [futures :as fs])) (require-python '[requests :refer [get post]]) (requests/get \"https//www.google.com\") ;;=> (get \"https//www.google.com\") ;;=> In some cases we may generate invalid arglists metadata for the clojure compiler. In those cases we have a flag, :no-arglists that will disable adding arglists to the generated metadata for the vars. Use the reload flag below if you need to force reload a namespace where invalid arglists have been generated. (require-python '[numpy :refer [linspace] :no-arglists :as np]) If you would like to bind the Python module to the namespace, use the :bind-ns flag. (require-python '[requests :bind-ns true]) or (require-python '[requests :bind-ns]) ## Use with custom modules ## For use with a custom namespace foo.py while developing, you can use: (require-python '[foo :reload]) NOTE: unless you specify the :reload flag, ..: the module will NOT reload. If the :reload flag is set, ..: the behavior mimics importlib.reload ## Setting up classpath for custom modules ## Note: you may need to setup your PYTHONPATH correctly. **WARNING**: This is very handy for local REPL development, ..: if you are going to AOT classes, ..: refer to the documentation on codegen ..: or your AOT compilation will fail. If your foo.py lives at /path/to/foodir/foo.py, the easiest way to do it is: (require-python :from \"/path/to/foodir\" 'foo) ;; or (require-python \"/path/to/foodir\" 'foo) ;; or (require-python {:from \"/path/to/foodir\"} 'foo) as you prefer. Additionally, if you want to keep the namespacing as you have it in Python, you may prefer to use a relative import starting from a location of your choosing. If your os.getcwd() => /some/path/foo, and your directory structure looks something like: /some $ tree . └── path ├── baz │ └── quux.py └── foo └── bar.py (require-python :from \"path\" '[baz.quux :as quux] :from \"path/foo\" 'bar) is perfectly acceptable. It probably makes the most sense to keep you style consistent, but you can mix and match as you see fit between , :from , and {:from }. can either be a file or a directory. If it is a file, the Python path will be set to the directory containing that file. You may also stack several require-pythons under one path: (require-python {:from \"dir-a\"} 'a 'b 'c {:from \"dir-b\"} 'e.f 'g {:from \"dir-c} 'hi.there) Other options more in keeping with traditional PYTHONPATH management include: (require-python 'sys) (py/call-attr (py/get-attr sys \"path\") \"append\" \"/path/to/foodir\") Another option is (require-python 'os) (os/chdir \"/path/to/foodir\") ## prefix lists ## For convenience, if you are loading multiple Python modules with the same prefix, you can use the following notation: (require-python '(a b c)) is equivalent to (require-python 'a.b 'a.c) (require-python '(foo [bar :as baz :refer [qux]])) is equivalent to (require-python '[foo.bar :as baz :refer [qux]]) (require-python '(foo [bar :as baz :refer [qux]] buster)) (require-python '[foo.bar :as baz :refer [qux]] 'foo.buster)) ## For library developers ## If you want to intern all symbols to your current namespace, you can do the following -- (require-python '[math :refer :all]) However, if you only want to use those things designated by the module under the __all__ attribute, you can do (require-python '[operators :refer :*])" ([req] (py/with-gil (cond (list? req) ;; prefix list (let [prefix-lists (req-transform req)] (doseq [req prefix-lists] (require-python req))) (symbol? req) (require-python (vector req)) (vector? req) (do-require-python req) :else (throw (Exception. "Invalid argument: %s" req)))) :ok) ([req & reqs] (cond (and (map? req) (contains? req :from) (seq reqs)) (apply require-python (:from req) reqs) (and (keyword? req) (= :from req) (string? (first reqs))) (apply require-python (first reqs) (rest reqs)) (and (string? req) (.isFile (File. req))) (let [file (File. req) cwd (pymeta/py-getcwd)] (apply require-python (str (.getParent file)) reqs)) (and (string? req) (.isDirectory (File. req))) (let [cwd (pymeta/py-getcwd)] (try (pymeta/py-chdir req) (apply require-python reqs) (finally (pymeta/py-chdir cwd)))) :else (do (require-python req) (when (not-empty reqs) (apply require-python reqs)))) :ok)) (defn import-python "Loads python, python.list, python.dict, python.set, python.tuple, and python.frozenset." [] (require-python '(builtins [list :as python.list] [dict :as python.dict] [set :as python.set] [tuple :as python.tuple] [frozenset :as python.frozenset] [str :as python.str]) '[builtins :as python]) :ok) (def ^:private builtins (py/import-module "builtins")) (def ^:private pytype (comp symbol str (py/get-attr builtins "type"))) (defmulti ^:no-doc pydafy "Turn a Python object into Clojure data. Metadata of Clojure data will automatically be merged with nav protocol. Extend this method to convert a custom Python object into Clojure data. Extend pynav if you would like to nav the resulting Clojure data. Note: we don't have a way yet to use a 'python type' as a 'jvm class', so you need to extend with the symbol of the object name. I know it's an ugly hack. Sorry. See examples in libpython-clj.require." pytype) (defmulti ^:no-doc pynav "Nav data from a Python object. Extend this method to nav a custom Python object into Clojure data. Extend pydafy if you would like to datafy a Python object. Note: we don't have a way yet to use a 'python type' as a 'jvm class', so you need to extend with the symbol of the object name. I know it's an ugly hack. Sorry. See examples in libpython-clj.require." (fn [coll k v] (pytype coll))) (defmethod pydafy :default [x] (if (pymeta/pyclass? x) (pymeta/datafy-module-or-class x) (throw (ex-info (str "datafy not implemented for " (pytype x)) {:type (pytype x)})))) (defmethod pynav :default [x] (if (pymeta/pyclass? x) (pymeta/nav-module x) (throw (ex-info (str "nav not implemented for " (pytype x)) {:type (pytype x)})))) (defmethod pydafy 'builtins.module [m] (pymeta/datafy-module-or-class m)) (defmethod pynav 'builtins.module [coll k v] (pymeta/nav-module coll k v)) (defmethod pydafy 'builtins.dict [x] (py/->jvm x)) (defn ^:private py-datafy [item] (let [res (pydafy item) m (meta res)] (try (with-meta res (merge {'clj-proto/nav pynav} m)) (catch ClassCastException _ ;; presumably metadata doesn't work for this type res)))) (defn ^:private py-nav [coll k v] (let [res (pynav coll k v) m (meta res)] (try (with-meta res (merge {'clj-proto/datafy pydafy} m)) (catch ClassCastException _ ;; presumably metadata doesn't work for this type res)))) (defmacro ^:no-doc pydatafy [& types] ;; credit: Tom Spoon ;; https://clojurians.zulipchat.com/#narrow/stream/215609-libpython-clj-dev/topic/feature-requests/near/187056819 `(do ~@(for [t types] `(extend-type ~t clj-proto/Datafiable (datafy [item#] (py-datafy item#)) clj-proto/Navigable (nav [coll# k# v#] (py-nav coll# k# v#)))))) ================================================ FILE: src/libpython_clj2/sugar.clj ================================================ (ns libpython-clj2.sugar (:require [libpython-clj2.python :as py])) (py/initialize!) (let [{{:strs [pyxfn]} :globals} (py/run-simple-string " import collections class Deque: def __init__(self): self.q = collections.deque() def __iter__(self): while True: yield next(self) def __next__(self): return self.q.popleft() def append(self, x): self.q.appendleft(x) def pop(self): self.q.popleft() def pyxfn(g, *args, **kwargs): q = Deque() gx = g(q, *args, **kwargs) return q, gx ")] (def ^:private -pyxfn pyxfn)) (let [builtins (py/import-module "builtins") pynext (py/get-attr builtins "next")] (defn pyxfn [g & args] (fn [rf] (let [[q gx] (apply -pyxfn g args)] (fn ([] (rf)) ([result] (rf result)) ([result input] (py/$a q append input) (rf result (pynext gx)))))))) ================================================ FILE: test/libpython_clj2/classes_test.clj ================================================ (ns libpython-clj2.classes-test (:require [libpython-clj2.python :as py] [clojure.test :refer :all] [clojure.edn :as edn])) (py/initialize!) (deftest new-cls-test ;;The crux of this is making instance functions to get the 'self' parameter ;;passed in. (let [cls-obj (py/create-class "Stock" nil {"__init__" (py/make-instance-fn (fn [self name shares price] ;;Because we did not use an arg-converter, all the ;;arguments above are raw jna Pointers - borrowed ;;references. (py/set-attrs! self {"name" name "shares" shares "price" price}) ;;If you don't return nil from __init__ that is an ;;error. nil)) "cost" (py/make-instance-fn (fn [self] (* (py/py.- self shares) (py/py.- self price))) {:name "cost"}) "__str__" (py/make-instance-fn (fn [self] (pr-str {"name" (py/py.- self name) "shares" (py/py.- self shares) "price" (py/py.- self price)}))) "kw_clj_fn" (py/make-kw-instance-fn (fn [pos-args kw-args] (let [self (first pos-args) price (double (py/py.- self price))] ;;keywords become strings!! (apply + price (get kw-args "a" 5) (drop 1 pos-args))))) "clsattr" 55}) new-instance (cls-obj "ACME" 50 90)] (is (= 4500 (py/$a new-instance cost))) (is (= 55 (py/py.- new-instance clsattr))) (is (= {"name" "ACME", "shares" 50, "price" 90} (edn/read-string (.toString new-instance)))) (is (= 116.0 (py/call-attr-kw new-instance "kw_clj_fn" [1 2 3] {:a 20}))) (is (= 101.0 (py/call-attr-kw new-instance "kw_clj_fn" [1 2 3] nil))) )) (deftest new-kw-init-cls-test ;;The crux of this is making instance functions to get the 'self' parameter ;;passed in. (let [cls-obj (py/create-class "Stock" nil {"__init__" (py/make-kw-instance-fn (fn [[self :as args] {:as kwargs}] (py/set-attr! self "kwargs" kwargs) ;;Because we did not use an arg-converter, all the ;;arguments above are raw jna Pointers - borrowed ;;references. ;;If you don't return nil from __init__ that is an ;;error. nil))}) new-instance (py/cfn cls-obj "ACME" 50 :a 1 :b 2) dict (py/get-attr new-instance "kwargs")] (is (= {"a" 1 "b" 2} (py/->jvm dict))))) ================================================ FILE: test/libpython_clj2/codegen_test.clj ================================================ (ns libpython-clj2.codegen-test (:require [clojure.test :refer [deftest is testing]] [clojure.string :as s] [clojure.java.io :as io] [libpython-clj2.codegen :as codegen])) (defn- ns-symbol-for [py-mod-or-cls ns-prefix] (symbol (str (when-not (s/blank? ns-prefix) (str ns-prefix ".")) py-mod-or-cls))) (deftest ns-prefix-nil-test (testing "ns-prefix nil should not produce leading dot" (is (= 'numpy (ns-symbol-for "numpy" nil))) (is (= 'builtins (ns-symbol-for "builtins" nil)))) (testing "ns-prefix empty string should not produce leading dot" (is (= 'numpy (ns-symbol-for "numpy" ""))) (is (= 'builtins (ns-symbol-for "builtins" "")))) (testing "ns-prefix with value should produce prefixed namespace" (is (= 'python.numpy (ns-symbol-for "numpy" "python"))) (is (= 'my.prefix.builtins (ns-symbol-for "builtins" "my.prefix"))))) (deftest write-namespace-nil-prefix-test (testing "write-namespace! with nil ns-prefix" (let [tmp-dir (str (System/getProperty "java.io.tmpdir") "/libpython-clj-test-" (System/currentTimeMillis))] (try (codegen/write-namespace! "builtins" {:output-dir tmp-dir :ns-prefix nil}) (is (.exists (io/file tmp-dir "builtins.clj"))) (let [content (slurp (io/file tmp-dir "builtins.clj"))] (is (re-find #"\(ns builtins" content))) (finally (doseq [f (reverse (file-seq (io/file tmp-dir)))] (.delete f))))))) ================================================ FILE: test/libpython_clj2/ffi_test.clj ================================================ (ns libpython-clj2.ffi-test "Short low level tests used to verify specific aspects of ffi integration" (:require [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python :as py] [libpython-clj2.python.protocols :as py-proto] [libpython-clj2.python.fn :as py-fn] [clojure.test :refer [deftest is]])) (py/initialize!) (deftest module-type-name-test (py-ffi/with-gil (let [main-mod (py-ffi/PyImport_AddModule "__main__") mod-type (py-ffi/pyobject-type main-mod) mod-name (py-ffi/pytype-name mod-type)] (is (= "module" mod-name))))) (deftest pydir-basic (py-ffi/with-gil (let [main-mod (py-ffi/PyImport_AddModule "__main__") dirdata (py-proto/dir main-mod)] (is (>= (count dirdata) 7))))) (deftest error-handling (py-ffi/with-gil (is (thrown? Exception (py-ffi/run-simple-string "data = 1 +"))))) (deftest clj-fn (py-ffi/with-gil (let [pfn (py-fn/make-tuple-fn #(+ %1 %2))] (is (= 3 (py-fn/call pfn 1 2)))))) ================================================ FILE: test/libpython_clj2/fncall_test.clj ================================================ (ns libpython-clj2.fncall-test (:require [libpython-clj2.python :as py] [clojure.test :refer :all])) (py/initialize!) (deftest complex-fn-test (let [testmod (py/import-module "testcode") testcases (py/py.- testmod complex_fn_testcases)] (is (= (-> (get testcases "complex_fn(1, 2, c=10, d=10, e=10)") (py/->jvm)) (-> (py/$a testmod complex_fn 1 2 :c 10 :d 10 :e 10) (py/->jvm)))) (is (= (-> (get testcases "complex_fn(1, 2, 10, 11, 12, d=10, e=10)") (py/->jvm)) (-> (py/$a testmod complex_fn 1 2 10 11 12 :d 10 :e 10) (py/->jvm)))) (is (= (-> (get testcases "complex_fn(1, 2, c=10, d=10, e=10)") (py/->jvm)) (-> (apply py/afn testmod "complex_fn" [1 2 :c 10 :d 10 :e 10]) (py/->jvm)))) (is (= (-> (get testcases "complex_fn(1, 2, 10, 11, 12, d=10, e=10)") (py/->jvm)) (-> (apply py/afn testmod "complex_fn" [1 2 10 11 12 :d 10 :e 10]) (py/->jvm)))))) ================================================ FILE: test/libpython_clj2/iter_gen_seq_test.clj ================================================ (ns libpython-clj2.iter-gen-seq-test "Iterators/sequences and such are crucial to handling lots of forms of data and thus they have to work correctly between the languages." (:require [libpython-clj2.python :as py] [libpython-clj2.require :refer [require-python]] [clojure.test :refer :all])) (require-python '[builtins :as python]) (deftest generate-sequence-test (let [{{:strs [fortwice]} :globals} (py/run-simple-string " def fortwice(xs): for x in xs: yield x for x in xs: yield x")] (is (= [1 2 3 4 5 6 7 8 9 10] (vec (fortwice (python/map inc (range 10)))))) (is (= [1 2 3 4 5 6 7 8 9 10 1 2 3 4 5 6 7 8 9 10] (vec (fortwice (map inc (range 10)))))) (is (= [1 2 3 4 5 6 7 8 9 10 1 2 3 4 5 6 7 8 9 10] (vec (fortwice (vec (python/map inc (range 10))))))))) ================================================ FILE: test/libpython_clj2/java_api_test.clj ================================================ (ns libpython-clj2.java-api-test (:require [libpython-clj2.java-api :as japi] [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python :as py] [clojure.test :refer [deftest is]])) (deftest base-japi-test (japi/-initialize nil) (with-open [locker (japi/-GILLocker)] (japi/-runStringAsFile "data = 5") (is (= 5 (japi/-getGlobal "data"))) (japi/-setGlobal "data" 6) (is (= 6 (japi/-getGlobal "data"))) ;; (japi/-setGlobal "bdata" (byte-array (range 100))) ;; (is (= :ndarray (py/python-type (japi/-getGlobal "bdata")))) ;; (japi/-setGlobal "bdata" (into-array (repeat 4 (byte-array (range 100))))) ;; (is (= :ndarray (py/python-type (japi/-getGlobal "bdata")))) ;; (japi/-setGlobal "bdata" (into-array (concat (repeat 4 (byte-array (range 100))) ;; [(byte-array (range 10))]))) ;; (is (not= :ndarray (py/python-type (japi/-getGlobal "bdata")))) (let [np (japi/-importModule "numpy") ones-fn (japi/-getAttr np "ones") ;;also works with int-array base-data (ones-fn (java.util.ArrayList. [2 3])) jvm-data (japi/-arrayToJVM base-data)] (is (= "float64" (get jvm-data "datatype"))) (is (= (vec (repeat 6 1.0)) (vec (get jvm-data "data")))) (let [base-data (japi/-callKw ones-fn [[2 3]] {"dtype" "int32"}) jvm-data (japi/-arrayToJVM base-data) data-ary (get jvm-data "data")] (is (= "int32" (get jvm-data "datatype"))) (is (= (vec (repeat 6 1)) (vec data-ary))) (java.util.Arrays/fill ^ints data-ary 25) (japi/-copyData data-ary base-data) (let [jvm-data (japi/-arrayToJVM base-data)] (is (= (vec (repeat 6 25)) (vec (get jvm-data "data"))))))) (try (let [test-fn (-> (japi/-runStringAsFile "def calcSpread(bid,ask):\n\treturn bid-ask\n\n") (get "calcSpread")) n-calls 100000] (let [start-ns (System/nanoTime) _ (dotimes [iter n-calls] (japi/-call test-fn 1 2)) end-ns (System/nanoTime) ms (/ (- end-ns start-ns) 10e6)] (println "Python fn calls/ms" (/ n-calls ms))) ;;low level api (let [call-ctx (japi/-allocateFastcallContext) _ (is (= -1 (japi/-fastcall call-ctx test-fn 1 2))) start-ns (System/nanoTime) _ (dotimes [iter n-calls] (japi/-fastcall call-ctx test-fn 1 2)) end-ns (System/nanoTime) ms (/ (- end-ns start-ns) 10e6)] (japi/-releaseFastcallContext call-ctx) (println "Python fastcall calls/ms" (/ n-calls ms))) ;;high level api (with-open [fcall (japi/-makeFastcallable test-fn)] (is (= -1 (japi/-call fcall 1 2))) (let [start-ns (System/nanoTime) _ (dotimes [iter n-calls] (japi/-call fcall 1 2)) end-ns (System/nanoTime) ms (/ (- end-ns start-ns) 10e6)] (println "Python fastcallable calls/ms" (/ n-calls ms)))) ;;Global setitem pathway (japi/-setGlobal "bid" 1) (japi/-setGlobal "ask" 2) (is (= -1 (japi/-runStringAsInput "bid-ask"))) (let [start-ns (System/nanoTime) _ (dotimes [iter n-calls] (japi/-setGlobal "bid" 1) (japi/-setGlobal "ask" 2) (japi/-runStringAsInput "bid-ask")) end-ns (System/nanoTime) ms (/ (- end-ns start-ns) 10e6)] (println "Python setglobal pathway calls/ms" (/ n-calls ms))))))) (defn only-string-input [] (let [gilstate (japi/-lockGIL) n-calls 5000000] (try (dotimes [iter n-calls] (japi/-setGlobal "bid" 1.1) (japi/-setGlobal "ask" 2.2) (japi/-runStringAsInput "bid-ask")) (finally (japi/-unlockGIL gilstate))))) ================================================ FILE: test/libpython_clj2/numpy_test.clj ================================================ (ns libpython-clj2.numpy-test (:require [clojure.test :refer [deftest is]] [libpython-clj2.python :as py] [tech.v3.datatype :as dtype] [tech.v3.datatype.functional :as dfn] [tech.v3.tensor :as dtt])) (py/initialize!) (def np-mod (py/import-module "numpy")) ;;The basic math operations of the dfn namespace must work on numpy objects. (deftest basic-numpy (let [test-data [[1 2] [3 4]] np-ary (py/$a np-mod array test-data) tens (dtt/->tensor test-data)] (is (dfn/equals (dtt/ensure-tensor np-ary) tens)) (is (dfn/equals [1 2 3 4] (dtype/make-container :java-array :int64 np-ary))))) ================================================ FILE: test/libpython_clj2/python_test.clj ================================================ (ns libpython-clj2.python-test (:require [libpython-clj2.python :as py :refer [py. py.. py.- py* py**]] ;;support for tensor/numpy integration [libpython-clj2.python.np-array] [libpython-clj2.python.ffi :as py-ffi] [tech.v3.datatype :as dtype] [tech.v3.datatype.functional :as dfn] [tech.v3.datatype.ffi :as dt-ffi] [tech.v3.tensor :as dtt] [clojure.test :refer :all] libpython-clj2.python.bridge-as-python) (:import [java.io StringWriter] [java.util Map List] [tech.v3.datatype.ffi Pointer])) (py/initialize!) (py-ffi/enable-gil-check!) ;; Useful to see how many times we convert a string to a python object. ;; (dt-ffi/enable-string->c-stats!) ;; (.addShutdownHook (Runtime/getRuntime) (Thread. ;; (fn [] ;; (clojure.pprint/pprint ;; (dt-ffi/string->c-data-histogram))))) (deftest stdout-and-stderr (is (= "hey\n" (with-out-str (py/run-simple-string "print('hey')")))) (is (= "hey\n" (let [custom-writer (StringWriter.)] (with-bindings {#'*err* custom-writer} (py/run-simple-string "import sys\nprint('hey', file=sys.stderr)")) (.toString custom-writer)))) ;;Python exceptions get translated into actual java exceptions. (is (thrown? Throwable (py/run-simple-string "import sys\nprint('hey', stderr")))) (deftest dicts (py/with-gil-stack-rc-context (let [py-dict (py/->python {:a 1 :b 2})] (is (= :dict (py/python-type py-dict))) (is (= 2 (-> (py/call-attr py-dict "__len__") (py/->jvm)))) (is (= {"a" 1 "b" 2} (->> (py/->jvm py-dict) (into {})))) (let [bridge-dict (py/as-jvm py-dict)] (is (instance? Map bridge-dict)) (is (= #{"a" "b"} (->> (keys bridge-dict) set))) (is (= #{1 2} (->> (vals bridge-dict) set))) (is (= {"a" 1 "b" 2} (into {} bridge-dict))))))) (deftest lists (let [py-list (py/->py-list [4 3 2 1])] (is (= :list (py/python-type py-list))) (is (= 4 (py/call-attr py-list "__len__"))) (is (= [4 3 2 1] (->> (py/->jvm py-list) (into [])))) (let [bridge-list (py/as-jvm py-list)] (is (instance? List bridge-list)) (is (= [4 3 2 1] (into [] bridge-list))) ;;This actually calls the python sort function. (.sort ^List bridge-list nil) (is (= [1 2 3 4] (into [] bridge-list)))))) (deftest global-dict (let [main-module (py/add-module "__main__") ^Map globals (-> (py/module-dict main-module) (py/as-jvm))] (is (instance? Map globals)) (.put globals "item" 100) (py/set-item! globals "item2" 200) ;;During run-simple-string, if nothing else is specified the ;;global map is used as a local map. (py/run-simple-string "item3 = item + item2") (is (= 300 (globals "item3"))))) (deftest numpy-and-back (let [jvm-tens (dtt/->tensor (->> (range 9) (partition 3)) :datatype :float64)] (let [py-tens (py/->python jvm-tens)] (is (= [[0.0 1.0 2.0] [3.0 4.0 5.0] [6.0 7.0 8.0]] (-> (dtt/as-tensor py-tens) dtt/->jvm))) ;;This operation is in-place (let [py-trans (py/call-attr py-tens "transpose" [1 0])] (is (= [[0.0 1.0 2.0] [3.0 4.0 5.0] [6.0 7.0 8.0]] (-> (dtt/as-tensor py-tens) dtt/->jvm))) (is (= [[0.0 3.0 6.0] [1.0 4.0 7.0] [2.0 5.0 8.0]] (-> (dtt/as-tensor py-trans) dtt/->jvm))) ;;But they are sharing backing store, so mutation will travel both ;;ways. Creepy action at a distance indeed (dtype/copy! [5 6 7] (nth (dtt/as-tensor py-trans) 0)) (is (= [[5.0 1.0 2.0] [6.0 4.0 5.0] [7.0 7.0 8.0]] (-> (dtt/as-tensor py-tens) dtt/->jvm)))) (let [main-module (py/add-module "__main__") ^Map globals (-> (py/module-dict main-module) (py/as-jvm))] (py/set-item! globals "np_ary" py-tens) (py/run-simple-string "np_ary[2,2] = 100") (is (= [[5.0 1.0 2.0] [6.0 4.0 5.0] [7.0 7.0 100.0]] ;;zero copy almost always works the other way, however. So there is ;;py/->tensor available. Copying the numpy object will allow the ;;zero copy pathway to work. (-> (dtt/as-tensor py-tens) dtt/->jvm))))))) (deftest numpy-scalars (let [np (py/import-module "numpy") scalar-constructors (concat ["float64" "float32"] (for [int-type ["int" "uint"] int-width [8 16 32 64]] (str int-type int-width)))] (doseq [constructor scalar-constructors] (is (= 3.0 (-> (py/call-attr np constructor 3.0) double)) (str "Item type " constructor))))) (deftest dict-with-complex-key (let [py-dict (py/->python {["a" "b"] 1 ["c" "d"] 2}) bridged (py/as-jvm py-dict)] (is (= #{["a" "b"] ["c" "d"]} (->> (keys bridged) ;;Bridged tuples are lists, not persistent vectors. (map vec) set))))) (deftest simple-print-crashed (let [numpy (py/import-module "numpy")] (println (dtt/as-tensor (py/call-attr numpy "ones" [3 3]))))) (deftest true-false-list (is (= [false true] (-> '(false true) py/->py-list py/->jvm)))) (deftest true-false-true-numpy (let [numpy (py/import-module "numpy")] (is (= [true false true] (->> (for [a (py/call-attr numpy "array" [true false true])] a) vec))))) (deftest aspy-iter (let [testcode-module (py/import-module "testcode")] (is (= [1 2 3 4 5] (-> (py/call-attr testcode-module "for_iter" (py/as-python [1 2 3 4 5])) (py/->jvm)))) (is (= ["a" "b" "c"] (-> (py/call-attr testcode-module "for_iter" (py/as-python {"a" 1 "b" 2 "c" 3})) (py/->jvm)))))) (deftest basic-with-test (let [testcode-module (py/import-module "testcode")] (let [fn-list (py/->py-list [])] (is (nil? (py/with [item (py/call-attr testcode-module "WithObjClass" true fn-list)] (py/call-attr item "doit_err")))) (is (= ["enter" "exit: ('Spam', 'Eggs')"] (py/->jvm fn-list)))) (let [fn-list (py/->py-list [])] (is (= 1 (py/with [item (py/call-attr testcode-module "WithObjClass" true fn-list)] (py/call-attr item "doit_noerr")))) (is (= ["enter" "exit: None"] (py/->jvm fn-list)))) (let [fn-list (py/->py-list [])] (is (thrown? Throwable (py/with [item (py/call-attr testcode-module "WithObjClass" false fn-list)] (py/call-attr item "doit_err")))) (is (= ["enter" "exit: ('Spam', 'Eggs')"] (py/->jvm fn-list)))) (let [fn-list (py/->py-list [])] (py/with [item (py/call-attr testcode-module "WithObjClass" false fn-list)] (py/call-attr item "doit_noerr")) (is (= ["enter" "exit: None"] (py/->jvm fn-list)))))) (deftest with-enter-returns-different-object (testing "py/with should bind the return value of __enter__, not the context manager" (let [testcode (py/import-module "testcode")] (py/with [f (py/call-attr testcode "FileWrapper" "test content")] ;; f should be the StringIO object returned by __enter__, not FileWrapper (is (= "test content" (py/call-attr f "read"))))))) (deftest arrow-as-fns-with-nil (is (= nil (py/->jvm nil))) (is (= nil (py/as-jvm nil)))) (deftest pydict-nil-get (let [dict (py/->python {:a 1 :b {:a 1 :b 2}}) bridged (py/as-jvm dict)] (is (= nil (bridged nil))))) (deftest bridged-dict-to-jvm (let [py-dict (py/->py-dict {:a 1 :b 2}) bridged (py/as-jvm py-dict) copied-back (py/->jvm bridged)] (is (instance? clojure.lang.PersistentArrayMap copied-back)))) (deftest calling-conventions (let [np (py/import-module "numpy") linspace (py/py.. np -linspace)] (is (dfn/equals [2.000 2.250 2.500 2.750 3.000] (dtt/as-tensor (linspace 2 3 :num 5)))) (is (dfn/equals [2.000 2.250 2.500 2.750 3.000] (dtt/as-tensor (py/$c linspace 2 3 :num 5)))) (is (dfn/equals [2.000 2.250 2.500 2.750 3.000] (dtt/as-tensor (py/$a np linspace 2 3 :num 5)))))) (deftest syntax-sugar (py/initialize!) (let [np (py/import-module "numpy")] (is (= (str (py/py.- np linspace)) (str (py/get-attr np "linspace")))) (is (= (str (py/py.. np -random -shuffle)) (str (-> (py/get-attr np "random") (py/get-attr "shuffle")))))) (let [builtins (py/import-module "builtins") l (py/call-attr builtins "list")] (is (= (py/py. l __len__) 0)) (py/py. l append 1) (is (= (py/py. l __len__) 1)) (py/py.. l (extend [1 2 3])) (is (= ((py/py.- l __len__)) 4))) (let [sys (py/import-module "sys")] (is (int? (py/py.. sys -path __len__)))) (let [{{Foo :Foo} :globals} (py/run-simple-string " class Foo: def __init__(self, a, b): self.a = a self.b = b self._res = [] def res(self): return self._res def extend(self, arg): self._res.extend(arg) return self def count(self): return len(self._res) def append(self, *args): return self.extend(args) def math(self, c): return self.append(self.a + self.b + c) ") f (Foo 1 2)] (is (= [] ((py/py.- f res)) (py/py. f res))) (is (= 6 (py/py.. f (append 1) (append 2) (math 3) (extend [4 5 6]) count))) (is (= [1 2 6 4 5 6] ((py/py.- f res)) (py/py. f res))) (is (= 6 (py/py.. f res __len__) ((py/py.. f res -__len__)) (py/py.. f count) ((py/py.. f -count))))) (let [builtins (py/import-module "builtins") dict (py/get-attr builtins "dict") d (dict)] (py* d update nil {:a 1}) (is (= 1 (py* d get [:a]))) (let [iterable [[:a 2]]] (py* d update [iterable])) (is (= 2 (py* d get [:a]))) (let [iterable [[:a 1] [:b 2]] kwargs {:name "taco"}] (py* d update [iterable] kwargs)) (is (= {"name" "taco" "a" 1 "b" 2} d)) (py. d clear) (py** d update {:a 1}) (is (= d {"a" 1})) (py** d update [[:a 2]] {:c 3}) (is (= d {"a" 2 "c" 3})) (py. d clear) (doto d (py.. (*update nil {:a 1})) (py.. (*update [[[:b 2]]])) (py.. (**update {:c 3})) (py.. (**update [[:d 4]] {:e 5}))) (is (= d {"a" 1 "b" 2 "c" 3 "d" 4 "e" 5})))) (deftest infinite-seq (let [islice (-> (py/import-module "itertools") (py/get-attr "islice"))] (is (= (vec (range 10)) ;;Range is an infinite sequence (-> (range) (islice 0 10) (vec)))))) (deftest persistent-vector-nparray (testing "Create numpy array from nested persistent vectors" (let [ary-data (-> (py/import-module "numpy") (py/$a array [[1 2 3] [4 5 6]]))] (is (dfn/equals (dtt/->tensor [[1 2 3] [4 5 6]]) (dtt/as-tensor ary-data)))))) (deftest python-tuple-equals (testing "Python tuples have nice equal semantics." (let [lhs (py/->py-tuple [1 2]) same (py/->py-tuple [1 2]) not-same (py/->py-tuple [3 4])] (is (= lhs same)) (is (not= lhs not-same)) (is (= (.hashCode lhs) (.hashCode same))) (is (not= (.hashCode lhs) (.hashCode not-same)))))) (deftest range-nparray (let [ary-data (-> (py/import-module "numpy") (py/$a array (range 10)))] (is (dfn/equals (dtt/->tensor (range 10)) (dtt/as-tensor ary-data))))) (deftest false-is-always-py-false (let [py-false (py-ffi/py-false) ->false (py/->python false) as-false (py/as-python false)] (is (= (dt-ffi/->pointer py-false) (dt-ffi/->pointer ->false))) (is (= (dt-ffi/->pointer py-false) (dt-ffi/->pointer as-false))))) (deftest instance-abc-classes (let [py-dict (py/->python {"a" 1 "b" 2}) bridged-dict (py/as-python {"a" 1 "b" 2}) bridged-iter (py/as-python (repeat 5 1)) bridged-list (py/as-python (vec (range 10))) pycol (py/import-module "collections.abc") mapping-type (py/get-attr pycol "Mapping") iter-type (py/get-attr pycol "Iterable") sequence-type (py/get-attr pycol "Sequence")] (is (py/is-instance? py-dict mapping-type)) (is (py/is-instance? bridged-dict mapping-type)) (is (py/is-instance? bridged-iter iter-type)) (is (py/is-instance? bridged-list sequence-type)))) (deftest nested-map-and-back (let [py-dict (-> (py/run-simple-string "testdata={'camera_id': 'CODOT-10106-12067', 'country': 'United States', 'state': 'Colorado', 'city': 'Fountain', 'provider': 'CO DOT', 'description': '0.6 mi N of Ray Nixon Rd Int', 'direction': 'North', 'video': False, 'links': {'jpeg': {'url': 'https://www.cotrip.org/dimages/camera?imageURL=remote/CTMCCAM025S125-20-N.jpg'}}, 'tags': ['auto_rerated'], 'ratings': {'road_weather': 4, 'visibility': 4}, 'health': {}, 'created_at': '2016-04-19T20:27:45.030Z', 'time_zone_offset': -25200}") (get-in [:globals "testdata"])) jvm-dict (py/->jvm py-dict)] (is (= (get jvm-dict "ratings") (py/->jvm (py/get-item py-dict "ratings")))))) (deftest characters (is (= (py/->jvm (py/->python "c")) (py/->jvm (py/->python \c))))) (deftest numpy-all (let [np (py/import-module "numpy")] (is (= true (py/call-attr np "all" (py/call-attr np "array" [true true true])))) (is (= false (py/call-attr np "all" (py/call-attr np "array" [true false true])))))) (deftest np-dot (let [np (py/import-module "numpy") np-dot (py/get-attr np "dot") np-ary (py/call-attr np "array" [1 2 3])] (is (== 14 (np-dot np-ary np-ary))))) (deftest ->python-expands-sequences (let [test-dict {:a (seq [1 2 3 4 5 7 8 9])} py-dict (py/->python test-dict) py-data (py/get-item py-dict "a")] (is (= 8 (py/call-attr py-data "__len__"))))) (deftest python-as-jvm-destructuring (let [py-dict (py/->python {:a 1}) jvm-py-dict (py/as-jvm py-dict) {:keys [a b]} jvm-py-dict] (is (nil? b)))) (deftest incorrect-numpy-marshal (let [np (py/import-module "numpy") p (py/$a np full [2 5] 7) tp (py/get-attr np "transpose") pp (tp p)] (is (= [5 2] (py/->jvm (py/get-attr pp "shape")))))) (deftest iter-should-not-npe ;; credit Carsten Behring (is (true? (boolean (py. (libpython-clj2.python.bridge-as-python/map-as-python {}) __iter__))))) (deftest call-attr-test (let [np (py/import-module "numpy") random (py/get-attr np "random") data (py/call-attr random :randn 8 6)] (is (= [8 6] (dtype/shape (py/call-attr random :randn 8 6)))))) (comment (require '[libpython-clj.require :refer [require-python]]) (require-python '[pandas :as pd]) (require-python '[plotly.express :as px]) (def px (py/import-module "plotly.express")) (let [data (doto (pd/DataFrame {:index [1 2] :value [2 3] :variable [1 1]}) (py. melt :id_vars "index"))] (py. px line :data_frame data :x "index" :y "value" :color "variable")) (let [data (doto (pd/DataFrame {:index [1 2] :value [2 3] :variable [1 1]}) (py. melt :id_vars "index"))] ((py.- px line) :data_frame data :x "index" :y "value" :color "variable"))) ================================================ FILE: test/libpython_clj2/require_python_test.clj ================================================ (ns libpython-clj2.require-python-test (:require [libpython-clj2.require :as req :refer [require-python pydafy pynav] :reload true] [libpython-clj2.python :as py] [clojure.test :refer :all] [clojure.datafy :refer [datafy nav]])) ;; Since this test mutates the global environment we have to accept that ;; it may not always work. (require-python '[math :refer :* :exclude [sin cos] :as pymath]) (deftest base-require-test (let [publics (ns-publics (find-ns 'libpython-clj2.require-python-test))] (is (not (contains? publics 'sin))) (is (= 10.0 (double (floor 10.1)))) (is (thrown? Throwable (require-python '[math :refer [blah]]))))) (deftest parse-flags-test ;; sanity check (is (= #{:reload :foo} #{:foo :reload})) (let [parse-flags #'req/parse-flags] (is (= #{:reload} (parse-flags #{:reload} '[:reload foo]))) (is (= #{:reload} (parse-flags #{:reload} '[:reload true]))) (is (= #{:reload} (parse-flags #{:reload} '[:reload :as foo]))) (is (= #{:reload} (parse-flags #{:reload} '[:reload foo :as]))) (is (= #{:reload} (parse-flags #{:reload} '[foo :reload :as bar]))) (is (= #{} (parse-flags #{:reload} '[:reload false]))) (is (= #{:reload} (parse-flags #{:reload} '[:reload false :reload]))) (is (= #{:reload} (parse-flags #{:reload} '[:reload false :reload true]))) (is (= #{} (parse-flags #{:reload} '[:reload :reload false]))) (is (= #{} (parse-flags #{:reload} '[:reload true :reload false]))) (is (= #{:a :b} (parse-flags #{:a :b} '[:a true :b]))) (is (= #{:a :b} (parse-flags #{:a :b} '[:a :b]))) (is (= #{:a :b} (parse-flags #{:a :b} '[:a true :b]))) (is (= #{:a :b} (parse-flags #{:a :b} '[:a :b true]))) (is (= #{:a :b} (parse-flags #{:a :b} '[:a true :b true]))) (is (= #{:b} (parse-flags #{:a :b} '[:a false :b true]))) (is (= #{:b} (parse-flags #{:a :b} '[:b true :a false]))) (is (= #{:b} (parse-flags #{:a :b} '[:b :a false]))) (is (= #{:b :a} (parse-flags #{:a :b} '[:b :a false :a true]))))) (require-python '[builtins :as python] '[builtins.list :as python.pylist]) ;; NOTE -- even though builtins.list has been aliased to ;; to python.pylist, you are still required to require ;; "builtins as python" in order to construct a list (deftest require-python-classes-with-alias-test (let [l (python/list)] (is (= (vec l) [])) (python.pylist/append l 1) (is (= (vec l) [1])) (python.pylist/append l 3) (is (= (vec l) [1 3])) (python.pylist/append l 5) (is (= (vec l) [1 3 5])) (python.pylist/clear l) (is (= (python/list) (vec l))))) (require-python 'csv.DictWriter) (deftest require-python-classes ;; simple creation/recall test (is csv.DictWriter/__init__) (is csv.DictWriter/writeheader) (is csv.DictWriter/writerow) (is csv.DictWriter/writerows)) (deftest test-req-transform (let [req-transform #'libpython-clj2.require/req-transform] (is (= (req-transform 'a) 'a)) (is (= (req-transform '(a b c)) '(a.b a.c))) (is (= (req-transform '(a [b :as c :refer [blah]])) (list '[a.b :as c :refer [blah]]))) (is (= (req-transform '(a [b :as c :refer [x] :flagA] d)) (list '[a.b :as c :refer [x] :flagA] 'a.d))) (is (= (req-transform 'a 'b) 'a.b)) (is (= (req-transform 'a.b 'c) 'a.b.c)) (is (thrown? Exception (req-transform 'a.b 'c.d))) (is (= (req-transform 'a '[b]) '[a.b])) (is (= (req-transform 'a '[b :as c :refer [blah] :flagA]) '[a.b :as c :refer [blah] :flagA])))) (deftest datafy-test (defmethod pydafy 'builtins.list [x] (vec x)) (is (vector? (datafy (python/list [1 2 3])))) (defmethod pydafy 'builtins.frozenset [x] (set x)) (is (set? (datafy (python/frozenset [1 2 3]))))) (deftest import-python-test (is (= :ok (libpython-clj2.require/import-python)))) (require-python '[socket :bind-ns true]) (require-python 'socket.SocketIO) (deftest metadata-test (testing "metadata generation" ;; module meta (let [{line :line file :file} (meta #'socket)] (is (= 1 line) "Modules have line numbers") (is (string? file) "Modules have file paths")) ;; class meta (let [{line :line file :file} (meta #'socket/SocketIO)] (is (int? line) "Classes have line numbers") (is (string? file) "Classes have file paths")) ;; function meta (let [{line :line file :file} (meta #'socket/_intenum_converter)] (is (int? line) "Functions have line numbers") (is (string? file) "Functions have file paths")) ;; method meta (let [{line :line file :file} (meta #'socket.SocketIO/readable)] (is (int? line) "Methods have line numbers") (is (string? file) "Methods have file paths")))) (deftest convert-types (let [typing-module (py/import-module "typing")] (testing "convert generic alias type to JVM" (-> (py/py. typing-module GenericAlias list str) py/->jvm :type (= :generic-alias) is)))) ================================================ FILE: test/libpython_clj2/stress_test.clj ================================================ (ns libpython-clj2.stress-test "A set of tests meant to crash the system or just run the system out of memory if it isn't setup correctly." (:require [libpython-clj2.python :as py] [libpython-clj2.python.ffi :as py-ffi] [libpython-clj2.python.fn :as py-fn] [libpython-clj2.python.class :as py-class] [clojure.test :refer :all] [clojure.edn :as edn])) (py/initialize!) (def test-script (memoize (fn [] (-> (py/run-simple-string " import itertools def getdata(): while True: yield {'a': 1, 'b': 2} def print_data(): print(\"hey\") def getmultidata(): a = {'disableReason': 'None', 'generationNumber': 1186, 'leDomain': 0, 'protocol': 'FC', 'index': 197, 'authentication': 'None', 'physicalID': 4, 'cFlags': ['0x1'], 'wwn': '20:c5:00:05:1e:ba:a7:00', 'scn': 'Offline', 'health': 'OFFLINE', 'connectionSpeed': 'N8Gbps', 'shareIFID': None, 'id': '586a6086ce8d6e5d86a0a04b', 'flags': ['0x4001', 'PRESENT', 'LED'], 'portID': '01c500', 'storagecenterSnapshotType': 'live', 'transitionCount': 1, 'portType': 17.0, 'podPort': None, 'name': 'slot9 port21', 'deviceNumber': 267654, 'isPartOtherAD': False, 'creditRecovery': 'Inactive', 'distance': 'normal', 'storagecenterSnapshotTime': '2019-11-04T14:12:20.740000+00:00', 'scnID': 2, 'portIFID': '4392001d', 'fcFastwrite': False, 'state': 'Offline', 'wwnConnected': [], 'faa': 'Inactive', 'localSwcFlags': ['0x0'], 'stateID': 2, 'aoq': 'Inactive', 'physical': 'No_Light', 'peerBeacon': False} b = {'disableReason': 'None', 'generationNumber': 0, 'leDomain': 0, 'protocol': 'FC', 'index': 777, 'authentication': 'None', 'physicalID': 6, 'cFlags': ['0x1'], 'wwn': '50:00:53:32:3d:6f:73:09', 'scn': 'Online', 'health': 'HEALTHY', 'connectionSpeed': 'N8Gbps', 'shareIFID': None, 'id': '586a603560a298494d6a5e97', 'flags': ['0x24b03', 'PRESENT', 'ACTIVE', 'F_PORT', 'G_PORT', 'LOGICAL_ONLINE', 'LOGIN', 'NOELP', 'LED', 'ACCEPT'], 'portID': '3d8d80', 'storagecenterSnapshotType': 'deleted', 'transitionCount': 0, 'portType': 17.0, 'podPort': None, 'name': 'slot1 port57', 'deviceNumber': 365521, 'isPartOtherAD': None, 'creditRecovery': 'Inactive', 'distance': 'normal', 'storagecenterSnapshotTime': '2018-06-07T02:12:16.083000+00:00', 'scnID': 1, 'portIFID': '43120039', 'fcFastwrite': False, 'state': 'Online', 'wwnConnected': ['21:00:00:24:ff:f7:37:01'], 'faa': 'Inactive', 'localSwcFlags': ['0x0'], 'stateID': 1, 'aoq': 'Inactive', 'physical': 'In_Sync', 'peerBeacon': False} c = {'disableReason': 'None', 'generationNumber': 0, 'leDomain': 0, 'protocol': 'FC', 'index': 127, 'authentication': 'None', 'physicalID': 4, 'cFlags': ['0x1'], 'wwn': '20:7f:00:05:33:61:48:01', 'scn': 'Offline', 'health': 'OFFLINE', 'connectionSpeed': 'N8Gbps', 'shareIFID': None, 'id': '5c7d9d73c146f2bb9dd1a48c', 'flags': ['0x1', 'PRESENT'], 'portID': '42e000', 'storagecenterSnapshotType': 'live', 'transitionCount': 1, 'portType': 17.0, 'podPort': None, 'name': 'slot12 port15', 'deviceNumber': 382664, 'isPartOtherAD': None, 'creditRecovery': 'Inactive', 'distance': 'normal', 'storagecenterSnapshotTime': '2019-03-04T21:49:38.234000+00:00', 'scnID': 2, 'portIFID': '43c20037', 'fcFastwrite': False, 'state': 'Offline', 'wwnConnected': [], 'faa': None, 'localSwcFlags': ['0x0'], 'stateID': 2, 'aoq': None, 'physical': 'No_Light', 'peerBeacon': False} d = {'disableReason': 'None', 'generationNumber': 506, 'leDomain': 0, 'protocol': 'FC', 'index': 187, 'authentication': 'None', 'physicalID': 4, 'cFlags': ['0x1'], 'wwn': '20:bb:00:05:33:24:6a:01', 'scn': 'Offline', 'health': 'OFFLINE', 'connectionSpeed': 'N8Gbps', 'shareIFID': None, 'id': '586a604a1d2c89767dc345f1', 'flags': ['0x4001', 'PRESENT', 'LED'], 'portID': '3ed100', 'storagecenterSnapshotType': 'live', 'transitionCount': 1, 'portType': 17.0, 'podPort': None, 'name': 'slot4 port27 DISABLED server 640461 seg config', 'deviceNumber': 365522, 'isPartOtherAD': None, 'creditRecovery': 'Inactive', 'distance': 'normal', 'storagecenterSnapshotTime': '2019-10-18T13:10:24.968000+00:00', 'scnID': 2, 'portIFID': '4342100b', 'fcFastwrite': False, 'state': 'Offline', 'wwnConnected': [], 'faa': 'Inactive', 'localSwcFlags': ['0x0'], 'stateID': 2, 'aoq': 'Inactive', 'physical': 'No_Light', 'peerBeacon': False} for x in itertools.cycle([a, b, c, d]): yield x ") :globals)))) (defn get-data [] (let [gd-fn (-> (test-script) (get "getdata"))] (gd-fn))) (defn print-data [] (let [pr-fn (-> (test-script) (get "print_data"))] (pr-fn))) (defn get-multi-data [] (let [gd-fn (-> (test-script) (get "getmultidata"))] (gd-fn))) (deftest forever-test (doseq [items (take 10 (partition 999 (get-data)))] ;;One way is to use the GC (time (do (last (eduction (map py/->jvm) (map (partial into {})) items)) (System/gc))) ;;A faster way is to grab the gil and use the resource system ;;This also ensures that resources within that block do not escape (time (py/with-gil-stack-rc-context (last (eduction (map py/->jvm) (map (partial into {})) items)))))) (deftest multidata-test (doseq [items (take 5 (partition 1000 (get-multi-data)))] (time (do (py/with-gil-stack-rc-context (mapv py/->jvm items)) :ok)))) (deftest str-marshal-test (let [test-str (py/->python "a nice string to work with")] (time (py/with-gil-stack-rc-context (dotimes [iter 1000] (py/->jvm test-str)))))) (deftest dict-marshal-test (let [test-item (py/->python {:a 1 :b 2})] (time (py/with-gil-stack-rc-context (dotimes [iter 100] (py/->jvm test-item)))))) (deftest print-stress-test (dotimes [iter 100] (with-out-str (print-data)))) (deftest new-cls-stress-test (dotimes [iter 100] (py/with-gil-stack-rc-context (let [test-cls (py-class/create-class "testcls" nil {"__init__" (py-class/make-tuple-instance-fn (fn [self name shares price] (py/set-attr! self "name" name) (py/set-attr! self "shares" shares) (py/set-attr! self "price" price) nil)) "cost" (py-class/make-tuple-instance-fn (fn [self] (let [self (py/as-jvm self)] (* (py/py.- self shares) (py/py.- self price))))) "__str__" (py-class/make-tuple-instance-fn (fn [self] (let [self (py/as-jvm self)] ;;Self is just a dict so it converts to a hashmap (pr-str {"name" (py/py.- self name) "shares" (py/py.- self shares) "price" (py/py.- self price)})))) "testvar" 55}) new-inst (test-cls "ACME" 50 90)] (is (= 4500 (py/$a new-inst cost))) (is (= 55 (py/py.- new-inst testvar))) (is (= {"name" "ACME", "shares" 50, "price" 90} (edn/read-string (.toString new-inst)))))))) (deftest fastcall (let [gilstate (py-ffi/lock-gil)] (try ;;Without fastcall callsite optimization (let [test-fn (-> (py/run-simple-string "def calcSpread(bid,ask):\n\treturn bid-ask\n\n") :globals (get "calcSpread")) n-calls 100000] (let [start-ns (System/nanoTime) _ (dotimes [iter n-calls] (test-fn 1 2)) end-ns (System/nanoTime) ms (/ (- end-ns start-ns) 10e6)] (println "Python calls/ms" (/ n-calls ms))) ;;low level api (let [call-ctx (py-fn/allocate-fastcall-context) _ (is (= -1 (py-fn/fastcall call-ctx test-fn 1 2))) start-ns (System/nanoTime) _ (dotimes [iter n-calls] (py-fn/fastcall call-ctx test-fn 1 2)) end-ns (System/nanoTime) ms (/ (- end-ns start-ns) 10e6)] (py-fn/release-fastcall-context call-ctx) (println "Python fastcall calls/ms" (/ n-calls ms))) ;;high level api (with-open [callable (py-fn/make-fastcallable test-fn)] (is (= -1 (callable 1 2))) (let [start-ns (System/nanoTime) _ (dotimes [iter n-calls] (callable 1 2)) end-ns (System/nanoTime) ms (/ (- end-ns start-ns) 10e6)] (println "Python fastcallable calls/ms" (/ n-calls ms))))) (finally (py-ffi/unlock-gil gilstate))))) ================================================ FILE: test/libpython_clj2/sugar_test.clj ================================================ (ns libpython-clj2.sugar-test (:require [libpython-clj2.sugar :as pysug :reload true] [clojure.test :refer :all] [libpython-clj2.python :as py])) (deftest test-pyxfn (let [{{:strs [addem addx addxkwargs stringify addbang]} :globals} (py/run-simple-string " def addem(nums): for num in nums: yield num + num def addx(nums, x): for num in nums: yield num + x def addxkwargs(nums, *, x=None): if x is None: raise Exception('x should not be None') for num in nums: yield num + x def stringify(xs): for x in xs: yield str(x) def addbang(xs): for x in xs: yield '{}!'.format(x) ")] (is (= [0 2 4 6 8 10 12 14 16 18] (into [] (pysug/pyxfn addem) (range 10)))) (is (= [1 2 3 4 5] (into [] (pysug/pyxfn addx 1) (range 5)))) (is (= [1 2 3 4 5] (into [] (pysug/pyxfn addxkwargs :x 1) (range 5)))) (is (= ["00!" "11!" "22!" "33!"] (transduce (comp (pysug/pyxfn stringify) (pysug/pyxfn addem) (pysug/pyxfn addbang)) (completing conj) [] (range 4)))) (is (= ["33!" "22!" "11!" "00!"] (transduce (comp (pysug/pyxfn stringify) (pysug/pyxfn addem) (pysug/pyxfn addbang)) (fn ([result] ((comp vec reverse) result)) ([result input] (conj result input))) [] (range 4)))) (is (= [["22!" "33!"] ["00!" "11!"]] (transduce (comp (pysug/pyxfn stringify) (pysug/pyxfn addem) (pysug/pyxfn addbang) (partition-all 2)) (fn ([result] ((comp vec reverse) result)) ([result input] (conj result input))) [] (range 4)))))) ================================================ FILE: testcode/__init__.py ================================================ class WithObjClass: def __init__(self, suppress, fn_list): self.suppress = suppress self.fn_list = fn_list def __enter__(self): self.fn_list.append("enter") return self # Return self so methods can be called on the bound variable def doit_noerr(self): return 1 def doit_err(self): raise Exception("Spam", "Eggs") def __exit__(self, ex_type, ex_val, ex_traceback): self.fn_list.append("exit: " + str(ex_val)) return self.suppress class FileWrapper: """Context manager where __enter__ returns a different object""" def __init__(self, content): self.content = content def __enter__(self): # Return a different object with the content import io return io.StringIO(self.content) def __exit__(self, *args): return False def for_iter(arg): retval = [] for item in arg: retval.append(item) return retval def calling_custom_clojure_fn(arg): return arg.clojure_fn() def complex_fn(a, b, c: str = 5, *args, d=10, **kwargs): return {"a": a, "b": b, "c": c, "args": args, "d": d, "kwargs": kwargs} complex_fn_testcases = { "complex_fn(1, 2, c=10, d=10, e=10)": complex_fn(1, 2, c=10, d=10, e=10), "complex_fn(1, 2, 10, 11, 12, d=10, e=10)": complex_fn( 1, 2, 10, 11, 12, d=10, e=10 ), } ================================================ FILE: topics/Usage.md ================================================ # LibPython-CLJ Usage Python objects are essentially two dictionaries, one for 'attributes' and one for 'items'. When you use python and use the '.' operator, you are referencing attributes. If you use the '[]' operator, then you are referencing items. Attributes are built in, item access is optional and happens via the `__getitem__` and `__setitem__` attributes. This is important to realize in that the code below doesn't look like python because we are referencing the item and attribute systems by name and not via '.' or '[]'. This would result in the following analogous code (full example [further on](#dataframe-access-full-example)): ```python table.loc[row_date] ``` ```clojure (get-item (get-attr table :loc) row-date) ``` ### Installation #### Ubuntu ```console sudo apt install libpython3.6 # numpy and pandas are required for unit tests. Numpy is required for # zero copy support. python3.6 -m pip install numpy pandas --user ``` #### MacOSX Python installation instructions [here](https://docs.python-guide.org/starting/install3/osx/). ### Initialize python ```clojure user> (require '[libpython-clj2.python :refer [as-python as-jvm ->python ->jvm get-attr call-attr call-attr-kw get-item initialize! run-simple-string add-module module-dict import-module python-type dir] :as py]) nil ; Mac and Linux user> (initialize!) Jun 30, 2019 4:47:39 PM clojure.tools.logging$eval7369$fn__7372 invoke INFO: executing python initialize! Jun 30, 2019 4:47:39 PM clojure.tools.logging$eval7369$fn__7372 invoke INFO: Library python3.6m found at [:system "python3.6m"] Jun 30, 2019 4:47:39 PM clojure.tools.logging$eval7369$fn__7372 invoke INFO: Reference thread starting :ok ; Windows with Anaconda (initialize! ; Python executable :python-executable "C:\\Users\\USER\\AppData\\Local\\Continuum\\anaconda3\\python.exe" ; Python Library :library-path "C:\\Users\\USER\\AppData\\Local\\Continuum\\anaconda3\\python37.dll" ; Anacondas PATH environment to load native dlls of modules (numpy, etc.) :windows-anaconda-activate-bat "C:\\Users\\USER\\AppData\\Local\\Continuum\\anaconda3\\Scripts\\activate.bat" ) ... :ok ``` This dynamically finds the python shared library and loads it using output from the python3 executable on your system. For information about how that works, please checkout the code [here](https://github.com/cnuernber/libpython-clj/blob/master/src/libpython_clj/python/interpreter.clj#L30). ### Execute Some Python `*out*` and `*err*` capture python stdout and stderr respectively. ```clojure user> (run-simple-string "print('hey')") hey {:globals {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': }, :locals {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': }} ``` The results have been 'bridged' into java meaning they are still python objects but there are java wrappers over the top of them. For instance, `Object.toString` forwards its implementation to the python function `__str__`. ```clojure (def bridged (run-simple-string "print('hey')")) (instance? java.util.Map (:globals bridged)) true user> (:globals bridged) {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': } ``` We can get and set global variables here. If we run another string, these are in the environment. The globals map itself is the global dict of the main module: ```clojure (def main-globals (-> (add-module "__main__") (module-dict))) #'user/main-globals user> main-globals {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': } user> (keys main-globals) ("__name__" "__doc__" "__package__" "__loader__" "__spec__" "__annotations__" "__builtins__") user> (get main-globals "__name__") "__main__" user> (.put main-globals "my_var" 200) nil user> (run-simple-string "print('your variable is:' + str(my_var))") your variable is:200 {:globals {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': , 'my_var': 200}, :locals {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': , 'my_var': 200}} ``` Running Python isn't ever really necessary, however, although it may at times be convenient. You can call attributes from clojure easily: ```clojure user> (def np (import-module "numpy")) #'user/np user> (def ones-ary (call-attr np "ones" [2 3])) #'user/ones-ary user> ones-ary [[1. 1. 1.] [1. 1. 1.]] user> (call-attr ones-ary "__len__") 2 user> (vec ones-ary) [[1. 1. 1.] [1. 1. 1.]] user> (type (first *1)) :pyobject user> (get-attr ones-ary "shape") (2, 3) user> (vec (get-attr ones-ary "shape")) [2 3] user> (dir ones-ary) ["T" "__abs__" "__add__" "__and__" "__array__" "__array_finalize__" ... ... "strides" "sum" "swapaxes" "take" "tobytes" "tofile" "tolist" "tostring" "trace" "transpose" "var" "view"] ### DataFrame access full example Here's how to create Pandas DataFrame and accessing its rows via `loc` in both Python and Clojure: ```python # Python import numpy as np import pandas as pan dates = pan.date_range("1/1/2000", periods=8) table = pan.DataFrame(np.random.randn(8, 4), index=dates, columns=["A", "B", "C", "D"]) row_date = pan.date_range(start="2000-01-01", end="2000-01-01") table.loc[row_date] ``` ```clojure ; Clojure (require '[libpython-clj2.require :refer [require-python]]) (require-python '[numpy :as np]) (require-python '[pandas :as pan]) (def dates (pan/date_range "1/1/2000" :periods 8)) (def table (pan/DataFrame (call-attr np/random :randn 8 4) :index dates :columns ["A" "B" "C" "D"])) (def row-date (pan/date_range :start "2000-01-01" :end "2000-01-01")) (get-item (get-attr table :loc) row-date) ``` ### Errors Errors are caught and an exception is thrown. The error text is saved verbatim in the exception: ```clojure user> (run-simple-string "print('syntax errrr") Execution error (ExceptionInfo) at libpython-clj.python.interpreter/check-error-throw (interpreter.clj:260). File "", line 1 print('syntax errrr ^ SyntaxError: EOL while scanning string literal ``` ### Some Syntax Sugar ```clojure user> (py/from-import numpy linspace) #'user/linspace user> (linspace 2 3 :num 10) [2. 2.11111111 2.22222222 2.33333333 2.44444444 2.55555556 2.66666667 2.77777778 2.88888889 3. ] user> (doc linspace) ------------------------- user/linspace Return evenly spaced numbers over a specified interval. Returns `num` evenly spaced samples, calculated over the interval [`start`, `stop`]. ``` * `from-import` - sugar around python `from a import b`. Takes multiple b's. * `import-as` - sugar around python `import a as b`. * `$a` - call an attribute using symbol att name. Keywords map to kwargs * `$c` - call an object mapping keywords to kwargs #### Experimental Sugar We are trying to find the best way to handle attributes in order to shorten generic python notebook-type usage. The currently implemented direction is: * `$.` - get an attribute. Can pass in symbol, string, or keyword * `$..` - get an attribute. If more args are present, get the attribute on that result. ```clojure user> (py/$. numpy linspace) user> (py/$.. numpy random shuffle) ``` ##### Extra sugar `libpython-clj` offers syntactic forms similar to those offered by Clojure for interacting with Python classes and objects. **Class/object methods** Where in Clojure you would use `(. obj method arg1 arg2 ... argN)`, you can use `(py. pyobj method arg1 arg2 ... argN)`. In Python, this is equivalent to `pyobj.method(arg1, arg2, ..., argN)`. Concrete examples are shown below. **Class/object attributes** Where in Clojure you would use `(.- obj attr)`, you can use `(py.- pyobj attr)`. In Python, this is equivalent to `pyobj.attr`. Concrete examples shown below. **Nested attribute access** To achieve a chain of method/attribute access, use the `py..` for. ```clojure (py.. (requests/get "http://www.google.com") -content (decode "latin-1")) ``` (**Note**: requires Python `requests` module installled) **Examples** ```clojure user=> (require '[libpython-clj2.python :as py :refer [py. py.. py.-]]) nil user=> (require '[libpython-clj2.require :refer [require-python]]) ... debug info ... user=> (require-python '[builtins :as python]) WARNING: AssertionError already refers to: class java.lang.AssertionError in namespace: builtins, being replaced by: #'builtins/AssertionError WARNING: Exception already refers to: class java.lang.Exception in namespace: builtins, being replaced by: #'builtins/Exception nil user=> (def xs (python/list)) #'user/xs user=> (py. xs append 1) nil user=> xs [1] user=> (py. xs extend [1 2 3]) nil user=> xs [1, 1, 2, 3] user=> (py. xs __len__) 4 user=> ((py.- xs __len__)) ;; attribute syntax to get then call method 4 user=> (py. xs pop) 3 user=> (py. xs clear) nil ;; requires Python requests module installed user=> (require-python 'requests) nil user=> (def requests (py/import-module "requests")) #'user/requests user=> (py.. requests (get "http://www.google.com") -content (decode "latin-1")) " (def ones-ary (py/py. np ones [2 3])) #'user/ones-ary user> (def tens-data (dtt/as-tensor ones-ary)) #'user/tens-data user> tens-data #tech.v3.tensor[2 3] [[1.000 1.000 1.000] [1.000 1.000 1.000]] user> (require '[tech.v3.datatype :as dtype]) nil ;;Only constant-time count items can be copied, so vectors and arrays and such. user> (def ignored (dtype/copy! (vec (repeat 6 5)) tens-data)) #'user/ignored user> (.put main-globals "ones_ary" ones-ary) nil user> (run-simple-string "print(ones_ary)") [[5. 5. 5.] [5. 5. 5.]] {:globals {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': , 'my_var': 200, 'ones_ary': array([[5., 5., 5.], [5., 5., 5.]])}, :locals {'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': , '__spec__': None, '__annotations__': {}, '__builtins__': , 'my_var': 200, 'ones_ary': array([[5., 5., 5.], [5., 5., 5.]])}} ``` So heavy data has a zero-copy route. Anything backed by a `:native-buffer` has a zero copy pathway to and from numpy. For more information on how this happens, please refer to the datatype library [documentation](https://github.com/techascent/tech.datatype/tree/master/docs). Just keep in mind, careless usage of zero copy is going to cause spooky action at a distance. ### Pickle Speaking of numpy, you can pickle python objects and transform the result via numpy and dtype to a java byte array and back: ```clojure user> (require '[libpython-clj2.python :as py]) nil user> (py/initialize!) Sep 03, 2022 11:23:34 AM clojure.tools.logging$eval5948$fn__5951 invoke INFO: Detecting startup info Sep 03, 2022 11:23:34 AM clojure.tools.logging$eval5948$fn__5951 invoke INFO: Startup info {:lib-version "3.9", :java-library-path-addendum "/home/chrisn/miniconda3/lib", :exec-prefix "/home/chrisn/miniconda3", :executable "/home/chrisn/miniconda3/bin/python3", :libnames ("python3.9m" "python3.9"), :prefix "/home/chrisn/miniconda3", :base-prefix "/home/chrisn/miniconda3", :libname "python3.9m", :base-exec-prefix "/home/chrisn/miniconda3", :python-home "/home/chrisn/miniconda3", :version [3 9 1], :platform "linux"} Sep 03, 2022 11:23:34 AM clojure.tools.logging$eval5948$fn__5951 invoke INFO: Prefixing java library path: /home/chrisn/miniconda3/lib Sep 03, 2022 11:23:35 AM clojure.tools.logging$eval5948$fn__5951 invoke INFO: Loading python library: python3.9 Sep 03, 2022 11:23:35 AM clojure.tools.logging$eval5948$fn__5951 invoke INFO: Reference thread starting :ok user> (def data (py/->python {:a 1 :b 2})) #'user/data user> (def pickle (py/import-module "pickle")) #'user/pickle user> (def bdata (py/py. pickle dumps data)) #'user/bdata user> bdata b'\x80\x04\x95\x11\x00\x00\x00\x00\x00\x00\x00}\x94(\x8c\x01a\x94K\x01\x8c\x01b\x94K\x02u.' user> (def np (py/import-module "numpy")) #'user/np user> (py/py. np frombuffer bdata :dtype "int8") [-128 4 -107 17 0 0 0 0 0 0 0 125 -108 40 -116 1 97 -108 75 1 -116 1 98 -108 75 2 117 46] user> (require '[libpython-clj2.python.np-array]) nil user> (def ary (py/py. np frombuffer bdata :dtype "int8")) #'user/ary user> (py/->jvm ary) #tech.v3.tensor[28] [-128 4 -107 17 0 0 0 0 0 0 0 125 -108 40 -116 1 97 -108 75 1 -116 1 98 -108 75 2 117 46] user> (require '[tech.v3.datatype :as dt]) nil user> (dt/->byte-array *2) [-128, 4, -107, 17, 0, 0, 0, 0, 0, 0, 0, 125, -108, 40, -116, 1, 97, -108, 75, 1, -116, 1, 98, -108, 75, 2, 117, 46] user> (require '[tech.v3.tensor :as dtt]) nil user> (dtt/as-tensor *2) nil user> (def bdata *3) #'user/bdata user> bdata [-128, 4, -107, 17, 0, 0, 0, 0, 0, 0, 0, 125, -108, 40, -116, 1, 97, -108, 75, 1, -116, 1, 98, -108, 75, 2, 117, 46] user> (type bdata) [B user> (def tens (dtt/reshape bdata [(dt/ecount bdata)])) #'user/tens user> (def pdata (py/->python tens)) #'user/pdata user> pdata [-128 4 -107 17 0 0 0 0 0 0 0 125 -108 40 -116 1 97 -108 75 1 -116 1 98 -108 75 2 117 46] user> (py/python-type *1) :ndarray user> (def py-ary *2) #'user/py-ary user> (def py-bytes (py/py. py-ary tobytes)) #'user/py-bytes user> (py/py. pickle loads py-bytes) {'a': 1, 'b': 2} user> ``` ================================================ FILE: topics/embedded.md ================================================ # Embedding Clojure In Python The initial development push for `libpython-clj` was simply to embed Python in Clojure allowing Clojure developers to use Python modules simply transparently. This approach relied on `libpython-clj` being able to find the Python shared library and having some capability to setup various Python system variables before loading any modules. While this works great most of the time there are several reasons for which this approach is less than ideal: 1. In some cases a mainly Python team wants to use some Clojure for a small part of their work. Telling them to host Python from Clojure is for them a potentially very disruptive change. 2. The python ecosystem is moving away from the shared library and towards compiling a statically linked executable. This can never work with libpython-clj's default pathway. 3. Embedded Python cannot use all of Python functionality available due to the fact that the host process isn't `python`. Specifically the multithreading module relies on forking the host process and thus produces a hang if the JVM is the main underlying process. 4. Replicating the exact python environment is error prone especially when Python environment managers such as `pyenv` and `Conda` are taken into account. Due to the above reasons there is a solid argument for, if possible, embedding Clojure into Python allowing the Python executable to be the host process. ## Enter: cljbridge Python already had a nascent system for embedding Java in Python - the [javabridge module](https://pypi.org/project/javabridge/). We went a step further and provide `cljbridge` python module. In order to compile `javabridge` a JDK is required and **not just the JRE**. [tristanstraub](https://github.com/tristanstraub/) had found a way to use this in order to work with [Blender](https://github.com/tristanstraub/blender-clj/). We took a bit more time and worked out ways to smooth out these interactions and make sure they were supported throughout the system. ## From the Python REPL The next step involves starting a python repl. This requires a python library `cljbridge`, which can be installed via ``` export JAVA_HOME=<--YOUR JAVA HOME--> python3 -m pip install cljbridge ``` This will install and eventually compile `javabridge` as well. If the installation cannot find 'jni.h' then most likely you have the Java runtime (JRE) installed as opposed to the Java development kit (JDK). So we start by importing that script: ```python Python 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from clojurebridge import cljbridge >>> test_var=10 >>> cljbridge.init_jvm(start_repl=True) Mar 11, 2021 9:08:47 AM clojure.tools.logging$eval3186$fn__3189 invoke INFO: nREPL server started on port 40241 on host localhost - nrepl://localhost:40241 ``` At this point we do not get control back; we have released the GIL and java is blocking this thread to allow the Clojure REPL systems access to the GIL. We have two important libraries for clojure loaded, nrepl and cider which allow a rich, interactive development experience so let's now connect to that port with our favorite Clojure editor - emacs of course ;-). ### Passing JVM arguments If you want to specify arbitrary arguments for the JVM to be started by Python, you can use the environment variable `JDK_JAVA_OPTIONS` to do so. It will be picked up by the JVM when starting. Since clojurebridge 0.0.8, you can as well specify a list of aliases, which get resolved from the `deps.edn` file. This allows as well to specify JVM arguments and JVM properties. Example: Starting Clojure embedded from python via ```python cljbridge.init_jvm(aliases=["jdk-17","fastcall"],start_repl=True) ``` and a `deps.edn` with ```clojure :aliases { :fastcall {:jvm-opts ["-Dlibpython_clj.manual_gil=true"]} :jdk-17 {:jvm-opts ["--add-modules=jdk.incubator.foreign" "--enable-native-access=ALL-UNNAMED"]}} ``` would add then the appropriate JVM options. ## From the Clojure REPL From emacs, I run the command 'cider-connect' which allows me to specify a host and port to connect to. Once connected, I get a minimal repl environment: ```clojure ;; M-x cider-connect ...localhost...40241 ;; I am not sure why but to initialize the user namespace I have to eval ns user user> (eval '(ns user)) nil user> (require '[libpython-clj2.python :as py]) nil ;; Python has been initialized and libpython-clj can detect this user> (py/initialize!) :already-initialized user> ;;We can share data via the main module user> (def main-mod (py/add-module "__main__")) #'user/main-mod user> (def mod-dict (py/module-dict main-mod)) #'user/mod-dict user> (keys mod-dict) ("__name__" "__doc__" "__package__" "__loader__" "__spec__" "__annotations__" "__builtins__" "cljbridge" "test_var") user> (get mod-dict "test_var") 10 user> (.put mod-dict "clj_fn" (fn [& args] (println "Printing from Clojure: " (vec args)))) nil user> ;;Now if we stop the repl server we can access our python environment again user> (require '[libpython-clj2.embedded :as embedded]) nil user> (embedded/stop-repl!) ``` ## And Back to Python!! Shutting down the repl always gives us an exception; something perhaps to work on. But the important thing is that we can access variables and data that we set in the main module - ```python >>> Exception in thread "nREPL-session-d684061e-f21c-4265-a9a2-828b99dcaf42" java.net.SocketException: Socket closed at java.net.SocketOutputStream.socketWrite(SocketOutputStream.java:118) at java.net.SocketOutputStream.write(SocketOutputStream.java:155) at java.io.BufferedOutputStream.flushBuffer(BufferedOutputStream.java:82) at java.io.BufferedOutputStream.flush(BufferedOutputStream.java:140) at nrepl.transport$bencode$fn__7714.invoke(transport.clj:121) at nrepl.transport.FnTransport.send(transport.clj:28) at nrepl.middleware.print$send_streamed.invokeStatic(print.clj:136) at nrepl.middleware.print$send_streamed.invoke(print.clj:122) at nrepl.middleware.print$printing_transport$reify__8149.send(print.clj:173) at cider.nrepl.middleware.track_state$make_transport$reify__17923.send(track_state.clj:228) at nrepl.middleware.caught$caught_transport$reify__8184.send(caught.clj:58) at nrepl.middleware.interruptible_eval$evaluate$fn__8250.invoke(interruptible_eval.clj:132) at clojure.main$repl$fn__9121.invoke(main.clj:460) at clojure.main$repl.invokeStatic(main.clj:458) at clojure.main$repl.doInvoke(main.clj:368) at clojure.lang.RestFn.invoke(RestFn.java:1523) at nrepl.middleware.interruptible_eval$evaluate.invokeStatic(interruptible_eval.clj:84) at nrepl.middleware.interruptible_eval$evaluate.invoke(interruptible_eval.clj:56) at nrepl.middleware.interruptible_eval$interruptible_eval$fn__8258$fn__8262.invoke(interruptible_eval.clj:152) at clojure.lang.AFn.run(AFn.java:22) at nrepl.middleware.session$session_exec$main_loop__8326$fn__8330.invoke(session.clj:202) at nrepl.middleware.session$session_exec$main_loop__8326.invoke(session.clj:201) at clojure.lang.AFn.run(AFn.java:22) at java.lang.Thread.run(Thread.java:748) >>> # So let's call our new clojure fn >>> clj_fn(1, 2, 3, 4, "Embedded Clojure FTW!!") Printing from Clojure: [1 2 3 4 Embedded Clojure FTW!!] >>> ``` ## Loading and running a Clojure file in embedded mode We can runs as well a .clj file in embedded mode. The following does this without an interactive pytho shell, it just runs the provided clj file with `clojure.core/load-file` ```bash python3 -c 'import cljbridge;cljbridge.load_clojure_file(clj_file="my-file.clj")' ``` ## Are You Not Entertained??? So there you have it, embedding a Clojure repl in a Python process and passing data in between these two systems. This sidesteps a *ton* of issues with embedding Python and provides another interesting set of possibilities, essentially extending existing Python systems with some of the greatest tech the JVM has to offer :-). * [javabridge github](https://github.com/LeeKamentsky/python-javabridge) * [libpython-clj cljbridge.py](https://github.com/clj-python/libpython-clj/blob/94c72ca0ac94b210a9b126805cd4112024ad0b96/cljbridge.py) * [libpython-clj embedded docs](https://clj-python.github.io/libpython-clj/libpython-clj2.embedded.html) * [blender-clj - the inspiration](https://github.com/tristanstraub/blender-clj/) ================================================ FILE: topics/environments.md ================================================ # Python Environments ## pyenv pyenv requires that you build the shared library. This is a separate configuration option than a lot of pyenv users have used before. * [pyenv shared library issue](https://github.com/pyenv/pyenv/issues/392) * [libpython-clj related issue](https://github.com/clj-python/libpython-clj/issues/123) ## Conda Conda requires that we set the LD_LIBRARY_PATH to the conda install. * [example conda repl launcher](https://github.com/clj-python/libpython-clj/blob/master/scripts/conda-repl) * [libpython-clj issue for Conda](https://github.com/clj-python/libpython-clj/issues/18) ================================================ FILE: topics/new-to-clojure.md ================================================ # So Many Parenthesis! ## About Clojure LISP stands for List Processing and it was originally designed by John McCarthy around 1958. It was the first language with a garbage collector making it the first truly high level language assuming you don't consider Fortran a high level language. Here is Dr. McCarthy's [seminal paper](http://www-formal.stanford.edu/jmc/recursive.pdf) and for a much better intro than I can give please see [here](http://www.paulgraham.com/rootsoflisp.html). Time passed and along came a man named Rich Hickey. Making a long story short, Rich was working in a variety of languages such as C++, Java, and C# when he did a project in Common Lisp and was hooked. There are many YouTube videos and documents that Rich has produced but [simple made easy](https://www.infoq.com/presentations/Simple-Made-Easy/) is one I found very compelling. If you enjoy that video, don't stop there; Rich has many interesting, profound, and sometimes provocative things to add to the conversation. For more about his reasoning behind Clojure, please check out his [rationale](https://clojure.org/about/rationale). My perspective is closer to [Uncle Bob's](http://blog.cleancoder.com/uncle-bob/2019/08/22/WhyClojure.html). To address the parenthesis, we need to talk about [homoiconicity](https://en.wikipedia.org/wiki/Homoiconicity). LISPs are part of a subset of languages that build themselves out of their own data structures so that when you type symbols into a file or repl, you get back a data structure of the language itself. This means that several parts of the programmers toolbox can be simpler and you can load a file as data, transform it, and then execute some portion of it all without leaving the language. This isn't something you will really need to understand today, but the point is that the look and structure of the language is a sweet spot to make it more of middle ground between what a human and a machine can understand. The fallout from having a language that is both a language and a data structure is that you can extend the language without needing to change the compiler. For example, the very first standardized 'object oriented programming' system was [CLOS](https://en.wikipedia.org/wiki/Common_Lisp_Object_System), or Common Lisp Object System. This was implemented on top of Common Lisp with no updates to the compiler whatsoever. In Clojure, we have been able to add things like an [async library](https://github.com/clojure/core.async) or [software transactional memory](https://clojure.org/reference/refs) without changing the compiler itself because we can extend or change the language quite substantially at compile time. Clojure is a deeply functional language with pragmatic pathways built for mutation. All of the basic data structures of Clojure are immutable. Learning to program in a functional manner will mean learning things like `map` and `reduce` and basically re-wiring how you think about problems. I believe it is this re-wiring that is most beneficial in the long term regardless of whether you become some functional programming God or just dabble for a while. Many systems, regardless of language, are designed in a functional manner because properties like [idempotency](https://en.wikipedia.org/wiki/Idempotence) and [referential transparency](https://en.wikipedia.org/wiki/Referential_transparency) make it easier to reason about code that you didn't write. That being said, Clojure doesn't force you to write functional code all the time as it is mainly a pragmatic language. You can easily write mutable code if you like. For the web, Clojure has a [version](https://clojurescript.org/) that compiles to JavaScript so that you can write one language both server and front end side. Many Clojure projects are just one repository and one artifact that when run produces both the server and client side of the equation. Another important usage of the Clojurescript is mobile application development using frameworks like [React Native](https://www.upwork.com/blog/2018/11/developing-react-native-applications-in-clojurescript/). Clojurescript is truly one of Clojure's greatest strengths and one that the Clojure community has strongly embraced. No talk about Clojure would be complete without giving major credit to its excellent REPL support. One important aspect of the Clojure REPL is that you can see all of complex nested datastructures easily without needing to write `toString` or `__str__` methods. Because of this visibility advantage a common way to use Clojure is to model your problem as a transformation from datastructure to datastructure, testing each stage of this transformation in the repl and just letting the REPL printing show you the next move. Programming with data is often just easier than programming with objects and debugging data transformations is far, far easier than debugging a complex object graph. ## Learning Clojure There are in fact many resources to learn Clojure and here are some the community recommends: ### Books/Courses 1. [Clojure for the Brave and True](https://www.braveclojure.com/clojure-for-the-brave-and-true/) 1. [Practicalli](https://practicalli.github.io/clojure/) 1. [Clojure for Data Science](https://www.amazon.it/dp/B00YSILGWG/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1) 1. [Functional Programming in Scala and Clojure](https://www.amazon.it/dp/B00HUEG8KK/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1) Practicalli has a page devoted purely to resources on learning Clojure at whatever level you are so if these recommendations do not speak to you please review their [books page](https://practicalli.github.io/clojure/reference/books.html). ### Learn by Writing Code 1. [Clojure Koans](https://github.com/functional-koans/clojure-koans) 1. [clojinc](https://github.com/lspector/clojinc) 1. [Clojurescript Koans](http://clojurescriptkoans.com/) 1. [4Clojure](http://www.4clojure.com/) ### IDEs/Editors There are many more IDEs available than listed here; these ones are just very popular: 1. [Calva](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva) 1. [Cursive](https://cursive-ide.com/) 1. [Atom](https://medium.com/@jacekschae/slick-clojure-editor-setup-with-atom-a3c1b528b722) 1. [emacs + cider](https://cider.mx/) 1. [vim + fireplace](https://www.vim.org/scripts/script.php?script_id=4978) One thing to be sure of, regardless of IDE, is to use some form of [structural editing](https://shaunlebron.github.io/parinfer/). All the better IDEs have it; all the IDEs listed here have it, and I personally really struggle without it. When I have a form of [structure editing](https://wikemacs.org/wiki/Paredit-mode), however, I can move code around much faster than I can in Java, Python, or C++. This is another benefit of the homoiconicity that we spoke earlier in that we can transform the program easily because it is just a data structure and this includes editor level transformations and analysis. ## Off We Go! Clojure is an amazing language. It is really rewarding on a personal level because it is tailored towards extremely high individual and small group productivity. But this power comes with some caveats and one of those is that learning Clojure takes time and patience. The community is here to support you, however, so check us out: * [Clojurians Slack](https://clojurians.slack.com) * [Clojurians Zulip](https://clojurians.zulipchat.com/) * [r/Clojure reddit](https://www.reddit.com/r/Clojure/) * [r/Clojurescript reddit](https://www.reddit.com/r/Clojurescript/) * [Clojureverse](https://clojureverse.org/) ================================================ FILE: topics/scopes-and-gc.md ================================================ # Scopes And Garbage Collection libpython-clj now supports stack-based scoping rules so you can guarantee all python objects created during a section of code will be released by a certain point. Using the stack-based scoping looks like: ```clojure user> (require '[libpython-clj.python :as py]) nil user> (py/initialize!) ... (logging elided) :ok user> (py/stack-resource-context (-> (py/->py-dict {:a 1 :b 2}) ;;Note - Without this call you guarantee a crash. (py/->jvm))) {"a" 1, "b" 2} ``` You must either call ->jvm or return a keyword at the end of your scope. In the case where you are processing a batch of items (which we recommend for perf reasons), you can also grab the GIL at the top of your thing: ```clojure user> (def dict-seq (py/as-jvm (py/->py-list (repeat 1000 (py/->py-dict {:a 1 :b 2}))))) #'user/dict-seq user> (def ignored (time (mapv py/->jvm dict-seq))) "Elapsed time: 2200.556506 msecs" #'user/ignored user> (def ignored (time (py/with-gil (mapv py/->jvm dict-seq)))) "Elapsed time: 2095.815518 msecs" #'user/ignored ``` The hidden thing above, regardless of if you grab the gil or not is that you are actually holding onto a lot of python objects that could be released. Hence if you aren't disciplined about calling System/gc or if the jvm gc just decides not to run you could be allocating a lot of native-heap objects. Plus what you don't see is that if you call System/gc the resource thread dedicated to releasing things will have a lot of work to do. For production use cases where you need a bit more assurance that things get released, please consider both grabbing the gil *and* opening a resource context: ```clojure user> (def ignored (time (py/with-gil-stack-rc-context (->> (repeatedly 1000 #(py/->py-dict {:a 1 :b 2})) (py/->py-list) (py/as-jvm) (mapv py/->jvm))))) "Elapsed time: 3246.847595 msecs" #'user/ignored ``` This took a second longer! But, you *know* that all python objects allocated within that scope are released. Before, you would be in essence hoping that things would be released soon enough. Again, for production contexts we recommend batch processing objects *and* using the `with-gil-stack-rc-context` function call that correctly grabs the gil, opens a resource context and then releases anything allocated within that context. ================================================ FILE: topics/slicing.md ================================================ # Slicing And Slices The way Python implements slicing is via overloading the `get-item` function call. This is the call the Python interpreter makes under the covers whenever you use the square bracket `[]` syntax. For quite a few objects, that function call take a tuple of arguments. The trick to numpy slicing is to create builtin slice objects with the appropriate arguments and pass them into the `get-item` call in a tuple. ```clojure user> (require '[libpython-clj.python :as py]) nil user> (require '[libpython-clj.require :refer [require-python]]) ... lotta logs ... user> (require-python '[builtins]) WARNING: AssertionError already refers to: class java.lang.AssertionError in namespace: builtins, being replaced by: #'builtins/AssertionError WARNING: Exception already refers to: class java.lang.Exception in namespace: builtins, being replaced by: #'builtins/Exception :ok user> (doc builtins/slice) ------------------------- builtins/slice [[self & [args {:as kwargs}]]] slice(stop) slice(start, stop[, step]) Create a slice object. This is used for extended slicing (e.g. a[0:10:2]). nil user> (require-python '[numpy :as np]) :ok user> (require-python '[numpy :as np]) :ok user> (def ary (-> (np/arange 9) (np/reshape [3 3]))) #'user/ary user> ary [[0 1 2] [3 4 5] [6 7 8]] user> (py/get-item ary [(builtins/slice 1 nil) (builtins/slice 1 nil)]) [[4 5] [7 8]] user> (py/get-item ary [(builtins/slice -1) (builtins/slice 1 nil)]) [[1 2] [4 5]] user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 nil)]) [[1 2] [4 5] [7 8]] user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 2)]) [[1] [4] [7]] user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 3)]) [[1 2] [4 5] [7 8]] user> (py/get-item ary [(builtins/slice nil) (builtins/slice 1 4)]) [[1 2] [4 5] [7 8]] ```