Initial commit

Co-authored-by: Aradhana Dube <a.dube@rug.nl>
Co-authored-by: Renzo I. Barraza Altamirano <r.i.barraza.altamirano@rug.nl>
Co-authored-by: Paolo Gibertini <p.gibertini@rug.nl>
Co-authored-by: Luca D. Fehlings <l.d.fehlings@rug.nl>

docs-site/docs/api/datasets.md

@@ -0,0 +1,7 @@
+# Datasets
+
+::: felice.datasets
+    options:
+      show_root_heading: true
+      show_source: true
+      heading_level: 2

docs-site/docs/api/index.md

@@ -0,0 +1,9 @@
+# API Reference
+
+API documentation for Felice.
+
+## Modules
+
+- [Neuron Models](neuron_models.md) - Neuron model implementations
+- [Solver](solver.md) - Zero-clipping solver
+- [Datasets](datasets.md) - Built-in datasets

docs-site/docs/api/neuron_models.md

@@ -0,0 +1,8 @@
+# Neuron Models
+
+::: felice.neuron_models
+    options:
+        show_root_heading: true
+        show_source: true
+        members_order: source
+        heading_level: 2

docs-site/docs/api/solver.md

@@ -0,0 +1,7 @@
+# Solver
+
+::: felice.solver
+    options:
+      show_root_heading: true
+      show_source: true
+      heading_level: 2

docs-site/docs/index.md

