3.8. Treatment of Numerical Algorithms

3.8.1. Numerical Representation

The MCAF at present utilizes only fixed-point (and not floating-point) computation. The majority of state variables and parameters are represented as Q15 fixed-point stored in a signed 16-bit number (int16_t), with a handful of 32-bit values (usually in integrators or filter state) and a few unsigned Q15 16-bit values. Some gains use other scaling factors like Q11 or variable shifts, where appropriate.

3.8.1.1. Normalization Factors

The primary normalization factors used since MCAF R3 are shown below.

quantity factor (in general) factor used with MCLV-2 factor used with MCHV (MCHV-2 and MCHV-3)
Voltage Maximum ADC input for DC link 52.8V 453.3V
Current Twice the maximum phase current measurement, which allows room for gain calibration and avoids overflow in Park and Clarke transforms, at the cost of reduced resolution on the low end. 8.8A 32.8A
Velocity 1.5 times the maximum motor speed.

3.8.2. Constants in Code

Constants found in code are sometimes considered “magic numbers” if the reason for choosing their value is unclear. We try to avoid this situation in the Motor Control Application Framework.

Constants used in the Motor Control Application Framework generally fall into one of five categories.

  1. Automatically calculated values: In the parameters/ directory, in header files or in C run-time initialization functions –- these are calculated by motorBench® Development Suite during the autotuning and code generation steps. We do not recommend changing these values manually. Where they are fixed-point integer constants, a comment generally accompanies them indicating the floating-point equivalent and the corresponding engineering value, along with quantization accuracy, for example:

    #define KIP             8696    // Q15(  0.26538) = +414.67629 mV/A     = +414.65940 mV/A    + 0.0041%
#define KII              643    // Q15(  0.01962) = +613.24024 V/A/s    = +613.20687 V/A/s   + 0.0054%

    Among many other tasks, we are working on improving the documentation within our code to clarify how these constants are calculated, or at least what factors they depend on. In some cases the calculations are proprietary formulas within motorBench® Development Suite.

  2. Part of the Hardware Abstraction Layer: In the hal/ directory. These are intended to be consistent with, and eventually replaced by, automatically-generated output from MCC.

  3. “Obvious” values in the C source files outside the parameters/ directory, including some examples shown below. In these cases, hiding them behind an abstracted symbolic constant obscures rather than clarifies their usage. If you see an example where they seem inappropriate, please bring them to our attention, and we will consider alternatives.

    • 0
    • +1 or -1 as a sign/direction value
    • maximum representative values like 0xFFFF or 0x7FFF
    • shift counts, e.g. >> 16 when converting from int32_t to int16_t, or >> N where multiplying a QN fixed-point number, and the value of N is clarified in code comments
    • array indices for unrolled loops
    • MCAF_DelayNanoseconds(500); (used to output a “short pulse” as mentioned in an accompanying comment)

  4. Hand-calculated constants with accompanying comment explaining how they were derived — these are uncommon; if any are unclear, please bring these to our attention.

  5. Legacy code constants — if for some reason you notice a constant in code that does not fall into one of the above categories, it is probably an oversight, in which case please bring it to our attention.