TIP-697: Migrate Floating-Point Calculations from Math to StrictMath

[halibobo1205]

tip: 697
title: Migrate Floating-Point Calculations from Math to StrictMath	
author: halibobo1205@gmail.com
discussions to: https://github.com/tronprotocol/TIPs/issues/697
status: Draft
type: Standards Track
category: Core
created: 2024-10-30

Simple Summary

   This TIP proposes migrating Java-Tron's floating-point calculation library from java.lang.Math to java.lang.StrictMath while keeping data consistent and preparing for future JDK version upgrades and multi-platform support.

Motivation

   Up to GreatVoyage-v4.7.6(Anaximander), Java-Tron has utilized the class Math for floating-point calculations. However, the class Math may yield varying calculation results for identical inputs across different hardware platforms and JDK versions. As Java-Tron's released versions have exclusively supported JDK8 and x86 environments, data inconsistency issues related to the class Math have not yet emerged.
   Looking ahead to potential cross-platform support and broader JDK version compatibility, Java-Tron needs to transition from java.lang.Math to a mathematical library that ensures consistent calculation results across platforms and newer JDK versions.
   This TIP also examines maintaining data consistency throughout the TRON network during the migration process without impacting consensus dating back to the genesis block.

Specification

   As noted above, the class java.lang.Math may produce different calculation results across platforms and multiple JDK versions. Although this hasn't affected Java-Tron's data consistency due to limited platform and JDK version support, replacing the java.lang.Math class is essential for future cross-platform and multi-JDK version support.
   According to Java's official documentation, class java.lang.StrictMath provides the equivalent functions of class java.lang.Math can produce the same results across different hardware platforms and the JDK versions. This makes java.lang.StrictMath is an ideal replacement for the java.lang.Math class in this scenario.
   Hence, we propose implementing a uniform replacement of the java.lang.Math class with java.lang.StrictMath class throughout Java-Tron via this proposal.
   It's important to note that the java.lang.StrictMath class may exhibit slight variations in calculation results compared to the java.lang.Math library in certain scenarios. This TIP will list all relevant differences in Java-Tron and analyze their potential impact on consensus. Any changes affecting consensus will only be implemented network-wide after proposal approval, ensuring the Math class migration does not compromise data consistency.

Rationale

   StrictMath guarantees reproducible results, independent of the JDK version, hardware implementation, etc. To help ensure the portability of Java programs, the numeric functions in this class require that they produce the same results as certain published algorithms. These algorithms are available from the well-known network library Netlib as the package "Freely Distributable Math Library."
   Key differences between Math and StrictMath:

• Determinism:
  • StrictMath guarantees reproducible results across all platforms
  • Math may use platform-specific optimizations for better performance
• Performance:
  • Math is generally faster as it can use platform-specific implementations
  • StrictMath might be slightly slower but provides better reproducibility
• Usage considerations:
  • Use StrictMath when you need exact reproducibility across different platforms
  • Use Math when performance is more important than exact reproducibility
  • The numerical differences between Math and StrictMath results are usually very small

Backwards Compatibility

   Since consensus-affecting changes will only be activated post-proposal approval, this migration maintains backward compatibility and preserves consensus from the genesis block onward.

Implementation

Stage 1

   Migrate the pow operation from java.lang.Math to java.lang.StrictMath will be activated by proposal No 87 in this PR:

• feat(math): migrate pow operation from java.lang.Math to java.lang.StrictMath java-tron#6098.

Stage 2

   Migrate all other operations from java.lang.Math to java.lang.StrictMath.

Currently, Tron uses Math in the following methods, and after analyzing the results of the calculations, there is no problem replacing it with StrictMath.

Function	Purpose	Math vs StrictMath Difference	Explanation
addExact	Performs exact integer addition, throws ArithmeticException on overflow	No difference	Identical implementation
subtractExact	Performs exact integer subtraction, throws ArithmeticException on overflow	No difference	Identical implementation
multiplyExact	Performs exact integer multiplication, throws ArithmeticException on overflow	No difference	Identical implementation
floorDiv	Returns the largest integer less than or equal to the algebraic quotient	No difference	Identical implementation
max	Returns the greater of two values	No difference	Identical implementation
min	Returns the smaller of two values	No difference	Identical implementation
signum	Returns the signum function of the argument	No difference	Identical implementation
round	Returns the closest long value to the argument	No difference	Identical implementation
abs	Returns the absolute value of the argument	No difference	Identical implementation
random	Returns a pseudorandom double value between 0.0 and 1.0	Not applicable	Identical implementation
ceil	Returns the smallest double value greater than or equal to the argument and is equal to a mathematical integer	No difference	Identical implementation
pow	Returns the first argument raised to the power of the second argument	Different	Math may use hardware instructions, StrictMath uses fdlibm

[angrynurd]

This TIP will list all relevant differences in Java-Tron and analyze their potential impact on consensus. Any changes affecting consensus will only be implemented network-wide after proposal approval, ensuring the Math class migration does not compromise data consistency.

Could you make the above descriptions clearer? eg: what kind of potential impacts it will have when this proposal is approved?

[tomatoishealthy]

It's important to note that the java.lang.StrictMath class may exhibit slight variations in calculation results compared to the java.lang.Math library in certain scenarios. This TIP will list all relevant differences in Java-Tron and analyze their potential impact on consensus. Any changes affecting consensus will only be implemented network-wide after proposal approval, ensuring the Math class migration does not compromise data consistency.

Can you show which modules will be affected?

