Adding Neuroevolution (#183)

* neuroevo push 1 + devcontainer git no verify

* read write utils

* initialize functions

* add exchange_agents & fix init_common

* update_exchange_and_mutate_info & type fixes

* readwrite numpy -> lists

* evolve utils + hydra config restructure start

* restructuring + docstring bleeding into DL module

* update recommended git workflow (#133)

* DL doc beautified

* compute utils + split fit/config

* added hybrid ne+dl module, restructured to match

* update readme

* utils fixup

* docstring dot paths

* utils touchups, start porting envs

* touchups + imitation

* misc changes

* documentation update + high level config docu

* more doc updates + clean

* replaced autoapi w/ autosummary in docs/ for greater customizability

* config fixes for all but DL + NE

* added paramlink color when targetted

* add documentation on how to document

* finished fixing DL docs, resumed NE

* mostly neuroevo docu

* hydra yaml inheritance, more stable paths, better intro

* reorganized run & store_configs, big doc add root API

* full transition to hydra-zen, big more stable structure

* messy commit, good hydra zen progress

* full hydra-zen (+ yaml configs if wished) more or less figured

* file shuffling

* small cleaning

* doc cleanup + starting finalizing neuroevo

* general done, dl done, ne almost done

* neuroevolution example

* more ne fixes

* almost finish neuroevo

* pr ready

* missing req

* formatting + docker logic typecheck unittest

* more workflow patching

.devcontainer.json

@@ -14,30 +14,32 @@
           "matangover.mypy"
         ],
         "settings": {
-          "ruff.lint.arg": [
-              "--config=pyproject.toml"
-          ],
           "black-formatter.args": [
               "--config=pyproject.toml"
           ],
-          "[python]": {
-              "editor.defaultFormatter": "ms-python.black-formatter",
-              "editor.formatOnSave": true,
-              "editor.codeActionsOnSave": {
-                  "source.organizeImports": true
-              }
-          },
-          "mypy.configFile": "pyproject.toml",
+          "esbonio.server.hideSphinxOutput": true,
           "esbonio.sphinx.buildDir": "${workspaceFolder}/docs/_build/html",
           "esbonio.sphinx.confDir": "${workspaceFolder}/docs/",
           "esbonio.sphinx.srcDir": "${workspaceFolder}/docs/",
-          "restructuredtext.linter.doc8.executablePath": "/usr/local/bin/doc8",
-          "restructuredtext.syntaxHighlighting.disabled": true,
           "files.insertFinalNewline": true,
           "files.trimTrailingWhitespace": true,
+          "git.allowNoVerifyCommit": true,
+          "mypy.configFile": "pyproject.toml",
           "python.analysis.ignore": [
               "/**"
-          ]
+          ],
+          "restructuredtext.linter.doc8.executablePath": "/usr/local/bin/doc8",
+          "restructuredtext.syntaxHighlighting.disabled": true,
+          "ruff.lint.arg": [
+              "--config=pyproject.toml"
+          ],
+          "[python]": {
+              "editor.defaultFormatter": "ms-python.black-formatter",
+              "editor.formatOnSave": true,
+              "editor.codeActionsOnSave": {
+                  "source.organizeImports": true
+              }
+          }
         }
       }
     },

.github/workflows/container-build-push.yaml → .github/workflows/docker-build-push.yaml

@@ -1,21 +1,21 @@
-# Builds the container image with run dependencies & push it to the registry
-name: Container Build & Push
+# Builds the Docker image & pushes it to Docker Hub.
+name: Docker Build & Push
 
 on:
   push:
     branches: [main]
     paths:
-      - Containerfile
+      - Dockerfile
       - pyproject.toml
-      - .github/workflows/container-build-push.yaml
+      - .github/workflows/docker-build-push.yaml
 
 jobs:
-  container-build-push:
+  docker-build-push:
     runs-on: self-hosted
     steps:
       - name: Checkout the GitHub repo
         uses: actions/checkout@v4
       - name: Build the CNeuroMax image
-        run: podman build -t cneuromod/cneuromax:latest -f Containerfile .
+        run: podman build -t cneuromod/cneuromax:latest -f Dockerfile .
       - name: Push the CNeuroMax image to Docker Hub
         run: podman push docker.io/cneuromod/cneuromax:latest

.github/workflows/container-build.yaml → .github/workflows/docker-build.yaml

