Merge branch 'main' into main

docs/conf.py

@@ -46,7 +46,7 @@ templates_path = ["_templates"]
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".pytest_cache"]
 
 
 # -- Options for HTML output -------------------------------------------------

docs/learning/02 Packaging It Up.ipynb

@@ -44,8 +44,8 @@
     "│       └── #The Jupyer notebooks that form the main body of this project\n",
     "│\n",
     "├── pyproject.toml # Machine readable information about the MCFF package\n",
-    "├── readthedocs.yaml # Tells readthedocs.com how to build the documentation\n",
-    "├── requirements.txt # What packages MCFF requires\n",
+    "├── readthedocs.yml # Tells readthedocs.com how to build the documentation\n",
+    "├── environment.yml # A specification for building a conda environment including all the dependencies\n",
     "├── setup.cfg # Machine readable information about the MCFF package\n",
     "├── src\n",
     "│   └── MCFF # The actual code!\n",
@@ -56,7 +56,7 @@
     "It's looks pretty intimidating! But let's quickly go through it, at the top level of most projects you'll find on Github and elsewhere you'll find files to do with the project as a whole:\n",
     "- `README.md` - An intro to the project\n",
     "- `LICENSE` - The software license that governs this project, there are a few standard ones people use.\n",
-    "- `requirements.txt` or `environment.yaml` (or both) this list what python packages the project needs in a standard format\n",
+    "- `environment.yaml` (or both) this list what python packages the project needs in a standard format\n",
     "- `CITATION.cff` This is the new standard way to describe how a work should be cited, v useful for academic software.\n",
     "\n",
     "Then below that you will usually have directories breaking the project up into main categories, here I have `code/` and `learning/` but it would be more typical to have what is in `code` at the top level.\n",
@@ -73,7 +73,7 @@
     "from MCFF import mcmc #once we've written this that is!\n",
     "```\n",
     "\n",
-    "`pyproject.toml` and `setup.cfg` are the current way to describe the metadat about a python package like how it should be installed and who the author is etc, but typically you just copy the standard layouts and build from there. The empty `__init__.py` file flags that this folder is a python module.\n",
+    "`pyproject.toml` and `setup.cfg` are the current way to describe the metadata about a python package like how it should be installed and who the author is etc, but typically you just copy the standard layouts and build from there. The empty `__init__.py` file flags that this folder is a python module.\n",
     "\n",
     "pyproject.toml:\n",
     "```\n",
@@ -94,28 +94,42 @@
     "\n",
     "setup.cfg\n",
     "```\n",
-    "[metadata]\n",
-    "name = MCFF\n",
     "version = 0.0.1\n",
     "author = Tom Hodson\n",
     "author_email = tch14@ic.ac.uk\n",
     "description = A small example package\n",
     "long_description = file: README.md\n",
     "long_description_content_type = text/markdown\n",
-    "url = None\n",
+    "url = https://github.com/TomHodson/MCMC_for_fun_and_profit\n",
     "classifiers =\n",
     "    Programming Language :: Python :: 3\n",
-    "    License :: OSI Approved :: MIT License\n",
+    "    License :: OSI Approved :: The 3-Clause BSD License\n",
     "    Operating System :: OS Independent\n",
     "\n",
     "[options]\n",
-    "package_dir = \n",
+    "package_dir =\n",
     "    = src\n",
     "packages = find:\n",
     "python_requires = >=3.6\n",
+    "install_requires =\n",
+    "  numpy == 1.21      \n",
+    "  scipy == 1.7\n",
+    "  matplotlib == 3.5\n",
+    "  numba == 0.55\n",
+    "  ipykernel == 6.9   # Allows this conda environment to show up automatically in Jupyter Lab\n",
+    "  watermark == 2.3    # Generates a summary of package version for use inside Jupyter Notebooks\n",
     "\n",
     "[options.packages.find]\n",
     "where = src\n",
+    "dev = \n",
+    "  pytest == 7.1      # Testing\n",
+    "  pytest-cov == 3.0  # For Coverage testing\n",
+    "  hypothesis == 6.29  # Property based testing\n",
+    "  pre-commit == 2.20\n",
+    "  \n",
+    "docs = \n",
+    "  sphinx == 5.0       # For building the documentation\n",
+    "  myst-nb == 0.16 \n",
     "```\n",
     "Phew, that was a lot. Python packaging has been evolving a lot over the years and the consequence is there is a lot of out of date advice and there are many other ways to do this. You're best bet to figure out what the current best practice is is to consult offical sources like python.org"
    ]
@@ -127,9 +141,9 @@
    "source": [
     "Once all that is setup, cd to the `code/` folder and install the module using:\n",
     "```bash\n",
-    "pip install --editable .\n",
+    "pip install --editable \".[dev,docs]\"\n",
     "```\n",
-    "The dot means we should install MCFF from the current directory and `--editable` means to do it as an editable package so that we can edit the files in MCFF and not have to reinstall. This is really useful for development. "
+    "The dot means we should install MCFF from the current directory and `--editable` means to do it as an editable package so that we can edit the files in MCFF and not have to reinstall. This is really useful for development. `[dev,docs]` means we also want to install the packages that are needed to do development of this repository and to build the documentation, boths those things will become relevant later!"
    ]
   },
   {
@@ -141,13 +155,49 @@
     "\n",
     "<img style=\"max-width:700px;margin:auto;\" src = \"https://imgs.xkcd.com/comics/python_environment.png\" alt = \"An xkcd comic with a diagram of p values, saying that small ones are highly significant and giving humorous excuses for why larger ones are still intersting\">"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "c4752c3c-5550-4052-bcef-0683460cd010",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Author: Thomas Hodson\n",
+      "\n",
+      "Github username: T_Hodson\n",
+      "\n",
+      "Last updated: Mon Jul 18 2022\n",
+      "\n",
+      "Python implementation: CPython\n",
+      "Python version       : 3.9.12\n",
+      "IPython version      : 8.4.0\n",
+      "\n",
+      "Git hash: 03657e08835fdf23a808f59baa6c6a9ad684ee55\n",
+      "\n",
+      "Git repo: https://github.com/ImperialCollegeLondon/ReCoDE_MCMCFF.git\n",
+      "\n",
+      "Git branch: main\n",
+      "\n",
+      "Watermark: 2.3.1\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "%load_ext watermark\n",
+    "%watermark -n -u -v -iv -w -g -r -b -a \"Thomas Hodson\" -gu \"T_Hodson\""
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python [conda env:jupyter3.9] *",
+   "display_name": "Python [conda env:recode]",
    "language": "python",
-   "name": "conda-env-jupyter3.9-py"
+   "name": "conda-env-recode-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -159,7 +209,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.9.12"
   }
  },
  "nbformat": 4,

