Add benchmark documentation (#2763)

add benchmark docs

Signed-off-by: Asish Kumar <[email protected]>

docs/contributing/tools/benchmark.ipynb

@@ -0,0 +1,124 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Benchmarking Information\n",
+    "\n",
+    "A benchmark is a comparison of the performance of code along commit history. It is a way to measure the performance of the code and to ensure that the code is not getting slower. In this notebook, we will be understanding the best ways to write benchmarks and how to run them. Throughout the notebook, we will be using the `asv` package for benchmarking. \n",
+    "\n",
+    "### Setting up asv\n",
+    "\n",
+    "Prior to installing asv, you need to set up a conda environment and install conda-build. You can do this by running the following commands:\n",
+    "\n",
+    "```\n",
+    "conda activate base\n",
+    "conda install conda-build\n",
+    "```\n",
+    "\n",
+    "After running the above commands, you can install asv by running the following command:\n",
+    "\n",
+    "```\n",
+    "pip install asv\n",
+    "```\n",
+    "\n",
+    "### Running the benchmarks\n",
+    "\n",
+    "To run the benchmarks, you can run the following command:\n",
+    "\n",
+    "```\n",
+    "asv run\n",
+    "```\n",
+    "\n",
+    "This command will run for last 2 commits. asv can also run for a specific commit or a range of commits which can be done by running the following commands:\n",
+    "\n",
+    "- `asv run <tag/branch>^!` runs for the last commit for the given tag/branch.\n",
+    "- `asv run master..mybranch` runs for the commits between master and mybranch.\n",
+    "- `asv run HASHFILE:hashestobenchmark.txt` runs for the commits in the file hashestobenchmark.txt where each line is a commit hash.\n",
+    "\n",
+    "Some of the important commands of asv are:\n",
+    "\n",
+    "- `--quick` quickly runs the benchmarks.\n",
+    "- `-e` shows errors in the benchmark.\n",
+    "- `--bench <file>` runs the benchmarks only for the given file. The extension of the file should not be included.\n",
+    "- `--skip-existing-successful` skips the benchmarks that have already been run successfully.\n",
+    "\n",
+    "Example: \n",
+    "`asv run master^! --quick -e --bench run_tardis`\n",
+    "\n",
+    "To view the result in a website, you can run the following command:\n",
+    "\n",
+    "```\n",
+    "asv publish\n",
+    "asv preview\n",
+    "```\n",
+    "\n",
+    "In order to run the tardis benchmarks, you need to change `atomic_data_fname` function in [benchmark_base.py](https://github.com/tardis-sn/tardis/blob/master/benchmarks/benchmark_base.py) file and download the atomic_data. Here are the changes:\n",
+    "\n",
+    "```python\n",
+    "    def atomic_data_fname(self):\n",
+    "        from tardis.io.configuration.config_internal import get_data_dir\n",
+    "\n",
+    "        data_dir = get_data_dir()\n",
+    "        atomic_data_fname = (\n",
+    "            f\"{data_dir}/kurucz_cd23_chianti_H_He.h5\"\n",
+    "        )\n",
+    "\n",
+    "        if not Path(atomic_data_fname).exists():\n",
+    "            atom_data_missing_str = (\n",
+    "                f\"{atomic_data_fname} atomic datafiles \"\n",
+    "                f\"does not seem to exist\"\n",
+    "            )\n",
+    "            raise Exception(atom_data_missing_str)\n",
+    "\n",
+    "        return atomic_data_fname\n",
+    "```\n",
+    "\n",
+    "\n",
+    "After this you need to download the atomic data file which can be done by running the following file:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from tardis.io.atom_data.util import download_atom_data\n",
+    "\n",
+    "download_atom_data('kurucz_cd23_chianti_H_He')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Writing Benchmarks\n",
+    "\n",
+    "TARDIS has adopted a class way of writing benchmarks. You can browse the benchmarks directory in the tardis repository to understand how the benchmarks are written. Here are some of the important points to keep in mind while writing benchmarks:\n",
+    "\n",
+    "- The naming of file must specify the directory along with the file. Mentioning the tardis directory is not required. \n",
+    "- The class name should be the same as the file name with `Benchmark` prepended to it.\n",
+    "- The class should inherit from `BenchmarkBase` if required.\n",
+    "- Every class should have a `setup` function which is used to set up the environment for the benchmark. This is done so that we can avoid potential noise in the benchmarks. For example, if a function needs a parameter which needs some time to be set up, we can write it up in the `setup` function.\n",
+    "- Common functions which can be inherited in multiple files in the future should be written in benchmark_base.py file. \n",
+    "- The benchmark should be written in a function with the name `time_<function_name>`.\n",
+    "- Based on the local run, setting up the [repeat](https://asv.readthedocs.io/en/stable/tuning.html) might reduce time to run the benchmarks in the github actions. For example, if a benchmark takes less time to run then it might be a good idea to run that function for say 4 times but if a benchmark takes more time to run then it might be a good idea to run that function for 2 times."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "tardis",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/contributing/tools/index.rst

@@ -9,3 +9,4 @@ The following pages contain information about coding concepts used in the develo
     hdf_writer
     isotope_pd_subclass
     profiling/index
+    benchmark