Repository: commons-math Updated Branches: refs/heads/master 6df150da2 -> 6ddd71b06 (forced update)
http://git-wip-us.apache.org/repos/asf/commons-math/blob/d14573fe/src/site/xdoc/userguide/index.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml index d874581..81bdd22 100644 --- a/src/site/xdoc/userguide/index.xml +++ b/src/site/xdoc/userguide/index.xml @@ -183,13 +183,6 @@ <li><a href="exceptions.html#a19.4_Features">19.4 Features</a></li> </ul> </li> - <li><a href="rng.html">20. Random Number Generators</a> - <ul> - <li><a href="rng.html#a20.1_Overview">20.1 Overview</a></li> - <li><a href="rng.html#a20.2_Performance">20.2 Performance</a></li> - <li><a href="rng.html#a20.3_Quality">20.3 Quality</a></li> - </ul> - </li> </ul> </section> http://git-wip-us.apache.org/repos/asf/commons-math/blob/d14573fe/src/userguide/README ---------------------------------------------------------------------- diff --git a/src/userguide/README b/src/userguide/README index 7ee72a0..f81bc0f 100644 --- a/src/userguide/README +++ b/src/userguide/README @@ -10,12 +10,12 @@ to the following: Alternatively, a "standalone" JAR can be created with the following command: - $ mvn -Dmainclass=org.apache.commons.math4.userguide.rng.RandomStressTester \ - -Djarbasename=RandomStressTester \ + $ mvn -Dmainclass=org.apache.commons.math4.userguide.rng.ChineseRingsClassifier \ + -Djarbasename=ChineseRingsClassifier \ clean compile assembly:single where the value of the "mainclass" argument is the fully-qualified name of the class whose "main" method will be the program's entry point, and the "jarbasename" argument is the basename of the JAR file to be created. Then, the application can be run with the following command: - $ java -jar RandomStressTester [args] + $ java -jar ChineseRingsClassifier [args] where "[args]" is the list of arguments passed to the "main" method. http://git-wip-us.apache.org/repos/asf/commons-math/blob/d14573fe/src/userguide/c/rng/stdin2testu01.c ---------------------------------------------------------------------- diff --git a/src/userguide/c/rng/stdin2testu01.c b/src/userguide/c/rng/stdin2testu01.c deleted file mode 100644 index d1a4a6a..0000000 --- a/src/userguide/c/rng/stdin2testu01.c +++ /dev/null @@ -1,127 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/* - * Utility for simple interfacing with the "TestU01" library: - * http://simul.iro.umontreal.ca/testu01/tu01.html - * - * It reads from its standard input an infinite sequence of 32-bits - * integers and runs one of the test suites "SmallCrush", "Crush" or - * "BigCrush". - * "TestU01" writes its report to standard output. - */ - -#include <stdint.h> -#include <unistd.h> -#include <string.h> - -#include <testu01/unif01.h> -#include <testu01/bbattery.h> -#include <testu01/util.h> - -#define TU_S "SmallCrush" -#define TU_C "Crush" -#define TU_B "BigCrush" -#define BUFFER_LENGTH 256 - -typedef struct { - unsigned long buffer[BUFFER_LENGTH]; - uint32_t index; -} StdinReader_state; - -unsigned long nextInt(void *par, - void *sta) { - StdinReader_state *state = (StdinReader_state *) sta; - if (state->index >= BUFFER_LENGTH) { - /* Refill. */ - fread(state->buffer, sizeof(unsigned long), BUFFER_LENGTH, stdin); - state->index = 0; - } - - uint32_t random = state->buffer[state->index]; - ++state->index; /* Next request. */ - - return random; -} - -double nextDouble(void *par, - void *sta) { - return nextInt(par, sta) / 4294967296.0; -} - - -static void dummy(void *sta) { - printf("N/A"); - - return; -} - -unif01_Gen *createStdinReader(void) { - unif01_Gen *gen; - StdinReader_state *state; - size_t len; - char name[60]; - - state = util_Malloc(sizeof(StdinReader_state)); - - gen = util_Malloc(sizeof(unif01_Gen)); - gen->state = state; - gen->param = NULL; - gen->Write = dummy; - gen->GetU01 = nextDouble; - gen->GetBits = nextInt; - - strcpy(name, "stdin"); - len = strlen(name); - gen->name = util_Calloc(len + 1, sizeof (char)); - strncpy(gen->name, name, len); - - // Read binary input. - freopen(NULL, "rb", stdin); - state->index = BUFFER_LENGTH; - - return gen; -} - -void deleteStdinReader(unif01_Gen *gen) { - gen->state = util_Free(gen->state); - gen->name = util_Free(gen->name); - util_Free(gen); -} - -int main(int argc, - char **argv) { - unif01_Gen *gen = createStdinReader(); - char *spec = argv[1]; - - if (argc < 2) { - printf("[ERROR] Specify test suite: '%s', '%s' or '%s'\n", TU_S, TU_C, TU_B); - exit(1); - } else if (strcmp(spec, TU_S) == 0) { - bbattery_SmallCrush(gen); - } else if (strcmp(spec, TU_C) == 0) { - bbattery_Crush(gen); - } else if (strcmp(spec, TU_B) == 0) { - bbattery_BigCrush(gen); - } else { - printf("[ERROR] Unknown specification: '%s'\n", spec); - exit(1); - } - - deleteStdinReader(gen); - return 0; -} http://git-wip-us.apache.org/repos/asf/commons-math/blob/d14573fe/src/userguide/java/org/apache/commons/math4/userguide/rng/GeneratorsList.java ---------------------------------------------------------------------- diff --git a/src/userguide/java/org/apache/commons/math4/userguide/rng/GeneratorsList.java b/src/userguide/java/org/apache/commons/math4/userguide/rng/GeneratorsList.java deleted file mode 100644 index 043bce9..0000000 --- a/src/userguide/java/org/apache/commons/math4/userguide/rng/GeneratorsList.java +++ /dev/null @@ -1,57 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.apache.commons.math4.userguide.rng; - -import java.util.List; -import java.util.ArrayList; -import java.util.Iterator; - -import org.apache.commons.math4.rng.UniformRandomProvider; -import org.apache.commons.math4.rng.RandomSource; - -/** - * List of generators. - */ -public class GeneratorsList implements Iterable<UniformRandomProvider> { - /** List. */ - private final List<UniformRandomProvider> list = new ArrayList<>(); - - /** - * Creates list. - */ - public GeneratorsList() { - list.add(RandomSource.create(RandomSource.JDK)); - list.add(RandomSource.create(RandomSource.MT)); - list.add(RandomSource.create(RandomSource.WELL_512_A)); - list.add(RandomSource.create(RandomSource.WELL_1024_A)); - list.add(RandomSource.create(RandomSource.WELL_19937_A)); - list.add(RandomSource.create(RandomSource.WELL_19937_C)); - list.add(RandomSource.create(RandomSource.WELL_44497_A)); - list.add(RandomSource.create(RandomSource.WELL_44497_B)); - list.add(RandomSource.create(RandomSource.ISAAC)); - list.add(RandomSource.create(RandomSource.MT_64)); - list.add(RandomSource.create(RandomSource.SPLIT_MIX_64)); - list.add(RandomSource.create(RandomSource.XOR_SHIFT_1024_S)); - list.add(RandomSource.create(RandomSource.TWO_CMRES)); - } - - /** {@inheritDoc} */ - @Override - public Iterator<UniformRandomProvider> iterator() { - return list.iterator(); - } -} http://git-wip-us.apache.org/repos/asf/commons-math/blob/d14573fe/src/userguide/java/org/apache/commons/math4/userguide/rng/RandomStressTester.java ---------------------------------------------------------------------- diff --git a/src/userguide/java/org/apache/commons/math4/userguide/rng/RandomStressTester.java b/src/userguide/java/org/apache/commons/math4/userguide/rng/RandomStressTester.java deleted file mode 100644 index e257b53..0000000 --- a/src/userguide/java/org/apache/commons/math4/userguide/rng/RandomStressTester.java +++ /dev/null @@ -1,280 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.apache.commons.math4.userguide.rng; - -import java.util.List; -import java.util.ArrayList; -import java.util.Arrays; -import java.io.IOException; -import java.io.File; -import java.io.PrintWriter; -import java.io.FileWriter; -import java.io.DataOutputStream; -import java.util.concurrent.ExecutionException; -import java.util.concurrent.ExecutorService; -import java.util.concurrent.Executors; -import java.util.concurrent.Future; - -import org.apache.commons.math4.rng.UniformRandomProvider; - -/** - * Class that can be used for testing a generator by piping the values - * returned by its {@link UniformRandomProvider#nextInt()} method to a - * program that reads {@code int} values from its standard input and - * writes an analysis report to standard output. - * - * <p> - * The <a href="http://www.phy.duke.edu/~rgb/General/dieharder.php";> - * "dieharder"</a> test suite is such a software. - * <br> - * Example of command line, assuming that "examples.jar" specifies this - * class as the "main" class (see {@link #main(String[]) main} method): - * <pre><code> - * $ java -jar examples.jar \ - * report/dh_ \ - * 4 \ - * org.apache.commons.math4.userguide.rng.GeneratorsList \ - * /usr/bin/dieharder -a -g 200 -Y 1 -k 2 - * </code></pre> - * </p> - */ -public class RandomStressTester { - /** Comment prefix. */ - private static final String C = "# "; - /** New line. */ - private static final String N = "\n"; - /** Command line. */ - private final List<String> cmdLine; - /** Output prefix. */ - private final String fileOutputPrefix; - - /** - * Creates the application. - * - * @param cmd Command line. - * @param outputPrefix Output prefix for file reports. - */ - private RandomStressTester(List<String> cmd, - String outputPrefix) { - final File exec = new File(cmd.get(0)); - if (!exec.exists() || - !exec.canExecute()) { - throw new RuntimeException("Program is not executable: " + exec); - } - - cmdLine = new ArrayList<String>(cmd); - fileOutputPrefix = outputPrefix; - - final File reportDir = new File(fileOutputPrefix).getParentFile(); - if (!reportDir.exists() || - !reportDir.isDirectory() || - !reportDir.canWrite()) { - throw new RuntimeException("Invalid output directory: " + reportDir); - } - } - - /** - * Program's entry point. - * - * @param args Application's arguments. - * The order is as follows: - * <ul> - * <li>Output prefix: Filename prefix where the output of the analysis will - * written to. The appended suffix is the index of the instance within the - * list of generators to be tested.</li> - * <li>Number of threads to use concurrently: One thread will process one of - * the generators to be tested.</li> - * <li>Name of a class that implements {@code Iterable<UniformRandomProvider>} - * (and defines a default constructor): Each generator of the list will be - * tested by one instance of the analyzer program</li> - * <li>Path to the executable: this is the analyzer software that reads 32-bits - * integers from stdin.</li> - * <li>All remaining arguments are passed to the executable.</li> - * </ul> - */ - public static void main(String[] args) throws Exception { - final String output = args[0]; - final int numThreads = Integer.valueOf(args[1]); - - final Iterable<UniformRandomProvider> rngList = createGeneratorsList(args[2]); - - final List<String> cmdLine = new ArrayList<>(); - cmdLine.addAll(Arrays.asList(Arrays.copyOfRange(args, 3, args.length))); - - final RandomStressTester app = new RandomStressTester(cmdLine, output); - app.run(rngList, numThreads); - } - - /** - * Creates the tasks and starts the processes. - * - * @param generators List of generators to be analyzed. - * @param numConcurrentTasks Number of concurrent tasks. - * Twice as many threads will be started: one thread for the RNG and one - * for the analyzer. - */ - private void run(Iterable<UniformRandomProvider> generators, - int numConcurrentTasks) - throws IOException { - // Parallel execution. - final ExecutorService service = Executors.newFixedThreadPool(numConcurrentTasks); - - // Placeholder (output will be "null"). - final List<Future<?>> execOutput = new ArrayList<Future<?>>(); - - // Run tasks. - int count = 0; - for (UniformRandomProvider rng : generators) { - final File output = new File(fileOutputPrefix + (++count)); - final Runnable r = new Task(rng, output); - execOutput.add(service.submit(r)); - } - - // Wait for completion (ignoring return value). - try { - for (Future<?> f : execOutput) { - try { - f.get(); - } catch (ExecutionException e) { - System.err.println(e.getCause().getMessage()); - } - } - } catch (InterruptedException ignored) {} - - // Terminate all threads. - service.shutdown(); - } - - /** - * Creates the list of generators to be tested. - * - * @param name Name of the class that contains the generators to be - * analyzed. - * @return the list of generators. - */ - private static Iterable<UniformRandomProvider> createGeneratorsList(String name) - throws ClassNotFoundException, - InstantiationException, - IllegalAccessException { - return (Iterable<UniformRandomProvider>) Class.forName(name).newInstance(); - } - - /** - * Pipes random numbers to the standard input of an analyzer. - */ - private class Task implements Runnable { - /** Directory for reports of the tester processes. */ - private final File output; - /** RNG to be tested. */ - private final UniformRandomProvider rng; - - /** - * Creates the task. - * - * @param random RNG to be tested. - * @param report Report file. - */ - public Task(UniformRandomProvider random, - File report) { - rng = random; - output = report; - } - - /** {@inheritDoc} */ - @Override - public void run() { - try { - // Write header. - printHeader(output, rng); - - // Start test suite. - final ProcessBuilder builder = new ProcessBuilder(cmdLine); - builder.redirectOutput(ProcessBuilder.Redirect.appendTo(output)); - final Process testingProcess = builder.start(); - final DataOutputStream sink = new DataOutputStream(testingProcess.getOutputStream()); - - final long startTime = System.nanoTime(); - - try { - while (true) { - sink.writeInt(rng.nextInt()); - } - } catch (IOException e) { - // Hopefully getting here when the analyzing software terminates. - } - - final long endTime = System.nanoTime(); - - // Write footer. - printFooter(output, endTime - startTime); - - } catch (IOException e) { - throw new RuntimeException("Failed to start task: " + e.getMessage()); - } - } - } - - /** - * @param output File. - * @param rng Generator being tested. - * @param cmdLine - */ - private void printHeader(File output, - UniformRandomProvider rng) - throws IOException { - final StringBuilder sb = new StringBuilder(); - sb.append(C).append(N); - sb.append(C).append("RNG: ").append(rng.toString()).append(N); - sb.append(C).append(N); - sb.append(C).append("Java: ").append(System.getProperty("java.version")).append(N); - sb.append(C).append("Runtime: ").append(System.getProperty("java.runtime.version", "?")).append(N); - sb.append(C).append("JVM: ").append(System.getProperty("java.vm.name")) - .append(" ").append(System.getProperty("java.vm.version")).append(N); - sb.append(C).append("OS: ").append(System.getProperty("os.name")) - .append(" ").append(System.getProperty("os.version")) - .append(" ").append(System.getProperty("os.arch")).append(N); - sb.append(C).append(N); - - sb.append(C).append("Analyzer: "); - for (String s : cmdLine) { - sb.append(s).append(" "); - } - sb.append(N); - sb.append(C).append(N); - - final PrintWriter w = new PrintWriter(new FileWriter(output, true)); - w.print(sb.toString()); - w.close(); - } - - /** - * @param output File. - * @param nanoTime Duration of the run. - */ - private void printFooter(File output, - long nanoTime) - throws IOException { - final PrintWriter w = new PrintWriter(new FileWriter(output, true)); - w.println(C); - - final double duration = ((double) nanoTime) * 1e-9 / 60; - w.println(C + "Test duration: " + duration + " minutes"); - - w.println(C); - w.close(); - } -}