@@ -1,19 +1,19 @@
-# Builds the container image with run dependencies
-name: Container Build
+# Builds the Docker image
+name: Docker Build
 
 on:
   pull_request:
     branches: [main]
     paths:
-      - Containerfile
+      - Dockerfile
       - pyproject.toml
-      - .github/workflows/container-build.yaml
+      - .github/workflows/docker-build.yaml
 
 jobs:
-  container-build:
+  docker-build:
     runs-on: self-hosted
     steps:
       - name: Checkout the GitHub repo
         uses: actions/checkout@v4
       - name: Build the tentative CNeuroMax image
-        run: podman build -f Containerfile .
+        run: podman build -f Dockerfile .

.github/workflows/typecheck-unittest.yaml

@@ -22,19 +22,23 @@ jobs:
   typecheck-unittest:
     runs-on: self-hosted
     steps:
-      - name: Pull the container image
-        run: podman pull docker.io/cneuromod/cneuromax:latest
       - name: Checkout the GitHub repo
         uses: actions/checkout@v4
+      # Waiting for `Docker Build` to complete to not build the image twice
+      - name: Stall the job for 5 minutes if it is a pull request
+        if: github.event_name == 'pull_request'
+        run: sleep 300
+      - name: Build the CNeuroMax image
+        run: podman build -t cneuromod/cneuromax:test -f Dockerfile .
       - name: Run mypy
         run: >
           podman run --rm -v $PWD:/cneuromax -w /cneuromax
-          docker.io/cneuromod/cneuromax:latest
+          cneuromod/cneuromax:test
           mypy --config-file=pyproject.toml cneuromax
       - name: Run pytest
         run: >
           podman run --rm -v $PWD:/cneuromax -w /cneuromax
-          docker.io/cneuromod/cneuromax:latest
+          cneuromod/cneuromax:test
           pytest --cov cneuromax
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v3

.gitignore

@@ -1,5 +1,5 @@
 **/_build/
-**/autoapi/
+**/_autosummary/
 **/cneuromax.egg-info/
 **/.coverage
 **/data/
@@ -11,3 +11,5 @@
 **/.ruff_cache/
 **/.vscode/
 WANDB_KEY.txt
+test.ipynb
+cneuromax/fitting/neuroevolution/space/imitation.py

Containerfile → Dockerfile

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------#
-# This Containerfile (a.k.a. Dockerfile) is used to build the Docker image
+# This Dockerfile (a.k.a. Dockerfile) is used to build the Docker image
 # (which can turn into an Apptainer image) shared by all CNeuroMax projects.
 # It installs all of the dependencies but does not install CNeuroMax itself,
 # for development purposes.

README.md

@@ -19,80 +19,137 @@
     https://img.shields.io/badge/code%20style-black-000000.svg)](
         https://github.com/psf/black)
 
