> On 24 Jan 2020, at 00:07, Gilles Sadowski <gillese...@gmail.com> wrote: > > Hello. > > 2020-01-24 0:30 UTC+01:00, Alex Herbert <alex.d.herb...@gmail.com > <mailto:alex.d.herb...@gmail.com>>: >> In short: >> >> - Math.hypot is required in Complex to compute sqrt(x^2 + y^2) without >> over/underflow to 1 ULP precision. >> - Complex also requires the same computation without the sqrt or >> over/underflow protection >> - I found the reference for Math.hypot and reimplemented the function >> - My port is 4x faster than Math.hypot and the same accuracy (or better) >> - I will add this as a private internal method in Complex >> - The source for the port requires the original licence is maintained >> >> The question is where to put the notice of the original license? Copying >> from commons RNG it would be in the source method javadoc and also in all >> LICENSE.txt files through the multi-module project. This seems excessive. I >> thought perhaps to include it only in numbers parent and then the complex >> module where it applies. > > IIUC, this would agree with the recommendations here: > http://www.apache.org/dev/licensing-howto.html > <http://www.apache.org/dev/licensing-howto.html> >
That talks about LICENCE in the entire product distribution. So that would be the archive available from the downloads page. Then it states the LICENSE should be at the top level of the source tree. So parent has a LICENSE that covers all the additions for each sub-module. It is not clear to me about whether all modules require the same licence. It states "LICENSE and NOTICE must exactly represent the contents of the distribution they reside in.” So I would assume each module should have a LICENSE and NOTICE that reflects its distribution which is the module jar distributed to maven. So my interpretation is to have a LICENSE and NOTICE in each module where LICENSE can reflect the specific additions for that module. The parent root directory would combine all the additions from each LICENSE in all the sub-modules. This would mean the LICENSE addition for MersenneTwister can be dropped from all the commons modules except the commons-rng-core module. Likewise I would add the short license for fdlibm to numbers in the parent dir and only in the complex module. Please let me know if you interpret this differently. > [By the way, we should perhaps remove the ".txt" suffix.] Although the guidelines talk about LICENSE and NOTICE all the commons projects I checked have a .txt suffix. The commons-build plugin that generates the README.md file even adds links to LICENSE.txt. Looking at other apache projects they show both forms, e.g. LICENSE beam, spark, tomcat LICENSE.txt cassandra, arrow, jackrabbit-oak So I don’t think changing the .txt suffix is required. We are in the same boat as a lot of other projects and at least this is consistent across all of commons. > > Regards, > Gilles > >> >> >> Background >> >> The complex class uses the Math.hypot(double, double) function to determine >> the absolute value of a complex number x + iy as sqrt(x^2 + y^2) without >> over/underflow to 1 ULP precision. This is used directly (in sqrt() and >> abs()) but also without the square root to compute x^2 + y^2 in the log() >> function. These functions also perform over/underflow protection and so >> ideally just require access to the same formula for high precision x^2 + >> y^2. This would enable consistency across the different methods that use the >> absolute of the complex number. Currently the hypot function is very slow in >> the Complex JMH benchmark so I looked into hypot. >> >> This function is known to be slow [1] pre-Java 9 which I was using for >> benchmarking. I found that in Java 9 the code was changed from calling a >> native function to an implementation in Java of the "Freely Distributable >> Maths Library" [2]. The JMH benchmark for complex shows an improvement >> between Java 8 and 9 of about 7-fold speed increase. However this does not >> allow access to the same computation without the square root. The source >> code for fdlibm has a permission license [3] so I have implemented a port >> that allows separation of the x^2 + y^2 computation from the sqrt and the >> overflow protection. >> >> In testing my ported version I found cases where it was more accurate than >> the Java reference, but none where it was less accurate. I attribute this to >> the different implementation of splitting a number into parts for high >> precision that is different in my port from the original. I used the split >> that is already present in Complex. I tested side-by-side an alternative >> that was closer to the method from fdlibm and it was a bit slower (in Java) >> and the same accuracy as the JDK reference. So I assume that the JDK >> reference has stuck exactly to the fdlibm code. I also found my port to be >> 4x faster than the Java reference. This may require more investigation but >> for now I would like to put my port into Complex as an internal method. Note >> the method is different from the commons FastMath.hypot implementation which >> does not compute the result to 1 ULP. I will add this to the JMH benchmark >> for reference so we have Math.hypot, FastMath.hypot and the hypot method >> within Complex. >> >> The licence for fdlibm is shown in [3]. This states that code can be >> copied/modified as long as the original notice is maintained. In commons RNG >> the licence for the port of the MersenneTwister is placed in the Java source >> file and in all LICENSE.txt files through the multi-module project. So >> should I do the same for numbers or just put the license into the complex >> module? >> >> >> [1] >> https://stackoverflow.com/questions/3764978/why-hypot-function-is-so-slow >> <https://stackoverflow.com/questions/3764978/why-hypot-function-is-so-slow >> <https://stackoverflow.com/questions/3764978/why-hypot-function-is-so-slow>> >> >> [2] https://bugs.java.com/bugdatabase/view_bug.do?bug_id=7130085 >> <https://bugs.java.com/bugdatabase/view_bug.do?bug_id=7130085> >> <https://bugs.java.com/bugdatabase/view_bug.do?bug_id=7130085 >> <https://bugs.java.com/bugdatabase/view_bug.do?bug_id=7130085>> >> >> [3] https://www.netlib.org/fdlibm/e_hypot.c >> <https://www.netlib.org/fdlibm/e_hypot.c> >> <https://www.netlib.org/fdlibm/e_hypot.c >> <https://www.netlib.org/fdlibm/e_hypot.c>> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > <mailto:dev-unsubscr...@commons.apache.org> > For additional commands, e-mail: dev-h...@commons.apache.org > <mailto:dev-h...@commons.apache.org>
