Merge pull request #1770 from ArmDeveloperEcosystem/main

Production update

Author: jasonrandrews

.gitignore

@@ -14,4 +14,10 @@ startup.sh
 nohup.out
 
 venv/
-z_local_saved/
+z_local_saved/
+/.idea/
+/tools/.python-version
+/.python-version
+*.iml
+*.xml
+

.wordlist.txt

@@ -3872,3 +3872,48 @@ upscales
 upscaling
 vl
 webbot
+APKs
+ASR's
+DLRM
+DLRMv
+DeepSeek
+Geremy
+MERCHANTABILITY
+MLPerf’s
+MoE
+NONINFRINGEMENT
+NaN
+OCPU
+OCaml
+Ollama
+Ollama's
+Prefill
+Unsloth’s
+YAMLs
+Yiyang
+bartowski
+bc
+checkboxes
+deepseek
+diy
+fenv
+gguf
+highmem
+inria
+lfs
+lora
+ollama
+opam
+perceptrons
+personalization
+rclone
+screenspace
+significand
+stdbuf
+sublicense
+tok
+truncations
+ulp
+unmangled
+unportable
+zeropoint

assets/contributors.csv

@@ -47,7 +47,7 @@ Alaaeddine Chakroun,Day Devs,Alaaeddine-Chakroun,alaaeddine-chakroun,,https://da
 Koki Mitsunami,Arm,,kmitsunami,,
 Chen Zhang,Zilliz,,,,
 Tianyu Li,Arm,,,,
-Georgios Mermigkis,VectorCamp,gMerm,georgios-mermigkis,,https://vectorcamp.gr/ 
+Georgios Mermigkis,VectorCamp,gMerm,georgios-mermigkis,,https://vectorcamp.gr/
 Ben Clark,Arm,,,,
 Han Yin,Arm,hanyin-arm,nacosiren,,
 Willen Yang,Arm,,,,
@@ -80,3 +80,5 @@ Tom Pilar,,,,,
 Cyril Rohr,,,,,
 Odin Shen,Arm,odincodeshen,odin-shen-lmshen,,
 Avin Zarlez,Arm,AvinZarlez,avinzarlez,,https://www.avinzarlez.com/
+Shuheng Deng,Arm,,,,
+Yiyang Fan,Arm,,,,

content/learning-paths/cross-platform/floating-point-rounding-errors/_index.md

@@ -0,0 +1,56 @@
+---
+title: Learn about floating point rounding on Arm
+
+draft: true
+cascade:
+    draft: true
+
+minutes_to_complete: 30
+
+who_is_this_for: Developers porting applications from x86 to Arm who observe different floating point values on each platform.
+
+learning_objectives: 
+    - Understand the differences between floating point numbers on x86 and Arm. 
+    - Understand factors that affect floating point behavior.
+    - How to use compiler flags to produce predictable behavior.
+
+prerequisites:
+    - Access to an x86 and an Arm Linux machine.
+    - Basic understanding of floating point numbers.
+
+author: Kieran Hejmadi
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Cortex-A
+    - Neoverse
+tools_software_languages:
+    - C++
+operatingsystems:
+    - Linux
+shared_path: true
+shared_between:
+    - servers-and-cloud-computing
+    - laptops-and-desktops
+    - mobile-graphics-and-gaming
+
+further_reading:
+    - resource:
+        title: G++ Optimisation Flags 
+        link: https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html
+        type: documentation
+    - resource:
+        title: Floating-point environment
+        link: https://en.cppreference.com/w/cpp/numeric/fenv
+        type: documentation
+
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/embedded-and-microcontrollers/llm-fine-tuning-for-mobile-applications/_next-steps.md renamed to content/learning-paths/cross-platform/floating-point-rounding-errors/_next-steps.md

