Introduction to Handcalcs.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "065377c0-2b6f-40f7-9e1a-81c8f8ef4ce8",
   "metadata": {},
   "outputs": [],
   "source": [
    "import handcalcs.render"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a04e89da-7c5c-408a-90a9-44a4dbcd128d",
   "metadata": {},
   "source": [
    "# 📖🖊 Engineering Calculations in Jupyter"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7b9dc175-0e95-47b2-a7f2-099241d86348",
   "metadata": {},
   "source": [
    "Python and Jupyterlab can be used together for performing engineering calculations.\n",
    "\n",
    "e.g.\n",
    "```python\n",
    "# Calculate properties for a rectangular section\n",
    "d = 450\n",
    "t = 35\n",
    "A =d*t\n",
    "S_x = (t*d**2)/ 6\n",
    "I_x = (t*d**3)/12\n",
    "I_y = (d*t**3)/12\n",
    "print(f\"S_x: {S_x}\\nI_x: {I_x}\\nI_y: {I_y}\")\n",
    "```\n",
    "\n",
    "However, this code just performs the calculation and prints the output which does not make for good engineering notes. It would be good if we could have nicer looking notes!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "270713bb-0841-443f-aa00-6252b3dcb86b",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "407d5cfa-fe53-479e-88e8-1666948f1483",
   "metadata": {},
   "source": [
    "# Introducing: handcalcs\n",
    "\n",
    "[Read the handcalcs documentation](https://github.com/connorferster/handcalcs)\n",
    "\n",
    "**Typical import**\n",
    "```python\n",
    "import handcalcs.render\n",
    "```\n",
    "\n",
    "After we have done `import handcalcs.render`, we have access to the `%%render` \"cell magic\". \n",
    "\n",
    "A cell magic is a special _Jupyter-only_ command that performs some \"magic\" ability to the code in your cell before or after running it. \n",
    "\n",
    "A normal cell:\n",
    "```python\n",
    "a = 4\n",
    "b = 5.2\n",
    "c = 2*a + b\n",
    "```\n",
    "\n",
    "Lets add the `%%render` cell magic to our previous cell (and ditch the `print()` statement):\n",
    "\n",
    "```python\n",
    "%%render\n",
    "a = 4\n",
    "b = 5.2\n",
    "c = 2*a + b\n",
    "```\n",
    "\n",
    "Copy-paste the code above into the cell below to see what happens."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6f8b6ae8-dc14-4874-9bf1-ad5820285fcf",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "0c66c2d1-fe79-4693-a353-c38569c2c540",
   "metadata": {
    "tags": []
   },
   "source": [
    "# handcalcs: what it's all about\n",
    "\n",
    "`handcalcs` is about rendering python arithmetic expressions similar to how you would write them out by hand:\n",
    "1. Display the symbolic formula\n",
    "2. Followed by the numeric substitutions\n",
    "3. Followed by the result\n",
    "\n",
    "While there are other excellent software programs for doing similar stuff (SMath Studio, MathCAD), handcalcs is different in three ways:\n",
    "\n",
    "1. It shows the numeric substitution\n",
    "2. You don't have to click and drag your formulas around on the page: it's just laid out nicely\n",
    "3. It's free and open-source"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "804d9320-d93e-4e06-b858-4c4ae056cb1f",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "a88637c5-83c8-4bf7-9115-255a72453323",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Use handcalcs in cells\n",
    "\n",
    "## handcalcs cell commands\n",
    "\n",
    "When using `%%render` there are some additional commands you can put afterwards that alters the behaviour of how handcalcs displays your calculation:\n",
    "\n",
    "```python\n",
    "%%render [options] [precision_of_display]\n",
    "```\n",
    "\n",
    "#### Options\n",
    "* `params` - Does not render the formula or the subsitution. Just displays the variable (symbol) and the value (result) within a three column layout. Useful for displaying input parameters in a condensed fashion or any value for which the calculation is trivial.\n",
    "* `symbolic` - Does not render the numeric substition or the result. Renders the variable (symbol) and the formula.\n",
    "* `short` - Some formulas are really long and do not fit on one line. handcalcs tries to guess if your equation is too long and, if so, it will break it up over three lines. Sometimes it guesses wrong. If you want your formula to displayed on one line _as though it were a \"short\" equation_ then use `short`.\n",
    "* `long` - Similar to above. If your equation is quite long but handcalcs guesses that it is short, then use `long` to display it over three lines _as though it were a \"long\" equation_.\n",
    "\n",
    "\n",
    "Try using each of the different cell commands on the following cells to see how they work:\n",
    "\n",
    "```python\n",
    "from math import sqrt\n",
    "```\n",
    "\n",
    "**Cell 1:**\n",
    "```python\n",
    "%%render long 2\n",
    "a = 3.238728302\n",
    "b = 4.38\n",
    "c = -15.0\n",
    "\n",
    "x_pos = (-b + sqrt(b**2 - 4 * a * c)) / (2*a)\n",
    "x_neg = (-b - sqrt(b**2 - 4 * a * c)) / (2*a)\n",
    "Delta = (-b + sqrt(b**2 - 4 * a * c)) / (2*a) - (-b - sqrt(b**2 - 4 * a * c)) / (2*a)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2eaecd96-bf65-4620-87a8-2a1d579a7a81",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "f7756102-b24a-4525-83f1-b68a2f67ef9c",
   "metadata": {
    "tags": []
   },
   "source": [
    "**Cell 2:**\n",
    "```python\n",
    "%%render params 2\n",
    "phi = 0.65\n",
    "f_prime_c = 35 # in MPa\n",
    "beta = 0.18\n",
    "b_w_beam = 300 # in mm\n",
    "d_v_beam = 520 # in mm\n",
    "V_c_beam = phi * beta * sqrt(f_prime_c) * b_w_beam * d_v_beam # Cl. 11.3.4\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "641ece6a-6540-467e-be55-9f9438ec4fef",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "a1db7661-120c-4d97-b8a5-dc5acf8ab3bb",
   "metadata": {},
   "source": [
    "## A short summary of handcalcs features\n",
    "\n",
    "* Use `_` in your variable names to create sub-scripts (and sub-sub-scripts, etc.)\n",
    "* Use Greek letter names for Greek symbols. e.g. `Delta` for a capital delta, `delta` for little delta.\n",
    "* You can use functions like `sin()` and `cos()` imported from the `math` module\n",
    "* Any function called `sqrt` will be rendered with a radical symbol\n",
    "* Comments are rendered in different contexts:\n",
    "    * If a comment is on a line by itself, it will not be rendered\n",
    "    * If a comment is on a line by itself and written with two `##` comment symbols, it will be rendered in the cell\n",
    "    * If a comment is after a line of calculation, it will be rendered in parentheses\n",
    "\n",
    "\n",
    "```python\n",
    "from math import sin, sqrt\n",
    "```\n",
    "\n",
    "```python\n",
    "%%render\n",
    "# A comment not rendered\n",
    "a_sub1_sub2 = 1\n",
    "## A comment that is rendered\n",
    "delta_2 = 3 \n",
    "c = sqrt((a_sub1_sub2 + delta_2)/delta_2) # A comment in parens\n",
    "```\n",
    "\n",
    "**A Known Bug (that needs fixing)**\n",
    "\n",
    "Always put spaces around your equal signs, e.g. `a = 32` instead of `a=32`. Sometimes it gets messed up if you don't."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aa54b569-91cb-46c8-817b-6097b7662569",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}