tutorials/Tutorial0.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9bfbf775-a013-4749-bbed-a5fd7fce4b01",
   "metadata": {},
   "source": [
    "# Tutorial 0: Intro material for LAT Workshop"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ee2df1f-d06a-4666-807f-8f436755675a",
   "metadata": {},
   "source": [
    "In this introductory tutorial, we will give a basic overview of a few Python topics that are essential to understanding and using codes developed within the LISA Analysis Tools environment. You will also get an initial understanding how the tutorials are structured. ,\n",
    "\n",
    "This module is meant to be completed before the workshop. It will also ensure installation is successful.\n",
    "\n",
    "* Tasks: throughout the tutorials, you will be given \"tasks.\" These will direct the tutorial approach and separate the tutorials into natural sections. \n",
    "* Questions: additional questions are given within larger tasks. These will sometimes involve coding, sometimes not. A lot of them are meant to be discussion questions for yourself or small groups.\n",
    "* Structure: Depending on the task at hand, we will provide a specific intruction, small amounts of code, and documentation that is helpful to complete the task. The user must do most or all of the actual coding in order to make these notebooks run successfully. **Note**: in many cases, tutorials within the specific code bases are also available that can you close to the right answer. Most instances, the user will have to navigate these tutorials to find helpful answers. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ff811102-edd2-4784-adee-b27bb4bda938",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "from lisatools.utils.constants import *\n",
    "from copy import deepcopy  # can be useful\n",
    "from lisatools.utils.constants import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce939155-a34a-4c93-8daa-13b720d653bd",
   "metadata": {},
   "source": [
    "## Task 1: build and initialize a class object. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4c6161d-10c7-4591-8445-22f6619635de",
   "metadata": {},
   "source": [
    "Classes are essential objects in the construction of LISA Analysis Tools and its associated codes. Understanding and using classes will maximize your understanding and capabilities with LISA Analysis Tools. \n",
    "\n",
    "\n",
    "Build a class object that has two methods: `__init__` and `get_wave`. \n",
    "\n",
    "In `__init__`, store a frequency, amplitude, and initial phase.\n",
    "\n",
    "In `get_wave`, enter a time array as an argument. Then use the frequency, amplitude, and initial phase stored in `self` and the time array to return a sinusoidal function result to the user.\n",
    "\n",
    "Helpful documentation:\n",
    "* [Python class objects](https://docs.python.org/3/tutorial/classes.html#class-objects)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb2d8e0f-a60d-4d33-9b14-d625ce4885bc",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "76b168e0-aed3-4024-be34-fba313ec001f",
   "metadata": {},
   "source": [
    "Now, instantiate the class by providing the necessary arguments. Build a numpy array for the time array and test your class output. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1db1c1b0-6633-4d12-988d-3a26aa8cde7f",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "3f196f24-0ddb-4533-aab8-dccb3eadc731",
   "metadata": {},
   "source": [
    "## Task 2: `*args` and `**kwargs`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56948754-0491-4cb5-8db2-575342623d33",
   "metadata": {},
   "source": [
    "Another topic that is essential to using `lisatools`, is the usage of `*args` and `**kwargs`. These are ways to have flexible passage of Arguments (`*args`) and Keyword Arguments (`**kwargs`). Here, we will experiment with a few ways this works.\n",
    "\n",
    "Useful documentation:\n",
    "* [examples](https://www.geeksforgeeks.org/args-kwargs-python/)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d7258fe-75cd-44d5-b763-b0627a02b76e",
   "metadata": {},
   "source": [
    "We are effectively going to copy those examples. Start by designing a function that takes a flexible number of arguments and prints them out. The function signature will be `func(*args)`. In this case, args will be an iterable, so you can iterate through the arguments with a for loop. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b3a6a327-6d5a-41df-8cf7-0c9a55d7babf",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "37888532-076e-40df-a157-df71d82a90e2",
   "metadata": {},
   "source": [
    "Add a few arguments into the function signature before `*args` and observe how that changes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b1fbcab-92da-4e76-872d-b8f77a971152",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "3b3b7426-70ff-4f8d-94cf-bc1de22eb8cb",
   "metadata": {},
   "source": [
    "Now do the same things for `func(**kwargs)`. This will produce a dictionary, so print that in a for loop. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e7ffdaf7-434d-4e23-b1c3-9d71a708a971",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "30223bd8-8392-439d-9b00-94ac8dd97248",
   "metadata": {},
   "source": [
    "`**kwargs` can be very useful when making functions flexible because you can have it field the specific `kwargs` needed and store any others in the `**kwargs` dictionary. Add keyword arguments into the function signature and see how it changes the printing results. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1912634e-7c95-4eae-ac5c-debd7e871a40",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "1b7e2a3d-0cd2-4854-84d2-e3ce8ac571f2",
   "metadata": {},
   "source": [
    "You can also perform effectively the inverted operations. You can enter an iterable into a function call with `*args` and it will spread out your iterable to the args in the function signature. Make a function call with 2 arguments only. Then, create a list that has 2 entries. Enter it into the function call with `*list` and print the output in the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2ad428f2-91d2-4396-a32e-81381c20e11e",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "7bce1bf7-56ca-460a-84db-602001cbadc8",
   "metadata": {},
   "source": [
    "Same type of thing works for kwargs with any input dictionary called like `**dict`. Do the same thing as above for `kwargs`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4221d323-36eb-4022-be06-8ea2ba7d4c56",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "3257525c-f2df-4f18-8677-4005e06fe214",
   "metadata": {},
   "source": [
    "## Task 3: Class inheritance"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d06705f-3842-4094-ac26-5783c38871ca",
   "metadata": {},
   "source": [
    "Class inheritance gets a bit more complex. It is not essential to know this for the workshop specifically, but it can really help you understand LISA Analysis Tools and other abstracted code libraries designed for future development and maintenance. \n",
    "\n",
    "Copy your class from above. Add a keyword argument to the `__init__` function that takes a vertical bias from zero for the sinusoidal function (a float value). Store it to `self`. Inside of `get_wave` add this value onto the end of the sinusoidal return value. \n",
    "\n",
    "**Note**: make sure any value entered for $A$ is not too many orders of magnitude away from this added bias factor. Otherwise, you may have issues with machine precision.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fdc5aca7-4296-4fb6-bd95-f440cd3252e6",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "e9371cfd-e72a-437f-8618-17459ba77cb5",
   "metadata": {},
   "source": [
    "\n",
    "Now, we will create a class that will inherit our class above and adjust its output on the way through the computation. Add two methods to this class:\n",
    "\n",
    "In `__init__`, have it take in a single argument representing a multiplicative factor (a float value). Store it in `self`. Then, in the function signature, make sure it is flexible by adding an adjustable number of arguments and keyword arguments. Pass these arguments and keyword arguments to the parent class with this type of line: \n",
    "```\n",
    "super(ChildClass, self).__init__(*args, **kwargs)\n",
    "```\n",
    "\n",
    "`__call__` methods on functions allow the user to initialize a class and pass it as a function or `callable`. In other words: `c = Class()` -> `y = c(x)`, rather than having to name a specific method like `get_wave`. \n",
    "\n",
    "Useful Documentation:\n",
    "* [`__call__`](https://www.geeksforgeeks.org/__call__-in-python/) (this is a clickable link)\n",
    "\n",
    "In `__call__`, take one argument, the time array (numpy array), and put it into the `get_wave` method. Take the output from `get_wave` and multiply by the stored multiplicative factor. Return that to the user. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12d29a54-4a9a-4df8-bb29-df68a81d5a0b",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "15a81db2-b8cf-46a5-ad4d-c156a832c3d5",
   "metadata": {},
   "source": [
    "Now initialize and test your class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1d7c142e-b051-4646-a119-29e1a8855038",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "2b35df0b-3c1a-4931-9c3d-440b18156106",
   "metadata": {},
   "source": [
    "## A `pdb` manifesto. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e7a0573-4e4a-47f0-b627-00bc51273b9d",
   "metadata": {},
   "source": [
    "(Michael's opinion)\n",
    "\n",
    "The python debugger ([pdb](https://docs.python.org/3/library/pdb.html)) is an unbelievably helpful tool. For me, it is up there with `Numpy` and `Matplotlib` in terms of how useful it has been for me. It has shaved so much time from the development process, it is honestly incalculable. `pdb` allows you to use most one-line `ipython` commands stopped anywhere in your code. In other words, you can stop your Python code and run functions, print any stored variables, store new variables, plot things, etc.\n",
    "\n",
    "I notice that a lot of people do not know about this intrinsic python library or do not use it. \n",
    "\n",
    "\n",
    "The start of my development code file is usually:\n",
    "```\n",
    "import numpy as np\n",
    "\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "\n",
    "    # debugger at the end to catch and analyze any output. \n",
    "    breakpoint()  \n",
    "```\n",
    "\n",
    "I often do, what I am now calling as of writting this, \"proactive debugging.\" Proactive debugging means that the code is run until it reaches a point where I am about to develop. I will then develop line by line in the debugger, testing each line as I go. Once it works, it gets pasted in the code. This is a little tedious to get used to and does not work sometimes (only sometimes), but I highly recommend trying it. It is a very efficient way to develop code in my opinion.  \n",
    "\n",
    "We are not going to practice it here because it really does not work as well in a notebook. It is more useful in the terminal. In the terminal, it is an almost ipython-like experience stopping anywhere in the code you place a `breakpoint`. You can use it to stop inside functions you design, or inside python codes of others. In other words, you can open a python code that is in your `$PATH` and place a breakpoint inside of it. You can then run your code that calls this package. It will stop at your breakpoint. You can step through and print anything you need. This has really helped me in the past to learn better coding techniques and to understanding complex codes others have designed. \n",
    "\n",
    "Here is the documentation:\n",
    "* [pdb](https://docs.python.org/3/library/pdb.html)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d708bb50-25c7-44e2-88a0-30da3cdb0716",
   "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.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}