@@ -0,0 +1,33 @@
+# Felice
+
+This project provides a [JAX](https://github.com/google/jax) implementation of the different neuron models in felice
+
+## Overview
+
+The framework is built on top of diffrax and leverages JAX's automatic differentiation for efficient simulation and training of analogue models.
+
+### Key Features
+
+- **Delay learning**
+- **Non-linear neuron models**
+    - [**WereRabbit Neuron Model**](neuron_models/wererabbit/index.md): Implementation of a dual-state oscillatory neuron model with bistable dynamics
+    - [**FHN Neuron Model**](neuron_models/fhn/index.md)
+    - [**Snowball Neuron Model**](neuron_models/snowball/index.md)
+
+## 📦 Installation
+
+Felice uses [uv](https://github.com/astral-sh/uv) for dependency management. To install:
+
+```bash
+uv sync
+```
+
+### CUDA Support (Optional)
+
+For GPU acceleration with CUDA 13:
+
+```bash
+uv sync --extra cuda
+```
+
+See the [examples](scripts/examples/neuron_models/) directory for more detailed usage examples.

docs-site/docs/javascripts/mathjax.js

@@ -0,0 +1,20 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [['$', '$'], ['\\(', '\\)']],
+    displayMath: [['$$', '$$'], ['\\[', '\\]']],
+    processEscapes: true,
+    processEnvironments: true,
+    tags: 'ams'
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => { 
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})

docs-site/docs/neuron_models/fhn/README.md

@@ -0,0 +1,4 @@
+# Circuit implementing the fhn neuron.
+
+- The circuits in the schematics implement the FHN neuron described.
+- The FHN neuron is an implementation of the circuit described in (Ribar, L. (2019). Synthesis of neuromorphic circuits with neuromodulatory properties [Apollo - University of Cambridge Repository]. https://doi.org/10.17863/CAM.53750). The OTA and CMFB are well known designs that can be found in textbooks.

docs-site/docs/neuron_models/fhn/index.md

@@ -0,0 +1,22 @@
+# FitzHugh-Nagumo
+
+## Circuit equation
+
+$$
+\begin{align}
+    C\frac{dv}{dt} &= I_{app} - I_{passive} - I_{fast} - I_{slow} \\
+    \frac{dv_{slow}}{dt} &= \frac{v - v_{slow}}{\tau_{slow}} \\
+    \frac{dI_{app}}{dt} &= -\frac{I_{app}}{\tau_{syn}}
+\end{align}
+$$
+
+where the currents are:
+- $I_{passive} = g_{max}(v - E_{rev})$
+- $I_{fast} = a_{fast} \tanh(v - v_{off,fast})$
+- $I_{slow} = a_{slow} \tanh(v_{slow} - v_{off,slow})$
+
+## Examples
+
+See the following interactive notebook for a practical example:
+
+- [Basic Usage Example](fhn.ipynb) - Introduction to the FitzHugh-Nagumo model

docs-site/docs/neuron_models/index.md

@@ -0,0 +1,12 @@
+# Neuron Models
+
+Felice implements several non-linear neuron models for spiking neural networks.
+
+## Available Models
+
+| Model | Type | Key Features |
+|-------|------|--------------|
+| [WereRabbit](wererabbit/index.md) | Dual-state oscillatory | Bistable dynamics, predator-prey |
+| [FitzHugh-Nagumo](fhn/index.md) | ... | ... |
+| [Snowball](snowball/index.md) | Exponential Integrate-and-Fire neuron model | ... |
+| [LIF](lif/index.md) | Leaky Integrate-and-Fire neuron model | ... |

docs-site/docs/neuron_models/lif/index.md

@@ -0,0 +1,7 @@
+# LIF
+## Circuit Design
+W/L = 4/3
+## Circuit Simulation
+![lif, output plot](/docs-site/docs/img/lif_plot.png) Fig.1 The dynamics of leaky integrate and fire neuron. The grey signal is the input spikes, the yellow signal is the membrane potential and the dark blue is the output spikes from the neuron.
+## Referennces
+1. Sourikopoulos I, Hedayat S, Loyez C, Danneville F, Hoel V, Mercier E and Cappy A (2017) A 4-fJ/Spike Artificial Neuron in 65 nm CMOS Technology. Front. Neurosci. 11:123. doi: 10.3389/fnins.2017.00123

docs-site/docs/neuron_models/snowball/index.md

@@ -0,0 +1,13 @@
+# Snowball
+
+## Circuit description
+The circuit implemented for exponential integrate and fire neuron has been used from [1]. Part (a) in Fig.2 in [1] implements the exponential integrate and fire neuron. The neuron receives input currents using the input DPI filter [2]. This input current is integrated on the node Vmem by the membrane capacitance. The membrane potential leaks in the absence of an input spike which can be set by the bias Vleak. The Vmem potential node is connected to a cascoded source follower formed by the P14-15 and N5-6. A threshold voltage of the neuron can be set by the bias Vthr which is compared to the membrane potential. When the membrane potential is just near the threshold voltage, it starts the positive feedback block which exponentially increases membrane potential and causes the neuron to spike. As the neuron spikes, the membrane potential gets reset to ground and the refractory bias helps to stop the neuron from spiking during the refractory period as similar to a biological neuron. The circuit implemented for this experiment does not exercise either adaptability or needs a pulse extender as implemented in [1]. The Vdd used in the simulation is 1V. The neuron receives 5nA input pulses with a pulse width of 100μs.
+
+Input current mirror W/l = 0.2 <br>
+All other transistors W/L = 4/3
+## Circuit Simulation
+
+![snowball, output plot](/docs-site/docs/img/exif_plot.png) Fig.1 The dynamics of Exponential integrate and fire neuron. The light blue signal is the input spikes, the yellow signal is the membrane potential and the dark blue is the output spikes from the neuron.
+## References
+1. Rubino, Arianna, Melika Payvand, and Giacomo Indiveri. "Ultra-low power silicon neuron circuit for extreme-edge neuromorphic intelligence." 2019 26th IEEE International Conference on Electronics, Circuits and Systems (ICECS). IEEE, 2019.
+2. Bartolozzi, Chiara, Srinjoy Mitra, and Giacomo Indiveri. "An ultra low power current-mode filter for neuromorphic systems and biomedical signal processing." 2006 IEEE Biomedical Circuits and Systems Conference. IEEE, 2006.

docs-site/docs/neuron_models/wererabbit/index.md

@@ -0,0 +1,66 @@
+# WereRabbit
+
+The wererabbit neuron model is a two coupled oscillator that follows a predator- prey dynamic with a switching in the diagonal of the phaseplane. When the z in equation 1c represents the “moon phase”, when ever it cross that threshold, the rabbit (prey) becomes the predator.
+
+## Circuit equation
+
+$$
+\begin{align}
+    C\frac{du}{dt} &= z I_{bias} - I_{n0} e^{\kappa v / U_t} [z + 26e^{-2} (0.5 - u) z] - I_a \\
+    C\frac{dv}{dt} &= -z I_{bias} + I_{n0} e^{\kappa u / U_t} [z + 26e^{-2} (0.5 - v) z] - I_a \\
+    z &= tanh(\rho (u-v))\\
+    I_a &= \sigma I_{bias} \\
+\end{align}
+$$
+
+| **Parameter** | **Symbol** | **Definition** | **Value** |
+|-----------|--------|------------|-------|
+| Capacitance | C | Circuit capacitance | $0.1\,pF$ |
+| Bias current | $I_{bias}$ | DC bias current for the fixpoint location | $100\,pA$
+Leakage current | $I_{n0}$ | Transistor leakage current | $0.129\,pA$
+Subthreshold slope | $\kappa$ | Transistor subthreshold slope factor | $0.39$
+Thermal voltage | $U_t$ | Thermal voltage at room temperature | $25\,mV$
+Bias scale | $\sigma$ | Scaling factor for the distance between fixpoints | $0.6$
+Steepness | $\rho$ | Tanh steepness for the moonphase | $5$s
+
+## Abstraction
+To simplify the analysis of the model for simulation purposes, we can introduce a dimensionless time variable $\tau=tI_{bias}/C$, transforming the derivate of the equations in $\frac{d}{dt}=\frac{I_{bias}}{C}\frac{d}{d\tau}$. Substituting this time transformation on equation~\ref{eq:wererabbit:circ}
+
+$$
+\begin{equation}
+C\frac{I_{bias}}{C}\frac{du}{d\tau} = z I_{bias} - I_{n0} e^{\kappa v / U_t} [z + 26e^{-2} (0.5 - u) z] - \sigma I_{bias}
+\end{equation}
+$$
+
+And dividing by $I_{bias}$ on both sides:
+
+$$
+\begin{equation}
+    \frac{du}{d\tau} = z - \frac{I_{n0}}{I_{bias}} e^{\kappa v / U_t} [z + 26e^{-2} (0.5 - u) z] - \sigma
+\end{equation}
+$$
+
+Obtaining the following set of equations:
+
+$$
+\begin{align}
+    z &= tanh(\kappa (u-v)) \\
+    \frac{du}{dt} &= z - z \alpha e^{\beta v} [1 + \gamma (0.5 - u)] - \sigma \\
+    \frac{dv}{dt} &= -z - z \alpha e^{\beta u} [1 + \gamma (0.5 - v)] - \sigma
+\end{align}
+$$
+
+| **Parameter** | **Definition** | **Value** |
+|---------------|----------------|-----------|
+| $\tau$ | $tI_{bias}/C$ | -- |
+| $\alpha$ | $I_{n0}/I_{bias}$ | $0.0129$ |
+| $\beta$ | $\kappa/U_t$ | 15.6  |
+| $\gamma$ | -- | $26e^{-2}$ |
+| $\rho$ | Tanh steepness for the moonphase | 5  |
+| $\sigma$ | Scaling factor for the distance between fixpoints | 0.6 |
+
+## Examples
+
+See the following interactive notebook for a practical example:
+
+- [Basic Usage Example](wererabbit.ipynb) - Introduction to the WereRabbit model

docs-site/docs/stylesheets/extra.css

@@ -0,0 +1,14 @@
+.md-header__button.md-logo {
+    margin-top: 0;
+    margin-bottom: 0;
+    padding-top: 0;
+    padding-bottom: 0;
+}
+
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+    display: block;
+    width: auto;
+    height: 2.4rem;
+    fill: currentcolor;
+}