flatmax@597: Introduction

flatmax@597:

This C++ code implements Dick Lyon's CARFAC model for the peripheral hearing circuit.

flatmax@597:

flatmax@597: Philosophy of the implementation

flatmax@597:

flatmax@597: Matching the design document

flatmax@597:

As requested by the CARFAC design description, this codebase uses Eigen to compute matrix/vector operations.

flatmax@597:

flatmax@597: Object oriented acritecture

flatmax@597:

Where possible common paradigms inherit from common Objects. This aims to minimise the amount of coding required to implement and modify CARFAC. For example, the EarComponent encapsulates the CAR, AGC and IHC where all of the have the common features of Coefficients, Parameters and State.

flatmax@597:

flatmax@597: Common code

flatmax@597:

Where possible typedefs, definitions, includes and namespace inclusions which are common to the code, or usefull outside of class definitions are put in the CARFACCommon.H file.

flatmax@597:

flatmax@597: File naming convention and header guards

flatmax@597:

C++ files in this codebase are named using the .C and .H suffixes (C code uses .c and .h).

flatmax@597:

Header guards are labeled using the files name with '_' characters, for example.H would become EXAMPLE_H_.

flatmax@597:

flatmax@597: Global variables

flatmax@597:

In general the use of global variables is discouraged. Where possible the code must be instantiated many times on the same computer system and the use of global variables complicates having multiple instances of shared library classes.

flatmax@597:

flatmax@597: Class and variable naming convention

flatmax@597:

In general, classes begin with capitol letters and a variable name begis with a lower case character. The consider a class for example :

flatmax@597:

    class ForExample { class def here };
flatmax@597: 
flatmax@597:     ForExample forExample;
flatmax@597: 
flatmax@597:     class OMG { class def here };
flatmax@597: 
flatmax@597:     OMG omg; // here it is clear what is the type and what is the variable.
flatmax@597:

The class 'ForExample' is defined, and the variable name 'forExample' may be used in the code, which clearly indicates the type of the variable.

flatmax@597:

The concept of labeling variables using 'p' for pointer, and type name references is not necessary, and in some cases discouraged. Consider for example,

flatmax@597:

 float *fs 
flatmax@597:

defining the pointer to the sample rate. If we were to use

flatmax@597:

 float * pFFs // don't do this - difficult to see that pFFs references fs - the sample rate 
flatmax@597:

, it becomes rather difficult to understand that pFFs actualy points to the sample rate.

flatmax@597:

A deeper argument for using simple variable names (in C++) is as follows. Good engineers program classes and methods which are short and concise. As monitors (LCDs) get larger, most of your methods and in some cases classes are visible in one or two pages of your monitor. Consequently if the exact type of a variable named 'fs' needs to be found, it is as simple as looking at the top of your monitor or scrolling up a little to find a method's input variable name/type. In the case of class member variables, a class 'SoundCard' is expected to define a sound card. Consequently certain member variables are expected to exist, for example, fs, inputChannels, outputChannels and so on. If the actual types of these variables have been forgotten, then the header file is referenced, and this is normally as simple as a few key strokes to change from the SoundCard.C file to the SoundCard.H file to inspect the names and types of available member variables.

flatmax@597:

Copyright:

{

 Copyright 2013 Matt R. Flax <flatmax\@> All Rights Reserved.
flatmax@597: 
flatmax@597:     Author Matt Flax <flatmax@>
flatmax@597: 
flatmax@597: 
flatmax@597:     This C++ file is part of an implementation of Lyon's cochlear model:
flatmax@597: 
flatmax@597:     "Cascade of Asymmetric Resonators with Fast-Acting Compression"
flatmax@597: 
flatmax@597:     to supplement Lyon's upcoming book "Human and Machine Hearing"
flatmax@597: 
flatmax@597: 
flatmax@597:     Licensed under the Apache License, Version 2.0 (the "License");
flatmax@597: 
flatmax@597:     you may not use this file except in compliance with the License.
flatmax@597: 
flatmax@597:     You may obtain a copy of the License at
flatmax@597: 
flatmax@597: 
flatmax@597:         http://www.apache.org/licenses/LICENSE-2.0
flatmax@597: 
flatmax@597: 
flatmax@597:     Unless required by applicable law or agreed to in writing, software
flatmax@597: 
flatmax@597:     distributed under the License is distributed on an "AS IS" BASIS,
flatmax@597: 
flatmax@597:     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
flatmax@597: 
flatmax@597:     See the License for the specific language governing permissions and
flatmax@597: 
flatmax@597:     limitations under the License. 
flatmax@597:

}

flatmax@597: