Greg,I'm sending this email to help explain Gilles response to your GSoC project and what you should send in response.
Gilles: There is no structure for benchmarks in Commons Math (there are home-made codes used there for "FastMath" (that have shown that "FastMath" is nos always fast...). Here the purpose is to use JMH. [There are examples in "Commons RNG".]
Explanation: In your GSoC project said that you would use commons-math as a guideline to create benchmarks for commons-numbers. Gilles is saying that benchmarks in commons-math is not a good place to start, because those benchmarks don't use a test frame work to run the benchmarks. Your GSoC proposal is to do the work that's documented in the the NUMBERS-70 Jira ticket. That ticket indicates that the JMH test framework (openjdk.java.net/projects/code-tools/jmh) should be used. What Gilles is saying is to use commons-rng as the example starting point for creating the commons-numbers benchmarks. This is because commons-rng has benchmarks which are done in jmh.
I checked out commons-rng. It's a library to generate random numbers, which is a very important thing for encryption. You can find it at commons.apache.org/proper/commons-rng. The link "Source Repository (current)" is an easy rudimentary way to look at the source. commons-rng-examples/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh contains the code which benchmarks commons-math using jmh to run the tests.
Your response: Thanks for your insights on the benchmarks. I'll change my project to use the benchmarks in commons-rng as the template for commons-numbers benchmarks. I found jmh benchmarks in commons-rng/examples-jmh/src/main/java/org/apache/commons/rng/examples/jmh. I'm assuming those are the jmh benchmarks you were talking about.
Your project doc: Update the Background section of your doc to indicate the benchmarks in commons-rng will be used template for the benchmark for commons-numbers. At the end of the doc add a section titled CHANGE LOG. Below that put "04/10 - Changed Background section to say that benchmarks will be based on commons-rng rather than commons-math."
Gilles: I'd suggest "apt" for the documentation format since it is somewhat easier than "xdoc" for tables (as the likely output of the benchmark project). Explanation: "xdoc" and "apt" are different documentation formats for Doxia. See maven.apache.org/doxia/index.html for more info about Doxia. Doxia is a tool for generating web documentation. The way it works is your write documentation in a format that Doxia understands, then run Doxia to process those files to generate web pages to display the documentation. Doxia supports a bunch of different formats, "xdoc" and "apt" are two of them. See maven.apache.org/doxia/referenes/index.html for a complete list of the formats supported. From what I can tell "apt" format is seems simpler and easy to use, while "xdoc" is a richer but more complicated format.
Note that Doxia is part of the Apache Maven project. Maven is tool to build (compile, etc) a project from its source code and dependent libraries. Apache uses Maven to build many of their open source projects. For projects that have documentation in a Doxia format, Maven runs the Doxia tool on the documentation files to generate the finished documentation files that can be viewed via the web.
Your response: I don't really know either the xdoc or apt formats well. Apt seems simpler & easier to use than xdoc. xdoc looks like it has more features but would be harder to use. So using apt seems like it would be easier, as long as it supports all the documentation features that are needed. I was originally thinking the documentation would be in xdoc because the commons-numbers/src/site/xdoc/userguide contain the doc from commons-math and is in xdoc format. I though this was done because people wanted the commons-numbers doc to use xdoc and be similar the commons-math doc. Do you have any good examples of apt doc that I could use as a starting point?
Gilles: Don't hesitate to open JIRA reports for each task that may need interaction on the details.
Explanation: Jira is the issue tracking system used by the Apache organization. It's a very common system and used by many organizations. Ullink uses is for the same thing. Jira tickets/issues are created for new features that need to be added, bugs that need to be fixed, etc. People put in the details of what they are a requesting. Using Jira, people can track the status of the issue, see what's going on with it, what release its fixed in, etc. It's quite common that there is not enough information in the ticket to implement the request. It's common for people to ask questions to clarify the details of things. They can either be asked on the existing ticket, which is NUMBERS-70 in your case, or a new ticket linked to the original ticket.
Your response: Okay. I'm just getting familiar with Jira. I'll start with updating NUMBERS-70 and adding a comment with a link to my GSoC project document. When I need to get details worked out or have questions, how should I do it in Jira? Should I put them as comments on NUMBERS-70? Or should I create a new Jira issue linked to NUMBERS-70 and if so what type, i.e. Task? Gilles: At first sight, script(s) to convert from JMH's output to "apt" would be welcome. Explanation: He's suggesting that a simple program be created which reads the jmh benchmark test output and creates a doc in apt format with the test results. Then those results could be displayed on the commons-numbers web site. A simple program like this would typically be written in a scripting language. Like Borne Shell (which I know), which is the command line language available on most Linux machines. Python is another example of a scripting language, but it is more complicated (I don't know it). Perl is another scripting language (which I know). Typically scripting language programs don't need to be complied. You run them by passing them to the interpreter for the language which parses and executed the commands in your program file. Languages like Java, Haskell, etc. need to be compiled before they can be run.
Your response: I've got experience with Java and Haskell, but don't have much experience with scripting languages. What scripting language would you suggest for something like this, i.e. Bourne Shell, Perl, Python? I'll give it a try. I'd have to keep it really simple. I'd do it after I finish the benchmarks. It would be one of the last things I would do. But I may not have enough time to complete it, if learning the scripting language and writing the script take me a while.
Hi. On Fri, 6 Apr 2018 21:09:56 -0400, Greg Driscoll wrote:Hello all,I'm a computer science student that's really interested in doing a GoogleSummer of Code project working on the commons-numbers User Guide andbenchmarks. In Jira it'shttps://issues.apache.org/jira/browse/NUMBERS-70.Thanks for your interest, and welcome.The link to my proposal is here https://docs.google.com/document/d/1i6yy2cW0x9MYbDOuLPdZrV0XA0eKO5q5N0SNg99mJfA/edit?usp=sharingLooks good. A few remarks: * There is no structure for benchmarks in Commons Math" (there are home-made codes used there for "FastMath" (that have shown that "FastMath is nos always fast...). Here the purpose is to use JMH. [There are examples in "Commons RNG".] * I'd suggest "apt" for the documentation format since it is somewhat easier than "xdoc" for tables (as the likely output of the benchmark project). * Don't hesitate to open JIRA reports for each task that may need interaction on the details * At first sight, script(s) to convert from JMH's output to "apt" would be welcome.Please let me know what you think about it. You can reply to this mailinglist, comment on the doc, or email me directly.Let's keep discussion on this list so that everyone interested can participate. Best, GillesThanks.--------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@xxxxxxxxxxxxxxxxxx For additional commands, e-mail: dev-help@xxxxxxxxxxxxxxxxxx
--------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@xxxxxxxxxxxxxxxxxx For additional commands, e-mail: dev-help@xxxxxxxxxxxxxxxxxx