From bcee8af68fab9ac46e547bf65f653efa4ded8338 Mon Sep 17 00:00:00 2001 From: Francesco Innocenti Date: Wed, 12 Jun 2024 15:19:17 +0100 Subject: [PATCH] Add docs --- .github/workflows/build_docs.yml | 39 +++++++ docs/.htaccess | 1 + docs/FAQs.md | 0 docs/_overrides/partials/source.html | 20 ++++ docs/_static/custom_css.css | 162 +++++++++++++++++++++++++++ docs/_static/favicon.png | Bin 0 -> 5721 bytes docs/_static/mathjax.js | 19 ++++ docs/api/Energy functions.md | 5 + docs/api/Gradients.md | 7 ++ docs/api/Inference.md | 3 + docs/api/Initialisation.md | 5 + docs/index.md | 74 ++++++++++++ docs/requirements.txt | 15 +++ mkdocs.yml | 105 +++++++++++++++++ 14 files changed, 455 insertions(+) create mode 100644 .github/workflows/build_docs.yml create mode 100644 docs/.htaccess create mode 100644 docs/FAQs.md create mode 100644 docs/_overrides/partials/source.html create mode 100644 docs/_static/custom_css.css create mode 100644 docs/_static/favicon.png create mode 100644 docs/_static/mathjax.js create mode 100644 docs/api/Energy functions.md create mode 100644 docs/api/Gradients.md create mode 100644 docs/api/Inference.md create mode 100644 docs/api/Initialisation.md create mode 100644 docs/index.md create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 0000000..3f5116f --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,39 @@ +name: Build docs + +on: + push: + branches: + - main + +jobs: + build: + strategy: + matrix: + python-version: [ 3.11 ] + os: [ ubuntu-latest ] + runs-on: ${{ matrix.os }} + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install . + #python -m pip install -r docs/requirements.txt + + - name: Build docs + run: | + mkdocs build + mkdocs build + + - name: Upload docs + uses: actions/upload-artifact@v2 + with: + name: docs + path: site # where `mkdocs build` puts the built site \ No newline at end of file diff --git a/docs/.htaccess b/docs/.htaccess new file mode 100644 index 0000000..88c2d9c --- /dev/null +++ b/docs/.htaccess @@ -0,0 +1 @@ +ErrorDocument 404 /diffrax/404.html \ No newline at end of file diff --git a/docs/FAQs.md b/docs/FAQs.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/_overrides/partials/source.html b/docs/_overrides/partials/source.html new file mode 100644 index 0000000..10bba66 --- /dev/null +++ b/docs/_overrides/partials/source.html @@ -0,0 +1,20 @@ +{% import "partials/language.html" as lang with context %} + +
+ {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %} + {% include ".icons/" ~ icon ~ ".svg" %} +
+
+ {{ config.repo_name }} +
+ +{% if config.theme.twitter_url %} + +
+ {% include ".icons/fontawesome/brands/twitter.svg" %} +
+
+ {{ config.theme.twitter_name }} +
+ +{% endif %} \ No newline at end of file diff --git a/docs/_static/custom_css.css b/docs/_static/custom_css.css new file mode 100644 index 0000000..e9be9fc --- /dev/null +++ b/docs/_static/custom_css.css @@ -0,0 +1,162 @@ +/* Fix /page#foo going to the top of the viewport and being hidden by the navbar */ +html { + scroll-padding-top: 50px; +} + +/* Fit the Twitter handle alongside the GitHub one in the top right. */ + +div.md-header__source { + width: revert; + max-width: revert; +} + +a.md-source { + display: inline-block; +} + +.md-source__repository { + max-width: 100%; +} + +/* Emphasise sections of nav on left hand side */ + +nav.md-nav { + padding-left: 5px; +} + +nav.md-nav--secondary { + border-left: revert !important; +} + +.md-nav__title { + font-size: 0.9rem; +} + +.md-nav__item--section > .md-nav__link { + font-size: 0.9rem; +} + +/* Indent autogenerated documentation */ + +div.doc-contents { + padding-left: 25px; + border-left: 4px solid rgba(230, 230, 230); +} + +/* Increase visibility of splitters "---" */ + +[data-md-color-scheme="default"] .md-typeset hr { + border-bottom-color: rgb(0, 0, 0); + border-bottom-width: 1pt; +} + +[data-md-color-scheme="slate"] .md-typeset hr { + border-bottom-color: rgb(230, 230, 230); +} + +/* More space at the bottom of the page */ + +.md-main__inner { + margin-bottom: 1.5rem; +} + +/* Remove prev/next footer buttons */ + +.md-footer__inner { + display: none; +} + +/* Change font sizes */ + +html { + /* Decrease font size for overall webpage + Down from 137.5% which is the Material default */ + font-size: 110%; +} + +.md-typeset .admonition { + /* Increase font size in admonitions */ + font-size: 100% !important; +} + +.md-typeset details { + /* Increase font size in details */ + font-size: 100% !important; +} + +.md-typeset h1 { + font-size: 1.6rem; +} + +.md-typeset h2 { + font-size: 1.5rem; +} + +.md-typeset h3 { + font-size: 1.3rem; +} + +.md-typeset h4 { + font-size: 1.1rem; +} + +.md-typeset h5 { + font-size: 0.9rem; +} + +.md-typeset h6 { + font-size: 0.8rem; +} + +/* Bugfix: remove the superfluous parts generated when doing: + +??? Blah + + ::: library.something +*/ + +.md-typeset details .mkdocstrings > h4 { + display: none; +} + +.md-typeset details .mkdocstrings > h5 { + display: none; +} + +/* Change default colours for tags */ + +[data-md-color-scheme="default"] { + --md-typeset-a-color: rgb(0, 189, 164) !important; +} +[data-md-color-scheme="slate"] { + --md-typeset-a-color: rgb(0, 189, 164) !important; +} + +/* Highlight functions, classes etc. type signatures. Really helps to make clear where + one item ends and another begins. */ + +[data-md-color-scheme="default"] { + --doc-heading-color: #DDD; + --doc-heading-border-color: #CCC; + --doc-heading-color-alt: #F0F0F0; +} +[data-md-color-scheme="slate"] { + --doc-heading-color: rgb(25,25,33); + --doc-heading-border-color: rgb(25,25,33); + --doc-heading-color-alt: rgb(33,33,44); + --md-code-bg-color: rgb(38,38,50); +} + +h4.doc-heading { + /* NOT var(--md-code-bg-color) as that's not visually distinct from other code blocks.*/ + background-color: var(--doc-heading-color); + border: solid var(--doc-heading-border-color); + border-width: 1.5pt; + border-radius: 2pt; + padding: 0pt 5pt 2pt 5pt; +} +h5.doc-heading, h6.heading { + background-color: var(--doc-heading-color-alt); + border-radius: 2pt; + padding: 0pt 5pt 2pt 5pt; +} \ No newline at end of file diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..5e71b54ab1905db2b2059665f36ba2e489cc40e1 GIT binary patch literal 5721 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 literal 0 HcmV?d00001 diff --git a/docs/_static/mathjax.js b/docs/_static/mathjax.js new file mode 100644 index 0000000..0b00d2f --- /dev/null +++ b/docs/_static/mathjax.js @@ -0,0 +1,19 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.startup.output.clearCache() + MathJax.typesetClear() + MathJax.texReset() + MathJax.typesetPromise() +}) \ No newline at end of file diff --git a/docs/api/Energy functions.md b/docs/api/Energy functions.md new file mode 100644 index 0000000..24ac42f --- /dev/null +++ b/docs/api/Energy functions.md @@ -0,0 +1,5 @@ +# Energy functions + +::: jpc.pc_energy_fn + +::: jpc.hpc_energy_fn \ No newline at end of file diff --git a/docs/api/Gradients.md b/docs/api/Gradients.md new file mode 100644 index 0000000..8f4495a --- /dev/null +++ b/docs/api/Gradients.md @@ -0,0 +1,7 @@ +# Gradients + +::: jpc.compute_pc_param_grads + +::: jpc.compute_gen_param_grads + +::: jpc.compute_amort_param_grads \ No newline at end of file diff --git a/docs/api/Inference.md b/docs/api/Inference.md new file mode 100644 index 0000000..2f4ed30 --- /dev/null +++ b/docs/api/Inference.md @@ -0,0 +1,3 @@ +# Inference + +::: jpc.solve_pc_activities \ No newline at end of file diff --git a/docs/api/Initialisation.md b/docs/api/Initialisation.md new file mode 100644 index 0000000..3b86173 --- /dev/null +++ b/docs/api/Initialisation.md @@ -0,0 +1,5 @@ +# Initialisation + +::: jpc.init_activities_with_ffwd + +::: jpc.init_activities_from_gaussian \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..92b3065 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,74 @@ +# Getting started + +JPC is a [JAX](https://github.com/google/jax) library for predictive +coding networks (PCNs). It is built on top of two main libraries: + +* [Equinox](https://github.com/patrick-kidger/equinox) to define neural +networks with PyTorch-like syntax, and +* [Diffrax](https://github.com/patrick-kidger/diffrax) to solve the PC +activity (inference) dynamics. + +JPC provides a simple but flexible API for research of PCNs compatible with +useful JAX transforms such as `vmap` and `jit`. + + +## Installation + +``` +pip install jpc +``` + +Requires Python 3.8+, JAX 0.4.13+, [Equinox](https://github.com/patrick-kidger/equinox) +0.10.4+, [Diffrax](https://github.com/patrick-kidger/diffrax) 0.3.1+, and +[Jaxtyping](https://github.com/patrick-kidger/jaxtyping) 0.2.19+. + + +## Quick example + +Given a neural network with callable layers, for example defined with +[Equinox](https://github.com/patrick-kidger/equinox) +```py +import jax +import jax.numpy as jnp +from equinox import nn as nn + +# some data +x = jnp.array([1., 1., 1.]) +y = -x + +# network +key = jax.random.key(0) +_, *subkeys = jax.random.split(key) +network = [ + nn.Sequential( + [ + nn.Linear(3, 100, key=subkeys[0]), + nn.Lambda(jax.nn.relu) + ], + ), + nn.Linear(100, 3, key=subkeys[1]), +] +``` +We can train it with predictive coding in a few lines of code +```py +import jpc + +# initialise layer activities with a feedforward pass +activities = jpc.init_activities_with_ffwd(network, x) + +# run the inference dynamics to equilibrium +equilib_activities = jpc.solve_pc_activities(network, activities, y, x) + +# compute the PC parameter gradients +pc_param_grads = jpc.compute_pc_param_grads( + network, + equilib_activities, + y, + x +) +``` +The gradients can then be fed to your favourite optimiser (e.g. gradient +descent) to update the network parameters. + + +## Citation diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c6bedb3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,15 @@ +# Latest versions at time of writing. +mkdocs==1.3.0 # Main documentation generator. +mkdocs-material==7.3.6 # Theme +pymdown-extensions==9.4 # Markdown extensions e.g. to handle LaTeX. +mkdocstrings==0.17.0 # Autogenerate documentation from docstrings. +mknotebooks==0.7.1 # Turn Jupyter Lab notebooks into webpages. +pytkdocs_tweaks==0.0.8 # Tweaks mkdocstrings to improve various aspects +mkdocs_include_exclude_files==0.0.1 # Allow for customising which files get included +jinja2==3.0.3 # Older version. After 3.1.0 seems to be incompatible with current versions of mkdocstrings. +nbconvert==6.5.0 # | Older verson to avoid error +nbformat==5.4.0 # | +pygments==2.14.0 + +# Install latest version of our dependencies +jax[cpu] \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..c29665c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,105 @@ +theme: + name: material + features: + - navigation.sections # Sections are included in the navigation on the left. + - toc.integrate # Table of contents is integrated on the left; does not appear separately on the right. + - header.autohide # header disappears as you scroll + palette: + # Light mode / dark mode + # We deliberately don't automatically use `media` to check a user's preferences. We default to light mode as + # (a) it looks more professional, and (b) is more obvious about the fact that it offers a (dark mode) toggle. + - scheme: default + primary: white + accent: amber + toggle: + icon: material/weather-night + name: Switch to dark mode + - scheme: slate + primary: black + accent: amber + toggle: + icon: material/weather-sunny + name: Switch to light mode + icon: + repo: fontawesome/brands/github # GitHub logo in top right + logo: "material/brain" # brain logo in top left + favicon: "_static/favicon.png" + custom_dir: "docs/_overrides" # Overriding part of the HTML + + # These additions are my own custom ones, having overridden a partial. + #twitter_name: "@InnocFrancesco" + #twitter_url: "https://x.com/InnocFrancesco" + +site_name: jpc +site_description: The documentation for the jpc software library. +site_author: Francesco Innocenti + +repo_url: https://github.com/thebuckleylab/jpc +repo_name: thebuckleylab/jpc +edit_uri: "" # No edit button, as some of our pages are in /docs and some in /examples via symlink, so it's impossible for them all to be accurate + +strict: true # Don't allow warnings during the build process + +extra_javascript: + # The below three make MathJax work, see https://squidfunk.github.io/mkdocs-material/reference/mathjax/ + - _static/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js + +extra_css: + - _static/custom_css.css + +markdown_extensions: + - pymdownx.arithmatex: # Render LaTeX via MathJax + generic: true + - pymdownx.superfences # Seems to enable syntax highlighting when used with the Material theme. + - pymdownx.details # Allowing hidden expandable regions denoted by ??? + - pymdownx.snippets: # Include one Markdown file into another + base_path: docs + - admonition + - toc: + permalink: "ยค" # Adds a clickable permalink to each section heading + toc_depth: 4 + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +plugins: + - search # default search plugin; needs manually re-enabling when using any other plugins + - autorefs # Cross-links to headings + - include_exclude_files: + include: + - ".htaccess" + exclude: + - "_overrides" + - "_static/README.md" + - mknotebooks # Jupyter examples + - mkdocstrings: + handlers: + python: + setup_commands: + - import pytkdocs_tweaks + - pytkdocs_tweaks.main() + selection: + inherited_members: true # Allow looking up inherited methods + options: + show_root_heading: true # actually display anything at all... + show_root_full_path: true # display "jpc.asdf" not just "asdf" + show_if_no_docstring: true + show_signature_annotations: true + show_source: false # don't include source code + members_order: source # order methods according to their order of definition in the source code, not alphabetical order + heading_level: 4 + +nav: + - 'index.md' + - API: + - 'api/Initialisation.md' + - 'api/Inference.md' + - 'api/Energy functions.md' + - 'api/Gradients.md' + - 'FAQs.md' + +copyright: | + © 2024 Francesco Innocenti \ No newline at end of file