|
| 1 | + |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +# EARNET - Neurogram Emulator |
| 6 | +The Estimation of Auditory Representations Network (EARNET): a Neural Network Approximation to the Auditory Periphery Model |
| 7 | + |
| 8 | +## Overview |
| 9 | +EARNET produces multiple auditory representations, specifically inner hair cell voltages in the formof a IHCogram, and synaptic firing rates in the form of Neurogram. Additionally, EARNET takes as input an audiogram at runtime, corresponding to specific hearing impairment. The input to the model is an acoustic waveform, sampled at 16 kHz (focused on speech inputs). This code runs a neural network-based joint IHC/Neurogram emulator based of cochlear filtering and hair-cell transduction stages of the Zilany & Bruce auditory model (J. Acoust. Soc. Am. 120(3), 1446–1466, 2006). |
| 10 | + |
| 11 | +## Citation |
| 12 | +When using the EARNET auditory model, please cite the following paper: |
| 13 | +Placeholder for paper or zenodo reference here. |
| 14 | + |
| 15 | +## Installation and User Documentation |
| 16 | +The code requires Python 3.8 and Tensorflow 2.13. The required conda environment is described in the file 'earnet.yaml', |
| 17 | +and can be created using the following command: |
| 18 | +conda env create -f earnet.yaml |
| 19 | + The required conda environment is described in the file 'earnet.yaml' for linux. The linux and Windows (WSL2) install instructions assume use of NVDIA GPU. |
| 20 | + |
| 21 | +### Linux |
| 22 | +```conda env create -f earnet.yaml``` |
| 23 | +### Mac OS (Apple Silicon) |
| 24 | +```conda env create -f earnet-mac.yaml``` |
| 25 | + |
| 26 | +### Windows (WSL2) |
| 27 | + |
| 28 | +``` |
| 29 | +sudo apt update && sudo apt -y upgrade |
| 30 | +sudo apt -y install wget git build-essential |
| 31 | +
|
| 32 | +# Download latest Miniforge installer for Linux (arm64 if on Apple Silicon; x86_64 for WSL on PC) |
| 33 | +wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh |
| 34 | +
|
| 35 | +# Make it executable |
| 36 | +chmod +x Miniforge3-Linux-x86_64.sh |
| 37 | +
|
| 38 | +# Run installer |
| 39 | +./Miniforge3-Linux-x86_64.sh |
| 40 | +
|
| 41 | +# create conda env |
| 42 | +conda env create -f earnet-wsl2.yaml |
| 43 | +conda activate earnet |
| 44 | +
|
| 45 | +# ----- CUDA 11.8 (WSL) ----- |
| 46 | +# From NVIDIA's CUDA on WSL instructions (add repo and install): |
| 47 | +# (If you've installed other CUDA versions before, purge them first.) |
| 48 | +wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb |
| 49 | +sudo dpkg -i cuda-keyring_1.1-1_all.deb |
| 50 | +sudo apt update && sudo apt -y upgrade |
| 51 | +sudo apt -y install cuda-toolkit-11-8 |
| 52 | +sudo apt install -y cuda-compiler-11-8 # smaller |
| 53 | +# (or) sudo apt install -y cuda-11-8 # full toolkit including samples |
| 54 | +
|
| 55 | +# Ensure the tools are on PATH |
| 56 | +echo 'export CUDA_HOME=/usr/local/cuda-11.8' | sudo tee /etc/profile.d/cuda.sh |
| 57 | +echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' | sudo tee -a /etc/profile.d/cuda.sh |
| 58 | +source /etc/profile.d/cuda.sh |
| 59 | +
|
| 60 | +# Verify ptxas |
| 61 | +which ptxas |
| 62 | +ptxas --version |
| 63 | +
|
| 64 | +# Verify nvcc (optional) |
| 65 | +nvcc --version |
| 66 | +apt install sox |
| 67 | +``` |
| 68 | + |
| 69 | +## Usage |
| 70 | + |
| 71 | +The main script for running the system is ‘run_emulator.py’. The command-line arguments are: |
| 72 | + |
| 73 | +-f : specify an individual audio file to process |
| 74 | + |
| 75 | +-l : process the content of a list of audio files |
| 76 | + |
| 77 | +-d : the output directory to which output files are written (default : ‘processed’) |
| 78 | + |
| 79 | +-s : the sound pressure level, in dB, at which to process the signal |
| 80 | + |
| 81 | +-a : the audiogram corresponding to the auditory system to emulate, saved as a .csv file |
| 82 | + |
| 83 | +-c : the channel to process (for audio files with multiple channels) |
| 84 | + |
| 85 | +-v : model version to use; 1 designates the large EARNET model with 4.4M parameters, and 2 designates the small model with 1.4M parameters |
| 86 | + |
| 87 | +The system outputs a matlab .mat file for each input audio file that is processed. If the input audio file contains multiple channels, |
| 88 | +a separate .mat file for each, with the '_ch<x>.mat' extension used to denote input channel 'x'. The output .mat files contain 3 variables: |
| 89 | + |
| 90 | +1) 'waveform' : the waveform from the input audio file |
| 91 | + |
| 92 | +2) 'ihc' : the 80-channel approximated IHCogram, generated by the emulator |
| 93 | + |
| 94 | +3) 'ngram' : the 80-channel approximated Neurogram, generated by the emulator |
| 95 | + |
| 96 | + |
| 97 | +## Distribution Statement |
| 98 | +DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited. This material is based upon work supported by the Department of the Army under Air Force Contract No. FA8702-15-D-0001 or FA8702-25-D-B002. Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Department of the Army. © 2025 Massachusetts Institute of Technology. |
| 99 | + |
| 100 | +Subject to FAR52.227-11 Patent Rights - Ownership by the contractor (May 2014) |
| 101 | +The software/firmware is provided to you on an As-Is basis |
| 102 | + |
| 103 | +Delivered to the U.S. Government with Unlimited Rights, as defined in DFARS Part 252.227-7013 or 7014 (Feb 2014). Notwithstanding any copyright notice, U.S. Government rights in this work are defined by DFARS 252.227-7013 or DFARS 252.227-7014 as detailed above. Use of this work other than as specifically authorized by the U.S. Government may violate any copyrights that exist in this work. |
0 commit comments