@@ -0,0 +1,41 @@
+---
+title: Floating Point Representations
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Review of floating point numbers
+
+If you are unfamiliar with floating point number representation, you can review [Learn about integer and floating-point conversions](/learning-paths/cross-platform/integer-vs-floats/introduction-integer-float-types/). It covers different data types and explains data type conversions.
+
+Floating-point numbers are a fundamental representation of real numbers in computer systems, enabling efficient storage and computation of decimal values with varying degrees of precision. In C/C++, floating point variables are created with keywords such as  `float` or `double`. The IEEE 754 standard, established in 1985, is the most widely used format for floating-point arithmetic, ensuring consistency across different hardware and software implementations.
+
+IEEE 754 defines two primary formats: single-precision (32-bit) and double-precision (64-bit). 
+
+Each floating-point number consists of three components: 
+- **sign bit**. (Determining positive or negative value)
+- **exponent** (defining the scale or magnitude)
+- **significand** (also called the mantissa, representing the significant digits of the number). 
+
+The standard uses a biased exponent to handle both large and small numbers efficiently, and it incorporates special values such as NaN (Not a Number), infinity, and subnormal numbers for robust numerical computation. A key feature of IEEE 754 is its support for rounding modes and exception handling, ensuring predictable behavior in mathematical operations. However, floating-point arithmetic is inherently imprecise due to limited precision, leading to small rounding errors.
+
+The graphic below illustrates various forms of floating point representation supported by Arm, each with varying number of bits assigned to the exponent and mantissa.
+
+![floating-point](./floating-point-numbers.png)
+
+## Rounding errors 
+
+Since computers use a finite number of bits to store a continuous range of numbers, rounding errors are introduced. The unit in last place (ULP) is the smallest difference between two consecutive floating-point numbers. It measures floating-point rounding error, which arises because not all real numbers can be exactly represented. 
+
+When an operation is performed, the result is rounded to the nearest representable value, introducing a small error. This error, often measured in ULPs, indicates how close the computed value is to the exact result. For a simple example, if a floating-point schema with 3 bits for the mantissa (precision) and an exponent in the range of -1 to 2 is used, the possible values are represented in the graph below. 
+
+![ulp](./ulp.png)
+
+Key takeaways:
+
+- ULP size varies with the number’s magnitude.
+- Larger numbers have bigger ULPs due to wider spacing between values.
+- Smaller numbers have smaller ULPs, reducing quantization error.
+- ULP behavior impacts numerical stability and precision in computations.

content/learning-paths/cross-platform/floating-point-rounding-errors/differences.png

@@ -0,0 +1,123 @@
+---
+title: Differences between x86 and Arm
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## What are the differences in behavior between x86 and Arm floating point?
+
+Architecture and standards define floating point overflows and truncations in different ways. 
+
+You can see this by comparing an example application on an x86 and an Arm Linux system. 
+
+You can use any Linux systems for this example. If you are using AWS, you can use EC2 instance types
+`t3.micro` and `t4g.small` running Ubuntu 24.04.
+
+To learn about floating point differences, use an editor to copy and paste the C++ code below into a new file named `converting-float.cpp`.
+
+```cpp
+#include <iostream>
+#include <cmath>
+#include <limits>
+#include <cstdint>
+
+void convertFloatToInt(float value) {
+    // Convert to unsigned 32-bit integer
+    uint32_t u32 = static_cast<uint32_t>(value);
+
+    // Convert to signed 32-bit integer
+    int32_t s32 = static_cast<int32_t>(value);
+
+    // Convert to unsigned 16-bit integer (truncation happens)
+    uint16_t u16 = static_cast<uint16_t>(u32); 
+    uint8_t u8 = static_cast<uint8_t>(value); 
+
+    // Convert to signed 16-bit integer (truncation happens)
+    int16_t s16 = static_cast<int16_t>(s32);
+
+    std::cout << "Floating-Point Value: " << value << "\n";
+    std::cout << "  → uint32_t:  " << u32 << " (0x" << std::hex << u32 << std::dec << ")\n";
+    std::cout << "  → int32_t:   " << s32 << " (0x" << std::hex << s32 << std::dec << ")\n";
+    std::cout << "  → uint16_t (truncated):  " << u16 << " (0x" << std::hex << u16 << std::dec << ")\n";
+    std::cout << "  → int16_t (truncated):   " << s16 << " (0x" << std::hex << s16 << std::dec << ")\n";
+    std::cout << "  → uint8_t (truncated):   " << static_cast<int>(u8) << std::endl;
+
+    std::cout << "----------------------------------\n";
+}
+
+int main() {
+    std::cout << "Demonstrating Floating-Point to Integer Conversion\n\n";
+
+    // Test cases
+    convertFloatToInt(42.7f);                   // Normal case
+    convertFloatToInt(-15.3f);                  // Negative value -> wraps on unsigned
+    convertFloatToInt(4294967296.0f);           // Overflow: 2^32 (UINT32_MAX + 1)
+    convertFloatToInt(3.4e+38f);                // Large float exceeding UINT32_MAX
+    convertFloatToInt(-3.4e+38f);               // Large negative float
+    convertFloatToInt(NAN);                     // NaN behavior on different platforms
+    return 0;
+}
+```
+
+If you need to install the `g++` compiler, run the commands below. 
+
+```bash
+sudo apt update
+sudo apt install g++  -y
+```
+
+Compile `converting-float.cpp` on an Arm and x86 machine. 
+
+The compile command is the same on both systems.
+
+```bash
+g++ converting-float.cpp -o converting-float 
+```
+
+For easy comparison, the image below shows the x86 output (left) and Arm output (right). The  highlighted lines show the difference in output. 
+
+![differences](./differences.png)
+
+As you can see, there are several cases where different behavior is observed. For example when trying to convert a signed number to a unsigned number or dealing with out-of-bounds numbers. 
+
+## Removing hardcoded values with macros
+
+The above differences show that explicitly checking for specific values will lead to unportable code. 
+
+For example, consider the function below. The code checks if the value is 0. The value an x86 machine will convert a floating point number that exceeds the maximum 32-bit float value. This is different from Arm behavior leading to unportable code. 
+
+```cpp
+void checkFloatToUint32(float num) {
+    uint32_t castedNum = static_cast<uint32_t>(num);
+    if (castedNum == 0) {
+        std::cout << "The casted number is 0, indicating the float could out of bounds for uint32_t." << std::endl;
+    } else {
+        std::cout << "The casted number is: " << castedNum << std::endl;
+    }
+}
+```
+
+This can simply be corrected by using the macro, `UINT32_MAX`. 
+
+{{% notice Note %}} 
+To find out all the available compiler-defined macros, you can output them using:
+```bash
+echo "" | g++ -dM -E -
+```
+{{% /notice %}}
+
+A portable version of the code is:
+
+```cpp
+void checkFloatToUint32(float num) {
+    uint32_t castedNum = static_cast<uint32_t>(num);
+    if (castedNum == UINT32_MAX) {
+        std::cout << "The casted number is " << UINT32_MAX <<  " indicating the float was out of bounds for uint32_t." << std::endl;
+    } else {
+        std::cout << "The casted number is: " << castedNum << std::endl;
+    }
+}
+```
+

