numexpr 2.10.1__tar.gz → 2.11.0__tar.gz

{numexpr-2.10.1 → numexpr-2.11.0}/ANNOUNCE.rst

@@ -1,29 +1,33 @@
 =========================
-Announcing NumExpr 2.10.1
+Announcing NumExpr 2.11.0
 =========================
 
 Hi everyone,
 
-NumExpr 2.10.1 continues to establize the support for NumPy 2.0.0.
-Also, the default number of 'safe' threads has been upgraded to 16
-(instead of previous 8). Finally, preliminary support for Python 3.13;
-thanks to Karolina Surma.
+NumExpr 2.11.0 Initial support for free-threaded Python 3.13t has been added.
+This is still experimental, so please report any issues you find.
+Finally, Python 3.10 is now the minimum supported version.
 
 Project documentation is available at:
 
 http://numexpr.readthedocs.io/
 
-Changes from 2.9.0 to 2.10.0
-----------------------------
+Changes from 2.10.2 to 2.11.0
+-----------------------------
 
-* Support for NumPy 2.0.0.  This is still experimental, so please
-  report any issues you find.  Thanks to Clément Robert and Thomas
-  Caswell for the work.
+* Initial support for free-threaded Python 3.13t has been added.
+  This is still experimental, so please report any issues you find.
+  For more info, see discussions PRs #504, #505 and #508.
+  Thanks to @andfoy, @rgommers and @FrancescAlted for the work.
 
-* Avoid erroring when OMP_NUM_THREADS is empty string.  Thanks to
-  Patrick Hoefler.
+* Fix imaginary evaluation in the form of `1.1e1j`.  This was
+  previously not supported and would raise an error.  Thanks to @27rabbitlt
+  for the fix.
 
-* Do not warn if OMP_NUM_THREAD set.
+* The test suite has been modernized to use `pytest` instead of `unittest`.
+  This should make it easier to run the tests and contribute to the project.
+
+* Python 3.10 is now the minimum supported version.
 
 What's Numexpr?
 ---------------

{numexpr-2.10.1 → numexpr-2.11.0}/AUTHORS.txt

@@ -23,7 +23,7 @@ Google Inc. contributed bug fixes.
 
 David Cox improved readability of the Readme.
 
-Robert A. McLeod contributed bug fixes and ported the documentation to 
+Robert A. McLeod contributed bug fixes and ported the documentation to
 numexpr.readthedocs.io. He has served as the maintainer of the package
 since 2016 to 2023.
 

