# Cavitational Capacitive Drive (CCD) Model for Ultrasonic Neuromodulation

This repository package contains a standalone NEURON simulation demonstrating the **Cavitational Capacitive Drive (CCD)** model applied to a cortical Regular Spiking (RS) neuron model, with ultrasound stimulation intensity recorded in **mW/cm²**.

## Citation & Authorship
- **Author**: Dr. Mithun Padmakumar
- **Publication Citation**: 
  Padmakumar, M., Rajan, D., & Steephen, J. E. (2026). *Cavitational capacitive drive: A computationally efficient model for ultrasonic neuromodulation.* **Journal of Neural Engineering**.

---

## Model Overview
Focused Ultrasound Stimulation (FUSS) induces high-frequency acoustic cavitation within lipid bilayers, periodically modulating membrane capacitance ($C_m$) and driving neuromodulatory responses. 

The CCD model provides a computationally efficient alternative to differential-equation-based intramembrane cavitation models by utilizing pre-computed optimization parameter tables ($k$, $s_e$, $s_c$). It directly evaluates the time-varying capacitance waveform $c(t)$ and its derivative $\frac{dc}{dt}$, allowing efficient long-duration multi-frequency simulations.

---

## Parameter Ranges
Ultrasound intensity (`usi`) is specified in **mW/cm²**. The parameter tables accept intensity values in the range **10 to 2000 mW/cm²**.

Ultrasound frequency (`usf`) is specified in kHz. The accepted frequency range is from 100 to 1000 kHz. 

---

## File Manifest
- `main.hoc`: Primary HOC entry point script. Constructs the RS neuron model, loads parameter tables, initializes recording vectors, opens GUI panels, and sets up voltage visualization.
- `ccd.mod`: NMODL mechanism implementing the CCD variable capacitance model.
- `ccd_tables.hoc`: HOC script initializing optimized parameter lookup tables ($k$, $s_e$, $s_c$) across ultrasound intensities (10–2000 mW/cm²) and frequencies (100–1000 kHz).
- `HH_traub.mod`: Hodgkin-Huxley fast $Na^+$ and $K^+$ channels for hippocampal/cortical pyramidal cells (Traub & Miles, 1991; Destexhe, 1992).
- `IM_cortex.mod`: Slow non-inactivating $M$-current ($K^+$) responsible for spike-frequency adaptation (Yamada et al., 1989; Destexhe, 1995).
- `GUI.hoc`: Graphical User Interface for adjusting CCD parameters (`usi` in mW/cm²) and selecting output saving operations.
- `processes.hoc`: HOC helper functions managing mechanism insertion, parameter updates, signal pre-processing (window averaging & downsampling), and data exports.

---

## Prerequisites
- **NEURON Simulation Environment** (v7.8+ or v8.x) with Python support.
- C/C++ compiler (`gcc` / `clang`) for compiling NMODL mechanisms via `nrnivmodl`.

---

## How to Run the Demonstration

### Step 1: Compile NMODL Mechanisms
Open a terminal in the `ccd_model_demo` directory and run:
```bash
nrnivmodl
```
This compiles `ccd.mod`, `HH_traub.mod`, and `IM_cortex.mod`, creating an `x86_64` (or host architecture) binary library directory.

### Step 2: Launch the Simulation GUI
Execute `main.hoc` using NEURON's GUI wrapper:
```bash
nrngui main.hoc
```

Upon launching:
1. The **RunControl** panel will automatically open.
2. The **CCD Parameters** panel will open with FUSS enabled (`bFUSS = 1`) and default intensity `usi = 50 mW/cm²`.
3. The **Manage Output** panel and **soma.v(0.5)** voltage graph will be visible.
4. Click **Init & Run** in the RunControl panel to execute the simulation.

---

## Output Options in GUI
Clicking buttons in the **Manage Output** panel exports data files into the `./Results/` directory:

1. **Save Raw Vm**: Saves time (`ts`) and raw soma membrane potential (`vsoma`) recorded at the original simulation time step (`dt = 0.025 / freq` ms) to `Results/ccd_<usi>_<freq>.dat` (or `Results/baseline.dat` if FUSS is disabled).
2. **Save Processed Vm**: Applies a 40-point centered moving window average and downsamples by the frequency factor (`freq`) to convert the effective resolution to `dt = 0.025` ms. Plots the processed trace in a new NEURON graph window and saves to `Results/ccd_processed_<usi>_<freq>.dat` along with metadata `Results/ccd_processed_<usi>_<freq>_metadata.dat`.
3. **Save Cm Waveform**: Exports the full membrane capacitance vector ($C_m(t)$) from $t=0$ to $t_{stop}$ to `Results/ccd_Cm_<usi>_<freq>.dat`.
4. **Save AP Times**: Saves the action potential firing timestamps to `Results/APtimes_ccd_<usi>_<freq>.dat`.

---

## How to Use the CCD Mechanism in Custom NEURON Scripts

To integrate the CCD mechanism into your own custom neuron or network models in NEURON:

### 1. Load Parameter Lookup Tables
Always load `ccd_tables.hoc` before inserting the `ccd` mechanism:
```hoc
load_file("ccd_tables.hoc")
```

### 2. Insert Mechanism & Bind Pointer
Insert `ccd` into the target sections (e.g., `soma`) and **immediately bind the mechanism's `c` pointer to NEURON's capacitance variable (`cm`) for all segments in the target section**:
```hoc
soma {
    insert ccd
    for (x, 0) {
        setpointer c_ccd(x), cm(x)
    }
}
```

### 3. Set Stimulation Parameters
Set the ultrasound stimulation parameters (intensity in **mW/cm²**):
```hoc
usi_ccd = 100     // Ultrasound intensity in mW/cm2 (supported range: 10 to 2000 mW/cm2)
usf_ccd = 200     // Ultrasound frequency in kHz (supported range: 100 to 1000 kHz)
tbegin_ccd = 20   // FUSS start time in ms
tdur_ccd = 100    // FUSS duration in ms
```

Optionally, if it is intended to use pulse-width-modulation (PWM), set the following parameters also:

```hoc
PWMperiod_ccd = 10  // PWM Period ( = 1000 / PRF) in ms, where PRF is the pulse-repetition frequency in Hz. 
PWMdc_ccd = 0.2     // Duty Cycle
```

### 4. Adjust Integration Time Step (`dt`) before running simulation
Because ultrasound oscillations occur at high frequencies (100–1000 kHz), the simulation time step `dt` MUST be scaled with frequency:
```hoc
dt = 0.025 / usf_ccd
```