So that the community can confirm whether the change will affect their own interests

[halibobo1205]

Currently the Bancor trading and DynamicEnergy are known to use the math.pow method for floating point calculations. @endiaoekoe @tomatoishealthy

[lxcmyf]

In Java, certain methods in the Math and StrictMath classes may produce inconsistent results, especially when dealing with floating-point arithmetic. This arises because the Math class can utilize platform-specific optimizations, whereas the StrictMath class strictly adheres to the IEEE 754 standard (officially known as IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985), also referred to as IEC 60559:1989, which is the standard for binary floating-point arithmetic in microprocessor systems). Here are some methods that may lead to inconsistent results:

1. Trigonometric functions:

• Math.sin(double a)

• Math.cos(double a)

• Math.tan(double a)

2. Inverse trigonometric functions:

• Math.asin(double a)

• Math.acos(double a)

• Math.atan(double a)

3. Exponential functions:

• Math.exp(double a)

• Math.log(double a)

• Math.log10(double a)

4. Square root function:

• Math.sqrt(double a)

5. Power function:

• Math.pow(double a, double b)

Since the methods in the StrictMath class provide precise and consistent results across different platforms, whereas the methods in the Math class may vary due to platform-specific optimizations, the return values of the two can differ in certain scenarios. The only method used in Java-tron code that may result in inconsistent calculation results is Math.pow.

[halibobo1205]

It is recommended that for future code development, if there are no special reasons to use the Math class, it is always preferred to use the StrictMath class.

[halibobo1205]

The next step to consider is to migrate directly between Math and StrictMath for computationally consistent methods without requiring a proposal.

[zoHao03]

你好，你的邮件我已经收到了。

[halibobo1205]

Migrate the pow operation from java.lang.Math to java.lang.StrictMath will be activated by proposal No 87 in this PR: tronprotocol/java-tron#6098.

[Kingcb1]

tip: 697
title: Migrate Floating-Point Calculations from Math to StrictMath	
author: halibobo1205@gmail.com
discussions to: https://github.com/tronprotocol/TIPs/issues/697
status: Draft
type: Standards Track
category: Core
created: 2024-10-30

Simple Summary

   This TIP proposes migrating Java-Tron's floating-point calculation library from java.lang.Math to java.lang.StrictMath while keeping data consistent and preparing for future JDK version upgrades and multi-platform support.

Motivation

   Up to GreatVoyage-v4.7.6(Anaximander), Java-Tron has utilized the class Math for floating-point calculations. However, the class Math may yield varying calculation results for identical inputs across different hardware platforms and JDK versions. As Java-Tron's released versions have exclusively supported JDK8 and x86 environments, data inconsistency issues related to the class Math have not yet emerged.
   Looking ahead to potential cross-platform support and broader JDK version compatibility, Java-Tron needs to transition from java.lang.Math to a mathematical library that ensures consistent calculation results across platforms and newer JDK versions.
   This TIP also examines maintaining data consistency throughout the TRON network during the migration process without impacting consensus dating back to the genesis block.

Specification

   As noted above, the class java.lang.Math may produce different calculation results across platforms and multiple JDK versions. Although this hasn't affected Java-Tron's data consistency due to limited platform and JDK version support, replacing the java.lang.Math class is essential for future cross-platform and multi-JDK version support.
   According to Java's official documentation, class java.lang.StrictMath provides the equivalent functions of class java.lang.Math can produce the same results across different hardware platforms and the JDK versions. This makes java.lang.StrictMath is an ideal replacement for the java.lang.Math class in this scenario.
   Hence, we propose implementing a uniform replacement of the java.lang.Math class with java.lang.StrictMath class throughout Java-Tron via this proposal.
   It's important to note that the java.lang.StrictMath class may exhibit slight variations in calculation results compared to the java.lang.Math library in certain scenarios. This TIP will list all relevant differences in Java-Tron and analyze their potential impact on consensus. Any changes affecting consensus will only be implemented network-wide after proposal approval, ensuring the Math class migration does not compromise data consistency.

Rationale

   StrictMath guarantees reproducible results, independent of the JDK version, hardware implementation, etc. To help ensure the portability of Java programs, the numeric functions in this class require that they produce the same results as certain published algorithms. These algorithms are available from the well-known network library Netlib as the package "Freely Distributable Math Library."
   Key differences between Math and StrictMath:

• Determinism:
  • StrictMath guarantees reproducible results across all platforms
  • Math may use platform-specific optimizations for better performance
• Performance:
  • Math is generally faster as it can use platform-specific implementations
  • StrictMath might be slightly slower but provides better reproducibility
• Usage considerations:
  • Use StrictMath when you need exact reproducibility across different platforms
  • Use Math when performance is more important than exact reproducibility
  • The numerical differences between Math and StrictMath results are usually very small

Backwards Compatibility

   Since consensus-affecting changes will only be activated post-proposal approval, this migration maintains backward compatibility and preserves consensus from the genesis block onward.

Implementation

Stage 1

   Migrate the pow operation from java.lang.Math to java.lang.StrictMath will be activated by proposal No 87 in this PR:

• feat(math): migrate pow operation from java.lang.Math to java.lang.StrictMath java-tron#6098.

Stage 2

   Migrate all other operations from java.lang.Math to java.lang.StrictMath.

[bAJWA05]

✨✨ Here's an AI-assisted sketch of how you might approach this issue saved by @bAJWA05 using Copilot Workspace v0.27

[zoHao03]

你好，你的邮件我已经收到了。