From 4b6d9140614dac24becc8ad3ac50365aa2f9d322 Mon Sep 17 00:00:00 2001
From: He Sichao <1310722434@qq.com>
Date: Tue, 18 Jun 2024 15:42:23 +0800
Subject: [PATCH] Update quantity.ipynb

---
 docs/physical_units/quantity.ipynb | 1450 +++++++++++++++++++++++++++-
 1 file changed, 1449 insertions(+), 1 deletion(-)

diff --git a/docs/physical_units/quantity.ipynb b/docs/physical_units/quantity.ipynb
index 52432e9..04bfa74 100644
--- a/docs/physical_units/quantity.ipynb
+++ b/docs/physical_units/quantity.ipynb
@@ -7,6 +7,139 @@
     "# Quantity"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Braincore generates standard names for units, combining the unit name (e.g. “siemens”) with a prefixes (e.g. “m”), and also generates squared and cubed versions by appending a number. For example, the units “msiemens”, “siemens2”, “usiemens3” are all predefined. You can import these units from the package `brianunit` – accordingly, an `from brainunit import *` will result in everything being imported.\n",
+    "\n",
+    "We recommend importing only the units you need, to have a cleaner namespace. For example, `import brainunit as bu` and then using `bu.msiemens` instead of `msiemens`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import brainunit as bu"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can generate a physical quantity by multiplying a scalar or ndarray with its physical unit:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "20. * msecond"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "tau = 20 * bu.ms\n",
+    "tau"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([10., 20., 30.], dtype=float32) * hertz"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "rates = [10, 20, 30] * bu.Hz\n",
+    "rates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[10., 20., 30.],\n",
+       "           [20., 30., 40.]], dtype=float32) * hertz"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "rates = [[10, 20, 30], [20, 30, 40]] * bu.Hz\n",
+    "rates"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Braincore will check the consistency of operations on units and raise an error for dimensionality mismatches:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Cannot calculate ... += 1, units do not match (units are s and 1).\n"
+     ]
+    }
+   ],
+   "source": [
+    "try:\n",
+    "    tau += 1  # ms? second?\n",
+    "except Exception as e:\n",
+    "    print(e)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Cannot calculate 3.0 + 3.0, units do not match (units are kg and A).\n"
+     ]
+    }
+   ],
+   "source": [
+    "try:\n",
+    "    3 * bu.kgram + 3 * bu.amp\n",
+    "except Exception as e:\n",
+    "    print(e)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -14,6 +147,438 @@
     "## Creating Quantity Instances"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Creating a Quantity object can be accomplished in several ways, categorized based on the type of input used. Here, we present the methods grouped by their input types and characteristics for better clarity."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import jax.numpy as jnp\n",
+    "import brainstate as bst\n",
+    "bst.environ.set(precision=64) # we recommend using 64-bit precision for better numerical stability"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Scalar and Array Multiplication\n",
+    "- Multiplying a Scalar with a Unit"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "5. * msecond"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "5 * bu.ms"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Multiplying a Jax nunmpy value type with a Unit:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "5. * msecond"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "jnp.float64(5) * bu.ms"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Multiplying a Jax numpy array with a Unit:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([1., 2., 3.]) * msecond"
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "jnp.array([1, 2, 3]) * bu.ms"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Multiplying a List with a Unit:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([1., 2., 3.]) * msecond"
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[1, 2, 3] * bu.ms"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Direct Quantity Creation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Creating a Quantity Directly with a Value"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Quantity(5.)"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity(5)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Creating a Quantity Directly with a Value and Unit"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "5. * msecond"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity(5, unit=bu.ms)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Creating a Quantity with a Jax numpy Array of Values and a Unit"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([1., 2., 3.]) * msecond"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity(jnp.array([1, 2, 3]), unit=bu.ms)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Creating a Quantity with a List of Values and a Unit"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([1., 2., 3.]) * msecond"
+      ]
+     },
+     "execution_count": 15,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity([1, 2, 3], unit=bu.ms)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Creating a Quantity with a List of Quantities"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([0.5, 1. ]) * second"
+      ]
+     },
+     "execution_count": 16,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity([500 * bu.ms, 1 * bu.second])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "- Using the with_units Method"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([0.5, 1. ]) * second"
+      ]
+     },
+     "execution_count": 17,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity.with_units(jnp.array([0.5, 1]), second=1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Unitless Quantity\n",
+    "Quantities can be unitless, which means they have no units. If there is no unit provided, the quantity is assumed to be unitless. The following are examples of creating unitless quantities:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Quantity(ArrayImpl([1., 2., 3.]))"
+      ]
+     },
+     "execution_count": 18,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity([1, 2, 3])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 19,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Quantity(ArrayImpl([1., 2., 3.]))"
+      ]
+     },
+     "execution_count": 19,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity(jnp.array([1, 2, 3]))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Quantity(ArrayImpl([], dtype=float64))"
+      ]
+     },
+     "execution_count": 20,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "bu.Quantity([])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Illegal Quantity Creation\n",
+    "The following are examples of illegal quantity creation:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 21,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "All elements must have the same unit\n"
+     ]
+    }
+   ],
+   "source": [
+    "try:\n",
+    "    bu.Quantity([500 * bu.ms, 1])\n",
+    "except Exception as e:\n",
+    "    print(e)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 22,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Value 'some' with dtype <U4 is not a valid JAX array type. Only arrays of numeric types are supported by JAX.\n"
+     ]
+    }
+   ],
+   "source": [
+    "try:\n",
+    "    bu.Quantity([\"some\", \"nonsense\"])\n",
+    "except Exception as e:\n",
+    "    print(e)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "All elements must have the same unit\n"
+     ]
+    }
+   ],
+   "source": [
+    "try:\n",
+    "    bu.Quantity([500 * bu.ms, 1 * bu.volt])\n",
+    "except Exception as e:\n",
+    "    print(e)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -21,6 +586,13 @@
     "## Converting to Different Units"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "TODO"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -28,6 +600,109 @@
     "## Attributes of a Quantity"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The important attributes of a `Quantity` object are:\n",
+    "- `value`: the numerical value of the quantity\n",
+    "- `dim`: the dimension of the unit of the quantity\n",
+    "- `ndim`: the number of dimensions of quantity's value\n",
+    "- `shape`: the shape of the quantity's value\n",
+    "- `size`: the size of the quantity's value\n",
+    "- `dtype`: the dtype of the quantity's value"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### An example"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[10., 20., 30.],\n",
+       "           [20., 30., 40.]]) * hertz"
+      ]
+     },
+     "execution_count": 24,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "rates = [[10, 20, 30], [20, 30, 40]] * bu.Hz\n",
+    "rates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 25,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Array([[10., 20., 30.],\n",
+       "       [20., 30., 40.]], dtype=float64, weak_type=True)"
+      ]
+     },
+     "execution_count": 25,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "rates.value"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "second ** -1"
+      ]
+     },
+     "execution_count": 26,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "rates.dim"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 27,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(2, (2, 3), 6, dtype('float64'))"
+      ]
+     },
+     "execution_count": 27,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "rates.ndim, rates.shape, rates.size, rates.dtype"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -35,6 +710,35 @@
     "## Arithmetic Functions"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Like Numpy and Jax numpy, arithmetic operators on arrays apply elementwise."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 28,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([0., 1., 2., 3.]) * mvolt"
