installation instructions in README; minimal example

Author: alexander-mead

README.md

@@ -1,15 +1,54 @@
-## HMcode
+# HMcode
 
-To whom it may concern,
-
-I coded this `Python` version of `HMcode-2020` ([Mead et al. 2021](https://arxiv.org/abs/2009.01858)) up quite quickly before leaving academia in February 2023. It is written in pure `Python` and doesn't use any of the original Fortran code whatsoever. There is something amazing/dispiriting about coding something up in 3 days that previously took 5 years. A tragic last hoorah! At least I switched to `Python` eventually...
+A pure-`Python` implementation of the `HMcode-2020` method ([Mead et al. 2021](https://arxiv.org/abs/2009.01858)) for computing accurate non-linear matter power spectra across a wide range of cosmological parameters for $w(a)$-CDM models including curvature and massive neutrinos.
 
-You might also be interested in [`pyhalomodel`](https://pypi.org/project/pyhalomodel/), upon which this code depends, which implements a vanilla halo-model calculation for any desired large-scale-structure tracer. Alternatively, and very confusingly, you might be interested in this [`pyhmcode`](https://pypi.org/project/pyhmcode/), which provides a wrapper around the original `Fortran` `HMcode` implementation.
+## Installation
 
-To install, clone the repository, `cd` into the directory, and then
+Either
+```
+pip install hmcode
+```
+or, if you want to edit the code, use the demo notebook, or run the tests or consistency checks, then clone the repository, `cd` into the directory, and then
 ```
 poetry install
 ```
+to create a virtual environment with everything you need to get going.
+
+## Dependencies
+
+- `numpy`
+- `scipy`
+- `camb`
+- `pyhalomodel`
+
+## Use
+
+```
+import numpy as np
+import camb
+import hmcode
+
+# Ranges
+k = np.logspace(-3, 1, 100) # Wavenumbers [h/Mpc]
+zs = [3., 2., 1., 0.5, 0.]  # Redshifts
+
+# Run CAMB
+parameters = camb.CAMBparams(WantCls=False)
+parameters.set_cosmology(H0=70.)
+parameters.set_matter_power(redshifts=zs, kmax=100.) # kmax should be much larger than the wavenumber of interest
+results = camb.get_results(parameters)
+
+# HMcode
+Pk = hmcode.power(k, zs, results)
+```
+
+## Note
+
+To whom it may concern,
+
+I coded this `Python` version of `HMcode-2020` ([Mead et al. 2021](https://arxiv.org/abs/2009.01858)) up quite quickly before leaving academia in February 2023. It is written in pure `Python` and doesn't use any of the original Fortran code whatsoever. There is something amazing/dispiriting about coding something up in 3 days that previously took 5 years. A tragic last hoorah! At least I switched to `Python` eventually...
+
+You might also be interested in [`pyhalomodel`](https://pypi.org/project/pyhalomodel/), upon which this code depends, which implements a vanilla halo-model calculation for any desired large-scale-structure tracer. Alternatively, and very confusingly, you might be interested in this [`pyhmcode`](https://pypi.org/project/pyhmcode/), which provides a wrapper around the original `Fortran` `HMcode` implementation.
 
 I compared it against the `CAMB-HMcode` version for 100 random sets of cosmological parameters ($k < 10 h\mathrm{Mpc}^{-1}$; $z < 3$). The level of agreement between the two codes is as follows:
 - LCDM: Mean error: 0.10%; Std error: 0.03%; Worst error; 0.21%

notebooks/minimal.ipynb

@@ -0,0 +1,75 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Standard imports\n",
+    "import numpy as np\n",
+    "\n",
+    "# Third-party imports\n",
+    "import camb\n",
+    "import hmcode\n",
+    "\n",
+    "# Ranges\n",
+    "k = np.logspace(-3, 1, 100) # Wavenumbers [h/Mpc]\n",
+    "zs = [3., 2., 1., 0.5, 0.]  # Redshifts\n",
+    "\n",
+    "# Run CAMB\n",
+    "parameters = camb.CAMBparams(WantCls=False)\n",
+    "parameters.set_cosmology(H0=70.)\n",
+    "parameters.set_matter_power(redshifts=zs, kmax=100.) # kmax should be much larger than the wavenumber of interest\n",
+    "results = camb.get_results(parameters)\n",
+    "\n",
+    "# HMcode\n",
+    "Pk = hmcode.power(k, zs, results)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "# Plot\n",
+    "for iz, z in enumerate(zs):\n",
+    "    plt.loglog(k, Pk[iz, :], label='z = {:1.1f}'.format(z))\n",
+    "plt.xlabel('$k$ $[h \\mathrm{Mpc}^{-1}]$')\n",
+    "plt.ylabel('$P(k)$ $[(h^{-1}\\mathrm{Mpc})^3]$')\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "hmcode-S0Z6NeuA-py3.10",
+   "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.9"
+  },
+  "orig_nbformat": 4,
+  "vscode": {
+   "interpreter": {
+    "hash": "e82eed08d8d58f92fc7a23e50eeb23ca4d9777479ef0aea969fd18c18280722f"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}