Skip to main content

Bruce-Zilany-Carney Auditory Nerve Model (Python Interface)

This repository provides a modern Python interface to the auditory periphery model developed by the Bruce, Zilany, and Carney labs. The model simulates spike train responses in auditory nerve fibers with detailed physiological realism.

It is implemented in C++ with pybind11. All dependencies on Matlab have been removed, making it fully standalone and suitable for Python-based environments. In general, the library should have feature-parity with the original source, but the code should be considerably faster to execute.


🧠 Model Background

This code is based on:

  • Bruce, I. C., Erfani, Y., & Zilany, M. S. A. (2018)
    A phenomenological model of the synapse between the inner hair cell and auditory nerve: Implications of limited neurotransmitter release sites.
    Hearing Research, 360:40–54.

  • Bruce, I., Buller, A., & Zilany, M. (2023)
    Modeling of auditory nerve fiber input/output functions near threshold.
    Acoustics 2023, Sydney, Australia.

📢 Please cite both of the above if you publish research using this model or a modified version.


🚀 Getting Started

1. Install prerequisites

You need a working C++14 compiler and Python 3.9+. Use a virtual environment if needed.

2. Clone and install

git clone https://github.com/jacobdenobel/brucezilany.git
cd brucezilany
pip install .

For development mode:

pip install -e .

Install from PyPi

Alternatively, you can also install the package from pip, if you want to include it as dependency.

pip install brucezilany

🧪 Example Usage

import numpy as np
from brucezilany import inner_hair_cell, synapse, stimulus, map_to_synapse

# Generate a stimulus
stim = stimulus.ramped_sine_wave(
    duration=0.05,
    simulation_duration=0.1,
    sampling_rate=100000,
    rt=0.005,
    delay=0.01,
    f0=1000,
    db=65
)

# IHC response
ihc_output = inner_hair_cell(stim, cf=1000, n_rep=10)

# Intermediate mapper. In the orginal Matlab, this was part of the synapse function. 
# Here, it is separate, and needs to be called before synapse.
mapped_ihc = map_to_synapse(
    ihc_output=ihc_output,
    spontaneous_firing_rate=100,
    characteristic_frequency=1000,
    time_resolution=stim.time_resolution,
)

# Synapse response
out = synapse(
    amplitude_ihc=mapped_ihc,
    cf=1000,
    n_rep=10,
    n_timesteps=stim.n_simulation_timesteps,
    spontaneous_firing_rate=100
)

print("Mean firing rate:", np.mean(out.mean_firing_rate))

See examples/ for more. These contain Python translations of the Matlab test files contained in the original source.


⚙️ Model Components

inner_hair_cell

Simulates the receptor potential of an inner hair cell (IHC) in response to acoustic stimuli. Includes cochlear filtering and nonlinear transduction.

Args:

  • stimulus: Stimulus object
  • cf: characteristic frequency (Hz)
  • n_rep: number of stimulus repetitions
  • cohc: normal ohc function (float)
  • cihc: normal ihc function (float)
  • species: Species enum

Returns:

  • IHC output as a vector (float)

map_to_synapse

In the original Matlab source, this was included in the synapse function. However, since you sometimes want to call synapse for a number of trails, see for example test_adaptive_redocking.py, you don't always need to recompute this function. Therefore, in this code, it is separate, and you call this outside of calling synapse. The function applies a mapping function to the output of inner_hair_cell, by default a SOFTPLUS function.

Args:

  • ihc_output: array of floats
  • spontaneous_firing_rate: spontaneous firing rate of the fiber
  • characteristic_frequency: characteristic frequency
  • time_resolution: 1 / sampling rate
  • mapping_function: SynapseMapping enum

Returns:

  • mapped IHC output as a vector (float)

synapse

Simulates stochastic spike generation at the IHC-ANF synapse, using a 4-site vesicle model with adaptive redocking and realistic refractory behavior. Note that you can provide an optional seeded RNG. This is important, because otherwise this model will produce a deterministic output. Alternatively, calling brucezilany.set_seed(<int>) before calling synapse, also make this function behave randomly. Again, see test_adaptive_redocking.py for an example.

