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.

Tuning Profile:

profile:"Saki"
profile:"Komari"
profile:"R9 7950X (NT)"

Set the tuning profile to be used. The profile names differ by binary.
Refer to "Tuning.txt" or the profile option within the program for the list
of available profiles. Use the exact string as the profile text.

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.

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.

colors:0 Disable console colors.

Colors should be enabled for competitive benchmarking since disabling them

may give an unfair performance advantage for small computations.

Output Log:

logfile:"output.txt"

Log al the console output to the specified file.

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.

Set Console Height: (advanced, 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.

Console: (advanced)

console:winapi Use Windows API. (Windows only. Default for Windows)

console:win-vterm Use Virtual Terminal for Windows. (Windows only.)
console:linux-vterm Use Virtual Terminal for Linux.

This option controls the backend to use for console output. This affects
how colors and cursor movement are handled.

The Virtual Terminal options will use ANSI color codes for setting colors.
The Windows API option will use "SetConsoleTextAttribute()" for colors.
"linux-vterm" can be selected on Windows. It mostly works, but will scramble
up any Unicode text.

This option is intended to be used for integration with wrapper programs.

Users should not need to set this option manually as y-cruncher will
usually pick the correct default.

Status Lines: (advanced)

status:none Do not print the status line until it won't change anymore.
status:overwrite Overwrite the status line when it updates. (default)

y-cruncher shows status lines that are updated in real-time. However, these
updating status lines will screw up the output file if stdout is piped.

This option allows you suppress the updating status lines so that the piped
output is nice and clean.

This option is intended to be used for integration with wrapper programs.

Users should not need to set this option manually as y-cruncher will
usually pick the correct default.
--------------------------------------------------------------------------------

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}]
[-noSMT]
[-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

--------------------------------------------------------------------------------
Benchmark Pi BBP:

{program} bench-bbp {size}

y-cruncher bench-bbp 10b

y-cruncher bench-bbp 100b

The valid values for {size} are: 100m, 1b, 10b, 100b, 1t, 10t, 100t, 1q
The "1q" option is only available for binaries with FMA3 or higher.

--------------------------------------------------------------------------------
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, SFTv4, SNT, SVT, FFTv4, NTT63, N63,
VSTv3, and VT3.

The options N32, N64, HNT, VST and C17 are no longer supported.
(N64 aliases to NTT63 and VST aliases to VSTv3)

BKT - Basecase + Karatsuba + Toom-Cook

BBP - Bailey-Borwein-Plouffe Digit Extraction for Pi
SFTv4 - Small In-Cache FFTv4
SNT - Small In-Cache NTT63/N63
SVT - Small In-Cache VSTv3/VT3
FFTv4 - Fast Fourier Transform (version 4)
NTT63 - Classic 64-bit NTT (version 2)
N63 - (alias of NTT63)
N64 - Formerly Classic 64-bit NTT (v1). Now aliases to N63.
VSTv3 - Vector-Scalable Transform (version 3)
VT3 - (alias of VSTv3)
VST - Formerly Vector-Scalable Transform (version 2). Now aliases to VSTv3.

--------------------------------------------------------------------------------
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.

--------------------------------------------------------------------------------
BBP Digit Extractor for Pi:

{program} bbp {-hex:{hexadecimal offset}}

 [-digits:{digits to compute}]
[-TD:{tasks}]
[-algorithm:{algorithm}]

y-cruncher bbp -hex:10b

y-cruncher bbp -hex:10b -digits:100 -TD:8 -algorithm:bellard

--------------------------------------------------------------------------------
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}]
[-noSMT]
[-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 custom:"Zeta(2) - Direct.cfg" -dec:5000000
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.

Suppress SMT:

-noSMT

Disables the use of SMT. This sets the computation to use no more than one
thread per physical core.

This option will override both the Task Decomposition (-TD) and Parallel
Framework (-PF) options. So it should be specified before either of those.

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 the (-noSMT) option requires that the parallel framework support
core affinity. Only "taskqueue" and "pushpool" support core affinity. Thus
(-noSMT) will only function correctly if the framework is set to one of
those, or omitted - in which it will default to Push Pool.

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.