numexpr-2.11.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: numexpr
+Version: 2.11.0
+Summary: Fast numerical expression evaluator for NumPy
+Author-email: "David M. Cooke, Francesc Alted, and others" <blosc@blosc.org>
+Maintainer-email: Blosc Development Team <blosc@blosc.org>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/pydata/numexpr
+Project-URL: documentation, https://numexpr.readthedocs.io
+Project-URL: repository, https://github.com/pydata/numexpr
+Classifier: Development Status :: 6 - Mature
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+License-File: AUTHORS.txt
+Requires-Dist: numpy>=1.23.0
+Dynamic: license-file
+
+======================================================
+NumExpr: Fast numerical expression evaluator for NumPy
+======================================================
+
+:Author: David M. Cooke, Francesc Alted, and others.
+:Maintainer: Francesc Alted
+:Contact: faltet@gmail.com
+:URL: https://github.com/pydata/numexpr
+:Documentation: http://numexpr.readthedocs.io/en/latest/
+:GitHub Actions: |actions|
+:PyPi: |version|
+:DOI: |doi|
+:readthedocs: |docs|
+
+.. |actions| image:: https://github.com/pydata/numexpr/workflows/Build/badge.svg
+        :target: https://github.com/pydata/numexpr/actions
+.. |travis| image:: https://travis-ci.org/pydata/numexpr.png?branch=master
+        :target: https://travis-ci.org/pydata/numexpr
+.. |docs| image:: https://readthedocs.org/projects/numexpr/badge/?version=latest
+        :target: http://numexpr.readthedocs.io/en/latest
+.. |doi| image:: https://zenodo.org/badge/doi/10.5281/zenodo.2483274.svg
+        :target:  https://doi.org/10.5281/zenodo.2483274
+.. |version| image:: https://img.shields.io/pypi/v/numexpr
+        :target: https://pypi.python.org/pypi/numexpr
+
+
+What is NumExpr?
+----------------
+
+NumExpr is a fast numerical expression evaluator for NumPy.  With it,
+expressions that operate on arrays (like :code:`'3*a+4*b'`) are accelerated
+and use less memory than doing the same calculation in Python.
+
+In addition, its multi-threaded capabilities can make use of all your
+cores -- which generally results in substantial performance scaling compared
+to NumPy.
+
+Last but not least, numexpr can make use of Intel's VML (Vector Math
+Library, normally integrated in its Math Kernel Library, or MKL).
+This allows further acceleration of transcendent expressions.
+
+
+How NumExpr achieves high performance
+-------------------------------------
+
+The main reason why NumExpr achieves better performance than NumPy is
+that it avoids allocating memory for intermediate results. This
+results in better cache utilization and reduces memory access in
+general. Due to this, NumExpr works best with large arrays.
+
+NumExpr parses expressions into its own op-codes that are then used by
+an integrated computing virtual machine. The array operands are split
+into small chunks that easily fit in the cache of the CPU and passed
+to the virtual machine. The virtual machine then applies the
+operations on each chunk. It's worth noting that all temporaries and
+constants in the expression are also chunked. Chunks are distributed among
+the available cores of the CPU, resulting in highly parallelized code
+execution.
+
+The result is that NumExpr can get the most of your machine computing
+capabilities for array-wise computations. Common speed-ups with regard
+to NumPy are usually between 0.95x (for very simple expressions like
+:code:`'a + 1'`) and 4x (for relatively complex ones like :code:`'a*b-4.1*a > 2.5*b'`),
+although much higher speed-ups can be achieved for some functions  and complex
+math operations (up to 15x in some cases).
+
+NumExpr performs best on matrices that are too large to fit in L1 CPU cache.
+In order to get a better idea on the different speed-ups that can be achieved
+on your platform, run the provided benchmarks.
+
+Installation
+------------
+
+From wheels
+^^^^^^^^^^^
+
+NumExpr is available for install via `pip` for a wide range of platforms and
+Python versions (which may be browsed at: https://pypi.org/project/numexpr/#files).
+Installation can be performed as::
+
+    pip install numexpr
+
+If you are using the Anaconda or Miniconda distribution of Python you may prefer
+to use the `conda` package manager in this case::
+
+    conda install numexpr
+
+From Source
+^^^^^^^^^^^
+
+On most \*nix systems your compilers will already be present. However if you
+are using a virtual environment with a substantially newer version of Python than
+your system Python you may be prompted to install a new version of `gcc` or `clang`.
+
+For Windows, you will need to install the Microsoft Visual C++ Build Tools
+(which are free) first. The version depends on which version of Python you have
+installed:
+
+https://wiki.python.org/moin/WindowsCompilers
+
+For Python 3.6+ simply installing the latest version of MSVC build tools should
+be sufficient. Note that wheels found via pip do not include MKL support. Wheels
+available via `conda` will have MKL, if the MKL backend is used for NumPy.
+
+See `requirements.txt` for the required version of NumPy.
+
+NumExpr is built in the standard Python way::
+
+  python setup.py build install
+
+You can test `numexpr` with::
+
+  python -c "import numexpr; numexpr.test()"
+
+Do not test NumExpr in the source directory or you will generate import errors.
+
+Enable Intel® MKL support
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NumExpr includes support for Intel's MKL library. This may provide better
+performance on Intel architectures, mainly when evaluating transcendental
+functions (trigonometrical, exponential, ...).
+
+If you have Intel's MKL, copy the `site.cfg.example` that comes with the
+distribution to `site.cfg` and edit the latter file to provide correct paths to
+the MKL libraries in your system.  After doing this, you can proceed with the
+usual building instructions listed above.
+
+Pay attention to the messages during the building process in order to know
+whether MKL has been detected or not.  Finally, you can check the speed-ups on
+your machine by running the `bench/vml_timing.py` script (you can play with
+different parameters to the `set_vml_accuracy_mode()` and `set_vml_num_threads()`
+functions in the script so as to see how it would affect performance).
+
+Usage
+-----
+
+::
+
+  >>> import numpy as np
+  >>> import numexpr as ne
+
+  >>> a = np.arange(1e6)   # Choose large arrays for better speedups
+  >>> b = np.arange(1e6)
+
+  >>> ne.evaluate("a + 1")   # a simple expression
+  array([  1.00000000e+00,   2.00000000e+00,   3.00000000e+00, ...,
+           9.99998000e+05,   9.99999000e+05,   1.00000000e+06])
+
+  >>> ne.evaluate("a * b - 4.1 * a > 2.5 * b")   # a more complex one
+  array([False, False, False, ...,  True,  True,  True], dtype=bool)
+
+  >>> ne.evaluate("sin(a) + arcsinh(a/b)")   # you can also use functions
+  array([        NaN,  1.72284457,  1.79067101, ...,  1.09567006,
+          0.17523598, -0.09597844])
+
+  >>> s = np.array([b'abba', b'abbb', b'abbcdef'])
+  >>> ne.evaluate("b'abba' == s")   # string arrays are supported too
+  array([ True, False, False], dtype=bool)
+
+
+Free-threading support
+----------------------
+Starting on CPython 3.13 onwards there is a new distribution that disables the
+Global Interpreter Lock (GIL) altogether, thus increasing the performance yields
+under multi-threaded conditions on a single interpreter, as opposed to having to use
+multiprocessing.
+
+Whilst numexpr has been demonstrated to work under free-threaded
+CPython, considerations need to be taken when using numexpr native parallel
+implementation vs using Python threads directly in order to prevent oversubscription,
+we recommend either using the main CPython interpreter thread to spawn multiple C threads
+using the parallel numexpr API, or spawning multiple CPython threads that do not use
+the parallel API.
+
+For more information about free-threaded CPython, we recommend visiting the following
+`community Wiki <https://py-free-threading.github.io/>`
+
+
+Documentation
+-------------
+
+Please see the official documentation at `numexpr.readthedocs.io <https://numexpr.readthedocs.io>`_.
+Included is a user guide, benchmark results, and the reference API.
+
+
+Authors
+-------
+
+Please see `AUTHORS.txt <https://github.com/pydata/numexpr/blob/master/AUTHORS.txt>`_.
+
+
+License
+-------
+
+NumExpr is distributed under the `MIT <http://www.opensource.org/licenses/mit-license.php>`_ license.
+
+
+.. Local Variables:
+.. mode: text
+.. coding: utf-8
+.. fill-column: 70
+.. End:

{numexpr-2.10.1 → numexpr-2.11.0}/README.rst

@@ -159,6 +159,24 @@ Usage
   array([ True, False, False], dtype=bool)
 
 
+Free-threading support
+----------------------
+Starting on CPython 3.13 onwards there is a new distribution that disables the
+Global Interpreter Lock (GIL) altogether, thus increasing the performance yields
+under multi-threaded conditions on a single interpreter, as opposed to having to use
+multiprocessing.
+
+Whilst numexpr has been demonstrated to work under free-threaded
+CPython, considerations need to be taken when using numexpr native parallel
+implementation vs using Python threads directly in order to prevent oversubscription,
+we recommend either using the main CPython interpreter thread to spawn multiple C threads
+using the parallel numexpr API, or spawning multiple CPython threads that do not use
+the parallel API.
+
+For more information about free-threaded CPython, we recommend visiting the following
+`community Wiki <https://py-free-threading.github.io/>`
+
+
 Documentation
 -------------
 

{numexpr-2.10.1 → numexpr-2.11.0}/RELEASE_NOTES.rst

@@ -1,22 +1,51 @@
 =====================================
-Release notes for NumExpr 2.10 series
+Release notes for NumExpr 2.11 series
 =====================================
 
+Changes from 2.10.2 to 2.11.0
+-----------------------------
+
+* Initial support for free-threaded Python 3.13t has been added.
+  This is still experimental, so please report any issues you find.
+  For more info, see discussions PRs #504, #505 and #508.
+  Thanks to @andfoy, @rgommers and @FrancescAlted for the work.
+
+* Fix imaginary evaluation in the form of `1.1e1j`.  This was
+  previously not supported and would raise an error.  Thanks to @27rabbitlt
+  for the fix.
+
+* The test suite has been modernized to use `pytest` instead of `unittest`.
+  This should make it easier to run the tests and contribute to the project.
+
+* Python 3.10 is now the minimum supported version.
+
+Changes from 2.10.1 to 2.10.2
+-----------------------------
+
+* Better support for CPUs that do not have a power of 2 number of
+  cores.  See #479 and #490.  Thanks to @avalentino.
+
+* Allow numexpr to run with the multithreading package in Python.
+  See PR #496.  Thanks to @emmaai
+
+* Wheels for Python 3.13 are now provided.
+
+
 Changes from 2.10.0 to 2.10.1
 -----------------------------
 
-- The default number of 'safe' threads has been upgraded to 16 (instead of
+* The default number of 'safe' threads has been upgraded to 16 (instead of
   previous 8). That means that if your CPU has > 16 cores, the default is
   to use 16. You can always override this with the "NUMEXPR_MAX_THREADS"
   environment variable.
 
-- NumPy 1.23 is now the minimum supported.
+* NumPy 1.23 is now the minimum supported.
 
-- Preliminary support for Python 3.13. Thanks to Karolina Surma.
+* Preliminary support for Python 3.13. Thanks to Karolina Surma.
 
-- Fix tests on nthreads detection (closes: #479). Thanks to @avalentino.
+* Fix tests on nthreads detection (closes: #479). Thanks to @avalentino.
 
-- The build process has been modernized and now uses the `pyproject.toml`
+* The build process has been modernized and now uses the `pyproject.toml`
   file for more of the configuration options.
 
 

numexpr-2.11.0/VERSION

@@ -0,0 +1 @@
+2.11.0

{numexpr-2.10.1 → numexpr-2.11.0}/bench/boolean_timing.py

@@ -9,8 +9,10 @@
 ####################################################################
 
 from __future__ import print_function
+
 import sys
 import timeit
+
 import numpy
 
 array_size = 5_000_000

numexpr-2.11.0/bench/free_threading.py

@@ -0,0 +1,171 @@
+#################################################################################
+# To compare the performance of numexpr when free-threading CPython is used.
+#
+# This example makes use of Python threads, as opposed to C native ones
+# in order to highlight the improvement introduced by free-threading CPython,
+# which now disables the GIL altogether.
+#################################################################################
+"""
+Results with GIL-enabled CPython:
+
+Benchmarking Expression 1:
+NumPy time (threaded over 32 chunks with 16 threads): 1.173090 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 0.951071 seconds
+numexpr speedup: 1.23x
+----------------------------------------
+Benchmarking Expression 2:
+NumPy time (threaded over 32 chunks with 16 threads): 10.410874 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 8.248753 seconds
+numexpr speedup: 1.26x
+----------------------------------------
+Benchmarking Expression 3:
+NumPy time (threaded over 32 chunks with 16 threads): 9.605909 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 11.087108 seconds
+numexpr speedup: 0.87x
+----------------------------------------
+Benchmarking Expression 4:
+NumPy time (threaded over 32 chunks with 16 threads): 3.836962 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 18.054531 seconds
+numexpr speedup: 0.21x
+----------------------------------------
+
+Results with free-threading CPython:
+
+Benchmarking Expression 1:
+NumPy time (threaded over 32 chunks with 16 threads): 3.415349 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 2.618876 seconds
+numexpr speedup: 1.30x
+----------------------------------------
+Benchmarking Expression 2:
+NumPy time (threaded over 32 chunks with 16 threads): 19.005238 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 12.611407 seconds
+numexpr speedup: 1.51x
+----------------------------------------
+Benchmarking Expression 3:
+NumPy time (threaded over 32 chunks with 16 threads): 20.555149 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 17.690749 seconds
+numexpr speedup: 1.16x
+----------------------------------------
+Benchmarking Expression 4:
+NumPy time (threaded over 32 chunks with 16 threads): 38.338372 seconds
+numexpr time (threaded with re_evaluate over 32 chunks with 16 threads): 35.074684 seconds
+numexpr speedup: 1.09x
+----------------------------------------
+"""
+
+import os
+
+os.environ["NUMEXPR_NUM_THREADS"] = "2"
+import threading
+import timeit
+
+import numpy as np
+
+import numexpr as ne
+
+array_size = 10**8
+num_runs = 10
+num_chunks = 32  # Number of chunks
+num_threads = 16  # Number of threads constrained by how many chunks memory can hold
+
+a = np.random.rand(array_size).reshape(10**4, -1)
+b = np.random.rand(array_size).reshape(10**4, -1)
+c = np.random.rand(array_size).reshape(10**4, -1)
+
+chunk_size = array_size // num_chunks
+
+expressions_numpy = [
+    lambda a, b, c: a + b * c,
+    lambda a, b, c: a**2 + b**2 - 2 * a * b * np.cos(c),
+    lambda a, b, c: np.sin(a) + np.log(b) * np.sqrt(c),
+    lambda a, b, c: np.exp(a) + np.tan(b) - np.sinh(c),
+]
+
+expressions_numexpr = [
+    "a + b * c",
+    "a**2 + b**2 - 2 * a * b * cos(c)",
+    "sin(a) + log(b) * sqrt(c)",
+    "exp(a) + tan(b) - sinh(c)",
+]
+
+
+def benchmark_numpy_chunk(func, a, b, c, results, indices):
+    for index in indices:
+        start = index * chunk_size
+        end = (index + 1) * chunk_size
+        time_taken = timeit.timeit(
+            lambda: func(a[start:end], b[start:end], c[start:end]), number=num_runs
+        )
+        results.append(time_taken)
+
+
+def benchmark_numexpr_re_evaluate(expr, a, b, c, results, indices):
+    for index in indices:
+        start = index * chunk_size
+        end = (index + 1) * chunk_size
+        # if index == 0:
+        # Evaluate the first chunk with evaluate
+        time_taken = timeit.timeit(
+            lambda: ne.evaluate(
+                expr,
+                local_dict={
+                    "a": a[start:end],
+                    "b": b[start:end],
+                    "c": c[start:end],
+                },
+            ),
+            number=num_runs,
+        )
+        results.append(time_taken)
+
+
+def run_benchmark_threaded():
+    chunk_indices = list(range(num_chunks))
+
+    for i in range(len(expressions_numpy)):
+        print(f"Benchmarking Expression {i+1}:")
+
+        results_numpy = []
+        results_numexpr = []
+
+        threads_numpy = []
+        for j in range(num_threads):
+            indices = chunk_indices[j::num_threads]  # Distribute chunks across threads
+            thread = threading.Thread(
+                target=benchmark_numpy_chunk,
+                args=(expressions_numpy[i], a, b, c, results_numpy, indices),
+            )
+            threads_numpy.append(thread)
+            thread.start()
+
+        for thread in threads_numpy:
+            thread.join()
+
+        numpy_time = sum(results_numpy)
+        print(
+            f"NumPy time (threaded over {num_chunks} chunks with {num_threads} threads): {numpy_time:.6f} seconds"
+        )
+
+        threads_numexpr = []
+        for j in range(num_threads):
+            indices = chunk_indices[j::num_threads]  # Distribute chunks across threads
+            thread = threading.Thread(
+                target=benchmark_numexpr_re_evaluate,
+                args=(expressions_numexpr[i], a, b, c, results_numexpr, indices),
+            )
+            threads_numexpr.append(thread)
+            thread.start()
+
+        for thread in threads_numexpr:
+            thread.join()
+
+        numexpr_time = sum(results_numexpr)
+        print(
+            f"numexpr time (threaded with re_evaluate over {num_chunks} chunks with {num_threads} threads): {numexpr_time:.6f} seconds"
+        )
+        print(f"numexpr speedup: {numpy_time / numexpr_time:.2f}x")
+        print("-" * 40)
+
+
+if __name__ == "__main__":
+    run_benchmark_threaded()

{numexpr-2.10.1 → numexpr-2.11.0}/bench/issue-36.py

@@ -2,10 +2,14 @@
 # performs better than the serial code.  See issue #36 for details.
 
 from __future__ import print_function
+
+from time import time
+
 import numpy as np
-import numexpr as ne
 from numpy.testing import assert_array_equal
-from time import time
+
+import numexpr as ne
+
 
 def bench(N):
     print("*** array length:", N)
@@ -31,4 +35,3 @@ if __name__ == "__main__":
     ne.set_num_threads(2)
     for N in range(10, 20):
         bench(2**N)
-

{numexpr-2.10.1 → numexpr-2.11.0}/bench/issue-47.py

@@ -1,4 +1,5 @@
 import numpy
+
 import numexpr
 
 numexpr.set_num_threads(8)