docs/learning/05 Adding Functionality.ipynb

@@ -127,7 +127,7 @@
     {
      "data": {
       "text/plain": [
-       "(<generator object my_range at 0x7fe3b2359660>, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9])"
+       "(<generator object my_range at 0x7fcaff25da50>, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9])"
       ]
      },
      "execution_count": 2,
@@ -158,7 +158,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 3,
    "id": "f73d6335-6514-45b1-9128-d72122d8b0b7",
    "metadata": {},
    "outputs": [
@@ -166,9 +166,9 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "18.4 ms ± 364 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)\n",
-      "9.51 ms ± 309 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)\n",
-      "0x slowdown!\n"
+      "18.6 ms ± 645 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)\n",
+      "13.3 ms ± 1.74 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n",
+      "1x slowdown!\n"
      ]
     }
    ],
@@ -217,6 +217,46 @@
     "\n",
     "We take a factor of two slowdown but that doesn't seem so much to pay for the fact we can now sample the state at every single step rather than just the last."
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "b4e3c207-bc11-483a-aaf6-2daebb3194d8",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Author: Thomas Hodson\n",
+      "\n",
+      "Github username: T_Hodson\n",
+      "\n",
+      "Last updated: Mon Jul 18 2022\n",
+      "\n",
+      "Python implementation: CPython\n",
+      "Python version       : 3.9.12\n",
+      "IPython version      : 8.4.0\n",
+      "\n",
+      "Git hash: 03657e08835fdf23a808f59baa6c6a9ad684ee55\n",
+      "\n",
+      "Git repo: https://github.com/ImperialCollegeLondon/ReCoDE_MCMCFF.git\n",
+      "\n",
+      "Git branch: main\n",
+      "\n",
+      "json      : 2.0.9\n",
+      "numpy     : 1.21.5\n",
+      "matplotlib: 3.5.1\n",
+      "\n",
+      "Watermark: 2.3.1\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "%load_ext watermark\n",
+    "%watermark -n -u -v -iv -w -g -r -b -a \"Thomas Hodson\" -gu \"T_Hodson\""
+   ]
   }
  ],
  "metadata": {

environment.yml

@@ -6,15 +6,28 @@ channels:
 
 dependencies:
   - python=3.9
-  - pytest=7.1
-  - pytest-cov=3.0
-  - ipykernel=6.9
+
+  # Core packages
   - numpy=1.21
   - scipy=1.7
   - matplotlib=3.5
   - numba=0.55
-  - pre-commit=2.20
-  - hypothesis=6.29
+  - ipykernel=6.9   # Allows this conda environment to show up automatically in Jupyter Lab
+  - watermark=2.3    # Generates a summary of package version for use inside Jupyter Notebooks
+
+  # Testing
+  - pytest=7.1      # Testing
+  - pytest-cov=3.0  # For Coverage testing
+  - hypothesis=6.29  # Property based testing
+
+  # Development
+  - pre-commit=2.20  # For running black and other tools before commits
+
+  # Documentation
+  - sphinx=5.0       # For building the documentation
+  - myst-nb=0.16     # Allows sphinx to include Jupyter Notebooks
+
+  # Installing MCFF itself
   - pip=21.2
   - pip:
       - --editable . #install MCFF from the local repository using pip and do it in editable mode

readthedocs.yaml

@@ -19,12 +19,9 @@ sphinx:
 # formats:
 #    - pdf
 
-# Optionally declare the Python requirements required to build your docs
 python:
   install:
     - method: pip
       path: .
       extra_requirements:
-       - .
         - docs
-       - dev

setup.cfg

@@ -18,22 +18,24 @@ package_dir =
 packages = find:
 python_requires = >=3.6
 install_requires =
-    numpy
-    scipy
-    matplotlib
-    numba
+    numpy == 1.21
+    scipy == 1.7
+    matplotlib == 3.5
+    numba == 0.55
+    ipykernel == 6.9  # Allows this conda environment to show up automatically in Jupyter Lab
+    watermark == 2.3  # Generates a summary of package version for use inside Jupyter Notebooks
 
 [options.extras_require]
 dev =
-    pytest == 7.1
-    pytest-cov == 3.0
+    pytest == 7.1       # Testing
+    pytest-cov == 3.0   # For Coverage testing
+    hypothesis == 6.29  # Property based testing
     pre-commit == 2.20
-    hypothesis == 6.29
     jupyterlab == 3.4.3
 docs =
     ipykernel == 6.9.0
-    sphinx >= 4.0.0
-    myst-nb
+    sphinx == 5.0.0
+    myst-nb == 0.16.0
 
 [options.packages.find]
 where = src