y-cruncher Command-Line Manual -------------------------------------------------------------------------------- General Usage: y-cruncher [startup options] [option] [extra parameters] Examples: Run a Pi benchmark 500 million digits and skip any startup warnings: y-cruncher skip-warnings bench 500m Compute log(2) to 100 billion digits using 60GB ram and 4 drives in raid 0: y-cruncher custom log:2 -dec:100b -mode:swap -M:60g -swap:raid0 g:/ h:/ i:/ j:/ Run a configuration file: y-cruncher config config-name.ini y-cruncher config "my saved settings" The command line options described here only cover a subset of y-cruncher's full functionality. Simply put, the program is far too complicated for all of its features to be feasibly expressed with command line options in a usable manner. The only way to access the all the functionality is from the console UI, or with configuration files. Automation can be done through configuration files. -------------------------------------------------------------------------------- Startup Parameters: These parameters are all optional and must be passed before the [option] parameter. Pause at End of Computation: pause:1 Always pause at the end of a computation. pause:0 Default behavior - automatically decide whether to pause. pause:-1 Never pause at the end of a computation. Will pause on errors. pause:-2 Never pause at all, not even on errors. By default, y-cruncher will try to detect if it's run manually, or from the command line. If run manually, it will pause at the end of the computation to prevent the window from automatically closing. Otherwise, it will not pause. Skip Warnings: skip-warnings Skip all the startup warnings so you don't need to press ENTER to continue. Set Console Height: (Windows Only) height:{height in lines} (Examples: "height:60", "height:100") Sets the height of the console window the specified number of lines. This option is used by the HWBOT Submitter to size the window to exactly the expected height of the full output of a computation. This option is currently only supported in Windows. It is ignored in Linux. Priority: priority:{value} Run y-cruncher with the specified priority. The priority values differ between operating systems. Windows: 3 Realtime (Windows automatically downgrades it to "High".) 2 High 1 Above Normal 0 Normal -1 Below Normal (Default) -2 Low Linux: 0 Maximum Priority -1 Minimum Priority (Default) On Linux, privilege elevation may be needed for this option to work. Colors: colors:1 Enable console colors. (Default) colors:0 Disable console colors. Colors should be enabled for competitive benchmarking since disabling them may give an unfair performance advantage for small computations. Personally Identifiable Information: PII:1 Enable PII PII:-1 Disable PII PII:0 Default behavior (disabled) If enabled, it allows y-cruncher to read hardware serial numbers and include them in the validation files that it outputs. Currently, the only PII that y-cruncher can read is the motherboard's serial number. -------------------------------------------------------------------------------- Features: Many features share the same sub-parameters. Refer to the last section in this readme for descriptions on sub-parameters. -------------------------------------------------------------------------------- Run a Configuration File: {program} config {filename}[extension] y-cruncher config my-config.cfg y-cruncher config "file name with space" Run whatever is in the specified configuration file. If no extension is detected, it will automatically append ".cfg". Configuration files follow a JSON-like object format. The contents of the config format vary depending on the action that is being run. There is currently no documentation for the object configs. But y-cruncher can generate them automatically and they can be manually edited. -------------------------------------------------------------------------------- Benchmark Pi: {program} bench {size} [-o {output path}] [-od:{output digits}] [-TD:{tasks}] [-PF:{framework}] [-MA:{allocator}] y-cruncher bench 25m y-cruncher bench 1b -TD:8 y-cruncher bench 1b -TD:1 -PF:none y-cruncher bench 1b -od:0 The valid values for {size} are: 25m, 50m, 100m, 250m, 500m, 1b, 2.5b, 5b, 10b, 25b, 50b, 100b, 250b, 500b, 1t, 2.5t, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G, 2G, 4G, 8G, 16G, 32G, 64G, 128G -------------------------------------------------------------------------------- Component Stress Tester: {program} stress [-M:{memory bytes}] [-D:{per test duration}] [-TL:{test time limit}] [algorithm] y-cruncher stress y-cruncher stress -M:3.5G -D:300 -TL:3600 FFT VT3 Runs a stress test using the specified parameters. Unspecified parameters are left at their defaults. By default, all algorithms are enabled. Specifying any algorithm disables the rest. Multiple algorithms can be specified. -D and -TL are measured in seconds. The valid values for [algorithm] are: BKT, BBP, SFT, SNT, SVT, FFT, N63, and VT3. The options N32, N64, HNT, VST and C17 are no longer supported. (N64 aliases to N63 and VST aliases to VT3) -------------------------------------------------------------------------------- I/O Benchmark: {program} benchio [-M:{memory bytes}] [-TD:{tasks}] [-PF:{framework}] [-MA:{allocator}] [-minIO:{Min I/O Size}] [-swap:{mode} [configuration]] y-cruncher benchio -M:16.5G y-cruncher benchio -M:4g -TD:8 -minIO:512k Runs the I/O benchmark using the specified parameters. Unspecified parameters are left at their defaults. When "-swap" is not specified, it will use a single path at the current working directory. -------------------------------------------------------------------------------- Custom Compute: {program} custom {constant[:param]} [-algorithm:{#}] [-dec:{decimal digits}] [-hex:{hexadecimal digits}] [-o {output path}] [-od:{output digits}] [-C:{compress}] or [-compress:{compress}] [-verify:{0 or 1}] [-mode:{mode}] [-TD:{tasks}] [-PF:{framework}] [-MA:{allocator}] [-M:{memory bytes}] [-minIO:{Min I/O Size}] [-swap:{mode} [configuration]] y-cruncher custom catalan -dec:1000000 y-cruncher custom log:2 -algorithm:1 -dec:100b -hex:0 -o "c:/" -compress:1b -verify:1 -mode:swap -TD:64 -M:120g -minIO:512k -swap:raid0 g:/ h:/ i:/ j:/ Performs a custom computation using the specified parameters. The optional parameters are handled in the order they are specified as if they were manually entered into the Custom Compute menu UI. Automatic parameter correction and restrictions are done identically as in the UI. Therefore it is recommended to specify the parameters in the order they are listed above since that is the direction of the auto-correction dependencies. Parameter: {constant:[param]} Examples: pi, log:3, sqrt:3, custom:"filename" Valid Values: sqrt, phi, goldenratio, e, pi, log, lemniscate, apery, zeta(3), catalan, gamma, brent, custom -------------------- Parameter: [-algorithm:{#}] Examples: -algorithm:0, -algorithm:1 "#" specifies the algorithm number to use. The number corresponds to the same numbers shown from within the UI. 0 is the default algorithm. The number of algorithms varies with each constant. -------------------- Parameter: [-dec:{decimal digits}] [-hex:{hexadecimal digits}] Examples: -dec:1000000 -hex:0, -dec:100m Sets the number of digits to compute. "-dec" and "-hex" inherently override each other. The only time it is meaningful to use both is "-dec:X -hex:0" which will compute X decimal digits and disables the hexadecimal digits. Suffixes are accepted: 500k, 100m, 10b, 2t Suffixes are not case sensitive. -------------------- Parameter: [-C:{compress}] or [-compress:{compress}] Examples: -compress:0, -compress:-1, -compress:1000000000 -compress:100m Compress the digits using the specified number of digits per file. If the # is zero, compression is disabled and the output will be text files. If the # is -1, the output will be compressed into a single file. Suffixes are accepted: 500k, 100m, 10b, 2t Suffixes are not case sensitive. -------------------- Parameter: [-verify:0] or [-verify:1] Examples: -verify:0, -verify:1 "-verify:1" enables verification of the base conversion and output digits. "-verify:0" disables these verifications. Enabling verification is mandatory when claiming a new world record size computation. -------------------- Parameter: [-mode:{mode}] Examples: -mode:ram, -mode:swap Pretty self-explanatory. Those are the only two valid options. -------------------- The options, "-M", "-minIO", and "-swap" are only valid in swap mode. -------------------------------------------------------------------------------- Common Sub-Parameters: These parameters are used by multiple components in y-cruncher. Output Path: -o {output path} (Examples: -o c:/digits, -o "c:/path with space") Output to the specified path. This applies to both the digits and the validation/stats file. Digit Output: -od:{output digits} -od:0 disables output of digits -od:1 enables output of digits (default) Use this to suppress digits if you're only benchmarking and you don't want the digit output. Task Decomposition: -TD:{tasks} (Examples: "-TD:8", "-TD:12") Run the operation using the desired level of task decomposition. A larger number enables more parallelism, but at the cost of more computational and memory overhead. For most systems, setting this equal to the number of logical cores is ideal. But forcing it higher may reduce load-imbalance. Note that setting this value to 1 does not disable multi-threading since some subroutines ignore the parameter and will decompose anyway. To get a correct single-threaded benchmark, you need to also set the parallel framework to "none". Disable Multi-threading: -TD:1 -PF:none Parallel Framework: -PF:{framework} (Examples: "-PF:none", "-PF:cppasync") Use the specified parallel computing framework. The valid values are: -PF:none Disable multi-threading and sequentialize all tasks. -PF:spawn Spawn a thread for every task. -PF:cppasync Use C++11 Async. -PF:taskqueue Use y-cruncher's custom task queue. -PF:pushpool Use y-cruncher's custom decentralized thread pool. -PF:winpool Use the Windows Thread Pool. (only available on Windows) -PF:cilk Use Cilk Plus work-stealing. (not available everywhere) -PF:tbb Use Thread Building Blocks (TBB). (not available everywhere) Note that there is no way to set framework-specific settings via the command line. So they will be left at their default values. You can only set them from within y-cruncher's console UI or with config files. Memory: -M:{memory bytes} (Examples: "-M:100000000", "-M:4.7g") Run the operation using the specified amount of memory. Decimals and suffixes are accepted: 4.7g, 9.1t Suffixes are not case sensitive. Memory Allocator: -MA:{allocator} (Examples: "-MA:mmap", "-MA:interleave") Use the specified parallel computing framework. The valid values are: -MA:malloc Use the C malloc() allocator. -MA:mmap Use memory mapping. ("VirtualAlloc()" on Windows, "mmap()" on Linux) -MA:interleave Interleave NUMA nodes. -MA:interleave-libnuma Interleave NUMA nodes using the libnuma library. (only available with the dynamically-linked Linux binaries) Note that there is currently no way to set allocator-specific settings via the command line. So they will be left at their default values. You can only set them from within y-cruncher's console UI or with config files. Min I/O Bytes (Bytes per Seek): -minIO:{Min I/O Size} (Examples: "-minIO:1048576", "-minIO:4m") Run the operation using the specified amount Min I/O parameter. Decimals and suffixes are accepted: 512k, 1.5m Suffixes are not case sensitive. Note: The behavior of this option has changed from v0.7.2 to v0.7.3. In v0.7.2 and earlier, this option set the "physical Min I/O" which is then automatically adjusted based on the swap mode configuration to compute the "logical Min I/O". In v0.7.3, the concept of "physical Min I/O" has been removed. This option will now set the "logical Min I/O" instead. It will not be automatically adjusted as it was before. Swap Mode Configuration: -swap:default -swap:ram -swap:raid0 [path0] [path1] [path2] [etc...] -swap:default -swap:ram -swap:raid0 c:/ d:/ e:/ f:/ "path with space" If this option is used, it must be the last option. All arguments after it will be parsed as paths. Note that the "Swap Configuration" feature no longer exists in y-cruncher. It has been replaced with a selectable set of "Far-Memory" frameworks. Therefore, this feature is out-of-date. But for the sake of backwards compatibility, it will remain for now and will map to some reasonable far-memory configuration that most closely imitates the original behavior. As with the parallel frameworks and memory allocators, there is no way to set sub-options from the command line. This feature is far too complicated for command line use. Therefore, you can only set them from within y-cruncher's console UI or with config files.