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


--------------------------------------------------------------------------------
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, SFT, SFTv4, SNT, SVT, FFT, 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
SFT   - Small In-Cache FFT (v2 or v3)
SFTv4 - Small In-Cache FFTv4
SNT   - Small In-Cache NTT63/N63
SVT   - Small In-Cache VSTv3/VT3
FFT   - Fast Fourier Transform (v2 or v3)
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}]
                     [-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.


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.







