{
 "cells": [
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "# Combining and Defining Unit\n",
    "\n",
    "[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/chaobrain/brainunit/blob/master/docs/advanced_tutorials/combining_and_defining.ipynb)\n",
    "[![Open in Kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://github.com/chaobrain/brainunit/blob/master/docs/advanced_tutorials/combining_and_defining.ipynb)"
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Combining Example\n",
    "\n",
    "Units and quantities can be combined together using the regular Python numeric operators:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-04T15:09:52.158525Z",
     "start_time": "2026-03-04T15:09:51.421986700Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import brainunit as u\n",
    "volt = u.meter2 * u.kilogram / (u.second3 * u.ampere)\n",
    "volt == u.volt"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 1
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Defining Units\n",
    "\n",
    "Users are free to define new units, either fundamental or compound, using the `Unit.create` and  `Unit.create_scaled_unit` function:"
   ]
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Creating Basic Units\n",
    "\n",
    "First, we create some basic units, such as meters (metre) and seconds (second):"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-04T15:09:52.227159800Z",
     "start_time": "2026-03-04T15:09:52.176527300Z"
    }
   },
   "cell_type": "code",
   "source": [
    "# Creating a basic unit: metre\n",
    "metre = u.Unit.create(u.get_or_create_dimension(m=1), \"metre\", \"m\", base=10.)\n",
    "\n",
    "# Creating a basic unit: second\n",
    "second = u.Unit.create(u.get_or_create_dimension(s=1), \"second\", \"s\", base=10.)\n",
    "\n",
    "metre, second"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Unit(\"m\"), Unit(\"s\"))"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 2
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Creating Compound Units\n",
    "\n",
    "Next, we create a compound unit, such as volt(metre ^ 2 * kilogram / (second ^ 3 * ampere)):"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-04T15:09:52.273904Z",
     "start_time": "2026-03-04T15:09:52.240903900Z"
    }
   },
   "cell_type": "code",
   "source": [
    "volt = u.Unit.create(u.get_or_create_dimension(m=2, kg=1, s=-3, A=-1), \"volt\", \"V\")\n",
    "\n",
    "volt"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Unit(\"V\")"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 3
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "In this example, we define the dimensions for the compound unit and create a new unit named \"volt\" with the specified dimensions."
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Creating Scaled Units\n",
    "\n",
    "Finally, we create a scaled version of a basic unit, such as kilometers (kilometre):"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-04T15:09:52.362997Z",
     "start_time": "2026-03-04T15:09:52.276233200Z"
    }
   },
   "cell_type": "code",
   "source": [
    "kilometre = u.Unit.create_scaled_unit(metre, \"k\")\n",
    "\n",
    "kilometre"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Unit(\"km\")"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 4
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-04T15:09:52.392418500Z",
     "start_time": "2026-03-04T15:09:52.366407900Z"
    }
   },
   "cell_type": "code",
   "source": "1 * kilometre / (1 * metre)",
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1000.0"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 5
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, `create_scaled_unit` creates a new unit named \"kilometre\" by scaling the base unit \"metre\" with a scale factor of \"k\" (kilo).\n",
    "\n",
    "The scale factor determines the prefix used for the unit, allowing for easy conversion between different scales of the same unit."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "brainpy-dev",
   "language": "python",
   "name": "python3"
  },
  "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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}