Args:

  • amplitude_ihc: IHC potential vector
  • cf: characteristic frequency (Hz)
  • n_rep: number of stimulus repetitions
  • n_timesteps: number of stimulus time steps
  • time_resolution: 1 / sampling rate
  • spontaneous_firing_rate: in spikes/s
  • noise: random noise mode (NoiseType)
  • pla_impl: power-law adaptation method (PowerLaw)
  • spontaneous_firing_rate: spontaneous firing rate of the fiber
  • abs_refractory_period: absolute refractory period
  • rel_refractory_period: relative refractory period
  • rng: optional seeded RNG

Returns:

  • SynapseOutput object with PSTH, spike times, and statistics

🎧 Stimulus Handling

The brucezilany.stimulus module provides tools for generating and loading stimuli with precise control over sampling rate, duration, delay, and amplitude. This ensures accurate modeling of auditory nerve responses to various acoustic signals.

📦 Stimulus Class

Stimuli are represented as Stimulus objects that encapsulate both the waveform and simulation parameters.

from brucezilany import stimulus

# Create a sine wave burst with a ramped onset/offset
stim = stimulus.ramped_sine_wave(
    duration=0.05,              # duration of tone burst (s)
    simulation_duration=0.1,    # total simulation time (s)
    sampling_rate=100_000,      # sampling rate (Hz)
    rt=2.5e-3,                  # rise/fall time (s)
    delay=25e-3,                # delay before tone onset (s)
    f0=5000,                    # frequency (Hz)
    db=60.0                     # SPL (dB)
)

You can inspect:

print("Stimulus duration:", stim.stimulus_duration)
print("Sampling rate:", stim.sampling_rate)
print("Samples:", stim.data.shape)

📂 Load from File

You can also load .wav files (e.g., speech or natural sounds):

stim = stimulus.from_file("data/defineit.wav", verbose=False)

By default, this:

  • Resamples to 100 kHz
  • Normalizes to 65 dB SPL
  • Pads with silence to match a simulation time of 1s

📐 Normalization

If you want to adjust the dB level of a stimulus manually:

stimulus.normalize_db(stim, stim_db=70)

🧰 Additional Tools

Neurogram class

Multi-threaded simulation manager for full neurograms across CFs and fiber types.

from brucezilany import Neurogram

ng = Neurogram(n_cf=50, n_low=5, n_med=5, n_high=10)
ng.create(sound_wave=stim, species=Species.HUMAN_SHERA, n_trials=3)

output = ng.get_output()  # 3D array: [fiber, trial, time]

🛠 Refactoring & Enhancements

Compared to the original code, the following major changes were made:

  • ✅ All Matlab dependencies removed

    • C++ replacements for resample, randn, etc.
    • Fully standalone backend
  • ✅ Modern C++14 style

    • No new/delete, safer memory via STL containers
    • Cleaner APIs and encapsulation
  • ✅ Modular structure

    • Split between IHC, map_to_synapse, synapse
  • ✅ Python bindings via pybind11

    • Fully exposed enums, structured output objects
  • ✅ Multi-threading support

    • Neurogram uses parallel processing for simulating many CF/fiber combinations

The original Matlab code can be found here. A reference to the code use to build this repository is included as a .zip file in the data/ folder.


🧠 References

Additional foundational papers:

  • Zilany, M. S. A., Bruce, I. C., & Carney, L. H. (2014). Updated parameters and expanded simulation options for a model of the auditory periphery. JASA, 135(1):283–286.

  • Zilany, M. S. A., Bruce, I. C., Nelson, P. C., & Carney, L. H. (2009). A phenomenological model of the synapse between the inner hair cell and auditory nerve: Long-term adaptation with power-law dynamics. JASA, 126(5):2390–2412.


📬 Contact

Questions or contributions? Open a GitHub issue or pull request.

Metadata

Release files for brucezilany 0.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brucezilany 0.0.6
File Size Uploaded Provenance Actions
brucezilany-0.0.6.tar.gz 54.8 kB With provenance Details for brucezilany-0.0.6.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for brucezilany 0.0.6
File Actions
brucezilany-0.0.6-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for brucezilany-0.0.6-cp312-cp312-win_amd64.whl
brucezilany-0.0.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.17+ x86-64 Details for brucezilany-0.0.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
brucezilany-0.0.6-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for brucezilany-0.0.6-cp311-cp311-win_amd64.whl
brucezilany-0.0.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.17+ x86-64 Details for brucezilany-0.0.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
brucezilany-0.0.6-cp310-cp310-win_amd64.whl CPython 3.10 CPython 3.10 Windows x86-64 Details for brucezilany-0.0.6-cp310-cp310-win_amd64.whl
brucezilany-0.0.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.17+ x86-64 Details for brucezilany-0.0.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
brucezilany-0.0.6-cp39-cp39-win_amd64.whl CPython 3.9 CPython 3.9 Windows x86-64 Details for brucezilany-0.0.6-cp39-cp39-win_amd64.whl
brucezilany-0.0.6-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.17+ x86-64 Details for brucezilany-0.0.6-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Total release size: 3.0 MB

