Hyperbolic Tangent Activation Function in Fixed-Point Arithmetic (LUT Generator)

This tool generates lookup tables (LUT) for the hyperbolic tangent sigmoid (tansig) transfer function, optimized for fixed-point arithmetic on microcontrollers. The generated LUT provides a fast approximation of the tansig function, making it ideal for resource-constrained environments.

Key Features

• Three Output Formats:
  • C header file with LUT array and metadata.
  • Floating-point CSV data.
  • Fixed-point CSV data.
• Automatic LUT Sizing:
  • Dynamically determines the number of points needed to reach the scaling factor.
  • Includes 0 as the starting point.
• Symmetry Utilization:
  • Leverages the property tanh(-x) = -tanh(x) to minimize storage.
  • Only positive values are stored; negative values are computed by negation.
• Power-of-2 Scaling Factor Validation:
  • Ensures the scaling factor is valid for fixed-point arithmetic.
• Efficient Memory Usage:
  • LUT size adapts to the scaling factor, ensuring optimal memory usage.

Installation

Build with Cargo

cargo build --release

Build with Make (Recommended)

# Build, test, and generate the default LUT
make

# Just build the project
make build

The executable will be available at target/release/tansig-lut.

Usage

tansig-lut <SCALING_FACTOR> [OPTIONS]

Examples

tansig-lut 512
tansig-lut 1024 --output my_lut
tansig-lut 256

Required Arguments

• <SCALING_FACTOR>: Power-of-2 scaling factor for fixed-point conversion (≤ 32767 in int16).

Options

• -o, --output <DIR>: Output directory (default: writes header to stdout).
• -h, --help: Print help information.
• -v, --version: Print version information.

Makefile Usage

The Makefile provides convenient targets for common operations:

make              # Build project, run tests, and generate default LUT
make build        # Build the project
make test         # Run the test suite
make run          # Generate LUT with default parameters (scale=64)
make plot         # Create plot from generated data
make clean        # Remove generated files
make custom SCALE=256  # Generate with custom scaling factor

Output Files

When using --output <DIR>, the tool generates:

1. tansig_lut.h - C header file containing:

   • FIXED_POINT_SCALE and FIXED_POINT_SHIFT defines.
   • LUT_SIZE constant.
   • Precomputed tansig_lut array.

2. output_float.data - Floating-point (x, tansig(x)) pairs.

3. output_fixed.data - Fixed-point (x, scaled_tansig(x)) pairs.

Implementation Details

Optimized Memory Usage

• The LUT stores only positive values, starting from 0.
• For negative inputs, the result is computed by negating the corresponding positive value.
• This reduces memory usage by half while maintaining accuracy.

Dynamic Point Generation

• The LUT is generated until the result hits the scaling factor.
• The number of points is determined dynamically, ensuring optimal coverage.

Fixed-Point Conversion

fixed_value = round(tansig(x) × scaling_factor)

• The scaling factor must be a power of 2 (validated at runtime).
• Values are stored as int16_t for microcontroller compatibility.
• Shift operations use FIXED_POINT_SHIFT (number of right shifts = log2(scale)).

Precision Considerations

• Larger scaling factors provide better resolution but increase LUT size.
• The LUT size grows linearly with the scaling factor.

Mathematical Background

The hyperbolic tangent sigmoid transfer function is defined as:

tansig(n) = \frac{2}{1 + e^{-2n}} - 1

Properties

• Domain: (-∞, ∞)
• Range: (-1, 1)
• Symmetry: tansig(-x) = -tansig(x)
• Shape: Sigmoid with a linear region near the origin.

Validation & Testing

The test suite verifies:

• Core tansig implementation accuracy.
• Power-of-2 validation checks.
• Fixed-point conversion correctness.
• Boundary condition handling.
• Overflow prevention.

Run tests with:

cargo test

References

[1] MATLAB Neural Network Toolbox Transfer Functions: ResearchGate Link