python/tests/hypercube.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b02ed67f-6299-4a25-be67-d37b737b917d",
   "metadata": {},
   "source": [
    "# Hypercube\n",
    "\n",
    "### Table of Content\n",
    "1. Overview\n",
    "2. Definitions and Basics\n",
    "3. Rolling\n",
    "4. Memory-Mapped Hypercube\n",
    "5. Cube Math and Vectorized Cube Math\n",
    "6. Python Integration and Interoperability with `numpy`\n",
    "7. Translating `numpy` code to Java\n",
    "8. Benchmarks and Performance\n",
    "\n",
    "## Overview\n",
    "`hypercube` is an `ndarray`-like package for Java, designed to offer a representation for `numpy` `ndarray`s that is feature-rich in numerical computations. Furthermore, hypercubes are designed to be interoperable with `numpy`, as we'll show in the examples. Additionally, this package can be used to directly translate `numpy` code into Java. E.g., you can prototype in Python but, if you have a codebase which is using Java for the heavy computations, then Hypercube can aid the development process.\n",
    "\n",
    "As part of the `hypercube` package, the `CubeMath` library is designed to offer many of `numpy`'s math operations for Hypercubes. As part of this effort, we have also developed `VectorizedCubeMath`, an experimental library, that offers SIMD-accelerated operations through [the Vector API](https://openjdk.org/jeps/426). It's worth making note here that [the Vector API](https://openjdk.org/jeps/426), as of 08/18/2023, is an incubator module in Java, and so it should be regarded as highly experimental.\n",
    "\n",
    "In this notebook, we'll be using hypercubes in Python (through PJRmi) for ease of demonstration. We'll be covering:\n",
    "- Hypercubes and `ndarray` operations on them\n",
    "- `CubeMath` and math operations on hypercubes\n",
    "- `VectorizedCubeMath` (experimental library)\n",
    "- Performance and benchmarks\n",
    "\n",
    "### Let's dive in!\n",
    "\n",
    "Note that we're passing the `includeVectorized` parameter to include `VectorizedCubeMath` in our build. By default, all Vectorized code is hidden from the build, since it requires Java 17 and we don't want to force users there unless we have to.\n",
    "\n",
    "Assuming you are in the PJRmi directory and only have one wheel file, you can run something like:\n",
    "\n",
    "```\n",
    "./gradlew wheel -PincludeVectorized\n",
    "unzip -f python/pjrmi-*.whl\n",
    "```\n",
    "Note: If some of the cells in the below do not work, you may need to add the directory containing the wheel (e.g. `pjrmi/python`) to the `PYTHONPATH`. This can occur when the global PJRmi version differs from the one we just built.\n",
    "\n",
    "Now we'll setup a PJRmi connection. Note that we're:\n",
    "- Using shared memory passing (for our benchmarks)\n",
    "- Enabling the incubated Vector API module in Java to be able to use `VectorizedCubeMath`\n",
    "\n",
    "##### Note on Fine-Tuning Performance\n",
    "It's worth noting that both of the cube math libraries support multithreaded processing, as well as efficient loop unrolling. By default, both libraries use a staging size of 128 for better loop unrolling and 4 threads for multithreaded processing, which are only enabled after a rough threshold to avoid the overhead of multithreading. More formally:\n",
    "- Staging size: The number of elements to process \"in bulk\" (by default 128).\n",
    "- Number of threads: The number of threads to use when multithreading (by default 4).\n",
    "- Multithreading threshold: The cube size at which Cube Math will enable multithreaded processing (by default 131,072).\n",
    "\n",
    "These parameters can all be arbitrarily set to fine-tune the performance of the cube math libraries to specific environments or machines. To do so, we can pass the following corresponding Java properties when initializing our Java connection.\n",
    "- `com.deshaw.hypercube.cubemath.stagingSize` -- The number of elements to stage when processing operations in bulk.\n",
    "- `com.deshaw.hypercube.cubemath.threadingThreshold` -- The cube size threshold at which VectorizedCubeMath will use multithreading.\n",
    "- `com.deshaw.hypercube.cubemath.numThreads` -- The number of threads used for multithreaded processing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27211bed-3c0e-4ab6-a803-a7e804856a9b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# What we'll need for this\n",
    "import numpy as np, numpy\n",
    "import pjrmi\n",
    "import time\n",
    "import timeit\n",
    "\n",
    "# Get a new instance.\n",
    "#\n",
    "# Here the application_args are just to allow the server to have\n",
    "# multiple threads. This is only really needed if you intend to\n",
    "# use callbacks, which we will in our examples later below.\n",
    "#\n",
    "# We set the number of CubeMath threads to 1 so that the numpy\n",
    "# benchmarks are reasonably comparable.\n",
    "#\n",
    "# We also pipe the stdout and stderr of the Java process to\n",
    "# /dev/null by means of setting the filehandles to None.\n",
    "cx = pjrmi.connect_to_child_jvm(stdout=None,\n",
    "                                stderr=None,\n",
    "                                application_args=('num_workers=4',),\n",
    "                                use_shm_arg_passing=True,\n",
    "                                java_args=['--add-modules', 'jdk.incubator.vector',\n",
    "                                           '-Dcom.deshaw.hypercube.cubemath.numThreads=1'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "379ec4cb-989d-46af-826f-678ce242715b",
   "metadata": {},
   "source": [
    "### Hypercube Class Definitions\n",
    "\n",
    "Here we'll define the relevant Hypercube classes in Python, to be able to play around with them. We'll also define our two cube math libraries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dfdce7ae-1940-49c8-814e-539d0c30f46a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Defining all the relevant Hypercube classes\n",
    "Dimension              = cx.class_for_name('com.deshaw.hypercube.Dimension')\n",
    "Hypercube              = cx.class_for_name('com.deshaw.hypercube.Hypercube')\n",
    "BooleanBitSetHypercube = cx.class_for_name('com.deshaw.hypercube.BooleanBitSetHypercube')\n",
    "DoubleArrayHypercube   = cx.class_for_name('com.deshaw.hypercube.DoubleArrayHypercube')\n",
    "FloatArrayHypercube    = cx.class_for_name('com.deshaw.hypercube.FloatArrayHypercube')\n",
    "IntegerArrayHypercube  = cx.class_for_name('com.deshaw.hypercube.IntegerArrayHypercube')\n",
    "LongArrayHypercube     = cx.class_for_name('com.deshaw.hypercube.LongArrayHypercube')\n",
    "DoubleMappedHypercube  = cx.class_for_name('com.deshaw.hypercube.DoubleMappedHypercube')\n",
    "DoubleSparseHypercube  = cx.class_for_name('com.deshaw.hypercube.DoubleSparseHypercube')\n",
    "\n",
    "# Defining our two Cube Math implementations and aliases for them\n",
    "CubeMath           = cm  = cx.class_for_name('com.deshaw.hypercube.CubeMath')\n",
    "VectorizedCubeMath = vcm = cx.class_for_name('com.deshaw.hypercube.VectorizedCubeMath')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5dcd1b47-654a-4106-88c1-1646d9fed000",
   "metadata": {},
   "source": [
    "Let's create an integer hypercube to work with."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9c23d1fd-ceb7-4766-9333-8b1919a54b7b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "cube = IntegerArrayHypercube(Dimension.of(10))\n",
    "cube"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "762f523f-a584-43a6-98d5-7b4b28ad6273",
   "metadata": {},
   "source": [
    "Now let's populate our cube with some values. We can use the `fromFlattened()` method for this. As the name suggests, using this method we can _unflatten_ an array of data into our cube. We can use `numpy` arrays, lists or any other iterable for this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d7b6d22-8cf7-4516-bd5c-d7dc2a7448fb",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "cube.fromFlattened(np.arange(10, dtype = np.int32))\n",
    "print(cube)\n",
    "cube.fromFlattened(range(10, 0, -1))\n",
    "print(cube)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9447b46d-8965-4191-a9b5-f0ea4372affd",
   "metadata": {},
   "source": [
    "We can also use most Python syntax on hypercubes. Here's an example of a few things we can do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e610820-b4f4-4b2b-aeb4-94dc11ec4941",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# We can call magic functions on cubes\n",
    "print(f\"Length of the cube is {len(cube)}.\")\n",
    "for i,e in enumerate(cube):\n",
    "    print(f\"The {i}-th element of the cube is {e}.\")\n",
    "\n",
    "# We can slice cubes\n",
    "subcube = cube[3:7]\n",
    "print(\"Subcube:\")\n",
    "print(subcube)\n",
    "\n",
    "# We can use Python's get/set syntax\n",
    "subcube[0] = 10",
    "print(cube[3]) # Unsurprisingly, the change is reflected in the original cube."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "367484b9-6403-41bd-baf0-5dea03a2ed9c",
   "metadata": {},
   "source": [
    "### Rolling\n",
    "\n",
    "Much like `ndarray`s, hypercubes support both flat rolling, and rolling across certain axes. This allows us to use cubes in a streaming data idiom.\n",
    "\n",
    "For example, if the primary axis is time, then we could roll the cube along that axis by one, pushing data back such that the oldest data wraps to the head, and then overwrite that data with the new data:\n",
    "\n",
    "    data                        [5, 4, 3, 2, 1]\n",
    "    data.roll(1, axis = 0)  =>  [1, 5, 4, 3, 2]\n",
    "    data[0] = 6             =>  [6, 5, 4, 3, 2] \n",
    "\n",
    "By doing so, we can use the same code in a static (non-realtime) context, as well as a realtime one."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ef3670b9-88e9-48e6-af16-483aebc644db",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# First let's reshape the cube, so we have multiple dimensions to work with.\n",
    "reshaped = cube.reshape((2, 5))\n",
    "print(\"Reshaped:\")\n",
    "print(reshaped)\n",
    "\n",
    "# Now shift (i.e., \"flat roll\") the cube.\n",
    "shifted = reshaped.roll(2)\n",
    "print(\"Shifted:\")\n",
    "print(shifted)\n",
    "\n",
    "# Now let's try rolling the cube across both axes.\n",
    "rolled = reshaped.roll((1, 2))\n",
    "print(\"Rolled:\")\n",
    "print(rolled)\n",
    "\n",
    "# We can also roll a cube by specifying a specific dimension\n",
    "print(reshaped.roll(2, axis=1))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c60ca969",
   "metadata": {},
   "source": [
    "### Memory-Mapped Hypercube\n",
    "\n",
    "Hypercube also offers a class of memory-mapped cubes that store their elements in a memory-mapped file. This memory-mapped file is readable by `numpy`'s memory-mapped arrays, which allows for seamless data transfer between Java and Python. For example, you can simultaneously work on the same `ndarray` both from a Java and a Python client, without even using PJRmi.\n",
    "\n",
    "We can see an example of this seamless transfer between these cubes and arrays below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dc30581f",
   "metadata": {},
   "outputs": [],
   "source": [
    "marray = numpy.memmap('/dev/shm/example.dat', dtype = numpy.float64, mode = 'w+', shape = (3,3), order = 'C')\n",
    "mcube  = DoubleMappedHypercube('/dev/shm/example.dat', Dimension.of((3, 3)))\n",
    "\n",
    "print(\"Memory-mapped array:\")\n",
    "print(marray)\n",
    "print(\"Memory-mapped cube:\")\n",
    "print(mcube)\n",
    "\n",
    "# Let's make a change in our array\n",
    "marray += 1\n",
    "\n",
    "# Let's see the change reflected in our cube\n",
    "print(\"Updated memory-mapped cube:\")\n",
    "print(mcube)\n",
    "\n",
    "# Now let's make a change to our cube\n",
    "CubeMath.negative(mcube, mcube)\n",
    "\n",
    "# Let's see the change reflected in our array\n",
    "print(\"Updated memory-mapped array:\")\n",
    "print(marray)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26b9e0bd-dd83-4df5-872c-a2bca967a14d",
   "metadata": {},
   "source": [
    "### Sparse Hypercube\n",
    "\n",
    "For high-dimensional data which isn't dense it may be desirable to have a more memory efficient backing store. The sparse cubes provide this support."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3e604b08-94ff-4187-a900-b831b28766e4",
   "metadata": {},
   "outputs": [],
   "source": [
    "sparse = DoubleSparseHypercube(Dimension.of((4, 4)))\n",
    "k = 0\n",
    "for i in range(0, 4):\n",
    "    for j in range(0, 4):\n",
    "        if ((i + j) % 2) == 0:\n",
    "            sparse[i,j] = k\n",
    "            k += 1\n",
    "print(\"Sparse:\")\n",
    "print(sparse)\n",
    "print(\"Sum: \", CubeMath.nansum(sparse))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b9669db-1c78-4ecd-b8b7-0a3747c701d9",
   "metadata": {},
   "source": [
    "Now that we've established the basics, let's get into the fun bits!\n",
    "\n",
    "### Cube Math\n",
    "\n",
    "Hypercube offers many of `numpy`'s `ndarray` operations for cubes, through the `CubeMath` and `VectorizedCubeMath` libraries. We have added support for some of the most commonly used `numpy` `ndarray` operations as a start, with more operations to be supported soon. Now, while these two libraries use different internal implementations for their operations, they both provide the exact same API to the users, and can be used interchangeably. Here we'll only show the examples on CubeMath for the sake of brevity.\n",
    "\n",
    "As of 08/23/2023, the full list of supported operations and data types in CubeMath can be found in the tables below:\n",
    "\n",
    "| Arithmetic | Arithmetic | Bitwise | Comparative | Comparative | Math  | Math  | Math  | Reductive | Reductive | Misc.     |\n",
    "|:----------:|:----------:|:-------:|:-----------:|:-----------:|:-----:|:-----:|:-----:|:---------:|:---------:|:---------:|\n",
    "| add        | modulo     | and     | =           | !=          | sin   | cos   | tan   | sum       | nansum    | extract   |\n",
    "| subtract   | power      | or      | <           | >           | sinh  | cosh  | tanh  | min       | max       | type cast |\n",
    "| multiply   | negative   | xor     | <=          | >=          | exp   | log   | log10 | any       | all       | copy      |\n",
    "| divide     | abs        | not     |             |             | floor | round | ceil  |           |           | broadcast |\n",
    "\n",
    "VectorizedCubeMath supports the same operations and data types as CubeMath. However, vectorized implementation is not supported for certain operations (marked in red in the table below). VectorizedCubeMath uses the standard implementation for these operations.\n",
    "\n",
    "| Arithmetic | Arithmetic | Bitwise | Comparative | Comparative | Math  | Math  | Math  | Reductive | Reductive |\n",
    "|:----------:|:----------:|:-------:|:-----------:|:-----------:|:-----:|:-----:|:-----:|:---------:|:---------:|\n",
    "| add        |            | and     | =           | !=          | sin   | cos   | tan   | sum       | nansum    |\n",
    "| subtract   | power      | or      | <           | >           | sinh  | cosh  | tanh  | min       | max       |\n",
    "| multiply   | negative   | xor     | <=          | >=          | exp   | log   | log10 | any       | all       |\n",
    "| divide     | abs        | not     |\n",
    "\n",
    "Now, let's see some of these operations in action:\n",
    "\n",
    "#### Basic math operations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a75a8918-e5f9-462a-9e40-bb20f591c5b4",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Again, don't forget to properly cast your numbers in Python\n",
    "print(\"Add with a value:\\n\",      CubeMath.add  (cube, 10))\n",
    "print(\"Add with a cube:\\n\",       CubeMath.add  (cube, cube))\n",
    "print(\"Xor with a cube:\\n\",       CubeMath.xor  (cube, cube))\n",
    "print(\"Equality with a value:\\n\", CubeMath.equal(cube, 10))\n",
    "print(\"Equality with a cube:\\n\",  CubeMath.equal(cube, cube))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e833fd49-cfd4-4ba8-97f2-9bd3ffd4ce37",
   "metadata": {},
   "source": [
    "#### Reductive operations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2de9fe35-20e4-4543-b2e6-b6d12d41c339",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(\"Min value:\\n\", CubeMath.min0d(cube))\n",
    "print(\"Max value:\\n\", CubeMath.max0d(cube))\n",
    "print(\"Sum:\\n\", CubeMath.sum0d(cube))\n",
    "\n",
    "# This one doesn't really make sense for integers, but you get the idea.\n",
    "print(\"NanSum:\\n\", CubeMath.nansum0d(cube))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a9e901b-cae2-48f8-a395-706d5666efde",
   "metadata": {},
   "source": [
    "#### Boolean selection and population count\n",
    "\n",
    "You can mix and match to get more complicated expressions too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9d61f64-63bd-4b57-bffc-cf0d5192fafc",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(\"How many values in the cube are greater than 6?\\n\", CubeMath.popcount(CubeMath.greater(cube, np.int32(6))))\n",
    "\n",
    "# Boolean extraction (selection)\n",
    "print(\"The elements that are smaller than 5:\\n\", CubeMath.extract(CubeMath.less(cube, np.int32(5)), cube))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "892dedd5-0205-44ef-b93d-3eec94a5db27",
   "metadata": {},
   "source": [
    "##### Copying and casting\n",
    "CubeMath also allows you to get casted copied of cubes in different data types. We can also just copy a given cube without casting it to other data types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6bba66fd-7c1e-4a5b-b9b8-607f250f076d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "double_cube = CubeMath.toDoubleHypercube(cube)\n",
    "print(\"Double Hypercube:\\n\", double_cube)\n",
    "\n",
    "copy_cube = CubeMath.copy(cube)\n",
    "print(\"Copy:\\n\", copy_cube)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a482e72e-f762-4d4b-bc20-225962c4ca03",
   "metadata": {},
   "source": [
    "#### Math functions\n",
    "\n",
    "CubeMath also supports your favorite math functions, from trigonometric functions, to basic utility functions like `floor()`.\n",
    "\n",
    "Note that certain math functions (like trigonometric ones) are only supported for floating-point data types. You can, however, cast your integer cubes (just we did like above) before applying your favorite math functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "33e37990-d747-4c15-99a5-f8fbded2376e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(\"Sin:\\n\",   CubeMath.sin(double_cube))\n",
    "print(\"Cos:\\n\",   CubeMath.cos(double_cube))\n",
    "print(\"Tanh:\\n\",  CubeMath.tanh(double_cube))\n",
    "print(\"Exp:\\n\",   CubeMath.exp(double_cube))\n",
    "print(\"Log:\\n\",   CubeMath.log(double_cube))\n",
    "print(\"Log10:\\n\", CubeMath.log10(double_cube))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f0f7f21-a009-4039-ae2e-c50230648bf4",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-08-17T21:24:56.308956Z",
     "iopub.status.busy": "2023-08-17T21:24:56.308570Z",
     "iopub.status.idle": "2023-08-17T21:24:56.318084Z",
     "shell.execute_reply": "2023-08-17T21:24:56.317672Z",
     "shell.execute_reply.started": "2023-08-17T21:24:56.308938Z"
    },
    "tags": []
   },
   "source": [
    "### Python Integration and interoperability with `numpy`\n",
    "\n",
    "Hypercubes can almost always be treated `ndarray`s in Python and so `ndarray` syntax and functions apply to them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eaa73d97-67b2-4dc0-8e4b-a81e186da8ef",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(cube)\n",
    "print(cube - cube)\n",
    "print(cube ** 2)\n",
    "print(cube / 2)\n",
    "print(cube // 2)\n",
    "print(cube == 10)\n",
    "print(cube[cube > 6])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d8c6a715-7de2-4bc7-926d-f40d9bf47a19",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# We can make numpy arrays from cubes.\n",
    "array = np.array(cube)\n",
    "print(\"Array:\\n\", type(array), array)\n",
    "\n",
    "# We can use numpy functions on cubes.\n",
    "print(\"`numpy` sum of cube:\\n\", np.sum(cube))\n",
    "\n",
    "# We can use CubeMath functions on numpy arrays.\n",
    "print(\"CubeMath sum of `numpy` array:\\n\", CubeMath.sum0d(array))\n",
    "\n",
    "# We can call operations on numpy arrays and cubes together, both from numpy and CubeMath.\n",
    "print(\"`numpy` equal:\\n\", array == cube)\n",
    "print(\"CubeMath equal:\\n\", CubeMath.equal(array, cube))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01abae49-1e0a-44b7-9827-7bd5b8fdfd77",
   "metadata": {},
   "source": [
    "Note that hypercube instances do not support all `numpy` array methods as attributes. You can, however, call the static `numpy` version of these functions with your cube as an argument. Let's take a look at the following example to see what you can and can not expect from hypercube:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d31cf5bc-0031-45a8-8ff4-cb238c9c1b17",
   "metadata": {
    "tags": [
     "pyflyby-cell"
    ]
   },
   "outputs": [],
   "source": [
    "reshaped_array = np.array(reshaped)\n",
    "\n",
    "print(\"Our previously reshaped cube as an array:\")\n",
    "print(reshaped_array)\n",
    "print(\"Now with the axes swapped:\")\n",
    "print(reshaped_array.swapaxes(0, 1))\n",
    "\n",
    "# Now try swapping the cube's axes through the static np.swapaxes method\n",
    "print(\"Swapping the cube's axes:\")\n",
    "print(np.swapaxes(reshaped, 0, 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2a0c245c-15fa-4c11-94ed-23550d05de66",
   "metadata": {},
   "source": [
    "What happened?\n",
    "\n",
    "We see that `reshaped.swapaxes(0, 1)` throws an error since our cube object has no attribute called `swapaxes` (which is as expected). However, this doesn't stop us from calling the static `np.swapaxes` method on our cube."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eba72ef7",
   "metadata": {},
   "source": [
    "### Translating `numpy` to Java\n",
    "\n",
    "At times, we might find the need or the desire to translate code written in `numpy` to Java. Here, we are going to show you the very broad formula for doing this translation. Depending on your specific needs, you may need to use Hypercube or CubeMath differently, but these general instructions will hopefully provide useful insights for the users:\n",
    "\n",
    "1. Magic methods: While Python supports magic dunder functions like `len()`, Java lacks such a feature and so hypercubes cannot use the same syntax in Java (this is also the case for operator overloading, e.g. doing `array[indices]`). However, Hypercube implements similar methods that can be used to achieve the same functionality (`cube.getObj(indices)` and `cube.get(indices)` as opposed to `array[indices]`). Alternatively, you can explicitly call the corresponding dunder methods on hypercubes (e.g., `cube.__getitem__(indices)`), although we do not recommend this behavior.\n",
    "2. It is worth noting here that due to how Java's type system works, primitive hypercubes (e.g., `IntegerHypercube` etc.) offer both object methods, and primitive ones for many of their operations (e.g., `cube.getObj(indices)` and `cube.get(indices)` as mentioned above). While all these method work as expected, we encourage using the latter for primitive hypercubes, since methods that deal with objects tend to make for a lousy performance, significantly slower than their primitive counterparts.\n",
    "3. Static methods instead of member methods: While `numpy` provides many of its operations as instance methods, hypercubes (as of 08/24/2023) do not do the same. For example, while you are able to write `array.sum()`, using `cube.sum()` will not work. However, Hypercube offers `ndarray` math operations as part of the CubeMath library that can be used as static method. For example, you would do the same as above by calling `CubeMath.sum0d(cube)` (note that `numpy` supports a similar static notation, i.e. `numpy.sum(array)`).\n",
    "4. Type casting: CubeMath and `numpy` differ in the way they handle type-casting for certain operations. For example, `numpy` always converts integer arrays to real arrays before performing certain math operations like sin and cos. CubeMath, on the other hand, was designed to loosely follow Java's typing system, meaning that floating-point operations (like sin, cos) are not supported on integer cubes. When translating `numpy` code to Java, think about how you want to cubes to be casted, before certain operations. Conveniently, CubeMath supports casting methods that can be used to do this."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c18f71d1-4bed-407a-9d9d-b417986ec648",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-08-18T15:47:23.889236Z",
     "iopub.status.busy": "2023-08-18T15:47:23.888176Z",
     "iopub.status.idle": "2023-08-18T15:47:23.920908Z",
     "shell.execute_reply": "2023-08-18T15:47:23.919920Z",
     "shell.execute_reply.started": "2023-08-18T15:47:23.889200Z"
    },
    "tags": []
   },
   "source": [
    "### Benchmarks and Performance\n",
    "\n",
    "Now finally, let's dive into the exciting realm of performance and see how CubeMath and VectorizedCubeMath compare to each other, as well as to `numpy`.\n",
    "\n",
    "It's worth noting here that we're not trying to outperform or replace `numpy`, but rather try to mainly show _comparable_ performance.\n",
    "\n",
    "#### Technical note on vectorization:\n",
    "All supported operations in VectorizedCubeMath use the Vector API internally, while none in CubeMath do. However, certain operations in CubeMath can be auto-vectorized by compilers and thus be translated into SIMD instructions. This is one of the reasons that for certain operations, CubeMath performs similarly or even slightly faster than VectorizedCubeMath.\n",
    "\n",
    "#### Technical note on multithreaded processing:\n",
    "By default CubeMath and VectorizedCubeMath use 4 threads when using multithreaded processing (which is the case here).\n",
    "\n",
    "However, It's more difficult to reason about `numpy`'s multithreading and the exact number of threads it uses. Internally, `numpy` uses multiple multithreaded math libraries (e.g., Intel MKL and LAPACK) that work independently and use a different number of threads. This is different from the PJRmi threading model. While it is possible to individually limit the number of used threads on the internal libraries, configuring the number of threads is idiosyncratic to the various underlying backend libraries.\n",
    "\n",
    "Take note that the performance of these libraries are highly dependant on their configurations. For more accurate comparisons, it is very important to make sure you configure CubeMath and `numpy`'s multithreaded processing to use similar resources. For more information on the internal backend libraries that your `numpy` is using, you can run the `numpy.show_config()` command that provides all the relevant backend details, as well as supported SIMD instructions. For more information on the multithreading schemes of the individual backend libraries, consult the libraries' documentation.\n",
    "\n",
    "#### Methodology\n",
    "\n",
    "For our benchmarks, we'll be using IPython's own magic `%timeit` function on randomly generated 64-bit floating-point arrays of 100 million elements. This large array size is deliberately chosen to reduce the relative noise of the benchmark instruments, as well as PJRmi communication between Python and Java.\n",
    "\n",
    "You should test the performance of these libraries with your desired functions, data types and array sizes.\n",
    "\n",
    "#### Before we begin...\n",
    "Here we define some utility methods for creating `numpy` arrays and hypercubes, plus some _type abstractions_ for the sake of easier testing in Python. Really, what we're doing here is abstracting the internal hypercube implementations, for easier cube initialization in Python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f5bee25c-2764-4b5a-9f18-8605f3be2fb8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Utility method to make a `numpy` array of a given size and data type\n",
    "def make_array(size = 1e6, dtype = np.float64):\n",
    "    if dtype in [np.float32, np.float64]:\n",
    "        return np.array(np.random.rand(int(size)), dtype=dtype)\n",
    "    elif dtype == np.int32:\n",
    "        return np.array(np.random.rand(int(size)) * 1e9, dtype=dtype)\n",
    "    elif dtype == np.int64:\n",
    "        return np.array(np.random.rand(int(size)) * 1e18, dtype=dtype)\n",
    "    else:\n",
    "        return np.array(np.random.rand(int(size)), dtype=np.float32) > 0.5\n",
    "\n",
    "# Method to make a Hypercube out of a given `numpy` array, or a given size and data type\n",
    "def make_cube(size = 1e6, dtype = np.float64, arr = None):\n",
    "    if not isinstance(arr, numpy.ndarray):\n",
    "        arr = make_array(size, dtype)\n",
    "    return CubeMath.copy(arr)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e9e3272-cca1-42c5-b12c-74ec6911975d",
   "metadata": {},
   "source": [
    "#### Benchmarking\n",
    "\n",
    "Now let's dive into the exciting part!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9126dde3-14ac-4dab-b850-66cbb33b8ffa",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "size = 1e8\n",
    "dtype = np.float64\n",
    "\n",
    "# We use different cubes for CubeMath and VectorizedCubeMath to avoid caching benefits for one against the other.\n",
    "a = make_array(size, dtype)\n",
    "b = make_cube(size, dtype)\n",
    "c = make_cube(size, dtype)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0726c771-6352-475b-a64a-597ca5f1df57",
   "metadata": {},
   "source": [
    "First let's test some basic math operations.\n",
    "\n",
    "Note that we'll be using in-place computations throughout to avoid memory allocation noise in our timings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "67ae2696-8ed7-4bc1-82d6-c8ca93cabe9f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.add(a, a, a)\n",
    "%timeit CubeMath.add(b, b, b)\n",
    "%timeit VectorizedCubeMath.add(c, c, c)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e159961d-8f4e-4230-9ee7-efd3642178b1",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.exp(a, a)\n",
    "%timeit CubeMath.exp(b, b)\n",
    "%timeit VectorizedCubeMath.exp(c, c)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "543f1b08",
   "metadata": {},
   "source": [
    "Let's repopulate our array and cubes. Since we are using in-place operations, results can quickly propagate into very large/small numbers for certain operations (e.g., `exp`). We _reset_ our array and cubes to make sure we're passing a clean copy to the next operations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4970b664-6efb-45cc-b170-5076a76852f6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "a = make_array(size, dtype)\n",
    "b = make_cube(size, dtype)\n",
    "c = make_cube(size, dtype)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0b5b7f7-bdf7-4925-83ac-812c5e5a2c36",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.sin(a, a)\n",
    "%timeit CubeMath.sin(b, b)\n",
    "%timeit VectorizedCubeMath.sin(c, c)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c719a30f-0708-4923-b8e0-b9401f9e3be6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.tanh(a, a)\n",
    "%timeit CubeMath.tanh(b, b)\n",
    "%timeit VectorizedCubeMath.tanh(c, c)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b6edfa98-9d2b-45eb-94be-b4e33ab0dc5a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.sum(a)\n",
    "%timeit CubeMath.sum0d(b)\n",
    "%timeit VectorizedCubeMath.sum0d(c)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ce05c205-72a9-4cbd-aa01-7a33cad841a0",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.nansum(a)\n",
    "%timeit CubeMath.nansum0d(b)\n",
    "%timeit VectorizedCubeMath.nansum0d(c)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d326439-ea76-4624-8980-6a612a853134",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.min(a)\n",
    "%timeit CubeMath.min0d(b)\n",
    "%timeit VectorizedCubeMath.min0d(c)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9dfb422",
   "metadata": {},
   "source": [
    "Again, let's repopulate our array and cubes here to make sure we're using numbers between [0, 1] so that the result of `power` always stays in the same range."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bf6d7971-f821-4448-9138-8d88ceb13ec2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "a = make_array(size, dtype)\n",
    "b = make_cube(size, dtype)\n",
    "c = make_cube(size, dtype)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f0a27cb9-8f53-4948-9c12-1c384c3887e6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%timeit np.power(a, a, a)\n",
    "%timeit CubeMath.power(b, b, b)\n",
    "%timeit VectorizedCubeMath.power(c, c, c)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e731dd75",
   "metadata": {},
   "source": [
    "### Discussion on the Benchmark Results\n",
    "\n",
    "While it is unwise to generalize the performance of these libraries within certain environments to the others, it is useful to hypothesize why the libraries behave in a certain way for certain operations. That said, we will not be going into too much detail here, as our main goal is to show CubeMath and VectorizedCubeMath's competitive performance (and that they are not significantly slow compared to `numpy`).\n",
    "\n",
    "1. Basic Arithmetic Operations (e.g., +, -, =, etc.):\n",
    "The performance of CubeMath is expected to be similar to VectorizedCubeMath for these operations. This is because compilers are able to auto-vectorize these operations in CubeMath, resulting in SIMD performance.\n",
    "2. Complex Math Operations (e.g., sin, cos, exp, power, etc.):\n",
    "VectorizedCubeMath outperforms CubeMath (and at times `numpy`) in these operations because it uses specialized SIMD-instructions, as well as a highly optimized algorithm, written in native assembly and C. The exact performance of `numpy` will depend on the underlying backend libraries, and its configuration.\n",
    "3. Reductive operations (e.g., sum, nansum, etc.):\n",
    "VectorizedCubeMath and CubeMath perform similarly for reductive operations, with CubeMath being faster for some (e.g., min) and VectorizedCubeMath being faster in others (e.g., sum). Notably, CubeMath and VectorizedCubeMath tend to outperform `numpy` in nansum, since the latter uses `sum()` with a masked ndarray.\n",
    "\n",
    "It's worth noting once again that depending on the available hardware and the specific configurations, these libraries may perform differently.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24487381",
   "metadata": {},
   "source": [
    "### Wrapping up...\n",
    "\n",
    "This was just a very quick introduction to some of the things we can do with Hypercube. The general rule of thumb is that: if you expect it to work, then it probably should.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "name"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}