Release files / brucezilany-0.0.6.tar.gz

Download URL brucezilany-0.0.6.tar.gz
Size 54.8 kB
Tags Source
SHA-256 checksum
How to use checksums
b50dad73312603722cb06f3d28d3b4941ae8ea4909900ed1402dd07e7fb8d366
BLAKE2b-256 checksum
How to use checksums
5065278a5c1a2206fd9b7f163a8470144103da2c3a621f66c82903f89462a42c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp312-cp312-win_amd64.whl

Download URL brucezilany-0.0.6-cp312-cp312-win_amd64.whl
Size 211.8 kB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
6e6529c8a911bb72e2038450ee31ffceaef17432e6291909ae499e17a59ff426
BLAKE2b-256 checksum
How to use checksums
2773b8daa1b4c63f56a0ad44ad095ef80e01a3cd5f487071120015a08c9b29bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL brucezilany-0.0.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 512.5 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
45d92facf3be3933ee6703b69725bcc960e778fc558319ecbdf489ebe126270b
BLAKE2b-256 checksum
How to use checksums
19389cea8d9a18c9ccc88d5a295ae03f0f03a511e2500171359cc691d8f87926
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp311-cp311-win_amd64.whl

Download URL brucezilany-0.0.6-cp311-cp311-win_amd64.whl
Size 209.2 kB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
6742a12fdc90b951a3f258588d16c797d73bd71769dd249de5273412dad01838
BLAKE2b-256 checksum
How to use checksums
d7e89c30c639280f2e7d7eccaac38a1d349c7c75eafe92996a441a6a391c561a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL brucezilany-0.0.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 518.1 kB
Tags CPython 3.11 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
3e4097e6d146569c6fcb2d72bade7811d6779ecb3ba25fd7710c1f8122aa8d44
BLAKE2b-256 checksum
How to use checksums
730a0c38d033e50ceffdc3e1c831290e48500178bcf420ef049fd833f004d2cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp310-cp310-win_amd64.whl

Download URL brucezilany-0.0.6-cp310-cp310-win_amd64.whl
Size 208.3 kB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
da17485f9bc370efbc2d83ebd590113ac7a38bb3528de0f93af442078636ea00
BLAKE2b-256 checksum
How to use checksums
57a1abfa9ae615e329edf02cf634c1a1243f63c07d3b6ca1fafc392fe5f5e2ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL brucezilany-0.0.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 515.4 kB
Tags CPython 3.10 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
b486aaded12db45486d0b9a472804eb5df85e06d261f7fa438a705544cd16372
BLAKE2b-256 checksum
How to use checksums
76688c45f5762e39b018cb8a96e6757d097280b9f3d1db4eeb0974e1c51e4d1a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp39-cp39-win_amd64.whl

Download URL brucezilany-0.0.6-cp39-cp39-win_amd64.whl
Size 220.2 kB
Tags CPython 3.9 Windows x86-64
SHA-256 checksum
How to use checksums
6c1397ec84c063783fb491f38904996a116cc52cd37e866e140b455b63c07645
BLAKE2b-256 checksum
How to use checksums
a6666b2c7798e9c786d3fdcbaea864a0bd4e523b25ddf744322eb568bf1ebadf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / brucezilany-0.0.6-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL brucezilany-0.0.6-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 515.8 kB
Tags CPython 3.9 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
a9479b03b633da0f67f38d077bfddf7b1d40110c3ec2617e0b331b0dabed6d7c
BLAKE2b-256 checksum
How to use checksums
7c1bb5f49bd979f66cc3d2f2ceda7eea945086b156a774cdf2ea5249e60f86d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for brucezilany 0.0.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 9 files in this release have been uploaded with provenance metadata.

Select from 9 files

Attestation for brucezilany-0.0.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page