# pinton-lab/ultraneuron architecture

> Architecture diagram of the GitHub repository pinton-lab/ultraneuron, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pinton-lab/ultraneuron
- Repository: https://github.com/pinton-lab/ultraneuron

## Overview

Ultraneuron predicts ultrasound-evoked neural activity from acoustic, displacement, and temperature fields, producing voxel-wise firing maps and validation reports. Its canonical workflow runs acoustic propagation, derives elastic displacement and bioheat fields, converts strain to membrane tension, simulates neural responses, then builds reports and mechanism/sensitivity comparisons. The README documents these stages; source excerpts and the source index support the internal model and report connections. Upstream physics solvers are external, and some documented driver details are unsampled.

Main entry points: [`validation_report/report_builder.py`](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/report_builder.py) (Report builder), [`ultraneuron/multicompartment.py`](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/multicompartment.py) (Multi-compartment HH), [`scripts/run_neural_sim.py`](https://github.com/pinton-lab/ultraneuron/blob/main/scripts/run_neural_sim.py) (Voxel simulation), [`validation_report/builders/acoustic_outputs.py`](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/acoustic_outputs.py) (Acoustic outputs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_physics["Field generation"]
  node_acoustic["Acoustic FDTD"]
  node_rescale["Pressure rescaling"]
  node_arf["ARF recompute<br/>[recompute_arf.py]"]
  node_elastic["Shear FDTD"]
  node_bioheat["Pennes bioheat<br/>[run_bioheat.py]"]
end

subgraph group_cell["Cell simulation"]
  node_neural_driver["Voxel simulation<br/>[run_neural_sim.py]"]
  node_strain["Strain conversion<br/>[strain.py]"]
  node_neuron["Point HH neuron<br/>[neuron.py]"]
  node_multicompartment["Multi-compartment HH"]
  node_cuda["CUDA kernels<br/>[cuda_backend.py]"]
end

subgraph group_mechanisms["Neural mechanisms"]
  node_channels["Mechanosensitive channels<br/>[channels.py]"]
  node_channel_library["Channel presets<br/>[channel_library.py]"]
  node_calcium["Calcium pool<br/>[calcium.py]"]
  node_nice["NICE cavitation<br/>[nice.py]"]
  node_thermosensors["TRP thermosensors<br/>[thermosensors.py]"]
  node_astrocyte["Astrocyte relay<br/>[astrocyte.py]"]
  node_synapse["Synaptic transmission<br/>[synapse.py]"]
  node_nmda["NMDA receptor<br/>[nmda.py]"]
  node_soliton["Soliton alternative<br/>[soliton.py]"]
end

subgraph group_reporting["Validation reports"]
  node_report_driver["Report builder<br/>[report_builder.py]"]
  node_acoustic_report["Acoustic outputs"]
  node_elastic_report["Elastic outputs<br/>[elastic_outputs.py]"]
  node_neural_report["Neural outputs<br/>[neural_outputs.py]"]
  node_thermal_report["Thermal outputs<br/>[thermal_outputs.py]"]
  node_astro_report["Astrocyte outputs"]
  node_synaptic_report["Synaptic outputs"]
  node_displacement_report["Displacement outputs"]
  node_wave_report["Wave animation<br/>[wave_animation.py]"]
end

subgraph group_support["Integration support"]
  node_provenance["Parameter provenance<br/>[provenance.py]"]
  node_registration["Anatomical registration<br/>[registration.py]"]
  node_paths["External path resolution<br/>[paths.py]"]
end

node_operator(("Researcher"))
node_upstream["External field solvers"]
node_maps["Voxel firing maps"]

node_operator -->|"runs"| node_acoustic
node_upstream -.->|"produces fields"| node_acoustic
node_acoustic -->|"pressure history"| node_rescale
node_rescale -->|"rescaled pressure"| node_arf
node_arf -->|"radiation force"| node_elastic
node_elastic -->|"displacement field"| node_neural_driver
node_elastic -.->|"simulation inputs"| node_bioheat
node_bioheat -->|"temperature field"| node_neural_driver
node_neural_driver -.->|"converts strain"| node_strain
node_strain -->|"drives gating"| node_channels
node_channel_library -->|"defines presets"| node_channels
node_multicompartment -->|"uses channels"| node_channels
node_neuron -->|"uses channels"| node_channels
node_multicompartment -->|"uses calcium"| node_calcium
node_multicompartment -->|"uses NICE model"| node_nice
node_multicompartment -->|"uses thermosensors"| node_thermosensors
node_neuron -->|"dispatches batch"| node_cuda
node_multicompartment -->|"dispatches batch"| node_cuda
node_neural_driver -->|"simulates voxels"| node_multicompartment
node_neural_driver -->|"writes maps"| node_maps
node_operator -->|"builds report"| node_report_driver
node_report_driver -->|"routes section"| node_acoustic_report
node_report_driver -->|"routes section"| node_elastic_report
node_report_driver -->|"routes section"| node_neural_report
node_report_driver -->|"routes section"| node_thermal_report
node_report_driver -->|"routes section"| node_astro_report
node_report_driver -->|"routes section"| node_synaptic_report
node_report_driver -->|"routes section"| node_displacement_report
node_report_driver -->|"routes animation"| node_wave_report
node_neural_report -->|"uses acoustic data"| node_acoustic_report
node_neural_report -->|"uses elastic data"| node_elastic_report
node_elastic_report -->|"uses acoustic data"| node_acoustic_report
node_acoustic_report -->|"uses placement"| node_registration
node_acoustic_report -->|"resolves resources"| node_paths
node_operator -->|"classifies parameters"| node_provenance
node_operator -->|"scores alternative"| node_soliton
node_operator -->|"selects relay"| node_astrocyte
node_operator -->|"selects pathway"| node_synapse
node_operator -->|"selects receptor"| node_nmda

click node_acoustic "https://github.com/pinton-lab/ultraneuron/blob/main/scripts/run_halle_dacc_fdtd.py"
click node_rescale "https://github.com/pinton-lab/ultraneuron/blob/main/scripts/rescale_propagation_map.py"
click node_arf "https://github.com/pinton-lab/ultraneuron/blob/main/scripts/recompute_arf.py"
click node_elastic "https://github.com/pinton-lab/ultraneuron/blob/main/scripts/rerun_shear_fdtd.py"
click node_bioheat "https://github.com/pinton-lab/ultraneuron/blob/main/scripts/run_bioheat.py"
click node_neural_driver "https://github.com/pinton-lab/ultraneuron/blob/main/scripts/run_neural_sim.py"
click node_strain "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/strain.py"
click node_channels "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/channels.py"
click node_channel_library "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/channel_library.py"
click node_neuron "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/neuron.py"
click node_multicompartment "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/multicompartment.py"
click node_cuda "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/cuda_backend.py"
click node_calcium "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/calcium.py"
click node_nice "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/nice.py"
click node_thermosensors "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/thermosensors.py"
click node_astrocyte "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/astrocyte.py"
click node_synapse "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/synapse.py"
click node_nmda "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/nmda.py"
click node_soliton "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/soliton.py"
click node_report_driver "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/report_builder.py"
click node_acoustic_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/acoustic_outputs.py"
click node_elastic_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/elastic_outputs.py"
click node_neural_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/neural_outputs.py"
click node_thermal_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/thermal_outputs.py"
click node_astro_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/astrocyte_outputs.py"
click node_synaptic_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/synaptic_outputs.py"
click node_displacement_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/displacement_outputs.py"
click node_wave_report "https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/wave_animation.py"
click node_provenance "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/provenance.py"
click node_registration "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/registration.py"
click node_paths "https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/paths.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_acoustic,node_rescale,node_arf,node_elastic,node_bioheat toneBlue
class node_neural_driver,node_strain,node_neuron,node_multicompartment,node_cuda toneAmber
class node_channels,node_channel_library,node_calcium,node_nice,node_thermosensors,node_astrocyte,node_synapse,node_nmda,node_soliton toneMint
class node_report_driver,node_acoustic_report,node_elastic_report,node_neural_report,node_thermal_report,node_astro_report,node_synaptic_report,node_displacement_report,node_wave_report toneRose
class node_provenance,node_registration,node_paths,node_operator,node_upstream,node_maps toneIndigo
```

## Components

### Field generation

- [Acoustic FDTD](https://github.com/pinton-lab/ultraneuron/blob/main/scripts/run_halle_dacc_fdtd.py): `scripts/run_halle_dacc_fdtd.py`
- [Pressure rescaling](https://github.com/pinton-lab/ultraneuron/blob/main/scripts/rescale_propagation_map.py): `scripts/rescale_propagation_map.py`
- [ARF recompute](https://github.com/pinton-lab/ultraneuron/blob/main/scripts/recompute_arf.py): `scripts/recompute_arf.py`
- [Shear FDTD](https://github.com/pinton-lab/ultraneuron/blob/main/scripts/rerun_shear_fdtd.py): `scripts/rerun_shear_fdtd.py`
- [Pennes bioheat](https://github.com/pinton-lab/ultraneuron/blob/main/scripts/run_bioheat.py): `scripts/run_bioheat.py`

### Cell simulation

- [Voxel simulation](https://github.com/pinton-lab/ultraneuron/blob/main/scripts/run_neural_sim.py): `scripts/run_neural_sim.py`
- [Strain conversion](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/strain.py): `ultraneuron/strain.py`
- [Point HH neuron](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/neuron.py): `ultraneuron/neuron.py`
- [Multi-compartment HH](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/multicompartment.py): `ultraneuron/multicompartment.py`
- [CUDA kernels](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/cuda_backend.py): `ultraneuron/cuda_backend.py`

### Neural mechanisms

- [Mechanosensitive channels](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/channels.py): `ultraneuron/channels.py`
- [Channel presets](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/channel_library.py): `ultraneuron/channel_library.py`
- [Calcium pool](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/calcium.py): `ultraneuron/calcium.py`
- [NICE cavitation](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/nice.py): `ultraneuron/nice.py`
- [TRP thermosensors](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/thermosensors.py): `ultraneuron/thermosensors.py`
- [Astrocyte relay](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/astrocyte.py): `ultraneuron/astrocyte.py`
- [Synaptic transmission](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/synapse.py): `ultraneuron/synapse.py`
- [NMDA receptor](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/nmda.py): `ultraneuron/nmda.py`
- [Soliton alternative](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/soliton.py): `ultraneuron/soliton.py`

### Validation reports

- [Report builder](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/report_builder.py): `validation_report/report_builder.py`
- [Acoustic outputs](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/acoustic_outputs.py): `validation_report/builders/acoustic_outputs.py`
- [Elastic outputs](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/elastic_outputs.py): `validation_report/builders/elastic_outputs.py`
- [Neural outputs](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/neural_outputs.py): `validation_report/builders/neural_outputs.py`
- [Thermal outputs](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/thermal_outputs.py): `validation_report/builders/thermal_outputs.py`
- [Astrocyte outputs](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/astrocyte_outputs.py): `validation_report/builders/astrocyte_outputs.py`
- [Synaptic outputs](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/synaptic_outputs.py): `validation_report/builders/synaptic_outputs.py`
- [Displacement outputs](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/displacement_outputs.py): `validation_report/builders/displacement_outputs.py`
- [Wave animation](https://github.com/pinton-lab/ultraneuron/blob/main/validation_report/builders/wave_animation.py): `validation_report/builders/wave_animation.py`

### Integration support

- [Parameter provenance](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/provenance.py): `ultraneuron/provenance.py`
- [Anatomical registration](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/registration.py): `ultraneuron/registration.py`
- [External path resolution](https://github.com/pinton-lab/ultraneuron/blob/main/ultraneuron/paths.py): `ultraneuron/paths.py`

### Other components

- **Researcher**
- **External field solvers**
- **Voxel firing maps**

## Connections

- Researcher → Acoustic FDTD: runs
- External field solvers → Acoustic FDTD: produces fields
- Acoustic FDTD → Pressure rescaling: pressure history
- Pressure rescaling → ARF recompute: rescaled pressure
- ARF recompute → Shear FDTD: radiation force
- Shear FDTD → Voxel simulation: displacement field
- Shear FDTD → Pennes bioheat: simulation inputs
- Pennes bioheat → Voxel simulation: temperature field
- Voxel simulation → Strain conversion: converts strain
- Strain conversion → Mechanosensitive channels: drives gating
- Channel presets → Mechanosensitive channels: defines presets (evidence: `ultraneuron/channel_library.py`)
- Multi-compartment HH → Mechanosensitive channels: uses channels (evidence: `ultraneuron/multicompartment.py`)
- Point HH neuron → Mechanosensitive channels: uses channels (evidence: `ultraneuron/neuron.py`)
- Multi-compartment HH → Calcium pool: uses calcium (evidence: `ultraneuron/multicompartment.py`)
- Multi-compartment HH → NICE cavitation: uses NICE model (evidence: `ultraneuron/multicompartment.py`)
- Multi-compartment HH → TRP thermosensors: uses thermosensors (evidence: `ultraneuron/multicompartment.py`)
- Point HH neuron → CUDA kernels: dispatches batch (evidence: `ultraneuron/neuron.py`)
- Multi-compartment HH → CUDA kernels: dispatches batch (evidence: `ultraneuron/multicompartment.py`)
- Voxel simulation → Multi-compartment HH: simulates voxels
- Voxel simulation → Voxel firing maps: writes maps
- Researcher → Report builder: builds report
- Report builder → Acoustic outputs: routes section (evidence: `validation_report/report_builder.py`)
- Report builder → Elastic outputs: routes section (evidence: `validation_report/report_builder.py`)
- Report builder → Neural outputs: routes section (evidence: `validation_report/report_builder.py`)
- Report builder → Thermal outputs: routes section (evidence: `validation_report/report_builder.py`)
- Report builder → Astrocyte outputs: routes section (evidence: `validation_report/report_builder.py`)
- Report builder → Synaptic outputs: routes section (evidence: `validation_report/report_builder.py`)
- Report builder → Displacement outputs: routes section (evidence: `validation_report/report_builder.py`)
- Report builder → Wave animation: routes animation (evidence: `validation_report/report_builder.py`)
- Neural outputs → Acoustic outputs: uses acoustic data (evidence: `validation_report/builders/neural_outputs.py`)
- Neural outputs → Elastic outputs: uses elastic data (evidence: `validation_report/builders/neural_outputs.py`)
- Elastic outputs → Acoustic outputs: uses acoustic data (evidence: `validation_report/builders/elastic_outputs.py`)
- Acoustic outputs → Anatomical registration: uses placement (evidence: `validation_report/builders/acoustic_outputs.py`)
- Acoustic outputs → External path resolution: resolves resources
- Researcher → Parameter provenance: classifies parameters
- Researcher → Soliton alternative: scores alternative
- Researcher → Astrocyte relay: selects relay
- Researcher → Synaptic transmission: selects pathway
- Researcher → NMDA receptor: selects receptor