content/learning-paths/cross-platform/floating-point-rounding-errors/floating-point-numbers.png

@@ -0,0 +1,79 @@
+---
+title: Error propagation
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## What is error propagation in x86 and Arm systems?
+
+One cause of different outputs between x86 and Arm stems from the order of instructions and how errors are propagated. As a hypothetical example, an Arm system may decide to reorder the instructions that each have a different rounding error so that subtle changes are observed. 
+
+It is possible that 2 functions that are mathematically equivalent will propagate errors differently on a computer. 
+
+ Functions `f1` and `f2` are mathematically equivalent. You would expect them to return the same value given the same input. 
+ 
+ If the input is a very small number, `1e-8`, the error is different due to the loss in precision caused by different operations. Specifically, `f2` avoids the subtraction of nearly equal number. For a full description look into the topic of [numerical stability](https://en.wikipedia.org/wiki/Numerical_stability). 
+
+Use an editor to copy and paste the C++ code below into a file named `error-propagation.cpp`. 
+
+```cpp
+#include <stdio.h>
+#include <math.h>
+
+// Function 1: Computes sqrt(1 + x) - 1 using the naive approach
+float f1(float x) {
+    return sqrtf(1 + x) - 1;
+}
+
+// Function 2: Computes the same value using an algebraically equivalent transformation
+// This version is numerically more stable
+float f2(float x) {
+    return x / (sqrtf(1 + x) + 1);
+}
+
+int main() {
+    float x = 1e-8;  // A small value that causes floating-point precision issues
+    float result1 = f1(x);
+    float result2 = f2(x);
+
+    // Theoretically, result1 and result2 should be the same
+    float difference = result1 - result2;
+    // Multiply by a large number to amplify the error
+    float final_result = 100000000.0f * difference + 0.0001f;
+
+    // Print the results
+    printf("f1(%e) = %.10f\n", x, result1);
+    printf("f2(%e) = %.10f\n", x, result2);
+    printf("Difference (f1 - f2) = %.10e\n", difference);
+    printf("Final result after magnification: %.10f\n", final_result);
+
+    return 0;
+}
+```
+
+Compile the code on both x86 and Arm with the following command.
+
+```bash
+g++ -g error-propagation.cpp -o error-propagation
+```
+
+Running the 2 binaries shows that the second function, `f2`, has a small rounding error on both architectures. Additionally, there is a further rounding difference when run on x86 compared to Arm.
+
+Running on x86:
+
+```output
+f1(1.000000e-08) = 0.0000000000
+f2(1.000000e-08) = 0.0000000050
+Difference (f1 - f2) = -4.9999999696e-09
+Final result after magnification: -0.4999000132
+```
+
+Running on Arm:
+```output
+f1(1.000000e-08) = 0.0000000000
+f2(1.000000e-08) = 0.0000000050
+Difference (f1 - f2) = -4.9999999696e-09
+Final result after magnification: -0.4998999834
+```