-Full documentation available at [https://courtois-neuromod.github.io/cneuromax](
-    https://courtois-neuromod.github.io/cneuromax/).
+<h2>Overview</h2>
 
-<h2>Introduction</h2>
+CNeuroMax is a Machine Learning workspace for model fitting
+([Deep Learning](https://en.wikipedia.org/wiki/Deep_learning) +
+[Neuroevolution](https://en.wikipedia.org/wiki/Neuroevolution) +
+[HPO](https://en.wikipedia.org/wiki/Hyperparameter_optimization)
+w/ [Oríon](https://github.com/Epistimio/orion)), testing
+and serving (with [Lightning Apps](https://lightning.ai/docs/app/stable/))
+AI/ML models. CNeuroMax aims to:
 
-CNeuroMax is a framework for large-scale training of machine learning models,
-with an emphasis on easy deployment in academic high-performance computing
-environments. CNeuroMax aims to:
+**1. Reduce code & configuration boilerplate with:**
+* [Hydra](https://github.com/facebookresearch/hydra) for task/experiment
+configuration.
+* [Hydra-zen](https://github.com/mit-ll-responsible-ai/hydra-zen) for
+[Hydra](https://github.com/facebookresearch/hydra) structured configuration
+management.
+* [Lightning](https://github.com/Lightning-AI/pytorch-lightning) for
+[PyTorch](https://github.com/pytorch/pytorch) code.
 
-1. **Facilitate the configuration of complex models and training runs through
-   tools like:** Hydra, Hydra-Zen, Lightning etc.
+**2. Simplify machine learning workflows:**
+* Hyperparameter optimization with [Orion](https://github.com/Epistimio/orion)
+through its
+[Hydra Sweeper plugin](https://github.com/Epistimio/hydra_orion_sweeper).
+* SLURM job definition, queuing and monitoring with
+[Submitit](https://github.com/facebookincubator/submitit) through its
+[Hydra Launcher plugin](https://hydra.cc/docs/plugins/submitit_launcher/).
+* [Docker](https://www.docker.com/) / [Apptainer](https://apptainer.org/)
+environment containerization for both regular & SLURM-based execution.
+* Transition from regular execution to SLURM-based execution by only swapping
+container technology and as little as a single
+[Hydra](https://github.com/facebookresearch/hydra)
+configuration field.
 
-2. **Automate much of the process of deployment in a high-performance computing
-   environment:** creating SLURM scripts, monitoring SLURM jobs, setting up
-   virtual environments, upgrading packages, tuning hyperparameters, etc.
+**3. Automate workspace & coding processes:**
+* Package upgrades through
+[Renovate](https://github.com/renovatebot/renovate).
+* Docstring documentation generation with
+[Sphinx](https://github.com/sphinx-doc/sphinx).
+* Pre-commit formatting & linting hooks with
+[pre-commit](https://pre-commit.com/).
+* Documentation/Docker image validation/deployment, formatting, linting,
+type-checking & unit tests upon contribution to the ``main`` branch using
+[GitHub Actions](https://github.com/features/actions).
 
-3. **Provide a space for researchers to share their code and experiment
-   results:** a central repository with a common solid and well-tested
-   object-oriented structure for Lightning Modules, subdirectories for each
-   experiment, Weights & Biases working both locally and on SLURM with support
-   for team-shared logging etc.
+**4. Facilitate researcher collaboration through:**
+* An object-oriented structure for code sharing & reusability.
+* A mono-repository workspace with task/experiment-specific subdirectories.
+* A very informative & clear to navigate Python API reference.
+* Shared logging with a [Weights & Biases](https://wandb.ai/site) team space.
 
-4. **Offer optional tools to strengthen code quality and reproducibility:**
-   code linting and formatting, unit testing, static & dynamic type checking
-   that supports tensor shapes and dtypes, documentation auto-generation and
-   auto-deployment, precommit hooks etc.
+**5. Promote high-quality and reproducible code by:**
+* Linting with [Ruff](https://github.com/astral-sh/ruff),
+formatting with [Black](https://github.com/psf/black),
+unit-testing with [pytest](https://github.com/pytest-dev/pytest).
+* Type-checking with [Mypy](https://github.com/python/mypy) (static)
+& [Beartype](https://github.com/beartype/beartype) (dynamic).
+* DType & Shape type hinting for [PyTorch](https://github.com/pytorch/pytorch)
+tensors using [jaxtyping](https://github.com/google/jaxtyping) &
+[NumPy](https://github.com/numpy/numpy) arrays using
+[nptyping](https://github.com/ramonhagenaars/nptyping). Fully type checkable
+at runtime with [Beartype](https://github.com/beartype/beartype).
+* Providing a common [Development Container](https://containers.dev/)
+recipe with the above features enabled + documentation preview
+with [esbonio](https://github.com/swyddfa/esbonio) &
+[GitHub Copilot](https://github.com/features/copilot).
 
-<h2>Repository structure:</h1>
+**6. Smoothen up rough edges by providing:**
+* Extensive documentation on how to install/execute on regular & SLURM-based
+systems.
+* Unassuming guides on how to contribute to the codebase.
+* Tutorials on i) how to facilitate code transport across machines &  ii) how
+to prune unrelated components of the library for paper publication.
+* Offline [Weights & Biases](https://wandb.ai/site) support with
+[wandb-osh](https://github.com/klieret/wandb-offline-sync-hook).
+
+<h2>High-level repository tree:</h2>
 
 ```
 cneuromax/
-├─ .github/                  <-- Config files for GitHub automation (tests, containers, etc)
-├─ cneuromax/                <-- Machine Learning code
-│  ├─ fitting/               <-- ML model fitting code
-│  │  ├─ common/             <-- Code common to all fitting workflows
-│  │  │  ├─ __init__.py      <-- Stores common Hydra configs
-│  │  │  └─ fitter.py        <-- Base Hydra config common to all fitting workflows
+├─ .github/                  <-- Config files for GitHub Actions (tests, containers, etc)
+├─ cneuromax/                <-- Root
+│  ├─ fitting/               <-- Model fitting code
 │  │  ├─ deeplearning/       <-- Deep Learning code
 │  │  │  ├─ datamodule/      <-- Lightning DataModules
-│  │  │  │  ├─ base.py       <-- Base Lightning DataModule to build upon
 │  │  │  ├─ litmodule/       <-- Lightning Modules
-│  │  │  │  ├─ base.py       <-- Base Lightning Module to build upon
-│  │  │  ├─ nnmodule/        <-- PyTorch Modules & Hydra configs
+│  │  │  ├─ nnmodule/        <-- PyTorch Modules
 │  │  │  ├─ utils/           <-- Deep Learning utilities
-│  │  │  ├─ __init__.py      <-- Stores Deep Learning Hydra configs
-│  │  │  ├─ __main__.py      <-- Entrypoint when calling `python cneuromax.fitting.deeplearning`
-│  │  │  ├─ config.yaml      <-- Default Hydra configs & settings
-│  │  │  └─ fitter.py        <-- Deep Learning fitting
-│  │  └─ neuroevolution/     <-- Neuroevolution code
-│  ├─ serving/               <-- Contains the code to create applications (cozmo inference, etc)
-│  ├─ task/                  <-- Contains the Deep Learning tasks
+│  │  │  ├─ config.py        <-- Deep Learning structured configs
+│  │  │  ├─ runner.py        <-- Deep Learning task runner
+│  │  │  └─ train.py         <-- Deep Learning training function
+│  │  ├─ neuroevolution/     <-- Neuroevolution code
+│  │  │  ├─ agent/           <-- Neuroevolution agents (encapsulate networks)
+│  │  │  ├─ net/             <-- Neuroevolution networks
+│  │  │  ├─ space/           <-- Neuroevolution spaces (where agents get evaluated)
+│  │  │  ├─ utils/           <-- Neuroevolution utilities
+│  │  │  ├─ config.py        <-- Neuroevolution structured configs
+│  │  │  ├─ evolve.py        <-- Neuroevolution evolution function
+│  │  │  └─ runner.py        <-- Neuroevolution task runner
+│  │  ├─ config.py           <-- Fitting structured configs
+│  │  └─ runner.py           <-- Fitting task runner
+│  ├─ serving/               <-- Contains the code to create apps (cozmo inference, etc)
+│  ├─ projects/              <-- Contains all existing projects
 │  │  │
 │  │  │                          ******************************************
-│  │  └─ my_new_task/        <-- *** Your new Deep Learning task folder ***
-│  │     ├─ __init__.py      <-- ********** Your Hydra Configs ************
+│  │  └─ my_new_project/     <-- ******** Your new project folder *********
+│  │     ├─ task/            <-- *********** Your task folder *************
+│  │     │  └─ config.yaml   <-- ****** Your task configuration file ******
+│  │     ├─ __main__.py      <-- **** Your Hydra Configs & entrypoint *****
 │  │     ├─ datamodule.py    <-- ******* Your Lightning DataModule ********
 │  │     ├─ litmodule.py     <-- ********* Your Lightning Module **********
 │  │     ├─ nnmodule.py      <-- ********** Your PyTorch Module ***********
-│  │     └─ config.yaml      <-- ****** Your Hydra configuration file *****
 │  │                             ******************************************
 │  │
-│  └─ utils/                 <-- CNeuroMax utilities
+│  ├─ utils/                 <-- CNeuroMax utilities
+│  ├─ __init__.py            <-- Sets up Beartype
+│  └─ config.py              <-- Base structured configs
+│  └─ runner.py              <-- Base task runner
 ├─ docs/                     <-- Documentation files
 ├─ .devcontainer.json        <-- VSCode container development config
 ├─ .gitignore                <-- Files to not track with Git/GitHub
 ├─ .pre-commit-config.yaml   <-- Pre-"git commit" actions config (format, lint, etc)
 ├─ .yamllint.yaml            <-- YAML files config
-├─ Containerfile             <-- To build the Docker image
+├─ Dockerfile                <-- To build the Docker image
 ├─ LICENSE                   <-- MIT License file
 ├─ README.md                 <-- Repository description file
 ├─ pyproject.toml            <-- Python code & dependencies config
 └─ renovate.json             <-- Renovate Bot config (keeps dependencies up-to-date)
 ```
 
+<h2>Additional information:</h1>
+
 CNeuroMax is developed in the context of the
 [Courtois Project on Neuronal Modelling](https://cneuromod.ca), also known as
 CNeuroMod. Launched in 2018, CNeuroMod aims to create more human-like AI models