+      ]
+     },
+     "execution_count": 28,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "a = [20, 30, 40, 50] * bu.mV\n",
+    "b = jnp.arange(4) * bu.mV\n",
+    "b"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -42,17 +746,761 @@
     "### Addition and Subtraction"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Addition and subtraction of quantities need to have the same units and keep the units in the result."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 29,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([20., 29., 38., 47.]) * mvolt"
+      ]
+     },
+     "execution_count": 29,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "c = a - b\n",
+    "c"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 30,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([20., 30., 40., 50.]) * mvolt"
+      ]
+     },
+     "execution_count": 30,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "c + b"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Multiplication and Division"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Multiplication and division of quantities multiply and divide the values and add and subtract the dimensions of the units."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 31,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(ArrayImpl([[1., 2.],\n",
+       "            [3., 4.]]) * mvolt,\n",
+       " ArrayImpl([[5., 6.],\n",
+       "            [7., 8.]]) * mvolt)"
+      ]
+     },
+     "execution_count": 31,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A = jnp.array([[1, 2], [3, 4]]) * bu.mV\n",
+    "B = jnp.array([[5, 6], [7, 8]]) * bu.mV\n",
+    "\n",
+    "A, B"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 32,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[ 5., 12.],\n",
+       "           [21., 32.]]) * mvolt2"
+      ]
+     },
+     "execution_count": 32,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A * B # element-wise multiplication"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 33,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[19., 22.],\n",
+       "           [43., 50.]]) * mvolt2"
+      ]
+     },
+     "execution_count": 33,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A @ B # matrix multiplication"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 34,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[19., 22.],\n",
+       "           [43., 50.]]) * mvolt2"
+      ]
+     },
+     "execution_count": 34,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A.dot(B) # matrix multiplication"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 35,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[0.5, 1. ],\n",
+       "           [1.5, 2. ]]) * mvolt"
+      ]
+     },
+     "execution_count": 35,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A / 2 # divide by a scalar"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "if the unit of result is unitless, the unit is removed and returned as jax.Array"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 38,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "Array([[0.5, 1. ],\n",
+       "       [1.5, 2. ]], dtype=float64, weak_type=True)"
+      ]
+     },
+     "execution_count": 38,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A / (2 * bu.mV) # divide by a quantity, return jax array"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 40,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[0.5, 1. ],\n",
+       "           [1.5, 2. ]]) * ohm"
+      ]
+     },
+     "execution_count": 40,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A / (2 * bu.mA) # divide by a quantity, return quantity"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Power"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The power operator raises the value of the quantity to the power of the scalar, and multiplies the unit by the scalar."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 48,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[1., 2.],\n",
+       "           [3., 4.]]) * mvolt"
+      ]
+     },
+     "execution_count": 48,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 49,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[ 1.,  4.],\n",
+       "           [ 9., 16.]]) * mvolt2"
+      ]
+     },
+     "execution_count": 49,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "A ** 2 # element-wise power"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Built-in Functions"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Braincore provides a number of built-in functions in `Quantity` class to perform operations on quantities. These functions are:\n",
+    "- unary operations\n",
+    "    - positive(+)\n",
+    "    - negative(-)\n",
+    "    - absolute(abs)\n",
+    "    - invert(~)\n",
+    "- logical operations\n",
+    "    - all\n",
+    "    - any\n",
+    "- shape operations\n",
+    "    - reshape\n",
+    "    - resize\n",
+    "    - squeeze\n",
+    "    - unsqueeze\n",
+    "    - spilt\n",
+    "    - swapaxes\n",
+    "    - transpose\n",
+    "    - ravel\n",
+    "    - take\n",
+    "    - repeat\n",
+    "    - diagonal\n",
+    "    - trace\n",
+    "- mathematical functions\n",
+    "    - nonzero\n",
+    "    - argmax\n",
+    "    - argmin\n",
+    "    - argsort\n",
+    "    - var\n",
+    "    - round\n",
+    "    - std\n",
+    "    - sum\n",
+    "    - cumsum\n",
+    "    - cumprod\n",
+    "    - max\n",
+    "    - mean\n",
+    "    - min\n",
+    "    - ptp\n",
+    "    - clip\n",
+    "    - conj\n",
+    "    - dot\n",
+    "    - fill\n",
+    "    - item\n",
+    "    - prod\n",
+    "    - clamp\n",
+    "    - sort\n",
+    "\n",
+    "For more details on these functions, refer to the [documentation](https://braincore.readthedocs.io/en/latest/braincore/apis/generated/brainunit.Quantity.html)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Indexing, Slicing and Iterating"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "One-dimensional Quantity can be indexed, sliced and iterated over, much like lists and other Python sequences."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 41,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([  0.,   1.,   8.,  27.,  64., 125., 216., 343., 512., 729.]) * mvolt"
+      ]
+     },
+     "execution_count": 41,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "a = jnp.arange(10) ** 3 * bu.mV\n",
+    "a"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 42,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "8. * mvolt"
+      ]
+     },
+     "execution_count": 42,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "a[2]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 43,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([ 8., 27., 64.]) * mvolt"
+      ]
+     },
+     "execution_count": 43,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "a[2:5]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Only same dimension Quantity can be set to a slice of a Quantity."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 44,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([1000.,    1., 1000.,   27., 1000.,  125.,  216.,  343.,  512.,\n",
+       "            729.]) * mvolt"
+      ]
+     },
+     "execution_count": 44,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# equivalent to a[0:6:2] = 1000;\n",
+    "# from start to position 6, exclusive, set every 2nd element to 1000\n",
+    "a[:6:2] = 1000 * bu.mV\n",
+    "a"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 45,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([ 729.,  512.,  343.,  216.,  125., 1000.,   27., 1000.,    1.,\n",
+       "           1000.]) * mvolt"
+      ]
+     },
+     "execution_count": 45,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "a[::-1] # reversed a"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 46,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "1. m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "0.1 m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "1. m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "0.3 m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "1. m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "0.5 m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "0.6 m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "0.7 m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "0.8 m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n",
+      "0.9 m^0.6666666666666666 kg^0.3333333333333333 s^-1.0 A^-0.3333333333333333\n"
+     ]
+    }
+   ],
+   "source": [
+    "for i in a:\n",
+    "    print(i**(1 / 3.))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Multidimensional Quantity can have one index per axis. These indices are given in a tuple separated by commas:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 50,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[ 0.,  1.,  2.,  3.],\n",
+       "           [10., 11., 12., 13.],\n",
+       "           [20., 21., 22., 23.],\n",
+       "           [30., 31., 32., 33.],\n",
+       "           [40., 41., 42., 43.]]) * mvolt"
+      ]
+     },
+     "execution_count": 50,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "def f(x, y):\n",
+    "    return 10 * x + y\n",
+    "b = jnp.fromfunction(f, (5, 4), dtype=jnp.int32) * bu.mV\n",
+    "b"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 51,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "23. * mvolt"
+      ]
+     },
+     "execution_count": 51,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "b[2, 3]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 52,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([ 1., 11., 21., 31., 41.]) * mvolt"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "b[0:5, 1]  # each row in the second column of b"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 53,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([ 1., 11., 21., 31., 41.]) * mvolt"
+      ]
+     },
+     "execution_count": 53,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "b[:, 1]  # equivalent to the previous example"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 54,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[10., 11., 12., 13.],\n",
+       "           [20., 21., 22., 23.]]) * mvolt"
+      ]
+     },
+     "execution_count": 54,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "b[1:3, :]  # each column in the second and third row of b"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When fewer indices are provided than the number of axes, the missing indices are considered complete slices:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 55,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([40., 41., 42., 43.]) * mvolt"
+      ]
+     },
+     "execution_count": 55,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "b[-1]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The expression within brackets in b[i] is treated as an i followed by as many instances of : as needed to represent the remaining axes. NumPy also allows you to write this using dots as b[i, ...].\n",
+    "\n",
+    "The dots (...) represent as many colons as needed to produce a complete indexing tuple. For example, if x is a Quantity with 5 axes, then\n",
+    "- x[1, 2, ...] is equivalent to x[1, 2, :, :, :],\n",
+    "- x[..., 3] to x[:, :, :, :, 3] and\n",
+    "- x[4, ..., 5, :] to x[4, :, :, 5, :]."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 56,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(2, 2, 3)"
+      ]
+     },
+     "execution_count": 56,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "c = jnp.array([[[0, 1, 2], [10, 12, 13]], [[100, 101, 102], [110, 112, 113]]]) * bu.mV # a 3D array (two stacked 2D arrays)\n",
+    "c.shape"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 57,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[100., 101., 102.],\n",
+       "           [110., 112., 113.]]) * mvolt"
+      ]
+     },
+     "execution_count": 57,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "c[1, ...] # same as c[1, :, :] or c[1]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 58,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ArrayImpl([[  2.,  13.],\n",
+       "           [102., 113.]]) * mvolt"
+      ]
+     },
+     "execution_count": 58,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "c[..., 2] # same as c[:, :, 2]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Iterating over multidimensional Quantity is done with respect to the first axis:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 59,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[0. 1. 2. 3.] mV\n",
+      "[10. 11. 12. 13.] mV\n",
+      "[20. 21. 22. 23.] mV\n",
+      "[30. 31. 32. 33.] mV\n",
+      "[40. 41. 42. 43.] mV\n"
+     ]
+    }
+   ],
+   "source": [
+    "for row in b:\n",
+    "    print(row)"
+   ]
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "brainpy-dev",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,